| 1 | import type { DocsSubagentsDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/subagents/page.tsx`. |
| 5 | * Copy moved verbatim from the page's `isZh` ternaries — any wording change |
| 6 | * belongs in its own commit, never mixed into a structural move. |
| 7 | */ |
| 8 | export const docsSubagents: DocsSubagentsDict = { |
| 9 | metaTitle: "Sub-Agents · Codewhale Docs", |
| 10 | metaDescription: |
| 11 | "The agent tool, fleet roles, context forking, worktree isolation, and concurrency caps.", |
| 12 | bodyClassName: "text-ink-soft leading-relaxed", |
| 13 | overviewTitle: "Sub-Agents", |
| 14 | overviewLead: |
| 15 | "A parent session launches one focused sub-agent through the agent tool and immediately gets back an agent_id, a compact receipt, and a transcript handle while the worker runs in the background. Sub-agents inherit the parent's tool registry by default, but they are leaf workers: they do not receive agent or nested lifecycle tools. agent launches detached background work — cancelling the parent turn stops the parent's wait path, but it does not kill already-opened child runs.", |
| 16 | overviewFleetNote: |
| 17 | "For work that must survive process restarts, sleep, or remote execution, prefer a fleet or a Workflow-backed fleet run over a short in-session agent call.", |
| 18 | roles: [ |
| 19 | [ |
| 20 | "worker", |
| 21 | "Flexible multi-step execution of the parent's brief; writes and shell allowed. The default role.", |
| 22 | ], |
| 23 | ["scout", "Read-only, maps the relevant code fast — “find every call site of Foo.”"], |
| 24 | [ |
| 25 | "planner", |
| 26 | "Analyse and produce a strategy without executing — “design the migration; don't run it.”", |
| 27 | ], |
| 28 | ["reviewer", "Read-and-grade with severity scores — “audit this PR for bugs.”"], |
| 29 | ["builder", "Land a specific change with minimal edits; writes and shell allowed."], |
| 30 | ["verifier", "Run tests and validation gates and report the outcome; no code edits."], |
| 31 | [ |
| 32 | "consultant", |
| 33 | "Read-only high-reasoning counsel for judgement calls and design critique.", |
| 34 | ], |
| 35 | ["custom", "An explicit narrow tool allowlist for locked-down dispatch."], |
| 36 | ], |
| 37 | forkTitle: "Context forking", |
| 38 | forkLead: |
| 39 | "{agentTool} starts fresh by default: the child gets its role prompt plus the task you pass. When the task depends on decisions, files, todos, or plan state already in the parent transcript, use {forkContext} — the runtime keeps the parent's request prefix byte-identical where available (preserving prefix-cache reuse), appends a structured state snapshot, then adds the sub-agent role instructions and task at the tail. Use fresh sessions for independent exploration and forked sessions for continuation, review, summarization, or compaction work.", |
| 40 | worktreeTitle: "Worktree isolation", |
| 41 | worktreeLead: |
| 42 | "Launch parallel edit lanes with {worktreeFlag}: Codewhale creates a fresh git worktree and branch for the child (default {branchPattern}, checked out beside the parent repo under {worktreeDir}) so the parent checkout stays clean. Isolation is not write authority: a prompt-only worker starts read-only, and a writer also declares {writeAuthority} plus at least one normalized {writeRoots}, {exactFiles}, or {coordinationContracts} value. Overlapping shared write claims fail before any mutation.", |
| 43 | capacityTitle: "Concurrency caps", |
| 44 | capacityLead: |
| 45 | "The sub-agent capacity source of truth is crates/tui/src/config/subagent_limits.rs: default configured concurrency is 64, maximum configured concurrency is 128, and maximum admitted running-plus-queued work is 1024. These are capacity ceilings, not advice to dispatch every slot — a manager should use the smallest useful fan-out, keep a single fan-in owner, and verify worker receipts before reporting combined completion.", |
| 46 | sourceNote: "Source document: docs/SUBAGENTS.md · Update docs-map.ts when changing.", |
| 47 | }; |
| 48 |