Tooling Reference
Complete reference for all built-in agent tools — parameters, requirements, and scope restrictions.
Tools are grouped by domain: file operations, search, code intelligence (LSP), debugger (DAP), and kaged-internal (checkpoint, issues, interaction).
Each tool can be enabled or disabled per-agent via tool_overrides in project.yaml. Tools marked root-only are rejected on subagents at both DSL parse time and dispatch time.
Parameters marked required must be provided by the agent. Optional parameters show their defaults where applicable.
file.read
Read a file or directory listing. Returns line-numbered content with offset/limit pagination. Binary files return metadata instead of content.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path |
string |
yes | — | Project-relative path to read. |
offset |
integer |
no | — |
Line number to start from (1-indexed). Default: 1.
[min: 1] |
limit |
integer |
no | — |
Max lines to return. Default: 2000.
[min: 1] |
Enable/disable in project.yaml: tool_overrides: { "file.read": { enabled: true } }
Requires read-only filesystem access
file.write
Write (create or overwrite) a file. Creates parent directories if needed. The agent must have read the file first before overwriting.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path |
string |
yes | — | Project-relative path. |
content |
string |
yes | — | Full file content. |
Enable/disable in project.yaml: tool_overrides: { "file.write": { enabled: true } }
Requires read-write filesystem access
file.create
Create a new file. Fails if the file already exists. Creates parent directories if needed.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path |
string |
yes | — | Project-relative path. |
content |
string |
yes | — | File content. |
Enable/disable in project.yaml: tool_overrides: { "file.create": { enabled: true } }
Requires read-write filesystem access
edit.text
Apply a targeted edit to a file using exact string matching. The agent must have read the file first.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path |
string |
yes | — | Project-relative path. |
old_string |
string |
yes | — | Exact text to find. |
new_string |
string |
yes | — | Replacement text. Must differ from old_string. |
replace_all |
boolean |
no | — | Replace all occurrences. Default: false. |
Enable/disable in project.yaml: tool_overrides: { "edit.text": { enabled: true } }
Requires read-write filesystem access
edit.ast
Apply AST-aware structural rewrite rules to source files using ast-grep. Dry-run by default — set dry_run to false to apply changes. Uses the same parser as search.ast for consistency.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
rewrites |
object |
yes | — | Map of ast-grep pattern string to replacement template. Keys are patterns with meta-variables ($VAR, $$); values are templates using the same variables. |
lang |
string |
no | — | Target language. Supported: typescript, javascript, tsx, python, rust, go, java, c, cpp, css, html, json, yaml, and others as ast-grep supports. Inferred from file extensions when omitted if all candidates share one language. |
path |
string |
no | — | Single file or directory to rewrite. Default: project root. |
glob |
string |
no | — | Optional glob filter within the search root. |
dry_run |
boolean |
no | — | When true (default), compute changes without writing files. |
max_replacements |
integer |
no | — |
Cap on replacement applications across all files. Default: unlimited.
[min: 1] |
max_files |
integer |
no | — |
Cap on distinct files that may be modified. Default: unlimited.
[min: 1] |
Enable/disable in project.yaml: tool_overrides: { "edit.ast": { enabled: true } }
Requires read-write filesystem access
search.grep
Search file contents using regular expressions. Supports file-pattern filtering and multiple output modes. Timeout: 60s, output cap: 256 KB.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
pattern |
string |
yes | — | Regex pattern. |
path |
string |
no | — | Directory to search. Default: project root. |
include |
string |
no | — | File glob filter (e.g. "*.ts", "*.{ts,tsx}"). |
output_mode |
"content" | "files_with_matches" | "count" |
no | — | "content" (matching lines), "files_with_matches" (paths only), "count" (match counts per file). Default: "files_with_matches". |
head_limit |
integer |
no | — |
Max results. Default: unlimited.
[min: 1] |
Enable/disable in project.yaml: tool_overrides: { "search.grep": { enabled: true } }
Requires read-only filesystem access
search.glob
Find files by name pattern. Results sorted by modification time (most recent first). Timeout: 60s, file limit: 100.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
pattern |
string |
yes | — | Glob pattern. |
path |
string |
no | — | Directory to search. Default: project root. |
Enable/disable in project.yaml: tool_overrides: { "search.glob": { enabled: true } }
Requires read-only filesystem access
search.ast
Search code using AST-aware pattern matching via ast-grep. Patterns must be complete AST nodes. Use meta-variables: $VAR (single node), $$$ (multiple nodes).
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
pattern |
string |
yes | — | AST pattern with meta-variables. Must be a complete AST node. |
lang |
"typescript" | "javascript" | "tsx" | "python" | "rust" | "go" | "java" | "c" | "cpp" | "css" | "html" | "json" | "yaml" |
yes | — | Target language. |
paths |
string[] |
no | — | Directories to search. Default: project root. |
globs |
string[] |
no | — | Include/exclude globs. Prefix ! to exclude. |
context |
integer |
no | — |
Context lines around match. Default: 0.
[min: 0] |
Enable/disable in project.yaml: tool_overrides: { "search.ast": { enabled: true } }
Requires read-only filesystem access
code.lsp
Query code intelligence via the Language Server Protocol. Supports diagnostics, go-to-definition, find-references, symbols (document and workspace), rename, code actions (quick fixes and refactors), and hover information. Language is auto-detected from file extension. Spawns the language server on first call if needed.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
action |
"diagnostics" | "definition" | "references" | "symbols" | "rename" | "rename_file" | "code_actions" | "hover" | "type_definition" | "implementation" | "status" | "reload" | "capabilities" | "request" |
yes | — | LSP operation to perform. diagnostics: get errors, warnings, and hints for a file or directory. definition: jump to the definition of a symbol. references: find all usages of a symbol across the workspace. symbols: get symbols from a file (document) or search across the workspace. rename: rename a symbol across the workspace (atomic, all-or-nothing). rename_file: rename a file and update all references. code_actions: get available quick fixes and refactors for a location. hover: get type info and documentation for a symbol. type_definition: jump to the type definition of a symbol. implementation: find all implementations of an interface or abstract class. status: get language server status (alive, capabilities). reload: reload the language server or workspace. capabilities: get the language server's supported capabilities. request: send an arbitrary LSP request (advanced). |
path |
string |
no | — | File or directory path. Required for all actions. For diagnostics on directories, returns diagnostics for all files of the detected language. |
line |
integer |
no | — |
Line number (1-indexed). Required for definition, references, rename, code_actions, hover.
[min: 1] |
character |
integer |
no | — |
Column (0-indexed). Required for definition, references, rename, code_actions, hover.
[min: 0] |
severity |
"error" | "warning" | "information" | "hint" | "all" |
no | — | Filter by severity. Default: "all". Used with diagnostics. |
include_declaration |
boolean |
no | — | Include the declaration itself. Default: false. Used with references. |
scope |
"document" | "workspace" |
no | — | "document" (file outline) or "workspace" (project-wide search). Default: "document". Used with symbols. |
query |
string |
no | — | Symbol name to search. Required for symbols with workspace scope. |
limit |
integer |
no | — |
Max results. Default: 50. Used with symbols.
[min: 1] |
new_name |
string |
no | — | New symbol name (for rename) or destination path (for rename_file). Required for rename and rename_file. |
include_diagnostics |
boolean |
no | — | Include diagnostic-associated actions. Default: true. Used with code_actions. |
payload |
string |
no | — | JSON-encoded request parameters. Required for request. Used with the request action to send arbitrary LSP messages. |
Enable/disable in project.yaml: tool_overrides: { "code.lsp": { enabled: true } }
Requires read-write filesystem access
debug
Drive a debug session via the Debug Adapter Protocol. Supports launching programs, attaching to running processes, breakpoints (including conditional and logpoints), stepping, stack inspection, variable inspection, expression evaluation, and session teardown. At most one active debug session per agent.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
action |
"launch" | "attach" | "set_breakpoint" | "remove_breakpoint" | "list_breakpoints" | "set_instruction_breakpoint" | "remove_instruction_breakpoint" | "data_breakpoint_info" | "set_data_breakpoint" | "remove_data_breakpoint" | "step_into" | "step_over" | "step_out" | "continue" | "pause" | "stack_trace" | "threads" | "scopes" | "variables" | "evaluate" | "disassemble" | "read_memory" | "write_memory" | "modules" | "loaded_sources" | "custom_request" | "disconnect" |
yes | — | Debug operation to perform. launch: start a program under the debugger. attach: connect to a running process via its debug port. set_breakpoint: add a breakpoint (requires path, line, or function). remove_breakpoint: remove a breakpoint (requires path, line, or function). list_breakpoints: list all active breakpoints. set_instruction_breakpoint: add an instruction-level breakpoint. remove_instruction_breakpoint: remove an instruction-level breakpoint. data_breakpoint_info: get info for a data breakpoint. set_data_breakpoint: set a data breakpoint. remove_data_breakpoint: remove a data breakpoint. step_into/step_over/step_out: step through code. continue: resume execution until next breakpoint or exit. pause: pause a running thread. stack_trace: get the call stack at the current pause point. threads: list all threads. scopes: list variable scopes for a frame. variables: inspect variables in the current scope. evaluate: evaluate an expression in the debug context. disassemble: disassemble memory into instructions. read_memory: read bytes from memory. write_memory: write bytes to memory. modules: list loaded modules. loaded_sources: list all loaded source files. custom_request: send an arbitrary DAP command. disconnect: end the debug session. |
runtime |
string |
no | — | Runtime identifier ("bun", "node", "python", "go", etc.). Required for launch and attach. |
script |
string |
no | — | Project-relative path to the entry point. Required for launch. |
args |
string[] |
no | — | Arguments to the program. Used with launch. |
env |
object |
no | — | Environment variables (merged with cage env). Used with launch. |
stop_on_entry |
boolean |
no | — | Pause on first line. Default: true. Used with launch. |
cwd |
string |
no | — | Working directory (project-relative). Default: project root. Used with launch. |
port |
integer |
no | — | Debug port. Required for attach. |
host |
string |
no | — | Host to connect to. Default: "localhost". Used with attach. |
path |
string |
no | — | File path. Required for set_breakpoint and remove_breakpoint. |
line |
integer |
no | — |
Line number. Required for set_breakpoint and remove_breakpoint.
[min: 1] |
condition |
string |
no | — | Conditional expression (only break when true). Used with set_breakpoint. |
hit_count |
integer |
no | — |
Break after N hits. Used with set_breakpoint.
[min: 1] |
log_message |
string |
no | — | Log message instead of breaking (logpoint). Used with set_breakpoint. |
thread_id |
integer |
no | — | Thread to operate on. Default: current/main thread. Used with step_into, step_over, step_out, continue, pause, stack_trace. |
levels |
integer |
no | — |
Max stack frames to return. Default: 20. Used with stack_trace.
[min: 1] |
frame_id |
integer |
no | — | Stack frame to inspect. Default: top frame (0). Used with variables, scopes, and evaluate. |
scope |
"local" | "closure" | "global" |
no | — | Variable scope. Default: "local". Used with variables. |
filter |
string |
no | — | Variable name filter (substring match). Used with variables. |
expand |
string |
no | — | Variable name to expand (show nested properties). Used with variables. |
expression |
string |
no | — | Expression to evaluate. Required for evaluate. |
context |
"watch" | "repl" |
no | — | "watch" (side-effect-free) or "repl" (may have side effects). Default: "watch". Used with evaluate. |
function |
string |
no | — | Function name for function breakpoints. Used with set_breakpoint and remove_breakpoint as an alternative to path+line. |
name |
string |
no | — | Variable or data name. Required for data_breakpoint_info. |
memory_reference |
string |
no | — | Memory reference or address. Required for read_memory and write_memory. Used with disassemble as fallback (current instruction pointer is used when omitted). |
instruction_reference |
string |
no | — | Instruction reference or address. Required for set/remove_instruction_breakpoint. |
instruction_count |
integer |
no | — | Number of instructions to disassemble. Required for disassemble. |
instruction_offset |
integer |
no | — | Offset from the instruction reference. Used with disassemble. |
count |
integer |
no | — | Bytes to read. Required for read_memory. |
data |
string |
no | — | Base64-encoded memory payload. Required for write_memory. |
data_id |
string |
no | — | Data breakpoint ID. Required for set/remove_data_breakpoint. |
access_type |
"read" | "write" | "readWrite" |
no | — | Access type for data breakpoints. Used with set_data_breakpoint. |
offset |
integer |
no | — | Byte offset. Used with read_memory and write_memory. |
resolve_symbols |
boolean |
no | — | Resolve symbol names in disassembly. Used with disassemble. |
allow_partial |
boolean |
no | — | Allow partial memory write. Used with write_memory. |
start_module |
integer |
no | — | Start index for module listing. Used with modules. |
module_count |
integer |
no | — | Max modules to return. Used with modules. |
command |
string |
no | — | Custom DAP request command. Required for custom_request. |
arguments |
object |
no | — | Custom DAP request arguments. Used with custom_request. |
terminate_debuggee |
boolean |
no | — | Kill the debugged program. Default: true. Used with disconnect. |
Enable/disable in project.yaml: tool_overrides: { "debug": { enabled: true } }
Requires read-only filesystem access
Requires capability: exec
shell.bash
Execute a shell command via /bin/sh -c through the PTY broker. Returns stdout (merged with stderr via PTY), exit code, and timeout status. Non-zero exit codes are data, not errors.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
command |
string |
yes | — |
Shell command to execute. Passed to /bin/sh -c. Max 64 KB.
[max length: 65536] |
cwd |
string |
no | — | Working directory, relative to project root. Default: project root. Must resolve within the project tree. |
timeout |
integer |
no | — |
Maximum execution time in milliseconds. Default: 120000 (2 minutes). Clamped to [1000, 600000].
[min: 1000, max: 600000] |
env |
object |
no | — | Additional environment variables merged into the process environment. Keys must be non-empty strings; values must be strings. Max 64 entries. |
Enable/disable in project.yaml: tool_overrides: { "shell.bash": { enabled: true } }
Requires read-write filesystem access
Requires capability: shell
compute.calc
Evaluate one or more mathematical expressions. Supports decimal, hex (0xFF), binary (0b1010), octal (0o755), and scientific notation (1e10). Operators: +, -, *, /, %, ** (exponentiation). Parentheses and unary +/- are supported. Exponentiation is right-associative: 2**3**2 = 512.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
calculations |
object[] |
yes | — | Array of calculations to evaluate. Each entry has an expression, and optional prefix/suffix text for formatting the output. |
Enable/disable in project.yaml: tool_overrides: { "compute.calc": { enabled: true } }
project.recipe
Auto-detect project build runners (npm, bun, cargo, poetry, pdm, uv, make) and execute common project tasks. Resolves a simple 'op' to the appropriate command for the detected runner and delegates execution to shell.bash. The response includes 'available_tasks' so the model can discover what operations are supported.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
op |
string |
yes | — | The operation to run (e.g., 'test', 'build --release'). Matched against each detected runner's task list. |
cwd |
string |
no | — | Working directory, relative to project root. Default: project root. Must resolve within the project tree. |
Enable/disable in project.yaml: tool_overrides: { "project.recipe": { enabled: true } }
Requires read-write filesystem access
Requires capability: shell
kaged.checkpoint
Pause execution and yield control to the operator. Call this when you need human review, approval, or input before proceeding. After calling this tool, produce a brief summary of your current state and stop.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
reason |
string |
no | — | Why the checkpoint is needed. Shown to the operator in the UI. |
Enable/disable in project.yaml: tool_overrides: { "kaged.checkpoint": { enabled: true } }
kaged.issue
Manage project issues — list, view, create, comment, and transition status. Supports the full issue lifecycle: filing, triage, assignment, resolution, and reopening. Comments are additive only — the agent cannot edit or delete existing comments or issue content.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
action |
"list" | "get" | "create" | "comment" | "transition" |
yes | — | Issue operation to perform. list: list issues with optional status filter and pagination. get: get full detail of a single issue including its update stream. create: file a new issue (agent is recorded as author). comment: add a comment to an existing issue. transition: change an issue's status (enforces lifecycle rules). |
status |
"open" | "triaged" | "assigned" | "in_progress" | "resolved" | "rejected" | "reopened" |
no | — | Filter by status. Omit for all. Used with list. |
limit |
integer |
no | — | Max results. Default: 25. Max: 100. Used with list. |
cursor |
string |
no | — | Pagination cursor from a previous response. Used with list. |
number |
integer |
no | — | Project-scoped issue number (e.g. 42 for #42). Required for get, comment, and transition. |
title |
string |
no | — | Issue title. Max 200 characters. Required for create. |
body |
string |
no | — | Issue body (for create) or comment text (for comment) in Markdown. Max 16 KB. Required for create and comment. |
visibility |
"all" | "operator_only" |
no | — | Who can see the comment. Default: all. Used with comment. |
to |
"triaged" | "assigned" | "in_progress" | "resolved" | "rejected" | "reopened" |
no | — | Target status. Required for transition. |
comment |
string |
no | — | Comment attached to the transition. Required for resolved and rejected. Used with transition. |
Enable/disable in project.yaml: tool_overrides: { "kaged.issue": { enabled: true } }
Restricted to root agent only (principal_scope: root-only)
kaged.todo
Manage the working checklist on the session's bound issue. Tasks are addressed by their text content. At most one task is in_progress at a time — the tool enforces this invariant. Requires a bound issue; errors if the session has none.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
action |
"view" | "set" | "add" | "start" | "done" | "drop" | "note" |
yes | — | Todo operation to perform. view: return the current list. set: replace the working list (init); accepts items and optional phase. add: append task(s) to a phase. start: mark a task in_progress (enforces single in_progress). done: mark a task completed. drop: mark a task abandoned (not deleted). note: append a note to a task. |
content |
string |
no | — | Target task, addressed by text content. Required for start, done, drop, note. |
items |
string[] |
no | — | Task contents for set/add. |
phase |
string |
no | — | Optional work-stage grouping for set/add. |
kind |
"step" | "criterion" |
no | — | Task kind. Default: "step". Used with set/add. |
text |
string |
no | — | Note body. Required for note. |
Enable/disable in project.yaml: tool_overrides: { "kaged.todo": { enabled: true } }
Restricted to root agent only (principal_scope: root-only)
kaged.ask
Ask the operator one or more structured questions. Each question has a title, description, and a set of predefined options with labels and descriptions. Questions can be single-select or multi-select. The session pauses until the operator responds. Use this when you need operator decisions, preferences, or direction before proceeding.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
summary |
string |
yes | — | Brief context explaining why you are asking. Shown above the questions. |
questions |
object[] |
yes | — | One or more questions to present to the operator. |
Enable/disable in project.yaml: tool_overrides: { "kaged.ask": { enabled: true } }
Restricted to root agent only (principal_scope: root-only)
kaged.form
Request structured data from the operator via a dynamic form. Each field has a name, label, type, and required flag. Supported types: text, textarea, url, number, boolean, file. File uploads are stored at config:/tmp/ and the path is returned. The session pauses until the operator submits the form. Use this when a workflow or task needs specific input data.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
summary |
string |
yes | — | Brief context explaining what data is needed and why. |
fields |
object[] |
yes | — | Form fields to present to the operator. |
Enable/disable in project.yaml: tool_overrides: { "kaged.form": { enabled: true } }
Restricted to root agent only (principal_scope: root-only)