docs(agents): refresh hierarchical AGENTS.md with team-mode coverage

Update root + 43 directory-level AGENTS.md files to reflect current state: - Root AGENTS.md rewritten with accurate counts (1967 TS files, 1304 source + 663 test, 278k LOC, 120 barrel index.ts), 7-step init flow, 5-tier hook composition, and full Team Mode section (12 team_* tools, eligibility, storage layout, config gate) - src/AGENTS.md adds team-mode init step, current per-subdir file/LOC table - src/tools/AGENTS.md documents conditional gates (team-mode +12, task system +4, hashline +1, interactive_bash +1, look_at +1) with always-on baseline of 20 - src/hooks/AGENTS.md splits into 5 tiers + 4 conditional team-mode hooks - src/features/team-mode/AGENTS.md surfaces 12 tools, eligible agents, spawn-race-safe invariants, and integration points - src/features/builtin-skills/AGENTS.md tracks 10 skills incl. team-mode - src/agents/AGENTS.md, src/plugin/AGENTS.md, src/config/AGENTS.md updated for team-mode awareness, accurate counts, and current schema field list - All other AGENTS.md files refreshed to 2026-05-08 generation date
2026-05-08 12:08:42 +09:00
parent cd31d2a1a8
commit 838b5ae216
44 changed files with 909 additions and 648 deletions
@@ -1,32 +1,44 @@
 # oh-my-opencode — OpenCode Plugin
-**Generated:** 2026-04-18 | **Commit:** 2892ca4a | **Branch:** dev
+**Generated:** 2026-05-08 | **Commit:** cd31d2a1a | **Branch:** dev
 ## OVERVIEW
-OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during transition) extending Claude Code with 11 agents, 52 lifecycle hooks, 26 tools, 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate classifier, and Claude Code compatibility. 1766 TypeScript source files, 377k LOC, 104 barrel index.ts files. Entry: `src/index.ts` → 5-step init (loadConfig → createManagers → createTools → createHooks → createPluginInterface).
+OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, ~50 lifecycle hooks across 57 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), and Claude Code compatibility. **1967 TypeScript files (1304 source + 663 test), 278k LOC, 120 barrel `index.ts` files.** Entry: `src/index.ts` → 7-step init.
 ## STRUCTURE
 ```
 oh-my-opencode/
 ├── src/
-│   ├── index.ts              # Plugin entry: default export `pluginModule`, shape `{ id, server }`
+│   ├── index.ts              # Plugin entry; default export `pluginModule` = `{ id, server }`
 │   ├── plugin-config.ts      # JSONC multi-level config: user → project → defaults (Zod v4)
 │   ├── plugin-interface.ts   # 10 OpenCode hook handlers
 │   ├── create-managers.ts    # 4 managers (Tmux, Background, SkillMcp, ConfigHandler)
 │   ├── create-tools.ts       # ToolRegistry composition
 │   ├── create-hooks.ts       # 5-tier hook composition
 │   ├── agents/               # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
-│   ├── hooks/                # 52 lifecycle hooks across dedicated modules and standalone files
+│   ├── hooks/                # ~50 lifecycle hooks across 57 dirs
-│   ├── tools/                # 26 tools across 16 directories (includes Hashline edit with LINE#ID content hashing)
+│   ├── tools/                # 16 tool dirs; produces 20–39 tools (config-gated)
-│   ├── features/             # 20 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, skill-mcp-manager, team-mode, etc.)
+│   ├── features/             # 20 feature modules (incl. team-mode, background-agent, skill-mcp-manager, openclaw, etc.)
-│   ├── shared/               # 170+ utility files (barrel-exported, logger → /tmp/oh-my-opencode.log)
+│   ├── shared/               # 258 utility files; logger → /tmp/oh-my-opencode.log
-│   ├── config/               # Zod v4 schema system (32 files)
+│   ├── config/               # Zod v4 schema system (32 schema files)
-│   ├── cli/                  # CLI: install, run, doctor, mcp-oauth (Commander.js)
+│   ├── cli/                  # CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version
 │   ├── mcp/                  # 3 built-in remote MCPs (websearch, context7, grep_app)
-│   ├── plugin/               # 10 OpenCode hook handlers + 52 hook composition
+│   ├── plugin/               # 10 OpenCode hook handlers + 5-tier hook composition
 │   ├── plugin-handlers/      # 6-phase config loading pipeline
-│   └── openclaw/             # Bidirectional external integration (Discord/Telegram/webhook/command)
+│   ├── openclaw/             # Bidirectional external integration (Discord/Telegram/HTTP/shell + reply listener daemon)
-├── packages/                 # 11 platform-specific compiled binaries (darwin/linux/windows, AVX2 + baseline variants)
+│   └── testing/              # Test utilities
 ├── packages/                 # 11 platform-specific compiled binary packages (darwin/linux/windows, AVX2 + baseline)
 ├── bin/                      # Platform-detection JS shim (oh-my-opencode + oh-my-openagent)
 ├── script/                   # Build/publish automation (singular, not scripts/)
-├── .sisyphus/                # AI agent workspace (rules, plans, tasks, notepads)
+├── docs/                     # User-facing docs (guide/, reference/, examples/, legal/, manifesto.md, superpowers/)
 ├── assets/                   # oh-my-opencode.schema.json (auto-generated from Zod)
 ├── signatures/               # CLA signature registry (cla.json)
 ├── postinstall.mjs           # Verifies platform binary + OpenCode version
 ├── test-setup.ts             # Bun test preload (resets state between tests)
 ├── bun-test.d.ts             # Custom bun:test type augmentations
 ├── .sisyphus/                # AI agent workspace (run-continuation/, plans/, tasks/, notepads/)
 └── .local-ignore/            # Dev-only test fixtures + PR worktrees
 ```
@@ -34,140 +46,193 @@ oh-my-opencode/
 ```
 pluginModule.server(input, options)
-  ├─→ loadPluginConfig()         # JSONC parse → project/user merge → Zod validate → migrate
+  ├─→ installAgentSortShim()       # patches Array.prototype.{toSorted,sort} for canonical agent ordering
-  ├─→ createManagers()           # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
+  ├─→ initConfigContext()          # opencode-vs-openagent layout flag
-  ├─→ createTools()              # SkillContext + AvailableCategories + ToolRegistry (26 tools)
+  ├─→ detectExternalSkillPlugin()  # warn on conflicts
-  ├─→ createHooks()              # 3-tier: Core(43) + Continuation(7) + Skill(2) = 52 hooks
+  ├─→ injectServerAuthIntoClient() # auth headers into shared SDK client
-  └─→ createPluginInterface()    # 10 OpenCode hook handlers → PluginInterface
+  ├─→ loadPluginConfig()           # JSONC parse → user/project merge → Zod validate → migrate
  ├─→ initializeOpenClaw()         # if openclaw config present
  ├─→ checkTeamModeDependencies()  # if team_mode.enabled
  ├─→ createManagers()             # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
  ├─→ createTools()                # SkillContext + AvailableCategories + ToolRegistry
  ├─→ createHooks()                # 5-tier: Session + ToolGuard + Transform + Continuation + Skill
  └─→ createPluginInterface()      # 10 OpenCode hook handlers → PluginInterface
 ```
 ## 10 OPENCODE HOOK HANDLERS
-| Handler | Purpose |
+| Handler | OpenCode Hook | Purpose |
-|---------|---------|
+|---------|---------------|---------|
-| `config` | 6-phase: provider → plugin-components → agents → tools → MCPs → commands |
+| `config` | `config` | 6-phase pipeline: provider → plugin-components → agents → tools → MCPs → commands |
-| `tool` | 26 registered tools |
+| `tool` | `tool` | 20–39 registered tools (config-gated: team-mode +12, task system +4, hashline +1, interactive_bash +1, look_at +1) |
-| `chat.message` | First-message variant, session setup, keyword detection (ultrawork/search/analyze) |
+| `chat.message` | `chat.message` | First-message variant, session setup, keyword detection (ultrawork/search/analyze/team) |
-| `chat.params` | Anthropic effort level, think mode, runtime fallback override |
+| `chat.params` | `chat.params` | Anthropic effort, think mode, runtime fallback override |
-| `chat.headers` | Copilot x-initiator header injection |
+| `chat.headers` | `chat.headers` | Copilot `x-initiator` header injection |
-| `event` | Session lifecycle (created, deleted, idle, error), openclaw dispatch, runtime fallback |
+| `event` | `event` | Session lifecycle (created/deleted/idle/error), openclaw dispatch, runtime fallback |
-| `tool.execute.before` | Pre-tool hooks (file guard, label truncator, rules injector, prometheus md-only) |
+| `tool.execute.before` | `tool.execute.before` | Pre-tool guards (write-existing-guard, label-truncator, rules-injector, prometheus-md-only, …) |
-| `tool.execute.after` | Post-tool hooks (output truncation, comment checker, hashline read enhancer) |
+| `tool.execute.after` | `tool.execute.after` | Post-tool hooks (output truncator, comment-checker, hashline read-enhancer, json-error-recovery, …) |
-| `experimental.chat.messages.transform` | Context injection, thinking block validation, tool pair validation |
+| `experimental.chat.messages.transform` | `experimental.chat.messages.transform` | Context injection, thinking-block validation, tool-pair validation, keyword detection |
-| `experimental.session.compacting` | Context + todo preservation during compaction |
+| `experimental.session.compacting` | `experimental.session.compacting` | Context + todo preservation across compaction |
 ## TOOL CATALOG (config-gated)
 **Always on (20):** `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_diagnostics`, `lsp_prepare_rename`, `lsp_rename`, `grep`, `glob`, `ast_grep_search`, `ast_grep_replace`, `session_list`, `session_read`, `session_search`, `session_info`, `background_output`, `background_cancel`, `call_omo_agent`, `task` (delegate), `skill`, `skill_mcp`.
 **Conditional:** `look_at` (+1, multimodal-looker not disabled), `interactive_bash` (+1, tmux enabled), `task_create`/`task_get`/`task_list`/`task_update` (+4, `experimental.task_system`), `edit` (+1, `hashline_edit`), `team_create`/`team_delete`/`team_shutdown_request`/`team_approve_shutdown`/`team_reject_shutdown`/`team_send_message`/`team_task_create`/`team_task_list`/`team_task_update`/`team_task_get`/`team_status`/`team_list` (+12, `team_mode.enabled`).
 ## TEAM MODE
 OFF by default. Parallel multi-agent coordination, modeled after Claude Code Agent Teams. Enable via `team_mode.enabled` in `.opencode/oh-my-opencode.jsonc` or user config; restart OpenCode after change.
 ```jsonc
 {
  "team_mode": {
    "enabled": true,
    "max_parallel_members": 4,
    "max_members": 8,
    "tmux_visualization": false
  }
 }
 ```
 Teams live as directories under `~/.omo/teams/{name}/config.json` (user) or `<project>/.omo/teams/{name}/config.json` (project; project beats user on collisions). Members declared as `kind: "subagent_type"` (direct agent) or `kind: "category"` (routed through `sisyphus-junior`).
 **Eligible members only:** sisyphus, atlas, sisyphus-junior, hephaestus. Read-only / orchestration agents (oracle, librarian, explore, multimodal-looker, metis, momus, prometheus) are rejected at parse time — use `task` (delegate) for those.
 **Storage layout** (`~/.omo/teams/{name}/`): `config.json` (spec), `state.json` (runtime), `mailbox/` (messages), `tasklist.jsonl` (tasks), `worktrees/` (per-member git worktrees).
 **Implementation:** [`src/features/team-mode/`](file:///Users/yeongyu/local-workspaces/omo/src/features/team-mode/AGENTS.md). User docs: [`docs/guide/team-mode.md`](file:///Users/yeongyu/local-workspaces/omo/docs/guide/team-mode.md).
 ## MULTI-LEVEL CONFIG
 ```
 Walked configs (closer wins): <pwd up to $HOME>/.opencode/oh-my-openagent.json[c]   (legacy: oh-my-opencode.json[c])
                            ↓ merged onto
 User config:               ~/.config/opencode/oh-my-openagent.json[c]   (Windows: %APPDATA%\opencode\)
                            ↓ falls back to
 Defaults                   (Zod safeParse fills omitted fields)
 ```
 - `agents`, `categories`, `claude_code`: deep merged recursively (prototype-pollution safe)
 - `disabled_*` arrays: Set union (concatenated + deduplicated)
 - All other fields: override replaces base value
 - `mcp_env_allowlist`: **user-only** for security; walked configs cannot extend it
 - `migrateConfigFile()` rewrites legacy keys (idempotent via `_migrations` tracking + timestamped backups)
 Schema autocomplete: `"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json"`
 ## THREE-TIER MCP SYSTEM
 | Tier | Source | Loader | Mechanism |
 |------|--------|--------|-----------|
 | 1. Built-in | `src/mcp/` | `createBuiltinMcps()` | 3 remote HTTP: websearch (Exa/Tavily), context7, grep_app |
 | 2. Claude Code | `.mcp.json` (project + user) | `claude-code-mcp-loader` | `${VAR}` env expansion (allowlist via `mcp_env_allowlist`) |
 | 3. Skill-embedded | SKILL.md YAML frontmatter | `SkillMcpManager` (per-session) | stdio + HTTP, OAuth 2.0 + PKCE + DCR step-up |
 ## WHERE TO LOOK
 | Task | Location | Notes |
 |------|----------|-------|
-| Add new agent | `src/agents/` + `src/agents/builtin-agents/` | Follow createXXXAgent factory pattern |
+| Add new agent | `src/agents/` + `src/agents/builtin-agents/` | `createXXXAgent` factory + `mode: "primary" \| "subagent" \| "all"` |
-| Add new hook | `src/hooks/{name}/` + register in `src/plugin/hooks/create-*-hooks.ts` | Match event type to tier |
+| Add new hook | `src/hooks/{name}/` + register in `src/plugin/hooks/create-*-hooks.ts` | Pick the right tier (Session/ToolGuard/Transform/Continuation/Skill) |
-| Add new tool | `src/tools/{name}/` + register in `src/plugin/tool-registry.ts` | Follow createXXXTool factory |
+| Add new tool | `src/tools/{name}/` + register in `src/plugin/tool-registry.ts` | Factory `createXXXTool` (most) or direct `ToolDefinition` (LSP, interactive_bash) |
-| Add new feature module | `src/features/{name}/` | Standalone module, wire in plugin/ |
+| Add new feature module | `src/features/{name}/` | Standalone module wired into `plugin/` layer |
-| Add new MCP | `src/mcp/` + register in `createBuiltinMcps()` | Remote HTTP only (tier 1 of 3) |
+| Add new MCP (tier 1) | `src/mcp/` + register in `createBuiltinMcps()` | Remote HTTP only |
-| Add new skill | `src/features/builtin-skills/skills/` | Implement BuiltinSkill interface |
+| Add new built-in skill | `src/features/builtin-skills/skills/{name}.ts` + register in `skills.ts` | Implement `BuiltinSkill` interface |
-| Add new command | `src/features/builtin-commands/` | Template in templates/ |
+| Add new command | `src/features/builtin-commands/` | Templates in `templates/` |
-| Add new CLI command | `src/cli/cli-program.ts` | Commander.js subcommand |
+| Add new CLI subcommand | `src/cli/cli-program.ts` | Commander.js subcommand |
-| Add new doctor check | `src/cli/doctor/checks/` | Register in checks/index.ts |
+| Add new doctor check | `src/cli/doctor/checks/` | Register in `checks/index.ts` |
-| Modify config schema | `src/config/schema/` + update root schema | Zod v4, add to OhMyOpenCodeConfigSchema |
+| Modify config schema | `src/config/schema/` + add to `OhMyOpenCodeConfigSchema` | Zod v4; auto-included in `assets/oh-my-opencode.schema.json` after `bun run build:schema` |
-| Add new category | `src/tools/delegate-task/constants.ts` | DEFAULT_CATEGORIES + CATEGORY_MODEL_REQUIREMENTS |
+| Add new category | `src/tools/delegate-task/constants.ts` | `DEFAULT_CATEGORIES` + `CATEGORY_MODEL_REQUIREMENTS` |
-| Debug provider errors | `src/hooks/runtime-fallback/` | Reactive error recovery (distinct from model-fallback) |
+| Add new team-mode tool | `src/features/team-mode/tools/` + register in `src/plugin/tool-registry.ts` `teamModeToolsRecord` | Gated on `team_mode.enabled` |
-| External notifications | `src/openclaw/` | Bidirectional Discord/Telegram/webhook integration |
+| Reactive provider error recovery | `src/hooks/runtime-fallback/` | Distinct from `model-fallback` (proactive, chat.params) |
-| Skill-embedded MCP | `src/features/skill-mcp-manager/` | Tier 3 MCPs (stdio + HTTP, per-session) |
+| External notifications | `src/openclaw/` | Bidirectional: outbound (event → HTTP/shell), inbound (Discord/Telegram daemon → tmux send-keys) |
-| Team mode | `src/features/team-mode/` | Parallel multi-agent coordination (OFF by default) |
+| Skill-embedded MCP | `src/features/skill-mcp-manager/` | Tier-3 MCPs (per-session, stdio + HTTP) |
-## MULTI-LEVEL CONFIG
+## ARCHITECTURE INVARIANTS
-```
+- **Canonical agent order:** Sisyphus → Hephaestus → Prometheus → Atlas. Enforced by `installAgentSortShim()` (patches `Array.prototype.toSorted`/`.sort` narrowly when the array contains ≥2 canonical core agents). See [`src/plugin-handlers/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/plugin-handlers/AGENTS.md) for the full history of why this exists.
-Project (.opencode/oh-my-opencode.jsonc)  →  User (~/.config/opencode/oh-my-opencode.jsonc)  →  Defaults
+- **Hashline edit + read pairing:** Every `Read` tool output is tagged with `LINE#ID` content hashes; `hashline_edit` validates the hash before applying. Stale hash → reject.
-```
+- **5-tier hook composition:** Session (24) + ToolGuard (14) + Transform (5) + Continuation (7) + Skill (2). Composed by `createCoreHooks()` + `createContinuationHooks()` + `createSkillHooks()`.
-
+- **Per-session MCP isolation:** Tier-3 MCP clients keyed by `${sessionID}:${skillName}:${serverName}` so the same skill in two sessions does not share state.
- `agents`, `categories`, `claude_code`: deep merged recursively (prototype-pollution-safe)
+- **Two fallback systems:** `model-fallback` (proactive, chat.params) vs `runtime-fallback` (reactive, session.error). They operate independently — no direct integration.
- `disabled_*` arrays: Set union (concatenated + deduplicated)
+- **OpenClaw bidirectional:** Outbound dispatchers fire on session events; inbound daemon polls Discord/Telegram and `send-keys` replies into the tracked tmux pane.
 - All other fields: override replaces base value
 - Zod `safeParse()` fills defaults for omitted fields; partial parsing as fallback
 - `migrateConfigFile()` transforms legacy keys automatically (idempotent via `_migrations` tracking)
 Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom), disabled_* arrays (agents, hooks, mcps, skills, commands, tools), 19 feature-specific configs.
 ## THREE-TIER MCP SYSTEM
 | Tier | Source | Mechanism |
 |------|--------|-----------|
 | Built-in | `src/mcp/` | 3 remote HTTP: websearch (Exa/Tavily), context7, grep_app |
 | Claude Code | `.mcp.json` | `${VAR}` env expansion via claude-code-mcp-loader |
 | Skill-embedded | SKILL.md YAML | Managed by SkillMcpManager (stdio + HTTP) |
 ## CONVENTIONS
- **Runtime**: Bun only (1.3.11 in CI) -- never use npm/yarn
+- **Runtime:** Bun only (1.3.11 in CI). Never npm/yarn/pnpm.
- **TypeScript**: strict mode, ESNext, bundler moduleResolution, `bun-types` (never `@types/node`)
+- **TypeScript:** strict mode, ESNext, bundler moduleResolution, `bun-types` (never `@types/node`).
- **Test pattern**: Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style (nested describe with `#given`/`#when`/`#then` prefixes or inline `// given` / `// when` / `// then` comments)
+- **Tests:** Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style — nested `describe` with `#given`/`#when`/`#then` prefixes, or inline `// given` / `// when` / `// then` comments. Never Arrange-Act-Assert comments.
- **CI test split**: `script/run-ci-tests.ts` auto-detects `mock.module()` usage, isolates those tests in separate processes
+- **CI test split:** `script/run-ci-tests.ts` auto-detects `mock.module()` and isolates those tests in separate processes.
- **Factory pattern**: `createXXX()` for all tools, hooks, agents
+- **Test setup:** `test-setup.ts` preloaded via `bunfig.toml` resets session/cache state between tests.
- **Hook tiers**: Session (24) → Tool-Guard (14) → Transform (5) → Continuation (7) → Skill (2)
+- **Factory pattern:** `createXXX()` for all tools, hooks, agents.
- **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all`
+- **File naming:** kebab-case for files and directories.
- **Model resolution**: 4-step: override → category-default → provider-fallback → system-default
+- **Module structure:** `index.ts` barrel exports, **no catch-all files** (`utils.ts`, `helpers.ts`, `service.ts` banned), 200 LOC soft limit per file.
- **Config format**: JSONC with comments, Zod v4 validation, snake_case keys
+- **Imports:** relative within a module, barrel imports across modules (`import { log } from "./shared"`). **No path aliases** — never `@/`.
- **File naming**: kebab-case for all files/directories
+- **Config format:** JSONC with comments + trailing commas, Zod v4 validation, snake_case keys.
- **Module structure**: index.ts barrel exports, no catch-all files (utils.ts, helpers.ts banned), 200 LOC soft limit
+- **Dual package:** `oh-my-opencode` + `oh-my-openagent` published simultaneously during the rename transition.
- **Imports**: relative within module, barrel imports across modules (`import { log } from "./shared"`)
+- **Comments:** AI slop comment patterns blocked by `comment-checker` hook (binary: `@code-yeongyu/comment-checker`). Use `// @allow` to bypass single line, `// comment-checker-disable-file` at file top to bypass file. Sparingly.
 - **No path aliases**: no `@/` -- relative imports only
 - **Dual package**: `oh-my-opencode` + `oh-my-openagent` published simultaneously (transition period)
