From 3313ec3e4f86a96a98c4b3f91b4545110a9beeef Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Wed, 18 Feb 2026 01:26:19 +0900 Subject: [PATCH] chore: regenerate AGENTS.md knowledge base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode) assistance --- AGENTS.md | 14 ++--- src/AGENTS.md | 8 +-- src/cli/run/AGENTS.md | 56 ++++++++++++++++++ src/features/AGENTS.md | 5 +- src/features/background-agent/AGENTS.md | 56 ++++++++++++++++++ src/features/opencode-skill-loader/AGENTS.md | 59 +++++++++++++++++++ src/features/tmux-subagent/AGENTS.md | 52 ++++++++++++++++ src/hooks/AGENTS.md | 11 ++-- .../AGENTS.md | 49 +++++++++++++++ src/plugin/AGENTS.md | 49 +++++++++++++++ src/tools/delegate-task/AGENTS.md | 58 ++++++++++++++++++ 11 files changed, 400 insertions(+), 17 deletions(-) create mode 100644 src/cli/run/AGENTS.md create mode 100644 src/features/background-agent/AGENTS.md create mode 100644 src/features/opencode-skill-loader/AGENTS.md create mode 100644 src/features/tmux-subagent/AGENTS.md create mode 100644 src/hooks/anthropic-context-window-limit-recovery/AGENTS.md create mode 100644 src/plugin/AGENTS.md create mode 100644 src/tools/delegate-task/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 36a8a2d8..36c0d262 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ # oh-my-opencode — OpenCode Plugin -**Generated:** 2026-02-17 | **Commit:** aac79f03 | **Branch:** dev +**Generated:** 2026-02-18 | **Commit:** 04e95d7e | **Branch:** dev ## OVERVIEW -OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 41 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1164 TypeScript files, 133k LOC. +OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 44 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1149 TypeScript files, 132k LOC. ## STRUCTURE @@ -14,14 +14,14 @@ oh-my-opencode/ │ ├── index.ts # Plugin entry: loadConfig → createManagers → createTools → createHooks → createPluginInterface │ ├── plugin-config.ts # JSONC multi-level config: user → project → defaults (Zod v4) │ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior) -│ ├── hooks/ # 41 hooks across 37 directories + 6 standalone files +│ ├── hooks/ # 44 hooks across 39 directories + 6 standalone files │ ├── tools/ # 26 tools across 15 directories -│ ├── features/ # 18 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.) +│ ├── features/ # 19 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.) │ ├── shared/ # 101 utility files in 13 categories │ ├── config/ # Zod v4 schema system (22 files) │ ├── cli/ # CLI: install, run, doctor, mcp-oauth (Commander.js) │ ├── mcp/ # 3 built-in remote MCPs (websearch, context7, grep_app) -│ ├── plugin/ # 8 OpenCode hook handlers + 41 hook composition +│ ├── plugin/ # 8 OpenCode hook handlers + 44 hook composition │ └── plugin-handlers/ # 6-phase config loading pipeline ├── packages/ # Monorepo: comment-checker, opencode-sdk └── local-ignore/ # Dev-only test fixtures @@ -34,7 +34,7 @@ OhMyOpenCodePlugin(ctx) ├─→ loadPluginConfig() # JSONC parse → project/user merge → Zod validate → migrate ├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler ├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry (26 tools) - ├─→ createHooks() # 3-tier: Core(32) + Continuation(7) + Skill(2) = 41 hooks + ├─→ createHooks() # 3-tier: Core(35) + Continuation(7) + Skill(2) = 44 hooks └─→ createPluginInterface() # 8 OpenCode hook handlers → PluginInterface ``` @@ -86,7 +86,7 @@ Fields: agents (14 overridable), categories (8 built-in + custom), disabled_* ar - **Test pattern**: Vitest, co-located `*.test.ts`, given/when/then style - **Factory pattern**: `createXXX()` for all tools, hooks, agents -- **Hook tiers**: Session (19) → Tool-Guard (9) → Transform (4) → Continuation (7) → Skill (2) +- **Hook tiers**: Session (22) → Tool-Guard (9) → Transform (4) → Continuation (7) → Skill (2) - **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all` - **Model resolution**: 3-step: override → category-default → provider-fallback → system-default - **Config format**: JSONC with comments, Zod v4 validation, snake_case keys diff --git a/src/AGENTS.md b/src/AGENTS.md index 209c7adb..5686e362 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -1,6 +1,6 @@ # src/ — Plugin Source -**Generated:** 2026-02-17 +**Generated:** 2026-02-18 ## OVERVIEW @@ -14,7 +14,7 @@ Root source directory. Entry point `index.ts` orchestrates 4-step initialization | `plugin-config.ts` | JSONC parse, multi-level merge (user → project → defaults), Zod validation | | `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler | | `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry | -| `create-hooks.ts` | 3-tier hook composition: Core(32) + Continuation(7) + Skill(2) | +| `create-hooks.ts` | 3-tier hook composition: Core(35) + Continuation(7) + Skill(2) | | `plugin-interface.ts` | Assembles 8 OpenCode hook handlers into PluginInterface | ## CONFIG LOADING @@ -32,8 +32,8 @@ loadPluginConfig(directory, ctx) ``` createHooks() - ├─→ createCoreHooks() # 32 hooks - │ ├─ createSessionHooks() # 19: contextWindowMonitor, thinkMode, ralphLoop, sessionRecovery... + ├─→ createCoreHooks() # 35 hooks + │ ├─ createSessionHooks() # 22: contextWindowMonitor, thinkMode, ralphLoop, sessionRecovery, jsonErrorRecovery, sisyphusGptHephaestusReminder, taskReminder... │ ├─ createToolGuardHooks() # 9: commentChecker, rulesInjector, writeExistingFileGuard... │ └─ createTransformHooks() # 4: claudeCodeHooks, keywordDetector, contextInjector, thinkingBlockValidator ├─→ createContinuationHooks() # 7: todoContinuationEnforcer, atlas, stopContinuationGuard... diff --git a/src/cli/run/AGENTS.md b/src/cli/run/AGENTS.md new file mode 100644 index 00000000..f33f3ea3 --- /dev/null +++ b/src/cli/run/AGENTS.md @@ -0,0 +1,56 @@ +# src/cli/run/ — Non-Interactive Session Launcher + +**Generated:** 2026-02-18 + +## OVERVIEW + +37 files. Powers the `oh-my-opencode run ` command. Connects to OpenCode server, creates/resumes sessions, streams events, and polls for completion. + +## EXECUTION FLOW + +``` +runner.ts + 1. opencode-binary-resolver.ts → Find OpenCode binary + 2. server-connection.ts → Connect to OpenCode server (start if needed) + 3. agent-resolver.ts → Flag → env → config → Sisyphus + 4. session-resolver.ts → Create new or resume existing session + 5. events.ts → Stream SSE events from session + 6. event-handlers.ts → Process each event type + 7. poll-for-completion.ts → Wait for todos + background tasks done + 8. on-complete-hook.ts → Execute user-defined completion hook +``` + +## KEY FILES + +| File | Purpose | +|------|---------| +| `runner.ts` | Main orchestration — connects, resolves, runs, completes | +| `server-connection.ts` | Start OpenCode server process, create SDK client | +| `agent-resolver.ts` | Resolve agent: `--agent` flag → `OPENCODE_AGENT` env → config → Sisyphus | +| `session-resolver.ts` | Create new session or resume via `--attach` / `--session-id` | +| `events.ts` | SSE event stream subscription | +| `event-handlers.ts` | Route events to handlers (message, tool, error, idle) | +| `event-stream-processor.ts` | Process event stream with filtering and buffering | +| `poll-for-completion.ts` | Poll session until todos complete + no background tasks | +| `completion.ts` | Determine if session is truly done | +| `continuation-state.ts` | Persist state for `run` continuation across invocations | +| `output-renderer.ts` | Format session output for terminal | +| `json-output.ts` | JSON output mode (`--json` flag) | +| `types.ts` | `RunOptions`, `RunResult`, `RunContext`, event payload types | + +## AGENT RESOLUTION PRIORITY + +``` +1. --agent CLI flag +2. OPENCODE_AGENT environment variable +3. default_run_agent config +4. "sisyphus" (default) +``` + +## COMPLETION DETECTION + +Poll-based with two conditions: +1. All todos marked completed (no pending/in_progress) +2. No running background tasks + +`on-complete-hook.ts` executes optional user command on completion (e.g., `--on-complete "notify-send done"`). diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index ebf98eab..9c1b596b 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -1,6 +1,6 @@ -# src/features/ — 18 Feature Modules +# src/features/ — 19 Feature Modules -**Generated:** 2026-02-17 +**Generated:** 2026-02-18 ## OVERVIEW @@ -27,6 +27,7 @@ Standalone feature modules wired into plugin/ layer. Each is self-contained with | **claude-code-agent-loader** | 3 | LOW | Load agents from .opencode/agents/ | | **claude-code-command-loader** | 3 | LOW | Load commands from .opencode/commands/ | | **claude-code-session-state** | 2 | LOW | Subagent session state tracking | +| **run-continuation-state** | 5 | LOW | Persistent state for `run` command continuation across sessions | | **tool-metadata-store** | 2 | LOW | Tool execution metadata cache | ## KEY MODULES diff --git a/src/features/background-agent/AGENTS.md b/src/features/background-agent/AGENTS.md new file mode 100644 index 00000000..90f29c74 --- /dev/null +++ b/src/features/background-agent/AGENTS.md @@ -0,0 +1,56 @@ +# src/features/background-agent/ — Core Orchestration Engine + +**Generated:** 2026-02-18 + +## OVERVIEW + +39 files (~10k LOC). Manages async task lifecycle: launch → queue → run → poll → complete/error. Concurrency limited per model/provider (default 5). Central to multi-agent orchestration. + +## TASK LIFECYCLE + +``` +LaunchInput → pending → [ConcurrencyManager queue] → running → polling → completed/error/cancelled/interrupt +``` + +## KEY FILES + +| File | Purpose | +|------|---------| +| `manager.ts` | `BackgroundManager` — main class: launch, cancel, getTask, listTasks | +| `spawner.ts` | Task spawning: create session → inject prompt → start polling | +| `concurrency.ts` | `ConcurrencyManager` — FIFO queue per concurrency key, slot acquisition/release | +| `task-poller.ts` | 3s interval polling, completion via idle events + stability detection (10s unchanged) | +| `result-handler.ts` | Process completed tasks: extract result, notify parent, cleanup | +| `state.ts` | In-memory task store (Map-based) | +| `types.ts` | `BackgroundTask`, `LaunchInput`, `ResumeInput`, `BackgroundTaskStatus` | + +## SPAWNER SUBDIRECTORY (6 files) + +| File | Purpose | +|------|---------| +| `spawner-context.ts` | `SpawnerContext` interface composing all spawner deps | +| `background-session-creator.ts` | Create OpenCode session for background task | +| `concurrency-key-from-launch-input.ts` | Derive concurrency key from model/provider | +| `parent-directory-resolver.ts` | Resolve working directory for child session | +| `tmux-callback-invoker.ts` | Notify TmuxSessionManager on session creation | + +## COMPLETION DETECTION + +Two signals combined: +1. **Session idle event** — OpenCode reports session became idle +2. **Stability detection** — message count unchanged for 10s (3+ stable polls at 3s interval) + +Both must agree before marking a task complete. Prevents premature completion on brief pauses. + +## CONCURRENCY MODEL + +- Key format: `{providerID}/{modelID}` (e.g., `anthropic/claude-opus-4-6`) +- Default limit: 5 concurrent per key (configurable via `background_task` config) +- FIFO queue: tasks wait in order when slots full +- Slot released on: completion, error, cancellation + +## NOTIFICATION FLOW + +``` +task completed → result-handler → parent-session-notifier → inject system message into parent session +``` diff --git a/src/features/opencode-skill-loader/AGENTS.md b/src/features/opencode-skill-loader/AGENTS.md new file mode 100644 index 00000000..26291f42 --- /dev/null +++ b/src/features/opencode-skill-loader/AGENTS.md @@ -0,0 +1,59 @@ +# src/features/opencode-skill-loader/ — 4-Scope Skill Discovery + +**Generated:** 2026-02-18 + +## OVERVIEW + +28 files (~3.2k LOC). Discovers, parses, merges, and resolves SKILL.md files from 4 scopes with priority deduplication. + +## 4-SCOPE PRIORITY (highest → lowest) + +``` +1. Project (.opencode/skills/) +2. OpenCode config (~/.config/opencode/skills/) +3. User (~/.config/opencode/oh-my-opencode/skills/) +4. Global (built-in skills) +``` + +Same-named skill at higher scope overrides lower. + +## KEY FILES + +| File | Purpose | +|------|---------| +| `loader.ts` | Main `loadSkills()` — orchestrates discovery → parse → merge | +| `async-loader.ts` | Async variant for non-blocking skill loading | +| `blocking.ts` | Sync variant for initial load | +| `merger.ts` | Priority-based deduplication across scopes | +| `skill-content.ts` | YAML frontmatter parsing from SKILL.md | +| `skill-discovery.ts` | Find SKILL.md files in directory trees | +| `skill-directory-loader.ts` | Load all skills from a single directory | +| `config-source-discovery.ts` | Discover scope directories from config | +| `skill-template-resolver.ts` | Variable substitution in skill templates | +| `skill-mcp-config.ts` | Extract MCP configs from skill YAML | +| `types.ts` | `LoadedSkill`, `SkillScope`, `SkillDiscoveryResult` | + +## SKILL FORMAT (SKILL.md) + +```markdown +--- +name: my-skill +description: What this skill does +tools: [Bash, Read, Write] +mcp: + - name: my-mcp + type: stdio + command: npx + args: [-y, my-mcp-server] +--- + +Skill content (instructions for the agent)... +``` + +## MERGER SUBDIRECTORY + +Handles complex merge logic when skills from multiple scopes have overlapping names or MCP configs. + +## TEMPLATE RESOLUTION + +Variables like `{{directory}}`, `{{agent}}` in skill content get resolved at load time based on current context. diff --git a/src/features/tmux-subagent/AGENTS.md b/src/features/tmux-subagent/AGENTS.md new file mode 100644 index 00000000..0f2a4495 --- /dev/null +++ b/src/features/tmux-subagent/AGENTS.md @@ -0,0 +1,52 @@ +# src/features/tmux-subagent/ — Tmux Pane Management + +**Generated:** 2026-02-18 + +## OVERVIEW + +28 files. State-first tmux integration managing panes for background agent sessions. Handles split decisions, grid planning, polling, and lifecycle events. + +## CORE ARCHITECTURE + +``` +TmuxSessionManager (manager.ts) + ├─→ DecisionEngine: Should we spawn/close panes? + ├─→ ActionExecutor: Execute spawn/close/replace actions + ├─→ PollingManager: Monitor pane health + └─→ EventHandlers: React to session create/delete +``` + +## KEY FILES + +| File | Purpose | +|------|---------| +| `manager.ts` | `TmuxSessionManager` — main class, session tracking, event routing | +| `decision-engine.ts` | Evaluate window state → produce `SpawnDecision` with actions | +| `action-executor.ts` | Execute `PaneAction[]` (close, spawn, replace) | +| `grid-planning.ts` | Calculate pane layout given window dimensions | +| `spawn-action-decider.ts` | Decide spawn vs replace vs skip | +| `spawn-target-finder.ts` | Find best pane to split or replace | +| `polling-manager.ts` | Health polling for tracked sessions | +| `types.ts` | `TrackedSession`, `WindowState`, `PaneAction`, `SpawnDecision` | + +## PANE LIFECYCLE + +``` +session.created → spawn-action-decider → grid-planning → action-executor → track session +session.deleted → cleanup tracked session → close pane if empty +``` + +## LAYOUT CONSTRAINTS + +- `MIN_PANE_WIDTH`: 52 chars +- `MIN_PANE_HEIGHT`: 11 lines +- Main pane preserved (never split below minimum) +- Agent panes split from remaining space + +## EVENT HANDLERS + +| File | Event | +|------|-------| +| `session-created-handler.ts` | New background session → spawn pane | +| `session-deleted-handler.ts` | Session ended → close pane | +| `session-created-event.ts` | Event type definition | diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 5e59103f..cdbfc11a 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -1,14 +1,14 @@ -# src/hooks/ — 41 Lifecycle Hooks +# src/hooks/ — 44 Lifecycle Hooks -**Generated:** 2026-02-17 +**Generated:** 2026-02-18 ## OVERVIEW -41 hooks across 37 directories + 6 standalone files. Three-tier composition: Core(33) + Continuation(7) + Skill(2). All hooks follow `createXXXHook(deps) → HookFunction` factory pattern. +44 hooks across 39 directories + 6 standalone files. Three-tier composition: Core(35) + Continuation(7) + Skill(2). All hooks follow `createXXXHook(deps) → HookFunction` factory pattern. ## HOOK TIERS -### Tier 1: Session Hooks (20) — `create-session-hooks.ts` +### Tier 1: Session Hooks (22) — `create-session-hooks.ts` | Hook | Event | Purpose | |------|-------|---------| @@ -31,6 +31,9 @@ | questionLabelTruncator | tool.execute.before | Truncate long question labels | | taskResumeInfo | chat.message | Inject task context on resume | | anthropicEffort | chat.params | Adjust reasoning effort level | +| jsonErrorRecovery | tool.execute.after | Detect JSON parse errors, inject correction reminder | +| sisyphusGptHephaestusReminder | chat.message | Toast warning when Sisyphus uses GPT model | +| taskReminder | tool.execute.after | Remind about task tools after 10 turns without usage | ### Tier 2: Tool Guard Hooks (9) — `create-tool-guard-hooks.ts` diff --git a/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md b/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md new file mode 100644 index 00000000..f76e0eb8 --- /dev/null +++ b/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md @@ -0,0 +1,49 @@ +# src/hooks/anthropic-context-window-limit-recovery/ — Multi-Strategy Context Recovery + +**Generated:** 2026-02-18 + +## OVERVIEW + +31 files (~2232 LOC). Most complex hook. Recovers from context window limit errors via multiple strategies applied in sequence. + +## RECOVERY STRATEGIES (in priority order) + +| Strategy | File | Mechanism | +|----------|------|-----------| +| **Empty content recovery** | `empty-content-recovery.ts` | Handle empty/null content blocks in messages | +| **Deduplication** | `deduplication-recovery.ts` | Remove duplicate tool results from context | +| **Target-token truncation** | `target-token-truncation.ts` | Truncate largest tool outputs to fit target ratio | +| **Aggressive truncation** | `aggressive-truncation-strategy.ts` | Last-resort truncation with minimal output preservation | +| **Summarize retry** | `summarize-retry-strategy.ts` | Compaction + summarization then retry | + +## KEY FILES + +| File | Purpose | +|------|---------| +| `recovery-hook.ts` | Main hook entry — `session.error` handler, strategy orchestration | +| `executor.ts` | Execute recovery strategies in sequence | +| `parser.ts` | Parse Anthropic token limit error messages | +| `state.ts` | `AutoCompactState` — per-session retry/truncation tracking | +| `types.ts` | `ParsedTokenLimitError`, `RetryState`, `TruncateState`, config constants | +| `storage.ts` | Persist tool results for later truncation | +| `tool-result-storage.ts` | Store/retrieve individual tool call results | +| `message-builder.ts` | Build retry messages after recovery | + +## RETRY CONFIG + +- Max attempts: 2 +- Initial delay: 2s, backoff ×2, max 30s +- Max truncation attempts: 20 +- Target token ratio: 0.5 (truncate to 50% of limit) +- Chars per token estimate: 4 + +## PRUNING SYSTEM + +`pruning-*.ts` files handle intelligent output pruning: +- `pruning-deduplication.ts` — Remove duplicate content across tool results +- `pruning-tool-output-truncation.ts` — Truncate oversized tool outputs +- `pruning-types.ts` — Pruning-specific type definitions + +## SDK VARIANTS + +`empty-content-recovery-sdk.ts` and `tool-result-storage-sdk.ts` provide SDK-based implementations for OpenCode client interactions. diff --git a/src/plugin/AGENTS.md b/src/plugin/AGENTS.md new file mode 100644 index 00000000..a0ab7c5d --- /dev/null +++ b/src/plugin/AGENTS.md @@ -0,0 +1,49 @@ +# src/plugin/ — 8 OpenCode Hook Handlers + Hook Composition + +**Generated:** 2026-02-18 + +## OVERVIEW + +Core glue layer. 20 source files assembling the 8 OpenCode hook handlers and composing 44 hooks into the PluginInterface. Every handler file corresponds to one OpenCode hook type. + +## HANDLER FILES + +| File | OpenCode Hook | Purpose | +|------|---------------|---------| +| `chat-message.ts` | `chat.message` | First-message variant, session setup, keyword detection | +| `chat-params.ts` | `chat.params` | Anthropic effort level, think mode | +| `event.ts` | `event` | Session lifecycle (created, deleted, idle, error) | +| `tool-execute-before.ts` | `tool.execute.before` | Pre-tool guards (file guard, label truncator, rules injector) | +| `tool-execute-after.ts` | `tool.execute.after` | Post-tool hooks (output truncation, comment checker, metadata) | +| `messages-transform.ts` | `experimental.chat.messages.transform` | Context injection, thinking block validation | +| `tool-registry.ts` | `tool` | 26 tools assembled from factories | +| `skill-context.ts` | — | Skill/browser/category context for tool creation | + +## HOOK COMPOSITION (hooks/ subdir) + +| File | Tier | Count | +|------|------|-------| +| `create-session-hooks.ts` | Session | 22 | +| `create-tool-guard-hooks.ts` | Tool Guard | 9 | +| `create-transform-hooks.ts` | Transform | 4 | +| `create-continuation-hooks.ts` | Continuation | 7 | +| `create-skill-hooks.ts` | Skill | 2 | +| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 35 | + +## SUPPORT FILES + +| File | Purpose | +|------|---------| +| `available-categories.ts` | Build `AvailableCategory[]` for agent prompt injection | +| `session-agent-resolver.ts` | Resolve which agent owns a session | +| `session-status-normalizer.ts` | Normalize session status across OpenCode versions | +| `recent-synthetic-idles.ts` | Dedup rapid idle events | +| `unstable-agent-babysitter.ts` | Track unstable agent behavior across sessions | +| `types.ts` | `PluginContext`, `PluginInterface`, `ToolsRecord`, `TmuxConfig` | + +## KEY PATTERNS + +- Each handler exports a function receiving `(hookRecord, ctx, pluginConfig, managers)` → returns OpenCode hook function +- Handlers iterate over hook records, calling each hook with `(input, output)` in sequence +- `safeHook()` wrapper in composition files catches errors per-hook without breaking the chain +- Tool registry uses `filterDisabledTools()` before returning diff --git a/src/tools/delegate-task/AGENTS.md b/src/tools/delegate-task/AGENTS.md new file mode 100644 index 00000000..3ac1db79 --- /dev/null +++ b/src/tools/delegate-task/AGENTS.md @@ -0,0 +1,58 @@ +# src/tools/delegate-task/ — Task Delegation Engine + +**Generated:** 2026-02-18 + +## OVERVIEW + +41 files. The `task` tool implementation — delegates work to subagents via background or sync sessions. Resolves categories, models, skills, and manages both async and synchronous execution flows. + +## TWO EXECUTION MODES + +| Mode | Flow | Use Case | +|------|------|----------| +| **Background** (`run_in_background=true`) | Launch → BackgroundManager → poll → notify parent | Explore, librarian, parallel work | +| **Sync** (`run_in_background=false`) | Create session → send prompt → poll until idle → return result | Sequential tasks needing immediate result | + +## KEY FILES + +| File | Purpose | +|------|---------| +| `tools.ts` | `createDelegateTask()` factory — main entry point | +| `executor.ts` | Route to background or sync execution | +| `types.ts` | `DelegateTaskArgs`, `DelegateTaskToolOptions`, `ToolContextWithMetadata` | +| `category-resolver.ts` | Map category name → model + config | +| `subagent-resolver.ts` | Map subagent_type → agent + model | +| `model-selection.ts` | Model availability checking + fallback | +| `skill-resolver.ts` | Resolve `load_skills[]` → skill content for injection | +| `prompt-builder.ts` | Build system/user prompt with skill content, categories | + +## SYNC EXECUTION CHAIN + +``` +sync-task.ts → sync-session-creator.ts → sync-prompt-sender.ts → sync-session-poller.ts → sync-result-fetcher.ts +``` + +Each file handles one step. `sync-continuation.ts` handles session continuation (resume with session_id). + +## BACKGROUND EXECUTION + +``` +background-task.ts → BackgroundManager.launch() → (async polling) → background-continuation.ts +``` + +`background-continuation.ts` handles `session_id` resume for existing background tasks. + +## CATEGORY RESOLUTION + +1. Check user-defined categories (`pluginConfig.categories`) +2. Fall back to built-in 8 categories +3. Resolve model from category config +4. Check model availability → fallback if unavailable + +## MODEL STRING PARSER + +`model-string-parser.ts` handles `"model variant"` format (e.g., `"gpt-5.3-codex medium"` → model=`gpt-5.3-codex`, variant=`medium`). + +## UNSTABLE AGENT TRACKING + +`unstable-agent-task.ts` marks tasks from categories/agents known to be unstable (e.g., free models). Enables `unstableAgentBabysitter` hook monitoring.