Tools & safety

The model picks its own tools; you approve the mutating ones according to your autonomy tier. /tools lists what is available right now, which changes with the mode and with which capabilities you have turned on.

Nothing is written without you100×30 · 0:16

The default tier shows the diff and waits: y allows once, a always allows this tool, n declines.

When it needs a decision100×30 · 0:16

ask_user opens a dropdown in the middle of the screen — the answer goes where the question is.

Every tool it can call100×30 · 0:06

/tools lists what is wired in right now, including anything from your koda.toml.

The tools

Tool	Approval	What it does
read_file	—	Numbered lines. offset/limit for large files. Reads PDFs, Word, Excel and CSV too.
list_dir	—	Directory entries, gitignore-aware. depth > 1 recurses.
find_files	—	Glob, e.g. **/*.rs. Gitignore-aware.
search	—	Regex over file contents; returns path:line:text.
codegraph	—	Where a symbol is defined and who uses it.
skill	—	Load a project convention on demand.
todo	—	The plan you see above the input, kept current as steps finish.
remember	—	Record a durable project fact, or forget one that turned out wrong.
delegate	—	Hand a read-only investigation to a subagent with its own context.
ask_user	—	Ask you a question mid-task, answered in a centred dialog.
web_search	—	SearXNG or DuckDuckGo. Off by default.
web_fetch	—	GET a URL and read it as text. Off by default.
browse	—	Open a URL in a real browser and read it after JavaScript runs. Off by default.
debug	●	Run a program under a real debugger.
manage_skill	●	Write a procedure it worked out as a skill. With role, a delegatable agent.
manage_agent	●	Create, update or delete a role agent on the fly.
write_file	●	Create or overwrite a file. Parent directories are created.
edit_file	●	Replace an exact substring. replace_all for every occurrence.
run_command	●	Run a shell command in the workspace. Returns exit code, stdout, stderr.

● means it asks before acting, unless your autonomy tier says otherwise.

The file tools run in-process. There is no sh -c cat behind read_file, so they are fast, and they cannot be talked into doing something a shell would.

The safety model

Every write shows a diff first. A unified diff before it is applied, and again after. You are approving a specific change, not a promise to change something.

Every command asks. y approves once, a approves this tool for the session, n denies and tells the model to ask you what to do instead. A denial produces a question, not a retry loop.

The sandbox is on by default. sandbox = true confines the file tools to the workspace root, symlinks out of it included. --no-sandbox lifts that when you genuinely want to read across projects.

Destructive commands are re-confirmed. confirm_destructive = true stops for irreversible shell commands even when auto-approval is on.

PLAN mode removes rather than denies. The write and command tools are not offered to the model at all, so it plans instead of proposing edits it cannot make.

Reading a stopped program is a read. In the debugger, stack_trace, variables, evaluate and output do not stop to ask. launch, continue and stepping do, like any other command.

Where it is not safe

-y / --yolo skips approvals entirely.

Danger

This is genuinely dangerous with a model that can hallucinate rm -rf. Run it in a git repository with a clean tree, or in a container. Nowhere else.

Headless mode (-p) has nobody to ask, so a write or command without --yolo is denied and koda exits with status 2. That is the safe failure, and it is deliberate.

Treat anything fetched from the web as untrusted input. web_fetch and browse turn a model-supplied URL into a request from your machine, which is why both are opt-in.

Limits that stop a runaway turn

Setting	Default	What it bounds
max_steps	24	Model↔tool round trips in one turn before the step check runs.
step_check	true	At max_steps, ask the model whether work remains rather than stopping flat.
max_steps_hard	96	The absolute ceiling once step_check starts extending the budget.
command_timeout_ms	120000	How long a single command may run.
max_file_bytes	262144	How much of a file one read returns; also caps attached images.
max_tool_output_bytes	24576	How much of a tool’s output reaches the model.
max_subagent_depth	1	How deep delegation may nest. 1 means subagents cannot delegate.

Custom tools count as commands

A [[tools]] entry in your config becomes a tool the model can call, and it runs through exactly the same approval and shell path as run_command — see Custom tools. They are offered only to the top-level agent, and never in plan mode.