-## ANTI-PATTERNS
+## ANTI-PATTERNS (BLOCKING)
- Never use `as any`, `@ts-ignore`, `@ts-expect-error`
+- Never `as any`, `@ts-ignore`, `@ts-expect-error`.
- Never suppress lint/type errors
+- Never suppress lint/type errors.
- Never add emojis to code/comments unless user explicitly asks
+- Never add emojis to code/comments unless user explicitly asks.
- Never commit unless explicitly requested
+- Never commit unless explicitly requested.
- Never run `bun publish` directly -- use GitHub Actions
+- Never run `bun publish` directly — use the GitHub Actions workflow.
- Never modify `package.json` version locally
+- Never modify `package.json` `version` locally — handled by publish workflow.
- Test: given/when/then -- never use Arrange-Act-Assert comments
+- Never write to existing files without reading them first (`write-existing-file-guard`).
- Comments: avoid AI-generated comment patterns (enforced by comment-checker hook)
+- Never use `background_cancel(all=true)` — cancel by `taskId` individually.
- Never create catch-all files (`utils.ts`, `helpers.ts`, `service.ts`)
+- Never delete a failing test to make a build green. Fix the code.
- Empty catch blocks `catch(e) {}` -- always handle errors
+- Never em dashes / en dashes / AI filler ("simply", "obviously", "clearly", "moreover", "furthermore") in generated content.
- Never use em dashes, en dashes, or AI filler phrases in generated content
+- Never create catch-all files (`utils.ts`, `helpers.ts`, `service.ts`).
- index.ts is entry point ONLY -- never dump business logic there
+- Never empty catch blocks `catch(e) {}`.
 - Never test with Arrange-Act-Assert comments — use given/when/then.
 - Never dump business logic into `index.ts` — barrel exports only.
 - Prometheus may ONLY edit `.md` files (enforced by `prometheus-md-only` hook); FORBIDDEN paths: `src/`, `package.json`, config files.
 ## COMMANDS
 ```bash
-bun test                    # Bun test suite
+bun test                          # Bun test suite (auto-split mock-heavy tests via script/run-ci-tests.ts)
-bun run build              # Build plugin (ESM + declarations + schema)
+bun run build                     # Build plugin (ESM bundle + .d.ts + cli bundle + schema generation)
-bun run build:all          # Build + platform binaries
+bun run build:all                 # Build + 11 platform binaries
-bun run typecheck           # tsc --noEmit
+bun run build:schema              # Regenerate assets/oh-my-opencode.schema.json
-bunx oh-my-opencode install # Interactive setup
+bun run build:model-capabilities  # Refresh shared/model-capabilities cache from models.dev
-bunx oh-my-opencode doctor  # Health diagnostics
+bun run typecheck                 # tsc --noEmit
-bunx oh-my-opencode run     # Non-interactive session
+bun run clean                     # rm -rf dist
 bunx oh-my-opencode install       # Interactive setup wizard
 bunx oh-my-opencode doctor        # Health diagnostics (4 categories: System / Config / Tools / Models)
 bunx oh-my-opencode run <message> # Non-interactive session (auto-completes when todos done + no bg tasks)
 bunx oh-my-opencode mcp-oauth login <server-url>  # Tier-3 MCP OAuth (PKCE + DCR)
 ```
 ## CI/CD
 | Workflow | Trigger | Purpose |
 |----------|---------|---------|
-| ci.yml | push/PR to master/dev | Tests (split: mock-heavy isolated + batch), typecheck, build, schema auto-commit |
+| `ci.yml` | push/PR to master/dev | Tests (split: mock-heavy isolated + batch), typecheck, build, schema auto-commit |
-| publish.yml | manual dispatch | Version bump, dual npm publish (oh-my-opencode + oh-my-openagent), platform binaries, GitHub release |
+| `publish.yml` | manual dispatch | Version bump, dual npm publish (`oh-my-opencode` + `oh-my-openagent`), platform binaries, GitHub release |
-| publish-platform.yml | called by publish | 11 platform binaries via bun compile (darwin/linux/windows) |
+| `publish-platform.yml` | called by publish.yml | 11 platform binaries via `bun compile` (darwin/linux/windows) |
-| sisyphus-agent.yml | @mention / dispatch | AI agent handles issues/PRs |
+| `sisyphus-agent.yml` | @mention or manual dispatch | AI agent handles issues/PRs |
-| refresh-model-capabilities.yml | weekly schedule / dispatch | Auto-refresh model capabilities from models.dev API |
+| `refresh-model-capabilities.yml` | weekly cron / dispatch | Refresh model capabilities from models.dev API |
-| cla.yml | issue_comment/PR | CLA assistant for contributors |
+| `cla.yml` | issue_comment / PR | CLA assistant for contributors |
-| lint-workflows.yml | push to .github/ | actionlint + shellcheck on workflow files |
+| `lint-workflows.yml` | push to .github/ | actionlint + shellcheck on workflow files |
 ## NOTES
