Spec: Agent Tooling

• Status: Draft
• Last amended: 2026-06-16 (web.search tool — ADR-0033 web namespace activation)
• Constrained by: ADR-0004, ADR-0008, ADR-0009, ADR-0010, ADR-0011, ADR-0022, ADR-0033, ADR-0034, ADR-0043
• Implements: packages/agent-tooling/, packages/natives/, daemon tool handlers in packages/daemon/src/runtime/tool-handlers/

Purpose

This spec defines the agent tooling layer: the daemon subsystem that provides tools to the primary agent and subagents for interacting with the project workspace. It owns the tool registry, tool dispatch, and the concrete implementations of built-in tools across three domains:

1. File & search tools — read, write, create, find, grep, and AST-aware structural operations on source files. Content editing via exact-string replacement (edit.text). Adopted from oh-my-pi's Rust implementations for speed.
2. Code intelligence (code.lsp) — diagnostics, go-to-definition, find-references, symbols, rename, and code actions via the Language Server Protocol. A single code.lsp tool with action-based dispatch. LSP is a first-class citizen alongside linters, not an afterthought.
3. Debugger (debug) — breakpoints, stepping, stack inspection, variable evaluation, and conditional watches via the Debug Adapter Protocol. A single debug tool with action-based dispatch. Real debugging — not console.log.

This document is normative for:

• The tool registry — how tools are declared, discovered, and versioned.
• The tool dispatch protocol — how agents request tools and receive results within the session's run model.
• The built-in tool catalog — every tool's name, parameters, return shape, and behavior.
• The LSP bridge — how language servers are spawned, multiplexed, and exposed as actions of the code.lsp tool.
• The DAP bridge — how debug adapters are spawned, session-scoped, and exposed as actions of the debug tool.
• The file tool implementations — which oh-my-pi tools are adopted, which are adapted, and which are built fresh.
• The sandbox integration — how tools interact with cage policies, seccomp profiles, and filesystem allowlists.

It is not normative for:

