Tools and permissions

Tools

Tool	What it does
`read`	Reads a file.
`glob`	Finds files by pattern (respects ignore rules).
`grep`	Searches file contents.
`edit`	Makes a targeted change to an existing file.
`write`	Creates or overwrites a file.
`exec_command`	Runs a command in one of the agent’s own PTY sessions.
`write_stdin`	Sends input to, and reads more output from, a running session.
`read_block`	Reads a command block’s output.
`update_plan`	Keeps the agent’s step-by-step plan up to date.
`ask_user`	Asks you a question and waits for the answer.

The agent’s own shells

Agent commands never run in your shell and are never typed into your prompt. Each exec_command runs in a separate PTY session owned by the agent, which can be sandboxed. A long-running command returns a session_id; the agent follows it with write_stdin instead of blocking.

Errors

A failing tool doesn’t crash the turn. The error goes back to the model as an is_error result, so it can read it and try something else.

Permissions

permissions/ has two parts: command classification and a policy.

Classification

Every command is classified as one of:

Class	Meaning
`readonly`	Only reads (for example `ls`, `cat`, `git status`).
`shell-state`	Changes the shell’s state (for example `cd`, `export`).
`dangerous`	Can destroy data or change the system.
`unknown`	Not recognised.

Classification is fail-closed: anything not recognised is unknown and treated with caution, never assumed safe.

Modes

Mode	Behaviour
`ask`	Asks before anything that isn’t safe.
`acceptEdits`	File edits are accepted automatically; other actions still ask.
`plan`	The agent plans but doesn’t change anything.
`yolo`	Everything is allowed.

Rule precedence

deny > ask > allow. A deny rule always wins, then ask, then allow. Protected paths stay protected whatever the mode.