Jeden/Docs

Controlled execution

Controlled tools, accountable effects.

A small allowlisted registry enforces path jails and write or command permission. Tool schemas are derived from each input contract and sent with the model request; every result is recorded in the session and returned to the model until it produces a final answer.

The tool registry#

The current scope ships jailed filesystem, document, archive, image, SQLite, search, Git, process, evaluation, URL, artifact, memory, todo, delegation, and MCP tools. File mutations return Jeden-native visual diffs and previews; oversized tool results are persisted as session artifacts and replaced in the model loop with a compact reference.

Every tool path is taken from the workspace root. A relative path resolves under it, an absolute path inside it resolves to the same file, and an absolute path outside it is refused with the root the path is taken from — so a refusal never leaves a caller guessing a relative form and inventing a directory that satisfies nothing. Each refusal is a cause of jeden.tools.input (jeden errors show jeden.tools.input) and leaves nothing read or changed: path-outside (an absolute path outside the workspace), path-climbs (a .. component, named), path-linked (a symbolic link on the way, with where it points; ls -l shows it), path-unexaminable (a component the file system will not let Jeden examine, with its answer), input-missing (a field the tool takes as text that the call left out or sent of another shape, with what it sent) and count-invalid.

Every amount a tool works to is the caller's. list_dir, search_files, glob_paths, grep_regex, git_log, ast_search, rows read by read_sqlite, and memory list and recall take limit, how many entries to answer; fetch_url, fetch_readable_url, read_binary_file, read_image, read_document, read_artifact and an entry read by read_archive take maxBytes, how many bytes to keep; memory context takes query and maxChars; lsp takes line and character (zero-based, as the protocol counts them) where an action needs a position, diagnostics for code actions, and tabSize and insertSpaces for formatting. A missing or non-positive amount is jeden.tools.input.count-invalid (<tool> takes <key>, a whole number above zero the caller states, and the call does not, with what it sent), and no tool supplies a default or caps the amount it was given. read_file answers the whole file or the lines its selector names; search_text answers every matching line of its one file; searches read every text file they reach on as many threads as the machine runs, and refuse by name when that count cannot be read.

The read tools refuse with the causes of jeden.tools.read, each naming the tool and the path: selector-invalid (a selector is raw, conflicts, or lines N, N-M, N- or N+COUNT counted from 1, and the refusal says which part is not: a line 0, a range ending before it starts, a count of none), read before the file is; path-absent (with the nearest directory on its way that exists); not-a-file (a directory, with how many entries it holds) and, for list_dir, not-a-directory (a file, with its size); file-unopenable (with the file's mode); file-unreadable (with how many bytes were read); not-text (the first line that is not UTF-8, the file's size and type; read it with read_binary_file); image-unsupported (read_image reads PNG, GIF, WebP and JPEG); directory-unlistable; mcp-uri-invalid; and cancelled, naming the line or entry it stopped at.

The memory tool states nothing for its caller either. Every call names its op (remember, list, recall, context, forget or stats); recall takes the query it recalls for; remember takes text, kind (what the note is) and confidence, how sure the note is from 0 to 1 as the store keeps it. A missing one is refused naming it, where the tool used to recall without an op, file every note as a note and give it a certainty of one half. tags must be a list of text and source a memory source; either is refused with its cause otherwise, and a note given no source is recorded as written by the memory tool. scope is a kind name or an object with kind and id; none, or repo, is the repository the session runs in, and any other shape is refused naming it instead of read as the repository.

ast_search reports truncated: true only when another selected capture actually exists beyond the caller's limit. A result with exactly that many matches and no further match is complete. ast_rewrite previews every selected capture without a search-result limit, refuses overlapping captures, and applies only against the unchanged source digest.

If the parser reports that its in-progress query capacity was exceeded, both AST tools refuse the incomplete capture set and name the observed parser capacity. Such a refusal creates no rewrite preview or pending mutation; it is not a successful truncated search.

search_files and grep_regex answer unreadable: every listed file that exists and could not be read, as path: cause, so a file the search could not open is never mistaken for one without a match. A file gone since listing, or one that is not text, is not searched and not listed there.

Delegated tasks (task, job, /tan) run under limits the operator declares as one setting, jeden config set taskScheduler '{"maxParallel":…,"maxBatch":…,"maxDepth":…,"maxChildren":…,"maxOutputBytes":…}', or in Jeden Desktop under Settings → Delegated tasks (both reach RPC config/task-limits/set); every field is required, and a zero count other than maxDepth is refused before anything is written. Without the declaration delegation is refused with taskScheduler is not declared: …, and the task tools and the Settings section report that sentence. A delegated agent's inbox keeps each message until that agent reads it, and a message read leaves the inbox; there is no inbox size or message length limit.

A task no task spawned sits at depth 0, and each delegated task one level deeper than the task that spawned it; a spawn deeper than maxDepth is refused. A task process the scheduler starts is told its depth in JEDEN_TASK_DEPTH; one that is set but is not a whole number is refused with JEDEN_TASK_DEPTH is <value>, which is not a task depth: <cause>, never read as the top. A task process is also told its job in JEDEN_TASK_JOB, which becomes the parent of what it spawns; a value that is not Unicode is refused with JEDEN_TASK_JOB is <value>, which is not Unicode, so the parent job cannot be named, never read as no parent. A parent job whose agent no loaded definition declares spawns nothing: the parent job <id> runs agent <agent>, which no loaded agent definition declares. The task tool's wait is true or false, absent meaning do not wait; any other value is refused with task wait is true or false; got <value>. A delegated child's stdout and stderr are kept up to maxOutputBytes each; a longer one ends with [cut at maxOutputBytes <max> of the <size> bytes in <file>]. Each running task holds one of maxParallel admission slots. A slot is published whole, its holder's process id and job id written before it is linked into place, so a slot another task is still writing is never taken for free; a slot whose holder is no process id is refused as damaged, naming the slot and its text, instead of being freed.

The harness ships an explicit tool policy for the model:

  • discover files with glob_paths or list_dir before reading unknown paths;
  • search content with grep_regex or search_files rather than shell discovery commands;
  • use targeted read_file selectors instead of dumping large files;
  • use run_package_script for declared package scripts and reserve general process tools for commands without a safer built-in;
  • verify behavior changes with the narrowest relevant check.

Persistent interpreter failures#

A terminal's readiness wait checks its own operation cancellation and session state when woken. An unrelated operation's cancellation wake does not abort a live startup; cancelling this startup refuses it as PTY startup cancelled before shell readiness. Native terminal cleanup reports a failed kill with its actual cause and a nonblocking observation of whether the child has exited or its status is unreadable; it does not then wait for the process that kill failed to stop.

Before reusing or resizing a persistent terminal, a failed process-status read refuses the operation as PTY session '<id>' status could not be read: <cause>. The shell stays registered with its existing identity and variables; an unreadable status does not mean the shell ended and does not silently create a replacement. Terminal identities are opaque UUID-bearing values, distinct across shell starts rather than counters that restart with the program.

A terminal starts with the VT100's standard 80-column, 24-line screen. Resize accepts positive dimensions representable by the native unsigned-short window-size fields, rather than an additional application cap; the native resize operation may still refuse a size and returns its actual system cause. The tool schema and invalid-dimensions diagnostic expose those same representation bounds.

Commands serialize within their scope, not across all terminals. Waiting for another command remains cancellable before any input is written. Blocking command-output reads hold neither the registry nor the native control lock, so another scope can execute and an established terminal can resize while output is pending. Scope teardown closes queued leases, stops and wakes the active shell even during its startup handshake, and prevents an older lease from registering into a later scope generation. Cancellation retains output already received, including bytes held back while matching a completion marker. Terminal-state diagnostics retain the first ended or cancelled transition.

The Unix native-PTY journey source is tests/terminal/lifecycle.rs, registered through the approved-test workflow before execution. Select real_terminal_scopes_resize_cancel_and_teardown explicitly with --ignored after target approval; the normal suite does not execute this dependency-bearing journey. It requires JEDEN_TEST_SOURCE_REVISION to match a clean candidate and its compiled identity, uses actual shells and FIFO barriers without polling or guessed deadlines, and retains API inputs, outputs, persisted effects, revision and binary hashes under .build/terminal. It covers scope isolation during a blocked command, cancelling a contending call without executing its input, native stty size after resize, an invalid-dimensions refusal, teardown and a fresh shell generation. This is native API coverage, not graphical qualification.

Persistent Python and JavaScript evaluations require their interpreter's framed completion response. Closing protocol stdout while the interpreter process still runs refuses the evaluation as <language> kernel closed protocol stdout before completing the evaluation: process <pid> still runs, with <bytes> unfinished frame bytes. Closing the stream is not completion, and Jeden does not wait for an unrelated process exit to decide it.

An interpreter that exits before completion reports its exit status and captured standard error. A status read failure is returned with its cause and the removed kernel is stopped rather than forgotten. Failed kill diagnostics retain the failed operation, its cause, and a nonblocking observation of whether the child has exited or its status is unreadable; cleanup does not wait after that failed kill. The same tool refusal is recorded for command-line, RPC and graphical conversations; no successful evaluation is synthesized.

Interpreter evaluations use the same cancellable exclusive leases as terminals, keyed by scope, working directory and language. A blocked Python evaluation does not hold the registry against another scope or JavaScript kernel. Teardown closes queued leases and controls the active native child independently of its input and output pipes; an older lease cannot republish into a later generation. Cancellation is checked before code is written and while native stderr is drained, so a continuous stderr producer cannot keep cancellation outside that loop. Launch retains native child ownership through process-tree attachment and pipe setup, so a partial launch failure stops its child and reports any cleanup failure rather than abandoning it.

The Unix native interpreter journey source is tests/interpreter/lifecycle.rs. After approved target registration, explicitly select real_interpreters_isolate_cancel_and_teardown with --ignored, using a clean declared JEDEN_TEST_SOURCE_REVISION, real Python and Node, and an enforced platform sandbox. It runs blocked evaluations, independent scopes and languages, pending cancellation, active context cancellation under native stderr pressure, and fresh-generation state checks. Python persists its actual PIDs and checks their absence after teardown and context cancellation. Commands, API results, source and binary identity remain under .build/interpreter; the same source attestation helper serves the terminal journey. Neither journey constitutes graphical qualification.

Every interpreter frame must name its evaluation with a string id. A frame without that identity is refused as kernel protocol frame has no string evaluation id: <frame>, not discarded while the evaluation waits. Frames naming another evaluation remain distinguishable from a malformed unidentified frame.

Reading images#

read_image reads a PNG, JPEG, GIF or WebP inside the workspace and supplies its pixels to the next model request as an image, not as encoded text. The model must support image input. No separate OCR process, command grant or write grant is required.

The same transport handles image results in a batch and preserves supporting text and input attachments. Image metadata stays in the text result; the original tool receipt retains the encoded bytes. Only the provider-bound copy gains image parts, so recorded conversation messages remain text-valued.

The reader reads the maxBytes the caller states. A result cut short of the whole image is refused before the model request and identifies the incomplete image; state a maxBytes that covers the file, since a partial PNG is not a readable image.

Inspect an image within a read-only workspace
jeden run "Use read_image on screenshot.png and describe the visible headings" --cwd ./screenshots --json

Approvals and grants#

Every file write or shell command pauses for interactive approval unless explicitly enabled, and destructive confirmations default to Cancel. In one-shot mode, grants are explicit per invocation. Project hooks in .jeden/hooks.json run only with --allow-command, so a cloned repository cannot silently execute shell.

Only a hooks file that does not exist declares no hooks. A ~/.jeden/hooks.json, a trusted .jeden/hooks.json, an enabled plugin's hooks.json or the Tama registry that cannot be read or is not JSON refuses every event it would have guarded, with the file and the filesystem or JSON-decoding cause, instead of being read as an empty config that turns its guards off; /hooks lists it as unreadable with the same cause.

One-shot grants
jeden run "summarize package.json"
jeden run "create notes.txt" --allow-write
jeden run "inspect the build" --allow-command

Guarded mutations#

File mutations are guarded: edits use the digest or snapshot tag returned by read_file, and snapshot-tagged edits reject stale state instead of overwriting it.

No tool may change <cwd>/.jeden/. That directory holds the workspace's own Jeden state — the session pointer, mode state, the usage ledger and the retained completion state — so a write there rewrites the record the work is judged by. The refusal names the path and says to write the work where the request asks for it; reading the directory stays allowed. Every mutating tool is also authorized as a write, so write, write_archive, write_sqlite and ast_rewrite can be approved in a live session rather than only refused.

edit_file takes ops, each one of replace, delete, insert_before or insert_after with a 1-based start; replace and delete also state end, the last line they cover, and one without it is refused as edit op "replace" needs end (or endLine): the last line it covers rather than read as one line. An undeclared op is refused naming every op. The anchored edit tool resolves its SWAP, DEL and INS hunks to these same edits, and write_archive (upsert, delete) and write_sqlite (insert, update, delete) refuse an action outside their own list by naming it.

Network access#

Jeden initiates every connection. The terminal, jeden run, jeden rpc, and jeden acp are stdio-only and open no socket; listening sockets exist only in the opt-in headless and relay listeners and the local stats dashboard, which binds loopback.

Model inference uses the explicit JEDEN_MODEL_ENDPOINT directly, with JEDEN_MODEL_KEY or Jeden's optional token list, or Stado's inference alternatives (stado capabilities call inference --consumer jeden); Brama's own API and Weles are reached at the route stado capabilities resolve FAMILY --consumer jeden names (see Other products). Durable memory, pursuit state and relay rooms use JEDEN_DATABASE_URL directly, with JEDEN_DATABASE_CA_FILE for a server. Neither path reads Skarbiec. Other configured integrations and tool-initiated network access retain their own grants and host/port allowlists.

For Brama and Weles control-plane requests, an unreadable non-Unicode bearer is a credential-configuration refusal naming the variable before HTTP dispatch, not a process panic or an anonymous request. A configured address or an available process alone does not prove its credential works; the catalog, readiness or operation response supplies that evidence.

A browser bridge request refusal retains the CDP URL and the original network, HTTP or JSON-decoding cause. Startup asks for a debugging port the system chooses and waits for Chromium's DevTools listening on announcement on stderr; the address it announces is recorded in the session's state as its CDP endpoint, and the returned webSocketDebuggerUrl is verified. A recorded endpoint that no longer answers starts a new browser, and when no Chromium is configured the refusal says why the recorded one could not be used. A browser that exits first is refused with its exit code or signal and everything it wrote to stderr. A browser process alone is not a successful connection. Once the CDP socket closes, every outstanding call and event wait fails with that closure, and a later call or wait is refused at once instead of waiting on the dead socket. The same tool error reaches command-line, RPC and graphical callers.

Browser actions take what they act on from the caller and refuse by name what is missing: navigate its url; click a selector or x and y; type a selector and one of text or value; press its key; evaluate one of expression or code; wait a selector; scroll the pixels along x, y or both; snapshot the number of controls (limit) and the characters of each text (maxChars); screenshot its format (png, jpeg or webp, with an optional quality). A tab is named as tab; with none named the session's current tab, else its first, is used.

A CDP socket that closes before the handshake opens also ends the connection request. Closure diagnostics retain the actual socket URL, protocol close code, reason and clean-close flag; connection errors retain the observed error event. Pending calls and event waits receive the same closure cause instead of waiting for a connection that can no longer open.

Only an absent browser state file starts an empty session. An unreadable or malformed state file refuses the operation with its path and actual filesystem or JSON-decoding cause; it is not silently replaced with an empty session that forgets browser ownership or the selected tab.

Browser startup owns its child until state persistence, readiness and CDP verification succeed. A failure in that scope stops the newly spawned process group and waits for its exit before returning the original operation error and stderr; a failed stop names the process group and its own cause. Reading existing session state happens before spawning, so a denied or corrupt state read does not start a new browser.

Every bridge answer, a refused action included, names the browser process the call found or started (browserPid), so the browser service keeps ownership of a browser even when a later navigation, click or tab action of it fails, and stops it when the service ends. The bridge routes by the tool the service names: browser_tab takes list, open, focus or close, and any other verb is refused with that list; a request with no action is refused before any browser is started. Page snapshots list the elements the browser itself reports as rendered and visible (Element.checkVisibility) with a nonempty box.

The browser opens a window only when /browser visible stored mode visible (browser.mode in the project config, or JEDEN_BROWSER_MODE); with no stored mode it runs headless, and /browser status says headless (no mode stored). Any other stored value is shown as it is and makes the browser service unavailable with the value read and the command that sets it, instead of running headless without a word. A bridge answer {"ok": false} that carries no error string is a protocol refusal naming the whole answer. So is a browser_screenshot answer that names no image format or no tab: the artifact is filed under the type the bridge captured, never typed png by assumption.

jeden relay serve reads requests with an HTTP server library and bounds each body by the size its operator states in JEDEN_RELAY_MAX_BLOB_BYTES: a declared body larger than it is answered 413, and a request that declares no length is answered 411, before any of it is read. A request that fails while it is read is written to the relay's standard error with the peer and the cause.

Custom tools, MCP, and hooks#

Custom JavaScript tools load from ~/.jeden/tools/ and <cwd>/.jeden/tools/. A custom module exports a default factory that receives the current workspace helpers and returns one tool or a list of tools; tool names must be unique and cannot collide with built-ins. Custom execution remains subject to the same jail, approval, and hook policy as built-in tools.

MCP servers load from ~/.jeden/mcp.json and <cwd>/.jeden/mcp.json using the standard mcpServers shape. Generic MCP tools list and call server tools, resources, and prompts; configured server tools may also appear under native mcp__<server>__<tool> names. The slash commands that edit a JSON file (/mcp add|remove|enable|disable, /ssh add|remove, /browser, /model, /rename, /collab, /usage reset, the plugin registry) and the agent's usage ledger read and write it through jeden.state.file (jeden errors show jeden.state.file, tested by tests/state/file.mjs): file-unreadable, file-not-json, directory-uncreatable and file-unwritable, each exit 1 naming the path and what the system or the decoder answered, and the file is left as it is.