• The session manager's run model or tool_calls table schema (that's session-manager.md).
• The sandbox mechanism itself (that's sandbox.md).
• The plugin host's tool-exposure mechanism (that's plugin-host.md — plugins expose their own methods; this spec covers built-in daemon tools).
• The WebSocket framing of tool calls/results (that's http-api.md).
• The task runner (that's task-runner.md — operator-initiated project tasks, not agent-callable tools).

Constraints (from ADRs)

Architecture

Why built-in, not plugin-provided

Three factors push these tools into the daemon core rather than the plugin boundary:

1. Performance. File reads, searches, and edits are the most frequently called tools in any coding session. Every call through the plugin JSON-RPC boundary pays serialization, IPC, and process-switch costs. Built-in tools eliminate this.
2. Sandbox mediation. Caged subagents cannot touch the host filesystem directly. The daemon must broker every file operation against the cage's fs allowlist. Built-in tools enforce this at the call site — no capability-overreach possible.
3. Seccomp constraints. DAP requires ptrace (blocked by default seccomp). Plugins are locked to default seccomp with no relaxed option (plugin-host.md). LSP servers need to execute arbitrary compilers/interpreters. Neither fits the plugin sandbox model.

Component layout

                   ┌──────────────────────────────────────┐
                   │          Session Manager             │
                   │  (dispatches tool calls from runs)   │
                   └──────────────┬───────────────────────┘
                                  │ tool_call(name, params, caller_context)
                                  ▼
                   ┌──────────────────────────────────────┐
                   │          ToolRegistry                │
                   │  built-in tools + plugin-declared    │
                   │  tools, unified dispatch             │
                   └───┬──────────┬──────────┬────────────┘
                       │          │          │
              ┌────────▼──┐  ┌───▼────┐  ┌──▼──────────┐
              │ FileTools  │  │  LSP   │  │    DAP      │
              │ (Rust FFI) │  │ Bridge │  │   Bridge    │
              └────────────┘  └───┬────┘  └──┬──────────┘
                                  │          │
                            ┌─────▼──┐  ┌───▼──────────┐
                            │LS Pool │  │ DA Pool      │
                            │(per-   │  │(per-session  │
                            │project)│  │ per-runtime) │
                            └────────┘  └──────────────┘

Five subsystems in packages/agent-tooling/:

• ToolRegistry — the catalog of all available tools (built-in and plugin-declared). Resolves tool names, validates parameters, enforces per-caller permissions, dispatches calls.
• FileTools — file read/write/edit, search (grep, glob), and AST-aware operations. Rust implementations called via Bun FFI.
• LSPBridge — spawns and manages language server processes, translates agent tool calls into LSP JSON-RPC, returns structured results.
• DAPBridge — spawns and manages debug adapter processes, translates agent tool calls into DAP JSON messages, manages debug sessions.
• ToolPermissions — enforces cage-derived access control on every tool call. A subagent in a cage with fs: [{mode: ro, path: ./src}] cannot call file.write on ./data/.

Tool registry

Registration

Tools are registered at daemon startup. Built-in tools are always present. Plugin-declared tools are registered when a plugin completes its initialize handshake (per plugin-host.md).

interface ToolDefinition {
  name: string;                    // dot-delimited, e.g. "file.read", "mcp.github.issue.create"
  namespace: "file" | "code" | "debug" | "search" | "shell" | "mcp" | string;  // grouping
  description: string;             // shown in tool-use prompts
  parameters: JSONSchema;          // input validation
  returns: JSONSchema;             // output shape documentation
  requires: ToolRequirement[];     // cage/permission prerequisites
  source: "builtin" | "plugin" | "mcp";
  plugin_name?: string;            // if source is "plugin"
  mcp_server?: string;             // if source is "mcp" — DSL key of the MCP server
  mcp_tool_name?: string;          // if source is "mcp" — tool name as the MCP server knows it
  principal_scope?: "root-only";   // if set, schema rejects this tool on non-root agents
}

Namespaces

Built-in namespace names (file, edit, search, code, debug, shell, compute, project, kaged, mcp) cannot be used by plugins. Per ADR-0033, additional namespaces (web, discover, media, job) are also reserved. Plugin methods follow the existing naming rules from plugin-host.md. The mcp namespace is reserved per ADR-0043 — built-in tools and plugins cannot claim it.

Tools carrying principal_scope: "root-only" are rejected by the DSL schema if an operator attempts to enable them on any non-root agent. See project-dsl.md § Tool resolution.

Dispatch

When the primary or a subagent emits a tool call:

1. Resolve. The registry looks up the tool by name. Unknown tool → error -32601 (tool_not_found).
2. Validate params. Input validated against the tool's parameters schema. Invalid → error -32602 (invalid_params).
3. Authorize. The ToolPermissions module checks the caller's cage policy against the tool's requires. Denied → error -32001 (capability_denied).
4. Execute. Dispatch to the owning subsystem: FileTools, LSPBridge, DAPBridge, plugin host, or MCP client proxy (for source: "mcp" tools).
5. Return. Result (or error) returned to the session manager, which records it in tool_calls and streams it to the WebSocket. For MCP tools, result size truncation is applied before return (see MCP result truncation).

Caller context

Every tool call carries the caller's identity and sandbox context:

interface ToolCallContext {
  session_id: string;
  run_id: string;
  caller: string;                  // tree-position path: "primary", "primary.subagents.scraper", etc.
  project_id: string;
  project_root: string;            // absolute host path
  cage_policy: CagePolicy | null;  // null for uncaged agents (cage: disabled)
  request_id: string;              // for audit correlation
}

The caller field encodes the agent's position in the AgentSpec tree (e.g. "primary", "primary.subagents.scraper", "primary.subagents.builder.subagents.linter"). This path is used for audit logging, tool resolution (root-only tools check caller === "primary"), and permission scoping.

The cage_policy is the effective policy the caller is running under. Tools use it to enforce access boundaries without consulting the sandbox directly — the policy is the single source of truth. Agents with cage: disabled have cage_policy: null.

Per-agent tool resolution

Per ADR-0022, tools are resolved per agent, not per project. There is no project-level tools: block. Each agent in the AgentSpec tree carries its own tools: override map (or omits it to accept defaults).

Resolution chain (evaluated once at session start, per agent):

1. Built-in registry. All built-in tools (file.*, edit.*, search.*, code.lsp, debug, kaged.issue.*, kaged.workflow.*), plugin-declared tools, and MCP-discovered tools (mcp.<server-key>.*) exist in the global registry. Existence in the registry does not mean availability — it means the tool can be enabled.

2. Role-based defaults. The root agent (the AgentSpec at ProjectDsl.primary) receives kaged.issue.* and kaged.workflow.* enabled by default. Every other agent in the tree starts with no tools enabled. The operator opts in per agent via the agent's tools: block.

3. Agent's tools: block. A Record<string, ToolOverride> on the AgentSpec. Each key is a tool name or glob pattern; the value is { enabled: true } or { enabled: false } (to suppress a role-based default). Glob patterns are expanded against the registry at resolution time.

4. principal_scope enforcement. Tools with principal_scope: "root-only" (currently kaged.issue.* and kaged.workflow.*) are rejected by the DSL parser if an operator attempts to enable them on any non-root agent. This is a schema-level rejection, not a runtime check — the project fails to load.

5. Cage filter at dispatch. Even after an agent's tool set is resolved, every tool call passes through ToolPermissions at dispatch time. A tool that is enabled but whose requires entries are not satisfied by the agent's cage is rejected with capability_denied. This is the runtime complement to the schema-level resolution.

Example resolution:

# Root agent — gets kaged.issue.* and kaged.workflow.* by default
primary:
  model: smart-generalist
  system_prompt: project:/prompts/primary.md
  cage: disabled
  # tools: omitted → role-based defaults only (kaged.issue.*, kaged.workflow.*)
  subagents:
    coder:
      model: smart-fast
      system_prompt: project:/prompts/coder.md
      cage:
        fs: [{ mode: rw, path: ./src }]
        net: { allow: [] }
        state: ephemeral
      tools:
        "file.*": { enabled: true }
        "search.*": { enabled: true }
        "lsp.*": { enabled: true }
        # kaged.issue.create: { enabled: true }  ← PARSE ERROR: root-only

In this example, the root agent can create/update issues and trigger workflows. The coder subagent can read/write files, search, and use LSP — but cannot touch issues or workflows. The coder's file.write calls are further constrained by its cage: writes outside ./src are rejected at dispatch time.

Synthetic agent-{key} tools. When the harness compiles the AgentSpec tree, each agent's direct children are registered as synthetic tools named agent-{key} on the parent (see agent.md). These synthetic tools do not appear in the tools: override map — they are always available to the parent. The operator controls the call graph by controlling the tree structure, not by toggling synthetic tools.

MCP tool source (ADR-0043)

MCP (Model Context Protocol) is a third tool source alongside built-in and plugin. MCP servers expose tools via a standardised protocol (tools/list, tools/call). The daemon acts as the MCP client — it discovers tools at runtime and proxies dispatch. Unlike plugins, MCP servers implement their own protocol; no kaged SDK is required.

Registration

At session-start, the daemon calls tools/list on each configured MCP server (per the project DSL's mcp: block). Each discovered tool is registered with:

• Name: mcp.<server-key>.<tool-name> — the mcp namespace is reserved (ADR-0033 amendment).
• Source: "mcp" — distinguishes from built-in and plugin tools.
• Parameters: from the MCP tool's inputSchema (JSON Schema).
• Description: from the MCP tool's metadata.

The tools.allow/deny filter patterns from the DSL's mcp.<server-key>.tools block are applied at registration time — only matching tools are registered. Registration failures (server unreachable, tools/list error) mark the server as failed; the session starts with other MCP servers active.

MCP tools are not root-only. Any agent can be granted MCP tools via its tools: block, subject to the standard per-agent resolution.

Dispatch

Agent calls mcp.github.issue.create → registry resolves source: "mcp" → daemon proxies to the MCP server's tools/call endpoint → result returned through the standard tool-result path (with size truncation applied).

The dispatch path for MCP tools:

1. Resolve — registry lookup (same as all tools).
2. Validate params — against the MCP tool's inputSchema (same as all tools).
3. Authorize — cage policy check. MCP tools have no requires entries (they are daemon-proxied, not cage-mediated). Authorization always passes.
4. Execute — the daemon's MCP client sends a tools/call JSON-RPC request to the MCP server. For stdio servers, this is stdin/stdout. For sse servers, this is HTTP POST.
5. Return — result is processed (truncation applied) and returned through the standard tool-result path.

MCP result truncation

MCP tool results can be arbitrarily large. The daemon enforces a configurable cap on all MCP tool results.

• Default: 64 KB (65,536 bytes).
• Configurable at: daemon operational config (config.toml), not per-server or per-tool. One knob for all MCP servers.
• Behaviour: Results exceeding the cap are truncated to the limit and appended with a truncation marker: \n[... truncated at 65536 bytes]. The tool result's truncated field is set to true.

MCP sampling rejection

MCP servers can request the client (kaged) to perform LLM sampling (sampling/createMessage). This is a fundamental trust boundary — allowing external code to trigger LLM calls means MCP servers can spend the operator's tokens and influence agent reasoning. The daemon rejects all sampling/createMessage requests from MCP servers with an error response. This is non-negotiable per ADR-0043.

What is explicitly NOT supported

• MCP resources — structured data exposed by MCP servers. Deferred to v2.
• MCP prompts — prompt templates. Deferred to v2.
• MCP server version pinning — min_version support. Not implemented.
• streamable-http transport — deferred to Phase 2.

See ADR-0043 for the full decision record and phasing.

File & search tools

Provenance

These tools are adopted from oh-my-pi's Rust implementations. oh-my-pi's file tools are battle-tested across millions of coding sessions. We adopt the Rust core and wrap it with kaged's permission layer.

Integration strategy

The Rust implementations are compiled as shared libraries (.so / .dylib) and loaded via bun:ffi. Each tool function is a synchronous or async FFI call that takes a path and parameters, returns structured JSON.

// Conceptual — actual FFI bindings in packages/agent-tooling/ffi/
import { dlopen, FFIType } from "bun:ffi";

const lib = dlopen("libkaged_filetools.so", {
  file_read: {
    args: [FFIType.ptr, FFIType.i32, FFIType.i32],  // path, offset, limit
    returns: FFIType.ptr,                             // JSON result
  },
  search_grep: {
    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr],   // pattern, path, include
    returns: FFIType.ptr,
  },
  // ...
});

If FFI proves fragile across platforms, the fallback is a compiled Rust sidecar binary (kaged-filetools) that the daemon communicates with over a Unix socket. The tool API shape is identical either way.

Tool: file.read

Read a file or directory listing.

Parameters:

{
  "path": "./src/main.ts",
  "offset": 1,
  "limit": 200
}

Returns:

{
  "path": "./src/main.ts",
  "type": "file",
  "content": "1: import { serve } from 'bun';\n2: ...",
  "total_lines": 42,
  "truncated": false
}

For directories, returns an entry listing (one per line, trailing / for subdirectories).

Permission: requires read:fs on the resolved path. Always allowed for the primary (no cage). For caged subagents, the path must fall inside an fs entry with mode ro or rw.

Behavior:

• Lines are prefixed with their line number (N: content).
• Lines longer than 2000 characters are truncated with a [truncated] marker.
• Binary files return {"type": "binary", "size": N, "mime": "..."} instead of content.
• If path does not exist, returns error file_not_found.
• Symlinks are resolved; the resolved path must still be within the cage's allowlist.

Tool: file.write

Write (create or overwrite) a file.

Parameters:

{
  "path": "./src/new-module.ts",
  "content": "export function greet() { ... }"
}

Returns:

{
  "path": "./src/new-module.ts",
  "bytes_written": 1234,
  "created": true
}

Permission: requires write:fs on the resolved path (cage fs entry with mode: rw). The primary can write anywhere in the project root.

Behavior:

• Creates parent directories if they don't exist.
• Overwrites existing files entirely — no merge.
• The agent MUST have read the file first (tracked by the tool registry) before overwriting. If the agent hasn't read the file, the tool returns error file_not_read with message "Read the file before overwriting it." This prevents blind overwrites.

Tool: edit.text

Apply a targeted edit to a file using exact string matching.

Parameters:

{
  "path": "./src/main.ts",
  "old_string": "const port = 3000;",
  "new_string": "const port = parseInt(process.env.PORT ?? '3000');",
  "replace_all": false
}

Returns:

{
  "path": "./src/main.ts",
  "replacements": 1
}

Permission: requires write:fs on the resolved path.

Behavior:

• old_string not found → error old_string_not_found.
• old_string found multiple times and replace_all is false → error multiple_matches with count.
• old_string == new_string → error no_change.
• Preserves file encoding (UTF-8) and line endings.
• The agent MUST have read the file first.

Tool: file.create

Create a new file. Fails if the file already exists.

Parameters:

{
  "path": "./src/utils/helpers.ts",
  "content": "export function clamp(n: number, min: number, max: number) { ... }"
}

Returns:

{
  "path": "./src/utils/helpers.ts",
  "bytes_written": 256,
  "created": true
}

Permission: requires write:fs on the resolved path.

Behavior:

• If file exists → error file_exists. Use file.write to overwrite.
• Creates parent directories if needed.

Tool: search.grep

Search file contents using regular expressions.

Parameters:

{
  "pattern": "TODO|FIXME",
  "path": "./src",
  "include": "*.ts",
  "output_mode": "content",
  "head_limit": 50
}

Returns:

{
  "matches": [
    { "file": "./src/main.ts", "line": 42, "content": "// TODO: handle errors" }
  ],
  "total_matches": 1,
  "truncated": false
}

Permission: requires read:fs on the search path. For caged subagents, results are filtered to only include files within the cage's readable mounts.

Behavior:

• Timeout: 60 seconds.
• Output cap: 256 KB. Truncated results include "truncated": true.
• Binary files are skipped.
• .gitignore patterns are respected by default.

Tool: search.glob

Find files by name pattern.

Parameters:

{
  "pattern": "**/*.test.ts",
  "path": "./src"
}

Returns:

{
  "files": ["./src/auth.test.ts", "./src/db.test.ts"],
  "count": 2,
  "truncated": false
}

Permission: requires read:fs on the search path.

Behavior:

• Timeout: 60 seconds.
• File limit: 100. Truncated results include "truncated": true.
• Results sorted by modification time (most recent first).
• .gitignore patterns respected.

Tool: search.ast

Search code using AST-aware pattern matching via ast-grep.

Parameters:

{
  "pattern": "console.log($MSG)",
  "lang": "typescript",
  "paths": ["./src"],
  "context": 2
}

Returns:

{
  "matches": [
    {
      "file": "./src/main.ts",
      "line": 15,
      "content": "console.log(\"server started\")",
      "meta_variables": { "MSG": "\"server started\"" },
      "context_before": ["  const server = serve({"],
      "context_after": ["  });"]
    }
  ],
  "count": 1
}

Permission: requires read:fs on the search paths.

Behavior:

• Patterns must be complete AST nodes (valid code fragments). Invalid patterns → error invalid_pattern.
• Meta-variables: $VAR matches a single node, $$$ matches multiple nodes.
• Uses the ast-grep Rust library via FFI.

Tool: edit.ast

Apply AST-aware structural rewrite rules to source files using ast-grep. Dry-run by default — agents must set dry_run: false to persist changes.

Parameters:

{
  "rewrites": { "console.log($MSG)": "logger.debug($MSG)" },
  "lang": "typescript",
  "path": "./src",
  "glob": "*.ts",
  "dry_run": true
}

Returns:

{
  "changes": [
    {
      "path": "./src/main.ts",
      "before": "console.log(\"server started\")",
      "after": "logger.debug(\"server started\")",
      "byte_start": 120,
      "byte_end": 150,
      "start_line": 15,
      "start_column": 8,
      "end_line": 15,
      "end_column": 45
    }
  ],
  "file_changes": [
    { "path": "./src/main.ts", "count": 1 }
  ],
  "total_replacements": 1,
  "files_touched": 1,
  "files_searched": 3,
  "applied": false,
  "limit_reached": false
}

Permission: requires write:fs on the resolved path when dry_run is false. Requires read:fs when dry_run is true.

Behavior:

• Dry-run by default ("applied": false). Agents must explicitly set dry_run: false to write changes to disk.
• When dry_run: true, the tool returns the full set of proposed replacements without modifying any files.
• When dry_run: false, the tool applies all non-overlapping edits and writes files back.
• Parse or pattern errors on individual files are collected and returned in parse_errors without failing the entire operation (unless the file is the only candidate).
• Invalid patterns (unparseable ast-grep syntax) → error invalid_pattern.
• Language inference failure (mixed extensions, unsupported extension) → error invalid_params with detail.
• Uses the ast-grep Rust library via FFI, sharing the same parser infrastructure as search.ast.

Code intelligence tool (code.lsp)

Design philosophy

LSP is a first-class citizen in kaged's agent tooling. Coding agents that can query diagnostics, navigate to definitions, and perform safe renames produce dramatically better code than agents that work blind.

The LSP bridge is not a passthrough — it translates LSP's chatty, stateful JSON-RPC protocol into discrete, stateless agent actions. An agent calls code.lsp with action: "diagnostics" and gets a clean result. The bridge manages the underlying language server lifecycle, initialization, file synchronization, and capability negotiation.

LSP bridge architecture

                ┌──────────────────────┐
                │    Agent (primary    │
                │    or subagent)      │
                └──────────┬───────────┘
                           │ code.lsp({ action: "diagnostics", path: "./src/main.ts" })
                           ▼
                ┌──────────────────────┐
                │     ToolRegistry     │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │     LSPBridge        │
                │  ┌────────────────┐  │
                │  │  ServerPool    │  │
                │  │                │  │
                │  │ ts-server ─────│──│──▶ typescript-language-server
                │  │ pyright  ──────│──│──▶ pyright-langserver
                │  │ rust-analyzer ─│──│──▶ rust-analyzer
                │  │ ...            │  │
                │  └────────────────┘  │
                │                      │
                │  ┌────────────────┐  │
                │  │  FileSync      │  │──── tracks open/changed files
                │  └────────────────┘  │     for textDocument/didOpen etc.
                └──────────────────────┘

Language server pool

The LSPBridge maintains a per-project pool of language servers. Servers are spawned on demand (first tool call for a given language in a project) and kept alive for the project's lifetime.

Server lifecycle:

1. Spawn. On first code.lsp call for a language, the bridge:
   • Resolves the language server binary from a configurable registry (see LSP server configuration).
   • Spawns the server as a child process of the daemon, outside any subagent cage (the daemon is the LSP client).
   • Performs the LSP initialize / initialized handshake.
   • Sends workspace/didOpen for files the agents have read so far.
2. Active. The server processes requests. File changes made by agents via file.write / edit.text trigger textDocument/didChange notifications.
3. Idle timeout. If no code.lsp call is made for 10 minutes, the server is sent shutdown + exit. It is re-spawned on next use.
4. Teardown. On project unload or daemon shutdown, all servers for the project are shut down.

Why daemon-side, not cage-side:

• Language servers often need the full project tree (imports, node_modules, tsconfig.json). Caged subagents may only see a slice.
• Language servers are expensive to start. A single daemon-side instance serves all agents in a project.
• The daemon can enforce that agents only see diagnostics for files within their cage — the bridge filters results post-hoc.

LSP server configuration

The LSP bridge needs to know which language server to use for each language. Configuration lives in the project DSL (new optional field) and/or the operator's local config.

Project DSL extension (optional):

# in .kaged/project.yaml
lsp:
  servers:
    - lang: typescript
      command: ["typescript-language-server", "--stdio"]
    - lang: python
      command: ["pyright-langserver", "--stdio"]
    - lang: rust
      command: ["rust-analyzer"]

Local config fallback:

# in config.toml
[lsp.servers.typescript]
command = ["typescript-language-server", "--stdio"]

[lsp.servers.python]
command = ["pyright-langserver", "--stdio"]

Resolution order: project DSL > local config > kaged built-in defaults.

Built-in defaults (v0):

Operators install language servers on their host. kaged does not bundle them. If a server binary is not found, code.lsp actions for that language return error lsp_server_not_found with the expected command and install instructions.

File synchronization

The LSP protocol requires the client to notify the server about file opens and changes. The LSPBridge maintains a FileSync tracker:

• file.read triggers textDocument/didOpen if the file hasn't been opened in the server yet.
• file.write / edit.text triggers textDocument/didChange with the new content.
• File sync is project-scoped, not agent-scoped. If subagent A edits a file, subagent B's next code.lsp diagnostics call sees the change.

This means LSP results are always current with the workspace state, even across concurrent subagent edits within the same session.

Tool: code.lsp

A single unified tool with action-based dispatch. The action parameter selects the LSP operation; action-specific parameters are flat siblings validated by the handler. All actions require read:fs on the path unless noted otherwise.

Common parameters (all actions):

Position parameters (required for definition, references, rename, code_actions, hover):

Permission: requires { kind: "fs", mode: "rw", path: "caller" }. Results are filtered to files within the caller's cage allowlist where applicable.

Action: diagnostics

Get errors, warnings, and hints for a file or directory.

Additional parameters:

Example:

{
  "action": "diagnostics",
  "path": "./src/main.ts",
  "severity": "error"
}

Returns:

{
  "path": "./src/main.ts",
  "diagnostics": [
    {
      "line": 15,
      "character": 8,
      "end_line": 15,
      "end_character": 12,
      "severity": "error",
      "message": "Property 'naem' does not exist on type 'User'. Did you mean 'name'?",
      "code": "ts(2551)",
      "source": "typescript"
    }
  ],
  "count": 1
}

Behavior:

• Language is auto-detected from file extension.
• If no language server is running for the detected language, one is spawned (may take a few seconds on first call).
• For directories, the tool scans files matching the language's default extensions and returns aggregated diagnostics.
• Timeout: 30 seconds (language servers can be slow on first analysis).

Action: definition

Jump to the definition of a symbol.

Example:

{
  "action": "definition",
  "path": "./src/main.ts",
  "line": 15,
  "character": 8
}

Returns:

{
  "definitions": [
    {
      "path": "./src/types.ts",
      "line": 3,
      "character": 0,
      "preview": "export interface User {"
    }
  ]
}

Permission: requires read:fs on both the source file and the definition target. Definitions in files outside the caller's cage are returned with path only (no preview).

Action: references

Find all usages of a symbol across the workspace.

Additional parameters:

Example:

{
  "action": "references",
  "path": "./src/types.ts",
  "line": 3,
  "character": 17,
  "include_declaration": false
}

Returns:

{
  "references": [
    { "path": "./src/main.ts", "line": 15, "character": 8, "preview": "const user: User = ..." },
    { "path": "./src/auth.ts", "line": 42, "character": 12, "preview": "function validateUser(u: User)" }
  ],
  "count": 2
}

Permission: read:fs on source. References outside the caller's cage are included (read-only information about the broader codebase is safe).

Action: symbols

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

Additional parameters:

Example:

{
  "action": "symbols",
  "path": "./src/main.ts",
  "scope": "document",
  "limit": 50
}

Returns:

{
  "symbols": [
    { "name": "serve", "kind": "function", "path": "./src/main.ts", "line": 5, "character": 0 },
    { "name": "handleRequest", "kind": "function", "path": "./src/main.ts", "line": 12, "character": 0 }
  ],
  "count": 2
}

Action: rename

Rename a symbol across the workspace.

Additional parameters:

Example:

{
  "action": "rename",
  "path": "./src/types.ts",
  "line": 3,
  "character": 17,
  "new_name": "AppUser"
}

Returns:

{
  "changes": [
    { "path": "./src/types.ts", "edits": 1 },
    { "path": "./src/main.ts", "edits": 3 },
    { "path": "./src/auth.ts", "edits": 2 }
  ],
  "total_edits": 6,
  "files_changed": 3
}

Permission: requires write:fs on all files that would be changed. If any file falls outside the caller's cage, the rename is rejected with error rename_scope_exceeds_cage listing the inaccessible files. The agent must request a broader cage or delegate to the primary.

Behavior:

• The bridge first calls textDocument/prepareRename to validate the rename is possible.
• If preparation fails (not a renameable symbol), returns error rename_not_possible.
• On success, all edits are applied atomically. If any file write fails, the entire rename is rolled back.

Action: code_actions

Get available code actions (quick fixes, refactors) for a location.

Additional parameters:

Example:

{
  "action": "code_actions",
  "path": "./src/main.ts",
  "line": 15,
  "character": 8,
  "include_diagnostics": true
}

Returns:

{
  "actions": [
    {
      "title": "Change spelling to 'name'",
      "kind": "quickfix",
      "preferred": true,
      "edits": [
        { "path": "./src/main.ts", "line": 15, "old": "naem", "new": "name" }
      ]
    }
  ],
  "count": 1
}

Applying actions: the agent selects an action and calls edit.text with the provided edits. Code actions are informational — the agent decides whether to apply them.

Action: hover

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

Example:

{
  "action": "hover",
  "path": "./src/main.ts",
  "line": 15,
  "character": 8
}

Returns:

{
  "content": "(property) User.name: string",
  "documentation": "The user's display name.",
  "range": { "start": { "line": 15, "character": 8 }, "end": { "line": 15, "character": 12 } }
}

Debugger tool (debug)

Design philosophy

Real debugging means breakpoints, stepping, stack inspection, and variable evaluation. Not console.log. kaged agents should debug like a senior engineer: set a breakpoint, run the program, inspect the state, hypothesize, adjust.

The DAP bridge translates the Debug Adapter Protocol's session-oriented model into a single debug tool with action-based dispatch. An agent calls debug with action: "launch" to start a debug session, action: "set_breakpoint" to set breakpoints, action: "continue" to run to the next breakpoint, and action: "variables" to inspect state.

DAP bridge architecture

                ┌──────────────────────┐
                │    Agent             │
                └──────────┬───────────┘
                           │ debug({ action: "launch", runtime: "bun", script: "./src/main.ts" })
                           ▼
                ┌──────────────────────┐
                │     ToolRegistry     │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │     DAPBridge        │
                │  ┌────────────────┐  │
                │  │  SessionPool   │  │
                │  │                │  │
                │  │ ses_abc → DA ──│──│──▶ debug adapter process
                │  │ ses_def → DA ──│──│──▶ debug adapter process
                │  └────────────────┘  │
                └──────────────────────┘

Debug sessions

A debug session is scoped to a kaged session (one run at a time). An agent can have at most one active debug session. Debug sessions are explicitly created (debug with action: "launch" / action: "attach") and explicitly ended (action: "disconnect").

Session lifecycle:

1. Launch/Attach. The agent calls debug with action: "launch" (start a new program under the debugger) or action: "attach" (attach to a running process). The bridge spawns a debug adapter and initializes it per DAP spec.
2. Active. The agent sets breakpoints, runs the program, inspects state.
3. Disconnect. The agent calls debug with action: "disconnect". The bridge terminates the debug adapter and the debugged process.
4. Auto-cleanup. If the kaged run ends (completes, fails, or is cancelled) while a debug session is active, the bridge disconnects automatically.

Debug adapter configuration

Similar to LSP servers, debug adapters are configured per runtime:

Project DSL extension (optional):

# in .kaged/project.yaml
dap:
  adapters:
    - runtime: bun
      command: ["bun", "--inspect-brk=0", "--inspect-wait"]
      type: "bun"
    - runtime: node
      command: ["node", "--inspect-brk"]
      adapter: ["js-debug-adapter"]
      type: "pwa-node"
    - runtime: python
      adapter: ["debugpy", "--listen", "0"]
      type: "debugpy"

Built-in defaults (v0):

Seccomp interaction

DAP debugging often requires ptrace for process attachment and stepping. This interacts with the sandbox:

For Bun's --inspect debugger (WebSocket-based, not ptrace-based), the default seccomp profile is sufficient. The bridge detects the runtime and advises accordingly.

Tool: debug

A single unified tool with action-based dispatch. The action parameter selects the debug operation; action-specific parameters are flat siblings validated by the handler. At most one active debug session per agent.

Common parameter (all actions):

Permission: requires { kind: "fs", mode: "ro", path: "caller" } and { kind: "capability", name: "exec" }. For caged subagents with default seccomp using non-WebSocket debuggers, returns error with guidance to use relaxed seccomp.

Action: launch

Start a program under the debugger.

Additional parameters:

Example:

{
  "action": "launch",
  "runtime": "bun",
  "script": "./src/main.ts",
  "args": ["--port", "3000"],
  "env": { "NODE_ENV": "test" },
  "stop_on_entry": true
}

Returns:

{
  "debug_session_id": "dap_01HXAB",
  "status": "stopped",
  "stopped_reason": "entry",
  "threads": [
    { "id": 1, "name": "main" }
  ]
}

Action: attach

Attach the debugger to a running process.

Additional parameters:

Example:

{
  "action": "attach",
  "runtime": "bun",
  "port": 9229,
  "host": "localhost"
}

Returns: same shape as launch.

Action: set_breakpoint

Add a breakpoint to a source location.

Additional parameters:

Example:

{
  "action": "set_breakpoint",
  "path": "./src/main.ts",
  "line": 42,
  "condition": "user.role === 'admin'"
}

Returns:

{
  "breakpoint_id": 1,
  "verified": true,
  "actual_line": 42,
  "path": "./src/main.ts"
}

Action: remove_breakpoint

Remove a breakpoint from a source location.

Additional parameters:

Example:

{
  "action": "remove_breakpoint",
  "path": "./src/main.ts",
  "line": 42
}

Action: list_breakpoints

List all active breakpoints. No additional parameters.

Example:

{
  "action": "list_breakpoints"
}

Returns:

{
  "breakpoints": [
    { "id": 1, "path": "./src/main.ts", "line": 42, "condition": "user.role === 'admin'", "verified": true },
    { "id": 2, "path": "./src/auth.ts", "line": 15, "condition": null, "verified": true }
  ]
}

Actions: step_into, step_over, step_out

Step through code.

Additional parameters:

Example:

{
  "action": "step_over",
  "thread_id": 1
}

Returns:

{
  "status": "stopped",
  "stopped_reason": "step",
  "location": {
    "path": "./src/main.ts",
    "line": 43,
    "column": 4,
    "source_preview": "  const result = await processRequest(req);"
  }
}

Action: continue

Continue execution until the next breakpoint or program exit.

Additional parameters:

Example:

{
  "action": "continue",
  "thread_id": 1
}

Returns:

{
  "status": "stopped",
  "stopped_reason": "breakpoint",
  "breakpoint_id": 2,
  "location": {
    "path": "./src/auth.ts",
    "line": 15,
    "column": 0,
    "source_preview": "function validateToken(token: string) {"
  }
}

If the program exits without hitting a breakpoint:

{
  "status": "exited",
  "exit_code": 0
}

Action: stack_trace

Get the call stack at the current pause point.

Additional parameters:

Example:

{
  "action": "stack_trace",
  "thread_id": 1,
  "levels": 10
}

Returns:

{
  "frames": [
    { "id": 0, "name": "validateToken", "path": "./src/auth.ts", "line": 15, "column": 0 },
    { "id": 1, "name": "handleRequest", "path": "./src/main.ts", "line": 28, "column": 8 },
    { "id": 2, "name": "serve", "path": "./src/main.ts", "line": 5, "column": 0 }
  ],
  "total_frames": 3
}

Action: variables

Inspect variables in the current scope.

Additional parameters:

Example:

{
  "action": "variables",
  "frame_id": 0,
  "scope": "local"
}

Returns:

{
  "variables": [
    { "name": "token", "value": "\"eyJhbG...\"", "type": "string" },
    { "name": "user", "value": "User { name: \"alice\", role: \"admin\" }", "type": "User", "expandable": true },
    { "name": "isValid", "value": "true", "type": "boolean" }
  ]
}

With "expand": "user":

{
  "variables": [
    { "name": "user.name", "value": "\"alice\"", "type": "string" },
    { "name": "user.role", "value": "\"admin\"", "type": "string" },
    { "name": "user.id", "value": "42", "type": "number" }
  ]
}

Action: evaluate

Evaluate an expression in the current debug context.

Additional parameters:

Example:

{
  "action": "evaluate",
  "expression": "user.permissions.includes('write')",
  "frame_id": 0,
  "context": "watch"
}

Returns:

{
  "result": "false",
  "type": "boolean"
}

Security note: context: "repl" can execute arbitrary code in the debugged process. The tool warns agents to prefer "watch" for inspection. The cage's capabilities bound the blast radius — the debugged process is inside the cage, not the daemon.

Action: disconnect

End the debug session.

Additional parameters:

Example:

{
  "action": "disconnect",
  "terminate_debuggee": true
}

Returns:

{
  "disconnected": true,
  "debuggee_terminated": true
}

Project management tools (kaged.*)

Design philosophy

The kaged.issue.* and kaged.workflow.* namespaces give the root agent first-class access to the daemon's project management surface. A root agent coordinating subagents can file issues, update their status, trigger workflows, and check run results — all within the same reasoning loop that drives delegation.

These tools are root-only by design (ADR-0022 rule 5, rule 10). Subagents do not file issues or trigger workflows. Subagent work products bubble up to the root agent, which decides whether to update an issue or trigger a workflow based on the results. This keeps the audit trail single-rooted and prevents subagents from side-effecting project state.

All kaged.* tools carry principal_scope: "root-only". The DSL parser rejects them on non-root agents at load time. As a defense-in-depth measure, the registry also checks caller === "primary" at dispatch time and rejects with principal_scope_violation if a non-root caller somehow reaches the tool.

These tools do not require cage permissions (fs, net, seccomp) — they are daemon-internal API calls that read from and write to the daemon's SQLite database. The requires array is empty.

Tool: kaged.issue.list

List issues in the current project.

Parameters:

{
  "status": "open",
  "limit": 25,
  "offset": 0
}

Returns:

{
  "issues": [
    {
      "id": "01HXYZ...",
      "number": 42,
      "title": "Add dark mode support",
      "status": "triaged",
      "assignment": null,
      "created_by": "guest:01HXAB...",
      "created_at": 1716700000,
      "updated_at": 1716700500
    }
  ],
  "total": 87,
  "limit": 25,
  "offset": 0
}

Permission: principal_scope: "root-only". No cage requirements.

Tool: kaged.issue.get

Get full detail of a single issue, including its update stream.

Parameters:

{
  "number": 42
}

Returns:

{
  "id": "01HXYZ...",
  "number": 42,
  "title": "Add dark mode support",
  "body": "The UI should support a dark color scheme...",
  "original_body": null,
  "status": "triaged",
  "assignment": null,
  "created_by": "guest:01HXAB...",
  "created_at": 1716700000,
  "updated_at": 1716700500,
  "resolved_at": null,
  "resolved_by": null,
  "updates": [
    {
      "id": "01HXYZ...",
      "author": "operator",
      "kind": "status_change",
      "body": null,
      "metadata": { "old_status": "open", "new_status": "triaged" },
      "visibility": "all",
      "created_at": 1716700500
    }
  ]
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• Issue not found → error issue_not_found.
• Updates are returned in chronological order.
• Updates with visibility: "operator_only" are included (the root agent is operator-equivalent for read purposes).

Tool: kaged.issue.create

File a new issue in the current project.

Parameters:

{
  "title": "Refactor auth module",
  "body": "The auth module has grown to 800 lines. Split into token validation, session management, and OAuth provider modules."
}

Returns:

{
  "id": "01HXYZ...",
  "number": 43,
  "status": "open",
  "created_at": 1716701000
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• The created_by field is set to "agent:primary".
• The issue number is auto-assigned (next sequential per project).
• Title exceeding 200 characters → error invalid_params.
• Body exceeding 16 KB → error invalid_params.

Tool: kaged.issue.update

Update an issue's title, body, or assignment.

Parameters:

{
  "number": 42,
  "body": "Rephrased: implement CSS custom property-based theming with prefers-color-scheme media query support.",
  "assignment": "primary"
}

Returns:

{
  "number": 42,
  "updated_fields": ["body", "assignment"],
  "updated_at": 1716701500
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• At least one of title, body, assignment must be provided. Otherwise → error invalid_params.
• Issue not found → error issue_not_found.
• Body edit on an issue that has never been edited preserves the original in original_body. Subsequent edits do not overwrite original_body.
• Assignment to a nonexistent workflow → error invalid_assignment with detail.
• Each updated field generates an issue_updates row with the appropriate kind (title_edit, body_edit, or assignment_change).

Tool: kaged.issue.comment

Add a comment to an issue.

Parameters:

{
  "number": 42,
  "body": "Analysis complete. The auth module can be split into 3 files with no breaking changes to the public API.",
  "visibility": "all"
}

Returns:

{
  "update_id": "01HXYZ...",
  "issue_number": 42,
  "created_at": 1716702000
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• Issue not found → error issue_not_found.
• The author field on the update row is set to "agent:primary".
• Empty body → error invalid_params.

Tool: kaged.issue.transition

Change an issue's status. Enforces the state machine defined in issues.md.

Parameters:

{
  "number": 42,
  "to": "assigned",
  "comment": "Assigning to primary for implementation."
}

Returns:

{
  "number": 42,
  "from": "triaged",
  "to": "assigned",
  "updated_at": 1716702500
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• Issue not found → error issue_not_found.
• Invalid transition (e.g., open → resolved) → error invalid_transition with detail listing legal transitions from the current status.
• rejected without a comment → error invalid_params with message "Rejection requires an explanatory comment."
• resolved sets resolved_at and resolved_by to "agent:primary".
• Each transition generates a status_change update row. If a comment is provided, a comment update row is also generated.

Tool: kaged.todo

Manage the working checklist on the session's bound issue. A single root-only tool with action-based dispatch, consistent with the unified kaged.issue shape. The tool operates implicitly on the bound issue — the agent never names the issue.

Per ADR-0034, todos are issue-owned (stored in the issue_todos table) and come in two kinds: step (agent working plan) and criterion (acceptance criteria). The single-in_progress invariant is enforced server-side.

Parameters:

{
  "action": "add",
  "items": ["Implement auth module", "Write tests", "Update docs"],
  "kind": "step"
}

Actions:

Returns:

Every action returns the full current todo list, markdown-renderable:

{
  "todos": [
    { "id": "01HX...", "content": "Implement auth module", "status": "in_progress", "kind": "step", "phase": null, "position": 0 },
    { "id": "01HX...", "content": "Write tests", "status": "pending", "kind": "step", "phase": null, "position": 1 },
    { "id": "01HX...", "content": "All endpoints return 200", "status": "pending", "kind": "criterion", "phase": null, "position": 2 }
  ],
  "markdown": "- [>] Implement auth module\n- [ ] Write tests\n- [ ] All endpoints return 200 (criterion)"
}

Permission: principal_scope: "root-only". No cage requirements. Requires a bound issue on the session.

Behavior:

• No bound issue → error no_bound_issue with guidance to ask the operator to bind an issue.
• Task not found by content → error todo_not_found. Content-addressed lookup is case-insensitive, trimmed.
• drop on a criterion todo → error invalid_transition with message "Only the operator can drop acceptance criteria."
• start auto-demotes any existing in_progress todo to pending before promoting the target.
• set abandons all existing todos (status → abandoned) before creating new ones.
• note appends to the notes JSON array on the todo row.
• done on a criterion sets completed_at but does not close the issue — closure requires operator checkpoint sign-off.

Todo bubble-up (ADR-0034)

Per ADR-0034 and ADR-0022 rule 10, subagents do not have kaged.todo tool access. The tool carries principal_scope: "root-only". Subagents are storage-blind and domain-blind — they never touch the issue tracker directly.

The todo bubble-up pattern is a sibling of the issue bubble-up pattern documented in issues.md:

1. Subagent proposes. A subagent expresses a proposed checklist as structured content in its delegation return value.
2. Root reviews. The root agent reviews the proposal: accept as-is, modify, reject, or escalate to the operator (via kaged.checkpoint / kaged.ask).
3. Root persists. Only what the root accepts is persisted via kaged.todo, recorded with origin_agent set to the subagent's tree-path so the issue shows it as that subagent's sublist.
4. Subagent sees only its slice. The subagent only ever sees the slice of the issue the root forwards in its delegation message — never the issue itself, never the full todo list.

Review policy is a per-agent knob (auto | review, default review). Whether the root reviews or auto-accepts a subagent's proposal is configurable, not hard-wired.

Tool: kaged.workflow.list

List workflows available in the current project.

Parameters:

{
  "invokable_by": "operator"
}

Returns:

{
  "workflows": [
    {
      "name": "deploy",
      "description": "Build and deploy the project to production.",
      "inputs": {
        "branch": { "type": "string", "required": true, "description": "Git branch to deploy." },
        "dry_run": { "type": "boolean", "required": false, "default": false }
      },
      "invokable_by": ["operator"],
      "timeout_seconds": 600
    }
  ],
  "count": 1
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• Returns workflows from the loaded project DSL. This is a read from the in-memory compiled DSL, not a database query.
• Each workflow's inputs schema is included so the agent can construct valid invocations.

Tool: kaged.workflow.trigger

Invoke a workflow with structured inputs.

Parameters:

{
  "name": "deploy",
  "inputs": {
    "branch": "main",
    "dry_run": true
  }
}

Returns:

{
  "run_id": "01HXYZ...",
  "workflow_name": "deploy",
  "status": "running",
  "created_at": 1716703000
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• Workflow not found → error workflow_not_found.
• Input validation failure → error invalid_params with per-field detail (same validation as the HTTP invoke endpoint).
• The invoking principal is recorded as { type: "operator", id: "agent:primary" } — the root agent acts with operator authority.
• The workflow run is created as a session with kind: "workflow" per workflows.md.
• The tool returns immediately after the run is created. The run executes asynchronously. Use kaged.workflow.status to poll for completion.
• file inputs are not supported via this tool (file uploads require the HTTP upload protocol). If the workflow has a required file input, the tool returns error file_input_not_supported with guidance to use the HTTP endpoint.

Tool: kaged.workflow.status

Get the status of a workflow run.

Parameters:

{
  "run_id": "01HXYZ..."
}

Returns:

{
  "run_id": "01HXYZ...",
  "workflow_name": "deploy",
  "status": "succeeded",
  "inputs": { "branch": "main", "dry_run": true },
  "created_at": 1716703000,
  "completed_at": 1716703120,
  "duration_ms": 120000
}

Permission: principal_scope: "root-only". No cage requirements.

Behavior:

• Run not found → error run_not_found.
• status is one of: running, succeeded, failed, cancelled.
• For failed runs, the response includes an additional error field with the failure reason.
• For running runs, completed_at and duration_ms are null.

Shell tools

Design philosophy

The shell namespace provides direct command execution via the daemon's PTY broker. Unlike file or search tools that abstract over specific operations, shell tools give agents raw access to the host shell — gated by cage policy and capability requirements. This is intentionally a single tool (shell.bash); additional shells (e.g., shell.python, shell.node) may follow in v0.x but the execution model is the same.

Shell commands run in a PTY (not a raw subprocess), so they inherit the operator's environment and produce output that matches what the operator would see in a terminal. The broker manages process lifecycle including timeout enforcement and graceful kill escalation (SIGTERM → 5s grace → SIGKILL).

Tool: shell.bash

Execute a shell command via /bin/sh -c through the PTY broker.

Parameters:

{
  "command": "bun test --recursive packages/",
  "cwd": "./packages/daemon",
  "timeout": 30000,
  "env": { "NODE_ENV": "test" }
}

Returns:

{
  "stdout": "bun test v1.2.3\n\n 42 pass\n 0 fail\n",
  "stderr": "",
  "exit_code": 0,
  "timed_out": false
}

Permission: Requires { kind: "capability", name: "shell" }. Primary agent (no cage) is always allowed. Caged subagents must have shell in their capability set. Additionally requires { kind: "fs", mode: "rw", path: "caller" } — the caller must have read-write filesystem access to the working directory.

Behavior:

• The command is spawned via PtyBroker.spawn() which uses Bun.spawn(["sh", "-c", command]).
• Non-zero exit codes are returned as successful outcomes (data), not errors. The agent is expected to interpret exit codes.
• If timeout is reached, the broker sends SIGTERM, waits 5 seconds (KILL_GRACE_MS), then sends SIGKILL. The response has timed_out: true.
• Output is captured via the broker's scrollback buffer (getScrollback()). Output exceeding 1 MB is truncated with a trailing \n[output truncated — 1 MB limit] marker.
• Empty command → error invalid_params.
• cwd resolving outside the project root → error invalid_params with detail.
• env keys containing = or empty strings → error invalid_params.
• The process inherits the daemon's environment, with env entries merged on top (overriding on collision).

Web search tool (web.search)

Design philosophy

The web namespace (reserved by ADR-0033) hosts agent operations against the public web. The first tool in this namespace is web.search — general-purpose web search with multi-provider fallback.

Coding agents that can reach the web are dramatically more useful than agents that cannot: they can look up current API docs, verify error messages against real-world reports, cross-check library versions, and ground their reasoning in primary sources. Unlike search.grep (local content discovery) or search.ast (local code structure), web.search reaches outside the project workspace — and outside the operator's host. It is therefore off by default and opt-in per agent via the standard tools: block. No agent gets web access without the operator explicitly writing "web.search": { enabled: true } in the DSL.

The tool is provider-pluggable. oh-my-pi's WebSearchTool (reference) proved the pattern: a uniform provider interface, a sequential fallback chain, and a markdown formatter that returns numbered sources an LLM can cite. kaged adopts the same shape with one important clarification: search providers are model-independent HTTP APIs. Whether the provider internally synthesises an answer with an LLM (Tavily, Perplexity, Anthropic web search, Gemini grounding) or returns raw results (Brave, Exa, Kagi, Jina, SearXNG) is an implementation detail of the provider. From the daemon's perspective, every provider is a callable that takes a query plus credentials and returns a unified WebSearchResponse. The provider's API key is independent of the operator's conversation LLM.

Why built-in, not MCP-only

ADR-0043 already gives operators MCP as an escape hatch — Brave, Exa, and Tavily all ship MCP servers, so an operator could wire up mcp.brave.web_search via the existing DSL surface without any new code in kaged. The case for a first-party web.search built-in alongside that escape hatch rests on three points:

1. Fallback chains we own. MCP tool dispatch is one-shot — call the server, get a result, return it. There is no MCP-native notion of "try Brave, fall back to Exa on rate-limit, fall back to Tavily on auth failure." Operators want this behaviour. Building it into a kaged-owned built-in gives every operator the same fallback story without each one having to author it themselves.
2. Provider-agnostic response shape. Each MCP search server returns its own idiosyncratic JSON. A first-party built-in normalises the response into a single WebSearchResponse (sources, optional synthesised answer, optional related queries) and formats it as numbered markdown for the LLM. The agent's prompt does not have to know which provider produced the result.
3. Operator-side config, project-side enablement. Provider credentials are per-operator (ADR-0011 — secrets never travel with the project). A first-party built-in lets the operator configure provider order and API keys once in local.toml and have every kaged project reuse them. MCP servers, by contrast, are declared per-project in the DSL.

MCP remains the right answer for operators who want a single, specific search provider and don't need a fallback chain. The two coexist.

Provider abstraction

Every search backend implements the same interface. The daemon's web-handlers.ts is provider-agnostic; it only knows the abstraction.

/** Uniform parameters passed to every provider. */
interface WebSearchParams {
  query: string;
  recency?: "day" | "week" | "month" | "year";
  limit?: number;                  // preferred max results (provider may cap)
  maxOutputTokens?: number;        // hint for LLM-backed providers
  numSearchResults?: number;       // hint for LLM-backed providers
  temperature?: number;            // hint for LLM-backed providers
  signal?: AbortSignal;            // composed with the daemon's hard timeout
}

/** Uniform response returned by every provider. */
interface WebSearchResponse {
  provider: string;                // the provider id that produced this response
  answer?: string;                 // synthesised answer (LLM-backed providers)
  sources: WebSearchSource[];      // numbered citations
  citations?: WebSearchCitation[]; // optional deeper citations (provider-specific)
  relatedQuestions?: string[];
  searchQueries?: string[];        // queries the provider actually issued
}

interface WebSearchSource {
  title: string;
  url: string;
  snippet?: string;
  publishedDate?: string;          // ISO-8601 if known
  ageSeconds?: number;             // convenience for formatter
}

interface WebSearchCitation {
  title?: string;
  url: string;
  citedText?: string;
}

/** Every search backend implements this. */
abstract class WebSearchProvider {
  abstract readonly id: string;          // "brave", "exa", "anthropic", ...
  abstract readonly label: string;       // human-readable
  abstract readonly needsApiKey: boolean;

  /** Returns true if the credentials/config for this provider are present and the provider is not disabled. */
  abstract isAvailable(config: WebProviderConfig): boolean;

  /** Execute a search. Throw on any failure — the fallback chain handles it. */
  abstract search(params: WebSearchParams, config: WebProviderConfig): Promise<WebSearchResponse>;
}

Provider implementations live in packages/daemon/src/runtime/web/providers/. Each is a single file (~150 LOC) that translates WebSearchParams into the provider's HTTP/LLM API and the provider's response into WebSearchResponse. Providers never see each other; they only see the abstraction.

Provider catalog

The catalog is divided into two tiers based on what the provider returns, not what it uses internally. Both tiers implement the same WebSearchProvider interface.

Tier 1 — Direct search APIs

Return raw search results (titles, URLs, snippets). No synthesised answer. The daemon's formatter composes the final markdown.

Tier 2 — LLM-backed search providers

Make their own LLM call internally to synthesise an answer with citations. The API key authenticates both the search and the LLM call. The operator's conversation LLM and the search LLM are independent — using Anthropic's web search tool does not require the operator to use Anthropic as their conversation model.

The daemon implementation MAY ship with a subset of these in the initial phase. The provider interface is stable; additional providers land as drop-in files under packages/daemon/src/runtime/web/providers/ with no other code changes required.

Fallback chain

The daemon does not pick a single provider. It tries providers in order until one succeeds.

Chain order resolution (highest priority first):

1. web.preferred_provider in local.toml [web] — if set and available, that provider goes first.
2. web.provider_order in local.toml [web] — explicit ordered list. Only listed providers are tried, in the given order.
3. Default order: direct-API providers first (lower latency, no token cost), LLM-backed providers second: ["brave", "exa", "tavily", "kagi", "jina", "searxng", "perplexity", "anthropic", "gemini", "openai", "zai", "kimi", "synthetic"]

Availability check: before each provider is tried, isAvailable(config) is called. A provider is available when its API key is present in [secrets.web.<provider>] (or the operator-configured endpoint, for searxng) AND it is not explicitly disabled in [web.<provider>]. Unavailable providers are silently skipped — they do not count as fallback failures.

Failure semantics:

• Any thrown error from provider.search() (network, HTTP 4xx/5xx, timeout, quota exhausted, parse failure) triggers fallback to the next available provider.
• The failure is recorded in fallback_attempts with the provider id and a short error code (rate_limited, auth_failed, network_error, timeout, quota_exhausted, provider_error).
• AbortSignal cancellation does NOT trigger fallback. If the operator (via run cancellation) or the hard timeout aborts the call, the entire tool call returns immediately with aborted.
• If every available provider fails, the tool returns error web_search_all_providers_failed with the full fallback_attempts chain in the detail field.

Hard timeout: every provider call is wrapped in AbortSignal.any([signal, AbortSignal.timeout(60_000)]). The 60s default is configurable via [web] hard_timeout_ms in local.toml. Per-provider timeout overrides live in [web.<provider>] timeout_ms.

Response formatting

The daemon formats WebSearchResponse into a single markdown string the LLM consumes as the tool result. The format is fixed so prompt engineering on the model side can rely on it:

<answer if present>

## Sources (N)
[1] Title (age or publish-date)
    https://example.com/source-1
    Optional snippet, truncated to 240 chars.

[2] ...

## Citations (M)                          ← only if response.citations present
[1] Title
    https://example.com/citation-1
    Optional cited text, truncated to 240 chars.

## Related                                 ← only if response.relatedQuestions present
- Related question one?
- Related question two?

Search queries (K):                        ← only if response.searchQueries present
- actual query the provider issued

The tool's content return field carries this string verbatim. The structured sources_count, provider_used, truncated, and fallback_attempts fields ride alongside for UI / observability.

Rate limiting, retries, and caching

• No retries within a single provider. A failed provider is recorded and the chain advances. Operators who want retries can configure them at the [web.<provider>] level in a future amendment; MVP does not retry.
• No result caching. Search results are time-sensitive; a cached result is often a wrong result. Each call hits the provider.
• Hard timeout is the only time bound. 60s default, configurable. Cancellation via AbortSignal propagates immediately.
• Provider-side rate limits are surfaced as rate_limited in fallback_attempts. The daemon does not attempt to wait and retry — the next provider is tried.

Local-config integration

Provider credentials and operator preferences live in local.toml. Per ADR-0011, no provider configuration of any kind appears in the project DSL — the DSL only enables web.search per agent via the standard tools: block. Everything else is operator-local.

# local.toml

[web]
# Operator-level preferences. None are required.
preferred_provider = "brave"               # try this provider first
# provider_order = ["brave", "exa", "tavily"]   # explicit ordered list (overrides preferred_provider + default order)
hard_timeout_ms = 60000                    # per-provider hard timeout, default 60000

[web.searxng]
endpoint = "https://searxng.operator.local"   # required for searxng provider

[web.brave]
timeout_ms = 15000                         # per-provider timeout override

# API keys — flat map under [secrets.web]. Key = provider id, value = API key.
# All MVP providers use a single API key; future providers needing multiple
# credentials will require a schema extension.
[secrets.web]
brave    = "BSA-xxxxxxxxxxxxxxxx"
exa      = "exa-xxxxxxxxxxxxxxxx"
tavily   = "tvly-xxxxxxxxxxxxxxxx"
anthropic = "sk-ant-xxxxxxxxxxxxxxxx"
gemini   = "AIzaXXXXXXXXXXXXXXXX"

# ...one key per provider the operator has credentials for.

Secret resolution: the daemon looks up a provider's API key in the flat [secrets.web] map — key is the provider id, value is the API key. This fits the existing 2-level secrets schema (Record<string, Record<string, string>>). Missing key for a provider → provider marked unavailable (not a startup error). All MVP providers use a single API key; providers needing multiple credentials in the future will require a schema extension.

Redaction: redactSecrets() strips all [secrets.web.*] values before any config is surfaced to the UI, API, or logs. This extends the existing redactor that already handles [secrets.*] and provider API keys.

See local-config.md § [web] for the normative schema.

Tool: web.search

A single unified tool. Off by default; agents opt in via their tools: block.

Parameters:

{
  "query": "Bun.serve options.interface documentation",
  "recency": "month",
  "limit": 5
}

Returns:

{
  "content": "<markdown-formatted response, see § Response formatting>",
  "provider_used": "brave",
  "sources_count": 5,
  "truncated": false,
  "fallback_attempts": [
    { "provider": "brave", "error": "rate_limited", "message": "HTTP 429" }
  ]
}

Permission: none. web.search has no requires entries. It is a daemon-brokered outbound HTTP call, not a cage-mediated resource. Authorisation is the operator's act of enabling the tool on an agent and configuring credentials in local.toml.

principal_scope: not set. Any agent (primary or subagent) can be granted web.search via its tools: block.

Behavior:

• The daemon resolves the provider chain from local.toml [web] at handler construction time (cheaper than per-call resolution; the handler holds the resolved chain).
• For each call, the chain is walked in order. The first available provider that returns successfully wins.
• Each provider call is wrapped in AbortSignal.any([incoming-signal, hard-timeout]). The incoming signal is the run's AbortController — cancellation aborts the entire tool call, no fallback.
• The response is formatted via the daemon's formatForLLM(response) helper, which produces the fixed markdown shape documented above.
• If query is empty or whitespace-only → error invalid_params.
• If query exceeds 1024 chars → error invalid_params.
• If no providers are available (no credentials configured) → error web_search_no_providers_configured. This is a configuration error, not a transient failure.
• If all available providers fail → error web_search_all_providers_failed with the full fallback_attempts chain in detail.

Worked example — happy path (single provider):

// Agent calls:
{ "query": "bun spawn typescript example", "recency": "year", "limit": 3 }

// Tool returns:
{
  "content": "## Sources (3)\n[1] Bun Documentation — Bun.spawn (2 months ago)\n    https://bun.com/docs/api/spawn\n    Bun.spawn spawns a child process ...\n[2] ...",
  "provider_used": "brave",
  "sources_count": 3,
  "truncated": false,
  "fallback_attempts": []
}

Worked example — fallback path:

// Agent calls:
{ "query": "postgres jsonb path query examples" }

// Brave is rate-limited; Exa succeeds. Tool returns:
{
  "content": "...",
  "provider_used": "exa",
  "sources_count": 5,
  "truncated": false,
  "fallback_attempts": [
    { "provider": "brave", "error": "rate_limited", "message": "HTTP 429: rate limit exceeded" }
  ]
}

Worked example — LLM-backed provider:

// Agent calls:
{ "query": "explain rust async drop semantics", "max_tokens": 1024 }

// brave + exa configured but operator marked tavily as preferred_provider.
// Tavily synthesises an answer from its search results. Tool returns:
{
  "content": "Rust does not have async Drop ...\n\n## Sources (4)\n[1] ...\n\n## Related\n- How does async drop interact with tokio?",
  "provider_used": "tavily",
  "sources_count": 4,
  "truncated": false,
  "fallback_attempts": []
}

Per-agent enablement

web.search is off by default for every agent, including the primary. The operator opts in per agent:

# .kaged/project.yaml
primary:
  tools:
    "web.search": { enabled: true }

  subagents:
    researcher:
      tools:
        "web.search": { enabled: true }   # subagent can search too

The standard per-agent resolution rules apply (see § Per-agent tool resolution). There is no project-level web: block in the DSL — provider configuration is purely operator-local.

Sandbox integration

Permission enforcement

Every tool call passes through ToolPermissions before execution. The permission check is based on the caller's cage_policy:

// Conceptual
function checkPermission(
  tool: ToolDefinition,
  params: Record<string, unknown>,
  context: ToolCallContext
): "allowed" | PermissionError {
  // Primary agent has no cage — always allowed
  if (context.cage_policy === null) return "allowed";

  const policy = context.cage_policy;

  for (const req of tool.requires) {
    switch (req.kind) {
      case "fs": {
        const requestedPath = resolve(context.project_root, params.path);
        const mode = req.mode;
        const allowed = policy.fs.some(mount =>
          requestedPath.startsWith(resolve(context.project_root, mount.path)) &&
          (mode === "ro" || mount.mode === "rw")
        );
        if (!allowed) return { code: "capability_denied", detail: `${mode}:fs:${params.path}` };
        break;
      }
      case "seccomp": {
        if (policy.seccomp !== req.profile) {
          return { code: "seccomp_insufficient", detail: `requires ${req.profile}, have ${policy.seccomp}` };
        }
        break;
      }
    }
  }

  return "allowed";
}

Result filtering

For read-only tools that return results across the workspace (e.g., search.grep, code.lsp references action), the bridge returns all results but marks those outside the caller's cage:

• Inside cage: full result with content previews.
• Outside cage: path and line number only. No content preview. Marked "outside_cage": true.

This gives agents workspace-wide awareness (they can see that a function is used in 15 files) without leaking file contents they shouldn't read.

Tool availability by cage type

Failure modes

Audit events

Testing notes

File tool tests

• file.read happy path: read a known file, assert line-numbered content.
• file.read binary detection: read a .png, assert type: "binary".
• file.read offset/limit: read lines 10-20 of a 100-line file.
• file.write creates parent dirs: write to ./a/b/c/new.ts, assert directories created.
• file.write requires prior read: write without reading first, assert file_not_read.
• edit.text exact match: edit a known string, assert replacement.
• edit.text multiple matches: old_string appears 3 times, replace_all false, assert multiple_matches.
• edit.text no match: old_string not in file, assert old_string_not_found.
• file.create existing file: file exists, assert file_exists.

Search tool tests

• search.grep regex match: search for TODO, assert matching lines.
• search.grep file filter: search *.ts only, assert no .js results.
• search.grep timeout: search a huge directory with pathological regex, assert timeout with partial results.
• search.glob pattern: **/*.test.ts, assert only test files.
• search.ast meta-variable: pattern console.log($MSG), assert matches with captured $MSG.
• edit.ast dry-run preview: pattern console.log($MSG) → logger.debug($MSG), dry_run: true, assert applied: false and changes array populated.
• edit.ast apply: same pattern with dry_run: false, assert applied: true and file on disk modified.
• edit.ast path resolution: single file path, assert only that file touched; directory path, assert all matching files.
• edit.ast invalid pattern: unparseable ast-grep pattern, assert invalid_pattern.
• edit.ast language inference: mixed .ts and .js files without explicit lang, assert inference error or successful inference when uniform.
• edit.ast max_replacements cap: set max_replacements: 1 with 3 matches, assert limit_reached: true and only 1 replacement.
• edit.ast max_files cap: set max_files: 1 with 2 matching files, assert limit_reached: true.
• edit.ast path traversal rejection: pass path: "../../etc", assert invalid_params.
• edit.ast parse error collection: file with syntax errors among candidates, assert parse_errors populated and operation continues on parseable files.

code.lsp tool tests

• Server spawn on demand: first code.lsp diagnostics call spawns the server, assert server process exists.
• diagnostics returns errors: file with a type error, assert diagnostic with correct line/message.
• definition navigates: cursor on a function call, assert definition in the correct file.
• references finds usages: cursor on a type, assert all usage locations.
• rename atomic: rename a symbol used in 3 files. Assert all 3 updated. Introduce a write failure on file 2 — assert all 3 rolled back.
• rename cage scoping: rename a symbol used in files inside and outside the cage. Assert rejection before any edits.
• File sync: agent edits a file via edit.text, then calls code.lsp diagnostics. Assert the diagnostics reflect the edit (not stale).
• Server crash recovery: kill the language server mid-request. Assert the bridge restarts it and the next call succeeds.
• Idle timeout: call code.lsp diagnostics, wait 10+ minutes, call again. Assert server was stopped and re-spawned.

debug tool tests

• launch + breakpoint + continue: launch a script, set a breakpoint, continue, assert stopped at breakpoint.
• variables inspection: at a breakpoint, inspect local variables. Assert correct names, values, types.
• evaluate watch: evaluate an expression at a breakpoint. Assert result.
• step_into/step_over/step_out: at a breakpoint, step over a function call, assert cursor moves to next line. Step into, assert cursor inside the function.
• disconnect cleanup: disconnect, assert debug adapter process is gone and debuggee is killed.
• Auto-cleanup on run end: cancel a run while a debug session is active. Assert debug session is cleaned up.
• default seccomp rejection: subagent in default cage calls debug with action: "launch" with ptrace-based debugger. Assert dap_requires_relaxed_seccomp.
• Bun --inspect works under default seccomp: Bun's WebSocket debugger doesn't need ptrace. Assert debug launch succeeds.

Permission tests

• Cage read enforcement: subagent with fs: [{mode: ro, path: ./src}] reads ./src/main.ts (ok), reads ./data/secrets.json (denied).
• Cage write enforcement: subagent with fs: [{mode: ro, path: ./src}] tries edit.text on ./src/main.ts (denied — ro, not rw).
• Primary has no cage: primary calls any tool on any path — all succeed.
• Search result filtering: subagent with restricted cage calls search.grep on project root. Results outside cage have no content preview.

Project management tool tests

• kaged.issue.list happy path: project has 3 issues, assert all returned with correct fields.
• kaged.issue.list status filter: filter by triaged, assert only triaged issues returned.
• kaged.issue.list search: FTS5 query matches title and body content.
• kaged.issue.list pagination: 30 issues, limit: 10, offset: 10, assert correct slice.
• kaged.issue.get happy path: get issue #42, assert full detail including updates.
• kaged.issue.get not found: get nonexistent issue, assert issue_not_found.
• kaged.issue.get includes operator-only updates: assert visibility: "operator_only" updates are included for root agent.
• kaged.issue.create happy path: create issue, assert sequential number assigned and status is open.
• kaged.issue.create title too long: 201 characters, assert invalid_params.
• kaged.issue.create author identity: assert created_by is "agent:primary".
• kaged.issue.update body edit: update body, assert original_body preserved on first edit.
• kaged.issue.update second body edit: update body again, assert original_body unchanged from first edit.
• kaged.issue.update assignment: assign to "workflow:deploy", assert assignment recorded.
• kaged.issue.update invalid assignment: assign to nonexistent workflow, assert invalid_assignment.
• kaged.issue.comment happy path: add comment, assert update row created with kind: "comment".
• kaged.issue.comment operator-only: add with visibility: "operator_only", assert visibility stored.
• kaged.issue.transition happy path: open → triaged, assert status changed and update row created.
• kaged.issue.transition invalid: open → resolved, assert invalid_transition with legal transitions.
• kaged.issue.transition rejected requires comment: transition to rejected without comment, assert invalid_params.
• kaged.issue.transition resolved sets timestamps: transition to resolved, assert resolved_at and resolved_by set.

kaged.todo tool tests

• view happy path: session has bound issue with 3 todos, assert all returned with correct fields and markdown.
• view no bound issue: session has no bound issue, assert no_bound_issue error.
• set replaces list: set 3 items, assert existing todos abandoned and new ones created.
• set with kind: set items with kind: "criterion", assert kind persisted.
• set with phase: set items with phase: "discovery", assert phase persisted.
• add appends: add 2 items to existing list, assert position continues from max.
• start promotes: start a pending todo, assert status in_progress.
• start single-in_progress: start a second todo while one is in_progress, assert first demoted to pending.
• done completes: mark a todo done, assert completed_at set.
• done criterion is a claim: mark a criterion done, assert completed_at set but issue not resolved.
• drop abandons: drop a step todo, assert status abandoned.
• drop criterion rejected: drop a criterion todo, assert invalid_transition error.
• note appends: add a note, assert notes array grows.
• note max length: note exceeds 2000 chars, assert invalid_params.
• Content-addressed lookup: start a todo by partial text match, assert correct todo found.
• Content not found: start a todo with nonexistent content, assert todo_not_found.

kaged.workflow.list happy path:** project has 2 workflows, assert both returned with input schemas.

• kaged.workflow.list filter: filter by invokable_by: "guest", assert only guest-invokable workflows returned.
• kaged.workflow.trigger happy path: trigger deploy with valid inputs, assert run_id returned and status is running.
• kaged.workflow.trigger not found: trigger nonexistent workflow, assert workflow_not_found.
• kaged.workflow.trigger invalid inputs: missing required input, assert invalid_params with per-field detail.
• kaged.workflow.trigger file input: workflow has required file input, assert file_input_not_supported.
• kaged.workflow.trigger invoker identity: assert invoking principal recorded as { type: "operator", id: "agent:primary" }.
• kaged.workflow.status happy path: poll completed run, assert succeeded with duration.
• kaged.workflow.status running: poll in-progress run, assert completed_at and duration_ms are null.
• kaged.workflow.status failed: poll failed run, assert error field present.
• kaged.workflow.status not found: poll nonexistent run, assert run_not_found.

Principal scope enforcement tests

• Root agent calls kaged.issue.list: assert success.
• Non-root agent calls kaged.issue.list: assert principal_scope_violation at dispatch time.
• DSL with kaged.issue.create on subagent: assert parse-time rejection (schema error).
• DSL with kaged.workflow.trigger on subagent: assert parse-time rejection.
• Per-agent tool resolution: root agent with no tools: override, assert kaged.issue.* and kaged.workflow.* enabled by default.
• Per-agent tool resolution: subagent with no tools: override, assert empty tool set (no defaults).
• Per-agent tool resolution: subagent with explicit "file.*": { enabled: true }, assert only file tools enabled.
• Root agent suppresses default: root agent with "kaged.issue.*": { enabled: false }, assert issue tools disabled.

Shell tool tests

• shell.bash happy path: execute echo hello, assert stdout contains hello, exit_code is 0, timed_out is false.
• shell.bash non-zero exit: execute exit 42, assert exit_code is 42, result is success (not error).
• shell.bash custom cwd: execute pwd with cwd: "./packages/daemon", assert output contains packages/daemon.
• shell.bash cwd escape: execute with cwd: "../../", assert invalid_params error.
• shell.bash timeout: execute sleep 60 with timeout: 2000, assert timed_out is true and exit_code is 137.
• shell.bash timeout clamping: pass timeout: 500, assert clamped to 1000.
• shell.bash timeout clamping upper: pass timeout: 999999, assert clamped to 600000.
• shell.bash empty command: pass command: "", assert invalid_params.
• shell.bash env vars: execute echo $FOO with env: { "FOO": "bar" }, assert output contains bar.
• shell.bash env validation: pass env: { "": "val" }, assert invalid_params.
• shell.bash output truncation: generate >1 MB output, assert truncated with marker.

Open questions

1. Structural rewrite tool (search.ast_replace). Resolved: exposed as edit.ast (dry-run by default, requires explicit dry_run: false to apply). Tool definition and handler wired in packages/daemon/src/runtime/tool-handlers/edit-handlers.ts, using the existing astEdit Rust N-API export. Tests cover dry-run, path resolution, and rewrite application.

2. LSP multi-root workspaces. Some language servers support multi-root workspaces. kaged projects are single-root by design. If a subagent needs LSP for a dependency (e.g., node_modules), the current model handles it (the server sees the whole project tree). But monorepo projects with multiple kaged projects may want a shared server. Deferred.

3. DAP for compiled languages. Debugging Go, Rust, or C++ requires delve, lldb, or gdb — which have their own DAP adapters. v0 supports interpreted runtimes (Bun, Node, Python). Compiled-language DAP adapters are v0.x.

4. Tool versioning. Built-in tools don't version today (they're part of the daemon). If we change a tool's parameter schema, agents with cached tool definitions may break. A tool_version field in the registry is plausible. Not v0.

5. Concurrent LSP requests. Language servers vary in their concurrency support. Some handle concurrent requests; some serialize. The bridge should respect the server's capabilities (from the initialize response). v0: serialize all requests to a given server. v0.x: parallel where the server supports it.

6. DAP logpoints as a linter-adjacent workflow. Logpoints (debug with action: "set_breakpoint" and log_message) are essentially structured console.log without modifying source. Should the tooling layer encourage agents to use logpoints before full breakpoint debugging? Possibly — but this is an agent-prompting concern, not a tool-layer concern.

7. File watching. Should the daemon watch the project filesystem for external changes (operator editing files in their IDE) and notify agents / update LSP? v0: no. The daemon trusts its own tool calls as the source of truth. External changes are invisible until the agent re-reads the file. v0.x may add inotify-based sync.

8. Tool usage quotas. Should there be per-run or per-session limits on tool calls (e.g., max 1000 file reads per run)? v0: no hard limits. The walltime limit on cages is the indirect bound. If agents abuse tools, the operator adjusts the walltime or intervenes at a checkpoint.

Skill tool (skill.use)

The skill namespace (reserved by ADR-0033) hosts the on-demand skill activation tool. Per ADR-0044, skills are declarative agent capabilities — structured markdown modules (SKILL.md with YAML frontmatter) that inject domain knowledge, methodology, or instructions into the agent's context.

This tool is dynamically registered. Unlike every other built-in tool, skill.use is not in the global builtin tool set. It is created per-agent at session start only when the agent has discovered skills (from .kaged/skills/*/SKILL.md matched against the agent's skills: glob filter). If an agent has no skills, the tool is not registered and the agent has no skill.* tool at all.

The catalog lives in the tool description. The tool's description field contains a human/LLM-readable catalog of available skills (name + description for each). This eliminates the need for a separate system-prompt injection block — the LLM sees tool definitions, so the catalog travels with the tool.

Tool: skill.use

{
  "name": "skill.use",
  "namespace": "skill",
  "description": "Activate a skill — load domain knowledge, methodology, or instructions into your context.\n\nAvailable skills:\n\n- **code-review**: Systematic code review methodology — check for correctness, security, performance, and style.\n- **deploy-runbook**: Step-by-step deployment procedure for this project.",
  "source": "builtin",
  "parameters": {
    "type": "object",
    "required": ["skill"],
    "properties": {
      "skill": {
        "type": "string",
        "enum": ["code-review", "deploy-runbook"],
        "description": "The skill to activate."
      }
    }
  },
  "returns": {
    "type": "object",
    "properties": {
      "content": { "type": "string" }
    }
  },
  "requires": [],
  "principal_scope": undefined
}

Parameters:

Returns: Text content containing the skill body wrapped in a <skill_content> element with a path hint and <skill_resources> listing:

<skill_content name="pdf-processing">
# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

[rest of SKILL.md body — frontmatter stripped]

Skill directory: .kaged/skills/pdf-processing
Relative paths in this skill are relative to the skill directory.

<skill_resources>
  <file>scripts/extract.py</file>
  <file>scripts/merge.py</file>
  <file>references/pdf-spec-summary.md</file>
</skill_resources>
</skill_content>

Permission: none. skill.use has no requires entries. It is a context-injection tool, not a cage-mediated resource.

principal_scope: not set. Any agent (primary or subagent) with discovered skills gets the tool.

File access: the skill's path hint tells the agent where supporting files live on disk (.kaged/skills/<name>/). The agent accesses them via its existing tools with normal project-relative paths. The cage controls access as it does for any other path — if the agent has shell access, it can run bundled scripts; if it doesn't, it can't. This is operator choice, not skill-level policy.

Compatibility: compatible with the standardised Agent Skills format (Cursor, Cline, Claude Code, etc.). Skills authored for those tools work without modification — the frontmatter fields (name, description) are interpreted identically, and supporting files are accessed via normal filesystem paths.

Amendments

2026-06-15 — skill.use tool: ADR-0044 skills integration

Activates the skill namespace reserved by ADR-0033 §1 with the first tool: skill.use. On-demand skill activation per ADR-0044.

• Namespace table gains a skill row: domain "Declarative agent capabilities", current tools skill.use.
• New section § Skill tool (skill.use) documents: dynamic per-agent registration, catalog-in-description pattern, <skill_content> activation result with path hint and <skill_resources>, file access via existing tools, standard-format compatibility.
• Dynamically registered, not global. Unlike all other built-in tools, skill.use is not in the global builtin tool set. It is created per-agent at session start only when discovered skills exist. Agents with no skills have no skill.* tool.
• No cage interaction. skill.use has no requires entries. The tool injects text content. File access by the agent after activation is mediated by existing tools and cage constraints — the skill does not grant any new permissions.
• Spec amendments required of this change: project-dsl.md gains a skills: glob array on AgentSpec; agent.md documents the skill discovery and activation lifecycle.

Activates the web namespace reserved by ADR-0033 §1 with the first tool: web.search. Multi-provider web search with sequential fallback chain. Provider abstraction and config flow adapted from oh-my-pi's WebSearchTool reference (reference/oh-my-pi/packages/coding-agent/src/web/search/).

• Namespace table gains a web row: domain "Web search", current tools web.search.
• New section § Web search tool (web.search) documents: provider abstraction (WebSearchProvider interface, WebSearchParams/WebSearchResponse types), provider catalog (Tier 1 direct-API: brave, exa, kagi, jina, searxng; Tier 2 LLM-backed: tavily, perplexity, anthropic, gemini, openai, zai, kimi, synthetic), fallback chain semantics, response formatting, rate limiting, local-config integration, full web.search tool definition with parameters/returns/behavior, and worked examples.
• Provider abstraction is uniform. Every provider — whether direct HTTP API or LLM-backed synthesis — implements the same WebSearchProvider interface. The operator's conversation LLM and the search provider are decoupled: using Anthropic's web search tool does not require Anthropic as the conversation model. All providers are model-independent HTTP APIs from the daemon's perspective.
• Off by default. web.search is not in any agent's default tool set, including the primary. Operators opt in per agent via the standard tools: block ("web.search": { enabled: true }). No principal_scope restriction.
• No cage interaction. web.search has no requires entries. It is a daemon-brokered outbound HTTP call, not a cage-mediated resource. The cage net.allow on the calling agent does not gate this tool — the daemon makes the outbound call, same trust model as LLM provider connections (per ADR-0011).
• Credentials flow. Per ADR-0011, provider credentials are operator-local. The DSL only enables the tool per agent; provider order, API keys, and per-provider timeouts live in local.toml. API keys are stored flat under [secrets.web] — key is the provider id, value is the API key (e.g., secrets.web.brave = "BSA-..."). This fits the existing 2-level secrets schema with no extension. Missing key → provider unavailable (not a startup error).
• Built-in, not MCP. ADR-0043 already provides MCP as an escape hatch (Brave, Exa, Tavily all ship MCP servers). web.search is a first-party built-in alongside that escape hatch because (a) the fallback chain is daemon-owned, (b) the response shape is normalised across providers, and (c) credentials configure once per operator, not per project. The two coexist.
• Redaction unchanged. redactSecrets() in @kaged/local-config already iterates all [secrets.*] sections generically, so [secrets.web] values are auto-redacted. No redactor code change was needed.
• Spec amendments required of this change: local-config.md gains a [web] section; 0033-tool-dot-namespace-convention.md §1 promotes web.search from "Future tools" to "Current tools".

2026-05-26 — ADR-0022: per-agent tools, kaged.issue.*/kaged.workflow.* namespaces, principal_scope

Per ADR-0022:

• ToolDefinition gains principal_scope?: "root-only" field. Tools with this field are rejected by the DSL parser on non-root agents and by the registry at dispatch time as defense-in-depth.
• Namespace table rewritten. The former kaged.* reserved row is replaced by two concrete namespaces: kaged.issue (6 tools: create, update, comment, transition, list, get) and kaged.workflow (3 tools: trigger, list, status). Both carry principal_scope: "root-only".
• ToolCallContext.caller now encodes tree-position path (e.g. "primary", "primary.subagents.scraper"). Root-only check is caller === "primary". cage_policy is null for agents with cage: disabled (was: "for primary").
• Per-agent tool resolution section added. Documents the resolution chain: built-in registry → role-based defaults → agent's tools: block → principal_scope enforcement → cage filter at dispatch. Project-level tools: block no longer exists; each agent declares its own tool surface.
• kaged.issue.* tool definitions added: kaged.issue.list, kaged.issue.get, kaged.issue.create, kaged.issue.update, kaged.issue.comment, kaged.issue.transition. Full parameter/return schemas, behavior, and error codes.
• kaged.workflow.* tool definitions added: kaged.workflow.list, kaged.workflow.trigger, kaged.workflow.status. Full parameter/return schemas, behavior, and error codes.
• Failure modes table extended with principal_scope_violation, issue/workflow not-found errors, invalid transitions, input validation failures, and file_input_not_supported.
• Audit events table extended with kaged.issue.created, kaged.issue.updated, kaged.issue.commented, kaged.issue.transitioned, kaged.workflow.triggered, kaged.workflow.status_checked.
• Tool availability table extended with kaged.issue.* and kaged.workflow.* rows (root agent only; principal_scope rejection for all other agents regardless of cage type).
• Testing notes extended with project management tool tests (31 cases) and principal scope enforcement tests (8 cases).

2026-05-27 — Bridge wiring complete: per-project cache, daemon shutdown, 87 handler tests

All 24 built-in tool handlers are now wired end-to-end in the daemon runtime. This amendment documents the implementation that closes the gap between the spec's bridge architecture sections and running code.

• @kaged/natives package created. Rust N-API crate (kaged-natives) with 14 exports (grep, glob, fuzzyFind, astGrep, astEdit, summarizeCode, listWorkspace, search, hasMatch, invalidateFsScanCache, getWorkProfile, AstMatchStrictness, FileType, GrepOutputMode). Vendored kaged-ast crate (from oh-my-pi's pi-ast). Platform-aware TS loader with lazy singleton. Release binary: 93MB (LTO fat + strip + panic abort, 50+ tree-sitter grammars).
• File handlers (file-handlers.ts). 4 handlers (file.read, file.write, edit.text, file.create) using pure Bun I/O. Path-traversal security, binary detection, pagination.
• Search handlers (search-handlers.ts). 3 handlers (search.grep, search.glob, search.ast_grep) calling @kaged/natives Rust N-API. PathCheck discriminated union with ToolErrorCode-typed codes. 18 tests.
• LSP handlers (lsp-handlers.ts). Unified code.lsp handler with action dispatch (14 actions: diagnostics, definition, references, symbols, rename, rename_file, code_actions, hover, type_definition, implementation, status, reload, capabilities, request) using LspBridge interface. PathCheck pattern with ToolErrorCode. 57 tests.
• DAP handlers (dap-handlers.ts). Unified debug handler with action dispatch (27 actions: 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) using DapBridge interface. Throws ToolCallError("dap_session_ended") when no bridge. 30 tests.
• LSP bridge runtime implemented per § LSP bridge architecture. lsp-jsonrpc.ts (Content-Length framing, JsonRpcParser, serializeMessage), lsp-client.ts (LspClient — Bun.spawn process lifecycle, JSON-RPC request/response correlation, initialize/initialized handshake, textDocument/didOpen/didChange file sync, publishDiagnostics cache, idle tracking, graceful shutdown), lsp-bridge-runtime.ts (LspBridgeRuntime — file-extension→server routing, on-demand client spawning, 10-min idle checker, all 8 bridge methods). 14 JSON-RPC tests.
• DAP bridge runtime implemented per § DAP bridge architecture. dap-client.ts (DapClient — Bun.spawn, DAP wire protocol with Content-Length framing + seq-based request/response, initialize/launch/attach/configurationDone sequence, event routing), dap-bridge-runtime.ts (DapBridgeRuntime — runtime adapter resolution for node/bun, all 9 bridge methods).
• Per-project bridge cache (bridge-cache.ts). getBridgesForProject(projectRoot) lazily creates LspBridgeRuntime + DapBridgeRuntime per project root. disposeAllBridges() for daemon shutdown. disposeBridgesForProject() for project unload.
• Daemon wiring. primary-runner.ts calls getBridgesForProject() at dispatch time and injects lspBridge/dapBridge into registerToolHandlers via ToolHandlerDeps. main.ts calls disposeAllBridges() in the shutdown sequence (after daemonServer.stop(), before broker.disposeAll()).
• Implements header updated. Changed from packages/agent-tooling/ (planned) to packages/agent-tooling/, packages/natives/, daemon tool handlers in packages/daemon/src/runtime/tool-handlers/.
• Remaining gaps. File sync tracker (LSP didChange notifications for external edits), audit event emission for tool calls. Both are v0.x concerns — the runtime is functional without them.

2026-05-27 — Issue tools, interaction tools, principal_scope enforcement implemented

Three new tool families implemented across @kaged/agent-tooling, @kaged/harness, and packages/daemon:

• kaged.issue.* tools implemented (5 tools, not 6). kaged.issue.create, kaged.issue.list, kaged.issue.get, kaged.issue.comment, kaged.issue.transition. The spec's kaged.issue.update was dropped — agents cannot edit base issue info (title/body/assignment); they can only comment and transition status. This is an additive-only design: agents file issues, comment on them, and move them through the state machine. Transition requires a comment for rejected and resolved statuses.
• kaged.ask + kaged.form interaction tools implemented (2 tools). Structured multi-question interaction (kaged.ask: questions array with id, title, description, options[], multiple flag) and dynamic data collection with file uploads (kaged.form: fields array with name, label, type, required, description; file uploads land in config:/tmp/<requestId>/). Both use the checkpoint-like pause/resume flow: session pauses → WS event → operator answers → new run.
• principal_scope: "root-only" enforcement implemented. ToolDefinition field added; ToolRegistry.dispatch() checks caller === "primary" before permission checks, returns principal_scope_violation error code. All 7 new tools (kaged.issue.* × 5 + kaged.ask + kaged.form) carry principal_scope: "root-only".
• Issue handler implementation (kaged-issue-handlers.ts). 5 handlers with IssueHandlerDeps (storage adapter dependency). Transition state machine: open→{triaged, assigned, in_progress, resolved, rejected}; resolved/rejected→{reopened}; reopened→same as open. Author tracking via agent:primary. resolvedAt/resolvedBy lifecycle on resolved status. 31 handler tests (70 expect() calls).
• Interaction signal flow in @kaged/harness. InteractionRequested type + InteractionKind ("ask" | "form") added to RunPrimaryResult. Mastra tools built in runPrimary closure with mutable interactionSignal, injected via kagedToolOverrides. Daemon handles interactionRequested signal via transitionSessionToCheckpoint with "interaction:" detail prefix. 5 new runtime tests.
• Config scaffolding. .kaged/.gitignore (ignores tmp/ and *.local.*) and .kaged/tmp/ directory created in initProjectDir.
• Namespace table updated. kaged namespace now has 8 tools: checkpoint (1) + issue (5) + interaction (2). Spec kaged.issue.update section retained for reference but the tool is not implemented — intentional deviation documented above.
• Error taxonomy extended. ToolErrorCode gains issue_not_found, invalid_transition, principal_scope_violation.
• ToolHandlerDeps extended with storage: StorageAdapter for issue handlers. registerToolHandlers wires all 31 tools (24 original + 5 issue + 2 interaction, though interaction tools are wired at the Mastra level in the harness, not via registerToolHandlers).
• Test counts. agent-tooling: 141 tests (was 136). harness: 127 tests (was 122). daemon: 862 tests (was 831). Total: 3,119 (was 3,065).

2026-06-04 — shell.bash tool: PTY-backed command execution

New shell namespace with a single tool for agent-driven command execution:

• shell.bash tool added. Execute shell commands via the daemon's PTY broker (PtyBroker.spawn()). Parameters: command (required), cwd, timeout, env. Returns: stdout, stderr (always empty — PTY merges streams), exit_code, timed_out. Non-zero exit codes are data, not errors.
• Namespace table extended. shell added as 6th built-in namespace. Reserved namespace list updated.
• ToolDefinition.namespace union extended with "shell".
• Permission model. Requires { kind: "capability", name: "shell" } + { kind: "fs", mode: "rw", path: "caller" }. Primary agent always allowed; caged subagents need explicit shell capability.
• PTY broker integration. Handler delegates to existing PtyBroker (threaded via ToolHandlerDeps.ptyBroker, not the getBrokerRef() singleton). Timeout enforcement uses broker's SIGTERM → 5s grace → SIGKILL escalation.
• Tool availability table extended with shell.bash row.
• Failure modes table extended with shell-specific failures: empty command, cwd escape, timeout, output truncation, spawn failure.
• Audit events extended with shell.executed.
• Testing notes extended with 11 shell tool test cases.

2026-06-05 — ADR-0034: kaged.todo tool, todo bubble-up

Per ADR-0034:

• kaged.todo tool added. Single root-only tool with 7 actions (view, set, add, start, done, drop, note). Operates implicitly on the session's bound issue. Content-addressed task lookup. Single-in_progress invariant enforced server-side. Two kinds: step (agent working plan) and criterion (acceptance criteria). Agent cannot drop criteria — only the operator can.
• Namespace table extended. kaged namespace now has 5 tool groups: checkpoint (1) + issue (5) + todo (1) + interaction (2) + workflow (3).
• Todo bubble-up section added. Documents how subagents propose checklists via delegation return values, the root reviews and persists via kaged.todo. Sibling of the issue bubble-up pattern.
• Tool availability table extended with kaged.todo row (root agent only; principal_scope rejection for all other agents).
• Failure modes table extended with no_bound_issue, todo_not_found, and criterion drop rejection.
• Audit events extended with kaged.todo.set, kaged.todo.added, kaged.todo.started, kaged.todo.completed, kaged.todo.dropped, kaged.todo.noted.
• Testing notes extended with 16 kaged.todo test cases.
• Error taxonomy extended. ToolErrorCode gains no_bound_issue, todo_not_found, session_not_found.
• Constrained-by list extended with ADR-0034.

2026-06-05: Live todo surfacing: sticky reminder, echo notes, content-addressing coaching

• Sticky reminder. A new ephemeral system-role message is injected near the tail of the messages array before each LLM call when the session has a bound issue with open todos. The reminder lists up to 5 open items (always including in_progress), formatted as a markdown checklist. It is not persisted, regenerated fresh each step. Suppressed when the immediately preceding turn already carries a kaged.todo tool result (preventing redundancy). Implemented in packages/daemon/src/runtime/sticky-todo-reminder.ts, wired into primary-runner.ts.
• Echo notes. The markdown output returned by every kaged.todo mutation now includes → note lines beneath the in_progress task's notes, giving the agent immediate visibility into its own scratch notes.
• Content-addressing coaching. Two new error behaviors on start, done, drop, note actions:
  • ID-like token rejection. If the content parameter matches /^(task|todo|item|step|id)-\d+$/i, the tool returns error code content_addressing_hint with guidance to use the task's full text instead of a synthetic ID.
  • Enhanced not-found. When content-addressed lookup fails, the todo_not_found error now includes a hint listing available items when the list is non-empty, or guidance that the list is empty when it is.
• content_addressing_hint error code added to ToolErrorCode union in @kaged/agent-tooling types.
• Failure modes table gains a row: | Agent uses ID-like token for todo content | Pattern match in handler | Error returned | Agent sees \content_addressing_hint` with guidance to use full task text. |`
• Testing notes kaged.todo section gains: content-addressing coaching tests (ID-like rejection, enhanced not-found with empty-list hint), sticky reminder tests (suppression, windowing, cap at 5).

2026-06-06 — edit.ast tool: AST-aware structural rewrite via ast-grep

• edit.ast tool implemented. Exposes the existing Rust N-API astEdit function as a daemon tool. Unified namespace: edit (not search), pairing with edit.text as the two editing modes (exact-string vs. structural). Dry-run by default (dry_run: true); agents must explicitly set dry_run: false to apply changes to disk.
• Tool definition added. EDIT_AST in packages/agent-tooling/src/builtins/file-tools.ts (or separate edit-tools.ts). Parameters: rewrites (required), lang, path, glob, dry_run, max_replacements, max_files. Returns: changes, file_changes, total_replacements, files_touched, files_searched, applied, limit_reached, parse_errors.
• Handler added. createEditAstHandler() in packages/daemon/src/runtime/tool-handlers/edit-handlers.ts (or search-handlers.ts). Resolves project-root-relative path, validates rewrites is a non-empty object, calls natives.astEdit() with dry_run: true by default, transforms native AstReplaceResult to daemon response shape.
• Registration. registerToolHandlers wires edit.ast alongside search.grep/search.glob/search.ast. ToolHandlerDeps unchanged.
• Default tools updated. edit.ast added to DEFAULT_ROOT_TOOLS in packages/dsl/src/defaults.ts (disabled by default, opt-in like edit.text).
• Spec updates. agent-tooling.md § Namespace table: edit namespace now has 2 tools (edit.text, edit.ast). Adoption table: ast_edit → search.ast / edit.ast (adapt). Open question #1 resolved. Testing notes: 10 new edit.ast test cases.
• Test updates. builtins.test.ts: FILE_TOOLS count 4→5, ALL_BUILTIN_TOOLS 17→18. New edit-handlers.test.ts (or search-handlers.test.ts extension): 10 tests covering dry-run, apply, path resolution, invalid pattern, language inference, max_replacements, max_files, path traversal, parse error collection, single-file vs directory.

References

• ADR-0004 — Bun runtime, FFI for Rust integration
• ADR-0008 — plugin model (tools are NOT plugins; this doc explains why)
• ADR-0009 — seccomp profiles, ptrace blocking, relaxed opt-in
• ADR-0010 — deployment modes tools must work under
• ADR-0011 — project-relative paths tools enforce
• ADR-0022 — recursive agents, per-agent tools, kaged.* namespaces
• sandbox.md — cage compiler, seccomp profiles, network gatekeeper
• plugin-host.md — plugin-declared methods that coexist with built-in tools in the registry
• session-manager.md — run model, tool_calls table, PTY broker
• task-runner.md — operator-initiated tasks (not agent tools)
• project-dsl.md — AgentSpec.tools and cage blocks that drive tool permissions
• issues.md — issue schema, status lifecycle, assignment semantics
• workflows.md — workflow schema, invocation lifecycle, tool intersection
• http-api.md — WebSocket framing for tool call/result streaming
• Language Server Protocol: https://microsoft.github.io/language-server-protocol/
• Debug Adapter Protocol: https://microsoft.github.io/debug-adapter-protocol/
• ast-grep: https://ast-grep.github.io/
• oh-my-pi file tools: https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo
• Bun FFI: https://bun.sh/docs/api/ffi
• Bun --inspect: https://bun.sh/docs/runtime/debugger