📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,172 @@
+# Delegation Patterns for Context Preservation
+
+How to delegate work to preserve main conversation context.
+
+> **TL;DR**: Subagents run in isolated contexts—only their summary returns. Delegate: 5+ file reads, codebase searches, specialized reviews. Keep in main: user Q&A, simple edits, files already in context. Use `run_in_background: true` for parallel work. Track delegated tasks with Tasks and agent IDs.
+
+## The Context Problem
+
+Main conversation context is ~128K tokens. Every operation consumes it:
+- Reading a file: file contents enter context
+- Search results: matches enter context
+- Reasoning: your analysis consumes tokens
+- Tool results: outputs accumulate
+
+Subagents run in **isolated contexts**. When they complete, only their final output (summary, findings, results) returns to main context. The files they read, searches they ran, reasoning they did — all stay in their isolated context.
+
+## Delegation Decision Matrix
+
+| Task Type | Delegate? | Agent | Why |
+|-----------|-----------|-------|-----|
+| Read 1-2 files | No | Main | Already focused |
+| Read 5+ files | Yes | Explore | Preserves main context |
+| Codebase search | Yes | Explore | Returns summary, not raw results |
+| Security review | Yes | outfitter:reviewer | Specialized + isolated |
+| Performance analysis | Yes | outfitter:analyst | Research-heavy |
+| Simple edit | No | Main | Quick, in-context |
+| Multi-file refactor | Yes | outfitter:engineer | Coordinates changes |
+| Test validation | Yes | outfitter:tester | Isolated execution |
+| User Q&A | No | Main | Needs conversation history |
+
+## Pattern: Research Delegation
+
+Instead of reading many files yourself:
+
+```json
+{
+  "description": "Find auth implementation",
+  "prompt": "Locate all authentication-related files. Summarize: (1) auth flow, (2) libraries used, (3) key entry points",
+  "subagent_type": "Explore"
+}
+```
+
+**Returns to main context**: ~50 lines of summary
+**Stayed in subagent context**: contents of 15 files
+
+## Pattern: Parallel Independent Reviews
+
+When multiple concerns need analysis:
+
+```json
+// All in single message, all run_in_background: true
+{
+  "description": "Security review",
+  "prompt": "Review src/auth/ for security vulnerabilities",
+  "subagent_type": "outfitter:reviewer",
+  "run_in_background": true
+}
+{
+  "description": "Performance review",
+  "prompt": "Analyze src/auth/ for performance issues",
+  "subagent_type": "outfitter:analyst",
+  "run_in_background": true
+}
+{
+  "description": "Test coverage",
+  "prompt": "Assess test coverage for src/auth/",
+  "subagent_type": "outfitter:tester",
+  "run_in_background": true
+}
+```
+
+Three reviews run simultaneously. Main agent stays responsive. Collect results with `TaskOutput` when ready.
+
+## Pattern: Sequential Handoff with Context
+
+When later agents need earlier agents' output:
+
+```
+1. outfitter:analyst researches → returns findings
+2. Main agent extracts key points
+3. outfitter:engineer implements → receives key points in prompt
+4. outfitter:reviewer reviews → receives implementation summary
+```
+
+Don't pass full agent output to next agent. Extract and summarize.
+
+## Pattern: Resumable Long-Running Work
+
+For multi-stage work:
+
+```json
+// Stage 1
+{
+  "description": "Begin auth analysis",
+  "prompt": "Analyze authentication patterns in src/auth/",
+  "subagent_type": "outfitter:analyst"
+}
+// Returns agent-id: abc123
+
+// Stage 2 (later)
+{
+  "description": "Continue auth analysis",
+  "prompt": "Now examine the session management aspect",
+  "subagent_type": "outfitter:analyst",
+  "resume": "abc123"
+}
+```
+
+Agent preserves its full context across invocations. Main agent stays lean.
+
+## What to Keep in Main Context
+
+Not everything should be delegated:
+
+**Keep in main**:
+- Direct user interaction
+- Final synthesis and decisions
+- Coordination logic
+- Files already read (don't re-delegate)
+- Simple, quick operations
+
+**Delegate**:
+- Exploratory research
+- Multi-file analysis
+- Specialized reviews
+- Test execution
+- Background validation
+
+## Task Integration
+
+Track delegated work with Tasks:
+
+```
+#1: "[analyst] Research caching patterns" - pending, metadata: {agentId: "abc123", background: true}
+#2: "Wait for analyst results" - pending, blockedBy: #1
+#3: "[engineer] Implement cache layer" - pending, blockedBy: #2
+#4: "[reviewer] Review implementation" - pending, blockedBy: #3
+```
+
+Update when agents complete:
+
+```
+#1: "[analyst] Research caching patterns" - completed, description: "Redis recommended"
+#2: "Wait for analyst results" - completed, description: "Redis approach confirmed"
+#3: "[engineer] Implement Redis cache layer" - in_progress
+```
+
+## Anti-Patterns
+
+**Delegating simple work**: Single file edit doesn't need an agent.
+
+**Over-parallelization**: Don't run 10 agents when 3 would do.
+
+**Missing handoff context**: Agents need enough info to act independently.
+
+**Forgetting to collect**: Background agents finish but results never retrieved.
+
+**Re-delegating**: If file already in context, don't send agent to read it again.
+
+## Context Budget Mental Model
+
+Think of context as a budget:
+
+```
+Total: 128K tokens
+System prompts: ~10K
+User messages: ~5K
+Your reasoning: ~20K
+Tool results: ~???
+```
+
+Every file read, search result, and agent output draws from `tool results`. Delegation shifts that cost to isolated contexts, keeping main budget available for synthesis and user interaction.