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.edit

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: { "file.edit": { 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

# 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

# lsp.diagnostics

Get errors, warnings, and hints for a file or directory. Language is auto-detected from file extension. Spawns the language server on first call if needed.

Field Type Required Default Description
path string yes — File or directory path. For directories, returns diagnostics for all files of the detected language.
severity "error" | "warning" | "information" | "hint" | "all" no — Filter by severity. Default: "all".

Enable/disable in project.yaml: tool_overrides: { "lsp.diagnostics": { enabled: true } }

Requires read-only filesystem access

# lsp.definition

Jump to the definition of a symbol. Returns file, line, and a preview of the definition.

Field Type Required Default Description
path string yes — File path.
line integer yes — Line number (1-indexed). [min: 1]
character integer yes — Column (0-indexed). [min: 0]

Enable/disable in project.yaml: tool_overrides: { "lsp.definition": { enabled: true } }

Requires read-only filesystem access

# lsp.references

Find all usages of a symbol across the workspace. References outside the caller's cage are included with path only (no preview).

Field Type Required Default Description
path string yes — File path.
line integer yes — Line number (1-indexed). [min: 1]
character integer yes — Column (0-indexed). [min: 0]
include_declaration boolean no — Include the declaration itself. Default: false.

Enable/disable in project.yaml: tool_overrides: { "lsp.references": { enabled: true } }

Requires read-only filesystem access

# lsp.symbols

Get symbols from a file (document outline) or search across the workspace.

Field Type Required Default Description
path string yes — File path (required even for workspace scope, for LSP context).
scope "document" | "workspace" no — "document" (file outline) or "workspace" (project-wide search). Default: "document".
query string no — Symbol name to search. Required for workspace scope.
limit integer no — Max results. Default: 50. [min: 1]

Enable/disable in project.yaml: tool_overrides: { "lsp.symbols": { enabled: true } }

Requires read-only filesystem access

# lsp.rename

Rename a symbol across the workspace. All edits are applied atomically. If any file falls outside the caller's cage, the rename is rejected.

Field Type Required Default Description
path string yes — File path.
line integer yes — Line number (1-indexed). [min: 1]
character integer yes — Column (0-indexed). [min: 0]
new_name string yes — New symbol name.

Enable/disable in project.yaml: tool_overrides: { "lsp.rename": { enabled: true } }

Requires read-write filesystem access

# lsp.actions

Get available code actions (quick fixes, refactors) for a location. Actions are informational — the agent decides whether to apply them via file.edit.

Field Type Required Default Description
path string yes — File path.
line integer yes — Line number (1-indexed). [min: 1]
character integer yes — Column (0-indexed). [min: 0]
diagnostics boolean no — Include diagnostic-associated actions. Default: true.

Enable/disable in project.yaml: tool_overrides: { "lsp.actions": { enabled: true } }

Requires read-only filesystem access

# lsp.hover

Get hover information (type info, documentation) for a symbol.

Field Type Required Default Description
path string yes — File path.
line integer yes — Line number (1-indexed). [min: 1]
character integer yes — Column (0-indexed). [min: 0]

Enable/disable in project.yaml: tool_overrides: { "lsp.hover": { enabled: true } }

Requires read-only filesystem access

# dap.launch

Start a program under the debugger. Creates a debug session scoped to the current kaged run. At most one active debug session per agent.

Field Type Required Default Description
runtime string yes — Runtime identifier ("bun", "node", "python", "go", etc.).
script string yes — Project-relative path to the entry point.
args string[] no — Arguments to the program.
env object no — Environment variables (merged with cage env).
stop_on_entry boolean no — Pause on first line. Default: true.
cwd string no — Working directory (project-relative). Default: project root.

Enable/disable in project.yaml: tool_overrides: { "dap.launch": { enabled: true } }

Requires read-only filesystem access

Requires capability: exec

# dap.attach

Attach the debugger to a running process via its debug port.

Field Type Required Default Description
runtime string yes — Runtime identifier.
port integer yes — Debug port.
host string no — Host to connect to. Default: "localhost".

Enable/disable in project.yaml: tool_overrides: { "dap.attach": { enabled: true } }

Requires capability: exec

# dap.breakpoint

Set, remove, or list breakpoints. Supports conditional breakpoints, hit counts, and logpoints.

Field Type Required Default Description
action "set" | "remove" | "list" yes — Breakpoint action.
path string no — File path. Required for set and remove.
line integer no — Line number. Required for set and remove. [min: 1]
condition string no — Conditional expression (only break when true).
hit_count integer no — Break after N hits. [min: 1]
log_message string no — Log message instead of breaking (logpoint).

Enable/disable in project.yaml: tool_overrides: { "dap.breakpoint": { enabled: true } }

# dap.step

Step through code: into, over, or out of the current function.

Field Type Required Default Description
action "into" | "over" | "out" yes — Step direction.
thread_id integer no — Thread to step. Default: current/main thread.

Enable/disable in project.yaml: tool_overrides: { "dap.step": { enabled: true } }

# dap.continue

Continue execution until the next breakpoint or program exit.

Field Type Required Default Description
thread_id integer no — Thread to continue. Default: all threads.

Enable/disable in project.yaml: tool_overrides: { "dap.continue": { enabled: true } }

# dap.stack

Get the call stack at the current pause point.

Field Type Required Default Description
thread_id integer no — Thread ID. Default: current thread.
levels integer no — Max stack frames to return. Default: 20. [min: 1]

Enable/disable in project.yaml: tool_overrides: { "dap.stack": { enabled: true } }

# dap.variables

Inspect variables in the current scope. Supports expanding nested properties.

Field Type Required Default Description
frame_id integer no — Stack frame to inspect. Default: top frame (0).
scope "local" | "closure" | "global" no — Variable scope. Default: "local".
filter string no — Variable name filter (substring match).
expand string no — Variable name to expand (show nested properties).

Enable/disable in project.yaml: tool_overrides: { "dap.variables": { enabled: true } }

# dap.evaluate

Evaluate an expression in the current debug context. Prefer "watch" context for side-effect-free inspection.

Field Type Required Default Description
expression string yes — Expression to evaluate.
frame_id integer no — Stack frame context. Default: top frame.
context "watch" | "repl" no — "watch" (side-effect-free) or "repl" (may have side effects). Default: "watch".

Enable/disable in project.yaml: tool_overrides: { "dap.evaluate": { enabled: true } }

# dap.disconnect

End the debug session. Optionally terminates the debugged program.

Field Type Required Default Description
terminate_debuggee boolean no — Kill the debugged program. Default: true.

Enable/disable in project.yaml: tool_overrides: { "dap.disconnect": { enabled: true } }

# 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.list

List issues in the current project. Returns summaries with number, title, status, assignment, and timestamps. Use status filter to find open, triaged, or in-progress issues.

Field Type Required Default Description
status "open" | "triaged" | "assigned" | "in_progress" | "resolved" | "rejected" | "reopened" no — Filter by status. Omit for all.
limit integer no — Max results. Default: 25. Max: 100.
cursor string no — Pagination cursor from a previous response.

Enable/disable in project.yaml: tool_overrides: { "kaged.issue.list": { enabled: true } }

Restricted to root agent only (principal_scope: root-only)

# kaged.issue.get

Get full detail of a single issue by project-scoped number, including its update stream (comments, status changes).

Field Type Required Default Description
number integer yes — Project-scoped issue number (e.g. 42 for #42).

Enable/disable in project.yaml: tool_overrides: { "kaged.issue.get": { enabled: true } }

Restricted to root agent only (principal_scope: root-only)

# kaged.issue.create

File a new issue in the current project. Returns the auto-assigned issue number. The agent is recorded as the author.

Field Type Required Default Description
title string yes — Issue title. Max 200 characters.
body string yes — Issue body in Markdown. Max 16 KB.

Enable/disable in project.yaml: tool_overrides: { "kaged.issue.create": { enabled: true } }

Restricted to root agent only (principal_scope: root-only)

# kaged.issue.comment

Add a comment to an issue. Comments are additive only — the agent cannot edit or delete existing comments or issue content.

Field Type Required Default Description
number integer yes — Project-scoped issue number.
body string yes — Comment text in Markdown. Max 16 KB.
visibility "all" | "operator_only" no — Who can see the comment. Default: all.

Enable/disable in project.yaml: tool_overrides: { "kaged.issue.comment": { enabled: true } }

Restricted to root agent only (principal_scope: root-only)

# kaged.issue.transition

Change an issue's status. Enforces the status lifecycle — invalid transitions are rejected. A comment is always required when resolving or rejecting an issue.

Field Type Required Default Description
number integer yes — Project-scoped issue number.
to "triaged" | "assigned" | "in_progress" | "resolved" | "rejected" | "reopened" yes — Target status.
comment string no — Comment attached to the transition. Required for rejected and resolved.

Enable/disable in project.yaml: tool_overrides: { "kaged.issue.transition": { 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)