/dispatching-coding-agents

name: dispatching-coding-agents
description: Dispatch stateless coding agents through Claude Code or Codex. Model catalog checked 2026-08-25: Claude Code includes Sonnet 5, Opus 5, and Fable 5; Codex includes GPT-5.6 Luna, Terra, and Sol. Use when you're stuck, need a second opinion, or need parallel research on a hard problem. They have no memory, so you must provide all context.

Dispatching Coding Agents

You can shell out to **Claude Code** (`claude`) and **Codex** (`codex`) as stateless sub-agents via Bash. They have filesystem and tool access (scope depends on sandbox/approval settings) but **zero memory** — every session starts from scratch.

**Default to `run_in_background: true`** on the Bash call so you can keep working while they run. Check results later with `TaskOutput`. Don't sit idle waiting for a subagent.

The Core Mental Model

Claude Code and Codex are highly optimized coding agents, but are re-born with each new session. Think of them like a brilliant intern that showed up today. Provide them with the right instructions and context to help them succeed and avoid having to re-learn things that you've learned.

You are the experienced manager with persistent memory of the user's preferences, the codebase, past decisions, and hard-won lessons. **Give them context, not a plan.** They won't know anything you don't tell them:

• **Specific task**: Be precise about what you need — not "look into the auth system" but "trace the request flow from the messages endpoint through to the LLM call, cite files and line numbers."
• **File paths and architecture**: Tell them exactly where to look and how pieces connect. They will wander aimlessly without this.
• **Preferences and constraints**: Code style, error handling patterns, things the user has corrected you on. Save them from making mistakes you already learned from.
• **What you've already tried**: If you're dispatching because you're stuck, this prevents them from rediscovering your dead ends.

If a subagent needs clarification or asks a question, respond in the same session (see Session Resumption below) — don't start a new session or you'll lose the conversation context.

When to Dispatch (and When Not To)

Dispatch for:

• **Hard debugging** — you've been looping on a problem and need fresh eyes
• **Second opinions** — you want validation before a risky change
• **Parallel research** — investigate multiple hypotheses simultaneously
• **Large-scope investigation** — tracing a flow across many files in an unfamiliar area
• **Code review** — have another agent review your diff or plan

Don't dispatch for:

• Simple file reads, greps, or small edits — faster to do yourself
• Anything that takes less than ~3 minutes of direct work
• Tasks where you already know exactly what to do
• When context transfer would take longer than just doing the task

Choosing an Agent and Model

Different agents have different strengths. Track what works in your memory over time — your own observations are more valuable than these defaults.

Categories

**Codex (catalog checked 2026-08-25):**

• `gpt-5.6-luna`: high-throughput, lower-latency work
• `gpt-5.6-terra`: strong performance with a balance of intelligence and cost
• `gpt-5.6-sol`: quality-first flagship for difficult coding and reasoning
• Use the configured default unless the user requests a model. Pass a requested model with `-m`, for example `codex exec "YOUR PROMPT" -m gpt-5.6-sol --sandbox workspace-write`.
• If a requested model is rejected, inspect the installed CLI and account configuration rather than guessing another model name.

**Claude Code (catalog checked 2026-08-25):**

• The current flagship models are Sonnet 5, Opus 5, and Fable 5. Use the configured default unless the user requests a model.
• Claude Code's stable aliases follow its current catalog:
• `best`: highest-capability model available to the account, using Fable 5 when available
• `fable`: Fable 5 for the hardest, longest-running tasks
• `opus`: Opus 5 for complex reasoning, docs, refactors, and open-ended tasks
• `sonnet`: Sonnet 5 for everyday coding
• `haiku`: fast, simple tasks
• Pass an alias with `--model`, for example `claude -p "YOUR PROMPT" --model fable --dangerously-skip-permissions`.
• Aliases update as Claude Code's catalog changes. If an alias is rejected, inspect the installed CLI version and account access rather than guessing a versioned model name.

Cost and speed tradeoffs

• Use each CLI's configured default model unless the task requires a model the user explicitly requested
• Use `--max-budget-usd N` (Claude Code) to cap spend on exploratory tasks

Known quirks

• **Claude Code can hang on large repos** with unrestricted tools — consider `--tools "Read Grep Glob"` (no Bash) and shorter timeouts for research tasks
• **Codex compactions can destroy long trajectories** — for very long tasks, prefer multiple shorter sessions over one marathon
• **Opus tends to over-generate** — produces more code than necessary. Good for exploration, verify before applying.

Prompting Subagents

Prompt template

TASK: [one-sentence summary]

CONTEXT:
- Repo: [path]
- Key files: [list specific files and what they contain]
- Architecture: [brief relevant context]

WHAT TO DO:
[what you need done — be precise, but let them figure out the approach]

CONSTRAINTS:
- [any preferences, patterns to follow, things to avoid]
- [what you've already tried, if dispatching because stuck]

OUTPUT:
[what you want back — a diff, a list of files, a root cause analysis, etc.]

What makes a good prompt

• **Be specific about files** — "look at `src/agent/message.ts` lines 40-80" not "look at the message handling code"
• **State the output format** — "return a bullet list of findings" vs. leaving it open-ended
• **Include constraints** — if the user prefers certain patterns, say so explicitly
• **Provide what you've tried** — when dispatching because you're stuck, this preven