Controlled tools, accountable effects.

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. Symbolic links and .. components stay refused.

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.

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 accepts at most 512 KB. A truncated result is refused before the model request and identifies the incomplete image. Use a complete image within the reader's size limit; a partial PNG is not a readable image.

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.

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.

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 jeden headless <addr> (mutual TLS), jeden collab-relay, and jeden stats --serve (bound to 127.0.0.1).

The one required outbound dependency is BRAMA_URL; optional dependencies — Wisent Platform Billing for subscription and quota decisions, the Stado integration and media APIs, and the release manifest host for jeden update — activate only when configured. Tool-initiated network access (fetch_url, fetch_readable_url, SSH) is checked against the execution grant’s host and port allowlist with pinned addresses and re-authorized redirects.

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.

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.

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 `<id>` is registered in <registry> as `<command>`, and no such file exists here (tried: …). /hooks lists the same registrations under Registrations with no executable here, so a broken hook install is visible before it refuses anything.

jeden tools --cwd .

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 — packages/sdk-typescript and python/jeden_sdk for embedding the machine interfaces.
• MCP — the extension interface for external tool servers.