- Logger writes to `/tmp/oh-my-opencode.log` -- check there for debugging
+- **Logger:** writes to `/tmp/oh-my-opencode.log` — check there for debugging.
- Background tasks: 5 concurrent per model/provider (configurable, circuit breaker support)
+- **Background tasks:** 5 concurrent per `${providerID}/${modelID}` key by default (configurable via `background_task.modelConcurrency` / `providerConcurrency`); FIFO queue when slots full.
- Plugin load timeout: 10s for Claude Code plugins
+- **Plugin load timeout:** 10s for Claude Code plugin discovery.
- Model fallback: per-agent chains in `shared/model-requirements.ts`, not a single global priority
+- **Model fallback:** per-agent chains in `src/shared/model-requirements.ts`. **There is no single global priority.**
- Two fallback systems: `model-fallback` (proactive, chat.params) vs `runtime-fallback` (reactive, session.error)
+- **Two fallback systems:** `model-fallback` (proactive, chat.params, hardcoded chains) vs `runtime-fallback` (reactive, session.error, configurable per-category/agent).
- Config migration: idempotent via `_migrations` tracking, creates timestamped backups before atomic writes
+- **Config migration:** idempotent via `_migrations` tracking, atomic writes with timestamped backups.
- Build: bun build (ESM) + tsc --emitDeclarationOnly, externals: @ast-grep/napi
+- **Build:** `bun build` (ESM) + `tsc --emitDeclarationOnly`, externals: `@ast-grep/napi`, `zod`.
- Test setup: `test-setup.ts` preloaded via bunfig.toml, resets session/cache state between tests
+- **CI test isolation:** `script/run-ci-tests.ts` auto-isolates files using `mock.module()` (plus `src/openclaw/__tests__/reply-listener-discord.test.ts`) — they run in separate processes.
- Test split: `script/run-ci-tests.ts` auto-isolates files using `mock.module()` (plus `src/openclaw/__tests__/reply-listener-discord.test.ts`)
+- **120 barrel `index.ts` files** establish module boundaries.
- 104 barrel export files (index.ts) establish module boundaries
+- **Architecture rules** enforced via `.sisyphus/rules/modular-code-enforcement.md` (when present in workspace).
- Architecture rules enforced via `.sisyphus/rules/modular-code-enforcement.md`
+- **Windows builds:** run on `windows-latest` (not cross-compiled) to avoid Bun segfaults.
- Windows builds run on `windows-latest` runner (not cross-compiled) to avoid Bun segfaults
+- **Platform binaries:** detect AVX2 + libc family at runtime, fallback to baseline if needed.
- Platform binaries detect AVX2 + libc family at runtime, fallback to baseline if needed
+- **IntentGate (`keyword-detector`):** classifies user intent (`ultrawork`/`ulw`, `search`, `analyze`, `team`) and injects mode-specific prompts.
- Hashline edit: every Read output tagged with `LINE#ID` content hashes; edits reject on hash mismatch
+- **Hashline edit:** every `Read` output tagged with `LINE#ID` content hashes (chars from `ZPMQVRWSNKTXJBYH`); edits reject on hash mismatch.
- IntentGate: classifies user intent (research/implementation/investigation/evaluation/fix) before routing
+- **Docs:** see [`docs/guide/`](file:///Users/yeongyu/local-workspaces/omo/docs/guide/) for user-facing guides (overview, installation, orchestration, agent-model-matching, team-mode), [`docs/reference/`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/) for CLI/configuration/features reference.
@@ -1,41 +1,101 @@
 # src/ — Plugin Source
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-Entry point `index.ts` orchestrates 5-step initialization: loadConfig → createManagers → createTools → createHooks → createPluginInterface.
+Entry `index.ts` orchestrates a 7-step initialization. Total: 1304 source files + 663 tests across the directories below. Cross-cutting helpers live in `shared/`; module boundaries are established by 120 barrel `index.ts` files.
 ## KEY FILES
 | File | Purpose |
 |------|---------|
-| `index.ts` | Plugin entry, default-exports `pluginModule: PluginModule` with `{ id, server }` |
+| `index.ts` | Plugin entry; default-exports `pluginModule: PluginModule` with `{ id, server }` |
-| `plugin-config.ts` | JSONC parse, multi-level merge, Zod v4 validation |
+| `plugin-config.ts` | JSONC parse, multi-level merge (user + walked project), Zod v4 validation, migration |
 | `plugin-state.ts` | `createModelCacheState()` — model resolution cache shared across handlers |
 | `plugin-interface.ts` | 10 OpenCode hook handlers wired into `Hooks` |
 | `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler |
-| `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry (26 tools) |
+| `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry composition |
-| `create-hooks.ts` | 3-tier: Core(43) + Continuation(7) + Skill(2) = 52 hooks |
+| `create-hooks.ts` | 5-tier composition: `createCoreHooks() + createContinuationHooks() + createSkillHooks()` |
-| `plugin-interface.ts` | 10 OpenCode hook handlers: config, tool, chat.message, chat.params, chat.headers, event, tool.execute.before, tool.execute.after, experimental.chat.messages.transform, experimental.session.compacting |
+| `create-runtime-tmux-config.ts` | `isTmuxIntegrationEnabled()` + `createRuntimeTmuxConfig()` |
-## CONFIG LOADING
+## INITIALIZATION (7 STEPS)
 ```
 serverPlugin(input, options)
  1. installAgentSortShim()        # patches Array.prototype.{toSorted,sort} for canonical agent ordering
  2. initConfigContext()           # detects opencode-vs-openagent config layout
  3. detectExternalSkillPlugin()   # warn if conflicting plugin loaded
  4. injectServerAuthIntoClient()  # wire auth headers into shared SDK client
  5. loadPluginConfig()            # walk project + user JSONC → Zod safeParse → migrate
  6. initializeOpenClaw()          # if openclaw config present (start reply-listener daemon)
  6. checkTeamModeDependencies()   # if team_mode.enabled (verify git, tmux, ensure ~/.omo/teams/)
  7. createManagers/Tools/Hooks/PluginInterface
 ```
 ## CONFIG LOADING (Phase pipeline)
 ```
 loadPluginConfig(directory, ctx)
-  1. User: ~/.config/opencode/oh-my-opencode.jsonc
+  1. User: ~/.config/opencode/oh-my-openagent.jsonc (legacy: oh-my-opencode.jsonc)
-  2. Project: .opencode/oh-my-opencode.jsonc
+  2. Walked configs: <pwd up to $HOME>/.opencode/oh-my-openagent.jsonc
-  3. mergeConfigs(user, project) → deepMerge for agents/categories, Set union for disabled_*
+  3. mergeConfigs(user, walked)
     - agents/categories/claude_code: deepMerge (recursive, prototype-pollution safe)
     - disabled_*: Set union
     - mcp_env_allowlist: user-only (security)
     - others: override replaces
  4. Zod safeParse → defaults for omitted fields
-  5. migrateConfigFile() → legacy key transformation
+  5. migrateConfigFile() → idempotent via _migrations tracking + timestamped backups
 ```
-## HOOK COMPOSITION
+## HOOK COMPOSITION (5-tier)
 ```
 createHooks()
-  ├─→ createCoreHooks()           # 43 hooks
+  ├─→ createCoreHooks()
-  │   ├─ createSessionHooks()     # 24: contextWindowMonitor, thinkMode, ralphLoop, modelFallback, runtimeFallback, noSisyphusGpt, noHephaestusNonGpt, anthropicEffort, intentGate, legacyPluginToast...
+  │   ├─ createSessionHooks()     # 24: contextWindowMonitor, thinkMode, ralphLoop, modelFallback,
-  │   ├─ createToolGuardHooks()   # 14: commentChecker, rulesInjector, writeExistingFileGuard, jsonErrorRecovery, hashlineReadEnhancer, bashFileReadGuard, readImageResizer, todoDescriptionOverride, webfetchRedirectGuard...
+  │   │                             runtimeFallback, anthropicEffort, anthropicContextWindowLimitRecovery,
-  │   └─ createTransformHooks()   # 5: claudeCodeHooks, keywordDetector, contextInjector, thinkingBlockValidator, toolPairValidator
+  │   │                             autoUpdateChecker, agentUsageReminder, nonInteractiveEnv,
-  ├─→ createContinuationHooks()   # 7: todoContinuationEnforcer, atlas, stopContinuationGuard, compactionContextInjector...
+  │   │                             interactiveBashSession, editErrorRecovery, delegateTaskRetry,
  │   │                             startWork, prometheusMdOnly, sisyphusJuniorNotepad,
  │   │                             questionLabelTruncator, taskResumeInfo, noSisyphusGpt,
  │   │                             noHephaestusNonGpt, legacyPluginToast, sessionRecovery,
  │   │                             sessionNotification, preemptiveCompaction
  │   ├─ createToolGuardHooks()   # 14: commentChecker, toolOutputTruncator, directoryAgentsInjector,
  │   │                             directoryReadmeInjector, emptyTaskResponseDetector, rulesInjector,
  │   │                             tasksTodowriteDisabler, writeExistingFileGuard, bashFileReadGuard,
  │   │                             readImageResizer, todoDescriptionOverride, webfetchRedirectGuard,
  │   │                             hashlineReadEnhancer, jsonErrorRecovery
  │   └─ createTransformHooks()   # 5: claudeCodeHooks, keywordDetector, contextInjectorMessagesTransform,
  │                                  thinkingBlockValidator, toolPairValidator
  ├─→ createContinuationHooks()   # 7: stopContinuationGuard, compactionContextInjector,
  │                                  compactionTodoPreserver, todoContinuationEnforcer (boulder),
  │                                  unstableAgentBabysitter, backgroundNotificationHook, atlasHook
  └─→ createSkillHooks()          # 2: categorySkillReminder, autoSlashCommand
 ```
 Each tier produces an array of `(input, output) => void` handlers; the matching OpenCode handler iterates and calls each in registration order.
 ## SUBSYSTEM INVENTORY
 | Subdir | Files (.ts) | LOC | Purpose | Has AGENTS.md |
 |--------|-------------|-----|---------|---------------|
 | `agents/` | 96 | 19,042 | 11 agent factories + dynamic prompt builder | yes |
 | `hooks/` | 570 | 73,515 | ~50 lifecycle hooks across 57 dirs | yes |
 | `tools/` | 306 | 43,348 | 16 tool dirs producing 20–39 tools | yes |
 | `features/` | 389 | 68,410 | 20 feature modules (team-mode, background-agent, etc.) | yes |
 | `shared/` | 258 | 30,416 | Cross-cutting utilities, barrel-exported | yes |
 | `cli/` | 150 | 16,975 | Commander.js CLI: install, run, doctor, mcp-oauth | yes |
 | `plugin/` | 55 | 11,756 | 10 OpenCode hook handlers + hook composition | yes |
 | `config/` | 41 | 2,282 | 32 Zod v4 schema files | yes |
 | `plugin-handlers/` | 27 | 5,791 | 6-phase config loading pipeline | yes |
 | `openclaw/` | 26 | 3,291 | Bidirectional Discord/Telegram/HTTP integration | yes |
 | `__tests__/` | 22 | 274 | Plugin-level integration tests + perf fixtures | — |
 | `mcp/` | 7 | 205 | 3 built-in remote MCPs | yes |
 | `testing/` | 2 | 225 | Test utilities | — |
 ## NOTES
 - `plugin-interface.ts` is the **only** layer that talks to OpenCode's `Plugin` API. Every other file goes through it.
 - Reach for `shared/` before adding helpers anywhere else — duplicate utilities WILL be flagged in review.
 - Path aliases are forbidden. Use relative imports within a module, barrel imports across modules.
@@ -5,30 +5,34 @@ description: Developer reference for all 11 Oh My OpenAgent agent definitions, f
 # src/agents/ — 11 Agent Definitions
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-Agent factories following `createXXXAgent(model) → AgentConfig` pattern. Each has static `mode` property. Built via `buildAgent()` compositing factory + categories + skills.
+Agent factories follow `createXXXAgent(model) → AgentConfig` pattern. Each has static `mode` property. Built via `buildAgent()` compositing factory + categories + skills. Built-in agent registry: [`builtin-agents.ts`](file:///Users/yeongyu/local-workspaces/omo/src/agents/builtin-agents.ts) `agentSources`. Type definition: [`types.ts`](file:///Users/yeongyu/local-workspaces/omo/src/agents/types.ts) `BuiltinAgentName` (10 names + sisyphus-junior derived = 11 distinct agents).
 ## AGENT INVENTORY
-| Agent | Model | Temp | Mode | Fallback Chain | Purpose |
+| Agent | Model | Temp | Mode | Fallback Chain (top of) | Purpose |
-|-------|-------|------|------|----------------|---------|
+|-------|-------|------|------|--------------------------|---------|
-| **Sisyphus** | claude-opus-4-7 max | 0.1 | all | k2p5 -> kimi-k2.6 -> gpt-5.5 medium -> glm-5 -> big-pickle | Main orchestrator, plans + delegates |
+| **Sisyphus** | claude-opus-4-7 max | 0.1 | all | k2p5 → kimi-k2.6 → gpt-5.5 medium → glm-5 → big-pickle | Main orchestrator, plans + delegates |
-| **Hephaestus** | gpt-5.5 medium | 0.1 | all | — | Autonomous deep worker |
+| **Hephaestus** | gpt-5.5 medium | 0.1 | all | (GPT-only) | Autonomous deep worker — "Legitimate Craftsman" |
-| **Oracle** | gpt-5.5 high | 0.1 | subagent | gemini-3.1-pro high -> claude-opus-4-7 max | Read-only consultation |
+| **Oracle** | gpt-5.5 high | 0.1 | subagent | gemini-3.1-pro high → claude-opus-4-7 max → glm-5.1 | Read-only consultation |
-| **Librarian** | gpt-5.4-mini-fast | 0.1 | subagent | qwen3.5-plus -> minimax-m2.7-highspeed -> minimax-m2.7 -> claude-haiku-4-5 -> gpt-5.4-nano | External docs/code search |
+| **Librarian** | gpt-5.4-mini-fast | 0.1 | subagent | qwen3.5-plus → minimax-m2.7-highspeed → claude-haiku-4-5 → gpt-5.4-nano | External docs/code search |
-| **Explore** | gpt-5.4-mini-fast | 0.1 | subagent | qwen3.5-plus -> minimax-m2.7-highspeed -> minimax-m2.7 -> claude-haiku-4-5 -> gpt-5.4-nano | Contextual grep |
+| **Explore** | gpt-5.4-mini-fast | 0.1 | subagent | qwen3.5-plus → minimax-m2.7-highspeed → claude-haiku-4-5 → gpt-5.4-nano | Contextual grep |
-| **Multimodal-Looker** | gpt-5.3-codex medium | 0.1 | subagent | k2p5 -> gemini-3-flash -> glm-4.6v -> gpt-5-nano | PDF/image analysis |
+| **Multimodal-Looker** | gpt-5.5 medium | 0.1 | subagent | kimi-k2.6 → glm-4.6v → gpt-5-nano | PDF/image analysis |
-| **Metis** | claude-opus-4-7 max | **0.3** | subagent | gpt-5.5 high -> gemini-3.1-pro high | Pre-planning consultant |
+| **Metis** | claude-opus-4-7 max | **0.3** | subagent | gpt-5.5 high → gemini-3.1-pro high → glm-5.1 → k2p5 | Pre-planning consultant |
-| **Momus** | gpt-5.5 xhigh | 0.1 | subagent | claude-opus-4-7 max -> gemini-3.1-pro high | Plan reviewer |
+| **Momus** | gpt-5.5 xhigh | 0.1 | subagent | claude-opus-4-7 max → gemini-3.1-pro high → glm-5.1 | Plan reviewer |
-| **Atlas** | claude-sonnet-4-6 | 0.1 | primary | gpt-5.5 medium | Todo-list orchestrator |
+| **Atlas** | claude-sonnet-4-6 | 0.1 | primary | kimi-k2.6 → gpt-5.5 medium → minimax-m2.7 | Todo-list orchestrator |
-| **Prometheus** | claude-opus-4-7 max | 0.1 | — | internal planner | Strategic planner (internal) |
+| **Prometheus** | claude-opus-4-7 max | 0.1 | primary | gpt-5.5 high → glm-5.1 → gemini-3.1-pro | Strategic planner (interview) |
 | **Sisyphus-Junior** | claude-sonnet-4-6 | 0.1 | all | user-configurable | Category-spawned executor |
 Authoritative chains live in [`src/shared/model-requirements.ts`](file:///Users/yeongyu/local-workspaces/omo/src/shared/model-requirements.ts).
 ## TOOL RESTRICTIONS
 Defined in [`src/shared/agent-tool-restrictions.ts`](file:///Users/yeongyu/local-workspaces/omo/src/shared/agent-tool-restrictions.ts).
 | Agent | Denied Tools |
 |-------|-------------|
 | Oracle | write, edit, task, call_omo_agent |
@@ -37,37 +41,41 @@ Agent factories following `createXXXAgent(model) → AgentConfig` pattern. Each
 | Multimodal-Looker | ALL except read |
 | Atlas | task, call_omo_agent |
 | Momus | write, edit, task |
 | Prometheus | enforces `.md`-only writes via `prometheus-md-only` hook (path-based, not tool-based) |
 ## TEAM-MODE ELIGIBILITY
 Only **sisyphus, atlas, sisyphus-junior, hephaestus** can be team members. Read-only agents (oracle, librarian, explore, multimodal-looker, metis, momus, prometheus) are rejected at TeamSpec parse. See [`team-mode/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/features/team-mode/AGENTS.md).
 ## STRUCTURE
 ```
 agents/
-├── sisyphus.ts            # 559 LOC, main orchestrator
+├── sisyphus.ts                                # Main orchestrator router
-├── hephaestus.ts          # 507 LOC, autonomous worker
+├── sisyphus/                                  # Model-specific variant prompts
-├── oracle.ts              # Read-only consultant
+│   ├── default.ts, gemini.ts, gpt-5-4.ts, gpt-5-5.ts
-├── librarian.ts           # External search
+├── hephaestus.ts                              # Routes to model variant
-├── explore.ts             # Codebase grep
+├── hephaestus/                                # gpt.ts, gpt-5-3-codex.ts, gpt-5-4.ts, gpt-5-5.ts
-├── multimodal-looker.ts   # Vision/PDF
+├── oracle.ts                                  # Read-only consultant
-├── metis.ts               # Pre-planning
+├── librarian.ts                               # External search
-├── momus.ts               # Plan review
+├── explore.ts                                 # Codebase grep
-├── atlas/agent.ts         # Todo orchestrator
+├── multimodal-looker.ts                       # Vision/PDF
-├── types.ts               # AgentFactory, AgentMode
+├── metis.ts                                   # Pre-planning
-├── agent-builder.ts       # buildAgent() composition
+├── momus.ts                                   # Plan review
-├── utils.ts               # Agent utilities
+├── atlas/agent.ts                             # Todo orchestrator
-├── builtin-agents.ts      # createBuiltinAgents() registry
+├── prometheus/                                # Strategic planner — system-prompt.ts, identity-constraints.ts, interview-mode.ts, plan-template.ts, gemini.ts, gpt.ts
-├── dynamic-agent-prompt-builder.ts    # Dynamic prompt builder system
+├── types.ts                                   # BuiltinAgentName, AgentMode, AgentConfig
-├── dynamic-agent-core-sections.ts   # Core prompt sections
+├── builtin-agents.ts                          # agentSources registry (10 → 11 with sisyphus-junior)
-├── dynamic-agent-policy-sections.ts # Policy prompt sections
+├── builtin-agents/                            # maybeCreateXXXConfig conditional factories + general-agents.ts + available-skills.ts
-├── dynamic-agent-tool-categorization.ts # Tool categorization
+├── agent-builder.ts                           # buildAgent() composition
-├── dynamic-agent-category-skills-guide.ts # Category skills guide
+├── utils.ts                                   # agent utilities
-├── custom-agent-summaries.ts        # Custom agent summaries
+├── env-context.ts                             # environment context for prompts
-├── env-context.ts                   # Environment context
+├── custom-agent-summaries.ts                  # custom-agent prompt summaries
-└── builtin-agents/        # maybeCreateXXXConfig conditional factories
+├── dynamic-agent-prompt-builder.ts            # dynamic prompt builder
-    ├── sisyphus-agent.ts
+├── dynamic-agent-core-sections.ts             # core prompt sections
-    ├── hephaestus-agent.ts
+├── dynamic-agent-policy-sections.ts           # policy sections
-    ├── atlas-agent.ts
+├── dynamic-agent-tool-categorization.ts       # tool categorization for prompt
-    ├── general-agents.ts  # collectPendingBuiltinAgents
+└── dynamic-agent-category-skills-guide.ts     # category-skill guidance
    └── available-skills.ts
 ```
 ## FACTORY PATTERN
