agent-orchestration

Local dispatch: the Agent tool

The Agent tool spawns a subagent in the current session. subagent_type: "fork" forks the caller — full conversation context, same model, shares the prompt cache — and is the right default whenever intermediate output isn't worth keeping in the parent's context. Any other subagent_type (or omitting it) starts a fresh agent with zero memory of the conversation; brief it like a colleague who just walked in.

Parallel dispatch: independent tasks go in a single message with multiple Agent tool calls — that is what makes them run concurrently. Sequential calls across separate messages block on each other.

Custom subagents: define reusable ones at .claude/agents/<name>.md. Frontmatter controls model, tools, and permissions:

---
name: my-agent
model: sonnet            # explicit model always — see assigning-subagent-models
tools: [Bash, Read, Grep]
---
System prompt / instructions for this agent go here.

The homelab's built-in agents (verify-deployment.md, validate-k8s.md, code-reviewer.md, k8s-debugger.md, nix-explorer.md, meta-reviewer.md, skill-optimizer.md) come from ~/claude-code-skills/agents/ and are symlinked into ~/.claude/agents by Home Manager — edit them in that repo, push, then just bump skills + just switch in ~/nixos-config; never edit the linked file directly.

Every spawn needs an explicit model — see the assigning-subagent-models skill for the effort-tier ladder. Don't leave a subagent to silently inherit the parent's model.

Remote dispatch: running on another machine

For work that needs a different host (not just isolation — an actual remote machine), use herdr, the terminal workspace manager, to open a session on that host and run claude there. herdr sessions on the existing hosts are the only remote pattern; there is no VM-provisioning layer.

Decision Matrix

Known Gotchas

• A forked agent's tool output isn't yours until it reports back. Never fabricate or predict a fork's results — wait for the completion notification.
• isolation: "worktree" only helps inside a git repo — it creates a git worktree, auto-cleaned if the agent makes no changes; otherwise the path/branch are returned.
• Don't re-delegate your whole assignment to one subagent when you're already the agent assigned to a task — use subagents for sub-tasks you'd otherwise have to context-switch out of, not as a proxy for the whole job.