docs(agents): Subagents-Sektion überarbeitet — Delegations-Default, fork, SendMessage statt task_id

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wcGPTAnGpH7wFGXCGQjtw

agents/AGENTS-claude.md

@@ -11,12 +11,30 @@
 - Two shortcuts past onyx: Thicket MCP for people lookups (role, team,
   email — its other sections are thin), Confluence CQL for precise
   lookups with known space/title.
+- Same-topic follow-ups: use `onyx answer "..." --session <last session_id>`.
 
 ## Subagents
 
-Spawn subagents to (a) isolate context-heavy work from the main thread, or (b) parallelize independent subtasks. Before spawning, ask: *could `Bash`/`Grep`/`Read` do this directly?* Subagents have overhead — skip the middleman for mechanical lookups.
+**Default to delegating whenever the expected tool output exceeds the
+conclusion the main thread actually needs** — multi-file research, log/data
+analysis, doc review, broad searches, verification runs. The session context
+is the scarce resource; a subagent burns its own context and returns only the
+result. Work inline only for single-fact lookups where file and symbol are
+already known — there, a subagent is pure overhead.
 
-Use the `Agent` tool. Prefer specialized agent types (`Explore`, `code-reviewer`, `Plan`, etc.) over `general-purpose` when one fits.
+Use the `Agent` tool. Prefer specialized agent types over `general-purpose`
+when one fits:
+
+- **`Explore`** — read-only search: *locates* code and facts (reads excerpts,
+  not whole files). It does not review or audit; quality judgments stay with
+  the parent or a dedicated reviewer.
+- **`Plan`** — implementation strategy, architecture trade-offs.
+- **`fork`** (`subagent_type: "fork"`) — inherits the full conversation
+  context, runs in the background, keeps its tool output out of the main
+  thread. The tool of choice for "do X with everything you already know, give
+  me only the outcome" — no need to re-explain state in the prompt.
+- Agent types not listed as available in the session (e.g. a `code-reviewer`)
+  don't exist there — check the available-types list instead of guessing.
 
 ### Behavioral tier (MANDATORY — always set)
 
@@ -28,15 +46,21 @@ Prefix every `Agent` prompt with one of:
 
 ### Model selection (override only when needed)
 
-Resolution order: explicit `model` param → agent type frontmatter → parent inheritance.
+Resolution order: explicit `model` param → agent type frontmatter → parent
+inheritance. (`fork` always runs on the parent model; an override is ignored.)
 
-1. **Don't override specialized agent types** (`Explore`, `code-reviewer`, `Plan`, etc.) — their frontmatter is tuned. Leave `model` off.
+1. **Don't override specialized agent types** (`Explore`, `Plan`, etc.) — their frontmatter is tuned. Leave `model` off.
-2. **For `general-purpose` under an Opus parent: set `model: sonnet`** — avoid paying Opus rates for routine subagent work.
+2. **For `general-purpose` under an expensive parent (Opus/Fable): set `model: sonnet`** — don't pay top rates for routine subagent work.
-3. **`model: opus`** on a subagent only when isolated context *and* reasoning beyond what the parent can easily do inline are both needed.
+3. **A bigger model (`opus`)** on a subagent only when isolated context *and* reasoning beyond what the parent can easily do inline are both needed.
 4. **`model: haiku`** only for mechanical tasks: bulk classification, format conversion, summarizing pre-filtered text. Code-semantic work → Sonnet.
 
 ### Context hygiene
 
-- Prefer parallel `Explore` calls over sequential `general-purpose` sessions.
+- Prefer parallel `Explore` calls over sequential `general-purpose` sessions;
-- Don't reuse `task_id` for fresh lookups; start new to keep prompts tiny.
+  spawn independent agents in a single message so they run concurrently.
-- Summarize subagent findings in the main thread to keep the terminal clean.
+- Once delegated, don't duplicate: never run the same search yourself while
+  an agent is on it, and don't poll — results arrive as notifications.
+- Follow-ups to an existing agent go via `SendMessage` (keeps its context);
+  a new `Agent` call always starts fresh — right for unrelated lookups.
+- Summarize subagent findings in the main thread; the raw report is not
+  shown to the user, so relay what matters.