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.

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–300 seconds, default 30). Runtime aliases shell and cmd also require intent.

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.

• Search returns path:line:text with 1-based lines. Rewrite previews identify each match by path, line, and exact end-exclusive byte range, then show removed - lines and replacement + lines. Surrounding text remains unchanged, and files are never written. Overlapping matches produce independent previews, not one combined patch.
• limit bounds returned lines (default 100, maximum 500); output is capped at 64 KiB. A boundary can cut a preview short, so check truncated before using it.
• Pattern and rewrite each accept up to 4 KiB. Search accepts complete UTF-8 files up to 256 KiB, visits at most 10,000 files, and reads at most 128 MiB per call. Syntax trees are limited to 16,384 nodes and depth 64; patterns to 256 nodes. Replacement allocation estimates are capped at 1 MiB before expansion. files_skipped, partial, and truncated report oversized, unreadable, non-UTF-8, or overly complex files.
• Parsing, including pattern parsing, checks cancellation and a shared 30-second deadline. Traversal checks each AST node before matching. A single bounded library match/replacement or filesystem operation cannot be interrupted mid-call. No detached workers are created. Unknown file types are skipped. In mixed-language searches, a pattern that cannot compile for one language makes results partial. Supply a language for strict pattern validation.
• Outline shares search's complete-file, file-count, scan-byte, and syntax-tree limits. Bundled rules cover Rust, TypeScript/TSX, JavaScript, Python, Go, Kotlin, Java, and Swift. Other languages are ignored.

{"operation":"outline","path":"src","language":"rust","limit":30}

• For outline, omit pattern and rewrite or set them to JSON null. Other values, including empty strings and placeholders, are rejected. Outline-only fields are items (structure by default, or exports, imports, all), view (digest by default, or names, signatures, expanded), name (Rust regex over top-level name/signature/first source line), symbol_type (comma-separated lower camel case types), and pub_members (default false). For search, omit these fields or set them to null; pub_members: false does not count as absent. Filters do not select members directly. Name/type filters are capped at 512 bytes.
• All fields except operation treat null as omission. Search still requires a nonempty pattern. If supplied, operation must be search or outline. Providers that require every key can use "pattern":null,"rewrite":null for outline and null outline-only fields for search. Invalid mode-specific arguments report offending fields with an omit-or-null example.
• Explicit structure/digest defaults retain internal symbols for directory and file requests. names omits members and computes only names, though name filtering still computes signatures. signatures includes top-level signatures; digest adds member names; expanded adds member signatures.
• Each output line is a complete JSON object with path, language, and item. Items contain names, types, signatures, export/import flags, ranges, and direct members selected by the view. Lines and columns are 1-based; range ends are exclusive. Byte offsets are omitted.
• limit counts top-level entries, not members or source lines (default 100, maximum 500). A parent and its selected members are kept or omitted together. Returned entry text is capped at 64 KiB.
• Outline checks cancellation and the shared 30-second deadline before and after each extraction iterator step and before accepting output. One step may traverse the remaining bounded file tree and collect direct members. Individual library calls, including compilation of fixed bundled rules, and filesystem operations cannot stop mid-call. The deadline is cooperative, not a strict timeout. No child processes or detached workers are created.
• Check symbols_returned, files_skipped, partial, and truncated. Byte and entry limits retain only complete earlier entries; deadlines return partial failure. Empty outlines succeed. Project or ancestor sgconfig.yml, custom language libraries, and custom outline rules are never loaded. Only approved regular files are read under the same path and read checks as search.

URL routing

Use the narrowest tool that meets the 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:

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

• With active openai-codex, search uses the active model and existing Codex OAuth/refresh at https://chatgpt.com/backend-api/codex/responses with native web_search. Other providers use Exa /search and require environment-only EXA_API_KEY. URL open fetches directly without credentials or an Exa key. Search backends do not fall back to each other or MCP.
• Codex returns a labeled model-generated synthesis with URL citations, not page extracts. It creates no cached references; open cited URLs separately for page text. limit requests a source count but does not enforce it. Codex rejects domainFilter and recencyFilter; omit both. The filtered example above applies only to Exa.
• Codex search requires response.completed, rejects failed or incomplete streams, and caps streams at 2 MiB. It reuses the provider's blocking transport, cancellation, byte-idle and semantic-progress watchdogs, and session-expiry refresh. Tool output remains capped at 48 KiB.
• Query: 1 to 512 characters after trimming. URL: at most 2,048 UTF-8 bytes. Search results: 1 to 10, default 5.
• Search-only domainFilter accepts at most 20 bare ASCII domains (253 characters per domain, 63 per label). Prefix - to exclude. Schemes, ports, paths, whitespace, empty labels, and leading/trailing label hyphens are rejected. Entries are trimmed. Includes/excludes map to Exa includeDomains/excludeDomains. recencyFilter accepts day, week, month, or year, mapped to startPublishedDate at the current UTC date minus 1, 7, 30, or 365 days. It filters publication date, not crawl freshness. For open, omit filters or set them to null. Aliases and query batches are unsupported.
• Only public HTTP(S) URLs are accepted. Credentials and sensitive URL parameters are rejected. URL open uses the DNS-pinned transport in url_fetch.rs, which rejects private/local destinations and redirects. Exa result URLs are also validated; Exa controls retrieval of search extracts.
• Exa search text requests are capped at 10,000 characters per page and responses at 2 MiB, with 5s/20s connect/request timeouts. Direct URL open downloads at most 512 KiB with 5s/15s connect/request timeouts and a 5,000-token text budget. Both check cancellation, cache at most 40,000 bytes per page, and cap output at 48 KiB with truncation metadata.
• Exa search shows source URLs, stable references, and bounded excerpts. Cached open returns stored text.
• Runtime stores up to 64 immutable page snapshots and evicts the oldest. Runtime clones share this cache. Sessions do not persist or restore it. An expired or unknown reference fails without network work; reopen the public URL for a new reference.
• URL open makes a direct GET and returns readable text, which may omit page content. Cached open returns the same snapshot without refreshing. Output gives no publication, crawl, or fetch timestamps; do not infer them from a reference.

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.

