Skip to content

Latest commit

 

History

History
99 lines (70 loc) · 5.6 KB

tools.md

File metadata and controls

99 lines (70 loc) · 5.6 KB

Tools

Everything the model can call. Which of these are available in a given run depends on allowed_tools (see Configuration); whether a call goes through without asking depends on the approval policy (see Approvals).

/tools lists what is active in the running session.

Files

Tool What it does
read Read a file, with long files truncated rather than blowing the context window.
write Create a file or replace its contents outright.
edit Replace an exact string in a file. The match must be unique unless replace_all is set, which is what makes edits surgical instead of approximate.
apply_patch Batch creates, updates, deletes and renames across several files into one all-or-nothing call — if any operation fails, none are committed.
grep Search file contents by pattern.
glob Find files by glob pattern, ** included.
list_directories List what is in a directory.

Every write shows a diff in the confirmation prompt before it happens.

Bash

The bash tool runs commands in the working directory. The environment it runs in is filtered first: variables matching exclude_patterns (by default anything that looks like a key, token or secret) are stripped, and set_vars are injected. Dangerous commands are refused outright by the safety layer, whatever the approval policy says.

Planning

The plan tool keeps a todo list across the agent loop, so a multi-step task has a visible spine — steps get marked off in the transcript as they complete.

Network

Tool What it does
search Web search, backed by DuckDuckGo.
fetch Fetch a URL and hand its contents to the model.

Memory

The memory tool is key-value storage that survives across sessions, for things worth remembering beyond one conversation.

Sub-agents

The main agent can delegate to a specialized sub-agent, each of which runs its own full agent loop with a narrowed tool set and its own turn cap. Sub-agent runs are never checkpointed — they belong to the turn that spawned them.

Sub-agent What it is for
general Uses any tools permitted by its parent, including network, MCP and custom tools.
codebase_investigator Answers questions about code structure; usually the first step before a review.
code_reviewer Reviews changes for quality, bugs and improvements.
software_architect Writes code to a prompt while staying inside the project's existing style.
test_writer Writes tests, edge cases included.
debugger Tracks down errors and inconsistencies, then fixes them with read, write and edit.

Approvals still route through you: a sub-agent's tool calls surface as confirmations in the parent session, so delegation never becomes a way around the policy.

Concurrent and nested delegation

Tool What it does
spawn_agent(role, goal) Starts a child in the background and immediately returns its ID.
wait_agents(agent_ids) Waits for descendants and returns each result, status and usage.
list_agents() Lists the caller's descendants and their current status.
cancel_agent(agent_id) Cancels a descendant and its children, then waits for cleanup.

Spawn independent tasks before waiting so they run concurrently. Children can delegate again within the same turn's limits. Each child has a separate conversation; its goal must include the context it needs. The existing subagent_* tools remain blocking shortcuts for one child.

Open the live agent tree with Ctrl+G or /agents to see nested tasks and active tools. Use ↑/↓ to select a child and read its recent activity and result, Enter to expand its children, and c to cancel its subtree. Ctrl+C interrupts the whole turn (while an approval prompt is open, it rejects that request). The status line shows active agent counts and token usage. /agents <id> shows a full result. This detail is kept for the current process's last turn; child conversations are not saved as resumable sessions.

By default the tree has at most four executing agents, two child levels below the root, and twelve agents total including the root. Waiting parents release their execution slots. All children finish or are cancelled before the turn closes. See the [agents] settings in Configuration.

Child tool permissions are intersected with their parent's and enforced at execution, including for MCP and custom tools. An empty allowed_tools list allows no tools. Approval requests are queued centrally. Mutating tool operations are serialized, including their approval previews; give changes to the same file to one agent because previous reads can become stale. Child failure is reported to its parent without cancelling unrelated siblings.

MCP

Postal connects to external Model Context Protocol servers over stdio or HTTP/SSE and registers their tools alongside the built-in ones. Configure servers under [mcp_servers.<name>] and check them with /mcp.

MCP tools are always treated as mutating, because a third-party server's side effects cannot be inferred from its schema.

Context handling

Two mechanisms keep long sessions alive, and neither is a tool the model calls — they run around the loop:

  • Pruning. Old tool outputs are cleared once they pile up past the recent working set, reclaiming tokens without touching the conversation itself.
  • Compaction. When the context window fills up, history is summarized into a continuation brief and the session resumes from it instead of erroring out.