Browse documentation

Technical documentation / Reference

Tools and safety model

Feature docs index · Repository README

Choose a tool below, then check its path, output, and credential limits before use. Shell guardrails are not an OS sandbox.

ToolContract
readRead local files and skills. Local reads supply tags and line anchors for hash_edit.
bashRun non-interactive shell commands or bounded background jobs. Aliases: shell, cmd.
bash_jobRead output, inspect, stop, or list this session's background jobs.
hash_editEdit existing UTF-8 files using current read tags and visible line anchors. Supports block edits, moves, and deletion.
writeCreate or replace a UTF-8 file, up to 1 MiB. Creates parent directories and rejects final symlink targets.
grepSearch file contents with regex or literal patterns, ranked or raw results, and pagination.
findFind file and directory paths with fuzzy matching and ignore rules.
list_filesList direct children of a directory, including hidden and ignored entries.
ast_grepSearch source structure, preview rewrites, or list symbols. Does not modify files or require an external CLI.
view_imageSend one local PNG, JPEG, GIF, or WebP image to the configured vision model.
subagentsDelegate independent tasks to bounded parallel child sessions. See Parallel subagents.
webSearch public sources or open a public URL. Does not control a browser.
code_modeRun synchronous JavaScript that calls permitted tools and returns selected results. Enabled by default. See Code Mode.
magi_controlInspect context usage or compact the current session. Direct calls only. See Sessions and context.

Availability depends on settings, agent permissions, and approved MCP servers. Direct tools and tools inside Code Mode have separate enable/disable lists.

Every built-in and MCP tool requires a top-level intent: a nonblank string briefly explaining why the call is needed. This includes code_mode, magi_control, and each built-in or MCP call inside Code Mode; an outer batch intent does not replace inner-call intents. Missing, non-string, empty, or whitespace-only intent fails before tool execution. Subagent task objectives remain separate from the batch intent. MCP calls put server inputs in a separate arguments object; only that object reaches the server, preserving any server-owned intent field. Client-registered tools retain their own schemas and do not require harness intent.

Concurrent calls

Consecutive direct calls to read, find, list_files, grep, ast_grep, web, and view_image from one provider response run with at most four scoped workers. Code Mode's synchronous tools.callAll([{name, args}, ...]) uses the same worker path and returns results in input order (at most 32 entries). Calls outside this list, unavailable or rejected calls, and mutation tools form barriers: earlier calls finish before the barrier runs, and later reads observe its changes. Individual tools.call calls remain sequential. MCP and client tools do not run in this parallel path.

Any configured hook keeps the response sequential, including hooks for other phases and disabled hook configurations. Tool permissions, inspection ceilings, per-surface exclusions, and argument validation still apply through normal dispatch.

All calls in a concurrent run are recorded and shown as started before dispatch. Results, execution evidence, read-snapshot coverage, instruction loading, provider context, and finish events are committed in original call order on the lifecycle thread. Cancellation reaches every worker; workers join before ordered result/cancel delivery and turn termination. Completed results remain recorded; unfinished calls receive failed results rather than dangling call records. A slow earlier call can delay display of later results.

Shell commands

bash requires command and a nonblank intent that briefly explains why the command is needed. The transcript card shows intent above command, then result summary. timeout is optional (1–600 seconds, default 600). Omit it for the full ten-minute allowance; set a shorter timeout only when needed. Runtime aliases shell and cmd also require intent.

On Unix, agent shell calls start Bash with pipefail: a failed pipeline stage makes the pipeline fail even when its final filter succeeds. This does not enable errexit and does not change hook shell defaults. Commands can disable pipefail or mask status explicitly, so this is not a sandbox or proof that a build passed. Output truncation and timeouts remain separate from process exit status.

Background jobs

Use bash with background: true for dev servers, watchers, and long builds. Do not add &, nohup, or setsid: the shell must stay in its managed process group. timeout is invalid with background: true; jobs have no lifetime timeout while their owner lives. The call observes up to 200 ms of startup, then returns JSON with job_id, pid (and Unix pgid), status, exit_code, uptime, stdout/stderr, and truncation metadata. Normal foreground commands keep their timeout and cleanup behavior.

Background Bash cards carry a background label. In Mission Control, the Background Jobs header panel (Alt-4, the header Panels menu, or /background-jobs) shows a live list for the primary conversation (not side conversations or subagents), including jobs started through Code Mode. With the panel focused, use Up/Down to select and k to stop its process group; Esc closes it when unpinned. It works during active prompts, never consumes job output, and keeps termination off the UI thread. Finished jobs disappear from this list; bash_job list still includes retained finished jobs.

