zidane/tools

Create an interaction tool that lets the agent request structured input.

The model calls this tool with a payload matching the schema. onRequest is called with the payload and should return the response (string or object) that gets sent back to the model as the tool result.

Creates the shell tool, which runs a command in the execution context, in the foreground or as a background task.

The default exported shell is equivalent to createShellTool({ allowBackground: true }). Hosts that use createAgent typically do not call this directly: when behavior.tasksDir is unset or behavior.disableBackgroundTasks: true is set, the agent rewrites the registered built-in shell using this factory.

Truncation is tail-priority: when stdout+stderr combined exceeds maxOutputBytes, the head is dropped and a marker …(N bytes truncated from head)… is inserted before the tail. Errors and exit summaries usually live at the end of output, so keeping the tail preserves the model's most useful signal. Commands that only explore (cat, sed -n, grep, ls, git log…) keep their start and end instead: what a read shows first is what it was run for.

The combined cap defaults to 32 KiB and the per-call timeout follows the execution context's own default (30 s for in-process).

Read-only commands run in parallel with other safe tool calls. Anything else runs alone.

Factory for skills_use. Auto-injected into the agent's tool set by the agent runtime when a non-empty skills catalog is available (unless SkillsConfig.tool === false).

The name property carries no enum so the tool list stays byte-stable across catalogs; unknown names are rejected at runtime with the list of available skills.

Create a configured spawn tool.

State (children, totalChildStats, counters, active count) is scoped to the returned instance. Multiple parent agents using the same instance will share counters + stats + concurrency slots — call createSpawnTool() per agent (or use the stateless default spawn) to keep them isolated.

Get or lazily create the per-session read-state map. Returns undefined when no session is provided.

Most tool callers should prefer resolveReadStateMap, which additionally honors an explicit ctx.readState (the path spawn's shareReadState: true uses to forward the parent's map into a sessionless child). Use this helper directly only when the Session-keyed map is exactly what you want and you don't need to accept an override.

Rebuild the per-session read-state map from durable session turns.

Durable replay runtimes may return recorded tool results without re-running the tool body, so in-memory side effects like readState.set(...) can be missing even though the transcript contains the successful read_file. This helper is intentionally opt-in: live hosts keep the normal side-effect behavior unless they call it themselves.

Hydration only fills missing keys. Live in-memory state may already reflect a newer read or edit from the current run, and durable history cannot prove it is fresher. Relative paths are resolved against the current execution cwd, matching replay hosts that run sessions from a stable workspace.

Canonical read-state key for a (cwd, path) pair.

