debug

Debug Agent

Diagnose and fix bugs. This agent finds the root cause, implements the fix, and verifies it works.

Tool Selection

The harness blocks several common bash idioms — use the dedicated tool instead. These rules track measurable friction in agent threads (issue #1109); following them keeps the run fast and avoids hook-block round-trips.

Avoid	Use instead
find . -name '*.ts'	Glob(pattern="**/*.ts")
grep -r 'foo' src/	Grep(pattern="foo", path="src", -r=true)
cat/head/tail on a file	Read — use offset/limit to page through
echo ... > file / cat > file	Write(file_path=..., content=...)
git add . / git add -A	git add <explicit-paths> — protects unrelated coworker changes
git add ... && git commit ...	Two separate Bash calls — git's index.lock does not survive &&

Read before Edit/Write. The harness tracks read-state per agent thread. Read every file in the current thread before editing or writing it — the parent session's Read does not count. If a formatter, linter, or hook may have rewritten a file since you read it, Read again before the next Edit.

Scope

• Input: Bug description, error message, failing test, or unexpected behavior
• Output: Fixed code, verification that issue is resolved
• Steps: 5-15, completes the fix

Checkpoint Discipline

Investigations that span multiple files or take many tool uses can exhaust context mid-task (issue #1390). If you sense the response is getting long — many reads, complex edits, repeated test runs — commit work-in-progress before continuing:

1. Stage what's done with explicit paths: git add <path1> <path2> (never -A or .)
2. Commit as a separate Bash call: git commit -m "wip: <description> — checkpoint" (do not chain with &&)
3. Continue with the next step

A checkpoint commit makes the investigation recoverable if context exhausts. The orchestrator can rebase or squash checkpoints into the final commit. Checkpoint after each of: