Tools & clearances

Tools are ka’s Hands: a registry trait the engine acts through. Every hand declares a clearance tier (read, write, or exec) which the permission gate enforces before any call runs. Every hand also carries annotations (read_only, idempotent) that permissions and output filtering consume.

The core hands

Tool	Clearance	Notes
read	read	Line/range selectors, image support (default cap 5 MB via [tools.read] max_image_mb); mints ledger entries
edit	write	Exact old→new match, must be unique; refuses unread or changed-since-read files
write	write	Refuses overwrite-without-read; a shebang earns +x
bash	exec	Timeouts, output caps, process-tree kill, spill for oversized output; auto-backgrounds long runs (default 30 s) into a jobs handle
glob	read	Gitignore-aware, bounded results
grep	read	Rust regex syntax only; errors teach the rewrite (no backreferences)
ask	none	Asks you a question; the TUI renders it, headless emits an Ask event and waits

The extended hands

Tool	Clearance	Notes
pathfinder	read	Read-only research subagent: a nested voice with inspect-only tools that returns a dense summary that keeps exploration out of your main context
delegate	exec	Runs a markdown agent as a subagent, optionally in an isolated git worktree (isolate: true frontmatter)
web_search	read	Tavily / Brave / Bing (configured under [[search]])
web_fetch	read	HTML→text with SSRF guards ([tools.web] allow_private_hosts is off by default)
todo	write	The live plan, mirrored into the TUI; items carry an optional confidence 0-100 (see the harness loop)
jobs	exec	Detached, auto-backgrounded bash processes that survive ka exiting
git	read	Read-only repo snapshot for context (branch, status); ka never mutates git unless you enable [git] auto_commit
snapshots	write	File undo journal behind /undo
tasks	read	Roster over background delegate work: list/read/cancel (read), send steers a running agent and merge applies an isolated task’s worktree branch (write)
secrets	none	Powers the one-way secret redaction applied to every tool result
bashp	none	Bash decomposition/hardstop analysis surfaced as a tool

MCP server tools join the same registry as <server>.<tool> at exec-tier clearance: the gate, rules, and snapshots treat them like any external execution.

Language-server hands ([lsp])

With [lsp] enable = true, four read-tier hands join: symbols (workspace symbol search), definition / references (IDE-style navigation), and diagnostics (project-wide or per-file findings). One stdio server spawns per configured [lsp.commands] language, eagerly, so navigation works before the first edit. The server’s latest diagnostics are also appended to successful edit/write results as informational context (never tool errors).

With [lsp] write_through = true, three write-tier hands join: lsp_rename (renames a symbol in one call, or moves a file with each server’s ripple edits), lsp_actions (lists and runs code actions), and lsp_format (formats a file). Server-proposed edits never bypass ka’s write path: the read ledger, snapshots (/undo covers them), size caps, and protected-path rules all apply.

The debug hand ([debug])

With [debug] enable = true, the debug hand drives a debug adapter over DAP: launch or attach a program, set breakpoints, step, and inspect threads, stack, variables, and expressions. gdb, lldb-dap, debugpy, dlv, and netcoredbg are seeded; [debug.adapters] adds or overrides entries. Control-flow actions run at exec clearance, inspection actions read. The debug console stays external (runInTerminal is refused), sessions are capped and reaped when idle or dead, and the /debug overlay in the TUI shows live sessions with their breakpoints and console tail.

Output handling

Every tool result flows through the same pipe: byte caps (default 32 KB tail / 8 KB head, line-capped) with oversized output parked to disk as spill://<id> and referenced by pointer. This happens before any model involvement; a chatty bash run cannot blow the context window.

Tool settings

[tools.bash]
background_after_ms = 30000   # auto-background threshold; 0 = never

[tools.read]
max_image_mb = 5              # 0 = unlimited

[tools.web]
allow_private_hosts = false   # SSRF guard for web_fetch