ctx.execution.readFile(handle, path) resolves the model-provided path against handle.cwd before touching disk — so src/App.tsx, ./src/App.tsx, and /abs/cwd/src/App.tsx all read the same bytes. The read-state map MUST mirror that resolution: without it, a model that reads src/App.tsx and then edits ./src/App.tsx trips the requireReadBeforeEdit gate for a file it demonstrably already saw (the gate's "has not been read in this session" message fires on a stale key).

node:path's resolve(cwd, path) short-circuits when path is already absolute, so absolute and relative shapes converge on the same canonical form. We don't realpath() symlinks — the file IS the path the model addressed, not the realpath behind it; the host's execution context decides how to dereference.

Resolve the active read-state map from a tool context. An explicit ctx.readState wins (used by spawn's shareReadState opt-in to forward the parent's map into a sessionless child); otherwise the usual Session-keyed lookup applies.

Tools should call this helper instead of getReadState(ctx.session) directly so the shareReadState plumbing is honored uniformly.

Keep the last maxBytes UTF-8 bytes of text, dropping the head and prefixing a marker. A non-positive maxBytes disables truncation and returns text unchanged.

maxBytes budgets the kept tail only; the marker is added on top and may push the returned string slightly past maxBytes. That tradeoff is intentional — folding the marker into the budget would shrink the content actually shown. A leading run of U+FFFD (left by an upstream raw-byte slice that landed mid-codepoint) is stripped from the kept tail.

Surgical edit — replace old_string with new_string in a single file.

Mirrors Claude Code's Edit semantics so models post-trained on Anthropic's tool surface need no relearning. Fails clearly when old_string isn't unique (unless replace_all: true) and when not found, with a nearest-match preview so the model can recover without a separate read_file round-trip.

The glob tool. Lists files in the execution context that match a glob pattern.

Delegates matching to ExecutionContext.listFiles with { glob: true }. This keeps filesystem semantics inside the execution context (process / docker / sandbox) instead of reaching around it from the tool.

Results are capped at 1000 entries by default to keep model input bounded. The cap applies after the directory filter, so dirs don't consume the file budget.

Patterns are deliberately NOT confined to the workspace: like read_file, ../-prefixed patterns may match outside the cwd — the execution context is the sandbox boundary, not this tool.

By default, contexts that can cheaply provide metadata return <path>\t<size>\t<mtime> rows. Contexts without cheap metadata support return paths only. Pass metadata: false to request plain newline-separated paths.

The grep tool. Searches file contents for regular expressions, using ripgrep when it is available and a JavaScript fallback otherwise.

Wraps ripgrep (rg) when available; when it's not, falls back to a regex search that enumerates files via the execution context's shell (find over exec) and reads them via ctx.execution.readFile. Both legs go through the ToolContext.execution seam, so the search runs wherever the context's files actually live — in-process, a container, or a remote sandbox — without the tool ever touching the host filesystem directly.

The tool surface mirrors Claude Code's Grep so models authored against the Anthropic tool surface need no relearning. Output modes:

• files_with_matches (default) — newline-separated paths.
• content — path:line:match (line numbers on by default).
• count — path:N per matching file.

Results are capped via head_limit (default 250) to keep model input bounded; offset lets the caller page through. Pagination operates on OUTPUT LINES, not match groups — in content mode, context lines and -- separators consume the budget too (documented in the schema).

A line cap is not enough on its own: ripgrep is line-oriented, so a minified / single-line file collapses to ONE match line that is the entire file, and head_limit would happily return megabytes — enough to blow the model's context window. Output is therefore ALSO byte-bounded: each line is clipped to MAX_LINE_BYTES and the total to OUTPUT_BYTE_CAP, mirroring the byte discipline read_file already enforces.

path is deliberately NOT confined to the workspace: like read_file, absolute paths and ../ traversal are allowed — the execution context is the sandbox boundary, not this tool.

The multi_edit tool. Applies a list of string replacements to one file in order, each on the output of the previous one. Best-effort, per-hunk semantics.

Each step replaces old_string with new_string against the file contents as left by the previous applied edit. A per-step failure (old_string not found, ambiguous match without replace_all, identical strings, malformed input) is recorded against THAT step only — the remaining steps still run. The file is written iff at least one step applied. The result text reports per-hunk outcomes inline and (when any step failed) carries an <edit-outcomes>…</edit-outcomes> annotation block so the chat layer

• replay can paint per-hunk badges via parseEditOutcomesFromResult.

Per-hunk approval is a TUI/host concern. When the user partially denies a multi_edit from the file-edit modal, the gate handler rebinds ctx.input.edits to the approved subset before this tool runs — so the body sees a smaller all-approved batch and reports outcomes keyed against THAT subset. The host's tool:transform hook merges this subset-keyed result with the approval-side denied entries (1:1 with the model's ORIGINAL edits list) before the canonical <edit-outcomes> block lands on the wire — see mergeApprovalAndBodyOutcomes in chat/edit-approval.ts.

Wire / replay format (see parseEditOutcomesFromResult):

Edited <path>: applied N of M edits (R replacements).
edit #2 failed: old_string not found in <path>.

<edit-outcomes>
#1 applied
#2 failed: old_string not found in <path>
#3 applied
</edit-outcomes>

The annotation is omitted entirely on the all-applied path — the renderer's isEditErrorResult check then suppresses the paired tool-result so the diff stands alone.

The read_file tool. Reads one file, or several files and ranges in one call, from the execution context, with line-based offset/limit and a hard byte cap.

Defaults are tuned for source code: 2000 lines / 256 KiB. A typical source file, lockfile, or large config fits in one read; logs and very large fixtures get truncated with a footer that documents how to fetch the remainder.

Binary files are detected on the leading characters of the decoded text — if the sample contains a NUL or a high proportion of U+FFFD replacement characters, we return a marker so the model doesn't drown in mojibake.

Default shell tool with background mode enabled.

Most hosts use this directly via basicTools. When the agent's behavior.tasksDir is unset OR behavior.disableBackgroundTasks: true is set, createAgent auto-rewrites this identity to a createShellTool({ allowBackground: false }) variant so the model never sees a flag it can't use. Hosts who want to bypass that auto-rewrite can register a createShellTool({ allowBackground }) directly — the rewrite only fires on identity-equal references to this constant.

Write a file, with an idempotency signal when the content is unchanged.

Three return shapes — chosen so the model can recognize a no-op without a separate read:

• Created path (N bytes) — file did not exist
• Updated path (N bytes) — content differed from on-disk
• No change needed: path already at target state (N bytes) — equal

Race window: in non-process execution contexts (docker, sandbox) shared by multiple agents, another writer can mutate the file between our read and our write. Local process context is single-writer per agent so the race is a non-issue there. Documented rather than locked because the cost of cross-context locking outweighs the cost of a stale "No change" message.

Runtime context passed to every tool execution. Provides access to the agent's provider, abort signal, execution environment, and hooks.

The preset-y fields (name, system, tools, toolAliases, toolDescriptions, mcpServers, skills, behavior) mirror the agent's own options so child-spawning tools can inherit them.