Reading is as strict as writing. An mcp.json or .jeden/plugins.json that exists but cannot be read or is not JSON is never read as empty: MCP tool calls, /mcp list, /mcp reload, /marketplace and /plugins answer with its jeden.state.file refusal (&lt;path&gt; cannot be read: … or &lt;path&gt; is not valid JSON, so nothing it holds can be read or kept by a rewrite), and the /mcp, /marketplace, /extensions and /usage views show the same refusal as one disabled error row. Read as empty, a typo in mcp.json made every server it declares, and every server it disables, vanish without a word. A file that does not exist, or one under a path whose parent is no directory, is simply empty. /usage is jeden.usage: a verb other than show, status or reset (verb-unknown) or a word after it (argument-unexpected) exits 2, and a ledger whose events are not the writer's shape is jeden.usage.ledger.ledger-malformed (tests/usage/ledger.mjs).

A stdio server starts with Jeden's own HOME and PATH and no other variable of Jeden's environment, so a server finds its home and the programs it runs by name without its entry spelling them. The server's env object, applied after, sets or replaces any variable, and a null value removes one, HOME and PATH included.

/mcp is jeden.mcp.command (tests/mcp/command.mjs): its verb and words are read whole before any file, each exit 2: verb-unknown, server-missing, name-invalid (a name of letters, digits, _, - and .), transport-missing, url-invalid, sse-unsupported, command-missing and argument-unexpected. --scope user|project is read only before the server's name, so a server's own arguments are never taken for it; a --scope without a scope or with another one is jeden.scope.scope-missing or scope-invalid (also for /plugins and /marketplace). Removing a server the scope does not declare is server-not-declared and writes nothing. What each mcp.json declares is read through jeden.mcp.config (tests/mcp/declarations.mjs): root-not-object, servers-not-object, server-not-object, enabled-not-boolean, disabled-not-list and disabled-not-name, each naming the file and the field; asking for a server is jeden.mcp.server: server-unknown names the declared servers and server-disabled names /mcp enable.

/ssh is jeden.ssh (tests/ssh/hosts.mjs): hosts are listed from every configuration layer and added to or removed from &lt;cwd&gt;/.jeden/config.json only. verb-unknown, argument-unexpected and option-invalid (an option that is no key=value) exit 2; hosts-not-object (an sshHosts of another shape, left as it is), host-elsewhere (a host another layer declares) and host-unknown exit 1. A state file whose root is no object is jeden.state.file.root-not-object, naming what it keeps (the mode state, the collaboration state, the plugin registry).

Extension discovery is held to the same rule. A plugin, configured or native extension root whose package.json exists but cannot be read or is not JSON, that declares in jeden.extensions (or pi.extensions) an entry which is not a module file, or a directory that cannot be listed, refuses extension loading with &lt;path&gt; cannot be read: &lt;cause&gt;, &lt;path&gt; is not JSON: &lt;cause&gt;, &lt;manifest&gt; declares the extension &lt;entry&gt;, which is not a module file or cannot list the extensions in &lt;root&gt;: &lt;cause&gt;; /extensions answers the same sentence, and the /extensions view shows it as one disabled error row in place of that root's modules. Skipped, every extension the package declared silently did not load. A root that does not exist holds no extensions.

What extensions declare is read under the same rule. When the extension registry cannot be read, the model catalog and the provider list refuse with the extension registry cannot be read: &lt;cause&gt; instead of answering without the models and providers extensions declare. An extension hook whose tool matcher is not a regular expression refuses its event with the &lt;event&gt; hook #&lt;n&gt; of &lt;source&gt; has a tool matcher that is no regular expression (&lt;matcher&gt;): &lt;cause&gt; instead of never matching, and a host reply to a hook without its result is refused naming the hook.

Installed plugins are read under it too. When a scope's package registry (.jeden/plugins/v2) cannot be read, /plugins list, /marketplace installed and /marketplace upgrade refuse with the installed plugins of &lt;scope dir&gt; cannot be read: &lt;cause&gt;; the /plugins picker shows that sentence as one disabled error row; custom command discovery answers it (the capability list shows File commands unavailable with the cause); and the plugin hook configs of that scope are reported as a failed hook config instead of none. Read as no plugins, the commands and hooks of every installed plugin vanished without a word. --scope without a value is refused (--scope takes user or project), and a catalogue that names a plugin without a name, or a marketplace catalog naming neither catalog.catalogId nor name, is refused naming it. /plugins enable|disable refuses an installed record that is not an object instead of replacing it with an empty one. It toggles a package the marketplace installed in that scope too, keeping the toggle in the scope's .jeden/plugins.json; a disabled package stays installed but its commands and hooks are not loaded, and /plugins list shows it disabled. A plugin installed in neither registry of the scope is refused with Installed plugin not found in &lt;scope&gt; scope: &lt;name@marketplace&gt;.

Marketplace installation preserves its transaction directory when rollback cannot restore every package, and the refusal names each failed step and the retained backup location. A later installation never deletes a pre-existing transaction to reuse its path: it refuses with that path and the filesystem cause, leaving retained recovery data untouched.

The Marketplace picker also refuses an unreadable catalogue with the source name and the catalogue reader's cause. It never substitutes an older plugin list stored in the registry for a catalogue that failed to load, so stale entries cannot appear as a freshly verified installation choice.

Catalogue discovery checks the next supported catalogue path only when the preceding file is absent. A directory, permission failure or malformed file at the preferred path is a named refusal with its read or parsing cause, not permission to load a different catalogue.

If any marketplace source fails to fetch or read during discovery, the command returns a refusal containing every source error and any entries already read successfully. It does not report an empty or successful inventory while a source remains unreadable.

