multi-agent-orchestrationlisted

# Multi-Agent Orchestration ## Overview Treat a multi-agent system as a constrained production system, not as a loose collection of helpers. Define role contracts, context shape, permissions, tools, MCP access, records, and cleanup before any agent starts working. ## Source Anchors - `src/tools/AgentTool/` - `src/tools/AgentTool/runAgent.ts` - `src/tools/AgentTool/built-in/` ## Workflow 1. Decide which work must stay on the main critical path and which work can be delegated. 2. Write an explicit contract for each agent type: goal, allowed tools, default model, async or sync behavior, and permission strategy. 3. Choose a context strategy for each agent: full fork, slim fork, or task-only prompt. 4. Scope permissions so parent session grants do not leak into child agents by accident. 5. Preload the right skills, frontmatter hooks, and agent-specific MCP servers before execution starts. 6. Record transcripts, metadata, parent-child hierarchy, and progress messages so runs stay auditable and resumable. 7. Define stop conditions such as `maxTurns`, abort propagation, and completion callbacks. 8. In `finally`, clean up MCP clients, session hooks, prompt-cache tracking, file state, and orphaned todo entries. ## Design Rules - Keep final responsibility on the main agent. Delegation does not delegate accountability. - Separate sync collaboration from async background work because permission behavior differs. - Treat agent-specific MCP as additive, and only clean up the connect