@@ -82,10 +90,24 @@ const createXXXAgent: AgentFactory = (model: string) => ({
 createXXXAgent.mode = "subagent" // or "primary" or "all"
 ```
-Model resolution: 4-step: override → category-default → provider-fallback → system-default. Defined in `shared/model-requirements.ts`.
+Model resolution: 4-step pipeline → override → category-default → provider-fallback → system-default. Defined in [`shared/model-resolution-pipeline.ts`](file:///Users/yeongyu/local-workspaces/omo/src/shared/model-resolution-pipeline.ts).
 ## MODES
- **primary**: Respects UI-selected model, uses fallback chain
+- **`primary`** — respects UI-selected model, uses fallback chain (Atlas, Prometheus)
- **subagent**: Uses own fallback chain, ignores UI selection
+- **`subagent`** — uses own fallback chain, ignores UI selection (Oracle, Librarian, Explore, etc.)
- **all**: Available in both contexts (Sisyphus-Junior)
+- **`all`** — available in both contexts (Sisyphus, Hephaestus, Sisyphus-Junior)
 ## CANONICAL ORDER
 `Sisyphus → Hephaestus → Prometheus → Atlas` (primary core agents) then alphabetical for the rest. Enforced by [`installAgentSortShim()`](file:///Users/yeongyu/local-workspaces/omo/src/shared/agent-sort-shim.ts) — patches `Array.prototype.{toSorted,sort}` narrowly when ≥2 canonical core agents are in the array. See [`src/plugin-handlers/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/plugin-handlers/AGENTS.md) for the full history.
 ## DYNAMIC PROMPT BUILDER
 `dynamic-agent-prompt-builder.ts` composes per-agent system prompts at runtime by stitching:
 - Core sections (identity, mode, restrictions)
 - Policy sections (citation, verification, anti-patterns)
 - Tool categorization (per-domain tool guidance)
 - Category-skills guide (which skills load with which categories)
 This is what the Sisyphus prompt's "AGENTS / CATEGORY + SKILLS" tables come from.
@@ -5,7 +5,7 @@ description: Developer reference for the Hephaestus autonomous deep worker agent
 # src/agents/hephaestus/ -- Autonomous Deep Worker
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -5,7 +5,7 @@ description: Developer reference for the Prometheus strategic planner agent —
 # src/agents/prometheus/ -- Strategic Planner
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -5,7 +5,7 @@ description: Developer reference for Sisyphus orchestrator model-specific prompt
 # src/agents/sisyphus/ -- Orchestrator Variants
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/cli/ — CLI: install, run, doctor, mcp-oauth
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/cli/config-manager/ — CLI Installation Utilities
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/cli/doctor/ — Health Diagnostics (25 Check Files)
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/cli/run/ — Non-Interactive Session Launcher
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,57 +1,78 @@
 # src/config/ — Zod v4 Schema System
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-32 schema files composing `OhMyOpenCodeConfigSchema`. Zod v4 validation with `safeParse()`. All fields optional — omitted fields use plugin defaults.
+30 non-test schema files composing `OhMyOpenCodeConfigSchema`. Zod v4 validation with `safeParse()`. All fields optional — omitted fields use defaults from the schema. Auto-emitted to `assets/oh-my-opencode.schema.json` via `bun run build:schema`.
 ## SCHEMA TREE
 ```
 config/schema/
-├── oh-my-opencode-config.ts    # ROOT: OhMyOpenCodeConfigSchema (composes all below)
+├── oh-my-opencode-config.ts    # ROOT: composes all sub-schemas
-├── agent-names.ts              # BuiltinAgentNameSchema (11), OverridableAgentNameSchema (14)
+├── agent-names.ts              # BuiltinAgentNameSchema (10) + sisyphus-junior
 ├── agent-overrides.ts          # AgentOverrideConfigSchema (21 fields per agent)
 ├── agent-definitions.ts        # custom agent definition schema
 ├── categories.ts               # 8 built-in + custom categories
-├── hooks.ts                    # HookNameSchema (48 hooks)
+├── hooks.ts                    # HookNameSchema (50+ hooks)
 ├── skills.ts                   # SkillsConfigSchema (sources, paths, recursive)
 ├── commands.ts                 # BuiltinCommandNameSchema
-├── experimental.ts             # Feature flags (plugin_load_timeout_ms min 1000)
+├── experimental.ts             # Feature flags incl plugin_load_timeout_ms (min 1000), task_system, max_tools
 ├── sisyphus.ts                 # SisyphusConfigSchema (task system)
 ├── sisyphus-agent.ts           # SisyphusAgentConfigSchema
 ├── ralph-loop.ts               # RalphLoopConfigSchema
 ├── tmux.ts                     # TmuxConfigSchema + TmuxLayoutSchema
 ├── websearch.ts                # provider: "exa" | "tavily"
-├── claude-code.ts              # CC compatibility settings
+├── claude-code.ts              # CC compatibility settings (plugins, plugins_override)
 ├── comment-checker.ts          # AI comment detection config
 ├── notification.ts             # OS notification settings
 ├── git-master.ts               # commit_footer: boolean | string
-├── browser-automation.ts       # provider: playwright | agent-browser | playwright-cli
+├── git-env-prefix.ts           # Git environment prefix config
-├── background-task.ts          # Concurrency limits per model/provider
+├── browser-automation.ts       # provider: playwright | playwright-cli | agent-browser
 ├── background-task.ts          # Concurrency limits per model/provider, syncPollTimeoutMs
 ├── fallback-models.ts          # FallbackModelsConfigSchema
-├── runtime-fallback.ts         # RuntimeFallbackConfigSchema
+├── runtime-fallback.ts         # RuntimeFallbackConfigSchema (reactive provider fallback)
 ├── babysitting.ts              # Unstable agent monitoring
 ├── dynamic-context-pruning.ts  # Context pruning settings
-├── start-work.ts              # StartWorkConfigSchema (auto_commit)
+├── start-work.ts               # StartWorkConfigSchema (auto_commit)
-├── openclaw.ts                # OpenClaw integration settings
+├── openclaw.ts                 # OpenClaw integration settings
-├── git-env-prefix.ts          # Git environment prefix config
+├── model-capabilities.ts       # Model capabilities config
-├── model-capabilities.ts      # Model capabilities config
+├── keyword-detector.ts         # disabled_keywords (ultrawork|search|analyze|team)
-└── internal/permission.ts      # AgentPermissionSchema
+└── team-mode.ts                # TeamModeConfigSchema (enabled, max_parallel_members, max_members, tmux_visualization)
 ```
-## ROOT SCHEMA FIELDS (32)
+## ROOT SCHEMA FIELDS
-`$schema`, `new_task_system_enabled`, `default_run_agent`, `disabled_mcps`, `disabled_agents`, `disabled_skills`, `disabled_hooks`, `disabled_commands`, `disabled_tools`, `hashline_edit`, `agents`, `categories`, `claude_code`, `sisyphus_agent`, `comment_checker`, `experimental`, `auto_update`, `skills`, `ralph_loop`, `background_task`, `notification`, `babysitting`, `git_master`, `browser_automation_engine`, `websearch`, `tmux`, `sisyphus`, `start_work`, `_migrations`, `model_fallback`, `model_capabilities`, `openclaw`, `mcp_env_allowlist`
+`$schema`, `new_task_system_enabled`, `default_run_agent`, `disabled_mcps`, `disabled_agents`, `disabled_skills`, `disabled_hooks`, `disabled_commands`, `disabled_tools`, `hashline_edit`, `agents`, `categories`, `claude_code`, `sisyphus_agent`, `comment_checker`, `experimental`, `auto_update`, `skills`, `ralph_loop`, `background_task`, `notification`, `babysitting`, `git_master`, `browser_automation_engine`, `websearch`, `tmux`, `sisyphus`, `start_work`, `_migrations`, `model_fallback`, `model_capabilities`, `openclaw`, `mcp_env_allowlist`, `keyword_detector`, **`team_mode`**, `runtime_fallback`, `dynamic_context_pruning`.
-## AGENT OVERRIDE FIELDS (21)
+## TEAM_MODE SCHEMA
-`model`, `variant`, `category`, `skills`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `providerOptions`
+```jsonc
 {
  "team_mode": {
    "enabled": false,                  // gate for 12 team_* tools and conditional hooks
    "max_parallel_members": 4,         // concurrent active members
    "max_members": 8,                  // hard cap on team size
    "tmux_visualization": false        // render tmux pane layout for the team
  }
 }
 ```
-## HOW TO ADD CONFIG
+When `enabled: true`:
 - 12 `team_*` tools register
 - 4 team-mode hooks activate (status injector, mailbox injector, session events, tool gating)
 - `team-mode` built-in skill loads
 - Doctor check `cli/doctor/checks/team-mode.ts` runs
 ## AGENT OVERRIDE FIELDS (per-agent)
 `model`, `variant`, `category`, `skills`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `providerOptions`, `fallback_models`, `ultrawork`.
 ## HOW TO ADD A CONFIG FIELD
 1. Create `src/config/schema/{name}.ts` with Zod schema
 2. Add field to `oh-my-opencode-config.ts` root schema
-3. Reference via `z.infer<typeof YourSchema>` for TypeScript types
+3. Reference via `z.infer<typeof YourSchema>` for the TypeScript type
-4. Access in handlers via `pluginConfig.{name}`
+4. Access in handlers via `pluginConfig.{field_name}` (snake_case JSON, snake_case TS field)
 5. Run `bun run build:schema` to regenerate `assets/oh-my-opencode.schema.json`
@@ -1,73 +1,84 @@
-# src/features/ — 19 Feature Modules
+# src/features/ — 20 Feature Modules
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-Standalone feature modules wired into plugin/ layer. Each is self-contained with own types, implementation, and tests.
+Standalone feature modules wired into `plugin/` layer. Each is self-contained with own types, implementation, and co-located tests. Most expose a single factory or class via `index.ts` barrel.
 ## MODULE MAP
 | Module | Files | Complexity | Purpose |
 |--------|-------|------------|---------|
-| **opencode-skill-loader** | 33 | HIGH | YAML frontmatter skill loading from 4 scopes |
+| **background-agent** | 47 | HIGH | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker |
-| **background-agent** | 47 | HIGH | Task lifecycle, concurrency (5/model), polling, spawner pattern, circuit breaker |
+| **opencode-skill-loader** | 33 | HIGH | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) |
-| **tmux-subagent** | 34 | HIGH | Tmux pane management, grid planning, session orchestration |
+| **tmux-subagent** | 34 | HIGH | Tmux pane management, grid planning, session orchestration via `runTmuxCommand` |
-| **mcp-oauth** | 18 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) for MCP servers |
+| **team-mode** | 24 dirs / 100+ files | HIGH | Parallel multi-agent coordination — 12 `team_*` tools, mailbox, tasklist, worktrees, optional tmux layout |
-| **builtin-skills** | 17 | LOW | 8 skills: git-master, playwright, playwright-cli, agent-browser, dev-browser, frontend-ui-ux, review-work, ai-slop-remover |
+| **mcp-oauth** | 18 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) + step-up auth for MCP servers |
-| **skill-mcp-manager** | 18 | HIGH | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth step-up) |
+| **skill-mcp-manager** | 18 | HIGH | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth) |
-| **claude-code-plugin-loader** | 15 | MEDIUM | Unified plugin discovery from .opencode/plugins/ |
+| **claude-code-plugin-loader** | 16 | MEDIUM | Unified Claude Code plugin discovery (commands, agents, skills, hooks, MCPs) |
-| **builtin-commands** | 11 | LOW | Command templates: refactor, init-deep, handoff, etc. |
+| **builtin-skills** | 17 | LOW–MED | 10 built-in skill files (git-master, playwright, frontend-ui-ux, review-work, ai-slop-remover, dev-browser, playwright-cli, **team-mode**, …) |
-| **claude-tasks** | 7 | MEDIUM | Task schema + file storage + OpenCode todo sync |
+| **builtin-commands** | 11 | LOW | Command templates: refactor, init-deep, handoff, ulw-loop, etc. |
-| **claude-code-mcp-loader** | 6 | MEDIUM | .mcp.json loading with ${VAR} env expansion |
+| **claude-tasks** | 7 | MEDIUM | Sisyphus task schema + atomic file storage + OpenCode todo API sync |
-| **context-injector** | 6 | MEDIUM | AGENTS.md/README.md injection into context |
+| **claude-code-mcp-loader** | 11 | MEDIUM | Tier-2 MCP loader: `.mcp.json` parse + `${VAR}` env expansion |
-| **run-continuation-state** | 5 | LOW | Persistent state for `run` command continuation across sessions |
+| **context-injector** | 6 | MEDIUM | AGENTS.md/README.md injection into session context |
-| **hook-message-injector** | 5 | MEDIUM | System message injection for hooks |
+| **run-continuation-state** | 5 | LOW | Persistent state for `oh-my-opencode run` continuation across invocations |
-| **boulder-state** | 5 | LOW | Persistent state for multi-step operations |
+| **hook-message-injector** | 5 | MEDIUM | System message injection helper used by hooks |
 | **boulder-state** | 5 | LOW | Persistent state for boulder/multi-step operations |
 | **task-toast-manager** | 4 | MEDIUM | Task progress notifications |
 | **tool-metadata-store** | 3 | LOW | Tool execution metadata cache |
 | **claude-code-session-state** | 3 | LOW | Subagent session state tracking |