When opt-in LSP edit injection has fresh diagnostics, they are appended to the successful write/hash_edit tool result. 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:

{ "paths": ["README.md:1-200"] }

• Provider-facing schema requires paths, accepting 1 to 8 entries. Runtime validation rejects missing, empty, blank, or unknown-file inputs.
• Recognized read targets: local files, skill://<name> skill definitions, and skill://<name>/<relative-reference> skill reference files. Other resource schemes are unsupported. HTTP(S) targets fail with guidance to use web open.
• String selector suffixes: :N, :-M, :N-M, :N+, :N+K, :raw, and compounds such as :raw:50-100. Selectors apply independently to each target.
• Each local file remains limited to 1 MiB and UTF-8 text. Local files without a selector return up to 400 lines; use line selectors to choose another range.
• Multi-file output uses --- FILE: <requested path> --- sections. File-specific errors appear as ERROR: sections, and successful file sections remain visible when another requested file fails.
• Complete multi-file ToolResult.content is capped at 1 MiB measured as UTF-8 bytes, including file headers, separators, file content, and ERROR: text.
• read does not search, expand globs, or discover files. Use find for fuzzy path discovery or grep for content search, then read known paths/resources.
• Local file reads default to hashline output: [path#TAG] header plus 1-indexed LINE:TEXT rows.
• :raw bypasses hashline formatting for plain text (path:raw, path:raw:20-40); it does not bypass byte caps or path/skill protections.
• Skill reference reads are limited to discovered/enabled skills. References must be relative, cannot contain .., cannot target symlinks or directories, must remain under the canonical skill directory, and must be UTF-8 under the 1 MiB read cap.
• hash_edit anchors must use the newest tag and visible line numbers from the most recent read or successful hash_edit response for that file. Stale-tag failures mean re-read first, then retry with fresh anchors.

Finding paths

Discover paths without reading contents:

{ "query": "lib", "kind": "mixed", "path": "src", "limit": 20, "offset": 0 }

Rules:

• query is required, trimmed, and limited to 512 characters.
• kind defaults to files; directories results end with / in output, and mixed can return both files and directories.
• limit defaults to 50 and is capped at 200; offset supports pagination.
• path is optional and must resolve to an existing directory. Relative paths stay within cwd; absolute paths outside cwd require capabilities.tools.find.absolute_paths (default true). Output is slash-normalized, cwd-relative for paths within cwd and absolute for outside paths.
• find is read-only, uses the shared workspace walker, and does not replace grep content search.
• Each scan cooperatively checks cancellation, visits at most 100,000 entries (including the root), and has a 10-second deadline. Filesystem calls can exceed a cooperative deadline. Narrow path when a scan is partial.
• scan_complete and total_matched_exact identify exhaustive scans. Partial scans rank only observed matches, set truncated: true and index_ready: false, and report has_more: null; total_matched is then a lower bound. entries_scanned, entry_limit_reached, timed_out, walk_errors, and walk_entries_omitted explain incomplete traversal. Paging does not resume a partial scan.
• Workspace walking honors standard hidden/.ignore/Git filters plus Perforce defaults and configuration. It prunes ignored directories before scanning and feeds find, grep, and directory-mode ast_grep; list_files intentionally remains a raw shallow listing.
• Perforce resolution follows P4CONFIG → P4ENVIRO → process environment → Windows user/system registry. P4IGNORE accepts ordered semicolon-separated relative or absolute rule files; unset values use .p4ignore followed by p4ignore.txt. Non-macOS POSIX systems default P4ENVIRO to $HOME/.p4enviro; Windows and macOS require it explicitly. .p4root is always excluded; .p4config and configured P4CONFIG filename are excluded when configuration discovery is active. P4 rule/config reads are bounded. macOS p4 set preferences are not read directly; expose those values through P4CONFIG, P4ENVIRO, or process environment.
• fs_cache stores directory listings only, keyed by path plus directory mtime with TTL expiry. It does not cache file bytes or provider-visible tool output.

Searching contents

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

• grep is fully in-process Rust search; it does not spawn rg or require search credentials.
• patterns is required, accepts 1 to 8 exact strings, and uses OR semantics.
• Each pattern is matched as a case-sensitive regex after common brace/parenthesis repairs; failed compilation falls back to literal matching. The original pattern bytes are preserved for matching diagnostics and display.
• Ranked mode is the default: it emits grouped_v1 path headers, [def-like], [match], and [import] primary labels, and deduplicated context rows. Raw mode emits flat deterministic path:line:content rows and uses one extra match as a pagination lookahead.
• limit and offset apply to primary matching lines; context adds at most 20 lines on either side and does not consume the primary limit. Ranked mode keeps at most five primary hits per file and reports omitted hits with truncated and per_file metadata.
• Reads are capped at 4 MiB per file and 128 MiB per invocation; traversal is capped at 10,000 files and 10 seconds. The provider-visible output is capped at 65,536 UTF-8 bytes and records are added atomically.
• Hidden, ignored, .git, target, binary, special, and unreadable files are skipped as applicable. Metadata reports scan byte/file limits, per-file limits, recovery skips, binary/invalid-UTF-8 counts, matcher adjustments/fallbacks, exact-match status, and truncation reasons.

Editing files

Anchor patches to the latest read tags:

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

Rules:

• Each file section starts [PATH#TAG]; TAG must come from latest current-session hashline read output or previous successful hash_edit response.
• Supported ops: SWAP, SWAP.BLK, DEL, DEL.BLK, INS.PRE, INS.POST, INS.BLK.POST, INS.HEAD, INS.TAIL, MV, and REM.
• Body-taking ops end with : and accept only +TEXT rows. Literal leading plus/minus content still needs the body prefix: ++value, +- item.
• Stale tag or surprising result: re-read file, then reissue patch with fresh tag/line anchors.
• hash_edit does not create new files; use write for creation.

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:

• path must be an absolute path to one existing regular local image. The path is canonicalized; supported formats are PNG, JPEG, GIF, and WebP, with case-insensitive extensions that must match the file signature. Outside-cwd access follows capabilities.tools.view_image.absolute_paths.
• prompt is required and should name the exact visual details to inspect.
• Image bytes go only to the explicitly configured vision model; there is no active-chat-model fallback.
• capabilities.tools.view_image.max_image_bytes defaults to 5 MiB and is configurable from 1 byte through 20 MiB. Returned text is capped at 64 KiB.

LSP edit diagnostics are opt-in and workspace-bound. Missing, slow, crashed, stale, or indexing servers skip injection without changing write or hash_edit success. They complement project checks and do not replace cargo check, tests, linters, or repository-specific verification.

Safety boundaries

• Tool calls and effects are represented in the session transcript.
• Relative paths resolve from the active working directory and cannot escape it. Built-ins accepting caller-controlled OS paths have independent, default-allow absolute-path settings; see the authoritative Configuration matrix for keys, aliases, exceptions, and opt-out behavior. LSP edit-diagnostic injection remains workspace-bound because it has no caller path argument.
• bash / shell allows shell expansion by default. Set capabilities.tools.bash.shell_expansion: false to reject $, ~, backticks, {, and } in bash commands during preflight.
• hash_edit and write reject final symlink mutation targets and enforce size/count limits. hash_edit validates all sections before mutation when semantic/path checks fail, rejects unanchored or unseen-line hunks, and guards REM to regular files only. Write replacement is atomic, but committed-but-undurable failures are possible.
• Cwd/root checks reduce accidental escapes and common symlink escapes, but they are not a full TOCTOU-safe sandbox against a malicious concurrent local process racing the filesystem.
• bash / shell runs through the host shell and is not an OS sandbox.
• web uses Codex OAuth for active Codex search and environment-only EXA_API_KEY for other search, with no backend/MCP fallback. URL open fetches directly without an API key. URL checks, timeouts, bounded snapshots, and output limits are described above.
• grep output is capped at 64 KiB; web output is capped at 48 KiB with explicit truncation metadata.
• Mission Control has separate transcript-card and Selected Activity Detail projections; subagents shows only safe summaries. Local/session raw results remain unchanged by these display projections. Do not ask tools to read or print secrets unless you accept them in terminal output and session artifacts.
• File mutations are coordinated by per-file mutation locks.

Token-triggered streaming reminders

TTSR is disabled by default. When agent.reminders.enabled is true, rules inspect assistant streaming deltas and completed tool-call arguments mid-turn. Regex rules stay dormant until a match; on a match, magi-code aborts the current stream, records a hidden local ttsr_injection JSONL event, injects the configured system reminder, and retries the turn.

Built-in rules cover destructive commands, secret exfiltration, credential routing, cwd widening, and force push patterns when TTSR is enabled. User rules live in agent.reminders.rules settings as { "pattern": "...", "reminder": "..." } objects. TTSR is separate from hooks: hooks run at phase boundaries around tool/assistant events, while TTSR can interrupt provider streaming before a tool executes or assistant text completes.

Related docs

• Offline tool-output measurement
• Tool-call bash hooks
• Parallel subagents
• LSP diagnostics

Edit this page on GitHub ↗