bash_job requires intent and action. Omit inapplicable optional fields or pass null (including timeout for background Bash calls):

Each owner permits four running jobs and retains at most sixteen jobs, evicting the oldest finished job when needed. A fifth running job fails with the running IDs. Each stream has a 256 KiB ring; old bytes are dropped and counted. Output calls stay within Bash's stdout/stderr limits and expose has_more_output. At most 64 background pipe-reader threads run per process; exhausting that bound fails job setup rather than creating more threads.

Jobs survive turn completion and Esc. Stop them when finished. Session switch, /new, application exit, and local-agent connection close stop owned jobs; subagent completion stops its own jobs, inaccessible to its parent. Unix cleanup targets the whole process group. Processes that deliberately escape it are not managed. Non-Unix cleanup kills only the direct child. SIGKILL of magi-code can orphan jobs; startup does not reap them.

Both tools use normal hooks, approvals, redaction, and permissions. Disabling bash also denies bash_job on that surface, including Code Mode, profiles, and task ceilings; inspection mode denies both. Code Mode jobs belong to the session, not the script. Background file activity is not inferred and never counts as confirmed changed paths. Calls/results are ordinary durable tool records, but live jobs are runtime-only: old, evicted, and foreign IDs return a not-found error rather than being replayed.

AST search and outlines

ast_grep defaults to operation: "search". Search requires pattern and accepts optional rewrite for a read-only diff preview. Use operation: "outline" to inspect symbols before reading source.

Neither operation needs an installed CLI. Embedded AST libraries infer language from file extension unless you supply one. Project configs and custom grammars are not loaded.

{"intent":"Inspect Rust symbols before reading implementations","operation":"outline","path":"src","language":"rust","limit":30}

URL routing

Use the narrowest tool that meets the request:

NeedToolUse
Public unauthenticated plain text, Markdown, JSON, or HTML ordinary GETweb openBounded native fetch/readability; no JavaScript or interaction.
Public research and page textwebSearch and open; no browser interaction or CSS extraction.
Custom or non-public HTTP workbashCustom methods, headers, bodies, redirect control, binary downloads, private/local services, or an explicit request.

URL open applies bounded readability extraction to substantial HTML and converts short HTML to Markdown. Never block or rewrite curl.

web contract

Use one operation per call. Omit unused fields or set them to null:

{"intent":"Find official Rust release notes","operation":"search","query":"Rust official release notes","limit":5,"domainFilter":["rust-lang.org","-old.rust-lang.org"],"recencyFilter":"month"}
{"intent":"Read the Rust project homepage","operation":"open","url":"https://www.rust-lang.org/"}
{"intent":"Read a cached research result","operation":"open","reference":"web:<reference from a result>"}

Visible tool output

Mission Control shows pending and completed tool activity with safe status, metadata, and bounded output. Pending write/hash_edit entries do not include file contents or replacement payloads. web shows query/result/truncation metadata and redacts credential-shaped text. read shows requested paths. Subagent summaries omit raw child output. Shared summaries live in src/output/tool_summary.rs.

Mission Control may show successful hash_edit changes as a bounded changed-line transcript preview and a larger activity-detail diff. Both are display-only, not provider tool results or JSONL session data.

subagents displays a bounded aggregate summary rather than raw child output.

Reading files

Use paths for known local files or skills:

{ "intent": "Read project setup instructions", "paths": ["README.md:1-200"] }

Missing read, list_files, grep, and find paths remain failures but may suggest up to three existing permitted paths. Suggestions compare the next missing component case-insensitively, then by edit distance up to two, scanning at most 1,000 entries in the deepest existing ancestor (up to 32 ancestor steps and a cooperative 100 ms deadline). Symlink targets outside the allowed root are never suggested. Suggestions do not execute a different path.

Finding paths

Discover paths without reading contents:

{ "intent": "Locate library source paths", "query": "lib", "kind": "mixed", "path": "src", "limit": 20, "offset": 0 }

Rules:

Searching contents

{ "intent": "Locate the run function", "patterns": ["fn run"], "path": "src", "limit": 20, "context": 2 }

Editing files

Anchor patches to the latest read tags:

{ "intent": "Update README instructions", "input": "[README.md#A1B2]\nSWAP 10.=10:\n+new line" }

Rules:

Inspecting images

Configure an explicit vision provider/model before use:

{
  "capabilities": {
    "tools": {
      "view_image": {
        "vision_model": {
          "provider": "local-vision",
          "model": "vision-model-id"
        },
        "absolute_paths": true,
        "max_image_bytes": 5242880
      }
    }
  }
}

Rules:

Safety boundaries

Edit this page on GitHub ↗