Subagents & pathfinder

Markdown agents

An agent is a markdown file with frontmatter; the body becomes its system prompt:

---
name: reviewer
description: Cold code review focused on correctness and edge cases
max-steps: 12
---
You are a meticulous reviewer. Read the diff, then the surrounding
code. Report only findings you can trace to a line; rank by severity.
---

<!-- .ka/agents/reviewer.md -->

Discovered in .ka/agents/, .agents/agents/, .claude/agents/, and ~/.config/ka/agents/. ka agents lists them; /agents manages them in the TUI.

The model delegates self-contained subtasks to these agents through the delegate tool. A delegated agent runs as a nested voice with its own step budget and returns a dense summary; the full transcript of the subtask stays out of your context.

Worktree isolation

Add isolate: true to the frontmatter and the delegate runs in a fresh git worktree on its own branch; the subagent can edit and test freely without touching your working tree. When it returns, the tasks hand’s merge action applies the surviving worktree branch to your working tree as an uncommitted change to review and commit (gated by your permission mode like any write); if it doesn’t apply cleanly, the .patch file path is surfaced instead and nothing is forced. Files the main voice had read before the merge are named in the result with a read-file conflict advisory (paths probe worktree-root-relative, so subdirectory launches work), and the read ledger still refuses a stale edit on them.

---
name: experimenter
description: Try risky refactors in isolation
isolate: true
---
…

pathfinder

pathfinder is the built-in read-only research subagent: the pattern delegate generalizes. When the model needs to explore (“where is auth handled?”), it can dispatch pathfinder, which gets inspect-only tools and returns a dense summary. Exploration noise never floods your main thread.

Output contracts

Add an output: frontmatter field with a JSON schema and the delegate’s final message is validated against it (the same structured-output path as ka run --schema), with one instructive retry on a mismatch. Useful when a delegated result must feed a script or another agent in a predictable shape.

---
name: auditor
description: Inventory public API changes
isolate: true
output: {"type":"object","properties":{"added":{"type":"array"},"removed":{"type":"array"}},"required":["added","removed"]}
---
…

Why summaries, not transcripts

Subagent transcripts are serialized into their own strands. The parent context receives the distilled result only: the same context survival approach applied to delegation.