-| **claude-code-command-loader** | 3 | LOW | Load commands from .opencode/commands/ |
+| **claude-code-command-loader** | 3 | LOW | Load `/commands` from `.opencode/commands/` and Claude Code plugins |
-| **claude-code-agent-loader** | 3 | LOW | Load agents from .opencode/agents/ |
+| **claude-code-agent-loader** | 3 | LOW | Load agents from `.opencode/agents/` and Claude Code plugins |
 ## KEY MODULES
-### background-agent (47 files, ~10k LOC)
+### background-agent (~10k LOC)
 Core orchestration engine. `BackgroundManager` manages task lifecycle:
- States: pending → running → completed/error/cancelled/interrupt
+- States: `pending → running → completed | error | cancelled | interrupt`
- Concurrency: per-model/provider limits via `ConcurrencyManager` (FIFO queue)
+- Concurrency: per-key (`${providerID}/${modelID}`) limits via `ConcurrencyManager` (FIFO queue)
- Polling: 3s interval, completion via idle events + stability detection (10s unchanged)
+- Polling: 3s interval, completion detected via idle event AND stability detection (10s unchanged)
 - Circuit breaker: automatic failure detection and recovery
- spawner/: 8 focused files composing via `SpawnerContext` interface
+- `spawner/`: 8 focused files composing via `SpawnerContext` interface
-### opencode-skill-loader (33 files, ~3.2k LOC)
+### team-mode (~13k LOC)
 Parallel multi-agent coordination, OFF by default. Subdirs:
 - `team-registry/` — load/validate `~/.omo/teams/{name}/config.json`
 - `team-state-store/` — durable runtime state with atomic locks
 - `team-runtime/` — `team_create`, status, shutdown lifecycle
 - `team-mailbox/` — async messaging (send/poll/ack)
 - `team-tasklist/` — shared tasks with atomic claiming
 - `team-worktree/` — git worktree per member
 - `team-layout-tmux/` — optional tmux pane visualization
 - `tools/` — 12 `team_*` tool implementations
 Eligible members: sisyphus, atlas, sisyphus-junior, hephaestus only. See [`team-mode/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/features/team-mode/AGENTS.md).
 ### opencode-skill-loader (~3.2k LOC)
 4-scope skill discovery (project > opencode > user > global):
 - YAML frontmatter parsing from SKILL.md files
 - Skill merger with priority deduplication
 - Template resolution with variable substitution
 - Provider gating for model-specific skills
-### tmux-subagent (34 files, ~3.6k LOC)
+### tmux-subagent (~3.6k LOC)
-State-first tmux integration:
+State-first tmux integration. Centralized tmux command execution through `src/shared/tmux/runner.ts` (`runTmuxCommand`). Direct `Bun.spawn(["tmux", ...])` is FORBIDDEN — would drift from retry/timeout discipline.
 - `TmuxSessionManager`: pane lifecycle, grid planning
 - Spawn action decider + target finder
 - Polling manager for session health
 - Event handlers for pane creation/destruction
-### builtin-skills (8 skill objects)
+### builtin-skills (10 skills)
-| Skill | Size | MCP | Tools |
+| Skill | LOC | MCP | Notes |
-|-------|------|-----|-------|
+|-------|-----|-----|-------|
-| git-master | 1111 LOC | — | Bash |
+| git-master | 1111 | — | Atomic commits, rebase, history search |
-| playwright | 312 LOC | @playwright/mcp | — |
+| playwright | 312 | @playwright/mcp | Browser automation via MCP |
-| agent-browser | (in playwright.ts) | — | Bash(agent-browser:*) |
+| playwright-cli | 268 | — | Browser automation via CLI |
-| playwright-cli | 268 LOC | — | Bash(playwright-cli:*) |
+| dev-browser | 221 | — | Persistent page state browser |
-| dev-browser | 221 LOC | — | Bash |
+| review-work | ~500 | — | 5-agent post-implementation review orchestrator |
-| frontend-ui-ux | 79 LOC | — | — |
+| ai-slop-remover | ~300 | — | Remove AI code patterns |
-| review-work | ~LOC | --- | --- |
+| **team-mode** | — | — | Loaded only when `team_mode.enabled` (skill explains the 12 tools to agents) |
-| ai-slop-remover | ~LOC | --- | --- |
+| frontend-ui-ux | 79 | — | Design-first UI development |
 | (git-master-skill-metadata) | — | — | Companion to git-master |
-Browser variant selected by `browserProvider` config: playwright (default) | playwright-cli | agent-browser.
+Browser variant selected by `browser_automation_engine` config: `playwright` (default) | `playwright-cli` | `agent-browser`.
@@ -1,6 +1,6 @@
 # src/features/background-agent/ — Core Orchestration Engine
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,50 +1,81 @@
-# src/features/builtin-skills/ -- 8 Built-in Skills
+# src/features/builtin-skills/ — 10 Built-in Skill Files
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
-24 files. 8 built-in skills registered via `createBuiltinSkills()`. Each skill implements `BuiltinSkill` interface with name, description, content, and optional MCP config.
+Skills shipped inside the plugin (always available, no install). Registered via `createBuiltinSkills()`. Each skill implements the `BuiltinSkill` interface with name, description, content, and optional MCP config. Loaded by `opencode-skill-loader` with priority: project > opencode > user > **builtin**. User-installed skills with the same name override built-ins.
 ## STRUCTURE
 ```
 builtin-skills/
 ├── index.ts              # Barrel exports
-├── skills.ts             # createBuiltinSkills() factory
+├── skills.ts             # createBuiltinSkills() factory — registers all 10 below
 ├── types.ts              # BuiltinSkill interface
-├── git-master/           # SKILL.md + resources
+├── skills/
-├── frontend-ui-ux/       # SKILL.md
+│   ├── git-master.ts                  # 1111 LOC
-├── agent-browser/        # SKILL.md
+│   ├── git-master-skill-metadata.ts   # Companion to git-master
-├── dev-browser/          # SKILL.md
+│   ├── playwright.ts                  # MCP variant + agent-browser
-└── skills/               # Skill implementations as .ts files
+│   ├── playwright-cli.ts              # CLI variant
-    ├── git-master-sections/  # Git master prompt sections
+│   ├── dev-browser.ts                 # Persistent page state
-    ├── playwright.ts         # Playwright + agent-browser + playwright-cli + dev-browser
+│   ├── frontend-ui-ux.ts              # Design-first UI guidance
-    ├── frontend-ui-ux.ts     # Frontend UI/UX skill
+│   ├── review-work.ts                 # 5-agent post-implementation review
-    ├── review-work.ts        # 5-agent parallel review orchestrator
+│   ├── ai-slop-remover.ts             # Remove AI-generated code patterns
-    └── ai-slop-remover.ts    # AI code smell remover
+│   ├── team-mode.ts                   # 12 team_* tool documentation (gated)
 │   ├── git-master-sections/           # Git-master prompt sub-sections
 │   └── index.ts                       # skill barrel
 ├── git-master/                        # Resources for git-master skill
 ├── frontend-ui-ux/                    # Resources for frontend-ui-ux skill
 ├── agent-browser/                     # Resources for agent-browser variant
 └── dev-browser/                       # Resources for dev-browser
 ```
 ## SKILL CATALOG
-| Skill | LOC | MCP | Purpose |
+| Skill | Approx LOC | MCP | Notes |
-|-------|-----|-----|---------|
+|-------|------------|-----|-------|
-| **git-master** | 1111 | -- | Atomic commits, rebase, history search |
+| `git-master` | 1111 | — | Atomic commits, rebase, history search; included by default for delegate-task `git` category |
-| **playwright** | 312 | @playwright/mcp | Browser automation via MCP |
+| `playwright` | 312 | `@playwright/mcp` | Browser automation via MCP |
-| **playwright-cli** | 268 | -- | Browser automation via CLI |
+| `playwright-cli` | 268 | — | Browser automation via shell CLI (no MCP) |
-| **agent-browser** | (in playwright.ts) | -- | Browser via agent-browser tool |
+| `agent-browser` | (in playwright.ts) | — | Browser via `agent-browser:*` Bash commands |
-| **dev-browser** | 221 | -- | Persistent page state browser |
+| `dev-browser` | 221 | — | Persistent page state browser for dev work |
-| **frontend-ui-ux** | 79 | -- | Design-first UI development |
+| `frontend-ui-ux` | 79 | — | Design-first UI development guidance |
-| **review-work** | ~500 | -- | 5-agent post-implementation review |
+| `review-work` | ~500 | — | Post-implementation review orchestrator (5 parallel agents) |
-| **ai-slop-remover** | ~300 | -- | Remove AI code patterns |
+| `ai-slop-remover` | ~300 | — | Remove AI-generated code smells |
 | `team-mode` | — | — | **Conditional** — only loaded when `team_mode.enabled`; documents the 12 `team_*` tools and lifecycle |
 ## BROWSER VARIANT SELECTION
 Config `browser_automation_engine` selects which browser skill loads:
 - `"playwright"` (default) -> playwright with @playwright/mcp
 - `"playwright-cli"` -> CLI-based playwright
 - `"agent-browser"` -> agent-browser tool
-## SKILL LOADING
+| Value | Skill Loaded |
 |-------|-------------|
 | `"playwright"` (default) | playwright (MCP-backed) |
 | `"playwright-cli"` | playwright-cli (CLI-backed) |
 | `"agent-browser"` | agent-browser (in playwright.ts) |
-Skills loaded by `opencode-skill-loader` with priority: project > opencode > user > builtin. User-installed skills with same name override built-ins.
+Only one browser skill is active per session — non-selected variants are skipped.
 ## TEAM-MODE SKILL GATING
 The `team-mode` skill is registered unconditionally but only **rendered** when `team_mode.enabled: true`:
 ```typescript
 // skills/team-mode.ts (paraphrase)
 const teamModeSkill: BuiltinSkill = {
  name: "team-mode",
  shouldLoad: (config) => config.team_mode?.enabled === true,
  // ...
 }
 ```
 When disabled, the skill is filtered out before agent prompt assembly so agents do not see `team_*` tool docs they cannot use.
 ## ADDING A NEW BUILT-IN SKILL
 1. Create `skills/{name}.ts` exporting a `BuiltinSkill` object
 2. Register in `skills.ts` `createBuiltinSkills()` factory
 3. Add resources (if any) under a sibling directory: `{name}/SKILL.md`, prompt sections, etc.
 4. If the skill is conditional, set `shouldLoad: (config) => …`
 5. Optionally declare an MCP server in the skill (loaded by `skill-mcp-manager` per session)
@@ -1,6 +1,6 @@
 # src/features/claude-code-mcp-loader/ — Tier 2 MCP Loader (.mcp.json)
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/features/claude-code-plugin-loader/ — Unified Claude Code Plugin Loader
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/features/claude-tasks/ — Task Schema + Storage
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/features/mcp-oauth/ — OAuth 2.0 + PKCE + DCR for MCP Servers
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/features/opencode-skill-loader/ — 4-Scope Skill Discovery
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/features/skill-mcp-manager/ — Skill-Embedded MCP Client Lifecycle
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,92 +1,160 @@
 # team-mode — Parallel Multi-Agent Coordination
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-Parity with Claude Code Agent Teams. OFF by default. Enable via `team_mode.enabled` in config.
+Spawns coordinated agent teams with shared mailbox, task list, optional tmux layout, and graceful lifecycle. Modeled after Claude Code Agent Teams. **OFF by default.** Enable via `team_mode.enabled` in `oh-my-opencode.jsonc`; restart OpenCode after enabling.
-Spawns coordinated agent teams with shared mailbox, task list, and lifecycle management. Lead delegates, members claim tasks, graceful shutdown with acks.
+User docs: [`docs/guide/team-mode.md`](file:///Users/yeongyu/local-workspaces/omo/docs/guide/team-mode.md).
 ## CONFIG
 ```jsonc
 {
  "team_mode": {
    "enabled": true,
    "max_parallel_members": 4,    // concurrent active members
    "max_members": 8,             // hard cap on team size
    "tmux_visualization": false   // optional tmux pane layout
  }
 }
 ```
 Schema: [`src/config/schema/team-mode.ts`](file:///Users/yeongyu/local-workspaces/omo/src/config/schema/team-mode.ts).
 ## 12 TEAM_* TOOLS
 Registered via [`src/plugin/tool-registry.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) `teamModeToolsRecord` only when enabled.
 | Tool | Source File | Purpose |
 |------|-------------|---------|
 | `team_create` | `tools/lifecycle.ts` | Spawn team + member sessions from named or inline TeamSpec |
 | `team_delete` | `tools/lifecycle.ts` | Tear down state, mailbox, tasklist, worktrees, optional tmux |
 | `team_shutdown_request` | `tools/lifecycle.ts` | Member or lead requests its own shutdown |
 | `team_approve_shutdown` | `tools/lifecycle.ts` | Lead acks shutdown |
 | `team_reject_shutdown` | `tools/lifecycle.ts` | Lead rejects shutdown with reason |
 | `team_send_message` | `tools/messaging.ts` | Send to member name or `*` broadcast |
 | `team_task_create` | `tools/tasks.ts` | Create task on shared list |
 | `team_task_list` | `tools/tasks.ts` | List tasks (filter by status / owner) |
 | `team_task_update` | `tools/tasks.ts` | Claim / complete / delete (atomic file lock) |
 | `team_task_get` | `tools/tasks.ts` | Fetch single task |
 | `team_status` | `tools/query.ts` | Full team run status (members, tasks, mailbox) |
 | `team_list` | `tools/query.ts` | List declared + active teams |
 ## ELIGIBLE AGENTS
 ```
 ALLOWED: sisyphus, atlas, sisyphus-junior, hephaestus
 REJECTED at parse: oracle, librarian, explore, multimodal-looker, metis, momus, prometheus
 ```
 Read-only and orchestration-only agents are blocked at TeamSpec parse time. For those, the lead delegates via `task` (delegate-task) instead.
 Eligibility registry: [`types.ts`](file:///Users/yeongyu/local-workspaces/omo/src/features/team-mode/types.ts) `AGENT_ELIGIBILITY_REGISTRY`.
 ## MEMBER KINDS
 ```jsonc
 {
  "members": [
    { "kind": "subagent_type", "name": "scout", "subagent_type": "sisyphus" },
    { "kind": "category", "name": "writer", "category": "writing", "prompt": "Write release notes" }
  ]
 }
 ```
 - `kind: "subagent_type"` — direct agent. `prompt` optional.
 - `kind: "category"` — routed through `sisyphus-junior` with the chosen category model. `prompt` REQUIRED.
 ## MODULE LAYOUT
 ```
 team-mode/
-├── index.ts                    # barrel exports (types, worktree)
+├── index.ts                    # barrel
-├── types.ts                    # Zod schemas: TeamSpec, Member, Message, Task, RuntimeState
+├── types.ts                    # Zod schemas: TeamSpec, Member, Message, Task, RuntimeState; AGENT_ELIGIBILITY_REGISTRY
-├── member-parser.ts            # member validation with eligibility registry
+├── deps.ts                     # checkTeamModeDependencies (git, tmux availability)
-├── deps.ts                     # dependency injection types
+├── member-parser.ts            # member validation against eligibility registry
-├── team-session-registry.ts    # in-memory sessionId -> team/member map for spawn-race-safe lookups
+├── member-guidance.ts          # auto-injected guidance per member kind
-├── team-registry/              # team spec loading from ~/.omo/teams/
+├── member-session-resolution.ts
-│   ├── index.ts
+├── member-session-routing.ts
-│   ├── loader.ts               # load from user + project scopes
+├── resolve-caller-team-lead.ts # determine if a session is acting as lead
-│   ├── paths.ts                # path resolution
+├── team-session-registry.ts    # spawn-race-safe sessionID → team/member lookups
-│   └── validator.ts            # TeamSpec validation
+├── team-registry/              # team spec loading from ~/.omo/teams/{name}/config.json
-├── team-state-store/           # durable runtime state
+│   ├── loader.ts
-│   ├── index.ts
+│   ├── paths.ts                # ensureBaseDirs, resolveBaseDir
-│   ├── store.ts                # CRUD for state.json
+│   └── validator.ts
-│   ├── resume.ts               # resume orphaned runs
+├── team-state-store/           # durable runtime state.json with atomic locks
-│   └── locks.ts                # atomic file locks
+├── team-runtime/               # create/status/shutdown lifecycle
-├── team-runtime/               # team lifecycle
+├── team-mailbox/               # async messaging (send / poll / ack / inbox)
-│   ├── index.ts
+├── team-tasklist/              # CRUD + claiming + dependencies
-│   ├── create.ts               # team_create implementation
+├── team-worktree/              # one git worktree per member; cleanup on delete
-│   ├── status.ts               # team_status implementation
+├── team-layout-tmux/           # optional pane layout — close-team-member-pane, sweep-stale-team-sessions
-│   ├── shutdown.ts             # shutdown request/approve/reject
+└── tools/                      # 12 team_* tool implementations + tests
 │   ├── resolve-member.ts       # member agent resolution
 │   └── resolve-member-dependencies.ts
 ├── team-mailbox/               # async messaging
 │   ├── index.ts
 │   ├── send.ts                 # team_send_message
 │   ├── poll.ts                 # inbox polling
 │   ├── ack.ts                  # message ack
 │   └── inbox.ts                # inbox file ops
 ├── team-tasklist/              # shared task list
 │   ├── index.ts
 │   ├── store.ts                # task CRUD
 │   ├── list.ts                 # team_task_list
 │   ├── get.ts                  # team_task_get
 │   ├── update.ts               # team_task_update (claim, complete)
 │   ├── claim.ts                # task claiming with locks
 │   └── dependencies.ts         # task dependency graph
 ├── team-worktree/              # git worktree per member
 │   ├── index.ts
 │   ├── manager.ts              # worktree lifecycle
 │   └── cleanup.ts              # worktree removal
 ├── team-layout-tmux/           # optional tmux visualization
 │   ├── index.ts
 │   ├── layout.ts               # pane layout management
 │   ├── close-team-member-pane.ts # close member pane + rebalance window
 │   ├── rebalance-team-window.ts  # redistribute layout after pane changes
 │   └── sweep-stale-team-sessions.ts # garbage-collect orphaned team tmux sessions
 └── tools/                      # 12 team_* tools
    ├── index.ts                # tool registration
    ├── lifecycle.ts            # create, delete, shutdown
    ├── messaging.ts            # send_message
    ├── tasks.ts                # task_create, list, update, get
    └── query.ts                # status, list
 ```
 ## STORAGE LAYOUT
-See user guide: `docs/guide/team-mode.md`
+```
 ~/.omo/teams/{name}/                       # user scope
 <project>/.omo/teams/{name}/               # project scope (wins on collision)
  ├── config.json                          # TeamSpec
  ├── state.json                           # runtime: members, sessionIDs, lifecycle
  ├── mailbox/                             # one .jsonl per recipient
  ├── tasklist.jsonl                       # shared task list
  └── worktrees/{member-name}/             # git worktree per member
 ```
 ## LIFECYCLE
 ```
 1. team_create
   → load TeamSpec → validate eligibility → spawn member sessions
   → init mailbox + tasklist + worktrees → optional tmux layout
 2. Lead delegates via team_send_message + team_task_create
 3. Members claim tasks (team_task_update status="claimed") → execute → report (team_send_message)
 4. team_shutdown_request → team_approve_shutdown / team_reject_shutdown
 5. team_delete → cleanup state, mailbox, tasklist, worktrees, panes
 ```
 ## KEY INVARIANTS
-1. **Deferred ack**: Messages are fire-and-forget; recipient acks via separate call.
+1. **Spawn-race-safe resolution:** every team spawn calls `registerTeamSession(sessionId, entry)` synchronously when sessionID is known; every hook resolving sessionID calls `lookupTeamSession` BEFORE `loadRuntimeState` to avoid the spawn-race window.
-2. **Locked tasks**: Task claiming uses atomic file locks; concurrent claims resolve safely.
+2. **Deferred ack:** messages are fire-and-forget; recipient acks via separate call.
-3. **Atomic writes**: All state changes write to temp file then rename.
+3. **Locked tasks:** task claiming uses atomic file locks; concurrent claims resolve safely.
-4. **Eligible agents only**: sisyphus, atlas, sisyphus-junior, hephaestus allowed. Read-only agents rejected at parse.
+4. **Atomic writes:** state changes write to temp file then rename.
-5. **No nested teams**: Members cannot call `team_create`.
+5. **Eligible agents only:** rejection at parse, never at runtime.
-6. **Spawn-race-safe session resolution**: Every team session spawn MUST call `registerTeamSession(sessionId, entry)` synchronously when the sessionID becomes known; every hook that resolves a sessionID to a team/member MUST call `lookupTeamSession` before falling back to `loadRuntimeState` to avoid the spawn-race window.
+6. **No nested teams:** members CANNOT call `team_create`.
 ## INTEGRATION POINTS
 | Where | What |
 |-------|------|
 | [`src/index.ts`](file:///Users/yeongyu/local-workspaces/omo/src/index.ts) (entry) | `checkTeamModeDependencies()` + `ensureBaseDirs()` if `team_mode.enabled` |
 | [`src/plugin/tool-registry.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) | `teamModeToolsRecord` gate registers 12 tools |
 | `src/hooks/team-mode-status-injector/` | Injects `<team_mode_status>` block into messages |
 | `src/hooks/team-mailbox-injector/` | Pulls pending mailbox messages into agent context |
 | `src/hooks/team-session-events/` | React to member session lifecycle |
 | `src/hooks/team-tool-gating/` | Restrict `team_*` tools by member role |
 | [`src/cli/doctor/checks/team-mode.ts`](file:///Users/yeongyu/local-workspaces/omo/src/cli/doctor/checks/team-mode.ts) | Doctor check for team-mode prerequisites |
 | [`src/features/builtin-skills/skills/team-mode.ts`](file:///Users/yeongyu/local-workspaces/omo/src/features/builtin-skills/skills/team-mode.ts) | Built-in skill that documents the tools — only loaded when enabled |
 ## WHERE TO LOOK
 | Task | Location |
 |------|----------|
-| Add new team tool | `tools/` + register in `index.ts` |
+| Add new team tool | `tools/` + register in [`src/plugin/tool-registry.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) `teamModeToolsRecord` |
-| Modify member eligibility | `types.ts` AGENT_ELIGIBILITY_REGISTRY |
+| Modify member eligibility | `types.ts` `AGENT_ELIGIBILITY_REGISTRY` |
 | Change storage format | `types.ts` Zod schemas |
-| Add worktree features | `team-worktree/manager.ts` |
+| Add worktree behavior | `team-worktree/manager.ts` |
 | Modify tmux layout | `team-layout-tmux/layout.ts` |
 | Task lifecycle changes | `team-tasklist/` |
 | Mailbox protocol changes | `team-mailbox/` |
 | Recover orphaned runs | `team-state-store/resume.ts` |
 ## ANTI-PATTERNS
 - Never bypass `team-session-registry` — direct `loadRuntimeState` lookups will hit the spawn-race window.
 - Never write team state files without the atomic lock from `team-state-store/locks.ts`.
 - Never substitute `task` (delegate-task) for `team_*` tools when the user explicitly asks for team-mode work — they are not equivalent.
 - Never allow members to call `team_create` (nested teams are forbidden by `team-tool-gating` hook).
@@ -1,6 +1,6 @@
 # src/features/tmux-subagent/ — Tmux Pane Management
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,176 +1,139 @@
-# src/hooks/ — 52 Lifecycle Hooks
+# src/hooks/ — ~50 Lifecycle Hooks Across 57 Dirs
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-52 hooks across dedicated modules and standalone files. Three-tier composition: Core(43) + Continuation(7) + Skill(2). All hooks follow `createXXXHook(deps) → HookFunction` factory pattern.
+50 hooks (7 of the 57 dirs are `zauc-mocks-*` test scaffolds + 1 `shared/`). 5-tier composition wired in `src/plugin/hooks/`. All hooks follow `createXXXHook(deps) → HookFunction` factory pattern.
-## HOOK TIERS
+## TIER COMPOSITION
 | Tier | Composer | Count | When |
 |------|----------|-------|------|
 | **Session** | `create-session-hooks.ts` | 24 | OpenCode session lifecycle (created/idle/error/status) + chat.params + chat.message |
 | **Tool Guard** | `create-tool-guard-hooks.ts` | 14 | Pre/post tool execution |
 | **Transform** | `create-transform-hooks.ts` | 5 | `experimental.chat.messages.transform` |
 | **Continuation** | `create-continuation-hooks.ts` | 7 | Boulder/atlas/compaction/notification |
 | **Skill** | `create-skill-hooks.ts` | 2 | Skill awareness (categorySkillReminder, autoSlashCommand) |
 | **Team-mode** | conditional in registries | 4 | When `team_mode.enabled`: team-mailbox-injector, team-mode-status-injector, team-session-events, team-tool-gating |
 ### Tier 1: Session Hooks (24)
 | Hook | Event | Purpose |
 |------|-------|---------|
 | `contextWindowMonitor` | session.idle | Track context usage |
 | `preemptiveCompaction` | session.idle | Trigger compaction before limit |
 | `sessionRecovery` | session.error | Recover from structural errors (tool_result_missing, thinking_block_order) |
 | `sessionNotification` | session.idle | OS notifications on completion |
 | `thinkMode` | chat.params | Model variant switching for extended thinking |
 | `anthropicContextWindowLimitRecovery` | session.error | Multi-strategy context recovery (truncation, compaction, dedup) |
 | `autoUpdateChecker` | session.created | Check npm for plugin updates |
 | `agentUsageReminder` | chat.message | Remind about available agents |
 | `nonInteractiveEnv` | chat.message | Adjust behavior for `run` command |
 | `interactiveBashSession` | tool.execute | Tmux session lifecycle for interactive_bash tool |
 | `ralphLoop` | event | Self-referential dev loop (boulder continuation) |
 | `editErrorRecovery` | tool.execute.after | Retry failed file edits |
 | `delegateTaskRetry` | tool.execute.after | Retry failed task delegations |
 | `startWork` | chat.message | `/start-work` command handler |
 | `prometheusMdOnly` | tool.execute.before | Enforce .md-only writes for Prometheus |
 | `sisyphusJuniorNotepad` | chat.message | Notepad injection for subagents |
 | `questionLabelTruncator` | tool.execute.before | Truncate long Question tool labels |
 | `taskResumeInfo` | chat.message | Inject task context on resume |
 | `anthropicEffort` | chat.params | Adjust reasoning effort level |
 | `modelFallback` | chat.params | Provider-level proactive model fallback |
 | `noSisyphusGpt` | chat.message | Block Sisyphus from non-GPT providers (with warning toast) |
 | `noHephaestusNonGpt` | chat.message | Block Hephaestus from non-GPT models |
 | `runtimeFallback` | event | Reactive auto-switch on API provider errors |
 | `legacyPluginToast` | chat.message | Show toast when legacy plugin name detected |
 ### Tier 2: Tool Guard Hooks (14)
 | Hook | Event | Purpose |
 |------|-------|---------|
 | `commentChecker` | tool.execute.after | Block AI-slop comment patterns (binary: `@code-yeongyu/comment-checker`) |
 | `toolOutputTruncator` | tool.execute.after | Truncate oversized tool output |
 | `directoryAgentsInjector` | tool.execute.before | Inject dir-local AGENTS.md into context |
 | `directoryReadmeInjector` | tool.execute.before | Inject dir-local README.md into context |
 | `emptyTaskResponseDetector` | tool.execute.after | Detect empty task results |
 | `rulesInjector` | tool.execute.before | Conditional rules injection (AGENTS.md, .rules) |
 | `tasksTodowriteDisabler` | tool.execute.before | Disable TodoWrite when Sisyphus task system active |
 | `writeExistingFileGuard` | tool.execute.before | Require Read before Write/Edit on existing files |
 | `bashFileReadGuard` | tool.execute.before | Guard bash commands that read files (cat/head/tail) |
 | `readImageResizer` | tool.execute.after | Resize large images for context efficiency |
 | `todoDescriptionOverride` | tool.execute.before | Override todo item descriptions |
 | `webfetchRedirectGuard` | tool.execute.before | Guard webfetch redirect behavior |
 | `hashlineReadEnhancer` | tool.execute.after | Tag every Read output with `LINE#ID` content hashes |
 | `jsonErrorRecovery` | tool.execute.after | Detect JSON parse errors, inject correction reminder |
 ### Tier 3: Transform Hooks (5)
 | Hook | Event | Purpose |
 |------|-------|---------|
 | `claudeCodeHooks` | messages.transform | Claude Code settings.json compatibility |
 | `keywordDetector` | messages.transform | Detect ultrawork/search/analyze/team modes; inject mode-specific prompt |
 | `contextInjectorMessagesTransform` | messages.transform | Inject AGENTS.md/README.md into context |
 | `thinkingBlockValidator` | messages.transform | Validate thinking block structure |
 | `toolPairValidator` | messages.transform | Validate tool call/result pairing |
 ### Tier 4: Continuation Hooks (7)
 | Hook | Event | Purpose |
 |------|-------|---------|
 | `stopContinuationGuard` | chat.message | `/stop-continuation` command handler |
 | `compactionContextInjector` | session.compacted | Re-inject context after compaction |
 | `compactionTodoPreserver` | session.compacted | Preserve todos through compaction |
 | `todoContinuationEnforcer` | session.idle | **Boulder** — force continuation on incomplete todos |
 | `unstableAgentBabysitter` | session.idle | Monitor unstable agent behavior |
 | `backgroundNotificationHook` | event | Background task completion notifications |
 | `atlasHook` | event | Master orchestrator for boulder/background sessions |
 ### Tier 5: Skill Hooks (2)
 | Hook | Event | Purpose |
 |------|-------|---------|
 | `categorySkillReminder` | chat.message | Hint to load skills before invoking categories |
 | `autoSlashCommand` | chat.message | Auto-execute matching `/command` from user message |
 ### Team-mode Hooks (4, conditional)
 Activated only when `team_mode.enabled: true`:
 | Hook | Tier | Purpose |
 |------|------|---------|
 | `team-mode-status-injector` | Transform | Inject `<team_mode_status>` block into messages |
 | `team-mailbox-injector` | Transform | Pull pending team mailbox messages into agent context |
 | `team-session-events` | Continuation | React to member session lifecycle (created/idle/deleted) |
 | `team-tool-gating` | Tool Guard | Restrict `team_*` tools based on member role + permissions |
 ### Tier 1: Session Hooks (24) — `create-session-hooks.ts`
 ## STRUCTURE
 ```
 hooks/
-├── agent-usage-reminder/         # Reminds about available agents
+├── shared/                                  # Cross-hook helpers (timing, prompt builders, etc.)
-├── atlas/                      # Main orchestration (757 lines)
+├── (50 hook directories — see tier tables above)
-├── anthropic-context-window-limit-recovery/ # Auto-summarize
+├── zauc-mocks-bg, zauc-mocks-cache, …       # Test mocks (NOT hooks; named for sort-order isolation)
-├── anthropic-effort/            # Reasoning effort level adjustment
+└── (each hook dir)/
-├── auto-slash-command/         # Detects /command patterns
+    ├── index.ts        # createXXXHook factory + barrel
-├── auto-update-checker/        # Plugin update check
+    ├── *.ts            # implementation
-├── background-notification/    # OS notification
+    └── *.test.ts       # bun:test
 ├── category-skill-reminder/    # Reminds of category skills
 ├── claude-code-hooks/          # settings.json compat layer
 ├── comment-checker/            # Prevents AI slop
 ├── compaction-context-injector/ # Injects context on compaction
 ├── compaction-todo-preserver/  # Preserves todos through compaction
 ├── delegate-task-retry/        # Retries failed delegations
 ├── directory-agents-injector/  # Auto-injects AGENTS.md
 ├── directory-readme-injector/  # Auto-injects README.md
 ├── edit-error-recovery/        # Recovers from failures
 ├── hashline-edit-diff-enhancer/ # Enhanced diff output for hashline edits
 ├── hashline-read-enhancer/     # Adds LINE#ID hashes to Read output
 ├── interactive-bash-session/   # Tmux session management
 ├── json-error-recovery/        # JSON parse error correction
 ├── keyword-detector/           # ultrawork/search/analyze modes
 ├── legacy-plugin-toast/        # Legacy plugin name migration toast
 ├── model-fallback/             # Provider-level model fallback
 ├── no-hephaestus-non-gpt/      # Block Hephaestus from non-GPT
 ├── no-sisyphus-gpt/            # Block Sisyphus from GPT
 ├── non-interactive-env/        # Non-TTY environment handling
 ├── prometheus-md-only/         # Planner read-only mode
 ├── question-label-truncator/   # Auto-truncates question labels
 ├── ralph-loop/                 # Self-referential dev loop
 ├── read-image-resizer/         # Resize images for context efficiency
 ├── rules-injector/             # Conditional rules
 ├── runtime-fallback/           # Auto-switch models on API errors
 ├── session-recovery/           # Auto-recovers from crashes
 ├── sisyphus-junior-notepad/    # Sisyphus Junior notepad
 ├── start-work/                 # Sisyphus work session starter
 ├── stop-continuation-guard/    # Guards stop continuation
 ├── task-reminder/              # Task system usage reminders
 ├── task-resume-info/           # Resume info for cancelled tasks
 ├── tasks-todowrite-disabler/   # Disable TodoWrite when task system active
 ├── think-mode/                 # Dynamic thinking budget
 ├── thinking-block-validator/   # Ensures valid <thinking>
 ├── todo-continuation-enforcer/ # Force TODO completion
 ├── todo-description-override/  # Override todo descriptions
 ├── tool-pair-validator/        # Validate tool pair usage
 ├── unstable-agent-babysitter/  # Monitor unstable agent behavior
 ├── webfetch-redirect-guard/    # Guard webfetch redirect behavior
 ├── write-existing-file-guard/  # Require Read before Write
 └── index.ts                    # Hook aggregation + registration
 ```
-| Hook | Event | Purpose |
+## ADDING A NEW HOOK
 |------|-------|---------|
 | contextWindowMonitor | session.idle | Track context window usage |
 | preemptiveCompaction | session.idle | Trigger compaction before limit |
 | sessionRecovery | session.error | Auto-retry on recoverable errors |
 | sessionNotification | session.idle | OS notifications on completion |
 | thinkMode | chat.params | Model variant switching (extended thinking) |
 | anthropicContextWindowLimitRecovery | session.error | Multi-strategy context recovery (truncation, compaction) |
 | autoUpdateChecker | session.created | Check npm for plugin updates |
 | agentUsageReminder | chat.message | Remind about available agents |
 | nonInteractiveEnv | chat.message | Adjust behavior for `run` command |
 | interactiveBashSession | tool.execute | Tmux session for interactive tools |
 | ralphLoop | event | Self-referential dev loop (boulder continuation) |
 | editErrorRecovery | tool.execute.after | Retry failed file edits |
 | delegateTaskRetry | tool.execute.after | Retry failed task delegations |
 | startWork | chat.message | `/start-work` command handler |
 | prometheusMdOnly | tool.execute.before | Enforce .md-only writes for Prometheus |
 | sisyphusJuniorNotepad | chat.message | Notepad injection for subagents |
 | questionLabelTruncator | tool.execute.before | Truncate long question labels |
 | taskResumeInfo | chat.message | Inject task context on resume |
 | anthropicEffort | chat.params | Adjust reasoning effort level |
 | modelFallback | chat.params | Provider-level model fallback on errors |
 | noSisyphusGpt | chat.message | Block Sisyphus from using GPT models (toast warning) |
 | noHephaestusNonGpt | chat.message | Block Hephaestus from using non-GPT models |
 | runtimeFallback | event | Auto-switch models on API provider errors |
 | legacyPluginToast | chat.message | Show toast when legacy plugin name detected |
-### Tier 2: Tool Guard Hooks (14) — `create-tool-guard-hooks.ts`
+1. `mkdir src/hooks/{name}` + `index.ts` exporting `createXXXHook(deps)`
 2. Pick the right tier:
   - Session lifecycle? → `create-session-hooks.ts`
   - Pre/post tool? → `create-tool-guard-hooks.ts`
   - Message transform? → `create-transform-hooks.ts`
   - Continuation/idle? → `create-continuation-hooks.ts`
   - Skill awareness? → `create-skill-hooks.ts`
   - Team-mode-only? → register inside the team-mode conditional block
 3. Add hook name to [`config/schema/hooks.ts`](file:///Users/yeongyu/local-workspaces/omo/src/config/schema/hooks.ts) `HookNameSchema`
 4. Cover with co-located `*.test.ts` (given/when/then style)
-| Hook | Event | Purpose |
+## NOTES
 |------|-------|---------|
 | commentChecker | tool.execute.after | Block AI-generated comment patterns |
 | toolOutputTruncator | tool.execute.after | Truncate oversized tool output |
 | directoryAgentsInjector | tool.execute.before | Inject dir AGENTS.md into context |
 | directoryReadmeInjector | tool.execute.before | Inject dir README.md into context |
 | emptyTaskResponseDetector | tool.execute.after | Detect empty task responses |
 | rulesInjector | tool.execute.before | Conditional rules injection (AGENTS.md, config) |
 | tasksTodowriteDisabler | tool.execute.before | Disable TodoWrite when task system active |
 | writeExistingFileGuard | tool.execute.before | Require Read before Write on existing files |
 | bashFileReadGuard | tool.execute.before | Guard bash commands that read files |
 | readImageResizer | tool.execute.after | Resize large images for context efficiency |
 | todoDescriptionOverride | tool.execute.before | Override todo item descriptions |
 | webfetchRedirectGuard | tool.execute.before | Guard webfetch redirect behavior |
 | hashlineReadEnhancer | tool.execute.after | Enhance Read output with line hashes |
 | jsonErrorRecovery | tool.execute.after | Detect JSON parse errors, inject correction reminder |
-### Tier 3: Transform Hooks (5) — `create-transform-hooks.ts`
+- **Tier order matters within a phase:** within Session tier the registration order in `create-session-hooks.ts` determines invocation order — earlier hooks see un-mutated input, later hooks see accumulated output.
-
+- **Mock files** (`zauc-mocks-*`, `zauc-sync-mocks`) are NOT hooks. They are placed inside `src/hooks/` purely so `bun:test` discovers them in the right order — auto-isolated by `script/run-ci-tests.ts` because they use `mock.module()`.
-| Hook | Event | Purpose |
+- **`atlasHook` vs `todoContinuationEnforcer`:** atlas handles boulder/ralph/subagent sessions, todoContinuationEnforcer handles the main Sisyphus session. Both fire on `session.idle` but check session type first.
-|------|-------|---------|
+- **`runtime-fallback` vs `model-fallback`:** runtime-fallback is reactive (after error); model-fallback is proactive (chat.params). They operate independently.
 | claudeCodeHooks | messages.transform | Claude Code settings.json compatibility |
 | keywordDetector | messages.transform | Detect ultrawork/search/analyze modes |
 | contextInjectorMessagesTransform | messages.transform | Inject AGENTS.md/README.md into context |
 | thinkingBlockValidator | messages.transform | Validate thinking block structure |
 | toolPairValidator | messages.transform | Validate tool call/result pairs |
 ### Tier 4: Continuation Hooks (7) — `create-continuation-hooks.ts`
 | Hook | Event | Purpose |
 |------|-------|---------|
 | stopContinuationGuard | chat.message | `/stop-continuation` command handler |
 | compactionContextInjector | session.compacted | Re-inject context after compaction |
 | compactionTodoPreserver | session.compacted | Preserve todos through compaction |
 | todoContinuationEnforcer | session.idle | **Boulder**: force continuation on incomplete todos |
 | unstableAgentBabysitter | session.idle | Monitor unstable agent behavior |
 | backgroundNotificationHook | event | Background task completion notifications |
 | atlasHook | event | Master orchestrator for boulder/background sessions |
 ### Tier 5: Skill Hooks (2) — `create-skill-hooks.ts`
 | Hook | Event | Purpose |
 |------|-------|---------|
 | categorySkillReminder | chat.message | Remind about category+skill delegation |
 | autoSlashCommand | chat.message | Auto-detect `/command` in user input |
 ## KEY HOOKS (COMPLEX)
 ### anthropic-context-window-limit-recovery (31 files, ~2232 LOC)
 Multi-strategy recovery when hitting context limits. Strategies: truncation, compaction, summarization.
 ### atlas (17 files, ~1976 LOC)
 Master orchestrator for boulder sessions. Decision gates: session type → abort check → failure count → background tasks → agent match → plan completeness → cooldown (5s). Injects continuation prompts on session.idle.
 ### ralph-loop (14 files, ~1687 LOC)
 Self-referential dev loop via `/ralph-loop` command. State persisted in `.sisyphus/ralph-loop.local.md`. Detects `<promise>DONE</promise>` in AI output. Max 100 iterations default.
 ### todo-continuation-enforcer (13 files, ~2061 LOC)
 "Boulder" mechanism. Forces agent to continue when todos remain incomplete. 2s countdown toast → continuation injection. Exponential backoff: 30s base, ×2 per failure, max 5 consecutive failures then 5min pause.
 ### keyword-detector (~1665 LOC)
 Detects modes from user input: ultrawork, search, analyze, prove-yourself. Injects mode-specific system prompts.
 ### rules-injector (19 files, ~1604 LOC)
 Conditional rules injection from AGENTS.md, config, skill rules. Evaluates conditions to determine which rules apply.
 ## STANDALONE HOOKS (in src/hooks/ root)
 | File | Purpose |
 |------|---------|
 | context-window-monitor.ts | Track context window percentage |
 | preemptive-compaction.ts | Trigger compaction before hard limit |
 | tool-output-truncator.ts | Truncate tool output by token count |
 | session-notification.ts + 4 helpers | OS notification on session completion |
 | empty-task-response-detector.ts | Detect empty/failed task responses |
 | session-todo-status.ts | Todo completion status tracking |
 ## HOW TO ADD A HOOK
 1. Create `src/hooks/{name}/index.ts` with `createXXXHook(deps)` factory
 2. Register in appropriate tier file (`src/plugin/hooks/create-{tier}-hooks.ts`)
 3. Add hook name to `src/config/schema/hooks.ts` HookNameSchema
 4. Hook receives `(event, ctx)` — return value depends on event type
@@ -1,6 +1,6 @@
 # src/hooks/anthropic-context-window-limit-recovery/ — Multi-Strategy Context Recovery
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/atlas/ — Master Boulder Orchestrator
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/claude-code-hooks/ — Claude Code Compatibility
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/comment-checker/ — AI Slop Comment Blocker
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/keyword-detector/ — Mode Keyword Injection
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/ralph-loop/ — Self-Referential Dev Loop
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/rules-injector/ — Conditional Rules Injection
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/runtime-fallback/ — Reactive Provider Error Recovery
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/session-recovery/ — Auto Session Error Recovery
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/hooks/todo-continuation-enforcer/ — Boulder Continuation Mechanism
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/mcp/ — 3 Built-in Remote MCPs
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/openclaw/ — Bidirectional External Integration
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/plugin-handlers/ — 6-Phase Config Loading Pipeline
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## CRITICAL: AGENT ORDERING
@@ -1,36 +1,38 @@
 # src/plugin/ — 10 OpenCode Hook Handlers + Hook Composition
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-Core glue layer. 20 source files assembling the 10 OpenCode hook handlers and composing 50 hooks into the PluginInterface. Every handler file corresponds to one OpenCode hook type.
+Core glue layer. Files assemble the 10 OpenCode hook handlers and compose the 5-tier hook system into the `PluginInterface`. Each handler file maps to one OpenCode hook type.
 ## HANDLER FILES
 | File | OpenCode Hook | Purpose |
 |------|---------------|---------|
-| `config.ts` | `config` | 6-phase config loading pipeline |
+| `config.ts` | `config` | 6-phase config loading pipeline (delegates to `plugin-handlers/`) |
-| `tool-registry.ts` | `tool` | 26 tools assembled from factories |
+| `tool-registry.ts` | `tool` | 20–39 tools assembled with config gates (team-mode +12, task system +4, hashline +1, interactive_bash +1, look_at +1) |
-| `chat-message.ts` | `chat.message` | First-message variant, session setup, keyword detection |
+| `chat-message.ts` | `chat.message` | First-message variant resolution, session setup, keyword detection trigger |
-| `chat-params.ts` | `chat.params` | Anthropic effort level, think mode |
+| `chat-params.ts` | `chat.params` | Anthropic effort, think mode, runtime fallback model override |
-| `chat-headers.ts` | `chat.headers` | Copilot x-initiator header injection |
+| `chat-headers.ts` | `chat.headers` | Copilot `x-initiator` header injection |
-| `event.ts` | `event` | Session lifecycle (created, deleted, idle, error) |
+| `event.ts` | `event` | Session lifecycle (created/deleted/idle/error/status), openclaw dispatch, runtime fallback |
-| `tool-execute-before.ts` | `tool.execute.before` | Pre-tool guards (file guard, label truncator, rules injector) |
+| `tool-execute-before.ts` | `tool.execute.before` | Pre-tool guards |
-| `tool-execute-after.ts` | `tool.execute.after` | Post-tool hooks (output truncation, comment checker, metadata) |
+| `tool-execute-after.ts` | `tool.execute.after` | Post-tool hooks (truncation, comment-checker, hashline read tagging, json-error-recovery) |
-| `messages-transform.ts` | `experimental.chat.messages.transform` | Context injection, thinking block validation |
+| `messages-transform.ts` | `experimental.chat.messages.transform` | Context injection, thinking-block validation, tool-pair validation, keyword detection |
-| `session-compacting.ts` | `experimental.session.compacting` | Context + todo preservation during compaction |
+| `session-compacting.ts` | `experimental.session.compacting` | Context + todo preservation across compaction |
-| `skill-context.ts` | — | Skill/browser/category context for tool creation |
+| `skill-context.ts` | (helper) | Skill/browser/category context shared with tool creation |
 ## HOOK COMPOSITION (hooks/ subdir)
 | File | Tier | Count |
 |------|------|-------|
-| `create-session-hooks.ts` | Session | 23 |
+| `create-session-hooks.ts` | Session | 24 |
 | `create-tool-guard-hooks.ts` | Tool Guard | 14 |
 | `create-transform-hooks.ts` | Transform | 5 |
 | `create-skill-hooks.ts` | Skill | 2 |
-| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 42 |
+| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 43 |
 `createContinuationHooks()` (7) lives in `src/create-hooks.ts` next to `createCoreHooks()` and `createSkillHooks()`.
 ## SUPPORT FILES
@@ -39,16 +41,45 @@ Core glue layer. 20 source files assembling the 10 OpenCode hook handlers and co
 | `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 |
+| `recent-synthetic-idles.ts` | Dedup rapid synthetic idle events |
 | `unstable-agent-babysitter.ts` | Track unstable agent behavior across sessions |
 | `types.ts` | `PluginContext`, `PluginInterface`, `ToolsRecord`, `TmuxConfig` |
 | `ultrawork-model-override.ts` | Ultrawork mode model override logic |
 | `ultrawork-db-model-override.ts` | DB-level model override for ultrawork |
 | `config-handler.ts` | Runtime config loading and caching |
 | `normalize-tool-arg-schemas.ts` | Coerce tool arg schemas into a normalized shape |
 ## TOOL REGISTRATION GATES
 ```typescript
 // src/plugin/tool-registry.ts
 const taskToolsRecord = isTaskSystemEnabled(config) ? { task_create, task_get, task_list, task_update } : {}
 const hashlineToolsRecord = config.hashline_edit ? { edit: createHashlineEditTool(ctx) } : {}
 const teamModeToolsRecord = config.team_mode?.enabled ? { team_create, team_delete, team_shutdown_request, team_approve_shutdown, team_reject_shutdown, team_send_message, team_task_create, team_task_list, team_task_update, team_task_get, team_status, team_list } : {}
 const lookAt = isMultimodalLookerEnabled ? { look_at: createLookAt(ctx) } : {}
 const interactiveBashTool = interactiveBashEnabled ? { interactive_bash } : {}
 const allTools = {
  ...builtinTools,                    // 6 LSP
  ...createGrepTools(ctx),
  ...createGlobTools(ctx),
  ...createAstGrepTools(ctx),
  ...createSessionManagerTools(ctx),
  ...backgroundTools,                 // 2 background_*
  call_omo_agent, task,
  ...lookAt,
  skill_mcp, skill,
  ...interactiveBashTool,
  ...teamModeToolsRecord,             // +12 conditional
  ...taskToolsRecord,                 // +4 conditional
  ...hashlineToolsRecord,             // +1 conditional
 }
 ```
 ## KEY PATTERNS
- Each handler exports a function receiving `(hookRecord, ctx, pluginConfig, managers)` → returns OpenCode hook function
+- Each handler exports a function receiving `(hookRecord, ctx, pluginConfig, managers)` → returns the OpenCode hook function.
- Handlers iterate over hook records, calling each hook with `(input, output)` in sequence
+- Handlers iterate over hook records, calling each hook with `(input, output)` in registration order.
- `safeHook()` wrapper in composition files catches errors per-hook without breaking the chain
+- `safeHook()` wrapper isolates hook errors so one broken hook does not crash the chain.
- Tool registry uses `filterDisabledTools()` before returning
+- `filterDisabledTools(allTools, disabled_tools)` prunes tools listed in `disabled_tools` config.
 - `experimental.max_tools` cap trims tool count when set (selects the highest-priority tools).
@@ -1,6 +1,6 @@
 # src/shared/ — 100+ Utility Files
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,108 +1,97 @@
-# src/tools/ - 26 Tools Across 16 Directories
+# src/tools/ — 20–39 Tools Across 16 Directories
-**Generated:** 2026-04-18
+**Generated:** 2026-05-08
 ## OVERVIEW
-26 tools registered via `createToolRegistry()`. Two patterns: factory functions (`createXXXTool`) for 19 tools, direct `ToolDefinition` for 7 (LSP + interactive_bash).
+Tools registered via [`createToolRegistry()`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) in `src/plugin/`. Two patterns: factory functions (`createXXXTool`) for most tools, direct `ToolDefinition` exports for the 6 LSP tools and `interactive_bash`. The total exposed count varies between 20 (minimum) and 39 (with all flags on) based on config gates listed below.
 ## TOOL CATALOG
-### Task Management (4)
+### Always On (20)
-| Tool | Factory | Parameters |
+| Group | Tools |
-|------|---------|------------|
+|-------|-------|
-| `task_create` | `createTaskCreateTool` | subject, description, blockedBy, blocks, metadata, parentID |
+| **LSP** (6) | `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_diagnostics`, `lsp_prepare_rename`, `lsp_rename` |
-| `task_list` | `createTaskList` | (none) |
+| **Search** (4) | `grep`, `glob`, `ast_grep_search`, `ast_grep_replace` |
-| `task_get` | `createTaskGetTool` | id |
+| **Sessions** (4) | `session_list`, `session_read`, `session_search`, `session_info` |
-| `task_update` | `createTaskUpdateTool` | id, subject, description, status, addBlocks, addBlockedBy, owner, metadata |
+| **Background tasks** (2) | `background_output`, `background_cancel` |
 | **Delegation** (2) | `task` (delegate, full skill+category support), `call_omo_agent` (named agent only: explore, librarian) |
 | **Skills/MCP** (2) | `skill` (load skill or invoke command), `skill_mcp` (call skill-embedded MCP tool/resource/prompt) |
-### Delegation (1)
+### Conditional (up to +19)
-| Tool | Factory | Parameters |
+| Tool(s) | Gate | Source |
-|------|---------|------------|
+|---------|------|--------|
-| `task` | `createDelegateTask` | description, prompt, category, subagent_type, run_in_background, session_id, load_skills, command |
+| `look_at` | not in `disabled_agents` for `multimodal-looker` | `look-at/` |
 | `interactive_bash` | `isInteractiveBashEnabled(config)` (tmux config) | `interactive-bash/` |
 | `task_create`, `task_get`, `task_list`, `task_update` | `experimental.task_system` | `task/` |
 | `edit` (hashline-edit) | `hashline_edit: true` | `hashline-edit/` |
 | 12 `team_*` tools | `team_mode.enabled: true` | `../features/team-mode/tools/` |
-**8 Built-in Categories**: visual-engineering, ultrabrain, deep, artistry, quick, unspecified-low, unspecified-high, writing
+### 12 team_* Tools (when team_mode enabled)
-### Agent Invocation (1)
+| Tool | Purpose |
 |------|---------|
 | `team_create` | Spawn team + member sessions from a TeamSpec (named or inline) |
 | `team_delete` | Tear down — removes mailbox, tasklist, worktrees, optional tmux layout |
 | `team_shutdown_request` | Member or lead requests its own shutdown |
 | `team_approve_shutdown` | Lead acks a pending shutdown |
 | `team_reject_shutdown` | Lead rejects a shutdown with reason |
 | `team_send_message` | Async message to specific member or `*` broadcast |
 | `team_task_create` | Create task on shared list |
 | `team_task_list` | List tasks (filter by status, owner) |
 | `team_task_update` | Claim/complete/delete (atomic file lock) |
 | `team_task_get` | Fetch single task |
 | `team_status` | Full team run status (members, tasks, mailbox) |
 | `team_list` | List declared + active teams |
-| Tool | Factory | Parameters |
+## DELEGATION CATEGORIES (built-in 8)
 |------|---------|------------|
 | `call_omo_agent` | `createCallOmoAgent` | description, prompt, subagent_type, run_in_background, session_id |
-### Background Tasks (2)
+`task` (delegate) selects model by category; categories defined in `delegate-task/constants.ts`:
-| Tool | Factory | Parameters |
+| Category | Default Model | Domain |
-|------|---------|------------|
+|----------|---------------|--------|
-| `background_output` | `createBackgroundOutput` | task_id, block, timeout, full_session, include_thinking, message_limit, since_message_id, thinking_max_chars |
+| `visual-engineering` | gemini-3.1-pro high | Frontend, UI/UX |
-| `background_cancel` | `createBackgroundCancel` | taskId, all |
+| `ultrabrain` | gpt-5.5 xhigh | Hard logic / heavy reasoning |
 | `deep` | gpt-5.5 medium | Autonomous multi-step problem-solving |
 | `artistry` | gemini-3.1-pro high | Creative / unconventional approaches |
 | `quick` | gpt-5.4-mini-fast | Trivial single-file changes |
 | `unspecified-low` | claude-sonnet-4-6 | Moderate effort fallback |
 | `unspecified-high` | claude-opus-4-7 max | High effort fallback |
 | `writing` | gemini-3-flash | Documentation, prose |
-### LSP Refactoring (6) - Direct ToolDefinition
+User-defined categories declared in `categories: { ... }` config override and add to this set.
-| Tool | Parameters |
+## TOOL DIR LAYOUT
 |------|------------|
 | `lsp_goto_definition` | filePath, line, character |
 | `lsp_find_references` | filePath, line, character, includeDeclaration |
 | `lsp_symbols` | filePath, scope (document/workspace), query, limit |
 | `lsp_diagnostics` | filePath, severity |
 | `lsp_prepare_rename` | filePath, line, character |
 | `lsp_rename` | filePath, line, character, newName |
-### Code Search (4)
+```
 tools/
 ├── ast-grep/             # ast_grep_search, ast_grep_replace
 ├── background-task/      # background_output, background_cancel (LLM interface; engine in features/background-agent)
 ├── call-omo-agent/       # call_omo_agent (explore + librarian only)
 ├── delegate-task/        # task — full delegation with categories + skills
 ├── glob/                 # glob (60s timeout, 100 file limit)
 ├── grep/                 # grep (60s timeout, 10MB limit)
 ├── hashline-edit/        # edit — hash-anchored line edits with LINE#ID validation
 ├── interactive-bash/     # interactive_bash — tmux session control
 ├── look-at/              # look_at — image/PDF analysis
 ├── lsp/                  # 6 LSP tools (direct ToolDefinition)
 ├── session-manager/      # 4 session_* tools
 ├── skill/                # skill — load skill or run command
 ├── skill-mcp/            # skill_mcp — call skill-embedded MCP servers
 ├── slashcommand/         # discoverCommandsSync — feeds skill tool with /-command list
 ├── task/                 # 4 task_* tools (Sisyphus task system)
 └── index.ts              # barrel exports
 ```
-| Tool | Factory | Parameters |
+## ADDING A NEW TOOL
 |------|---------|------------|
 | `ast_grep_search` | `createAstGrepTools` | pattern, lang, paths, globs, context |
 | `ast_grep_replace` | `createAstGrepTools` | pattern, rewrite, lang, paths, globs, dryRun |
 | `grep` | `createGrepTools` | pattern, path, include (60s timeout, 10MB limit) |
 | `glob` | `createGlobTools` | pattern, path (60s timeout, 100 file limit) |
-### Session History (4)
+1. Create `src/tools/{name}/index.ts` with factory `createXXXTool`
-
+2. Add `types.ts` for parameter Zod schemas
-| Tool | Factory | Parameters |
+3. Add `tools.ts` (or single index.ts) for implementation
-|------|---------|------------|
+4. Export factory from `src/tools/index.ts`
-| `session_list` | `createSessionManagerTools` | (none) |
+5. Register in `src/plugin/tool-registry.ts`:
-| `session_read` | `createSessionManagerTools` | session_id, include_todos, limit |
+   - Always-on: spread into `allTools` directly
-| `session_search` | `createSessionManagerTools` | query, session_id, case_sensitive, limit |
+   - Conditional: build a `Record<string, ToolDefinition>` and gate-spread
-| `session_info` | `createSessionManagerTools` | session_id |
+6. If the tool needs disabling, ensure it appears in `filterDisabledTools` allow-list (its name will be matched against `disabled_tools`)
 ### Skill/Command (2)
 | Tool | Factory | Parameters |
 |------|---------|------------|
 | `skill` | `createSkillTool` | name, user_message |
 | `skill_mcp` | `createSkillMcpTool` | mcp_name, tool_name/resource_name/prompt_name, arguments, grep |
 ### System (2)
 | Tool | Factory | Parameters |
 |------|---------|------------|
 | `interactive_bash` | Direct | tmux_command |
 | `look_at` | `createLookAt` | file_path, image_data, goal |
 ### Editing (1) - Conditional
 | Tool | Factory | Parameters |
 |------|---------|------------|
 | `hashline_edit` | `createHashlineEditTool` | file, edits[] |
 ## DELEGATION CATEGORIES
 | Category | Model | Domain |
 |----------|-------|--------|
 | visual-engineering | gemini-3.1-pro high | Frontend, UI/UX |
 | ultrabrain | gpt-5.5 xhigh | Hard logic |
 | deep | gpt-5.5 medium | Autonomous problem-solving |
 | artistry | gemini-3.1-pro high | Creative approaches |
 | quick | gpt-5.4-mini | Trivial tasks |
 | unspecified-low | claude-sonnet-4-6 | Moderate effort |
 | unspecified-high | claude-opus-4-7 max | High effort |
 | writing | gemini-3-flash | Documentation |
 ## HOW TO ADD A TOOL
 1. Create `src/tools/{name}/index.ts` exporting factory
 2. Create `src/tools/{name}/types.ts` for parameter schemas
 3. Create `src/tools/{name}/tools.ts` for implementation
 4. Register in `src/plugin/tool-registry.ts`
@@ -1,6 +1,6 @@
 # src/tools/background-task/ — Background Task Tool Wrappers
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/tools/call-omo-agent/ — Direct Agent Invocation Tool
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/tools/delegate-task/ — Task Delegation Engine
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/tools/hashline-edit/ — Hash-Anchored File Edit Tool
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW
@@ -1,6 +1,6 @@
 # src/tools/lsp/ — LSP Tool Implementations
-**Generated:** 2026-04-11
+**Generated:** 2026-05-08
 ## OVERVIEW