The real CLI catalogue regression is node tests/marketplace/catalogue.mjs. Set JEDEN_BIN to the candidate CLI, JEDEN_TEST_SOURCE_REVISION to its clean committed revision and JEDEN_TEST_MARKETPLACE_CATALOGUE to a genuine catalogue containing named plugins. It uses isolated copies to check preferred/alternate discovery, malformed-file and directory refusals, unchanged declarations and recovery, retaining commands, exit statuses, source and binary identity, fixture hashes and a report under .build/marketplace-catalogue. It does not install plugins or qualify the graphical picker.

/marketplace add &lt;source&gt; keys the marketplace by the name its catalogue declares (catalog.catalogId, else name), never by the last segment of the source path: the registry entry and the cache directory under .jeden/plugins/cache/marketplaces both carry the catalogue's name, and a catalogue that names neither is refused with Marketplace catalog at '&lt;source&gt;' names neither catalog.catalogId nor name. and registers nothing. The real CLI regression is node tests/marketplace/add.mjs with JEDEN_BIN and JEDEN_TEST_SOURCE_REVISION set as above; its source folder is named differently from the catalogue on purpose, so keying by the path would fail it, and it retains every command and a report under .build/marketplace-add.

Language tools start the configured language server in the workspace and keep what it prints on stderr in .jeden/lsp/&lt;server&gt;.stderr.log. A server that cannot start is refused as cannot start LSP server &lt;program&gt;: &lt;cause&gt;; one that stops answering is refused as LSP server &lt;program&gt; stopped answering: &lt;transport cause&gt; (&lt;exit status&gt;); its stderr is kept in &lt;log&gt;, so a crashed or misconfigured server says why instead of LSP reader stopped.

The service tools (browser, debugger, GitHub and git, SSH, media, web search) refuse as their declared functionalities, each refusal the tool's result the model reads with fix: and cause: lines: jeden.tools.service for what they share (an input field missing, a cancelled turn, the program a service runs that cannot start, ends unsuccessfully or prints no JSON, an artifact that cannot be kept), jeden.media (tests/media/generate.mjs), jeden.browser, jeden.github, jeden.debugger, jeden.ssh.tools and jeden.web (tests/tools/*.mjs). jeden errors show &lt;functionality&gt; prints every cause with its test. A tool kept unavailable says why in its health (jeden capabilities --json): a bridge, adapter, Chromium, Node.js, gh, git or ssh that is not there, or a browser mode or adapter arguments the configuration holds wrongly.

A tool that starts a program runs it under the turn's execution grant, jeden.runtime.grant (tests/runtime/grant.mjs): the grant runs every program, reads and writes under the workspace, hands a program only PATH, LANG, LC_ALL, TERM and TMPDIR (environment-denied names the variable a run_process env asked for), names no network host (host-not-granted: the SSH tools refuse every alias with it, naming the address ssh -G resolved, the grant's hosts and a context: line with the alias), lasts as long as the Jeden process holding it (a grant a client hands with an expiresAt is refused past it as expired), and gives a program the resource limits Jeden itself runs under, as getrlimit reports them, never a number of its own. Terminal sessions, kernels, MCP calls, the extension host and delegated tasks are untrusted children: they run only inside an enforced platform sandbox, and sandbox-unenforced names the step, the sandbox backend and what jeden doctor reports about it (a jeden-sandbox-helper that is missing, unsigned or did not enforce its probe; JEDEN_TASK_SANDBOX_HELPER names another).

