diff --git a/AGENTS.md b/AGENTS.md index 40a72f6af..1189b15be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,320 +1,119 @@ -# PROJECT KNOWLEDGE BASE +# oh-my-opencode — OpenCode Plugin -**Generated:** 2026-02-16T14:58:00+09:00 -**Commit:** 28cd34c3 -**Branch:** fuck-v1.2 - ---- - -## CRITICAL: PULL REQUEST TARGET BRANCH (NEVER DELETE THIS SECTION) - -> **THIS SECTION MUST NEVER BE REMOVED OR MODIFIED** - -### Git Workflow - -``` -master (deployed/published) - ↑ - dev (integration branch) - ↑ -feature branches (your work) -``` - -### Rules (MANDATORY) - -| Rule | Description | -|------|-------------| -| **ALL PRs → `dev`** | Every pull request MUST target the `dev` branch | -| **NEVER PR → `master`** | PRs to `master` are **automatically rejected** by CI | -| **"Create a PR" = target `dev`** | When asked to create a new PR, it ALWAYS means targeting `dev` | -| **Merge commit ONLY** | Squash merge is **disabled** in this repo. Always use merge commit when merging PRs. | - -### Why This Matters - -- `master` = production/published npm package -- `dev` = integration branch where features are merged and tested -- Feature branches → `dev` → (after testing) → `master` -- Squash merge is disabled at the repository level — attempting it will fail - -**If you create a PR targeting `master`, it WILL be rejected. No exceptions.** - ---- - -## CRITICAL: OPENCODE SOURCE CODE REFERENCE (NEVER DELETE THIS SECTION) - -> **THIS SECTION MUST NEVER BE REMOVED OR MODIFIED** - -### This is an OpenCode Plugin - -Oh-My-OpenCode is a **plugin for OpenCode**. You will frequently need to examine OpenCode's source code to: -- Understand plugin APIs and hooks -- Debug integration issues -- Implement features that interact with OpenCode internals -- Answer questions about how OpenCode works - -### How to Access OpenCode Source Code - -**When you need to examine OpenCode source:** - -1. **Clone to system temp directory:** - ```bash - git clone https://github.com/sst/opencode /tmp/opencode-source - ``` - -2. **Explore the codebase** from there (do NOT clone into the project directory) - -3. **Clean up** when done (optional, temp dirs are ephemeral) - -### Librarian Agent: YOUR PRIMARY TOOL for Plugin Work - -**CRITICAL**: When working on plugin-related tasks or answering plugin questions: - -| Scenario | Action | -|----------|--------| -| Implementing new hooks | Fire `librarian` to search OpenCode hook implementations | -| Adding new tools | Fire `librarian` to find OpenCode tool patterns | -| Understanding SDK behavior | Fire `librarian` to examine OpenCode SDK source | -| Debugging plugin issues | Fire `librarian` to find relevant OpenCode internals | -| Answering "how does OpenCode do X?" | Fire `librarian` FIRST | - -**DO NOT guess or hallucinate about OpenCode internals.** Always verify by examining actual source code via `librarian` or direct clone. - ---- - -## CRITICAL: ENGLISH-ONLY POLICY (NEVER DELETE THIS SECTION) - -> **THIS SECTION MUST NEVER BE REMOVED OR MODIFIED** - -### All Project Communications MUST Be in English - -| Context | Language Requirement | -|---------|---------------------| -| **GitHub Issues** | English ONLY | -| **Pull Requests** | English ONLY (title, description, comments) | -| **Commit Messages** | English ONLY | -| **Code Comments** | English ONLY | -| **Documentation** | English ONLY | -| **AGENTS.md files** | English ONLY | - -**If you're not comfortable writing in English, use translation tools. Broken English is fine. Non-English is not acceptable.** - ---- +**Generated:** 2026-02-17 | **Commit:** 5a8e424c | **Branch:** dev ## OVERVIEW -OpenCode plugin (oh-my-opencode): multi-model agent orchestration with 11 specialized agents, 41 lifecycle hooks across 7 event types, 26 tools (LSP, AST-Grep, delegation, task management), full Claude Code compatibility layer, 4-scope skill loading, background agent concurrency, tmux integration, and 3-tier MCP system. "oh-my-zsh" for OpenCode. +OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 41 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1164 TypeScript files, 133k LOC. ## STRUCTURE ``` oh-my-opencode/ ├── src/ -│ ├── agents/ # 11 AI agents — see src/agents/AGENTS.md -│ ├── hooks/ # 41 lifecycle hooks — see src/hooks/AGENTS.md -│ ├── tools/ # 26 tools — see src/tools/AGENTS.md -│ ├── features/ # Background agents, skills, CC compat — see src/features/AGENTS.md -│ ├── shared/ # Cross-cutting utilities — see src/shared/AGENTS.md -│ ├── cli/ # CLI installer, doctor — see src/cli/AGENTS.md -│ ├── mcp/ # Built-in MCPs — see src/mcp/AGENTS.md -│ ├── config/ # Zod schema — see src/config/AGENTS.md -│ ├── plugin-handlers/ # Config loading pipeline — see src/plugin-handlers/AGENTS.md -│ ├── plugin/ # Plugin interface composition (21 files) -│ ├── index.ts # Main plugin entry (106 lines) -│ ├── create-hooks.ts # Hook creation coordination (62 lines) -│ ├── create-managers.ts # Manager initialization (80 lines) -│ ├── create-tools.ts # Tool registry composition (54 lines) -│ ├── plugin-interface.ts # Plugin interface assembly (66 lines) -│ ├── plugin-config.ts # Config loading orchestration (180 lines) -│ └── plugin-state.ts # Model cache state (12 lines) -├── script/ # build-schema.ts, build-binaries.ts, publish.ts, generate-changelog.ts -├── packages/ # 11 platform-specific binary packages -└── dist/ # Build output (ESM + .d.ts) +│ ├── index.ts # Plugin entry: loadConfig → createManagers → createTools → createHooks → createPluginInterface +│ ├── plugin-config.ts # JSONC multi-level config: project → user → defaults (Zod v4) +│ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior) +│ ├── hooks/ # 41 hooks across 37 directories + 6 standalone files +│ ├── tools/ # 26 tools across 14 directories +│ ├── features/ # 18 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.) +│ ├── shared/ # 101 utility files in 13 categories +│ ├── config/ # Zod v4 schema system (22 files) +│ ├── cli/ # CLI: install, run, doctor, mcp-oauth (Commander.js) +│ ├── mcp/ # 3 built-in remote MCPs (websearch, context7, grep_app) +│ ├── plugin/ # 7 OpenCode hook handlers + 41 hook composition +│ └── plugin-handlers/ # 6-phase config loading pipeline +├── packages/ # Monorepo: comment-checker, opencode-sdk +└── local-ignore/ # Dev-only test fixtures ``` ## INITIALIZATION FLOW ``` OhMyOpenCodePlugin(ctx) - 1. injectServerAuthIntoClient(ctx.client) - 2. startTmuxCheck() - 3. loadPluginConfig(ctx.directory, ctx) → OhMyOpenCodeConfig - 4. createFirstMessageVariantGate() - 5. createModelCacheState() - 6. createManagers(ctx, config, tmux, cache) → TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler - 7. createTools(ctx, config, managers) → filteredTools, mergedSkills, availableSkills, availableCategories - 8. createHooks(ctx, config, backgroundMgr) → 41 hooks (core + continuation + skill) - 9. createPluginInterface(...) → 7 OpenCode hook handlers - 10. Return plugin with experimental.session.compacting + ├─→ loadPluginConfig() # JSONC parse → project/user merge → Zod validate → migrate + ├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler + ├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry (26 tools) + ├─→ createHooks() # 3-tier: Core(33) + Continuation(7) + Skill(2) = 41 hooks + └─→ createPluginInterface() # 7 OpenCode hook handlers → PluginInterface ``` +## 7 OPENCODE HOOK HANDLERS + +| Handler | Purpose | +|---------|---------| +| `config` | 6-phase: provider → plugin-components → agents → tools → MCPs → commands | +| `tool` | 26 registered tools | +| `chat.message` | First-message variant, session setup, keyword detection | +| `chat.params` | Anthropic effort level adjustment | +| `event` | Session lifecycle (created, deleted, idle, error) | +| `tool.execute.before` | Pre-tool hooks (file guard, label truncator, rules injector) | +| `tool.execute.after` | Post-tool hooks (output truncation, metadata store) | +| `experimental.chat.messages.transform` | Context injection, thinking block validation | + ## WHERE TO LOOK | Task | Location | Notes | |------|----------|-------| -| Add agent | `src/agents/` | Create .ts with factory, add to `agentSources` in builtin-agents/ | -| Add hook | `src/hooks/` | Create dir, register in `src/plugin/hooks/create-*-hooks.ts` | -| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts | -| Add MCP | `src/mcp/` | Create config, add to `createBuiltinMcps()` | -| Add skill | `src/features/builtin-skills/` | Create .ts in skills/ | -| Add command | `src/features/builtin-commands/` | Add template + register in commands.ts | -| Config schema | `src/config/schema/` | 21 schema component files, run `bun run build:schema` | -| Plugin config | `src/plugin-handlers/config-handler.ts` | JSONC loading, merging, migration | -| Background agents | `src/features/background-agent/` | manager.ts (1701 lines) | -| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (1976 lines) | -| Delegation | `src/tools/delegate-task/` | Category routing (constants.ts 569 lines) | -| Task system | `src/features/claude-tasks/` | Task schema, storage, todo sync | -| Plugin interface | `src/plugin/` | 21 files composing hooks, handlers, registries | +| Add new agent | `src/agents/` + `src/agents/builtin-agents/` | Follow createXXXAgent factory pattern | +| Add new hook | `src/hooks/{name}/` + register in `src/plugin/hooks/create-*-hooks.ts` | Match event type to tier | +| Add new tool | `src/tools/{name}/` + register in `src/plugin/tool-registry.ts` | Follow createXXXTool factory | +| Add new feature module | `src/features/{name}/` | Standalone module, wire in plugin/ | +| Add new MCP | `src/mcp/` + register in `createBuiltinMcps()` | Remote HTTP only | +| Add new skill | `src/features/builtin-skills/skills/` | Implement BuiltinSkill interface | +| Add new command | `src/features/builtin-commands/` | Template in templates/ | +| Add new CLI command | `src/cli/cli-program.ts` | Commander.js subcommand | +| 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 | -## TDD (Test-Driven Development) +## MULTI-LEVEL CONFIG -**MANDATORY.** RED-GREEN-REFACTOR: -1. **RED**: Write test → `bun test` → FAIL -2. **GREEN**: Implement minimum → PASS -3. **REFACTOR**: Clean up → stay GREEN +``` +Project (.opencode/oh-my-opencode.jsonc) → User (~/.config/opencode/oh-my-opencode.jsonc) → Defaults +``` -**Rules:** -- NEVER write implementation before test -- NEVER delete failing tests — fix the code -- Test file: `*.test.ts` alongside source (176 test files) -- BDD comments: `//#given`, `//#when`, `//#then` +Fields: agents (14 overridable), categories (8 built-in + custom), disabled_* arrays, 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 -- **Package manager**: Bun only (`bun run`, `bun build`, `bunx`) -- **Types**: bun-types (NEVER @types/node) -- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` -- **Exports**: Barrel pattern via index.ts -- **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories -- **Testing**: BDD comments, 176 test files, 1130 TypeScript files -- **Temperature**: 0.1 for code agents, max 0.3 -- **Modular architecture**: 200 LOC hard limit per file (prompt strings exempt) +- **Test pattern**: Vitest, co-located `*.test.ts`, given/when/then style +- **Factory pattern**: `createXXX()` for all tools, hooks, agents +- **Hook tiers**: Session (20) → Tool-Guard (9) → Transform (4) → Continuation (7) → Skill (2) +- **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all` +- **Model resolution**: 3-step: override → category-default → provider-fallback → system-default +- **Config format**: JSONC with comments, Zod v4 validation, snake_case keys ## ANTI-PATTERNS -| Category | Forbidden | -|----------|-----------| -| Package Manager | npm, yarn — Bun exclusively | -| Types | @types/node — use bun-types | -| File Ops | mkdir/touch/rm/cp/mv in code — use bash tool | -| Publishing | Direct `bun publish` — GitHub Actions only | -| Versioning | Local version bump — CI manages | -| Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` | -| Error Handling | Empty catch blocks | -| Testing | Deleting failing tests, writing implementation before test | -| Agent Calls | Sequential — use `task` parallel | -| Hook Logic | Heavy PreToolUse — slows every call | -| Commits | Giant (3+ files), separate test from impl | -| Temperature | >0.3 for code agents | -| Trust | Agent self-reports — ALWAYS verify | -| Git | `git add -i`, `git rebase -i` (no interactive input) | -| Git | Skip hooks (--no-verify), force push without request | -| Bash | `sleep N` — use conditional waits | -| Bash | `cd dir && cmd` — use workdir parameter | -| Files | Catch-all utils.ts/helpers.ts — name by purpose | - -## AGENT MODELS - -| Agent | Model | Temp | Purpose | -|-------|-------|------|---------| -| Sisyphus | anthropic/claude-opus-4-6 | 0.1 | Primary orchestrator (fallback: kimi-k2.5 → glm-4.7 → gpt-5.3-codex → gemini-3-pro) | -| Hephaestus | openai/gpt-5.3-codex | 0.1 | Autonomous deep worker (NO fallback) | -| Atlas | anthropic/claude-sonnet-4-5 | 0.1 | Master orchestrator (fallback: kimi-k2.5 → gpt-5.2) | -| Prometheus | anthropic/claude-opus-4-6 | 0.1 | Strategic planning (fallback: kimi-k2.5 → gpt-5.2) | -| oracle | openai/gpt-5.2 | 0.1 | Consultation, debugging (fallback: claude-opus-4-6) | -| librarian | zai-coding-plan/glm-4.7 | 0.1 | Docs, GitHub search (fallback: glm-4.7-free) | -| explore | xai/grok-code-fast-1 | 0.1 | Fast codebase grep (fallback: claude-haiku-4-5 → gpt-5-mini → gpt-5-nano) | -| multimodal-looker | google/gemini-3-flash | 0.1 | PDF/image analysis | -| Metis | anthropic/claude-opus-4-6 | 0.3 | Pre-planning analysis (fallback: kimi-k2.5 → gpt-5.2) | -| Momus | openai/gpt-5.2 | 0.1 | Plan validation (fallback: claude-opus-4-6) | -| Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor | - -## OPENCODE PLUGIN API - -Plugin SDK from `@opencode-ai/plugin`. Plugin = `async (PluginInput) => Hooks`. - -| Hook | Purpose | -|------|---------| -| `tool` | Register custom tools (Record) | -| `chat.message` | Intercept user messages (can modify parts) | -| `chat.params` | Modify LLM parameters (temperature, topP, options) | -| `tool.execute.before` | Pre-tool interception (can modify args) | -| `tool.execute.after` | Post-tool processing (can modify output) | -| `event` | Session lifecycle events (session.created, session.stop, etc.) | -| `config` | Config modification (register agents, MCPs, commands) | -| `experimental.chat.messages.transform` | Transform message history | -| `experimental.session.compacting` | Session compaction customization | - -## DEPENDENCIES - -| Package | Purpose | -|---------|---------| -| `@opencode-ai/plugin` + `sdk` | OpenCode integration SDK | -| `@ast-grep/cli` + `napi` | AST pattern matching (search/replace) | -| `@code-yeongyu/comment-checker` | AI comment detection/prevention | -| `@modelcontextprotocol/sdk` | MCP client for remote HTTP servers | -| `@clack/prompts` | Interactive CLI TUI | -| `commander` | CLI argument parsing | -| `zod` (v4) | Schema validation for config | -| `jsonc-parser` | JSONC config with comments | -| `picocolors` | Terminal colors | -| `picomatch` | Glob pattern matching | -| `vscode-jsonrpc` | LSP communication | -| `js-yaml` | YAML parsing (tasks, skills) | -| `detect-libc` | Platform binary selection | +- Never use `as any`, `@ts-ignore`, `@ts-expect-error` +- Never suppress lint/type errors +- Never add emojis to code/comments unless user explicitly asks +- Never commit unless explicitly requested +- Test: given/when/then — never use Arrange-Act-Assert comments +- Comments: avoid AI-generated comment patterns (enforced by comment-checker hook) ## COMMANDS ```bash -bun run typecheck # Type check -bun run build # ESM + declarations + schema -bun run rebuild # Clean + Build -bun test # 176 test files -bun run build:schema # Regenerate JSON schema +bun test # Vitest test suite +bun run build # Build plugin +bunx oh-my-opencode install # Interactive setup +bunx oh-my-opencode doctor # Health diagnostics +bunx oh-my-opencode run # Non-interactive session ``` -## DEPLOYMENT - -**GitHub Actions workflow_dispatch ONLY** -1. Commit & push changes -2. Trigger: `gh workflow run publish -f bump=patch` -3. Never `bun publish` directly, never bump version locally - -## COMPLEXITY HOTSPOTS - -| File | Lines | Description | -|------|-------|-------------| -| `src/features/background-agent/manager.ts` | 1701 | Task lifecycle, concurrency | -| `src/hooks/anthropic-context-window-limit-recovery/` | 2232 | Multi-strategy context recovery | -| `src/hooks/claude-code-hooks/` | 2110 | Claude Code settings.json compat | -| `src/hooks/todo-continuation-enforcer/` | 2061 | Core boulder mechanism | -| `src/hooks/atlas/` | 1976 | Session orchestration | -| `src/hooks/ralph-loop/` | 1687 | Self-referential dev loop | -| `src/hooks/keyword-detector/` | 1665 | Mode detection (ultrawork/search) | -| `src/hooks/rules-injector/` | 1604 | Conditional rules injection | -| `src/hooks/think-mode/` | 1365 | Model/variant switching | -| `src/hooks/session-recovery/` | 1279 | Auto error recovery | -| `src/features/builtin-skills/skills/git-master.ts` | 1112 | Git master skill | -| `src/tools/delegate-task/constants.ts` | 569 | Category routing configs | - -## MCP ARCHITECTURE - -Three-tier system: -1. **Built-in** (src/mcp/): websearch (Exa/Tavily), context7 (docs), grep_app (GitHub) -2. **Claude Code compat** (features/claude-code-mcp-loader/): .mcp.json with `${VAR}` expansion -3. **Skill-embedded** (features/opencode-skill-loader/): YAML frontmatter in SKILL.md - -## CONFIG SYSTEM - -- **Zod validation**: 21 schema component files in `src/config/schema/` -- **JSONC support**: Comments, trailing commas -- **Multi-level**: Project (`.opencode/`) → User (`~/.config/opencode/`) → Defaults -- **Migration**: Legacy config auto-migration in `src/shared/migration/` - ## NOTES -- **OpenCode**: Requires >= 1.0.150 -- **1130 TypeScript files**, 176 test files, 127k+ lines -- **Flaky tests**: ralph-loop (CI timeout), session-state (parallel pollution) -- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker -- **No linter/formatter**: No ESLint, Prettier, or Biome configured -- **License**: SUL-1.0 (Sisyphus Use License) +- Logger writes to `/tmp/oh-my-opencode.log` — check there for debugging +- Background tasks: 5 concurrent per model/provider (configurable) +- Plugin load timeout: 10s for Claude Code plugins +- Model fallback priority: Claude > OpenAI > Gemini > Copilot > OpenCode Zen > Z.ai > Kimi +- Config migration runs automatically on legacy keys (agent names, hook names, model versions) diff --git a/src/AGENTS.md b/src/AGENTS.md index 5c98a4046..2025fabda 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -1,81 +1,41 @@ -# SRC KNOWLEDGE BASE +# src/ — Plugin Source + +**Generated:** 2026-02-17 ## OVERVIEW -Main plugin entry point and orchestration layer. Plugin initialization, hook registration, tool composition, and lifecycle management. +Root source directory. Entry point `index.ts` orchestrates 4-step initialization: config → managers → tools → hooks → plugin interface. -## STRUCTURE +## KEY FILES + +| File | Purpose | +|------|---------| +| `index.ts` | Plugin entry, exports `OhMyOpenCodePlugin` | +| `plugin-config.ts` | JSONC parse, multi-level merge (project → user → defaults), Zod validation | +| `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler | +| `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry | +| `create-hooks.ts` | 3-tier hook composition: Core(33) + Continuation(7) + Skill(2) | +| `plugin-interface.ts` | Assembles 7 OpenCode hook handlers into PluginInterface | + +## CONFIG LOADING ``` -src/ -├── index.ts # Main plugin entry (106 lines) — OhMyOpenCodePlugin factory -├── create-hooks.ts # Hook coordination: core, continuation, skill (62 lines) -├── create-managers.ts # Manager initialization: Tmux, Background, SkillMcp, Config (80 lines) -├── create-tools.ts # Tool registry + skill context composition (54 lines) -├── plugin-interface.ts # Plugin interface assembly — 7 OpenCode hooks (66 lines) -├── plugin-config.ts # Config loading orchestration (user + project merge, 180 lines) -├── plugin-state.ts # Model cache state (context limits, anthropic 1M flag, 12 lines) -├── agents/ # 11 AI agents (32 files) — see agents/AGENTS.md -├── cli/ # CLI installer, doctor (107+ files) — see cli/AGENTS.md -├── config/ # Zod schema (21 component files) — see config/AGENTS.md -├── features/ # Background agents, skills, commands (18 dirs) — see features/AGENTS.md -├── hooks/ # 41 lifecycle hooks (36 dirs) — see hooks/AGENTS.md -├── mcp/ # Built-in MCPs (6 files) — see mcp/AGENTS.md -├── plugin/ # Plugin interface composition (21 files) -├── plugin-handlers/ # Config loading, plan inheritance (15 files) — see plugin-handlers/AGENTS.md -├── shared/ # Cross-cutting utilities (96 files) — see shared/AGENTS.md -└── tools/ # 26 tools (14 dirs) — see tools/AGENTS.md +loadPluginConfig(directory, ctx) + 1. User: ~/.config/opencode/oh-my-opencode.jsonc + 2. Project: .opencode/oh-my-opencode.jsonc + 3. mergeConfigs(user, project) → deepMerge for agents/categories, Set union for disabled_* + 4. Zod safeParse → defaults for omitted fields + 5. migrateConfigFile() → legacy key transformation ``` -## PLUGIN INITIALIZATION (10 steps) +## HOOK COMPOSITION -1. `injectServerAuthIntoClient(ctx.client)` — Auth injection -2. `startTmuxCheck()` — Tmux availability -3. `loadPluginConfig(ctx.directory, ctx)` — User + project config merge → Zod validation -4. `createFirstMessageVariantGate()` — First message variant override gate -5. `createModelCacheState()` — Model context limits cache -6. `createManagers(...)` → 4 managers: - - `TmuxSessionManager` — Multi-pane tmux sessions - - `BackgroundManager` — Parallel subagent execution - - `SkillMcpManager` — MCP server lifecycle - - `ConfigHandler` — Plugin config API to OpenCode -7. `createTools(...)` → `createSkillContext()` + `createAvailableCategories()` + `createToolRegistry()` -8. `createHooks(...)` → `createCoreHooks()` + `createContinuationHooks()` + `createSkillHooks()` -9. `createPluginInterface(...)` → 7 OpenCode hook handlers -10. Return plugin with `experimental.session.compacting` - -## HOOK REGISTRATION (3 tiers) - -**Core Hooks** (`create-core-hooks.ts`): -- Session (20): context-window-monitor, session-recovery, think-mode, ralph-loop, anthropic-effort, ... -- Tool Guard (8): comment-checker, tool-output-truncator, rules-injector, write-existing-file-guard, ... -- Transform (4): claude-code-hooks, keyword-detector, context-injector, thinking-block-validator - -**Continuation Hooks** (`create-continuation-hooks.ts`): -- 7 hooks: stop-continuation-guard, compaction-context-injector, todo-continuation-enforcer, atlas, ... - -**Skill Hooks** (`create-skill-hooks.ts`): -- 2 hooks: category-skill-reminder, auto-slash-command - -## PLUGIN INTERFACE (7 OpenCode handlers) - -| Handler | Source | Purpose | -|---------|--------|---------| -| `tool` | filteredTools | All registered tools | -| `chat.params` | createChatParamsHandler | Anthropic effort level | -| `chat.message` | createChatMessageHandler | First message variant, session setup | -| `experimental.chat.messages.transform` | createMessagesTransformHandler | Context injection, keyword detection | -| `config` | configHandler | Agent/MCP/command registration | -| `event` | createEventHandler | Session lifecycle | -| `tool.execute.before` | createToolExecuteBeforeHandler | Pre-tool hooks | -| `tool.execute.after` | createToolExecuteAfterHandler | Post-tool hooks | - -## SAFE HOOK CREATION PATTERN - -```typescript -const hook = isHookEnabled("hook-name") - ? safeCreateHook("hook-name", () => createHookFactory(ctx), { enabled: safeHookEnabled }) - : null; ``` - -All hooks use this pattern for graceful degradation on failure. +createHooks() + ├─→ createCoreHooks() # 33 hooks + │ ├─ createSessionHooks() # 20: contextWindowMonitor, thinkMode, ralphLoop, sessionRecovery... + │ ├─ createToolGuardHooks() # 9: commentChecker, rulesInjector, writeExistingFileGuard... + │ └─ createTransformHooks() # 4: claudeCodeHooks, keywordDetector, contextInjector, thinkingBlockValidator + ├─→ createContinuationHooks() # 7: todoContinuationEnforcer, atlas, stopContinuationGuard... + └─→ createSkillHooks() # 2: categorySkillReminder, autoSlashCommand +``` diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index 4946b8925..cfdd0f9b6 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -1,85 +1,79 @@ -# AGENTS KNOWLEDGE BASE +# src/agents/ — 11 Agent Definitions + +**Generated:** 2026-02-17 ## OVERVIEW -11 AI agents with factory functions, fallback chains, and model-specific prompt variants. Each agent has metadata (category, cost, triggers) and configurable tool restrictions. +Agent factories following `createXXXAgent(model) → AgentConfig` pattern. Each has static `mode` property. Built via `buildAgent()` compositing factory + categories + skills. -## STRUCTURE -``` -agents/ -├── sisyphus.ts # Main orchestrator (559 lines) -├── hephaestus.ts # Autonomous deep worker (651 lines) -├── oracle.ts # Strategic advisor (171 lines) -├── librarian.ts # Multi-repo research (329 lines) -├── explore.ts # Fast codebase grep (125 lines) -├── multimodal-looker.ts # Media analyzer (59 lines) -├── metis.ts # Pre-planning analysis (347 lines) -├── momus.ts # Plan validator (244 lines) -├── atlas/ # Master orchestrator (agent.ts + default.ts + gpt.ts) -├── prometheus/ # Planning agent (8 files, plan-template 423 lines) -├── sisyphus-junior/ # Delegated task executor (agent.ts + default.ts + gpt.ts) -├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (433 lines) -├── builtin-agents/ # Agent registry + model resolution -├── agent-builder.ts # Agent construction with category merging (51 lines) -├── utils.ts # Agent creation, model fallback resolution (571 lines) -├── types.ts # AgentModelConfig, AgentPromptMetadata (106 lines) -└── index.ts # Exports -``` +## AGENT INVENTORY -## AGENT MODELS - -| Agent | Model | Temp | Fallback Chain | Cost | -|-------|-------|------|----------------|------| -| Sisyphus | claude-opus-4-6 | 0.1 | kimi-k2.5 → glm-4.7 → gpt-5.3-codex → gemini-3-pro | EXPENSIVE | -| Hephaestus | gpt-5.3-codex | 0.1 | NONE (required) | EXPENSIVE | -| Atlas | claude-sonnet-4-5 | 0.1 | kimi-k2.5 → gpt-5.2 | EXPENSIVE | -| Prometheus | claude-opus-4-6 | 0.1 | kimi-k2.5 → gpt-5.2 | EXPENSIVE | -| oracle | gpt-5.2 | 0.1 | claude-opus-4-6 | EXPENSIVE | -| librarian | glm-4.7 | 0.1 | glm-4.7-free | CHEAP | -| explore | grok-code-fast-1 | 0.1 | claude-haiku-4-5 → gpt-5-mini → gpt-5-nano | FREE | -| multimodal-looker | gemini-3-flash | 0.1 | NONE | CHEAP | -| Metis | claude-opus-4-6 | 0.3 | kimi-k2.5 → gpt-5.2 | EXPENSIVE | -| Momus | gpt-5.2 | 0.1 | claude-opus-4-6 | EXPENSIVE | -| Sisyphus-Junior | claude-sonnet-4-5 | 0.1 | (user-configurable) | EXPENSIVE | +| Agent | Model | Temp | Mode | Fallback Chain | Purpose | +|-------|-------|------|------|----------------|---------| +| **Sisyphus** | claude-opus-4-6 | 0.1 | primary | kimi-k2.5 → glm-4.7 → gemini-3-pro | Main orchestrator, plans + delegates | +| **Hephaestus** | gpt-5.3-codex | 0.1 | primary | NONE (required) | Autonomous deep worker | +| **Oracle** | gpt-5.2 | 0.1 | subagent | claude-opus-4-6 → gemini-3-pro | Read-only consultation | +| **Librarian** | glm-4.7 | 0.1 | subagent | glm-4.7-free → claude-sonnet-4-5 | External docs/code search | +| **Explore** | grok-code-fast-1 | 0.1 | subagent | claude-haiku-4-5 → gpt-5-nano | Contextual grep | +| **Multimodal-Looker** | gemini-3-flash | 0.1 | subagent | gpt-5.2 → glm-4.6v → ... (6 deep) | PDF/image analysis | +| **Metis** | claude-opus-4-6 | **0.3** | subagent | kimi-k2.5 → gpt-5.2 → gemini-3-pro | Pre-planning consultant | +| **Momus** | gpt-5.2 | 0.1 | subagent | claude-opus-4-6 → gemini-3-pro | Plan reviewer | +| **Atlas** | claude-sonnet-4-5 | 0.1 | primary | kimi-k2.5 → gpt-5.2 → gemini-3-pro | Todo-list orchestrator | +| **Prometheus** | claude-opus-4-6 | 0.1 | — | kimi-k2.5 → gpt-5.2 → gemini-3-pro | Strategic planner (internal) | +| **Sisyphus-Junior** | claude-sonnet-4-5 | 0.1 | all | user-configurable | Category-spawned executor | ## TOOL RESTRICTIONS -| Agent | Denied | Allowed | -|-------|--------|---------| -| oracle | write, edit, task, call_omo_agent | Read-only consultation | -| librarian | write, edit, task, call_omo_agent | Research tools only | -| explore | write, edit, task, call_omo_agent | Search tools only | -| multimodal-looker | ALL except `read` | Vision-only | -| Sisyphus-Junior | task | No delegation | -| Atlas | task, call_omo_agent | Orchestration only | +| Agent | Denied Tools | +|-------|-------------| +| Oracle | write, edit, task, call_omo_agent | +| Librarian | write, edit, task, call_omo_agent | +| Explore | write, edit, task, call_omo_agent | +| Multimodal-Looker | ALL except read | +| Atlas | task, call_omo_agent | +| Momus | write, edit, task | -## THINKING / REASONING +## STRUCTURE -| Agent | Claude | GPT | -|-------|--------|-----| -| Sisyphus | 32k budget tokens | reasoningEffort: "medium" | -| Hephaestus | — | reasoningEffort: "medium" | -| Oracle | 32k budget tokens | reasoningEffort: "medium" | -| Metis | 32k budget tokens | — | -| Momus | 32k budget tokens | reasoningEffort: "medium" | -| Sisyphus-Junior | 32k budget tokens | reasoningEffort: "medium" | +``` +agents/ +├── sisyphus.ts # 559 LOC, main orchestrator +├── hephaestus.ts # 507 LOC, autonomous worker +├── oracle.ts # Read-only consultant +├── librarian.ts # External search +├── explore.ts # Codebase grep +├── multimodal-looker.ts # Vision/PDF +├── metis.ts # Pre-planning +├── momus.ts # Plan review +├── atlas/agent.ts # Todo orchestrator +├── types.ts # AgentFactory, AgentMode +├── agent-builder.ts # buildAgent() composition +├── utils.ts # Agent utilities +├── builtin-agents.ts # createBuiltinAgents() registry +└── builtin-agents/ # maybeCreateXXXConfig conditional factories + ├── sisyphus-agent.ts + ├── hephaestus-agent.ts + ├── atlas-agent.ts + ├── general-agents.ts # collectPendingBuiltinAgents + └── available-skills.ts +``` -## KEY PROMPT PATTERNS +## FACTORY PATTERN -- **Sisyphus/Hephaestus**: Dynamic prompts via `dynamic-agent-prompt-builder.ts` injecting available tools/skills/categories -- **Atlas, Sisyphus-Junior**: Model-specific prompts (Claude vs GPT variants) -- **Prometheus**: 6-section modular prompt (identity → interview → plan-generation → high-accuracy → template → behavioral) +```typescript +const createXXXAgent: AgentFactory = (model: string) => ({ + instructions: "...", + model, + temperature: 0.1, + // ...config +}) +createXXXAgent.mode = "subagent" // or "primary" or "all" +``` -## HOW TO ADD +Model resolution: `AGENT_MODEL_REQUIREMENTS` in `shared/model-requirements.ts` defines fallback chains per agent. -1. Create `src/agents/my-agent.ts` exporting factory + metadata -2. Add to `agentSources` in `src/agents/builtin-agents/` -3. Update `AgentNameSchema` in `src/config/schema/agent-names.ts` -4. Register in `src/plugin-handlers/agent-config-handler.ts` +## MODES -## ANTI-PATTERNS - -- **Trust agent self-reports**: NEVER — always verify outputs -- **High temperature**: Don't use >0.3 for code agents -- **Sequential calls**: Use `task` with `run_in_background` for exploration -- **Prometheus writing code**: Planner only — never implements +- **primary**: Respects UI-selected model, uses fallback chain +- **subagent**: Uses own fallback chain, ignores UI selection +- **all**: Available in both contexts (Sisyphus-Junior) diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index 5ac159ab2..59d05601f 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -1,69 +1,71 @@ -# CLI KNOWLEDGE BASE +# src/cli/ — CLI: install, run, doctor, mcp-oauth + +**Generated:** 2026-02-17 ## OVERVIEW -CLI entry: `bunx oh-my-opencode`. 107+ files with Commander.js + @clack/prompts TUI. 5 commands: install, run, doctor, get-local-version, mcp-oauth. - -## STRUCTURE -``` -cli/ -├── index.ts # Entry point (5 lines) -├── cli-program.ts # Commander.js program (150+ lines, 5 commands) -├── install.ts # TTY routing (TUI or CLI installer) -├── cli-installer.ts # Non-interactive installer (164 lines) -├── tui-installer.ts # Interactive TUI with @clack/prompts (140 lines) -├── config-manager/ # 20 config utilities -│ ├── add-plugin-to-opencode-config.ts # Plugin registration -│ ├── add-provider-config.ts # Provider setup (Google/Antigravity) -│ ├── detect-current-config.ts # Installed providers detection -│ ├── write-omo-config.ts # JSONC writing -│ ├── generate-omo-config.ts # Config generation -│ ├── jsonc-provider-editor.ts # JSONC editing -│ └── ... # 14 more utilities -├── doctor/ # 4 check categories, 21 check files -│ ├── runner.ts # Parallel check execution + result aggregation -│ ├── formatter.ts # Colored output (default/status/verbose/JSON) -│ └── checks/ # system (4), config (1), tools (4), models (6 sub-checks) -├── run/ # Session launcher (24 files) -│ ├── runner.ts # Run orchestration (126 lines) -│ ├── agent-resolver.ts # Agent: flag → env → config → Sisyphus -│ ├── session-resolver.ts # Session create or resume with retries -│ ├── event-handlers.ts # Event processing (125 lines) -│ ├── completion.ts # Completion detection -│ └── poll-for-completion.ts # Polling with timeout -├── mcp-oauth/ # OAuth token management (login, logout, status) -├── get-local-version/ # Version detection + update check -├── model-fallback.ts # Model fallback configuration -└── provider-availability.ts # Provider availability checks -``` +Commander.js CLI with 5 commands. Entry: `index.ts` → `runCli()` in `cli-program.ts`. ## COMMANDS | Command | Purpose | Key Logic | |---------|---------|-----------| -| `install` | Interactive setup | Provider selection → config generation → plugin registration | -| `run` | Session launcher | Agent: flag → env → config → Sisyphus. Enforces todo completion. | -| `doctor` | 4-category health checks | system, config, tools, models (6 sub-checks) | -| `get-local-version` | Version check | Detects installed, compares with npm latest | -| `mcp-oauth` | OAuth tokens | login (PKCE flow), logout, status | +| `install` | Interactive/non-interactive setup | Provider selection → config gen → plugin registration | +| `run ` | Non-interactive session launcher | Agent resolution (flag → env → config → Sisyphus) | +| `doctor` | 4-category health checks | System, Config, Tools, Models | +| `get-local-version` | Version detection | Installed vs npm latest | +| `mcp-oauth` | OAuth token management | login (PKCE), logout, status | -## RUN SESSION LIFECYCLE +## STRUCTURE -1. Load config, resolve agent (CLI > env > config > Sisyphus) -2. Create server connection (port/attach), setup cleanup/signal handlers -3. Resolve session (create new or resume with retries) -4. Send prompt, start event processing, poll for completion -5. Execute on-complete hook, output JSON if requested, cleanup +``` +cli/ +├── index.ts # Entry point → runCli() +├── cli-program.ts # Commander.js program (5 commands) +├── install.ts # Routes to TUI or CLI installer +├── cli-installer.ts # Non-interactive (console output) +├── tui-installer.ts # Interactive (@clack/prompts) +├── model-fallback.ts # Model config gen by provider availability +├── provider-availability.ts # Provider detection +├── fallback-chain-resolution.ts # Fallback chain logic +├── config-manager/ # 20 config utilities +│ ├── plugin registration, provider config +│ ├── JSONC operations, auth plugins +│ └── npm dist-tags, binary detection +├── doctor/ +│ ├── runner.ts # Parallel check execution +│ ├── formatter.ts # Output formatting +│ └── checks/ # 15 check files in 4 categories +│ ├── system.ts # Binary, plugin, version +│ ├── config.ts # JSONC validity, Zod schema +│ ├── tools.ts # AST-Grep, LSP, GH CLI, MCP +│ └── model-resolution.ts # Cache, resolution, overrides (6 sub-files) +├── run/ # Session launcher +│ ├── runner.ts # Main orchestration +│ ├── agent-resolver.ts # Flag → env → config → Sisyphus +│ ├── session-resolver.ts # Create/resume sessions +│ ├── event-handlers.ts # Event processing +│ └── poll-for-completion.ts # Wait for todos/background tasks +└── mcp-oauth/ # OAuth token management +``` -## HOW TO ADD CHECK +## MODEL FALLBACK SYSTEM -1. Create `src/cli/doctor/checks/my-check.ts` -2. Export `getXXXCheckDefinition()` returning `CheckDefinition` -3. Add to `getAllCheckDefinitions()` in `checks/index.ts` +Priority: Claude > OpenAI > Gemini > Copilot > OpenCode Zen > Z.ai > Kimi > glm-4.7-free -## ANTI-PATTERNS +Agent-specific: librarian→ZAI, explore→Haiku/nano, hephaestus→requires OpenAI/Copilot -- **Blocking in non-TTY**: Check `process.stdout.isTTY` -- **Direct JSON.parse**: Use `parseJsonc()` from shared -- **Silent failures**: Return `warn` or `fail` in doctor, don't throw -- **Hardcoded paths**: Use `getOpenCodeConfigPaths()` from config-manager +## DOCTOR CHECKS + +| Category | Validates | +|----------|-----------| +| **System** | Binary found, version >=1.0.150, plugin registered, version match | +| **Config** | JSONC validity, Zod schema, model override syntax | +| **Tools** | AST-Grep, comment-checker, LSP servers, GH CLI, MCP servers | +| **Models** | Cache exists, model resolution, agent/category overrides, availability | + +## HOW TO ADD A DOCTOR CHECK + +1. Create `src/cli/doctor/checks/{name}.ts` +2. Export check function matching `DoctorCheck` interface +3. Register in `checks/index.ts` diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md index 824d4e02f..426b1d62e 100644 --- a/src/config/AGENTS.md +++ b/src/config/AGENTS.md @@ -1,52 +1,50 @@ -# CONFIG KNOWLEDGE BASE +# src/config/ — Zod v4 Schema System + +**Generated:** 2026-02-17 ## OVERVIEW -Zod schema definitions for plugin configuration. 21 component files composing `OhMyOpenCodeConfigSchema` with multi-level inheritance and JSONC support. +22 schema files composing `OhMyOpenCodeConfigSchema`. Zod v4 validation with `safeParse()`. All fields optional — omitted fields use plugin defaults. + +## SCHEMA TREE -## STRUCTURE ``` -config/ -├── schema/ # 21 schema component files -│ ├── oh-my-opencode-config.ts # Root schema composition (57 lines) -│ ├── agent-names.ts # BuiltinAgentNameSchema (11 agents), BuiltinSkillNameSchema -│ ├── agent-overrides.ts # AgentOverrideConfigSchema (model, variant, temp, thinking...) -│ ├── categories.ts # 8 categories: visual-engineering, ultrabrain, deep, artistry, quick, ... -│ ├── hooks.ts # HookNameSchema (100+ hook names) -│ ├── commands.ts # BuiltinCommandNameSchema -│ ├── experimental.ts # ExperimentalConfigSchema -│ ├── dynamic-context-pruning.ts # DynamicContextPruningConfigSchema (55 lines) -│ ├── background-task.ts # BackgroundTaskConfigSchema -│ ├── claude-code.ts # ClaudeCodeConfigSchema -│ ├── comment-checker.ts # CommentCheckerConfigSchema -│ ├── notification.ts # NotificationConfigSchema -│ ├── ralph-loop.ts # RalphLoopConfigSchema -│ ├── sisyphus.ts # SisyphusConfigSchema -│ ├── sisyphus-agent.ts # SisyphusAgentConfigSchema -│ ├── skills.ts # SkillsConfigSchema (45 lines) -│ ├── tmux.ts # TmuxConfigSchema, TmuxLayoutSchema -│ ├── websearch.ts # WebsearchConfigSchema -│ ├── browser-automation.ts # BrowserAutomationConfigSchema -│ ├── git-master.ts # GitMasterConfigSchema -│ └── babysitting.ts # BabysittingConfigSchema -├── schema.ts # Barrel export (24 lines) -├── schema.test.ts # Validation tests (735 lines) -├── types.ts # TypeScript types from schemas -└── index.ts # Barrel export (33 lines) +config/schema/ +├── oh-my-opencode-config.ts # ROOT: OhMyOpenCodeConfigSchema (composes all below) +├── agent-names.ts # BuiltinAgentNameSchema (11), OverridableAgentNameSchema (14) +├── agent-overrides.ts # AgentOverrideConfigSchema (21 fields per agent) +├── categories.ts # 8 built-in + custom categories +├── hooks.ts # HookNameSchema (46 hooks) +├── skills.ts # SkillsConfigSchema (sources, paths, recursive) +├── commands.ts # BuiltinCommandNameSchema +├── experimental.ts # Feature flags (plugin_load_timeout_ms min 1000, hashline_edit) +├── 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 +├── 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 +├── background-task.ts # Concurrency limits per model/provider +├── babysitting.ts # Unstable agent monitoring +├── dynamic-context-pruning.ts # Context pruning settings +└── internal/permission.ts # AgentPermissionSchema ``` -## ROOT SCHEMA +## ROOT SCHEMA FIELDS (26) -`OhMyOpenCodeConfigSchema` composes: `$schema`, `new_task_system_enabled`, `default_run_agent`, `auto_update`, `disabled_{mcps,agents,skills,hooks,commands,tools}`, `agents` (14 agent keys), `categories` (8 built-in), `claude_code`, `sisyphus_agent`, `comment_checker`, `experimental`, `skills`, `ralph_loop`, `background_task`, `notification`, `babysitting`, `git_master`, `browser_automation_engine`, `websearch`, `tmux`, `sisyphus` +`$schema`, `new_task_system_enabled`, `default_run_agent`, `disabled_mcps`, `disabled_agents`, `disabled_skills`, `disabled_hooks`, `disabled_commands`, `disabled_tools`, `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`, `_migrations` -## CONFIGURATION HIERARCHY +## AGENT OVERRIDE FIELDS (21) -Project (`.opencode/oh-my-opencode.json`) → User (`~/.config/opencode/oh-my-opencode.json`) → Defaults +`model`, `variant`, `category`, `skills`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `providerOptions` -## AGENT OVERRIDE FIELDS +## HOW TO ADD CONFIG -`model`, `variant`, `category`, `skills`, `temperature`, `top_p`, `maxTokens`, `thinking`, `reasoningEffort`, `textVerbosity`, `prompt`, `prompt_append`, `tools`, `permission`, `providerOptions`, `disable`, `description`, `mode`, `color` - -## AFTER SCHEMA CHANGES - -Run `bun run build:schema` to regenerate `dist/oh-my-opencode.schema.json` +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` for TypeScript types +4. Access in handlers via `pluginConfig.{name}` diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 8844ab186..ebf98eabe 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -1,83 +1,69 @@ -# FEATURES KNOWLEDGE BASE +# src/features/ — 18 Feature Modules + +**Generated:** 2026-02-17 ## OVERVIEW -18 feature modules extending plugin capabilities: agent orchestration, skill loading, Claude Code compatibility, MCP management, task storage, and tmux integration. +Standalone feature modules wired into plugin/ layer. Each is self-contained with own types, implementation, and tests. -## STRUCTURE -``` -features/ -├── background-agent/ # Task lifecycle, concurrency (56 files, 1701-line manager) -│ ├── manager.ts # Main task orchestration (1701 lines) -│ ├── concurrency.ts # Parallel execution limits per provider/model (137 lines) -│ ├── task-history.ts # Task execution history per parent session (76 lines) -│ └── spawner/ # Task spawning: factory, starter, resumer, tmux (8 files) -├── tmux-subagent/ # Tmux integration (28 files, 3303 LOC) -│ └── manager.ts # Pane management, grid planning (350 lines) -├── opencode-skill-loader/ # YAML frontmatter skill loading (28 files, 2967 LOC) -│ ├── loader.ts # Skill discovery (4 scopes) -│ ├── skill-directory-loader.ts # Recursive directory scanning (maxDepth=2) -│ ├── skill-discovery.ts # getAllSkills() with caching + provider gating -│ └── merger/ # Skill merging with scope priority -├── mcp-oauth/ # OAuth 2.0 flow for MCP (18 files, 2164 LOC) -│ ├── provider.ts # McpOAuthProvider class -│ ├── oauth-authorization-flow.ts # PKCE, callback handling -│ └── dcr.ts # Dynamic Client Registration (RFC 7591) -├── skill-mcp-manager/ # MCP client lifecycle per session (12 files, 1769 LOC) -│ └── manager.ts # SkillMcpManager class (150 lines) -├── builtin-skills/ # 5 built-in skills (10 files, 1921 LOC) -│ └── skills/ # git-master (1112), playwright (313), dev-browser (222), frontend-ui-ux (80) -├── builtin-commands/ # 7 command templates (11 files, 1511 LOC) -│ └── templates/ # refactor (620), init-deep (306), handoff (178), start-work, ralph-loop, stop-continuation -├── claude-tasks/ # Task schema + storage (7 files) — see AGENTS.md -├── context-injector/ # AGENTS.md, README.md, rules injection (6 files, 809 LOC) -├── claude-code-plugin-loader/ # Plugin discovery from .opencode/plugins/ (10 files) -├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion (6 files) -├── claude-code-command-loader/ # Command loading from .opencode/commands/ (3 files) -├── claude-code-agent-loader/ # Agent loading from .opencode/agents/ (3 files) -├── claude-code-session-state/ # Subagent session state tracking (3 files) -├── hook-message-injector/ # System message injection (4 files) -├── task-toast-manager/ # Task progress notifications (4 files) -├── boulder-state/ # Persistent state for multi-step ops (5 files) -└── tool-metadata-store/ # Tool execution metadata caching (3 files) -``` +## MODULE MAP -## KEY PATTERNS +| Module | Files | Complexity | Purpose | +|--------|-------|------------|---------| +| **background-agent** | 49 | HIGH | Task lifecycle, concurrency (5/model), polling, spawner pattern | +| **tmux-subagent** | 27 | HIGH | Tmux pane management, grid planning, session orchestration | +| **opencode-skill-loader** | 25 | HIGH | YAML frontmatter skill loading from 4 scopes | +| **mcp-oauth** | 10 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) for MCP servers | +| **builtin-skills** | 10 | LOW | 6 skills: git-master, playwright, playwright-cli, agent-browser, dev-browser, frontend-ui-ux | +| **skill-mcp-manager** | 10 | MEDIUM | MCP client lifecycle per session (stdio + HTTP) | +| **claude-code-plugin-loader** | 10 | MEDIUM | Unified plugin discovery from .opencode/plugins/ | +| **builtin-commands** | 9 | LOW | Command templates: refactor, init-deep, handoff, etc. | +| **claude-code-mcp-loader** | 5 | MEDIUM | .mcp.json loading with ${VAR} env expansion | +| **context-injector** | 4 | MEDIUM | AGENTS.md/README.md injection into context | +| **boulder-state** | 4 | LOW | Persistent state for multi-step operations | +| **hook-message-injector** | 4 | MEDIUM | System message injection for hooks | +| **claude-tasks** | 4 | MEDIUM | Task schema + file storage + OpenCode todo sync | +| **task-toast-manager** | 3 | MEDIUM | Task progress notifications | +| **claude-code-agent-loader** | 3 | LOW | Load agents from .opencode/agents/ | +| **claude-code-command-loader** | 3 | LOW | Load commands from .opencode/commands/ | +| **claude-code-session-state** | 2 | LOW | Subagent session state tracking | +| **tool-metadata-store** | 2 | LOW | Tool execution metadata cache | -**Background Agent Lifecycle:** -pending → running → completed/error/cancelled/interrupt -- Concurrency: Per provider/model limits (default: 5), queue-based FIFO -- Events: session.idle + session.error drive completion detection -- Key methods: `launch()`, `resume()`, `cancelTask()`, `getTask()`, `getAllDescendantTasks()` +## KEY MODULES -**Skill Loading Pipeline (4-scope priority):** -opencode-project (`.opencode/skills/`) > opencode (`~/.config/opencode/skills/`) > project (`.claude/skills/`) > user (`~/.claude/skills/`) +### background-agent (49 files, ~10k LOC) -**Claude Code Compatibility Layer:** -5 loaders: agent-loader, command-loader, mcp-loader, plugin-loader, session-state +Core orchestration engine. `BackgroundManager` manages task lifecycle: +- States: pending → running → completed/error/cancelled/interrupt +- Concurrency: per-model/provider limits via `ConcurrencyManager` (FIFO queue) +- Polling: 3s interval, completion via idle events + stability detection (10s unchanged) +- spawner/: 8 focused files composing via `SpawnerContext` interface -**SKILL.md Format:** -```yaml ---- -name: my-skill -description: "..." -model: "claude-opus-4-6" # optional -agent: "sisyphus" # optional -mcp: # optional embedded MCPs - server-name: - type: http - url: https://... ---- -# Skill instruction content -``` +### opencode-skill-loader (25 files, ~3.2k LOC) -## HOW TO ADD +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 -1. Create directory under `src/features/` -2. Add `index.ts`, `types.ts`, `constants.ts` as needed -3. Export from `index.ts` following barrel pattern -4. Register in main plugin if plugin-level feature +### tmux-subagent (27 files, ~3.6k LOC) -## CHILD DOCUMENTATION +State-first tmux integration: +- `TmuxSessionManager`: pane lifecycle, grid planning +- Spawn action decider + target finder +- Polling manager for session health +- Event handlers for pane creation/destruction -- See `claude-tasks/AGENTS.md` for task schema and storage details +### builtin-skills (6 skill objects) + +| Skill | Size | MCP | Tools | +|-------|------|-----|-------| +| git-master | 1111 LOC | — | Bash | +| playwright | 312 LOC | @playwright/mcp | — | +| agent-browser | (in playwright.ts) | — | Bash(agent-browser:*) | +| playwright-cli | 268 LOC | — | Bash(playwright-cli:*) | +| dev-browser | 221 LOC | — | Bash | +| frontend-ui-ux | 79 LOC | — | — | + +Browser variant selected by `browserProvider` config: playwright (default) | playwright-cli | agent-browser. diff --git a/src/features/claude-tasks/AGENTS.md b/src/features/claude-tasks/AGENTS.md index 25cbcee97..3f2b8ec8b 100644 --- a/src/features/claude-tasks/AGENTS.md +++ b/src/features/claude-tasks/AGENTS.md @@ -1,68 +1,43 @@ -# CLAUDE TASKS KNOWLEDGE BASE +# src/features/claude-tasks/ — Task Schema + Storage + +**Generated:** 2026-02-17 ## OVERVIEW -Claude Code compatible task schema and storage. Core task management with file-based persistence, atomic writes, and OpenCode todo sync. - -## STRUCTURE -``` -claude-tasks/ -├── types.ts # Task schema (Zod) -├── types.test.ts # Schema validation tests -├── storage.ts # File operations (atomic write, locking) -├── storage.test.ts # Storage tests (30 tests, 543 lines) -├── session-storage.ts # Session-scoped task storage -├── session-storage.test.ts -└── index.ts # Barrel exports -``` +4 non-test files (~622 LOC). File-based task persistence with atomic writes, locking, and OpenCode todo API sync. ## TASK SCHEMA ```typescript -type TaskStatus = "pending" | "in_progress" | "completed" | "deleted" interface Task { - id: string // T-{uuid} - subject: string // Imperative: "Run tests" - description: string - status: TaskStatus - activeForm?: string // Present continuous: "Running tests" - blocks: string[] // Task IDs this task blocks - blockedBy: string[] // Task IDs blocking this task - owner?: string // Agent name + id: string // T-{uuid} auto-generated + subject: string // Short title + description?: string // Detailed description + status: "pending" | "in_progress" | "completed" | "deleted" + activeForm?: string // Current form/template + blocks?: string[] // Tasks this blocks + blockedBy?: string[] // Tasks blocking this + owner?: string // Agent/session metadata?: Record - repoURL?: string - parentID?: string - threadID?: string + repoURL?: string // Associated repository + parentID?: string // Parent task ID + threadID?: string // Session ID (auto-recorded) } ``` -## STORAGE UTILITIES +## FILES -| Function | Purpose | -|----------|---------| -| `getTaskDir(config)` | Task storage directory path | -| `resolveTaskListId(config)` | Task list ID (env → config → cwd) | -| `readJsonSafe(path, schema)` | Parse + validate, null on failure | -| `writeJsonAtomic(path, data)` | Atomic write via temp + rename | -| `acquireLock(dirPath)` | File lock with 30s stale threshold | -| `generateTaskId()` | `T-{uuid}` format | -| `findTaskAcrossSessions(config, taskId)` | Locate task in any session | +| File | Purpose | +|------|---------| +| `types.ts` | Task interface + status types | +| `storage.ts` | `readJsonSafe()`, `writeJsonAtomic()`, `acquireLock()`, `generateTaskId()` | +| `session-storage.ts` | Per-session task storage, threadID auto-recording | +| `index.ts` | Barrel exports | -## TODO SYNC +## STORAGE -Automatic bidirectional sync between tasks and OpenCode's todo system. - -| Task Status | Todo Status | -|-------------|-------------| -| `pending` | `pending` | -| `in_progress` | `in_progress` | -| `completed` | `completed` | -| `deleted` | `null` (removed) | - -Sync triggers: `task_create`, `task_update`. - -## ANTI-PATTERNS - -- Direct fs operations (use storage utilities) -- Skipping lock acquisition for writes -- Using old field names (title → subject, dependsOn → blockedBy) +- Location: `.sisyphus/tasks/` directory +- Format: JSON files, one per task +- Atomic writes: temp file → rename +- Locking: file-based lock for concurrent access +- Sync: Changes pushed to OpenCode Todo API after each update diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 1e1b7b34c..5e59103f1 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -1,95 +1,113 @@ -# HOOKS KNOWLEDGE BASE +# src/hooks/ — 41 Lifecycle Hooks + +**Generated:** 2026-02-17 ## OVERVIEW -41 lifecycle hooks intercepting/modifying agent behavior across 7 event types. Three-tier registration: Core (32) → Continuation (7) → Skill (2). +41 hooks across 37 directories + 6 standalone files. Three-tier composition: Core(33) + Continuation(7) + Skill(2). All hooks follow `createXXXHook(deps) → HookFunction` factory pattern. -## STRUCTURE -``` -hooks/ -├── agent-usage-reminder/ # Specialized agent hints (109 lines) -├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines, 29 files) -├── anthropic-effort/ # Effort=max for Opus max variant (56 lines) -├── atlas/ # Main orchestration hook (1976 lines, 17 files) -├── auto-slash-command/ # Detects /command patterns (1134 lines) -├── auto-update-checker/ # Plugin update check (1140 lines, 20 files) -├── background-notification/ # OS notifications (33 lines) -├── category-skill-reminder/ # Category+skill delegation reminders (597 lines) -├── claude-code-hooks/ # settings.json compat (2110 lines) — see AGENTS.md -├── comment-checker/ # Prevents AI slop comments (710 lines) -├── compaction-context-injector/ # Injects context on compaction (128 lines) -├── compaction-todo-preserver/ # Preserves todos during compaction (203 lines) -├── context-window-monitor.ts # Reminds of headroom at 70% (100 lines) -├── delegate-task-retry/ # Retries failed delegations (266 lines) -├── directory-agents-injector/ # Auto-injects AGENTS.md (195 lines) -├── directory-readme-injector/ # Auto-injects README.md (190 lines) -├── edit-error-recovery/ # Recovers from edit failures (188 lines) -├── empty-task-response-detector.ts # Detects empty responses (27 lines) -├── interactive-bash-session/ # Tmux session management (695 lines) -├── keyword-detector/ # ultrawork/search/analyze modes (1665 lines) -├── non-interactive-env/ # Non-TTY handling (483 lines) -├── preemptive-compaction.ts # Auto-compact at 78% usage (108 lines) -├── prometheus-md-only/ # Planner read-only mode (955 lines) -├── question-label-truncator/ # Truncates labels to 30 chars (199 lines) -├── ralph-loop/ # Self-referential dev loop (1687 lines) -├── rules-injector/ # Conditional .sisyphus/rules injection (1604 lines) -├── session-notification.ts # OS idle notifications (108 lines) -├── session-recovery/ # Auto-recovers from crashes (1279 lines, 14 files) -├── sisyphus-junior-notepad/ # Junior notepad directive (76 lines) -├── start-work/ # Sisyphus work session starter (648 lines) -├── stop-continuation-guard/ # Guards stop continuation (214 lines) -├── subagent-question-blocker/ # Blocks subagent questions (112 lines) -├── task-reminder/ # Task progress reminders (210 lines) -├── task-resume-info/ # Resume info for cancelled tasks (39 lines) -├── tasks-todowrite-disabler/ # Disables TodoWrite when tasks active (202 lines) -├── think-mode/ # Dynamic thinking budget (1365 lines) -├── thinking-block-validator/ # Validates thinking blocks (169 lines) -├── todo-continuation-enforcer/ # Force TODO completion — boulder mechanism (2061 lines) -├── tool-output-truncator.ts # Prevents context bloat (62 lines) -├── unstable-agent-babysitter/ # Monitors unstable behavior (451 lines) -└── write-existing-file-guard/ # Guards against file overwrite (356 lines) -``` +## HOOK TIERS -## EVENT TYPES +### Tier 1: Session Hooks (20) — `create-session-hooks.ts` -| Event | Hook Method | Can Block | Count | -|-------|-------------|-----------|-------| -| UserPromptSubmit | `chat.message` | Yes | 4 | -| ChatParams | `chat.params` | No | 2 | -| PreToolUse | `tool.execute.before` | Yes | 13 | -| PostToolUse | `tool.execute.after` | No | 15 | -| SessionEvent | `event` | No | 17 | -| MessagesTransform | `experimental.chat.messages.transform` | No | 1 | -| Compaction | `onSummarize` | No | 2 | +| Hook | Event | Purpose | +|------|-------|---------| +| 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 | -## BLOCKING HOOKS (8) +### Tier 2: Tool Guard Hooks (9) — `create-tool-guard-hooks.ts` -| Hook | Event | Blocks When | -|------|-------|-------------| -| auto-slash-command | chat.message | Command execution fails | -| keyword-detector | chat.message | Keyword injection fails | -| non-interactive-env | tool.execute.before | Interactive command in non-TTY | -| prometheus-md-only | tool.execute.before | Write outside .sisyphus/*.md | -| subagent-question-blocker | tool.execute.before | Question tool in subagent | -| tasks-todowrite-disabler | tool.execute.before | TodoWrite with task system | -| write-existing-file-guard | tool.execute.before | Write to existing file | -| claude-code-hooks | tool.execute.before | Exit code 2 from settings.json hook | +| Hook | Event | Purpose | +|------|-------|---------| +| 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 | +| hashlineReadEnhancer | tool.execute.after | Enhance Read output with line hashes | -## EXECUTION ORDER +### Tier 3: Transform Hooks (4) — `create-transform-hooks.ts` -**UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork -**PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → tasksToDoWriteDisabler → atlasHook -**PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo → taskReminder +| Hook | Event | Purpose | +|------|-------|---------| +| 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 | -## HOW TO ADD +### Tier 4: Continuation Hooks (7) — `create-continuation-hooks.ts` -1. Create `src/hooks/name/` with `index.ts` exporting `createMyHook(ctx)` -2. Add hook name to `HookNameSchema` in `src/config/schema/hooks.ts` -3. Register in appropriate `src/plugin/hooks/create-*-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 | -## ANTI-PATTERNS +### Tier 5: Skill Hooks (2) — `create-skill-hooks.ts` -- **Heavy PreToolUse**: Runs before EVERY tool — keep light -- **Blocking non-critical**: Use PostToolUse warnings instead -- **Redundant injection**: Track injected files to avoid context bloat -- **Direct state mutation**: Use `output.output +=` instead of replacing +| 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 `DONE` 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 diff --git a/src/hooks/claude-code-hooks/AGENTS.md b/src/hooks/claude-code-hooks/AGENTS.md index 46d0d01ab..905cc7b1a 100644 --- a/src/hooks/claude-code-hooks/AGENTS.md +++ b/src/hooks/claude-code-hooks/AGENTS.md @@ -1,55 +1,41 @@ -# CLAUDE CODE HOOKS COMPATIBILITY +# src/hooks/claude-code-hooks/ — Claude Code Compatibility + +**Generated:** 2026-02-17 ## OVERVIEW -Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands defined in settings.json. +~2110 LOC across 19 files. Provides Claude Code settings.json compatibility layer. Parses CC permission rules and maps CC hooks (PreToolUse, PostToolUse) to OpenCode hooks. -**Config Sources** (priority): `.claude/settings.local.json` > `.claude/settings.json` (project) > `~/.claude/settings.json` (global) +## WHAT IT DOES -## STRUCTURE -``` -claude-code-hooks/ -├── index.ts # Barrel export -├── claude-code-hooks-hook.ts # Main factory (22 lines) -├── config.ts # Claude settings.json loader (105 lines) -├── config-loader.ts # Extended plugin config (107 lines) -├── pre-tool-use.ts # PreToolUse hook executor (173 lines) -├── post-tool-use.ts # PostToolUse hook executor (200 lines) -├── user-prompt-submit.ts # UserPromptSubmit executor (125 lines) -├── stop.ts # Stop hook executor (122 lines) -├── pre-compact.ts # PreCompact executor (110 lines) -├── transcript.ts # Tool use recording (235 lines) -├── tool-input-cache.ts # Pre→post input caching (51 lines) -├── todo.ts # Todo integration -├── session-hook-state.ts # Active state tracking (11 lines) -├── types.ts # Hook & IO type definitions (204 lines) -├── plugin-config.ts # Default config constants (12 lines) -└── handlers/ # Event handlers (5 files) - ├── pre-compact-handler.ts - ├── tool-execute-before-handler.ts - ├── tool-execute-after-handler.ts - ├── chat-message-handler.ts - └── session-event-handler.ts +1. Parses Claude Code `settings.json` permission format +2. Maps CC hook types to OpenCode event types +3. Enforces CC permission rules (allow/deny per tool) +4. Supports CC `.claude/settings.json` and `.claude/settings.local.json` + +## CC → OPENCODE HOOK MAPPING + +| CC Hook | OpenCode Event | +|---------|---------------| +| PreToolUse | tool.execute.before | +| PostToolUse | tool.execute.after | +| Notification | event (session.idle) | +| Stop | event (session.idle) | + +## PERMISSION SYSTEM + +CC permissions format: +```json +{ + "permissions": { + "allow": ["Edit", "Write"], + "deny": ["Bash(rm:*)"] + } +} ``` -## HOOK LIFECYCLE +Translated to OpenCode tool restrictions via permission-compat in shared/. -| Event | Timing | Can Block | Context Provided | -|-------|--------|-----------|------------------| -| PreToolUse | Before exec | Yes (exit 2) | sessionId, toolName, toolInput, cwd | -| PostToolUse | After exec | Warn (exit 1) | + toolOutput, transcriptPath | -| UserPromptSubmit | On message | Yes (exit 2) | sessionId, prompt, parts, cwd | -| Stop | Session end | Inject | sessionId, parentSessionId, cwd | -| PreCompact | Before summarize | No | sessionId, cwd | +## FILES -## EXIT CODES - -- `0`: Pass (continue) -- `1`: Warn (continue + system message) -- `2`: Block (abort operation) - -## ANTI-PATTERNS - -- **Heavy PreToolUse**: Runs before EVERY tool — keep scripts fast -- **Blocking non-critical**: Prefer PostToolUse warnings -- **Ignoring exit codes**: Return `2` to block sensitive tools +Key files: `settings-loader.ts` (parse CC settings), `hook-mapper.ts` (CC→OC mapping), `permission-handler.ts` (rule enforcement), `types.ts` (CC type definitions). diff --git a/src/mcp/AGENTS.md b/src/mcp/AGENTS.md index b0a11ce1c..2b06b05b8 100644 --- a/src/mcp/AGENTS.md +++ b/src/mcp/AGENTS.md @@ -1,54 +1,58 @@ -# MCP KNOWLEDGE BASE +# src/mcp/ — 3 Built-in Remote MCPs + +**Generated:** 2026-02-17 ## OVERVIEW -Tier 1 of three-tier MCP system: 3 built-in remote HTTP MCPs. +Tier 1 of the three-tier MCP system. 3 remote HTTP MCPs created via `createBuiltinMcps(disabledMcps, config)`. -**Three-Tier System**: -1. **Built-in** (this directory): websearch, context7, grep_app -2. **Claude Code compat** (`features/claude-code-mcp-loader/`): .mcp.json with `${VAR}` expansion -3. **Skill-embedded** (`features/opencode-skill-loader/`): YAML frontmatter in SKILL.md +## BUILT-IN MCPs -## STRUCTURE -``` -mcp/ -├── index.ts # createBuiltinMcps() factory -├── index.test.ts # Tests -├── websearch.ts # Exa AI / Tavily web search -├── context7.ts # Library documentation -├── grep-app.ts # GitHub code search -└── types.ts # McpNameSchema -``` +| Name | URL | Env Vars | Tools | +|------|-----|----------|-------| +| **websearch** | `mcp.exa.ai` (default) or `mcp.tavily.com` | `EXA_API_KEY` (optional), `TAVILY_API_KEY` (if tavily) | Web search | +| **context7** | `mcp.context7.com/mcp` | `CONTEXT7_API_KEY` (optional) | Library documentation | +| **grep_app** | `mcp.grep.app` | None | GitHub code search | -## MCP SERVERS - -| Name | URL | Auth | Purpose | -|------|-----|------|---------| -| websearch | mcp.exa.ai/mcp (default) or mcp.tavily.com/mcp/ | EXA_API_KEY (optional) / TAVILY_API_KEY (required) | Real-time web search | -| context7 | mcp.context7.com/mcp | CONTEXT7_API_KEY (optional) | Library docs lookup | -| grep_app | mcp.grep.app | None | GitHub code search | - -## CONFIG PATTERN +## REGISTRATION PATTERN ```typescript -export const mcp_name = { +// Static export (context7, grep_app) +export const context7 = { type: "remote" as const, - url: "https://...", + url: "https://mcp.context7.com/mcp", enabled: true, oauth: false as const, - headers?: { ... }, } + +// Factory with config (websearch) +export function createWebsearchConfig(config?: WebsearchConfig): RemoteMcpConfig ``` -## HOW TO ADD +## ENABLE/DISABLE -1. Create `src/mcp/my-mcp.ts` with config object -2. Add conditional check in `createBuiltinMcps()` in `index.ts` -3. Add name to `McpNameSchema` in `types.ts` +```jsonc +// Method 1: disabled_mcps array +{ "disabled_mcps": ["websearch", "context7"] } -## NOTES +// Method 2: enabled flag +{ "mcp": { "websearch": { "enabled": false } } } +``` -- **Remote only**: HTTP/SSE transport, no stdio -- **Disable**: Set `disabled_mcps: ["name"]` in config -- **Exa**: Default provider, works without API key -- **Tavily**: Requires `TAVILY_API_KEY` env var +## THREE-TIER SYSTEM + +| Tier | Source | Mechanism | +|------|--------|-----------| +| 1. Built-in | `src/mcp/` | 3 remote HTTP, created by `createBuiltinMcps()` | +| 2. Claude Code | `.mcp.json` | `${VAR}` expansion via `claude-code-mcp-loader` | +| 3. Skill-embedded | SKILL.md YAML | Managed by `SkillMcpManager` (stdio + HTTP) | + +## FILES + +| File | Purpose | +|------|---------| +| `index.ts` | `createBuiltinMcps()` factory | +| `types.ts` | `McpNameSchema`: "websearch" \| "context7" \| "grep_app" | +| `websearch.ts` | Exa/Tavily provider with config | +| `context7.ts` | Context7 with optional auth header | +| `grep-app.ts` | Grep.app (no auth) | diff --git a/src/plugin-handlers/AGENTS.md b/src/plugin-handlers/AGENTS.md index b8288e33e..cd7786a9a 100644 --- a/src/plugin-handlers/AGENTS.md +++ b/src/plugin-handlers/AGENTS.md @@ -1,65 +1,58 @@ -# PLUGIN-HANDLERS KNOWLEDGE BASE +# src/plugin-handlers/ — 6-Phase Config Loading Pipeline + +**Generated:** 2026-02-17 ## OVERVIEW -Configuration orchestration layer. Runs once at plugin init — transforms raw OpenCode config into resolved agent/tool/permission structures via 6-phase sequential loading. +13 non-test files implementing the `ConfigHandler` — the `config` hook handler. Executes 6 sequential phases to register agents, tools, MCPs, and commands with OpenCode. -## STRUCTURE -``` -plugin-handlers/ -├── config-handler.ts # Main orchestrator (45 lines) — 6-phase loading -├── agent-config-handler.ts # Agent loading pipeline (197 lines) -├── plan-model-inheritance.ts # Plan demotion logic (28 lines) -├── prometheus-agent-config-builder.ts # Prometheus config builder (99 lines) -├── plugin-components-loader.ts # Claude Code plugin discovery (71 lines, 10s timeout) -├── provider-config-handler.ts # Provider config + model context limits cache -├── tool-config-handler.ts # Permission migration (101 lines) -├── mcp-config-handler.ts # Builtin + CC + plugin MCP merge -├── command-config-handler.ts # Command/skill parallel discovery -├── category-config-resolver.ts # Category lookup -├── agent-priority-order.ts # Agent ordering (sisyphus, hephaestus, prometheus, atlas first) -├── plan-model-inheritance.test.ts # 3696 lines of tests -├── config-handler.test.ts # 1061 lines of tests -└── index.ts # Barrel exports -``` +## 6-PHASE PIPELINE -## CONFIG LOADING FLOW (6 phases, sequential) +| Phase | Handler | Purpose | +|-------|---------|---------| +| 1 | `applyProviderConfig` | Cache model context limits, detect anthropic-beta headers | +| 2 | `loadPluginComponents` | Discover Claude Code plugins (10s timeout, error isolation) | +| 3 | `applyAgentConfig` | Load agents from 5 sources, skill discovery, plan demotion | +| 4 | `applyToolConfig` | Agent-specific tool permissions | +| 5 | `applyMcpConfig` | Merge builtin + CC + plugin MCPs | +| 6 | `applyCommandConfig` | Merge commands/skills from 9 parallel sources | -1. `applyProviderConfig` → Cache model context limits, detect anthropic-beta headers -2. `loadPluginComponents` → Discover Claude Code plugins (10s timeout, error isolation) -3. `applyAgentConfig` → Load all agents, sisyphus/prometheus/plan demotion -4. `applyToolConfig` → Agent-specific tool permissions (grep_app, task, teammate) -5. `applyMcpConfig` → Merge builtin + Claude Code + plugin MCPs -6. `applyCommandConfig` → Merge builtin + user + project + opencode commands/skills +## FILES -## PLAN MODEL INHERITANCE - -When `sisyphus_agent.planner_enabled === true`: -1. Prometheus config → extract model settings (model, variant, temperature, ...) -2. Apply user `agents.plan` overrides (plan override wins) -3. Set `mode: "subagent"` (plan becomes subagent, not primary) -4. Strip prompt/permission/description (only model settings inherited) - -## AGENT LOADING ORDER - -1. Builtin agents (sisyphus, hephaestus, oracle, ...) -2. Sisyphus-Junior (if sisyphus enabled) -3. OpenCode-Builder (if `default_builder_enabled`) -4. Prometheus (if `planner_enabled`) -5. User agents → Project agents → Plugin agents → Custom agents - -**Reordered** by `reorderAgentsByPriority()`: sisyphus, hephaestus, prometheus, atlas first. +| File | Lines | Purpose | +|------|-------|---------| +| `config-handler.ts` | ~200 | Main orchestrator, 6-phase sequential | +| `plugin-components-loader.ts` | ~100 | CC plugin discovery (10s timeout) | +| `agent-config-handler.ts` | ~300 | Agent loading + skill discovery from 5 sources | +| `mcp-config-handler.ts` | ~150 | Builtin + CC + plugin MCP merge | +| `command-config-handler.ts` | ~200 | 9 parallel sources for commands/skills | +| `tool-config-handler.ts` | ~100 | Agent-specific tool grants/denials | +| `provider-config-handler.ts` | ~80 | Provider config + model cache | +| `prometheus-agent-config-builder.ts` | ~100 | Prometheus config with model resolution | +| `plan-model-inheritance.ts` | 28 | Plan demotion logic | +| `agent-priority-order.ts` | ~30 | sisyphus, hephaestus, prometheus, atlas first | +| `agent-key-remapper.ts` | ~30 | Agent key → display name | +| `category-config-resolver.ts` | ~40 | User vs default category lookup | +| `index.ts` | ~10 | Barrel exports | ## TOOL PERMISSIONS -| Agent | Special Permissions | -|-------|---------------------| -| librarian | grep_app_* allowed | -| atlas | task, task_*, teammate allowed | -| sisyphus | task, task_*, teammate, question allowed | -| hephaestus | task, question allowed | -| multimodal-looker | Denies task, look_at | +| Agent | Granted | Denied | +|-------|---------|--------| +| Librarian | grep_app_* | — | +| Atlas, Sisyphus, Prometheus | task, task_*, teammate | — | +| Hephaestus | task | — | +| Default (all others) | — | grep_app_*, task_*, teammate, LSP | -## INTEGRATION +## MULTI-LEVEL CONFIG MERGE -Created in `create-managers.ts`, exposed as `config` hook in `plugin-interface.ts`. OpenCode calls it during session init. +``` +User (~/.config/opencode/oh-my-opencode.jsonc) + ↓ deepMerge +Project (.opencode/oh-my-opencode.jsonc) + ↓ Zod defaults +Final Config +``` + +- `agents`, `categories`, `claude_code`: deep merged +- `disabled_*` arrays: Set union diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index b164fa0e6..de4e29be9 100644 --- a/src/shared/AGENTS.md +++ b/src/shared/AGENTS.md @@ -1,97 +1,54 @@ -# SHARED UTILITIES KNOWLEDGE BASE +# src/shared/ — 101 Utility Files in 13 Categories + +**Generated:** 2026-02-17 ## OVERVIEW -96 cross-cutting utilities across 4 subdirectories. Import via barrel: `import { log, deepMerge } from "../../shared"` +Cross-cutting utilities used throughout the plugin. Barrel-exported from `index.ts`. Logger writes to `/tmp/oh-my-opencode.log`. + +## CATEGORY MAP + +| Category | Files | Key Exports | +|----------|-------|-------------| +| **Model Resolution** | 17 | `resolveModel()`, `checkModelAvailability()`, `AGENT_MODEL_REQUIREMENTS` | +| **Tmux Integration** | 11 | `createTmuxSession()`, `spawnPane()`, `closePane()`, server health | +| **Configuration & Paths** | 10 | `resolveOpenCodeConfigDir()`, `getDataPath()`, `parseJSONC()` | +| **Session Management** | 8 | `SessionCursor`, `trackInjectedPath()`, `SessionToolsStore` | +| **Git Worktree** | 7 | `parseGitStatusPorcelain()`, `collectGitDiffStats()`, `formatFileChanges()` | +| **Command Execution** | 7 | `executeCommand()`, `executeHookCommand()`, embedded command registry | +| **Migration** | 6 | `migrateConfigFile()`, AGENT_NAME_MAP, HOOK_NAME_MAP, MODEL_VERSION_MAP | +| **String & Tool Utils** | 6 | `toSnakeCase()`, `normalizeToolName()`, `parseFrontmatter()` | +| **Agent Configuration** | 5 | `getAgentVariant()`, `AGENT_DISPLAY_NAMES`, `AGENT_TOOL_RESTRICTIONS` | +| **OpenCode Integration** | 5 | `injectServerAuth()`, `detectExternalPlugins()`, client accessors | +| **Type Helpers** | 4 | `deepMerge()`, `DynamicTruncator`, `matchPattern()`, `isRecord()` | +| **Misc** | 8 | `log()`, `readFile()`, `extractZip()`, `downloadBinary()`, `findAvailablePort()` | + +## MODEL RESOLUTION PIPELINE -## STRUCTURE ``` -shared/ -├── logger.ts # File logging (/tmp/oh-my-opencode.log) — 62 imports -├── dynamic-truncator.ts # Token-aware context window management (202 lines) -├── model-resolver.ts # 3-step resolution entry point (65 lines) -├── model-availability.ts # Provider model fetching & fuzzy matching (359 lines) -├── model-requirements.ts # Agent/category fallback chains (161 lines) — 11 imports -├── model-resolution-pipeline.ts # Pipeline orchestration (176 lines) -├── model-resolution-types.ts # Resolution request/provenance types -├── model-sanitizer.ts # Model name sanitization -├── model-name-matcher.ts # Model name matching (91 lines) -├── model-suggestion-retry.ts # Suggest models on failure (144 lines) -├── model-cache-availability.ts # Cache availability checking -├── fallback-model-availability.ts # Fallback model logic (67 lines) -├── available-models-fetcher.ts # Fetch models from providers (114 lines) -├── models-json-cache-reader.ts # Read models.json cache -├── provider-models-cache-model-reader.ts # Provider cache reader -├── connected-providers-cache.ts # Provider caching (196 lines) -├── system-directive.ts # Unified message prefix & types (61 lines) — 11 imports -├── session-utils.ts # Session cursor, orchestrator detection -├── session-cursor.ts # Message cursor tracking (85 lines) -├── session-injected-paths.ts # Injected file path tracking -├── permission-compat.ts # Tool restriction enforcement (87 lines) — 9 imports -├── agent-tool-restrictions.ts # Tool restriction definitions -├── agent-variant.ts # Agent variant from config (91 lines) -├── agent-display-names.ts # Agent display name mapping -├── first-message-variant.ts # First message variant types -├── opencode-config-dir.ts # ~/.config/opencode resolution (138 lines) -├── claude-config-dir.ts # ~/.claude resolution -├── data-path.ts # XDG-compliant storage (47 lines) — 11 imports -├── jsonc-parser.ts # JSONC with comment support (66 lines) -├── frontmatter.ts # YAML frontmatter extraction (31 lines) — 10 imports -├── deep-merge.ts # Recursive merge (proto-pollution safe, MAX_DEPTH=50) -├── shell-env.ts # Cross-platform shell environment (111 lines) -├── opencode-version.ts # Semantic version comparison (80 lines) -├── external-plugin-detector.ts # Plugin conflict detection (137 lines) -├── opencode-server-auth.ts # Authentication utilities (190 lines) -├── safe-create-hook.ts # Hook error wrapper (24 lines) -├── pattern-matcher.ts # Pattern matching (40 lines) -├── file-utils.ts # File operations (34 lines) — 9 imports -├── file-reference-resolver.ts # File reference resolution (85 lines) -├── snake-case.ts # Case conversion (44 lines) -├── tool-name.ts # Tool naming conventions -├── port-utils.ts # Port management (48 lines) -├── zip-extractor.ts # ZIP extraction (83 lines) -├── binary-downloader.ts # Binary download (60 lines) -├── command-executor/ # Shell execution (6 files, 213 lines) -├── git-worktree/ # Git status/diff parsing (8 files, 311 lines) -├── migration/ # Legacy config migration (5 files, 341 lines) -│ ├── config-migration.ts # Migration orchestration (133 lines) -│ ├── agent-names.ts # Agent name mapping (70 lines) -│ ├── hook-names.ts # Hook name mapping (36 lines) -│ └── model-versions.ts # Model version migration (49 lines) -└── tmux/ # Tmux TUI integration (12 files, 427 lines) - └── tmux-utils/ # Pane spawn, close, replace, layout, health +resolveModel(input) + 1. Override: UI-selected model (primary agents only) + 2. Category default: From category config + 3. Provider fallback: AGENT_MODEL_REQUIREMENTS chains + 4. System default: Ultimate fallback ``` +Key files: `model-resolver.ts` (entry), `model-resolution-pipeline.ts` (orchestration), `model-requirements.ts` (fallback chains), `model-name-matcher.ts` (fuzzy matching). + +## MIGRATION SYSTEM + +Automatically transforms legacy config on load: +- `agent-names.ts`: Old agent names → new (e.g., `junior` → `sisyphus-junior`) +- `hook-names.ts`: Old hook names → new +- `model-versions.ts`: Old model IDs → current +- `agent-category.ts`: Legacy agent configs → category system + ## MOST IMPORTED -| Utility | Imports | Purpose | -|---------|---------|---------| -| logger.ts | 62 | Background task visibility | -| data-path.ts | 11 | XDG storage resolution | -| model-requirements.ts | 11 | Agent fallback chains | -| system-directive.ts | 11 | System message filtering | -| frontmatter.ts | 10 | YAML metadata extraction | -| permission-compat.ts | 9 | Tool restrictions | -| file-utils.ts | 9 | File operations | -| dynamic-truncator.ts | 7 | Token-aware truncation | - -## KEY PATTERNS - -**3-Step Model Resolution** (Override → Fallback → Default): -1. **Override**: UI-selected or user-configured model -2. **Fallback**: Provider/model chain with availability checking -3. **Default**: System fallback when no matches found - -**System Directive Filtering**: -```typescript -if (isSystemDirective(message)) return // Skip system-generated -const directive = createSystemDirective("TODO CONTINUATION") -``` - -## ANTI-PATTERNS - -- **Raw JSON.parse**: Use `jsonc-parser.ts` for comment support -- **Hardcoded paths**: Use `opencode-config-dir.ts` or `data-path.ts` -- **console.log**: Use `logger.ts` for background task visibility -- **Unbounded output**: Use `dynamic-truncator.ts` to prevent overflow -- **Manual version check**: Use `opencode-version.ts` for semver safety +| Utility | Import Count | Purpose | +|---------|-------------|---------| +| `logger.ts` | 62 | `/tmp/oh-my-opencode.log` | +| `data-path.ts` | 11 | XDG storage resolution | +| `model-requirements.ts` | 11 | Agent fallback chains | +| `system-directive.ts` | 11 | System message filtering | +| `frontmatter.ts` | 10 | YAML metadata extraction | diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index 6c8731caf..458976500 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -1,83 +1,109 @@ -# TOOLS KNOWLEDGE BASE +# src/tools/ — 26 Tools Across 14 Directories + +**Generated:** 2026-02-17 ## OVERVIEW -26 tools across 14 directories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent). +26 tools registered via `createToolRegistry()`. Two patterns: factory functions (`createXXXTool`) for 19 tools, direct `ToolDefinition` for 7 (LSP + interactive_bash). -## STRUCTURE -``` -tools/ -├── delegate-task/ # Category routing (constants.ts 569 lines, tools.ts 213 lines) -├── task/ # 4 tools: create, list, get, update (task-create.ts, task-list.ts, task-get.ts, task-update.ts) -├── lsp/ # 6 LSP tools: goto_definition, find_references, symbols, diagnostics, prepare_rename, rename -├── ast-grep/ # 2 tools: search, replace (25 languages) -├── grep/ # Content search (60s timeout, 10MB limit) -├── glob/ # File pattern matching (60s timeout, 100 file limit) -├── session-manager/ # 4 tools: list, read, search, info -├── call-omo-agent/ # Direct agent invocation (explore/librarian) -├── background-task/ # background_output, background_cancel -├── interactive-bash/ # Tmux session management (135 lines) -├── look-at/ # Multimodal PDF/image analysis (156 lines) -├── skill/ # Skill execution with MCP support (211 lines) -├── skill-mcp/ # MCP tool/resource/prompt operations (182 lines) -└── slashcommand/ # Slash command dispatch -``` +## TOOL CATALOG -## TOOL INVENTORY +### Task Management (4) -| Tool | Category | Pattern | Key Logic | -|------|----------|---------|-----------| -| `task_create` | Task | Factory | Auto-generated T-{uuid} ID, threadID recording, dependency management | -| `task_list` | Task | Factory | Active tasks with summary (excludes completed/deleted), filters unresolved blockers | -| `task_get` | Task | Factory | Full task object by ID | -| `task_update` | Task | Factory | Status/field updates, additive addBlocks/addBlockedBy for dependencies | -| `task` | Delegation | Factory | Category routing with skill injection, background execution | -| `call_omo_agent` | Agent | Factory | Direct explore/librarian invocation | -| `background_output` | Background | Factory | Retrieve background task result (block, timeout, full_session) | -| `background_cancel` | Background | Factory | Cancel running/all background tasks | -| `lsp_goto_definition` | LSP | Direct | Jump to symbol definition | -| `lsp_find_references` | LSP | Direct | Find all usages across workspace | -| `lsp_symbols` | LSP | Direct | Document or workspace symbol search | -| `lsp_diagnostics` | LSP | Direct | Get errors/warnings from language server | -| `lsp_prepare_rename` | LSP | Direct | Validate rename is possible | -| `lsp_rename` | LSP | Direct | Rename symbol across workspace | -| `ast_grep_search` | Search | Factory | AST-aware code search (25 languages) | -| `ast_grep_replace` | Search | Factory | AST-aware code replacement (dry-run default) | -| `grep` | Search | Factory | Regex content search with safety limits | -| `glob` | Search | Factory | File pattern matching | -| `session_list` | Session | Factory | List all sessions | -| `session_read` | Session | Factory | Read session messages with filters | -| `session_search` | Session | Factory | Search across sessions | -| `session_info` | Session | Factory | Session metadata and stats | -| `interactive_bash` | System | Direct | Tmux session management | -| `look_at` | System | Factory | Multimodal PDF/image analysis via dedicated agent | -| `skill` | Skill | Factory | Load skill instructions with MCP support | -| `skill_mcp` | Skill | Factory | Call MCP tools/resources/prompts from skill-embedded servers | -| `slashcommand` | Command | Factory | Slash command dispatch with argument substitution | +| Tool | Factory | Parameters | +|------|---------|------------| +| `task_create` | `createTaskCreateTool` | subject, description, blockedBy, blocks, metadata, parentID | +| `task_list` | `createTaskList` | (none) | +| `task_get` | `createTaskGetTool` | id | +| `task_update` | `createTaskUpdateTool` | id, subject, description, status, addBlocks, addBlockedBy, owner, metadata | -## DELEGATION SYSTEM (delegate-task) +### Delegation (1) -8 built-in categories with domain-optimized models: +| Tool | Factory | Parameters | +|------|---------|------------| +| `task` | `createDelegateTask` | description, prompt, category, subagent_type, run_in_background, session_id, load_skills, command | + +**8 Built-in Categories**: visual-engineering, ultrabrain, deep, artistry, quick, unspecified-low, unspecified-high, writing + +### Agent Invocation (1) + +| Tool | Factory | Parameters | +|------|---------|------------| +| `call_omo_agent` | `createCallOmoAgent` | description, prompt, subagent_type, run_in_background, session_id | + +### Background Tasks (2) + +| Tool | Factory | Parameters | +|------|---------|------------| +| `background_output` | `createBackgroundOutput` | task_id, block, timeout, full_session, include_thinking, message_limit | +| `background_cancel` | `createBackgroundCancel` | taskId, all | + +### LSP Refactoring (6) — Direct ToolDefinition + +| Tool | Parameters | +|------|------------| +| `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) + +| Tool | Factory | Parameters | +|------|---------|------------| +| `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) + +| Tool | Factory | Parameters | +|------|---------|------------| +| `session_list` | `createSessionManagerTools` | (none) | +| `session_read` | `createSessionManagerTools` | session_id, include_todos, limit | +| `session_search` | `createSessionManagerTools` | query, session_id, case_sensitive, limit | +| `session_info` | `createSessionManagerTools` | session_id | + +### Skill/Command (3) + +| Tool | Factory | Parameters | +|------|---------|------------| +| `skill` | `createSkillTool` | name | +| `skill_mcp` | `createSkillMcpTool` | mcp_name, tool_name/resource_name/prompt_name, arguments, grep | +| `slashcommand` | `createSlashcommandTool` | command, user_message | + +### 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-pro | UI/UX, design, styling | -| `ultrabrain` | gpt-5.3-codex xhigh | Deep logic, architecture | -| `deep` | gpt-5.3-codex medium | Autonomous problem-solving | -| `artistry` | gemini-3-pro high | Creative, unconventional | -| `quick` | claude-haiku-4-5 | Trivial tasks | -| `unspecified-low` | claude-sonnet-4-5 | Moderate effort | -| `unspecified-high` | claude-opus-4-6 max | High effort | -| `writing` | kimi-k2p5 | Documentation, prose | +| visual-engineering | gemini-3-pro | Frontend, UI/UX | +| ultrabrain | gpt-5.3-codex xhigh | Hard logic | +| deep | gpt-5.3-codex medium | Autonomous problem-solving | +| artistry | gemini-3-pro high | Creative approaches | +| quick | claude-haiku-4-5 | Trivial tasks | +| unspecified-low | claude-sonnet-4-5 | Moderate effort | +| unspecified-high | claude-opus-4-6 max | High effort | +| writing | kimi-k2p5 | Documentation | -## HOW TO ADD +## HOW TO ADD A TOOL -1. Create `src/tools/[name]/` with index.ts, tools.ts, types.ts, constants.ts -2. Static tools → `builtinTools` export, Factory → separate export -3. Register in `src/plugin/tool-registry.ts` - -## NAMING - -- **Tool names**: snake_case (`lsp_goto_definition`) -- **Functions**: camelCase (`createDelegateTask`) -- **Directories**: kebab-case (`delegate-task/`) +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`