chore: regenerate AGENTS.md knowledge base

🤖 Generated with [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode) assistance
2026-02-18 01:26:19 +09:00
parent 04e95d7e27
commit 3313ec3e4f
11 changed files with 400 additions and 17 deletions
--- 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
--- 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...
--- a/src/cli/run/AGENTS.md
+++ 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 <message>` 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"`).
--- 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
--- a/src/features/background-agent/AGENTS.md
+++ 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
+```
--- a/src/features/opencode-skill-loader/AGENTS.md
+++ 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.
--- a/src/features/tmux-subagent/AGENTS.md
+++ 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 |
--- 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`

--- a/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md
+++ 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.
--- a/src/plugin/AGENTS.md
+++ 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
--- a/src/tools/delegate-task/AGENTS.md
+++ 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.