The program itself is started by jeden.runtime.process (tests/runtime/process.mjs), each refusal naming the command line, its directory and its process id once it had one: program-unstarted (the system's answer, such as no such file), stdin-unwritten (a command that ended without reading the input it was given, with its exit status), and the causes of resource limits, process groups, signals after a cancelled turn and descendants left running (with the kill that ends them). Its output is kept by jeden.runtime.capture (tests/tools/sessions/capture.mjs): past the grant's file limit (the file-size limit Jeden runs under) it is refused as limit-exceeded with what was kept, and a body fetch_url keeps whole is refused as artifact-uncreatable when the session's artifacts directory cannot be made, naming the path and the system's answer.

eval_session, node_eval and python_eval keep one python3 or node kernel per session scope, language and directory, jeden.runtime.kernel (tests/runtime/kernel.mjs), each refusal naming the language and the kernel's process id: kernel-exited (code that ended its interpreter, with its exit status and standard error), protocol-closed (code that closed file descriptor 1 while it runs), frame-not-json, frame-unnamed and frame-invalid (code that wrote into the standard output the kernel answers on, quoting the line or frame), after each of which the kernel is ended and the next call starts a new one; the probe jeden doctor and jeden capabilities run is probe-failed with what the interpreter said. A terminal shell or kernel serves one call at a time, jeden.runtime.slot: a call waiting for it in a cancelled turn is wait-cancelled, and one whose scope ended while it waited is slot-retired.

ast_search and ast_rewrite, jeden.tools.ast (tests/tools/programs/ast.mjs), read the file as the read tools do (jeden.tools.read) and name it in every refusal: language-unnamed and language-unknown list the grammars (rust, javascript, typescript, tsx, python and their extensions); a query the parser refuses is query-syntax, query-node-unknown, query-field-unknown, query-capture-unknown, query-predicate-invalid or query-structure-impossible, each with the line and column of the query and the parser's words; capture-none and capture-unknown list the query's captures, and a rewrite whose captures overlap is captures-overlap naming both byte ranges. A previewed rewrite is a pending action of the session, jeden.tools.pending: a pendingId the session never previewed is unknown, naming the session and the pending actions still open on its branch, one already applied or discarded is already-resolved, and a file changed since its preview is jeden.tools.ast.rewrite-conflict with both SHA-256 values.

lsp, jeden.tools.lsp (tests/tools/lsp.mjs), reads its action and what the action needs (position-invalid, diagnostics-missing, spaces-invalid, action-unknown) before it starts a server; a file of no served extension is language-unserved, a server that is not installed server-not-installed and one the call names that is no file server-not-found, both naming the PATH. Once a server runs, each refusal names it, the method and .jeden/lsp/&lt;server&gt;.stderr.log; a server that ends, closes its output or breaks the framing (stream-closed, length-invalid, length-missing, frame-short, frame-not-json, server-exited) is dropped, so the next call starts it anew, and an error the server answers is server-refused with its code, message and data.

The tools of a session's own record refuse before they read or write: save_artifact, list_artifacts and read_artifact, jeden.tools.artifacts (tests/tools/sessions/session.mjs), refuse a name holding / or .. (name-invalid) and an artifact the session does not keep (artifact-absent, naming the directory and the artifacts it holds); recall_conversation, jeden.tools.recall, opens a chat memory line with both id and n (pair-incomplete, coordinate-invalid); ask_user, jeden.tools.ask, refuses a closed standard input as input-ended; context_recommend, jeden.tools.context, reads its query, limit and sources before any source is asked (query-missing, limit-invalid, source-unknown listing files, ground-truth, memory and transcripts, sources-empty); and memory, jeden.tools.memory, reads its op and everything it needs before it opens the store, so op-unknown, confidence-invalid, source-invalid and write-unpermitted (remember and forget without --allow-write) need no database.

todo, jeden.tools.todo (tests/tools/sessions/session.mjs), reads its call whole before the retained work: op-missing and op-unknown list the ops, init and append without items or list are items-missing, an empty list phases-empty, a phase without items phase-itemless, items that join no phase phase-unnamed, an item of no text item-textless (naming its place), start, done and drop without task or phase selector-missing, all exit 2 and none reads the session. Applied to the session's completion state: no active request request-inactive, task-unknown and phase-unknown listing what the session holds, a text several tasks share task-ambiguous listing their ids, a task the operator paused task-paused and a user task the agent cannot withdraw user-task. task_evidence, jeden.completion.evidence (tests/completion/gates/evidence.mjs), refuses a call without sessionPath or eventId as text, an evidence session whose state.json cannot be read or is no JSON, one that names no workspace, a workspace that cannot be resolved or is another than this one, and a receipt the session does not record (receipt-unknown, with how many it records); the receipts of a session and its lineage refuse a lineage that cycles or names no parent and a call or result recorded without its input or result, each naming the event.

Whether a turn may run a tool is jeden.tools.approval (tests/tools/sessions/approval.mjs), read from the workspace's .jeden/mode-state.json: under plan mode a write- or exec-tier tool is plan-mode (fix: /plan off); a tool whose policy is deny is policy-denies (fix: /approval &lt;tool&gt; allow or prompt, or /approval reset); a tool the approval mode asks for that the operator did not approve is approval-withheld, naming the mode, why the session asked and the flag that grants its tier. Each names the tool and its tier, and is the tool's result the model reads. A mode state that cannot be read is its own jeden.state.file cause with a context: line naming the tool it denied, never an empty policy.

The debugger tools keep the configured DAP adapter's (JEDEN_DAP_ADAPTER or toolServices.debugger.command) stderr in .jeden/dap/&lt;adapter&gt;.stderr.log; a failed start is adapter-unstartable, and an adapter that ends, closes its output or breaks the protocol's framing is adapter-exited, adapter-closed, length-invalid, length-missing, frame-short or frame-not-json, each naming the session, the adapter's state and the log.

web_search asks Stado's search alternatives (stado capabilities call search --consumer jeden --json) with {"query", "count"}, limit a whole number above zero (how many results Stado's search answers at most is Stado's to say and refuse), and answers their results with numbered citations; image_generate and tts ask stado capabilities call inference --operation images|speech, or the provider JEDEN_MODEL_ENDPOINT names, and keep what answered as an artifact. See Other products.

MCP readers and scoped mutations share the same declaration validation: the root and mcpServers must be objects, each server must be an object, a declared enabled must be boolean, and disabledServers must contain only names. A malformed selected scope is refused before add, remove, enable or disable writes anything. Valid edits preserve unrelated top-level fields; a non-object document is never replaced with an empty one.

The real declaration journey JEDEN_BIN=target/debug/jeden JEDEN_TEST_SOURCE_REVISION=&lt;candidate-commit&gt; node tests/mcp/config.mjs runs /mcp list and scoped removal through the native CLI in an isolated home and project. It checks disabled declarations, malformed syntax, wrong root/server-map/disabled-list shapes, unreadable directories, unchanged bytes on refusal and recovery after correcting the file. A valid later project layer must not conceal an invalid user layer. The candidate must embed the clean declared revision; command results, binary/test hashes and preserved-state observations remain under .build/mcp-config. This tests configuration admission, not a remote tool server, model or graphical picker.

The real environment journey JEDEN_BIN=target/debug/jeden JEDEN_TEST_SOURCE_REVISION=&lt;candidate-commit&gt; node tests/mcp/environment.mjs starts a test server (tests/mcp/fixtures/environment-server.mjs) through /mcp tools twice: declared with no env object it must report Jeden's HOME and PATH and none of Jeden's other variables; declared with one it must report that object's values, PATH removed by null. Commands, hashes and the observed environments remain under .build/mcp-environment.

Shared lifecycle hooks receive user-prompt, pre-tool, post-tool, session-start, and stop events. Hook output may add context, replace supported input fields, or block an action through the documented decision contract.

Stop checks intermediate messages and final answers in the agent loop before they are published. Final answers also pass the completion check first. Its payload carries session_id, transcript_path, cwd, the exact text as last_assistant_message, and stop_hook_active once an earlier message or answer of the same turn was refused. A hook refuses by exiting 2 or printing {"decision":"block","reason":"…"}. A refused message stays in the retained conversation but is not published as an assistant_message or sent to any message display. The reason returns to the model, a stop-hook contract violation is recorded, and the turn continues. CLI, terminal and connected clients consume only the permitted message events. Only --max-steps, when set, ends such a turn. Leaving a session does not fire Stop.

A failure to spawn a hook, hand it its payload on stdin, collect its output, complete its process normally, or dispatch an extension hook also refuses PreToolUse and Stop. The reserved negative infrastructure outcome is not permission. Diagnostics retain the failed operation and cause; shell process failures also name the command and working directory (hook spawn failed for `&lt;command&gt;` in &lt;directory&gt;: &lt;cause&gt;, hook output failed for …, hook `&lt;command&gt;` in &lt;directory&gt; was not handed its payload: &lt;cause&gt;). A hook that closes its input without reading the payload answers as itself. Other positive exit codes keep their nonblocking meaning unless the hook returns a blocking JSON decision.

A refusal whose diagnostics cannot be persisted still refuses the answer. CLI and RPC-backed conversations end with the failure's own declared refusal (its cause id, fix and exit status kept) and a line context: &lt;operation&gt; for the answer the Stop hook refused (&lt;original reason&gt;), distinguishing reading completion state, recording the stop-hook violation, publishing completion state, reading open completion requests and recording completion_stop_refusal. A missing session name or a name that is not UTF-8 is refused before any hook runs as jeden.session.recorder.directory-unnamed, naming the directory and the Stop hooks it was named for, not an empty or substituted session identity.

A Tama registry entry may name its hook by a path relative to the registry itself, such as shared-hooks/block_identity_literals.py. Jeden resolves such a path against the registry's own directory, preferring the absolute source the registry's catalog records for that hook id, so the same catalog runs from any workspace. An absolute command is run as written, and a bare program name is left to PATH.

A registration whose file this machine does not have still refuses the tool — a guard that cannot start has judged nothing — and the refusal names it: TAMA_HOOK_INFRASTRUCTURE: the hook `&lt;id&gt;` is registered in &lt;registry&gt; as `&lt;command&gt;`, and no such file exists here (tried: …). A registration Jeden cannot read refuses the same way, naming the registry and what it states: an entry without an id, a blocking that is not true or false, an event whose hooks are not a list; so does a registry with no events table. The turn's hooks and /hooks read the registry through one reader, so /hooks lists every such registration with its reason under Registrations that cannot run here, and a broken hook install is visible before it refuses anything.

Tama's registry names tools Claude's way. post_tool_use:any (and pre_tool_use:any) is its word for every tool, so those registrations run after every Jeden tool (matcher ^.+$), not after a tool literally called any. A registry event Jeden has no event for — before_provider_request, a hook OMP runs before each provider request — runs none of its hooks in Jeden; /hooks lists each such event with its hook ids under Registry events Jeden has no event for; these hooks do not run in Jeden, and jeden doctor reports the hooks probe degraded with them in evidence.unmapped (unavailable with the cause when the registry cannot be read). block-text-outside-tool-calls also runs at Stop, which checks every message Jeden would publish. The real journey is JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… JEDEN_TEST_STADO=… node tests/hooks/tama/events.mjs, against a registry file in Tama's format in an isolated home; the model is played through Stado's attestation alternative there (its first answer calls list_dir, its second says LISTED), and its commands and outputs stay under .build/hooks-tama-events.

A file-changing tool whose request does not itself carry the complete file it leaves — the anchored edit, edit_file, apply_patch, move_file and delete_file — fires PreToolUse once per file in the shared section form Tama's write gates rebuild: tool_name is edit and tool_input holds path, a patch of [path#TAG] with PUT, CUT, REM or MV, and the added lines as new_string. Line numbers count in the file as it is before the call. The sections come from the same plan the tool executes, so a gate judges the complete file under its final path, and a removal or rename is judged as one. tool and input keep the request as the model sent it, so a hook matched by Jeden's tool name still sees it. Tama's pre_tool_use:edit registrations match all five tools. A request that cannot be planned — a stale snapshot tag, an unreadable source, an out-of-range line — refuses the tool as PreToolUse hooks cannot be shown the files &lt;tool&gt; would leave: &lt;cause&gt; instead of handing the hooks a request they cannot read.

The real mutation journey runs JEDEN_BIN=&lt;candidate&gt; TAMA_BIN=&lt;installed tama&gt; JEDEN_TEST_SOURCE_REVISION=&lt;candidate-commit&gt; JEDEN_TEST_STADO=&lt;stado&gt; node tests/hooks/tama/mutations.mjs, under the run's own HOME, where the model is played through Stado's attestation alternative: each turn's first answer calls the anchored edit with a move and a removal, move_file or delete_file with the journey's arguments, and each pass of a turn starts from the same project files. The registry runs the actual tama hook pre-write-edit and records each payload. It checks the moved file's final path and content, the removed files' absence, an untouched sibling, the presented sections, and that a move into a Python name is refused by Tama before anything changes. Commands, statuses, payloads and observed file state stay under .build/hooks-tama-mutations; an unavailable Stado or Tama fails the journey rather than passing it.

SessionStart restores model-visible context on every ordinary session surface, including after compaction. Both native and nested additionalContext fields are read; a nonzero process exit, refusal or invalid context field fails the request instead of dropping the instruction. Tama's session_start:compact registrations run only for compaction, and its ordinary session_start registrations run for the other lifecycle sources. See <a href='/docs/sessions#restore-instructions-after-compaction'>session restoration</a> for retained snapshots and diagnostics.

To qualify restoration against real dependencies, run node tests/hooks/session-context.mjs with JEDEN_BIN, JEDEN_TEST_SOURCE_REVISION, JEDEN_TEST_STADO and JEDEN_TEST_COMPACTION_THRESHOLD. The model is played through Stado's attestation alternative under the run's own HOME, and the whole journey is one pass from an empty stage, run again until every request it asks is answered. The standing instructions are the run's own, answered by the session_start and session_start:compact registrations of the Tama-format registry it writes and hands Jeden as JEDEN_TAMA_REGISTRY, each stage's rules naming that stage, so a restoration that reused an earlier answer is caught. The journey opens a real RPC conversation, compacts it repeatedly, reopens it, and checks complete instructions in exported model context. A missing hook executable must refuse the request with its path and exit cause. Reports, raw RPC frames, commands, the registry and session exports remain under .build/session-context-journeys. A failed model or memory operation fails the journey rather than standing in for a compaction result.

The real hook journey runs with JEDEN_BIN=/path/to/candidate JEDEN_TEST_SOURCE_REVISION=&lt;candidate-commit&gt; JEDEN_TEST_STADO=&lt;stado&gt; node tests/hooks/answers/journey.mjs, under the run's own HOME, where the model is played through Stado's attestation alternative: its first answer is the candidate the hook judges (an intermediate message or a final answer), its next the accepted final answer. It requires a committed candidate checkout and records the declared source revision, binary hash, commands, exit statuses, hook payloads and exported sessions under .build/hook-journeys. It exercises withheld intermediate and final text, an extension handler failure, a hook killed by a signal, and a positive nonblocking process exit. A run that never reaches the stated action fails qualification. The journey does not qualify a graphical client's rendering.

The hook journey also exercises failed refusal persistence for both intermediate and final actions: its real configured hook removes write permission from its own isolated transcript, measures the actual append refusal, then blocks the candidate. The CLI must fail with the original policy reason, attempted recording operation, transcript path and observed OS cause; neither the rejected candidate nor an invented successful event may be published. The journey compares the unchanged transcript bytes and restores the measured permissions in finally. It runs under its own HOME, workspace and session root with the model played through Stado's attestation alternative, and hands Jeden no endpoint override. These CLI cases do not substitute for graphical qualification or for a model failure combined with a recorder failure.

Separate completion-state cases remove read permission from the isolated session's real completion.json at the Stop boundary. For both intermediate and final candidates, the returned failure must retain the policy reason, reading completion state, the state path and the measured OS error. The saved state bytes must remain unchanged after permissions are restored, and the refused candidate must remain unpublished. A fixture that still permits the requested file operation fails rather than pretending that the refusal was exercised.

The append and completion-state refusal cases also run through a real RPC subprocess: session/new, a uniquely identified session/prompt, and shutdown. They require the failed response and the error notification consumed by graphical clients to retain the same policy reason, operation, path and OS cause, bind the refusal to the requested session, and inspect its exported state after restoring permissions. Raw request, response and event frames and the subprocess exit status are retained. Lifecycle and refusal journeys share tests/hooks/rpc.mjs; no server or model response is simulated. A passed RPC journey would not by itself qualify the graphical rendering.

A shutdown or permission-restoration failure fails qualification without hiding the initiating session or prompt error. The RPC refusal helper retains the prompt result before shutdown, and the journey reports the original cause alongside subprocess cleanup and filesystem restoration failures. Cleanup is not proof that the requested refusal behavior passed.

Permission probes accept only the failed open operation as the measured refusal. A close failure after a successful open fails the fixture instead of qualifying denied transcript append, completion-state read or open-request read.

If the real RPC process prints an undecodable response, the retained command records the exact output line and parser or dispatch cause under protocolErrors. The pending request fails, and subprocess cleanup refuses qualification even if the malformed line arrived with no request pending or the process later exits successfully. Malformed output is never replaced with a simulated response.

The open-requests cases exercise the real operator-asks.json stored beside the isolated session root, through CLI and RPC for both action kinds. The hook removes read permission only after a candidate reaches Stop, so the later open-request read must expose its actual filesystem cause without losing the initiating refusal. The fixture requires an existing product-created register, preserves its bytes and restores its permissions; it does not construct a canned register or touch the operator's ordinary one. Each permission target must resolve inside the same isolated case directory that contains the hook receipt and session root.

These journeys deliberately configure workspace hooks, so the CLI invocation supplies --allow-command and RPC session options supply allowCommand: true, as required by the ordinary project-hook permission contract. Neither route changes Tama capabilities or global hook selection. Without that invocation-level permission, a project hook is not authorized to run and cannot qualify its refusal behavior.

List active tools
jeden tools --cwd .

Native extensions, and a tool that reloads them#

A native extension module exports its extension as default, extension, activate, tool or tools (looked for in that order). What it declares is refused, and the extension marked unhealthy with the cause, rather than completed: a tool states its input at most once (parameters, input or schema; none means it takes no input), a command its prompt at most once (prompt, template or body), a capability its kind and version as strings, a provider its loginMethods as a list of device_code, paste or api_key. exec(command, args, options) takes args as a list of strings ([] for none) and answers the command's whole stdout and stderr. The host reads every setting from the variables Jeden starts it with and refuses to run without them.

jeden rpc publishes executable file-based commands as quickReplies in both the ready frame and the capabilities response. Each entry carries its capability ID, label, slash prompt and discovery source; native clients use that projection instead of reproducing command-directory precedence.

A native extension is discovered and activated when a session starts, so its tools, hooks and commands come from the material on disk at that moment. A tool whose job is to install extension material asks for them to be loaded again: its execution context carries requestReload(). The host runs in a short-lived process and cannot touch the registry the session holds in memory, so the call records the request as .jeden/runtime/extensions/reload-request.json, and the session consumes it immediately after the tool answers: it rebuilds the registry with a new generation, re-activating every extension source and re-materializing tools, hooks and commands.

When a reload was requested, the tool's answer is wrapped as {"result": &lt;the tool's own answer&gt;, "extensionReload": {"reloaded": true, "generation": &lt;n&gt;, "activeExtensions": &lt;n&gt;, "tools": &lt;n&gt;, "hooks": &lt;n&gt;}}. A failed reload, or a reload request that cannot be read, reports {"reloaded": false, "error": "…"} beside the same answer, so a tool that asked for one never looks successful while the reload did not happen. A tool that never calls requestReload() gets its answer unchanged and no reload runs. The request is consumed per call: one tool call reloads at most once, and a later call can ask again.

A tool that installs extension material and loads it
api.registerTool({
  name: 'install_policy',
  description: 'install a policy release and load it here',
  parameters: api.zod.object({}),
  execute: async (_id, input, _update, context) => {
    const installed = await install(input);
    await context.requestReload();
    return installed;
  },
});

Interfaces#

  • CLI (jeden, jeden run, jeden pursue, management subcommands) — canonical for human interactive, direct one-shot, and contract-driven autonomous use.
  • Interactive terminal views and slash commands — canonical for in-terminal management; non-terminal stdin renders deterministic text lists for scripts.
  • jeden rpc (NDJSON), jeden acp, jeden headless — canonical for automation and editor integration; --json flags cover scripting.
  • SDKs — the Rust SDK in rust/sdk and packages/sdk-typescript for embedding the machine interfaces.
  • MCP — the extension interface for external tool servers.