release: v2.13.0

- Extract createSlashcommandTool factory with SlashcommandToolOptions
- Export discoverCommandsSync for external use
- Move description building to lazy evaluation with caching
- Support pre-warming cache with provided commands and skills
- Simplify tool initialization in plugin with new factory approach

This allows the slashcommand tool to be instantiated with custom options
while maintaining backward compatibility through lazy loading.

🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)

.github/workflows/lint-workflows.yml

@@ -0,0 +1,22 @@
+name: Lint Workflows
+
+on:
+  push:
+    paths:
+      - '.github/workflows/**'
+  pull_request:
+    paths:
+      - '.github/workflows/**'
+
+jobs:
+  actionlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install actionlint
+        run: |
+          bash <(curl -sSL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.10/scripts/download-actionlint.bash)
+
+      - name: Run actionlint
+        run: ./actionlint -color -shellcheck=""

.github/workflows/sisyphus-agent.yml

@@ -15,13 +15,13 @@ jobs:
   agent:
     runs-on: ubuntu-latest
     # @sisyphus-dev-ai mention only (maintainers, exclude self)
-    if: |
+    if: >-
       github.event_name == 'workflow_dispatch' ||
-      (contains(github.event.comment.body, '@sisyphus-dev-ai') &&
-       github.event.comment.user.login != 'sisyphus-dev-ai' &&
-       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
+      (github.event_name == 'issue_comment' &&
+       contains(github.event.comment.body || '', '@sisyphus-dev-ai') &&
+       (github.event.comment.user.login || '') != 'sisyphus-dev-ai' &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association || ''))
 
-    # Minimal default GITHUB_TOKEN permissions
     permissions:
       contents: read
 
@@ -156,6 +156,71 @@ jobs:
 
           OMO_JSON=~/.config/opencode/oh-my-opencode.json
           PROMPT_APPEND=$(cat << 'PROMPT_EOF'
+          <ultrawork-mode>
+          [CODE RED] Maximum precision required. Ultrathink before acting.
+
+          YOU MUST LEVERAGE ALL AVAILABLE AGENTS TO THEIR FULLEST POTENTIAL.
+          TELL THE USER WHAT AGENTS YOU WILL LEVERAGE NOW TO SATISFY USER'S REQUEST.
+
+          ## AGENT UTILIZATION PRINCIPLES (by capability, not by name)
+          - **Codebase Exploration**: Spawn exploration agents using BACKGROUND TASKS for file patterns, internal implementations, project structure
+          - **Documentation & References**: Use librarian-type agents via BACKGROUND TASKS for API references, examples, external library docs
+          - **Planning & Strategy**: For implementation tasks, spawn a dedicated planning agent for work breakdown (not needed for simple questions/investigations)
+          - **High-IQ Reasoning**: Leverage specialized agents for architecture decisions, code review, strategic planning
+          - **Frontend/UI Tasks**: Delegate to UI-specialized agents for design and implementation
+
+          ## EXECUTION RULES
+          - **TODO**: Track EVERY step. Mark complete IMMEDIATELY after each.
+          - **PARALLEL**: Fire independent agent calls simultaneously via background_task - NEVER wait sequentially.
+          - **BACKGROUND FIRST**: Use background_task for exploration/research agents (10+ concurrent if needed).
+          - **VERIFY**: Re-read request after completion. Check ALL requirements met before reporting done.
+          - **DELEGATE**: Don't do everything yourself - orchestrate specialized agents for their strengths.
+
+          ## WORKFLOW
+          1. Analyze the request and identify required capabilities
+          2. Spawn exploration/librarian agents via background_task in PARALLEL (10+ if needed)
+          3. Always Use Plan agent with gathered context to create detailed work breakdown
+          4. Execute with continuous verification against original requirements
+
+          ## TDD (if test infrastructure exists)
+
+          1. Write spec (requirements)
+          2. Write tests (failing)
+          3. RED: tests fail
+          4. Implement minimal code
+          5. GREEN: tests pass
+          6. Refactor if needed (must stay green)
+          7. Next feature, repeat
+
+          ## ZERO TOLERANCE FAILURES
+          - **NO Scope Reduction**: Never make "demo", "skeleton", "simplified", "basic" versions - deliver FULL implementation
+          - **NO MockUp Work**: When user asked you to do "port A", you must "port A", fully, 100%. No Extra feature, No reduced feature, no mock data, fully working 100% port.
+          - **NO Partial Completion**: Never stop at 60-80% saying "you can extend this..." - finish 100%
+          - **NO Assumed Shortcuts**: Never skip requirements you deem "optional" or "can be added later"
+          - **NO Premature Stopping**: Never declare done until ALL TODOs are completed and verified
+          - **NO TEST DELETION**: Never delete or skip failing tests to make the build pass. Fix the code, not the tests.
+
+          THE USER ASKED FOR X. DELIVER EXACTLY X. NOT A SUBSET. NOT A DEMO. NOT A STARTING POINT.
+
+          </ultrawork-mode>
+
+          ---
+
+
+          [analyze-mode]
+          ANALYSIS MODE. Gather context before diving deep:
+
+          CONTEXT GATHERING (parallel):
+          - 1-2 explore agents (codebase patterns, implementations)
+          - 1-2 librarian agents (if external library involved)
+          - Direct tools: Grep, AST-grep, LSP for targeted searches
+
+          IF COMPLEX (architecture, multi-system, debugging after 2+ failures):
+          - Consult oracle for strategic guidance
+
+          SYNTHESIZE findings before proceeding.
+
+          ---
 
           ## GitHub Actions Environment
 
@@ -244,14 +309,17 @@ jobs:
             AUTHOR="$COMMENT_AUTHOR"
             COMMENT_ID="$COMMENT_ID_VAL"
 
-            # Check if PR or Issue
-            if gh api "repos/$REPO/issues/${ISSUE_NUM}" | jq -e '.pull_request' > /dev/null; then
+            # Check if PR or Issue and get title
+            ISSUE_DATA=$(gh api "repos/$REPO/issues/${ISSUE_NUM}")
+            TITLE=$(echo "$ISSUE_DATA" | jq -r '.title')
+            if echo "$ISSUE_DATA" | jq -e '.pull_request' > /dev/null; then
               echo "type=pr" >> $GITHUB_OUTPUT
               echo "number=${ISSUE_NUM}" >> $GITHUB_OUTPUT
             else
               echo "type=issue" >> $GITHUB_OUTPUT
               echo "number=${ISSUE_NUM}" >> $GITHUB_OUTPUT
             fi
+            echo "title=${TITLE}" >> $GITHUB_OUTPUT
           fi
 
           echo "comment<<EOF" >> $GITHUB_OUTPUT
@@ -297,15 +365,32 @@ jobs:
           COMMENT_AUTHOR: ${{ steps.context.outputs.author }}
           CONTEXT_TYPE: ${{ steps.context.outputs.type }}
           CONTEXT_NUMBER: ${{ steps.context.outputs.number }}
+          CONTEXT_TITLE: ${{ steps.context.outputs.title }}
           REPO_NAME: ${{ github.repository }}
           DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
         run: |
           export PATH="$HOME/.opencode/bin:$PATH"
 
           PROMPT=$(cat <<'PROMPT_EOF'
+          [analyze-mode]
+          ANALYSIS MODE. Gather context before diving deep:
+
+          CONTEXT GATHERING (parallel):
+          - 1-2 explore agents (codebase patterns, implementations)
+          - 1-2 librarian agents (if external library involved)
+          - Direct tools: Grep, AST-grep, LSP for targeted searches
+
+          IF COMPLEX (architecture, multi-system, debugging after 2+ failures):
+          - Consult oracle for strategic guidance
+
+          SYNTHESIZE findings before proceeding.
+
+          ---
+
           Your username is @sisyphus-dev-ai, mentioned by @AUTHOR_PLACEHOLDER in REPO_PLACEHOLDER.
 
           ## Context
+          - Title: TITLE_PLACEHOLDER
           - Type: TYPE_PLACEHOLDER
           - Number: #NUMBER_PLACEHOLDER
           - Repository: REPO_PLACEHOLDER
@@ -316,8 +401,42 @@ jobs:
 
           ---
 
-          Write everything using the todo tools.
-          Then investigate and satisfy the request. Only if user requested to you to work explicitely, then use plan agent to plan, todo obsessivley then create a PR to `BRANCH_PLACEHOLDER` branch.
+          ## CRITICAL: First Steps (MUST DO BEFORE ANYTHING ELSE)
+
+          ### [CODE RED] MANDATORY CONTEXT READING - ZERO EXCEPTIONS
+
+          **YOU MUST READ ALL CONTENT. NOT SOME. NOT MOST. ALL.**
+
+          1. **READ FULL CONVERSATION** - Execute ALL commands below before ANY other action:
+             - **Issues**: `gh issue view NUMBER_PLACEHOLDER --comments`
+             - **PRs**: Use ALL THREE commands to get COMPLETE context:
+               ```bash
+               gh pr view NUMBER_PLACEHOLDER --comments
+               gh api repos/REPO_PLACEHOLDER/pulls/NUMBER_PLACEHOLDER/comments
+               gh api repos/REPO_PLACEHOLDER/pulls/NUMBER_PLACEHOLDER/reviews
+               ```
+             
+             **WHAT TO EXTRACT FROM THE CONVERSATION:**
+             - The ORIGINAL issue/PR description (first message) - this is often the TRUE requirement
+             - ALL previous attempts and their outcomes
+             - ALL decisions made and their reasoning
+             - ALL feedback, criticism, and rejection reasons
+             - ANY linked issues, PRs, or external references
+             - The EXACT ask from the user who mentioned you
+             
+             **FAILURE TO READ EVERYTHING = GUARANTEED FAILURE**
+             You WILL make wrong assumptions. You WILL repeat past mistakes. You WILL miss critical context.
+
+          2. **CREATE TODOS IMMEDIATELY**: Right after reading, create your todo list using todo tools.
+             - First todo: "Summarize issue/PR context and requirements"
+             - Break down ALL work into atomic, verifiable steps
+             - Plan everything BEFORE starting any work
+
+          ---
+
+
+          Plan everything using todo tools.
+          Then investigate and satisfy the request. Only if user requested to you to work explicitly, then use plan agent to plan, todo obsessively then create a PR to `BRANCH_PLACEHOLDER` branch.
           When done, report the result to the issue/PR with `gh issue comment NUMBER_PLACEHOLDER` or `gh pr comment NUMBER_PLACEHOLDER`.
           PROMPT_EOF
           )
@@ -326,6 +445,7 @@ jobs:
           PROMPT="${PROMPT//REPO_PLACEHOLDER/$REPO_NAME}"
           PROMPT="${PROMPT//TYPE_PLACEHOLDER/$CONTEXT_TYPE}"
           PROMPT="${PROMPT//NUMBER_PLACEHOLDER/$CONTEXT_NUMBER}"
+          PROMPT="${PROMPT//TITLE_PLACEHOLDER/$CONTEXT_TITLE}"
           PROMPT="${PROMPT//BRANCH_PLACEHOLDER/$DEFAULT_BRANCH}"
           PROMPT="${PROMPT//COMMENT_PLACEHOLDER/$USER_COMMENT}"
 

.gitignore

@@ -1,4 +1,5 @@
 # Dependencies
+.sisyphus/
 node_modules/
 
 # Build output

.opencode/command/publish.md

@@ -1,7 +1,6 @@
 ---
 description: Publish oh-my-opencode to npm via GitHub Actions workflow
 argument-hint: <patch|minor|major>
-model: opencode/big-pickle
 ---
 
 <command-instruction>

AGENTS.md

@@ -1,29 +1,29 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2025-12-28T19:26:00+09:00
-**Commit:** 122e918
+**Generated:** 2026-01-02T22:41:22+09:00
+**Commit:** d0694e5
 **Branch:** dev
 
 ## OVERVIEW
 
-OpenCode plugin implementing Claude Code/AmpCode features. Multi-model agent orchestration (GPT-5.2, Claude, Gemini, Grok), LSP tools (11), AST-Grep search, MCP integrations (context7, websearch_exa, grep_app). "oh-my-zsh" for OpenCode.
+OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok), 11 LSP tools, AST-Grep, Claude Code compatibility layer. "oh-my-zsh" for OpenCode.
 
 ## STRUCTURE
 
 ```
 oh-my-opencode/
 ├── src/
-│   ├── agents/        # AI agents (7): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker
-│   ├── hooks/         # 21 lifecycle hooks - see src/hooks/AGENTS.md
-│   ├── tools/         # LSP, AST-Grep, Grep, Glob, etc. - see src/tools/AGENTS.md
-│   ├── mcp/           # MCP servers: context7, websearch_exa, grep_app
-│   ├── features/      # Claude Code compatibility - see src/features/AGENTS.md
+│   ├── agents/        # 7 AI agents - see src/agents/AGENTS.md
+│   ├── hooks/         # 22 lifecycle hooks - see src/hooks/AGENTS.md
+│   ├── tools/         # LSP, AST-Grep, session mgmt - see src/tools/AGENTS.md
+│   ├── features/      # Claude Code compat layer - see src/features/AGENTS.md
+│   ├── auth/          # Google Antigravity OAuth - see src/auth/AGENTS.md
+│   ├── shared/        # Cross-cutting utilities - see src/shared/AGENTS.md
+│   ├── cli/           # CLI installer, doctor - see src/cli/AGENTS.md
+│   ├── mcp/           # MCP configs: context7, grep_app
 │   ├── config/        # Zod schema, TypeScript types
-│   ├── auth/          # Google Antigravity OAuth (antigravity/)
-│   ├── shared/        # Utilities: deep-merge, pattern-matcher, logger, etc.
-│   └── index.ts       # Main plugin entry (OhMyOpenCodePlugin)
+│   └── index.ts       # Main plugin entry (464 lines)
 ├── script/            # build-schema.ts, publish.ts, generate-changelog.ts
-├── assets/            # JSON schema
 └── dist/              # Build output (ESM + .d.ts)
 ```
 
@@ -31,58 +31,67 @@ oh-my-opencode/
 
 | Task | Location | Notes |
 |------|----------|-------|
-| Add agent | `src/agents/` | Create .ts, add to builtinAgents in index.ts, update types.ts |
-| Add hook | `src/hooks/` | Create dir with createXXXHook(), export from index.ts |
-| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to builtinTools |
+| Add agent | `src/agents/` | Create .ts, add to builtinAgents, update types.ts |
+| Add hook | `src/hooks/` | Dir with createXXXHook(), export from index.ts |
+| Add tool | `src/tools/` | Dir with constants/types/tools.ts, add to builtinTools |
 | Add MCP | `src/mcp/` | Create config, add to index.ts |
-| LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) |
-| AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding |
-| Google OAuth | `src/auth/antigravity/` | OAuth plugin for Google models |
-| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes |
+| Add skill | `src/features/builtin-skills/` | Dir with SKILL.md |
+| Config schema | `src/config/schema.ts` | Run `bun run build:schema` after |
 | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
-| Background agents | `src/features/background-agent/` | manager.ts for task management |
-| Interactive terminal | `src/tools/interactive-bash/` | tmux session management |
+
+## TDD (Test-Driven Development)
+
+**MANDATORY for new features and bug fixes.** Follow RED-GREEN-REFACTOR:
+
+```
+1. RED    - Write failing test first (test MUST fail)
+2. GREEN  - Write MINIMAL code to pass (nothing more)
+3. REFACTOR - Clean up while tests stay GREEN
+4. REPEAT - Next test case
+```
+
+| Phase | Action | Verification |
+|-------|--------|--------------|
+| **RED** | Write test describing expected behavior | `bun test` → FAIL (expected) |
+| **GREEN** | Implement minimum code to pass | `bun test` → PASS |
+| **REFACTOR** | Improve code quality, remove duplication | `bun test` → PASS (must stay green) |
+
+**Rules:**
+- NEVER write implementation before test
+- NEVER delete failing tests to "pass" - fix the code
+- One test at a time - don't batch
+- Test file naming: `*.test.ts` alongside source
 
 ## CONVENTIONS
 
-- **Package manager**: Bun only (`bun run`, `bun build`, `bunx`)
+- **Bun only**: `bun run`, `bun test`, `bunx` (NEVER npm/npx)
 - **Types**: bun-types (not @types/node)
-- **Build**: Dual output - `bun build` (ESM) + `tsc --emitDeclarationOnly`
-- **Exports**: Barrel pattern - `export * from "./module"` in index.ts
-- **Directory naming**: kebab-case (`ast-grep/`, `claude-code-hooks/`)
-- **Tool structure**: index.ts, types.ts, constants.ts, tools.ts, utils.ts
-- **Hook pattern**: `createXXXHook(input: PluginInput)` returning event handlers
-- **Test style**: BDD comments `#given`, `#when`, `#then` (same as AAA)
+- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
+- **Exports**: Barrel pattern in index.ts; explicit named exports for tools/hooks
+- **Naming**: kebab-case directories, createXXXHook/createXXXTool factories
+- **Testing**: BDD comments `#given`, `#when`, `#then` (same as AAA); TDD workflow (RED-GREEN-REFACTOR)
+- **Temperature**: 0.1 for code agents, max 0.3
 
-## ANTI-PATTERNS (THIS PROJECT)
+## ANTI-PATTERNS
 
-- **npm/yarn**: Use bun exclusively
-- **@types/node**: Use bun-types
-- **Bash file ops**: Never mkdir/touch/rm/cp/mv for file creation in code
-- **Direct bun publish**: GitHub Actions workflow_dispatch only (OIDC provenance)
-- **Local version bump**: Version managed by CI workflow
-- **Year 2024**: NEVER use 2024 in code/prompts (use current year)
-- **Rush completion**: Never mark tasks complete without verification
-- **Over-exploration**: Stop searching when sufficient context found
-
-## UNIQUE STYLES
-
-- **Platform**: Union type `"darwin" | "linux" | "win32" | "unsupported"`
-- **Optional props**: Extensive `?` for optional interface properties
-- **Flexible objects**: `Record<string, unknown>` for dynamic configs
-- **Error handling**: Consistent try/catch with async/await
-- **Agent tools**: `tools: { include: [...] }` or `tools: { exclude: [...] }`
-- **Temperature**: Most agents use `0.1` for consistency
-- **Hook naming**: `createXXXHook` function convention
+| Category | Forbidden |
+|----------|-----------|
+| Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` |
+| Package Manager | npm, yarn, npx |
+| File Ops | Bash mkdir/touch/rm for code file creation |
+| Publishing | Direct `bun publish`, local version bump |
+| Agent Behavior | High temp (>0.3), broad tool access, sequential agent calls |
+| Hooks | Heavy PreToolUse logic, blocking without reason |
+| Year | 2024 in code/prompts (use current year) |
 
 ## AGENT MODELS
 
 | Agent | Model | Purpose |
 |-------|-------|---------|
 | Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator |
-| oracle | openai/gpt-5.2 | Strategic advisor, code review |
-| librarian | anthropic/claude-sonnet-4-5 | Multi-repo analysis, docs |
-| explore | opencode/grok-code | Fast codebase exploration |
+| oracle | openai/gpt-5.2 | Strategy, code review |
+| librarian | anthropic/claude-sonnet-4-5 | Docs, OSS research |
+| explore | opencode/grok-code | Fast codebase grep |
 | frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation |
 | document-writer | google/gemini-3-pro-preview | Technical docs |
 | multimodal-looker | google/gemini-3-flash | PDF/image analysis |
@@ -93,8 +102,7 @@ oh-my-opencode/
 bun run typecheck      # Type check
 bun run build          # ESM + declarations + schema
 bun run rebuild        # Clean + Build
-bun run build:schema   # Schema only
-bun test               # Run tests
+bun test               # Run tests (380+)
 ```
 
 ## DEPLOYMENT
@@ -102,20 +110,26 @@ bun test               # Run tests
 **GitHub Actions workflow_dispatch only**
 
 1. Never modify package.json version locally
-2. Commit & push changes
-3. Trigger `publish` workflow: `gh workflow run publish -f bump=patch`
+2. Commit & push to dev
+3. Trigger: `gh workflow run publish -f bump=patch|minor|major`
 
-**Critical**: Never `bun publish` directly. Never bump version locally.
+CI auto-commits schema changes on master, maintains rolling `next` draft release on dev.
 
-## CI PIPELINE
+## COMPLEXITY HOTSPOTS
 
-- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master
-- **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish
+| File | Lines | Description |
+|------|-------|-------------|
+| `src/index.ts` | 464 | Main plugin, all hook/tool init |
+| `src/cli/config-manager.ts` | 669 | JSONC parsing, env detection |
+| `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting |
+| `src/tools/lsp/client.ts` | 611 | LSP protocol, JSON-RPC |
+| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 564 | Multi-stage recovery |
+| `src/agents/sisyphus.ts` | 504 | Orchestrator prompt |
 
 ## NOTES
 
-- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`
 - **OpenCode**: Requires >= 1.0.150
-- **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
-- **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)
-- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
+- **Config**: `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`
+- **JSONC**: Config files support comments and trailing commas
+- **Claude Code**: Full compat layer for settings.json hooks, commands, skills, agents, MCPs
+- **Skill MCP**: Skills can embed MCP server configs in YAML frontmatter

CONTRIBUTING.md

@@ -89,7 +89,7 @@ oh-my-opencode/
 │   ├── agents/        # AI agents (OmO, oracle, librarian, explore, etc.)
 │   ├── hooks/         # 21 lifecycle hooks
 │   ├── tools/         # LSP (11), AST-Grep, Grep, Glob, etc.
-│   ├── mcp/           # MCP server integrations (context7, websearch_exa, grep_app)
+│   ├── mcp/           # MCP server integrations (context7, grep_app)
 │   ├── features/      # Claude Code compatibility layers
 │   ├── config/        # Zod schemas and TypeScript types
 │   ├── auth/          # Google Antigravity OAuth

README.ja.md

@@ -2,12 +2,14 @@
 >
 > *「私はエージェントが生成したコードと人間が書いたコードを区別できない、しかしはるかに多くのことを達成できる世界を作り、ソフトウェア革命を起こすことを目指しています。私はこの旅に個人的な時間、情熱、そして資金を注ぎ込んできましたし、これからもそうし続けます。」*
 >
+> [![The Orchestrator is coming](./.github/assets/orchestrator-sisyphus.png)](https://x.com/justsisyphus/status/2006250634354548963)
+> > **オーケストレーターが来ます。今週中に。[Xで通知を受け取る](https://x.com/justsisyphus/status/2006250634354548963)**
+>
 > 一緒に歩みましょう！
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | [Discordコミュニティ](https://discord.gg/PWpXmbhF)に参加して、コントリビューターや`oh-my-opencode`仲間とつながりましょう。 |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PUwSMR9XNk) | [Discordコミュニティ](https://discord.gg/PUwSMR9XNk)に参加して、コントリビューターや`oh-my-opencode`仲間とつながりましょう。 |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | `oh-my-opencode`に関するニュースは私のXアカウントで投稿していましたが、無実の罪で凍結されたため、<br />[@justsisyphus](https://x.com/justsisyphus)が代わりに更新を投稿しています。 |
-> | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | [スポンサーになって](https://github.com/sponsors/code-yeongyu) `oh-my-opencode` の開発を応援してください。皆さまのご支援がこのプロジェクトを成長させます。 |
 
 <!-- <CENTERED SECTION FOR GITHUB DISPLAY> -->
 
@@ -46,6 +48,11 @@
 
 > "Oh My Opencodeを使って、たった1日で8000個のeslint警告を解消しました" — [Jacob Ferrari](https://x.com/jacobferrari_/status/2003258761952289061)
 
+> "Ohmyopencodeとralph loopを使って、一晩で45,000行のtauriアプリをSaaSウェブアプリに変換しました。インタビュープロンプトから始めて、質問に対する評価と推奨を求めました。作業する様子を見ているのは驚きでしたし、朝起きたらほぼ完成したウェブサイトがありました！" - [James Hargis](https://x.com/hargabyte/status/2007299688261882202)
+
+> "今週末はopen code、oh my opencode、supermemoryでマインクラフト/ソウルライクな何かを作る実験をしています。"
+> "昼食後の散歩に行く間に、しゃがみアニメーションを追加するよう頼みました。[動画]" - [MagiMetal](https://x.com/MagiMetal/status/2005374704178373023)
+
 > "これをコアに取り入れて彼を採用すべきです。マジで。本当に、本当に、本当に良いです" — Henning Kilset
 
 > "@yeon_gyu_kimを説得できるなら雇うべきです。彼はopencodeに革命を起こしました" — [mysticaltech](https://x.com/mysticaltech/status/2001858758608376079)
@@ -56,6 +63,8 @@
 
 > "Oh My Opencodeは頂点に立っています、敵はいません" — [RyanOnThePath](https://x.com/RyanOnThePath/status/2001438321252118548)
 
+> "Oh My OpenCode Is Actually Insane" - [YouTube - Darren Builds AI](https://www.youtube.com/watch?v=G_Snfh2M41M)
+
 > "シジフォスという名前自体が美しいじゃないですか?" — Sigrid ([@sigridjin_eth](https://x.com/sigridjin_eth))
 
 ---
@@ -70,6 +79,19 @@
   - [インストール](#インストール)
     - [人間の方へ](#人間の方へ)
     - [LLM エージェントの方へ](#llm-エージェントの方へ)
+    - [ステップ 0: サブスクリプション情報を確認](#ステップ-0-サブスクリプション情報を確認)
+    - [ステップ 1: OpenCode インストール確認](#ステップ-1-opencode-インストール確認)
+    - [ステップ 2: インストーラーを実行](#ステップ-2-インストーラーを実行)
+    - [ステップ 3: 設定確認](#ステップ-3-設定確認)
+    - [ステップ 4: 認証情報の設定](#ステップ-4-認証情報の設定)
+      - [4.1 Anthropic (Claude)](#41-anthropic-claude)
+      - [4.2 Google Gemini (Antigravity OAuth)](#42-google-gemini-antigravity-oauth)
+      - [4.3 OpenAI (ChatGPT Plus/Pro)](#43-openai-chatgpt-pluspro)
+    - [⚠️ 注意](#️-注意)
+    - [セットアップの確認](#セットアップの確認)
+    - [ユーザーに「おめでとうございます！🎉」と伝える](#ユーザーにおめでとうございますと伝える)
+    - [複雑すぎますか？](#複雑すぎますか)
+  - [アンインストール](#アンインストール)
   - [機能](#機能)
     - [Agents: あなたの新しいチームメイト](#agents-あなたの新しいチームメイト)
     - [バックグラウンドエージェント: 本当のチームのように働く](#バックグラウンドエージェント-本当のチームのように働く)
@@ -128,6 +150,12 @@ Windows から Linux に初めて乗り換えた時のこと、自分の思い
   - なぜこれが良いのか、単なるボイラープレートではないのか、具体的に何が良くなるのか聞いてみてください。
   - もしあなたが LLM エージェントなら、このプロジェクトによって今すぐ何が可能になるのか、ユーザーに説明してください。
 
+### 🪄 魔法の言葉：`ultrawork`
+
+**これ全部読みたくない？プロンプトに `ultrawork`（または `ulw`）を入れるだけでOK。**
+
+それだけです。私たちが提供するすべての機能が魔法のように動作します—並列エージェント、バックグラウンドタスク、深い探索、そして完了するまで止まらない実行。エージェントが自動的にすべてを処理します。
+
 ### 読みたい方のために：シジフォスに会う
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -223,8 +251,12 @@ OpenCode がインストールされていない場合は、[OpenCode インス
 
 ```bash
 bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
+# bunx が動作しない場合は npx を使用
+npx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
 ```
 
+> **Ubuntu/Debian ユーザーへの注意**: Snap で Bun をインストールした場合 (`/snap/bin/bun`)、Snap のサンドボックス化により `bunx` が「script not found」エラーで失敗します。代わりに `npx` を使用するか、公式インストーラーで Bun を再インストールしてください: `curl -fsSL https://bun.sh/install | bash`
+
 **例：**
 - すべてのサブスクリプション + max20: `bunx oh-my-opencode install --no-tui --claude=max20 --chatgpt=yes --gemini=yes`
 - Claude のみ（max20 なし）: `bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no`
@@ -265,7 +297,7 @@ opencode auth login
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-antigravity-auth@1.1.2"
+    "opencode-antigravity-auth@1.2.7"
   ]
 }
 ```
@@ -290,7 +322,7 @@ opencode auth login
 }
 ```
 
-**利用可能なモデル名**: `google/gemini-3-pro-high`, `google/gemini-3-pro-medium`, `google/gemini-3-pro-low`, `google/gemini-3-flash`, `google/gemini-3-flash`, `google/gemini-3-flash-lite`, `google/claude-sonnet-4-5`, `google/claude-sonnet-4-5-thinking`, `google/claude-opus-4-5-thinking`, `google/gpt-oss-120b-medium`
+**利用可能なモデル名**: `google/antigravity-gemini-3-pro-high`, `google/antigravity-gemini-3-pro-low`, `google/antigravity-gemini-3-flash`, `google/antigravity-claude-sonnet-4-5`, `google/antigravity-claude-sonnet-4-5-thinking-low`, `google/antigravity-claude-sonnet-4-5-thinking-medium`, `google/antigravity-claude-sonnet-4-5-thinking-high`, `google/antigravity-claude-opus-4-5-thinking-low`, `google/antigravity-claude-opus-4-5-thinking-medium`, `google/antigravity-claude-opus-4-5-thinking-high`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview`, `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
 
 その後、認証を行います：
 
@@ -313,26 +345,19 @@ opencode auth login
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-openai-codex-auth@4.1.1"
+    "opencode-openai-codex-auth@4.3.0"
   ]
 }
 ```
 
-**重要**: 現在、公式 npm パッケージに 400 エラー (`"No tool call found for function call output with call_id"`) を引き起こすバグがあります。修正版がリリースされるまでは、**ホットフィックスブランチの使用を推奨します**。`~/.config/opencode/package.json` を修正してください：
+##### モデル設定
 
-```json
-{
-  "dependencies": {
-    "opencode-openai-codex-auth": "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
-  }
-}
-```
-
-その後、`cd ~/.config/opencode && bun i` を実行してください。`opencode.json` ではバージョン指定なしで `"opencode-openai-codex-auth"` として使用します（`@4.1.0` は除外）。
-
-#### 4.3.1 モデル設定
 `opencode.json` に完全なモデル設定も構成する必要があります。
-[opencode-openai-codex-auth ドキュメント](https://github.com/numman-ali/opencode-openai-codex-auth)を読み、[`config/full-opencode.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/full-opencode.json) から provider/models 設定をコピーして、ユーザーの既存のセットアップを壊さないよう慎重にマージしてください。
+[opencode-openai-codex-auth ドキュメント](https://github.com/numman-ali/opencode-openai-codex-auth)を読み、[`config/opencode-modern.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-modern.json)（OpenCode v1.0.210+）または [`config/opencode-legacy.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-legacy.json)（旧バージョン）から provider/models 設定をコピーして、ユーザーの既存のセットアップを壊さないよう慎重にマージしてください。
+
+**利用可能なモデル**: `openai/gpt-5.2`, `openai/gpt-5.2-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.1`
+
+**Variants** (OpenCode v1.0.210+): `--variant=<none|low|medium|high|xhigh>` オプションで推論強度を制御できます。
 
 その後、認証を行います：
 
@@ -531,7 +556,6 @@ OpenCode セッション履歴をナビゲートおよび検索するための
     ```
 - **Online**: プロジェクトのルールがすべてではありません。拡張機能のための内蔵 MCP を提供します：
   - **context7**: ライブラリの最新公式ドキュメントを取得
-  - **websearch_exa**: Exa AI を活用したリアルタイムウェブ検索
   - **grep_app**: 数百万の公開 GitHub リポジトリから超高速コード検索（実装例を探すのに最適）
 
 #### マルチモーダルを活用し、トークンは節約する
@@ -623,7 +647,7 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 
 | トグル     | `false` の場合、ロードが無効になるパス                                                | 影響を受けないもの                                    |
 | ---------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | 内蔵 MCP (context7, websearch_exa)                    |
+| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | 内蔵 MCP (context7, grep_app)                         |
 | `commands` | `~/.claude/commands/*.md`, `./.claude/commands/*.md`                                  | `~/.config/opencode/command/`, `./.opencode/command/` |
 | `skills`   | `~/.claude/skills/*/SKILL.md`, `./.claude/skills/*/SKILL.md`                          | -                                                     |
 | `agents`   | `~/.claude/agents/*.md`, `./.claude/agents/*.md`                                      | 内蔵エージェント (oracle, librarian 等)               |
@@ -660,6 +684,10 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 - **Empty Message Sanitizer**: 空のチャットメッセージによるAPIエラーを防止します。送信前にメッセージ内容を自動的にサニタイズします。
 - **Grep Output Truncator**: grep は山のようなテキストを返すことがあります。残りのコンテキストウィンドウに応じて動的に出力を切り詰めます—50% の余裕を維持し、最大 50k トークンに制限します。
 - **Tool Output Truncator**: 同じ考え方をより広範囲に適用します。Grep、Glob、LSP ツール、AST-grep の出力を切り詰めます。一度の冗長な検索がコンテキスト全体を食いつぶすのを防ぎます。
+- **Preemptive Compaction**: トークン制限に達する前にセッションを事前にコンパクションします。コンテキストウィンドウ使用率85%で実行されます。**デフォルトで有効。** `disabled_hooks: ["preemptive-compaction"]`で無効化できます。
+- **Compaction Context Injector**: セッションコンパクション中に重要なコンテキスト（AGENTS.md、現在のディレクトリ情報）を保持し、重要な状態を失わないようにします。
+- **Thinking Block Validator**: thinking ブロックを検証し、適切なフォーマットを確保し、不正な thinking コンテンツによる API エラーを防ぎます。
+- **Claude Code Hooks**: Claude Code の settings.json からフックを実行します - これは PreToolUse/PostToolUse/UserPromptSubmit/Stop フックを実行する互換性レイヤーです。
 
 ## 設定
 
@@ -755,7 +783,19 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 }
 ```
 
-各エージェントでサポートされるオプション：`model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`。
+各エージェントでサポートされるオプション：`model`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`。
+
+`prompt_append` を使用すると、デフォルトのシステムプロンプトを置き換えずに追加の指示を付け加えられます：
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "Emacs Lisp のドキュメント検索には常に elisp-dev-mcp を使用してください。"
+    }
+  }
+}
+```
 
 `Sisyphus` (メインオーケストレーター) と `build` (デフォルトエージェント) も同じオプションで設定をオーバーライドできます。
 
@@ -800,7 +840,7 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 有効時（デフォルト）、Sisyphus はオプションの特殊エージェントを備えた強力なオーケストレーターを提供します：
 
 - **Sisyphus**: プライマリオーケストレーターエージェント (Claude Opus 4.5)
-- **Builder-Sisyphus**: OpenCode のデフォルトビルドエージェント（SDK 制限により名前変更、デフォルトで無効）
+- **OpenCode-Builder**: OpenCode のデフォルトビルドエージェント（SDK 制限により名前変更、デフォルトで無効）
 - **Planner-Sisyphus**: OpenCode のデフォルトプランエージェント（SDK 制限により名前変更、デフォルトで有効）
 
 **設定オプション：**
@@ -816,7 +856,7 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 }
 ```
 
-**例：Builder-Sisyphus を有効化：**
+**例：OpenCode-Builder を有効化：**
 
 ```json
 {
@@ -826,7 +866,7 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 }
 ```
 
-これにより、Sisyphus と並行して Builder-Sisyphus エージェントを有効化できます。Sisyphus が有効な場合、デフォルトのビルドエージェントは常にサブエージェントモードに降格されます。
+これにより、Sisyphus と並行して OpenCode-Builder エージェントを有効化できます。Sisyphus が有効な場合、デフォルトのビルドエージェントは常にサブエージェントモードに降格されます。
 
 **例：すべての Sisyphus オーケストレーションを無効化：**
 
@@ -847,7 +887,7 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
       "model": "anthropic/claude-sonnet-4",
       "temperature": 0.3
     },
-    "Builder-Sisyphus": {
+    "OpenCode-Builder": {
       "model": "anthropic/claude-opus-4"
     },
     "Planner-Sisyphus": {
@@ -860,7 +900,7 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 | オプション                  | デフォルト | 説明                                                                                                                                                         |
 | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `disabled`                  | `false` | `true` の場合、すべての Sisyphus オーケストレーションを無効化し、元の build/plan をプライマリとして復元します。                                                                       |
-| `default_builder_enabled`   | `false` | `true` の場合、Builder-Sisyphus エージェントを有効化します（OpenCode build と同じ、SDK 制限により名前変更）。デフォルトでは無効です。                                                   |
+| `default_builder_enabled`   | `false` | `true` の場合、OpenCode-Builder エージェントを有効化します（OpenCode build と同じ、SDK 制限により名前変更）。デフォルトでは無効です。                                                   |
 | `planner_enabled`           | `true`  | `true` の場合、Planner-Sisyphus エージェントを有効化します（OpenCode plan と同じ、SDK 制限により名前変更）。デフォルトで有効です。                                                       |
 | `replace_plan`              | `true`  | `true` の場合、デフォルトのプランエージェントをサブエージェントモードに降格させます。`false` に設定すると、Planner-Sisyphus とデフォルトのプランの両方を利用できます。                                |
 
@@ -874,23 +914,22 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 }
 ```
 
-利用可能なフック：`todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`
+利用可能なフック：`todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`
 
 **`auto-update-checker`と`startup-toast`について**: `startup-toast` フックは `auto-update-checker` のサブ機能です。アップデートチェックは有効なまま起動トースト通知のみを無効化するには、`disabled_hooks` に `"startup-toast"` を追加してください。すべてのアップデートチェック機能（トーストを含む）を無効化するには、`"auto-update-checker"` を追加してください。
 
 ### MCPs
 
-コンテキスト7、Exa、grep.app MCP がデフォルトで有効になっています。
+Context7、grep.app MCP がデフォルトで有効になっています。
 
 - **context7**: ライブラリの最新公式ドキュメントを取得
-- **websearch_exa**: Exa AI を活用したリアルタイムウェブ検索
 - **grep_app**: [grep.app](https://grep.app) を通じて数百万の公開 GitHub リポジトリから超高速コード検索
 
 不要であれば、`~/.config/opencode/oh-my-opencode.json` または `.opencode/oh-my-opencode.json` の `disabled_mcps` を使用して無効化できます：
 
 ```json
 {
-  "disabled_mcps": ["context7", "websearch_exa", "grep_app"]
+  "disabled_mcps": ["context7", "grep_app"]
 }
 ```
 
@@ -926,7 +965,7 @@ OpenCode でサポートされるすべての LSP 構成およびカスタム設
 ```json
 {
   "experimental": {
-    "preemptive_compaction": true,
+    "preemptive_compaction_threshold": 0.85,
     "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
     "auto_resume": true
@@ -936,8 +975,7 @@ OpenCode でサポートされるすべての LSP 構成およびカスタム設
 
 | オプション                        | デフォルト | 説明                                                                                                                                                                   |
 | --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `preemptive_compaction`           | `false`    | トークン制限に達する前にセッションを事前にコンパクションします。デフォルトでコンテキストウィンドウ使用率80%で実行されます。                                                   |
-| `preemptive_compaction_threshold` | `0.80`     | プリエンプティブコンパクションをトリガーする閾値（0.5-0.95）。`preemptive_compaction`が有効な場合のみ適用されます。                                                          |
+| `preemptive_compaction_threshold` | `0.85`     | プリエンプティブコンパクションをトリガーする閾値（0.5-0.95）。`preemptive-compaction` フックはデフォルトで有効です。このオプションで閾値をカスタマイズできます。                 |
 | `truncate_all_tool_outputs`       | `false`    | ホワイトリストのツール（Grep、Glob、LSP、AST-grep）だけでなく、すべてのツール出力を切り詰めます。Tool output truncator はデフォルトで有効です - `disabled_hooks`で無効化できます。 |
 | `aggressive_truncation`           | `false`    | トークン制限を超えた場合、ツール出力を積極的に切り詰めて制限内に収めます。デフォルトの切り詰めより積極的です。不十分な場合は要約/復元にフォールバックします。                 |
 | `auto_resume`                     | `false`    | thinking block エラーや thinking disabled violation からの回復成功後、自動的にセッションを再開します。最後のユーザーメッセージを抽出して続行します。                        |
@@ -1000,5 +1038,8 @@ OpenCode が Debian / ArchLinux だとしたら、Oh My OpenCode は Ubuntu / [O
 - **Numman Ali** [GitHub](https://github.com/numman-ali) [X](https://x.com/nummanali)
   - 最初のスポンサー
 - **Aaron Iker** [GitHub](https://github.com/aaroniker) [X](https://x.com/aaroniker)
+- **Suyeol Jeon (devxoul)** [GitHub](https://github.com/devxoul)
+  - 私のキャリアをスタートさせてくださった方であり、優れたエージェンティックワークフローをどのように構築できるかについて多大なインスピレーションを与えてくださった方です。優れたチームを作るために優れたシステムをどう設計すべきか多くのことを学び、その学びがこのharnessを作る上で大きな助けとなりました。
+- **Hyerin Won (devwon)** [GitHub](https://github.com/devwon)
 
 *素晴らしいヒーロー画像を作成してくれた [@junhoyeo](https://github.com/junhoyeo) に感謝します*

README.ko.md

@@ -2,12 +2,14 @@
 >
 > *"저는 에이전트가 생성한 코드와 인간이 작성한 코드를 구분할 수 없으면서도, 훨씬 더 많은 것을 달성할 수 있는 세상을 만들어 소프트웨어 혁명을 일으키고자 합니다. 저는 이 여정에 개인적인 시간, 열정, 그리고 자금을 쏟아부었고, 앞으로도 계속 그렇게 할 것입니다."*
 >
+> [![The Orchestrator is coming](./.github/assets/orchestrator-sisyphus.png)](https://x.com/justsisyphus/status/2006250634354548963)
+> > **오케스트레이터가 옵니다. 이번 주에요. [X에서 알림받기](https://x.com/justsisyphus/status/2006250634354548963)**
+>
 > 함께해주세요!
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | [Discord 커뮤니티](https://discord.gg/PWpXmbhF)에서 기여자들과 `oh-my-opencode` 사용자들을 만나보세요. |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PUwSMR9XNk) | [Discord 커뮤니티](https://discord.gg/PUwSMR9XNk)에서 기여자들과 `oh-my-opencode` 사용자들을 만나보세요. |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | `oh-my-opencode` 관련 소식은 제 X 계정에서 올렸었는데, 억울하게 정지당해서 <br />[@justsisyphus](https://x.com/justsisyphus)가 대신 소식을 전하고 있습니다. |
-> | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | [스폰서가 되어](https://github.com/sponsors/code-yeongyu) `oh-my-opencode` 개발을 응원해주세요. 여러분의 후원이 이 프로젝트를 계속 성장시킵니다. |
 
 <!-- <CENTERED SECTION FOR GITHUB DISPLAY> -->
 
@@ -43,6 +45,11 @@
 
 > "Oh My Opencode를 사용해서, 단 하루만에 8000개의 eslint 경고를 해결했습니다" — [Jacob Ferrari](https://x.com/jacobferrari_/status/2003258761952289061)
 
+> "Ohmyopencode와 ralph loop을 사용해서, 하룻밤 만에 45,000줄짜리 tauri 앱을 SaaS 웹앱으로 전환했습니다. 인터뷰 프롬프트로 시작해서, 질문에 대한 평점과 추천을 요청했습니다. 일하는 모습을 지켜보는 것도 놀라웠고, 아침에 일어나니 거의 완성된 웹사이트가 있었습니다!" - [James Hargis](https://x.com/hargabyte/status/2007299688261882202)
+
+> "이번 주말에 open code, oh my opencode와 supermemory로 마인크래프트/소울라이크 같은 괴물을 만들어보고 있습니다."
+> "점심 먹고 산책하러 가는 동안 웅크리기 애니메이션 추가해달라고 시켰습니다. [영상]" - [MagiMetal](https://x.com/MagiMetal/status/2005374704178373023)
+
 > "이걸 코어에 넣고 그를 채용해야 합니다. 진심으로요. 이건 정말, 정말, 정말 좋습니다." — Henning Kilset
 
 > "@yeon_gyu_kim 을 설득할 수 있다면 고용하세요, 이 사람은 opencode를 혁신했습니다." — [mysticaltech](https://x.com/mysticaltech/status/2001858758608376079)
@@ -53,6 +60,8 @@
 
 > "Oh My Opencode는 독보적입니다, 경쟁자가 없습니다" — [RyanOnThePath](https://x.com/RyanOnThePath/status/2001438321252118548)
 
+> "Oh My OpenCode Is Actually Insane" - [YouTube - Darren Builds AI](https://www.youtube.com/watch?v=G_Snfh2M41M)
+
 > "시지푸스 이름 자체가 이쁘잖아요?" — Sigrid ([@sigridjin_eth](https://x.com/sigridjin_eth))
 
 ---
@@ -67,6 +76,19 @@
   - [설치](#설치)
     - [인간인 당신을 위한 설치 가이드](#인간인-당신을-위한-설치-가이드)
     - [LLM Agent 를 위한 설치 가이드](#llm-agent-를-위한-설치-가이드)
+    - [0단계: 구독 정보 확인](#0단계-구독-정보-확인)
+    - [1단계: OpenCode 설치 확인](#1단계-opencode-설치-확인)
+    - [2단계: 설치 프로그램 실행](#2단계-설치-프로그램-실행)
+    - [3단계: 설정 확인](#3단계-설정-확인)
+    - [4단계: 인증정보 설정](#4단계-인증정보-설정)
+      - [4.1 Anthropic (Claude)](#41-anthropic-claude)
+      - [4.2 Google Gemini (Antigravity OAuth)](#42-google-gemini-antigravity-oauth)
+      - [4.3 OpenAI (ChatGPT Plus/Pro)](#43-openai-chatgpt-pluspro)
+    - [⚠️ 주의](#️-주의)
+    - [설정 확인](#설정-확인)
+    - [사용자에게 '축하합니다! 🎉'라고 말하세요](#사용자에게-축하합니다-라고-말하세요)
+    - [너무 복잡한가요?](#너무-복잡한가요)
+  - [언인스톨](#언인스톨)
   - [기능](#기능)
     - [Agents: 당신의 새로운 팀원들](#agents-당신의-새로운-팀원들)
     - [백그라운드 에이전트: 진짜 팀 처럼 일 하도록](#백그라운드-에이전트-진짜-팀-처럼-일-하도록)
@@ -127,6 +149,12 @@ OpenCode 가 낭만이 사라진것같은 오늘날의 시대에, 당신에게
   - 이게 왜 좋고, 그냥 뻔한 셋업이 아닌지, 당장 무엇이 더 좋아지는지 알려달라고 해보세요.
   - 당신이 LLM 에이전트라면, 사용자의 입장에서 이 프로젝트와 함께 당장 어떤것들이 가능해지는지 사용자에게 설명하세요.
 
+### 🪄 마법의 단어: `ultrawork`
+
+**이거 다 읽기 싫으시죠? 프롬프트에 `ultrawork` (또는 `ulw`) 만 넣으세요.**
+
+그게 다입니다. 우리가 제공하는 모든 기능이 마법처럼 작동합니다—병렬 에이전트, 백그라운드 태스크, 깊은 탐색, 그리고 완료될 때까지 멈추지 않는 실행. 에이전트가 알아서 다 합니다.
+
 ### 하지만 읽고 싶은 당신을 위해: 시지푸스를 만나보세요
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -220,8 +248,12 @@ OpenCode가 설치되어 있지 않다면, [OpenCode 설치 가이드](https://o
 
 ```bash
 bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
+# bunx가 작동하지 않으면 npx 사용
+npx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
 ```
 
+> **Ubuntu/Debian 사용자 참고**: Snap으로 Bun을 설치한 경우 (`/snap/bin/bun`), Snap의 샌드박싱으로 인해 `bunx`가 "script not found" 오류와 함께 실패합니다. 대신 `npx`를 사용하거나, 공식 설치 스크립트로 Bun을 재설치하세요: `curl -fsSL https://bun.sh/install | bash`
+
 **예시:**
 - 모든 구독 + max20: `bunx oh-my-opencode install --no-tui --claude=max20 --chatgpt=yes --gemini=yes`
 - Claude만 (max20 없음): `bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no`
@@ -262,7 +294,7 @@ opencode auth login
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-antigravity-auth@1.1.2"
+    "opencode-antigravity-auth@1.2.7"
   ]
 }
 ```
@@ -287,7 +319,7 @@ opencode auth login
 }
 ```
 
-**사용 가능한 모델 이름**: `google/gemini-3-pro-high`, `google/gemini-3-pro-medium`, `google/gemini-3-pro-low`, `google/gemini-3-flash`, `google/gemini-3-flash`, `google/gemini-3-flash-lite`, `google/claude-sonnet-4-5`, `google/claude-sonnet-4-5-thinking`, `google/claude-opus-4-5-thinking`, `google/gpt-oss-120b-medium`
+**사용 가능한 모델 이름**: `google/antigravity-gemini-3-pro-high`, `google/antigravity-gemini-3-pro-low`, `google/antigravity-gemini-3-flash`, `google/antigravity-claude-sonnet-4-5`, `google/antigravity-claude-sonnet-4-5-thinking-low`, `google/antigravity-claude-sonnet-4-5-thinking-medium`, `google/antigravity-claude-sonnet-4-5-thinking-high`, `google/antigravity-claude-opus-4-5-thinking-low`, `google/antigravity-claude-opus-4-5-thinking-medium`, `google/antigravity-claude-opus-4-5-thinking-high`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview`, `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
 
 그 후 인증:
 
@@ -310,26 +342,19 @@ opencode auth login
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-openai-codex-auth@4.1.1"
+    "opencode-openai-codex-auth@4.3.0"
   ]
 }
 ```
 
-**중요**: 현재 공식 npm 패키지에 400 에러(`"No tool call found for function call output with call_id"`)를 유발하는 버그가 있습니다. 수정 버전이 배포될 때까지 **핫픽스 브랜치 사용을 권장합니다**. `~/.config/opencode/package.json`을 수정하세요:
+##### 모델 설정
 
-```json
-{
-  "dependencies": {
-    "opencode-openai-codex-auth": "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
-  }
-}
-```
-
-그 후 `cd ~/.config/opencode && bun i`를 실행하세요. `opencode.json`에서는 버전 없이 `"opencode-openai-codex-auth"`로 사용합니다 (`@4.1.0` 제외).
-
-#### 4.3.1 모델 설정
 `opencode.json`에 전체 모델 설정도 구성해야 합니다.
-[opencode-openai-codex-auth 문서](https://github.com/numman-ali/opencode-openai-codex-auth)를 읽고, [`config/full-opencode.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/full-opencode.json)에서 provider/models 설정을 복사하여, 사용자의 기존 셋업에 영향을 주지 않도록 깊게 고민하여 적절히 통합하세요.
+[opencode-openai-codex-auth 문서](https://github.com/numman-ali/opencode-openai-codex-auth)를 읽고, [`config/opencode-modern.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-modern.json) (OpenCode v1.0.210+) 또는 [`config/opencode-legacy.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-legacy.json) (구버전)에서 provider/models 설정을 복사하여, 사용자의 기존 셋업에 영향을 주지 않도록 깊게 고민하여 적절히 통합하세요.
+
+**사용 가능한 모델**: `openai/gpt-5.2`, `openai/gpt-5.2-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.1`
+
+**Variants** (OpenCode v1.0.210+): `--variant=<none|low|medium|high|xhigh>` 옵션으로 추론 강도를 조절할 수 있습니다.
 
 그 후 인증:
 
@@ -524,7 +549,6 @@ OpenCode 세션 히스토리를 탐색하고 검색하기 위한 도구들입니
     ```
 - **Online**: 프로젝트 규칙이 전부는 아니겠죠. 확장 기능을 위한 내장 MCP를 제공합니다:
   - **context7**: 공식 문서 조회
-  - **websearch_exa**: 실시간 웹 검색
   - **grep_app**: 공개 GitHub 저장소에서 초고속 코드 검색 (구현 예제 찾기에 최적)
 
 #### 멀티모달을 다 활용하면서, 토큰은 덜 쓰도록.
@@ -616,7 +640,7 @@ Oh My OpenCode는 다음 위치의 훅을 읽고 실행합니다:
 
 | 토글       | `false`일 때 로딩 비활성화 경로                                                       | 영향 받지 않음                                        |
 | ---------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | 내장 MCP (context7, websearch_exa)                    |
+| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | 내장 MCP (context7, grep_app)                         |
 | `commands` | `~/.claude/commands/*.md`, `./.claude/commands/*.md`                                  | `~/.config/opencode/command/`, `./.opencode/command/` |
 | `skills`   | `~/.claude/skills/*/SKILL.md`, `./.claude/skills/*/SKILL.md`                          | -                                                     |
 | `agents`   | `~/.claude/agents/*.md`, `./.claude/agents/*.md`                                      | 내장 에이전트 (oracle, librarian 등)                  |
@@ -653,7 +677,7 @@ Oh My OpenCode는 다음 위치의 훅을 읽고 실행합니다:
 - **Empty Message Sanitizer**: 빈 채팅 메시지로 인한 API 오류를 방지합니다. 전송 전 메시지 내용을 자동으로 정리합니다.
 - **Grep Output Truncator**: grep은 산더미 같은 텍스트를 반환할 수 있습니다. 남은 컨텍스트 윈도우에 따라 동적으로 출력을 축소합니다—50% 여유 공간 유지, 최대 50k 토큰.
 - **Tool Output Truncator**: 같은 아이디어, 더 넓은 범위. Grep, Glob, LSP 도구, AST-grep의 출력을 축소합니다. 한 번의 장황한 검색이 전체 컨텍스트를 잡아먹는 것을 방지합니다.
-- **선제적 압축 (Preemptive Compaction)**: 세션 토큰 한계에 도달하기 전에 선제적으로 세션을 압축합니다. 문제가 발생하기 전에 미리 실행됩니다.
+- **선제적 압축 (Preemptive Compaction)**: 세션 토큰 한계에 도달하기 전에 선제적으로 세션을 압축합니다. 컨텍스트 윈도우 사용량 85%에서 실행됩니다. **기본적으로 활성화됨.** `disabled_hooks: ["preemptive-compaction"]`으로 비활성화 가능.
 - **압축 컨텍스트 주입기 (Compaction Context Injector)**: 세션 압축 중에 중요한 컨텍스트(AGENTS.md, 현재 디렉토리 정보 등)를 유지하여 중요한 상태를 잃지 않도록 합니다.
 - **사고 블록 검증기 (Thinking Block Validator)**: 사고(thinking) 블록의 형식이 올바른지 검증하여 잘못된 형식으로 인한 API 오류를 방지합니다.
 - **Claude Code 훅 (Claude Code Hooks)**: Claude Code의 settings.json에 설정된 훅을 실행합니다. PreToolUse/PostToolUse/UserPromptSubmit/Stop 이벤트를 지원하는 호환성 레이어입니다.
@@ -752,7 +776,19 @@ Schema 자동 완성이 지원됩니다:
 }
 ```
 
-각 에이전트에서 지원하는 옵션: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+각 에이전트에서 지원하는 옵션: `model`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+
+`prompt_append`를 사용하면 기본 시스템 프롬프트를 대체하지 않고 추가 지시사항을 덧붙일 수 있습니다:
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "Emacs Lisp 문서 조회 시 항상 elisp-dev-mcp를 사용하세요."
+    }
+  }
+}
+```
 
 `Sisyphus` (메인 오케스트레이터)와 `build` (기본 에이전트)도 동일한 옵션으로 설정을 오버라이드할 수 있습니다.
 
@@ -797,7 +833,7 @@ Schema 자동 완성이 지원됩니다:
 활성화 시 (기본값), Sisyphus는 옵션으로 선택 가능한 특화 에이전트들과 함께 강력한 오케스트레이터를 제공합니다:
 
 - **Sisyphus**: Primary 오케스트레이터 에이전트 (Claude Opus 4.5)
-- **Builder-Sisyphus**: OpenCode 기본 빌드 에이전트 (SDK 제한으로 이름만 변경, 기본적으로 비활성화)
+- **OpenCode-Builder**: OpenCode 기본 빌드 에이전트 (SDK 제한으로 이름만 변경, 기본적으로 비활성화)
 - **Planner-Sisyphus**: OpenCode 기본 플랜 에이전트 (SDK 제한으로 이름만 변경, 기본적으로 활성화)
 
 **설정 옵션:**
@@ -813,7 +849,7 @@ Schema 자동 완성이 지원됩니다:
 }
 ```
 
-**예시: Builder-Sisyphus 활성화하기:**
+**예시: OpenCode-Builder 활성화하기:**
 
 ```json
 {
@@ -823,7 +859,7 @@ Schema 자동 완성이 지원됩니다:
 }
 ```
 
-이렇게 하면 Sisyphus와 함께 Builder-Sisyphus 에이전트를 활성화할 수 있습니다. Sisyphus가 활성화되면 기본 빌드 에이전트는 항상 subagent 모드로 강등됩니다.
+이렇게 하면 Sisyphus와 함께 OpenCode-Builder 에이전트를 활성화할 수 있습니다. Sisyphus가 활성화되면 기본 빌드 에이전트는 항상 subagent 모드로 강등됩니다.
 
 **예시: 모든 Sisyphus 오케스트레이션 비활성화:**
 
@@ -844,7 +880,7 @@ Schema 자동 완성이 지원됩니다:
       "model": "anthropic/claude-sonnet-4",
       "temperature": 0.3
     },
-    "Builder-Sisyphus": {
+    "OpenCode-Builder": {
       "model": "anthropic/claude-opus-4"
     },
     "Planner-Sisyphus": {
@@ -857,7 +893,7 @@ Schema 자동 완성이 지원됩니다:
 | 옵션                        | 기본값   | 설명                                                                                                                                                  |
 | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `disabled`                  | `false` | `true`면 모든 Sisyphus 오케스트레이션을 비활성화하고 원래 build/plan을 primary로 복원합니다.                                                                       |
-| `default_builder_enabled`   | `false` | `true`면 Builder-Sisyphus 에이전트를 활성화합니다 (OpenCode build와 동일, SDK 제한으로 이름만 변경). 기본적으로 비활성화되어 있습니다.                                      |
+| `default_builder_enabled`   | `false` | `true`면 OpenCode-Builder 에이전트를 활성화합니다 (OpenCode build와 동일, SDK 제한으로 이름만 변경). 기본적으로 비활성화되어 있습니다.                                      |
 | `planner_enabled`           | `true`  | `true`면 Planner-Sisyphus 에이전트를 활성화합니다 (OpenCode plan과 동일, SDK 제한으로 이름만 변경). 기본적으로 활성화되어 있습니다.                                          |
 | `replace_plan`              | `true`  | `true`면 기본 플랜 에이전트를 subagent 모드로 강등시킵니다. `false`로 설정하면 Planner-Sisyphus와 기본 플랜을 모두 사용할 수 있습니다.                                        |
 
@@ -871,23 +907,22 @@ Schema 자동 완성이 지원됩니다:
 }
 ```
 
-사용 가능한 훅: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`
+사용 가능한 훅: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`
 
 **`auto-update-checker`와 `startup-toast`에 대한 참고사항**: `startup-toast` 훅은 `auto-update-checker`의 하위 기능입니다. 업데이트 확인은 유지하면서 시작 토스트 알림만 비활성화하려면 `disabled_hooks`에 `"startup-toast"`를 추가하세요. 모든 업데이트 확인 기능(토스트 포함)을 비활성화하려면 `"auto-update-checker"`를 추가하세요.
 
 ### MCPs
 
-기본적으로 Context7, Exa, grep.app MCP 를 지원합니다.
+기본적으로 Context7, grep.app MCP 를 지원합니다.
 
 - **context7**: 라이브러리의 최신 공식 문서를 가져옵니다
-- **websearch_exa**: Exa AI 기반 실시간 웹 검색
 - **grep_app**: [grep.app](https://grep.app)을 통해 수백만 개의 공개 GitHub 저장소에서 초고속 코드 검색
 
 이것이 마음에 들지 않는다면, ~/.config/opencode/oh-my-opencode.json 혹은 .opencode/oh-my-opencode.json 의 `disabled_mcps` 를 사용하여 비활성화할 수 있습니다:
 
 ```json
 {
-  "disabled_mcps": ["context7", "websearch_exa", "grep_app"]
+  "disabled_mcps": ["context7", "grep_app"]
 }
 ```
 
@@ -923,7 +958,7 @@ OpenCode 에서 지원하는 모든 LSP 구성 및 커스텀 설정 (opencode.js
 ```json
 {
   "experimental": {
-    "preemptive_compaction": true,
+    "preemptive_compaction_threshold": 0.85,
     "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
     "auto_resume": true
@@ -933,8 +968,7 @@ OpenCode 에서 지원하는 모든 LSP 구성 및 커스텀 설정 (opencode.js
 
 | 옵션                              | 기본값  | 설명                                                                                                                                                              |
 | --------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `preemptive_compaction`           | `false` | 토큰 제한에 도달하기 전에 세션을 미리 컴팩션합니다. 기본적으로 컨텍스트 윈도우 사용량이 80%일 때 실행됩니다.                                                              |
-| `preemptive_compaction_threshold` | `0.80`  | 선제적 컴팩션을 트리거할 임계값 비율(0.5-0.95). `preemptive_compaction`이 활성화된 경우에만 적용됩니다.                                                                |
+| `preemptive_compaction_threshold` | `0.85`  | 선제적 컴팩션을 트리거할 임계값 비율(0.5-0.95). `preemptive-compaction` 훅은 기본적으로 활성화되어 있으며, 이 옵션으로 임계값을 커스터마이즈할 수 있습니다.                 |
 | `truncate_all_tool_outputs`       | `false` | 화이트리스트 도구(Grep, Glob, LSP, AST-grep)만이 아닌 모든 도구 출력을 잘라냅니다. Tool output truncator는 기본적으로 활성화됩니다 - `disabled_hooks`로 비활성화 가능합니다. |
 | `aggressive_truncation`           | `false` | 토큰 제한을 초과하면 도구 출력을 공격적으로 잘라내어 제한 내에 맞춥니다. 기본 truncation보다 더 공격적입니다. 부족하면 요약/복구로 fallback합니다.                      |
 | `auto_resume`                     | `false` | thinking block 에러나 thinking disabled violation으로부터 성공적으로 복구한 후 자동으로 세션을 재개합니다. 마지막 사용자 메시지를 추출하여 계속합니다.                |
@@ -997,5 +1031,8 @@ OpenCode 를 사용하여 이 프로젝트의 99% 를 작성했습니다. 기능
 - **Numman Ali** [GitHub](https://github.com/numman-ali) [X](https://x.com/nummanali)
   - 첫 번째 스폰서
 - **Aaron Iker** [GitHub](https://github.com/aaroniker) [X](https://x.com/aaroniker)
+- **전수열 (devxoul)** [GitHub](https://github.com/devxoul)
+  - 저의 커리어 시작을 만들어주신분이며, 좋은 에이전틱 워크플로우를 어떻게 만들 수 있을까에 대해 많은 영감을 주신 분입니다. 좋은 팀을 만들기 위해 좋은 시스템을 어떻게 설계 할 수 있을지 많은 배움을 얻었고 그러한 내용들이 이 harness를 만드는데에 큰 도움이 되었습니다.
+- **원혜린 (devwon)** [GitHub](https://github.com/devwon)
 
 *멋진 히어로 이미지를 만들어주신 히어로 [@junhoyeo](https://github.com/junhoyeo) 께 감사드립니다*

README.md

@@ -2,12 +2,14 @@
 >
 > *"I aim to spark a software revolution by creating a world where agent-generated code is indistinguishable from human code, yet capable of achieving vastly more. I have poured my personal time, passion, and funds into this journey, and I will continue to do so."*
 >
+> [![The Orchestrator is coming](./.github/assets/orchestrator-sisyphus.png)](https://x.com/justsisyphus/status/2006250634354548963)
+> > **The Orchestrator is coming. This Week. [Get notified on X](https://x.com/justsisyphus/status/2006250634354548963)**
+>
 > Be with us!
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | Join our [Discord community](https://discord.gg/PWpXmbhF) to connect with contributors and fellow `oh-my-opencode` users. |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PUwSMR9XNk) | Join our [Discord community](https://discord.gg/PUwSMR9XNk) to connect with contributors and fellow `oh-my-opencode` users. |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | News and updates for `oh-my-opencode` used to be posted on my X account. <br /> Since it was suspended mistakenly, [@justsisyphus](https://x.com/justsisyphus) now posts updates on my behalf. |
-> | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | Support the development of `oh-my-opencode` by [becoming a sponsor](https://github.com/sponsors/code-yeongyu). Your contribution helps keep this project alive and growing. |
 
 <!-- <CENTERED SECTION FOR GITHUB DISPLAY> -->
 
@@ -51,6 +53,11 @@ No stupid token consumption massive subagents here. No bloat tools here.
 
 > "Knocked out 8000 eslint warnings with Oh My Opencode, just in a day" — [Jacob Ferrari](https://x.com/jacobferrari_/status/2003258761952289061)
 
+> "I converted a 45k line tauri app into a SaaS web app overnight using Ohmyopencode and ralph loop. Started with interview me prompt, asked it for ratings and recommendations on the questions. It was amazing to watch it work and to wake up this morning to a mostly working website!" - [James Hargis](https://x.com/hargabyte/status/2007299688261882202)
+
+> "Experimenting with open code, oh my opencode and supermemory this weekend to build some minecraft/souls-like abomination."
+> "Asking it to add crouch animations while I go take my post-lunch walk. [Video]" - [MagiMetal](https://x.com/MagiMetal/status/2005374704178373023)
+
 > "You guys should pull this into core and recruit him. Seriously. It's really, really, really good." — Henning Kilset
 
 > "Hire @yeon_gyu_kim if you can convince him, this dude has revolutionized opencode." — [mysticaltech](https://x.com/mysticaltech/status/2001858758608376079)
@@ -61,7 +68,9 @@ No stupid token consumption massive subagents here. No bloat tools here.
 
 > "Oh My Opencode is king of the hill and has no contenders" — [RyanOnThePath](https://x.com/RyanOnThePath/status/2001438321252118548)
 
-> "Isn't the name Sisyphus itself beautiful?" — Sigrid ([@sigridjin_eth](https://x.com/sigridjin_eth))
+> "Oh My OpenCode Is Actually Insane" - [YouTube - Darren Builds AI](https://www.youtube.com/watch?v=G_Snfh2M41M)
+>
+> "Isn't the name Sisyphus beautiful by itself?" — Sigrid ([@sigridjin_eth](https://x.com/sigridjin_eth))
 
 ---
 
@@ -149,6 +158,12 @@ Hand this doc to an agent and let them set it up.
   - Ask why it's good, why it's not just another boilerplate setup, what actually gets better.
   - If you're an LLM agent, explain to the user what becomes possible right now with this project.
 
+### 🪄 The Magic Word: `ultrawork`
+
+**Don't want to read all this? Just include `ultrawork` (or `ulw`) in your prompt.**
+
+That's it. All the features we provide will work like magic—parallel agents, background tasks, deep exploration, and relentless execution until completion. The agent figures out the rest automatically.
+
 ### For Those Who Want to Read: Meet Sisyphus
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -201,8 +216,12 @@ Run the interactive installer:
 
 ```bash
 bunx oh-my-opencode install
+# or use npx if bunx doesn't work
+npx oh-my-opencode install
 ```
 
+> **Note for Ubuntu/Debian users**: If you installed Bun via Snap (`/snap/bin/bun`), `bunx` will fail with "script not found" due to Snap's sandboxing. Either use `npx` instead, or reinstall Bun via the official installer: `curl -fsSL https://bun.sh/install | bash`
+
 Follow the prompts to configure your Claude, ChatGPT, and Gemini subscriptions. After installation, authenticate your providers as instructed.
 
 **Alternative: Let an LLM Agent do it**
@@ -302,7 +321,7 @@ First, add the opencode-antigravity-auth plugin:
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-antigravity-auth@1.1.2"
+    "opencode-antigravity-auth@1.2.7"
   ]
 }
 ```
@@ -327,7 +346,7 @@ The `opencode-antigravity-auth` plugin uses different model names than the built
 }
 ```
 
-**Available model names**: `google/gemini-3-pro-high`, `google/gemini-3-pro-medium`, `google/gemini-3-pro-low`, `google/gemini-3-flash`, `google/gemini-3-flash`, `google/gemini-3-flash-lite`, `google/claude-sonnet-4-5`, `google/claude-sonnet-4-5-thinking`, `google/claude-opus-4-5-thinking`, `google/gpt-oss-120b-medium`
+**Available model names**: `google/antigravity-gemini-3-pro-high`, `google/antigravity-gemini-3-pro-low`, `google/antigravity-gemini-3-flash`, `google/antigravity-claude-sonnet-4-5`, `google/antigravity-claude-sonnet-4-5-thinking-low`, `google/antigravity-claude-sonnet-4-5-thinking-medium`, `google/antigravity-claude-sonnet-4-5-thinking-high`, `google/antigravity-claude-opus-4-5-thinking-low`, `google/antigravity-claude-opus-4-5-thinking-medium`, `google/antigravity-claude-opus-4-5-thinking-high`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview`, `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
 
 Then authenticate:
 
@@ -350,26 +369,19 @@ First, add the opencode-openai-codex-auth plugin:
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-openai-codex-auth@4.1.1"
+    "opencode-openai-codex-auth@4.3.0"
   ]
 }
 ```
 
-**Important**: The official npm package currently has a bug causing 400 errors (`"No tool call found for function call output with call_id"`). **Use the hotfix branch** until fixed. Edit `~/.config/opencode/package.json`:
-
-```json
-{
-  "dependencies": {
-    "opencode-openai-codex-auth": "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
-  }
-}
-```
-
-Then run `cd ~/.config/opencode && bun i`. In `opencode.json`, use `"opencode-openai-codex-auth"` without the version suffix.
-
 ##### Model Configuration
+
 You'll also need full model settings in `opencode.json`.
-Read the [opencode-openai-codex-auth documentation](https://github.com/numman-ali/opencode-openai-codex-auth), copy provider/models config from [`config/full-opencode.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/full-opencode.json), and merge carefully to avoid breaking the user's existing setup.
+Read the [opencode-openai-codex-auth documentation](https://github.com/numman-ali/opencode-openai-codex-auth), copy provider/models config from [`config/opencode-modern.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-modern.json) (for OpenCode v1.0.210+) or [`config/opencode-legacy.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-legacy.json) (for older versions), and merge carefully to avoid breaking the user's existing setup.
+
+**Available models**: `openai/gpt-5.2`, `openai/gpt-5.2-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.1`
+
+**Variants** (OpenCode v1.0.210+): Use `--variant=<none|low|medium|high|xhigh>` for reasoning effort control.
 
 Then authenticate:
 
@@ -563,7 +575,6 @@ These tools enable agents to reference previous conversations and maintain conti
     ```
 - **Online**: Project rules aren't everything. Built-in MCPs for extended capabilities:
   - **context7**: Official documentation lookup
-  - **websearch_exa**: Real-time web search
   - **grep_app**: Ultra-fast code search across public GitHub repos (great for finding implementation examples)
 
 #### Be Multimodal. Save Tokens.
@@ -574,6 +585,26 @@ Instead of the agent reading massive files and bloating context, it internally l
 #### I Removed Their Blockers
 - Replaces built-in grep and glob tools. Default implementation has no timeout—can hang forever.
 
+#### Skill-Embedded MCP Support
+
+Skills can now bring their own MCP servers. Define MCP configurations directly in skill frontmatter or via `mcp.json` files:
+
+```yaml
+---
+description: Browser automation skill
+mcp:
+  playwright:
+    command: npx
+    args: ["-y", "@anthropic-ai/mcp-playwright"]
+---
+```
+
+When you load a skill with embedded MCP, its tools become available automatically. The `skill_mcp` tool lets you invoke these MCP operations with full schema discovery.
+
+**Built-in Skills:**
+- **playwright**: Browser automation, web scraping, testing, and screenshots out of the box
+
+Disable built-in skills via `disabled_skills: ["playwright"]` in your config.
 
 ### Goodbye Claude Code. Hello Oh My OpenCode.
 
@@ -655,7 +686,7 @@ Disable specific Claude Code compatibility features with the `claude_code` confi
 
 | Toggle     | When `false`, stops loading from...                                                   | Unaffected                                            |
 | ---------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | Built-in MCP (context7, websearch_exa)                |
+| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | Built-in MCP (context7, grep_app)                     |
 | `commands` | `~/.claude/commands/*.md`, `./.claude/commands/*.md`                                  | `~/.config/opencode/command/`, `./.opencode/command/` |
 | `skills`   | `~/.claude/skills/*/SKILL.md`, `./.claude/skills/*/SKILL.md`                          | -                                                     |
 | `agents`   | `~/.claude/agents/*.md`, `./.claude/agents/*.md`                                      | Built-in agents (oracle, librarian, etc.)             |
@@ -692,7 +723,7 @@ When agents thrive, you thrive. But I want to help you directly too.
 - **Empty Message Sanitizer**: Prevents API errors from empty chat messages by automatically sanitizing message content before sending.
 - **Grep Output Truncator**: Grep can return mountains of text. This dynamically truncates output based on your remaining context window—keeps 50% headroom, caps at 50k tokens.
 - **Tool Output Truncator**: Same idea, broader scope. Truncates output from Grep, Glob, LSP tools, and AST-grep. Prevents one verbose search from eating your entire context.
-- **Preemptive Compaction**: Compacts session proactively before hitting hard token limits. Runs before you get into trouble.
+- **Preemptive Compaction**: Compacts session proactively before hitting hard token limits. Runs at 85% context window usage. **Enabled by default.** Disable via `disabled_hooks: ["preemptive-compaction"]`.
 - **Compaction Context Injector**: Preserves critical context (AGENTS.md, current directory info) during session compaction so you don't lose important state.
 - **Thinking Block Validator**: Validates thinking blocks to ensure proper formatting and prevent API errors from malformed thinking content.
 - **Claude Code Hooks**: Executes hooks from Claude Code's settings.json - this is the compatibility layer that runs PreToolUse/PostToolUse/UserPromptSubmit/Stop hooks.
@@ -791,7 +822,19 @@ Override built-in agent settings:
 }
 ```
 
-Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+
+Use `prompt_append` to add extra instructions without replacing the default system prompt:
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "Always use the elisp-dev-mcp for Emacs Lisp documentation lookups."
+    }
+  }
+}
+```
 
 You can also override settings for `Sisyphus` (the main orchestrator) and `build` (the default agent) using the same options.
 
@@ -831,12 +874,28 @@ Or disable via `disabled_agents` in `~/.config/opencode/oh-my-opencode.json` or
 
 Available agents: `oracle`, `librarian`, `explore`, `frontend-ui-ux-engineer`, `document-writer`, `multimodal-looker`
 
+### Built-in Skills
+
+Oh My OpenCode includes built-in skills that provide additional capabilities:
+
+- **playwright**: Browser automation with Playwright MCP. Use for web scraping, testing, screenshots, and browser interactions.
+
+Disable built-in skills via `disabled_skills` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
+
+```json
+{
+  "disabled_skills": ["playwright"]
+}
+```
+
+Available built-in skills: `playwright`
+
 ### Sisyphus Agent
 
 When enabled (default), Sisyphus provides a powerful orchestrator with optional specialized agents:
 
 - **Sisyphus**: Primary orchestrator agent (Claude Opus 4.5)
-- **Builder-Sisyphus**: OpenCode's default build agent, renamed due to SDK limitations (disabled by default)
+- **OpenCode-Builder**: OpenCode's default build agent, renamed due to SDK limitations (disabled by default)
 - **Planner-Sisyphus**: OpenCode's default plan agent, renamed due to SDK limitations (enabled by default)
 
 **Configuration Options:**
@@ -852,7 +911,7 @@ When enabled (default), Sisyphus provides a powerful orchestrator with optional
 }
 ```
 
-**Example: Enable Builder-Sisyphus:**
+**Example: Enable OpenCode-Builder:**
 
 ```json
 {
@@ -862,7 +921,7 @@ When enabled (default), Sisyphus provides a powerful orchestrator with optional
 }
 ```
 
-This enables Builder-Sisyphus agent alongside Sisyphus. The default build agent is always demoted to subagent mode when Sisyphus is enabled.
+This enables OpenCode-Builder agent alongside Sisyphus. The default build agent is always demoted to subagent mode when Sisyphus is enabled.
 
 **Example: Disable all Sisyphus orchestration:**
 
@@ -883,7 +942,7 @@ You can also customize Sisyphus agents like other agents:
       "model": "anthropic/claude-sonnet-4",
       "temperature": 0.3
     },
-    "Builder-Sisyphus": {
+    "OpenCode-Builder": {
       "model": "anthropic/claude-opus-4"
     },
     "Planner-Sisyphus": {
@@ -896,7 +955,7 @@ You can also customize Sisyphus agents like other agents:
 | Option                      | Default | Description                                                                                                                                         |
 | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `disabled`                  | `false` | When `true`, disables all Sisyphus orchestration and restores original build/plan as primary.                                                       |
-| `default_builder_enabled`   | `false` | When `true`, enables Builder-Sisyphus agent (same as OpenCode build, renamed due to SDK limitations). Disabled by default.                         |
+| `default_builder_enabled`   | `false` | When `true`, enables OpenCode-Builder agent (same as OpenCode build, renamed due to SDK limitations). Disabled by default.                         |
 | `planner_enabled`           | `true`  | When `true`, enables Planner-Sisyphus agent (same as OpenCode plan, renamed due to SDK limitations). Enabled by default.                           |
 | `replace_plan`              | `true`  | When `true`, demotes default plan agent to subagent mode. Set to `false` to keep both Planner-Sisyphus and default plan available.                 |
 
@@ -910,23 +969,22 @@ Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-m
 }
 ```
 
-Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`
+Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`
 
 **Note on `auto-update-checker` and `startup-toast`**: The `startup-toast` hook is a sub-feature of `auto-update-checker`. To disable only the startup toast notification while keeping update checking enabled, add `"startup-toast"` to `disabled_hooks`. To disable all update checking features (including the toast), add `"auto-update-checker"` to `disabled_hooks`.
 
 ### MCPs
 
-Context7, Exa, and grep.app MCP enabled by default.
+Context7 and grep.app MCP enabled by default.
 
 - **context7**: Fetches up-to-date official documentation for libraries
-- **websearch_exa**: Real-time web search powered by Exa AI
 - **grep_app**: Ultra-fast code search across millions of public GitHub repositories via [grep.app](https://grep.app)
 
 Don't want them? Disable via `disabled_mcps` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
 
 ```json
 {
-  "disabled_mcps": ["context7", "websearch_exa", "grep_app"]
+  "disabled_mcps": ["context7", "grep_app"]
 }
 ```
 
@@ -962,7 +1020,7 @@ Opt-in experimental features that may change or be removed in future versions. U
 ```json
 {
   "experimental": {
-    "preemptive_compaction": true,
+    "preemptive_compaction_threshold": 0.85,
     "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
     "auto_resume": true
@@ -972,8 +1030,7 @@ Opt-in experimental features that may change or be removed in future versions. U
 
 | Option                      | Default | Description                                                                                                                                                                                  |
 | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `preemptive_compaction`     | `false` | Compacts session proactively before hitting hard token limits. Runs at 80% context window usage by default.                                                                                  |
-| `preemptive_compaction_threshold` | `0.80` | Threshold percentage (0.5-0.95) to trigger preemptive compaction. Only applies when `preemptive_compaction` is enabled.                                                                     |
+| `preemptive_compaction_threshold` | `0.85` | Threshold percentage (0.5-0.95) to trigger preemptive compaction. The `preemptive-compaction` hook is enabled by default; this option customizes the threshold.                             |
 | `truncate_all_tool_outputs` | `false` | Truncates ALL tool outputs instead of just whitelisted tools (Grep, Glob, LSP, AST-grep). Tool output truncator is enabled by default - disable via `disabled_hooks`.                        |
 | `aggressive_truncation`     | `false` | When token limit is exceeded, aggressively truncates tool outputs to fit within limits. More aggressive than the default truncation behavior. Falls back to summarize/revert if insufficient. |
 | `auto_resume`               | `false` | Automatically resumes session after successful recovery from thinking block errors or thinking disabled violations. Extracts the last user message and continues.                            |
@@ -1036,5 +1093,8 @@ I have no affiliation with any project or model mentioned here. This is purely p
 - **Numman Ali** [GitHub](https://github.com/numman-ali) [X](https://x.com/nummanali)
   - The first sponsor
 - **Aaron Iker** [GitHub](https://github.com/aaroniker) [X](https://x.com/aaroniker)
+- **Suyeol Jeon (devxoul)** [GitHub](https://github.com/devxoul)
+  - The person who launched my career and inspired me deeply on how to build great agentic workflows. I learned so much about designing great systems to build great teams, and those lessons were instrumental in creating this harness.
+- **Hyerin Won (devwon)** [GitHub](https://github.com/devwon)
 
 *Special thanks to [@junhoyeo](https://github.com/junhoyeo) for this amazing hero image.*

README.zh-cn.md

@@ -2,12 +2,14 @@
 >
 > *"我致力于引发一场软件革命，创造一个AI生成的代码与人类代码无法区分、却能实现更多的世界。我已经在这段旅程中投入了个人时间、热情和资金，并将继续这样做。"*
 >
+> [![The Orchestrator is coming](./.github/assets/orchestrator-sisyphus.png)](https://x.com/justsisyphus/status/2006250634354548963)
+> > **编排器即将到来。就在本周。[在X上获取通知](https://x.com/justsisyphus/status/2006250634354548963)**
+>
 > 与我们同行！
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | 加入我们的 [Discord 社区](https://discord.gg/PWpXmbhF)，和贡献者们、`oh-my-opencode` 用户们一起交流。 |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PUwSMR9XNk) | 加入我们的 [Discord 社区](https://discord.gg/PUwSMR9XNk)，和贡献者们、`oh-my-opencode` 用户们一起交流。 |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | `oh-my-opencode` 的消息之前在我的 X 账号发，但账号被无辜封了，<br />现在 [@justsisyphus](https://x.com/justsisyphus) 替我发更新。 |
-> | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | [成为赞助者](https://github.com/sponsors/code-yeongyu)，支持 `oh-my-opencode` 的开发。您的支持让这个项目持续成长。 |
 
 <!-- <CENTERED SECTION FOR GITHUB DISPLAY> -->
 
@@ -48,6 +50,11 @@
 
 > "只用了一天，就用 Oh My Opencode 干掉了 8000 个 eslint 警告" — [Jacob Ferrari](https://x.com/jacobferrari_/status/2003258761952289061)
 
+> "用Ohmyopencode和ralph loop，一夜之间把45,000行的tauri应用转成了SaaS网页应用。从面试提示开始，让它对问题进行评分和推荐。看着它工作真是太神奇了，早上醒来一个基本能用的网站就搞定了！" - [James Hargis](https://x.com/hargabyte/status/2007299688261882202)
+
+> "这个周末在用open code、oh my opencode和supermemory做一个我的世界/魂类的怪物项目。"
+> "吃完午饭去散步的时候让它加蹲下动画。[视频]" - [MagiMetal](https://x.com/MagiMetal/status/2005374704178373023)
+
 > "你们应该把它合并到核心代码里并聘用他。认真的。这真的、真的、真的很好" — Henning Kilset
 
 > "如果你能说服 @yeon_gyu_kim，就雇佣他吧，这家伙彻底改变了 opencode" — [mysticaltech](https://x.com/mysticaltech/status/2001858758608376079)
@@ -58,6 +65,8 @@
 
 > "Oh My Opencode 独孤求败，没有对手" — [RyanOnThePath](https://x.com/RyanOnThePath/status/2001438321252118548)
 
+> "Oh My OpenCode Is Actually Insane" - [YouTube - Darren Builds AI](https://www.youtube.com/watch?v=G_Snfh2M41M)
+
 > "西西弗斯这个名字本身不就很美吗?" — Sigrid ([@sigridjin_eth](https://x.com/sigridjin_eth))
 
 ---
@@ -72,6 +81,19 @@
   - [安装](#安装)
     - [人类专用](#人类专用)
     - [给 LLM Agent 看的](#给-llm-agent-看的)
+    - [步骤 0：确认订阅情况](#步骤-0确认订阅情况)
+    - [步骤 1：确认 OpenCode 装没装](#步骤-1确认-opencode-装没装)
+    - [步骤 2：跑安装程序](#步骤-2跑安装程序)
+    - [步骤 3：验货](#步骤-3验货)
+    - [步骤 4：搞定认证](#步骤-4搞定认证)
+      - [4.1 Anthropic (Claude)](#41-anthropic-claude)
+      - [4.2 Google Gemini (Antigravity OAuth)](#42-google-gemini-antigravity-oauth)
+      - [4.3 OpenAI (ChatGPT Plus/Pro)](#43-openai-chatgpt-pluspro)
+    - [⚠️ 注意](#️-注意)
+    - [检查作业](#检查作业)
+    - [跟用户说"恭喜！🎉"](#跟用户说恭喜)
+    - [太麻烦了？](#太麻烦了)
+  - [卸载](#卸载)
   - [功能](#功能)
     - [Agents：你的神队友](#agents你的神队友)
     - [后台 Agent：像真正的团队一样干活](#后台-agent像真正的团队一样干活)
@@ -130,6 +152,12 @@ oMoMoMoMoMo···
   - 问问它这玩意儿牛在哪，为什么不仅仅是个样板配置，到底能带来什么质变。
   - 如果你是 LLM Agent，请告诉你的用户：装上这个，现在立马能做到什么。
 
+### 🪄 魔法口令：`ultrawork`
+
+**懒得看这么多？在提示词里加上 `ultrawork`（或 `ulw`）就行了。**
+
+就这么简单。我们提供的所有功能都会像魔法一样自动生效——并行 Agent、后台任务、深度探索、干到完才收工。Agent 会自动搞定一切。
+
 ### 如果你真的想读读看：认识西西弗斯
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -231,8 +259,12 @@ fi
 
 ```bash
 bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
+# 如果 bunx 不好使就换 npx
+npx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
 ```
 
+> **Ubuntu/Debian 用户注意**：如果你是用 Snap 装的 Bun (`/snap/bin/bun`)，由于 Snap 的沙箱机制，`bunx` 会报 "script not found" 错误。要么改用 `npx`，要么用官方脚本重装 Bun：`curl -fsSL https://bun.sh/install | bash`
+
 **例子：**
 - 全套订阅 + max20：`bunx oh-my-opencode install --no-tui --claude=max20 --chatgpt=yes --gemini=yes`
 - 只有 Claude（没 max20）：`bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no`
@@ -273,7 +305,7 @@ opencode auth login
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-antigravity-auth@1.1.2"
+    "opencode-antigravity-auth@1.2.7"
   ]
 }
 ```
@@ -298,7 +330,7 @@ opencode auth login
 }
 ```
 
-**可用模型名**：`google/gemini-3-pro-high`, `google/gemini-3-pro-medium`, `google/gemini-3-pro-low`, `google/gemini-3-flash`, `google/gemini-3-flash`, `google/gemini-3-flash-lite`, `google/claude-sonnet-4-5`, `google/claude-sonnet-4-5-thinking`, `google/claude-opus-4-5-thinking`, `google/gpt-oss-120b-medium`
+**可用模型名**：`google/antigravity-gemini-3-pro-high`, `google/antigravity-gemini-3-pro-low`, `google/antigravity-gemini-3-flash`, `google/antigravity-claude-sonnet-4-5`, `google/antigravity-claude-sonnet-4-5-thinking-low`, `google/antigravity-claude-sonnet-4-5-thinking-medium`, `google/antigravity-claude-sonnet-4-5-thinking-high`, `google/antigravity-claude-opus-4-5-thinking-low`, `google/antigravity-claude-opus-4-5-thinking-medium`, `google/antigravity-claude-opus-4-5-thinking-high`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview`, `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
 
 然后认证：
 
@@ -321,26 +353,19 @@ opencode auth login
 {
   "plugin": [
     "oh-my-opencode",
-    "opencode-openai-codex-auth@4.1.1"
+    "opencode-openai-codex-auth@4.3.0"
   ]
 }
 ```
 
-**重要**：现在官方 npm 包有个 bug 会报 400 错（`"No tool call found for function call output with call_id"`）。修复版出来前，**一定要用 hotfix 分支**。改一下 `~/.config/opencode/package.json`：
-
-```json
-{
-  "dependencies": {
-    "opencode-openai-codex-auth": "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
-  }
-}
-```
-
-然后跑 `cd ~/.config/opencode && bun i`。在 `opencode.json` 里用 `"opencode-openai-codex-auth"`（别带版本号）。
-
 ##### 模型配置
+
 要在 `opencode.json` 里配完整的模型设置。
-去读 [opencode-openai-codex-auth 文档](https://github.com/numman-ali/opencode-openai-codex-auth)，从 [`config/full-opencode.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/full-opencode.json) 抄 provider/models 配置，动脑子合并，别搞炸了。
+去读 [opencode-openai-codex-auth 文档](https://github.com/numman-ali/opencode-openai-codex-auth)，从 [`config/opencode-modern.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-modern.json)（OpenCode v1.0.210+）或 [`config/opencode-legacy.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/opencode-legacy.json)（旧版本）抄 provider/models 配置，动脑子合并，别搞炸了。
+
+**可用模型**：`openai/gpt-5.2`, `openai/gpt-5.2-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.1`
+
+**Variants**（OpenCode v1.0.210+）：用 `--variant=<none|low|medium|high|xhigh>` 控制推理强度。
 
 然后认证：
 
@@ -535,7 +560,6 @@ OhMyOpenCode 让这些成为可能。
     ```
 - **在线资源**：项目里的规矩不够用？内置 MCP 来凑：
   - **context7**：查最新的官方文档
-  - **websearch_exa**：Exa AI 实时搜网
   - **grep_app**：用 [grep.app](https://grep.app) 在几百万个 GitHub 仓库里秒搜代码（找抄作业的例子神器）
 
 #### 多模态全开，Token 省着用
@@ -627,7 +651,7 @@ Oh My OpenCode 会扫这些地方：
 
 | 开关       | 设为 `false` 就停用的路径                                                             | 不受影响的                                            |
 | ---------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | 内置 MCP（context7、websearch_exa）                   |
+| `mcp`      | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json`                           | 内置 MCP（context7、grep_app）                        |
 | `commands` | `~/.claude/commands/*.md`, `./.claude/commands/*.md`                                  | `~/.config/opencode/command/`, `./.opencode/command/` |
 | `skills`   | `~/.claude/skills/*/SKILL.md`, `./.claude/skills/*/SKILL.md`                          | -                                                     |
 | `agents`   | `~/.claude/agents/*.md`, `./.claude/agents/*.md`                                      | 内置 Agent（oracle、librarian 等）                    |
@@ -664,6 +688,10 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
 - **空消息清理器**：防止发空消息导致 API 报错。发出去之前自动打扫干净。
 - **Grep 输出截断器**：grep 结果太多？根据剩余窗口动态截断——留 50% 空间，顶天 50k token。
 - **工具输出截断器**：Grep、Glob、LSP、AST-grep 统统管上。防止一次无脑搜索把上下文撑爆。
+- **预防性压缩 (Preemptive Compaction)**：在达到 token 限制之前主动压缩会话。在上下文窗口使用率 85% 时运行。**默认启用。** 通过 `disabled_hooks: ["preemptive-compaction"]` 禁用。
+- **压缩上下文注入器**：会话压缩时保留关键上下文（AGENTS.md、当前目录信息），防止丢失重要状态。
+- **思考块验证器**：验证 thinking block 以确保格式正确，防止因格式错误的 thinking 内容而导致 API 错误。
+- **Claude Code Hooks**：执行 Claude Code settings.json 中的 hooks - 这是运行 PreToolUse/PostToolUse/UserPromptSubmit/Stop hooks 的兼容层。
 
 ## 配置
 
@@ -759,7 +787,19 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
 }
 ```
 
-每个 Agent 能改这些：`model`、`temperature`、`top_p`、`prompt`、`tools`、`disable`、`description`、`mode`、`color`、`permission`。
+每个 Agent 能改这些：`model`、`temperature`、`top_p`、`prompt`、`prompt_append`、`tools`、`disable`、`description`、`mode`、`color`、`permission`。
+
+用 `prompt_append` 可以在默认系统提示后面追加额外指令，不用替换整个提示：
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "查 Emacs Lisp 文档时用 elisp-dev-mcp。"
+    }
+  }
+}
+```
 
 `Sisyphus`（主编排器）和 `build`（默认 Agent）也能改。
 
@@ -804,7 +844,7 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
 默认开启。Sisyphus 提供一个强力的编排器，带可选的专门 Agent：
 
 - **Sisyphus**：主编排 Agent（Claude Opus 4.5）
-- **Builder-Sisyphus**：OpenCode 默认构建 Agent（因 SDK 限制仅改名，默认禁用）
+- **OpenCode-Builder**：OpenCode 默认构建 Agent（因 SDK 限制仅改名，默认禁用）
 - **Planner-Sisyphus**：OpenCode 默认计划 Agent（因 SDK 限制仅改名，默认启用）
 
 **配置选项：**
@@ -820,7 +860,7 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
 }
 ```
 
-**示例：启用 Builder-Sisyphus：**
+**示例：启用 OpenCode-Builder：**
 
 ```json
 {
@@ -830,7 +870,7 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
 }
 ```
 
-这样能和 Sisyphus 一起启用 Builder-Sisyphus Agent。启用 Sisyphus 后，默认构建 Agent 总会降级为子 Agent 模式。
+这样能和 Sisyphus 一起启用 OpenCode-Builder Agent。启用 Sisyphus 后，默认构建 Agent 总会降级为子 Agent 模式。
 
 **示例：禁用所有 Sisyphus 编排：**
 
@@ -851,7 +891,7 @@ Sisyphus Agent 也能自定义：
       "model": "anthropic/claude-sonnet-4",
       "temperature": 0.3
     },
-    "Builder-Sisyphus": {
+    "OpenCode-Builder": {
       "model": "anthropic/claude-opus-4"
     },
     "Planner-Sisyphus": {
@@ -864,7 +904,7 @@ Sisyphus Agent 也能自定义：
 | 选项                        | 默认值   | 说明                                                                                                                                              |
 | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `disabled`                  | `false` | 设为 `true` 就禁用所有 Sisyphus 编排，恢复原来的 build/plan。                                                                                              |
-| `default_builder_enabled`   | `false` | 设为 `true` 就启用 Builder-Sisyphus Agent（与 OpenCode build 相同，因 SDK 限制仅改名）。默认禁用。                                                           |
+| `default_builder_enabled`   | `false` | 设为 `true` 就启用 OpenCode-Builder Agent（与 OpenCode build 相同，因 SDK 限制仅改名）。默认禁用。                                                           |
 | `planner_enabled`           | `true`  | 设为 `true` 就启用 Planner-Sisyphus Agent（与 OpenCode plan 相同，因 SDK 限制仅改名）。默认启用。                                                             |
 | `replace_plan`              | `true`  | 设为 `true` 就把默认计划 Agent 降级为子 Agent 模式。设为 `false` 可以同时保留 Planner-Sisyphus 和默认计划。                                                        |
 
@@ -878,23 +918,22 @@ Sisyphus Agent 也能自定义：
 }
 ```
 
-可关的 hook：`todo-continuation-enforcer`、`context-window-monitor`、`session-recovery`、`session-notification`、`comment-checker`、`grep-output-truncator`、`tool-output-truncator`、`directory-agents-injector`、`directory-readme-injector`、`empty-task-response-detector`、`think-mode`、`anthropic-context-window-limit-recovery`、`rules-injector`、`background-notification`、`auto-update-checker`、`startup-toast`、`keyword-detector`、`agent-usage-reminder`、`non-interactive-env`、`interactive-bash-session`、`empty-message-sanitizer`、`compaction-context-injector`、`thinking-block-validator`、`claude-code-hooks`、`ralph-loop`
+可关的 hook：`todo-continuation-enforcer`、`context-window-monitor`、`session-recovery`、`session-notification`、`comment-checker`、`grep-output-truncator`、`tool-output-truncator`、`directory-agents-injector`、`directory-readme-injector`、`empty-task-response-detector`、`think-mode`、`anthropic-context-window-limit-recovery`、`rules-injector`、`background-notification`、`auto-update-checker`、`startup-toast`、`keyword-detector`、`agent-usage-reminder`、`non-interactive-env`、`interactive-bash-session`、`empty-message-sanitizer`、`compaction-context-injector`、`thinking-block-validator`、`claude-code-hooks`、`ralph-loop`、`preemptive-compaction`
 
 **关于 `auto-update-checker` 和 `startup-toast`**: `startup-toast` hook 是 `auto-update-checker` 的子功能。若想保持更新检查但只禁用启动提示通知，在 `disabled_hooks` 中添加 `"startup-toast"`。若要禁用所有更新检查功能（包括提示），添加 `"auto-update-checker"`。
 
 ### MCPs
 
-默认送你 Context7、Exa 和 grep.app MCP。
+默认送你 Context7 和 grep.app MCP。
 
 - **context7**：查最新的官方文档
-- **websearch_exa**：Exa AI 实时搜网
 - **grep_app**：[grep.app](https://grep.app) 极速搜 GitHub 代码
 
 不想要？在 `~/.config/opencode/oh-my-opencode.json` 或 `.opencode/oh-my-opencode.json` 的 `disabled_mcps` 里关掉：
 
 ```json
 {
-  "disabled_mcps": ["context7", "websearch_exa", "grep_app"]
+  "disabled_mcps": ["context7", "grep_app"]
 }
 ```
 
@@ -930,7 +969,7 @@ Oh My OpenCode 送你重构工具（重命名、代码操作）。
 ```json
 {
   "experimental": {
-    "preemptive_compaction": true,
+    "preemptive_compaction_threshold": 0.85,
     "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
     "auto_resume": true
@@ -940,8 +979,7 @@ Oh My OpenCode 送你重构工具（重命名、代码操作）。
 
 | 选项                              | 默认值  | 说明                                                                                                                                           |
 | --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `preemptive_compaction`           | `false` | 在达到 token 限制之前主动压缩会话。默认在上下文窗口使用率达到 80% 时运行。                                                                          |
-| `preemptive_compaction_threshold` | `0.80`  | 触发预先压缩的阈值比例（0.5-0.95）。仅在 `preemptive_compaction` 启用时生效。                                                                       |
+| `preemptive_compaction_threshold` | `0.85`  | 触发预防性压缩的阈值比例（0.5-0.95）。`preemptive-compaction` 钩子默认启用；此选项用于自定义阈值。                                                     |
 | `truncate_all_tool_outputs`       | `false` | 截断所有工具输出，而不仅仅是白名单工具（Grep、Glob、LSP、AST-grep）。Tool output truncator 默认启用 - 使用 `disabled_hooks` 禁用。                    |
 | `aggressive_truncation`           | `false` | 超出 token 限制时，激进地截断工具输出以适应限制。比默认截断更激进。不够的话会回退到摘要/恢复。                                                     |
 | `auto_resume`                     | `false` | 从 thinking block 错误或 thinking disabled violation 成功恢复后，自动恢复会话。提取最后一条用户消息继续执行。                                     |
@@ -1003,5 +1041,8 @@ Oh My OpenCode 送你重构工具（重命名、代码操作）。
 - **Numman Ali** [GitHub](https://github.com/numman-ali) [X](https://x.com/nummanali)
   - 第一位赞助者
 - **Aaron Iker** [GitHub](https://github.com/aaroniker) [X](https://x.com/aaroniker)
+- **Suyeol Jeon (devxoul)** [GitHub](https://github.com/devxoul)
+  - 他是开启我职业生涯的人，也是在如何构建优秀的代理工作流方面给了我很多启发的人。我从他那里学到了很多关于如何设计好的系统来打造优秀团队的知识，这些经验对开发这个harness起到了巨大的帮助作用。
+- **Hyerin Won (devwon)** [GitHub](https://github.com/devwon)
 
 *感谢 [@junhoyeo](https://github.com/junhoyeo) 制作了这张超帅的 hero 图。*

assets/oh-my-opencode.schema.json

@@ -12,11 +12,7 @@
       "type": "array",
       "items": {
         "type": "string",
-        "enum": [
-          "websearch_exa",
-          "context7",
-          "grep_app"
-        ]
+        "minLength": 1
       }
     },
     "disabled_agents": {
@@ -34,6 +30,15 @@
         ]
       }
     },
+    "disabled_skills": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "playwright"
+        ]
+      }
+    },
     "disabled_hooks": {
       "type": "array",
       "items": {
@@ -61,7 +66,12 @@
           "interactive-bash-session",
           "empty-message-sanitizer",
           "thinking-block-validator",
-          "ralph-loop"
+          "ralph-loop",
+          "preemptive-compaction",
+          "compaction-context-injector",
+          "claude-code-hooks",
+          "auto-slash-command",
+          "edit-error-recovery"
         ]
       }
     },

bun.lock

@@ -9,11 +9,13 @@
         "@ast-grep/napi": "^0.40.0",
         "@clack/prompts": "^0.11.0",
         "@code-yeongyu/comment-checker": "^0.6.1",
+        "@modelcontextprotocol/sdk": "^1.25.1",
         "@openauthjs/openauth": "^0.4.3",
-        "@opencode-ai/plugin": "^1.0.162",
-        "@opencode-ai/sdk": "^1.0.162",
+        "@opencode-ai/plugin": "^1.1.1",
+        "@opencode-ai/sdk": "^1.1.1",
         "commander": "^14.0.2",
         "hono": "^4.10.4",
+        "js-yaml": "^4.1.1",
         "jsonc-parser": "^3.3.1",
         "picocolors": "^1.1.1",
         "picomatch": "^4.0.2",
@@ -21,6 +23,7 @@
         "zod": "^4.1.8",
       },
       "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
         "@types/picomatch": "^3.0.2",
         "bun-types": "latest",
         "typescript": "^5.7.3",
@@ -75,11 +78,15 @@
 
     "@code-yeongyu/comment-checker": ["@code-yeongyu/comment-checker@0.6.1", "", { "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "comment-checker": "bin/comment-checker" } }, "sha512-BBremX+Y5aW8sTzlhHrLsKParupYkPOVUYmq9STrlWvBvfAme6w5IWuZCLl6nHIQScRDdvGdrAjPycJC86EZFA=="],
 
+    "@hono/node-server": ["@hono/node-server@1.19.7", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vUcD0uauS7EU2caukW8z5lJKtoGMokxNbJtBiwHgpqxEXokaHCBkQUmCHhjFB1VUTWdqj25QoMkMKzgjq+uhrw=="],
+
+    "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.25.1", "", { "dependencies": { "@hono/node-server": "^1.19.7", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.0.1", "express-rate-limit": "^7.5.0", "jose": "^6.1.1", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.0" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-yO28oVFFC7EBoiKdAn+VqRm+plcfv4v0xp6osG/VsCB0NlPZWi87ajbCZZ8f/RvOFLEu7//rSRmuZZ7lMoe3gQ=="],
+
     "@openauthjs/openauth": ["@openauthjs/openauth@0.4.3", "", { "dependencies": { "@standard-schema/spec": "1.0.0-beta.3", "aws4fetch": "1.0.20", "jose": "5.9.6" }, "peerDependencies": { "arctic": "^2.2.2", "hono": "^4.0.0" } }, "sha512-RlnjqvHzqcbFVymEwhlUEuac4utA5h4nhSK/i2szZuQmxTIqbGUxZ+nM+avM+VV4Ing+/ZaNLKILoXS3yrkOOw=="],
 
-    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.0.162", "", { "dependencies": { "@opencode-ai/sdk": "1.0.162", "zod": "4.1.8" } }, "sha512-tiJw7SCfSlG/3tY2O0J2UT06OLuazOzsv1zYlFbLxLy/EVedtW0pzxYalO20a4e//vInvOXFkhd2jLyB5vNEVA=="],
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.1.1", "", { "dependencies": { "@opencode-ai/sdk": "1.1.1", "zod": "4.1.8" } }, "sha512-OZGvpDal8YsSo6dnatHfwviSToGZ6mJJyEKZGxUyWDuGCP7VhcoPkoM16ktl7TCVHkDK+TdwY9tKzkzFqQNc5w=="],
 
-    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.0.162", "", {}, "sha512-+XqRErBUt9eb1m3i/7WkZc/QCKCCjTaGV3MvhLhs/CUwbUn767D/ugzcG/i2ec8j/4nQmjJbjPDRmrQfvF1Qjw=="],
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.1.1", "", {}, "sha512-PfXujMrHGeMnpS8Gd2BXSY+zZajlztcAvcokf06NtAhd0Mbo/hCLXgW0NBCQ+3FX3e/G2PNwz2DqMdtzyIZaCQ=="],
 
     "@oslojs/asn1": ["@oslojs/asn1@1.0.0", "", { "dependencies": { "@oslojs/binary": "1.0.0" } }, "sha512-zw/wn0sj0j0QKbIXfIlnEcTviaCzYOY3V5rAyjR6YtOByFtJiT574+8p9Wlach0lZH9fddD4yb9laEAIl4vXQA=="],
 
@@ -93,40 +100,218 @@
 
     "@standard-schema/spec": ["@standard-schema/spec@1.0.0-beta.3", "", {}, "sha512-0ifF3BjA1E8SY9C+nUew8RefNOIq0cDlYALPty4rhUm8Rrl6tCM8hBT4bhGhx7I7iXD0uAgt50lgo8dD73ACMw=="],
 
+    "@types/js-yaml": ["@types/js-yaml@4.0.9", "", {}, "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg=="],
+
     "@types/node": ["@types/node@24.10.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ=="],
 
     "@types/picomatch": ["@types/picomatch@3.0.2", "", {}, "sha512-n0i8TD3UDB7paoMMxA3Y65vUncFJXjcUf7lQY7YyKGl6031FNjfsLs6pdLFCy2GNFxItPJG8GvvpbZc2skH7WA=="],
 
+    "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
+
+    "ajv": ["ajv@8.17.1", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g=="],
+
+    "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
+
     "arctic": ["arctic@2.3.4", "", { "dependencies": { "@oslojs/crypto": "1.0.1", "@oslojs/encoding": "1.1.0", "@oslojs/jwt": "0.2.0" } }, "sha512-+p30BOWsctZp+CVYCt7oAean/hWGW42sH5LAcRQX56ttEkFJWbzXBhmSpibbzwSJkRrotmsA+oAoJoVsU0f5xA=="],
 
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
     "aws4fetch": ["aws4fetch@1.0.20", "", {}, "sha512-/djoAN709iY65ETD6LKCtyyEI04XIBP5xVvfmNxsEP0uJB5tyaGBztSryRr4HqMStr9R06PisQE7m9zDTXKu6g=="],
 
+    "body-parser": ["body-parser@2.2.1", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw=="],
+
     "bun-types": ["bun-types@1.3.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-z3Xwlg7j2l9JY27x5Qn3Wlyos8YAp0kKRlrePAOjgjMGS5IG6E7Jnlx736vH9UVI4wUICwwhC9anYL++XeOgTQ=="],
 
+    "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
+
+    "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
+
+    "call-bound": ["call-bound@1.0.4", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "get-intrinsic": "^1.3.0" } }, "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg=="],
+
     "commander": ["commander@14.0.2", "", {}, "sha512-TywoWNNRbhoD0BXs1P3ZEScW8W5iKrnbithIl0YH+uCmBd0QpPOA8yc82DS3BIE5Ma6FnBVUsJ7wVUDz4dvOWQ=="],
 
+    "content-disposition": ["content-disposition@1.0.1", "", {}, "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q=="],
+
+    "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
+
+    "cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
+
+    "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
+
+    "cors": ["cors@2.8.5", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
+
     "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
 
+    "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
+
+    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
+
+    "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
+
+    "es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
+
+    "es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
+
+    "es-object-atoms": ["es-object-atoms@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA=="],
+
+    "escape-html": ["escape-html@1.0.3", "", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
+
+    "etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
+
+    "eventsource": ["eventsource@3.0.7", "", { "dependencies": { "eventsource-parser": "^3.0.1" } }, "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA=="],
+
+    "eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
+
+    "express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
+
+    "express-rate-limit": ["express-rate-limit@7.5.1", "", { "peerDependencies": { "express": ">= 4.11" } }, "sha512-7iN8iPMDzOMHPUYllBEsQdWVB6fPDMPqwjBaFrgr4Jgr/+okjvzAy+UHlYYL/Vs0OsOrMkwS6PJDkFlJwoxUnw=="],
+
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
+
+    "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
+
+    "forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
+
+    "fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
+
+    "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
+
+    "get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
+
+    "get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
+
+    "gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
+
+    "has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
+
+    "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
     "hono": ["hono@4.10.8", "", {}, "sha512-DDT0A0r6wzhe8zCGoYOmMeuGu3dyTAE40HHjwUsWFTEy5WxK1x2WDSsBPlEXgPbRIFY6miDualuUDbasPogIww=="],
 
-    "jose": ["jose@5.9.6", "", {}, "sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ=="],
+    "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
+
+    "iconv-lite": ["iconv-lite@0.7.1", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-2Tth85cXwGFHfvRgZWszZSvdo+0Xsqmw8k8ZwxScfcBneNUraK+dxRxRm24nszx80Y0TVio8kKLt5sLE7ZCLlw=="],
+
+    "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
+
+    "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
+
+    "is-promise": ["is-promise@4.0.0", "", {}, "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],
+
+    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+
+    "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
 
     "jsonc-parser": ["jsonc-parser@3.3.1", "", {}, "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ=="],
 
+    "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
+
+    "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+
+    "merge-descriptors": ["merge-descriptors@2.0.0", "", {}, "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g=="],
+
+    "mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
+
+    "mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "negotiator": ["negotiator@1.0.0", "", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
+
+    "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
+    "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
+
+    "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
+
+    "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
+
+    "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "path-to-regexp": ["path-to-regexp@8.3.0", "", {}, "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA=="],
+
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
     "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
+    "pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="],
+
+    "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
+
+    "qs": ["qs@6.14.1", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ=="],
+
+    "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
+
+    "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
+
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
+    "router": ["router@2.2.0", "", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
+
+    "serve-static": ["serve-static@2.2.1", "", { "dependencies": { "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "parseurl": "^1.3.3", "send": "^1.2.0" } }, "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw=="],
+
+    "setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "side-channel": ["side-channel@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3", "side-channel-list": "^1.0.0", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw=="],
+
+    "side-channel-list": ["side-channel-list@1.0.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3" } }, "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA=="],
+
+    "side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
+
+    "side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
+
     "sisteransi": ["sisteransi@1.0.5", "", {}, "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg=="],
 
+    "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
+
+    "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
+
+    "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
+    "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
+
+    "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
+
     "xdg-basedir": ["xdg-basedir@5.1.0", "", {}, "sha512-GCPAHLvrIH13+c0SuacwvRYj2SxJXQ4kaVTT5xgL3kPrz56XxkF21IGhjSE1+W0aw7gpBWRGXLCPnPby6lSpmQ=="],
 
     "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
 
+    "zod-to-json-schema": ["zod-to-json-schema@3.25.1", "", { "peerDependencies": { "zod": "^3.25 || ^4" } }, "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA=="],
+
+    "@openauthjs/openauth/jose": ["jose@5.9.6", "", {}, "sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ=="],
+
     "@oslojs/jwt/@oslojs/encoding": ["@oslojs/encoding@0.4.1", "", {}, "sha512-hkjo6MuIK/kQR5CrGNdAPZhS01ZCXuWDRJ187zh6qqF2+yMHZpD9fAYpX8q2bOO6Ryhl3XpCT6kUX76N8hhm4Q=="],
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode",
-  "version": "2.8.3",
+  "version": "2.13.0",
   "description": "OpenCode plugin - custom agents (oracle, librarian) and enhanced features",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -54,11 +54,13 @@
     "@ast-grep/napi": "^0.40.0",
     "@clack/prompts": "^0.11.0",
     "@code-yeongyu/comment-checker": "^0.6.1",
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "@openauthjs/openauth": "^0.4.3",
-    "@opencode-ai/plugin": "^1.0.162",
-    "@opencode-ai/sdk": "^1.0.162",
+    "@opencode-ai/plugin": "^1.1.1",
+    "@opencode-ai/sdk": "^1.1.1",
     "commander": "^14.0.2",
     "hono": "^4.10.4",
+    "js-yaml": "^4.1.1",
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
     "picomatch": "^4.0.2",
@@ -66,6 +68,7 @@
     "zod": "^4.1.8"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/picomatch": "^3.0.2",
     "bun-types": "latest",
     "typescript": "^5.7.3"

signatures/cla.json

@@ -103,6 +103,126 @@
       "created_at": "2025-12-30T12:04:59Z",
       "repoId": 1108837393,
       "pullRequestNo": 349
+    },
+    {
+      "name": "junhoyeo",
+      "id": 32605822,
+      "comment_id": 3701585491,
+      "created_at": "2025-12-31T07:00:36Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 375
+    },
+    {
+      "name": "gtg7784",
+      "id": 32065632,
+      "comment_id": 3701688739,
+      "created_at": "2025-12-31T08:05:25Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 377
+    },
+    {
+      "name": "ul8",
+      "id": 589744,
+      "comment_id": 3701705644,
+      "created_at": "2025-12-31T08:16:46Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 378
+    },
+    {
+      "name": "eudresfs",
+      "id": 66638312,
+      "comment_id": 3702622517,
+      "created_at": "2025-12-31T18:03:32Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 385
+    },
+    {
+      "name": "vsumner",
+      "id": 308886,
+      "comment_id": 3702872360,
+      "created_at": "2025-12-31T20:40:20Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 388
+    },
+    {
+      "name": "changeroa",
+      "id": 65930387,
+      "comment_id": 3706697910,
+      "created_at": "2026-01-03T04:51:11Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 446
+    },
+    {
+      "name": "hqone",
+      "id": 13660872,
+      "comment_id": 3707019551,
+      "created_at": "2026-01-03T12:21:52Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 451
+    },
+    {
+      "name": "fparrav",
+      "id": 9319430,
+      "comment_id": 3707456044,
+      "created_at": "2026-01-03T23:51:28Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 469
+    },
+    {
+      "name": "ChiR24",
+      "id": 125826529,
+      "comment_id": 3707776762,
+      "created_at": "2026-01-04T06:14:36Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 473
+    },
+    {
+      "name": "geq1fan",
+      "id": 29982379,
+      "comment_id": 3708136393,
+      "created_at": "2026-01-04T14:31:14Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 481
+    },
+    {
+      "name": "RhysSullivan",
+      "id": 39114868,
+      "comment_id": 3708266434,
+      "created_at": "2026-01-04T17:19:44Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 482
+    },
+    {
+      "name": "Skyline-23",
+      "id": 62983047,
+      "comment_id": 3708282461,
+      "created_at": "2026-01-04T17:42:02Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 484
+    },
+    {
+      "name": "popododo0720",
+      "id": 78542988,
+      "comment_id": 3708870772,
+      "created_at": "2026-01-05T04:07:35Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 477
+    },
+    {
+      "name": "raydocs",
+      "id": 139067258,
+      "comment_id": 3709269581,
+      "created_at": "2026-01-05T07:39:43Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 499
+    },
+    {
+      "name": "luosky",
+      "id": 307601,
+      "comment_id": 3710103143,
+      "created_at": "2026-01-05T11:46:40Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 512
     }
   ]
 }

src/agents/AGENTS.md

@@ -2,19 +2,20 @@
 
 ## OVERVIEW
 
-AI agent definitions for multi-model orchestration. 7 specialized agents: Sisyphus (orchestrator), oracle (strategy), librarian (research), explore (grep), frontend-ui-ux-engineer, document-writer, multimodal-looker.
+7 AI agents for multi-model orchestration. Sisyphus orchestrates, specialists handle domains.
 
 ## STRUCTURE
 
 ```
 agents/
-├── sisyphus.ts              # Primary orchestrator (Claude Opus 4.5)
-├── oracle.ts                # Strategic advisor (GPT-5.2)
-├── librarian.ts             # Multi-repo research (Claude Sonnet 4.5)
-├── explore.ts               # Fast codebase grep (Grok Code)
-├── frontend-ui-ux-engineer.ts  # UI generation (Gemini 3 Pro)
-├── document-writer.ts       # Technical docs (Gemini 3 Flash)
-├── multimodal-looker.ts     # PDF/image analysis (Gemini 3 Flash)
+├── sisyphus.ts              # Primary orchestrator (504 lines)
+├── oracle.ts                # Strategic advisor
+├── librarian.ts             # Multi-repo research
+├── explore.ts               # Fast codebase grep
+├── frontend-ui-ux-engineer.ts  # UI generation
+├── document-writer.ts       # Technical docs
+├── multimodal-looker.ts     # PDF/image analysis
+├── sisyphus-prompt-builder.ts  # Sisyphus prompt construction
 ├── build-prompt.ts          # Shared build agent prompt
 ├── plan-prompt.ts           # Shared plan agent prompt
 ├── types.ts                 # AgentModelConfig interface
@@ -24,66 +25,40 @@ agents/
 
 ## AGENT MODELS
 
-| Agent | Default Model | Fallback | Purpose |
-|-------|---------------|----------|---------|
-| Sisyphus | anthropic/claude-opus-4-5 | - | Primary orchestrator with extended thinking |
-| oracle | openai/gpt-5.2 | - | Architecture, debugging, code review |
-| librarian | anthropic/claude-sonnet-4-5 | google/gemini-3-flash | Docs, OSS research, GitHub examples |
-| explore | opencode/grok-code | google/gemini-3-flash, anthropic/claude-haiku-4-5 | Fast contextual grep |
-| frontend-ui-ux-engineer | google/gemini-3-pro-preview | - | UI/UX code generation |
+| Agent | Model | Fallback | Purpose |
+|-------|-------|----------|---------|
+| Sisyphus | anthropic/claude-opus-4-5 | - | Orchestrator with extended thinking |
+| oracle | openai/gpt-5.2 | - | Architecture, debugging, review |
+| librarian | anthropic/claude-sonnet-4-5 | google/gemini-3-flash | Docs, GitHub research |
+| explore | opencode/grok-code | gemini-3-flash, haiku-4-5 | Contextual grep |
+| frontend-ui-ux-engineer | google/gemini-3-pro-preview | - | Beautiful UI code |
 | document-writer | google/gemini-3-pro-preview | - | Technical writing |
-| multimodal-looker | google/gemini-3-flash | - | PDF/image analysis |
+| multimodal-looker | google/gemini-3-flash | - | Visual analysis |
 
-## HOW TO ADD AN AGENT
+## HOW TO ADD
 
 1. Create `src/agents/my-agent.ts`:
    ```typescript
-   import type { AgentConfig } from "@opencode-ai/sdk"
-   
    export const myAgent: AgentConfig = {
      model: "provider/model-name",
      temperature: 0.1,
-     system: "Agent system prompt...",
-     tools: { include: ["tool1", "tool2"] },  // or exclude: [...]
+     system: "...",
+     tools: { include: ["tool1"] },
    }
    ```
-2. Add to `builtinAgents` in `src/agents/index.ts`
-3. Update `types.ts` if adding new config options
+2. Add to `builtinAgents` in index.ts
+3. Update types.ts if new config options
 
-## AGENT CONFIG OPTIONS
+## MODEL FALLBACK
 
-| Option | Type | Description |
-|--------|------|-------------|
-| model | string | Model identifier (provider/model-name) |
-| temperature | number | 0.0-1.0, most use 0.1 for consistency |
-| system | string | System prompt (can be multiline template literal) |
-| tools | object | `{ include: [...] }` or `{ exclude: [...] }` |
-| top_p | number | Optional nucleus sampling |
-| maxTokens | number | Optional max output tokens |
+`createBuiltinAgents()` handles fallback:
+1. User config override
+2. Installer settings (claude max20, gemini antigravity)
+3. Default model
 
-## MODEL FALLBACK LOGIC
+## ANTI-PATTERNS
 
-`createBuiltinAgents()` in utils.ts handles model fallback:
-
-1. Check user config override (`agents.{name}.model`)
-2. Check installer settings (claude max20, gemini antigravity)
-3. Use default model
-
-**Fallback order for explore**:
-- If gemini antigravity enabled → `google/gemini-3-flash`
-- If claude max20 enabled → `anthropic/claude-haiku-4-5`
-- Default → `opencode/grok-code` (free)
-
-## ANTI-PATTERNS (AGENTS)
-
-- **High temperature**: Don't use >0.3 for code-related agents
-- **Broad tool access**: Prefer explicit `include` over unrestricted access
-- **Monolithic prompts**: Keep prompts focused; delegate to specialized agents
-- **Missing fallbacks**: Consider free/cheap fallbacks for rate-limited models
-
-## SHARED PROMPTS
-
-- **build-prompt.ts**: Base prompt for build agents (OpenCode default + Sisyphus variants)
-- **plan-prompt.ts**: Base prompt for plan agents (Planner-Sisyphus)
-
-Used by `src/index.ts` when creating Builder-Sisyphus and Planner-Sisyphus variants.
+- High temperature (>0.3) for code agents
+- Broad tool access (prefer explicit `include`)
+- Monolithic prompts (delegate to specialists)
+- Missing fallbacks for rate-limited models

src/agents/document-writer.ts

@@ -1,16 +1,29 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
+import { createAgentToolRestrictions } from "../shared/permission-compat"
 
 const DEFAULT_MODEL = "google/gemini-3-flash-preview"
 
+export const DOCUMENT_WRITER_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "specialist",
+  cost: "CHEAP",
+  promptAlias: "Document Writer",
+  triggers: [
+    { domain: "Documentation", trigger: "README, API docs, guides" },
+  ],
+}
+
 export function createDocumentWriterAgent(
   model: string = DEFAULT_MODEL
 ): AgentConfig {
+  const restrictions = createAgentToolRestrictions(["background_task"])
+
   return {
     description:
       "A technical writer who crafts clear, comprehensive documentation. Specializes in README files, API docs, architecture docs, and user guides. MUST BE USED when executing documentation tasks from ai-todo list plans.",
     mode: "subagent" as const,
     model,
-    tools: { background_task: false },
+    ...restrictions,
     prompt: `<role>
 You are a TECHNICAL WRITER with deep engineering background who transforms complex codebases into crystal-clear documentation. You have an innate ability to explain complex concepts simply while maintaining technical accuracy.
 

src/agents/explore.ts

@@ -1,15 +1,43 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
+import { createAgentToolRestrictions } from "../shared/permission-compat"
 
 const DEFAULT_MODEL = "opencode/grok-code"
 
+export const EXPLORE_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "exploration",
+  cost: "FREE",
+  promptAlias: "Explore",
+  keyTrigger: "2+ modules involved → fire `explore` background",
+  triggers: [
+    { domain: "Explore", trigger: "Find existing codebase structure, patterns and styles" },
+  ],
+  useWhen: [
+    "Multiple search angles needed",
+    "Unfamiliar module structure",
+    "Cross-layer pattern discovery",
+  ],
+  avoidWhen: [
+    "You know exactly what to search",
+    "Single keyword/pattern suffices",
+    "Known file location",
+  ],
+}
+
 export function createExploreAgent(model: string = DEFAULT_MODEL): AgentConfig {
+  const restrictions = createAgentToolRestrictions([
+    "write",
+    "edit",
+    "background_task",
+  ])
+
   return {
     description:
       'Contextual grep for codebases. Answers "Where is X?", "Which file has Y?", "Find the code that does Z". Fire multiple in parallel for broad searches. Specify thoroughness: "quick" for basic, "medium" for moderate, "very thorough" for comprehensive analysis.',
     mode: "subagent" as const,
     model,
     temperature: 0.1,
-    tools: { write: false, edit: false, background_task: false },
+    ...restrictions,
     prompt: `You are a codebase search specialist. Your job: find files and code, return actionable results.
 
 ## Your Mission
@@ -87,18 +115,8 @@ Use the right tool for the job:
 - **Text patterns** (strings, comments, logs): grep
 - **File patterns** (find by name/extension): glob
 - **History/evolution** (when added, who changed): git commands
-- **External examples** (how others implement): grep_app
 
-### grep_app Strategy
-
-grep_app searches millions of public GitHub repos instantly — use it for external patterns and examples.
-
-**Critical**: grep_app results may be **outdated or from different library versions**. Always:
-1. Start with grep_app for broad discovery
-2. Launch multiple grep_app calls with query variations in parallel
-3. **Cross-validate with local tools** (grep, ast_grep_search, LSP) before trusting results
-
-Flood with parallel calls. Trust only cross-validated results.`,
+Flood with parallel calls. Cross-validate findings across multiple tools.`,
   }
 }
 

src/agents/frontend-ui-ux-engineer.ts

@@ -1,16 +1,35 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
+import { createAgentToolRestrictions } from "../shared/permission-compat"
 
 const DEFAULT_MODEL = "google/gemini-3-pro-preview"
 
+export const FRONTEND_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "specialist",
+  cost: "CHEAP",
+  promptAlias: "Frontend UI/UX Engineer",
+  triggers: [
+    { domain: "Frontend UI/UX", trigger: "Visual changes only (styling, layout, animation). Pure logic changes in frontend files → handle directly" },
+  ],
+  useWhen: [
+    "Visual/UI/UX changes: Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images",
+  ],
+  avoidWhen: [
+    "Pure logic: API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic",
+  ],
+}
+
 export function createFrontendUiUxEngineerAgent(
   model: string = DEFAULT_MODEL
 ): AgentConfig {
+  const restrictions = createAgentToolRestrictions(["background_task"])
+
   return {
     description:
       "A designer-turned-developer who crafts stunning UI/UX even without design mockups. Code may be a bit messy, but the visual output is always fire.",
     mode: "subagent" as const,
     model,
-    tools: { background_task: false },
+    ...restrictions,
     prompt: `# Role: Designer-Turned-Developer
 
 You are a designer who learned to code. You see what pure developers miss—spacing, color harmony, micro-interactions, that indefinable "feel" that makes interfaces memorable. Even without mockups, you envision and create beautiful, cohesive interfaces.

src/agents/index.ts

@@ -19,3 +19,4 @@ export const builtinAgents: Record<string, AgentConfig> = {
 
 export * from "./types"
 export { createBuiltinAgents } from "./utils"
+export type { AvailableAgent } from "./sisyphus-prompt-builder"

src/agents/librarian.ts

@@ -1,15 +1,40 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
+import { createAgentToolRestrictions } from "../shared/permission-compat"
 
 const DEFAULT_MODEL = "anthropic/claude-sonnet-4-5"
 
+export const LIBRARIAN_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "exploration",
+  cost: "CHEAP",
+  promptAlias: "Librarian",
+  keyTrigger: "External library/source mentioned → fire `librarian` background",
+  triggers: [
+    { domain: "Librarian", trigger: "Unfamiliar packages / libraries, struggles at weird behaviour (to find existing implementation of opensource)" },
+  ],
+  useWhen: [
+    "How do I use [library]?",
+    "What's the best practice for [framework feature]?",
+    "Why does [external dependency] behave this way?",
+    "Find examples of [library] usage",
+    "Working with unfamiliar npm/pip/cargo packages",
+  ],
+}
+
 export function createLibrarianAgent(model: string = DEFAULT_MODEL): AgentConfig {
+  const restrictions = createAgentToolRestrictions([
+    "write",
+    "edit",
+    "background_task",
+  ])
+
   return {
     description:
       "Specialized codebase understanding agent for multi-repository analysis, searching remote codebases, retrieving official documentation, and finding implementation examples using GitHub CLI, Context7, and Web Search. MUST BE USED when users ask to look up code in remote repositories, explain library internals, or find usage examples in open source.",
     mode: "subagent" as const,
     model,
     temperature: 0.1,
-    tools: { write: false, edit: false, background_task: false },
+    ...restrictions,
     prompt: `# THE LIBRARIAN
 
 You are **THE LIBRARIAN**, a specialized open-source codebase understanding agent.
@@ -32,10 +57,10 @@ Classify EVERY request into one of these categories before taking action:
 
 | Type | Trigger Examples | Tools |
 |------|------------------|-------|
-| **TYPE A: CONCEPTUAL** | "How do I use X?", "Best practice for Y?" | context7 + websearch_exa (parallel) |
+| **TYPE A: CONCEPTUAL** | "How do I use X?", "Best practice for Y?" | context7 + web search (if available) in parallel |
 | **TYPE B: IMPLEMENTATION** | "How does X implement Y?", "Show me source of Z" | gh clone + read + blame |
-| **TYPE C: CONTEXT** | "Why was this changed?", "History of X?" | gh issues/prs + git log/blame |
-| **TYPE D: COMPREHENSIVE** | Complex/ambiguous requests | ALL tools in parallel |
+| **TYPE C: CONTEXT** | "Why was this changed?", "What's the history?", "Related issues/PRs?" | gh issues/prs + git log/blame |
+| **TYPE D: COMPREHENSIVE** | Complex/ambiguous requests | ALL available tools in parallel |
 
 ---
 
@@ -44,12 +69,12 @@ Classify EVERY request into one of these categories before taking action:
 ### TYPE A: CONCEPTUAL QUESTION
 **Trigger**: "How do I...", "What is...", "Best practice for...", rough/general questions
 
-**Execute in parallel (3+ calls)**:
+**Execute in parallel (2+ calls)**:
 \`\`\`
 Tool 1: context7_resolve-library-id("library-name")
         → then context7_get-library-docs(id, topic: "specific-topic")
-Tool 2: websearch_exa_web_search_exa("library-name topic 2025")
-Tool 3: grep_app_searchGitHub(query: "usage pattern", language: ["TypeScript"])
+Tool 2: grep_app_searchGitHub(query: "usage pattern", language: ["TypeScript"])
+Tool 3 (optional): If web search is available, search "library-name topic 2025"
 \`\`\`
 
 **Output**: Summarize findings with links to official docs and real-world examples.
@@ -111,21 +136,22 @@ gh api repos/owner/repo/pulls/<number>/files
 ### TYPE D: COMPREHENSIVE RESEARCH
 **Trigger**: Complex questions, ambiguous requests, "deep dive into..."
 
-**Execute ALL in parallel (6+ calls)**:
+**Execute ALL available tools in parallel (5+ calls)**:
 \`\`\`
-// Documentation & Web
+// Documentation
 Tool 1: context7_resolve-library-id → context7_get-library-docs
-Tool 2: websearch_exa_web_search_exa("topic recent updates")
 
 // Code Search
-Tool 3: grep_app_searchGitHub(query: "pattern1", language: [...])
-Tool 4: grep_app_searchGitHub(query: "pattern2", useRegexp: true)
+Tool 2: grep_app_searchGitHub(query: "pattern1", language: [...])
+Tool 3: grep_app_searchGitHub(query: "pattern2", useRegexp: true)
 
 // Source Analysis
-Tool 5: gh repo clone owner/repo \${TMPDIR:-/tmp}/repo -- --depth 1
+Tool 4: gh repo clone owner/repo \${TMPDIR:-/tmp}/repo -- --depth 1
 
 // Context
-Tool 6: gh search issues "topic" --repo owner/repo
+Tool 5: gh search issues "topic" --repo owner/repo
+
+// Optional: If web search is available, search for recent updates
 \`\`\`
 
 ---
@@ -171,7 +197,6 @@ https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQue
 | Purpose | Tool | Command/Usage |
 |---------|------|---------------|
 | **Official Docs** | context7 | \`context7_resolve-library-id\` → \`context7_get-library-docs\` |
-| **Latest Info** | websearch_exa | \`websearch_exa_web_search_exa("query 2025")\` |
 | **Fast Code Search** | grep_app | \`grep_app_searchGitHub(query, language, useRegexp)\` |
 | **Deep Code Search** | gh CLI | \`gh search code "query" --repo owner/repo\` |
 | **Clone Repo** | gh CLI | \`gh repo clone owner/repo \${TMPDIR:-/tmp}/name -- --depth 1\` |
@@ -180,6 +205,7 @@ https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQue
 | **Release Info** | gh CLI | \`gh api repos/owner/repo/releases/latest\` |
 | **Git History** | git | \`git log\`, \`git blame\`, \`git show\` |
 | **Read URL** | webfetch | \`webfetch(url)\` for blog posts, SO threads |
+| **Web Search** | (if available) | Use any available web search tool for latest info |
 
 ### Temp Directory
 

src/agents/multimodal-looker.ts

@@ -1,17 +1,33 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
+import { createAgentToolRestrictions } from "../shared/permission-compat"
 
 const DEFAULT_MODEL = "google/gemini-3-flash"
 
+export const MULTIMODAL_LOOKER_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "utility",
+  cost: "CHEAP",
+  promptAlias: "Multimodal Looker",
+  triggers: [],
+}
+
 export function createMultimodalLookerAgent(
   model: string = DEFAULT_MODEL
 ): AgentConfig {
+  const restrictions = createAgentToolRestrictions([
+    "write",
+    "edit",
+    "bash",
+    "background_task",
+  ])
+
   return {
     description:
       "Analyze media files (PDFs, images, diagrams) that require interpretation beyond raw text. Extracts specific information or summaries from documents, describes visual content. Use when you need analyzed/extracted data rather than literal file contents.",
     mode: "subagent" as const,
     model,
     temperature: 0.1,
-    tools: { write: false, edit: false, bash: false, background_task: false },
+    ...restrictions,
     prompt: `You interpret media files that cannot be read as plain text.
 
 Your job: examine the attached file and extract ONLY what was requested.

src/agents/oracle.ts

@@ -1,8 +1,36 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 import { isGptModel } from "./types"
+import { createAgentToolRestrictions } from "../shared/permission-compat"
 
 const DEFAULT_MODEL = "openai/gpt-5.2"
 
+export const ORACLE_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "advisor",
+  cost: "EXPENSIVE",
+  promptAlias: "Oracle",
+  triggers: [
+    { domain: "Architecture decisions", trigger: "Multi-system tradeoffs, unfamiliar patterns" },
+    { domain: "Self-review", trigger: "After completing significant implementation" },
+    { domain: "Hard debugging", trigger: "After 2+ failed fix attempts" },
+  ],
+  useWhen: [
+    "Complex architecture design",
+    "After completing significant work",
+    "2+ failed fix attempts",
+    "Unfamiliar code patterns",
+    "Security/performance concerns",
+    "Multi-system tradeoffs",
+  ],
+  avoidWhen: [
+    "Simple file operations (use direct tools)",
+    "First attempt at any fix (try yourself first)",
+    "Questions answerable from code you've read",
+    "Trivial decisions (variable names, formatting)",
+    "Things you can infer from existing code patterns",
+  ],
+}
+
 const ORACLE_SYSTEM_PROMPT = `You are a strategic technical advisor with deep reasoning capabilities, operating as a specialized consultant within an AI-assisted development environment.
 
 ## Context
@@ -70,21 +98,28 @@ Organize your final answer in three tiers:
 Your response goes directly to the user with no intermediate processing. Make your final message self-contained: a clear recommendation they can act on immediately, covering both what to do and why.`
 
 export function createOracleAgent(model: string = DEFAULT_MODEL): AgentConfig {
+  const restrictions = createAgentToolRestrictions([
+    "write",
+    "edit",
+    "task",
+    "background_task",
+  ])
+
   const base = {
     description:
       "Expert technical advisor with deep reasoning for architecture decisions, code analysis, and engineering guidance.",
     mode: "subagent" as const,
     model,
     temperature: 0.1,
-    tools: { write: false, edit: false, task: false, background_task: false },
+    ...restrictions,
     prompt: ORACLE_SYSTEM_PROMPT,
-  }
+  } as AgentConfig
 
   if (isGptModel(model)) {
-    return { ...base, reasoningEffort: "medium", textVerbosity: "high" }
+    return { ...base, reasoningEffort: "medium", textVerbosity: "high" } as AgentConfig
   }
 
-  return { ...base, thinking: { type: "enabled", budgetTokens: 32000 } }
+  return { ...base, thinking: { type: "enabled", budgetTokens: 32000 } } as AgentConfig
 }
 
 export const oracleAgent = createOracleAgent()

src/agents/sisyphus-prompt-builder.ts

@@ -0,0 +1,332 @@
+import type { AgentPromptMetadata, BuiltinAgentName } from "./types"
+
+export interface AvailableAgent {
+  name: BuiltinAgentName
+  description: string
+  metadata: AgentPromptMetadata
+}
+
+export interface AvailableTool {
+  name: string
+  category: "lsp" | "ast" | "search" | "session" | "command" | "other"
+}
+
+export interface AvailableSkill {
+  name: string
+  description: string
+  location: "user" | "project" | "plugin"
+}
+
+export function categorizeTools(toolNames: string[]): AvailableTool[] {
+  return toolNames.map((name) => {
+    let category: AvailableTool["category"] = "other"
+    if (name.startsWith("lsp_")) {
+      category = "lsp"
+    } else if (name.startsWith("ast_grep")) {
+      category = "ast"
+    } else if (name === "grep" || name === "glob") {
+      category = "search"
+    } else if (name.startsWith("session_")) {
+      category = "session"
+    } else if (name === "slashcommand") {
+      category = "command"
+    }
+    return { name, category }
+  })
+}
+
+function formatToolsForPrompt(tools: AvailableTool[]): string {
+  const lspTools = tools.filter((t) => t.category === "lsp")
+  const astTools = tools.filter((t) => t.category === "ast")
+  const searchTools = tools.filter((t) => t.category === "search")
+
+  const parts: string[] = []
+
+  if (searchTools.length > 0) {
+    parts.push(...searchTools.map((t) => `\`${t.name}\``))
+  }
+
+  if (lspTools.length > 0) {
+    parts.push("`lsp_*`")
+  }
+
+  if (astTools.length > 0) {
+    parts.push("`ast_grep`")
+  }
+
+  return parts.join(", ")
+}
+
+export function buildKeyTriggersSection(agents: AvailableAgent[], skills: AvailableSkill[] = []): string {
+  const keyTriggers = agents
+    .filter((a) => a.metadata.keyTrigger)
+    .map((a) => `- ${a.metadata.keyTrigger}`)
+
+  const skillTriggers = skills
+    .filter((s) => s.description)
+    .map((s) => `- **Skill \`${s.name}\`**: ${extractTriggerFromDescription(s.description)}`)
+
+  const allTriggers = [...keyTriggers, ...skillTriggers]
+
+  if (allTriggers.length === 0) return ""
+
+  return `### Key Triggers (check BEFORE classification):
+
+**BLOCKING: Check skills FIRST before any action.**
+If a skill matches, invoke it IMMEDIATELY via \`skill\` tool.
+
+${allTriggers.join("\n")}
+- **GitHub mention (@mention in issue/PR)** → This is a WORK REQUEST. Plan full cycle: investigate → implement → create PR
+- **"Look into" + "create PR"** → Not just research. Full implementation cycle expected.`
+}
+
+function extractTriggerFromDescription(description: string): string {
+  const triggerMatch = description.match(/Trigger[s]?[:\s]+([^.]+)/i)
+  if (triggerMatch) return triggerMatch[1].trim()
+
+  const activateMatch = description.match(/Activate when[:\s]+([^.]+)/i)
+  if (activateMatch) return activateMatch[1].trim()
+
+  const useWhenMatch = description.match(/Use (?:this )?when[:\s]+([^.]+)/i)
+  if (useWhenMatch) return useWhenMatch[1].trim()
+
+  return description.split(".")[0] || description
+}
+
+export function buildToolSelectionTable(
+  agents: AvailableAgent[],
+  tools: AvailableTool[] = [],
+  skills: AvailableSkill[] = []
+): string {
+  const rows: string[] = [
+    "### Tool & Skill Selection:",
+    "",
+    "**Priority Order**: Skills → Direct Tools → Agents",
+    "",
+  ]
+
+  // Skills section (highest priority)
+  if (skills.length > 0) {
+    rows.push("#### Skills (INVOKE FIRST if matching)")
+    rows.push("")
+    rows.push("| Skill | When to Use |")
+    rows.push("|-------|-------------|")
+    for (const skill of skills) {
+      const shortDesc = extractTriggerFromDescription(skill.description)
+      rows.push(`| \`${skill.name}\` | ${shortDesc} |`)
+    }
+    rows.push("")
+  }
+
+  // Tools and Agents table
+  rows.push("#### Tools & Agents")
+  rows.push("")
+  rows.push("| Resource | Cost | When to Use |")
+  rows.push("|----------|------|-------------|")
+
+  if (tools.length > 0) {
+    const toolsDisplay = formatToolsForPrompt(tools)
+    rows.push(`| ${toolsDisplay} | FREE | Not Complex, Scope Clear, No Implicit Assumptions |`)
+  }
+
+  const costOrder = { FREE: 0, CHEAP: 1, EXPENSIVE: 2 }
+  const sortedAgents = [...agents]
+    .filter((a) => a.metadata.category !== "utility")
+    .sort((a, b) => costOrder[a.metadata.cost] - costOrder[b.metadata.cost])
+
+  for (const agent of sortedAgents) {
+    const shortDesc = agent.description.split(".")[0] || agent.description
+    rows.push(`| \`${agent.name}\` agent | ${agent.metadata.cost} | ${shortDesc} |`)
+  }
+
+  rows.push("")
+  rows.push("**Default flow**: skill (if match) → explore/librarian (background) + tools → oracle (if required)")
+
+  return rows.join("\n")
+}
+
+export function buildExploreSection(agents: AvailableAgent[]): string {
+  const exploreAgent = agents.find((a) => a.name === "explore")
+  if (!exploreAgent) return ""
+
+  const useWhen = exploreAgent.metadata.useWhen || []
+  const avoidWhen = exploreAgent.metadata.avoidWhen || []
+
+  return `### Explore Agent = Contextual Grep
+
+Use it as a **peer tool**, not a fallback. Fire liberally.
+
+| Use Direct Tools | Use Explore Agent |
+|------------------|-------------------|
+${avoidWhen.map((w) => `| ${w} |  |`).join("\n")}
+${useWhen.map((w) => `|  | ${w} |`).join("\n")}`
+}
+
+export function buildLibrarianSection(agents: AvailableAgent[]): string {
+  const librarianAgent = agents.find((a) => a.name === "librarian")
+  if (!librarianAgent) return ""
+
+  const useWhen = librarianAgent.metadata.useWhen || []
+
+  return `### Librarian Agent = Reference Grep
+
+Search **external references** (docs, OSS, web). Fire proactively when unfamiliar libraries are involved.
+
+| Contextual Grep (Internal) | Reference Grep (External) |
+|----------------------------|---------------------------|
+| Search OUR codebase | Search EXTERNAL resources |
+| Find patterns in THIS repo | Find examples in OTHER repos |
+| How does our code work? | How does this library work? |
+| Project-specific logic | Official API documentation |
+| | Library best practices & quirks |
+| | OSS implementation examples |
+
+**Trigger phrases** (fire librarian immediately):
+${useWhen.map((w) => `- "${w}"`).join("\n")}`
+}
+
+export function buildDelegationTable(agents: AvailableAgent[]): string {
+  const rows: string[] = [
+    "### Delegation Table:",
+    "",
+    "| Domain | Delegate To | Trigger |",
+    "|--------|-------------|---------|",
+  ]
+
+  for (const agent of agents) {
+    for (const trigger of agent.metadata.triggers) {
+      rows.push(`| ${trigger.domain} | \`${agent.name}\` | ${trigger.trigger} |`)
+    }
+  }
+
+  return rows.join("\n")
+}
+
+export function buildFrontendSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+  if (!frontendAgent) return ""
+
+  return `### Frontend Files: Decision Gate (NOT a blind block)
+
+Frontend files (.tsx, .jsx, .vue, .svelte, .css, etc.) require **classification before action**.
+
+#### Step 1: Classify the Change Type
+
+| Change Type | Examples | Action |
+|-------------|----------|--------|
+| **Visual/UI/UX** | Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images | **DELEGATE** to \`frontend-ui-ux-engineer\` |
+| **Pure Logic** | API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic | **CAN handle directly** |
+| **Mixed** | Component changes both visual AND logic | **Split**: handle logic yourself, delegate visual to \`frontend-ui-ux-engineer\` |
+
+#### Step 2: Ask Yourself
+
+Before touching any frontend file, think:
+> "Is this change about **how it LOOKS** or **how it WORKS**?"
+
+- **LOOKS** (colors, sizes, positions, animations) → DELEGATE
+- **WORKS** (data flow, API integration, state) → Handle directly
+
+#### When in Doubt → DELEGATE if ANY of these keywords involved:
+style, className, tailwind, color, background, border, shadow, margin, padding, width, height, flex, grid, animation, transition, hover, responsive, font-size, icon, svg`
+}
+
+export function buildOracleSection(agents: AvailableAgent[]): string {
+  const oracleAgent = agents.find((a) => a.name === "oracle")
+  if (!oracleAgent) return ""
+
+  const useWhen = oracleAgent.metadata.useWhen || []
+  const avoidWhen = oracleAgent.metadata.avoidWhen || []
+
+  return `<Oracle_Usage>
+## Oracle — Your Senior Engineering Advisor (GPT-5.2)
+
+Oracle is an expensive, high-quality reasoning model. Use it wisely.
+
+### WHEN to Consult:
+
+| Trigger | Action |
+|---------|--------|
+${useWhen.map((w) => `| ${w} | Oracle FIRST, then implement |`).join("\n")}
+
+### WHEN NOT to Consult:
+
+${avoidWhen.map((w) => `- ${w}`).join("\n")}
+
+### Usage Pattern:
+Briefly announce "Consulting Oracle for [reason]" before invocation.
+
+**Exception**: This is the ONLY case where you announce before acting. For all other work, start immediately without status updates.
+</Oracle_Usage>`
+}
+
+export function buildHardBlocksSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+
+  const blocks = [
+    "| Type error suppression (`as any`, `@ts-ignore`) | Never |",
+    "| Commit without explicit request | Never |",
+    "| Speculate about unread code | Never |",
+    "| Leave code in broken state after failures | Never |",
+  ]
+
+  if (frontendAgent) {
+    blocks.unshift(
+      "| Frontend VISUAL changes (styling, layout, animation) | Always delegate to `frontend-ui-ux-engineer` |"
+    )
+  }
+
+  return `## Hard Blocks (NEVER violate)
+
+| Constraint | No Exceptions |
+|------------|---------------|
+${blocks.join("\n")}`
+}
+
+export function buildAntiPatternsSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+
+  const patterns = [
+    "| **Type Safety** | `as any`, `@ts-ignore`, `@ts-expect-error` |",
+    "| **Error Handling** | Empty catch blocks `catch(e) {}` |",
+    "| **Testing** | Deleting failing tests to \"pass\" |",
+    "| **Search** | Firing agents for single-line typos or obvious syntax errors |",
+    "| **Debugging** | Shotgun debugging, random changes |",
+  ]
+
+  if (frontendAgent) {
+    patterns.splice(
+      4,
+      0,
+      "| **Frontend** | Direct edit to visual/styling code (logic changes OK) |"
+    )
+  }
+
+  return `## Anti-Patterns (BLOCKING violations)
+
+| Category | Forbidden |
+|----------|-----------|
+${patterns.join("\n")}`
+}
+
+export function buildUltraworkAgentSection(agents: AvailableAgent[]): string {
+  if (agents.length === 0) return ""
+
+  const ultraworkAgentPriority = ["explore", "librarian", "plan", "oracle"]
+  const sortedAgents = [...agents].sort((a, b) => {
+    const aIdx = ultraworkAgentPriority.indexOf(a.name)
+    const bIdx = ultraworkAgentPriority.indexOf(b.name)
+    if (aIdx === -1 && bIdx === -1) return 0
+    if (aIdx === -1) return 1
+    if (bIdx === -1) return -1
+    return aIdx - bIdx
+  })
+
+  const lines: string[] = []
+  for (const agent of sortedAgents) {
+    const shortDesc = agent.description.split(".")[0] || agent.description
+    const suffix = (agent.name === "explore" || agent.name === "librarian") ? " (multiple)" : ""
+    lines.push(`- **${agent.name}${suffix}**: ${shortDesc}`)
+  }
+
+  return lines.join("\n")
+}

src/agents/sisyphus.ts

@@ -1,9 +1,22 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
 import { isGptModel } from "./types"
+import type { AvailableAgent, AvailableTool, AvailableSkill } from "./sisyphus-prompt-builder"
+import {
+  buildKeyTriggersSection,
+  buildToolSelectionTable,
+  buildExploreSection,
+  buildLibrarianSection,
+  buildDelegationTable,
+  buildFrontendSection,
+  buildOracleSection,
+  buildHardBlocksSection,
+  buildAntiPatternsSection,
+  categorizeTools,
+} from "./sisyphus-prompt-builder"
 
 const DEFAULT_MODEL = "anthropic/claude-opus-4-5"
 
-const SISYPHUS_SYSTEM_PROMPT = `<Role>
+const SISYPHUS_ROLE_SECTION = `<Role>
 You are "Sisyphus" - Powerful AI Agent with orchestration capabilities from OhMyOpenCode.
 Named by [YeonGyu Kim](https://github.com/code-yeongyu).
 
@@ -21,22 +34,27 @@ Named by [YeonGyu Kim](https://github.com/code-yeongyu).
 
 **Operating Mode**: You NEVER work alone when specialists are available. Frontend work → delegate. Deep research → parallel background agents (async subagents). Complex architecture → consult Oracle.
 
-</Role>
+</Role>`
 
-<Behavior_Instructions>
+const SISYPHUS_PHASE0_STEP1_3 = `### Step 0: Check Skills FIRST (BLOCKING)
 
-## Phase 0 - Intent Gate (EVERY message)
+**Before ANY classification or action, scan for matching skills.**
 
-### Key Triggers (check BEFORE classification):
-- External library/source mentioned → fire \`librarian\` background
-- 2+ modules involved → fire \`explore\` background
-- **GitHub mention (@mention in issue/PR)** → This is a WORK REQUEST. Plan full cycle: investigate → implement → create PR
-- **"Look into" + "create PR"** → Not just research. Full implementation cycle expected.
+\`\`\`
+IF request matches a skill trigger:
+  → INVOKE skill tool IMMEDIATELY
+  → Do NOT proceed to Step 1 until skill is invoked
+\`\`\`
+
+Skills are specialized workflows. When relevant, they handle the task better than manual orchestration.
+
+---
 
 ### Step 1: Classify Request Type
 
 | Type | Signal | Action |
 |------|--------|--------|
+| **Skill Match** | Matches skill trigger phrase | **INVOKE skill FIRST** via \`skill\` tool |
 | **Trivial** | Single file, known location, direct answer | Direct tools only (UNLESS Key Trigger applies) |
 | **Explicit** | Specific file/line, clear command | Execute directly |
 | **Exploratory** | "How does X work?", "Find Y" | Fire explore (1-3) + tools in parallel |
@@ -78,11 +96,9 @@ Then: Raise your concern concisely. Propose an alternative. Ask if they want to
 I notice [observation]. This might cause [problem] because [reason].
 Alternative: [your suggestion].
 Should I proceed with your original request, or try the alternative?
-\`\`\`
+\`\`\``
 
----
-
-## Phase 1 - Codebase Assessment (for Open-ended tasks)
+const SISYPHUS_PHASE1 = `## Phase 1 - Codebase Assessment (for Open-ended tasks)
 
 Before following existing patterns, assess whether they're worth following.
 
@@ -103,54 +119,9 @@ Before following existing patterns, assess whether they're worth following.
 IMPORTANT: If codebase appears undisciplined, verify before assuming:
 - Different patterns may serve different purposes (intentional)
 - Migration might be in progress
-- You might be looking at the wrong reference files
+- You might be looking at the wrong reference files`
 
----
-
-## Phase 2A - Exploration & Research
-
-### Tool Selection:
-
-| Tool | Cost | When to Use |
-|------|------|-------------|
-| \`grep\`, \`glob\`, \`lsp_*\`, \`ast_grep\` | FREE | Not Complex, Scope Clear, No Implicit Assumptions |
-| \`explore\` agent | FREE | Multiple search angles, unfamiliar modules, cross-layer patterns |
-| \`librarian\` agent | CHEAP | External docs, GitHub examples, OpenSource Implementations, OSS reference |
-| \`oracle\` agent | EXPENSIVE | Architecture, review, debugging after 2+ failures |
-
-**Default flow**: explore/librarian (background) + tools → oracle (if required)
-
-### Explore Agent = Contextual Grep
-
-Use it as a **peer tool**, not a fallback. Fire liberally.
-
-| Use Direct Tools | Use Explore Agent |
-|------------------|-------------------|
-| You know exactly what to search | Multiple search angles needed |
-| Single keyword/pattern suffices | Unfamiliar module structure |
-| Known file location | Cross-layer pattern discovery |
-
-### Librarian Agent = Reference Grep
-
-Search **external references** (docs, OSS, web). Fire proactively when unfamiliar libraries are involved.
-
-| Contextual Grep (Internal) | Reference Grep (External) |
-|----------------------------|---------------------------|
-| Search OUR codebase | Search EXTERNAL resources |
-| Find patterns in THIS repo | Find examples in OTHER repos |
-| How does our code work? | How does this library work? |
-| Project-specific logic | Official API documentation |
-| | Library best practices & quirks |
-| | OSS implementation examples |
-
-**Trigger phrases** (fire librarian immediately):
-- "How do I use [library]?"
-- "What's the best practice for [framework feature]?"
-- "Why does [external dependency] behave this way?"
-- "Find examples of [library] usage"
-- Working with unfamiliar npm/pip/cargo packages
-
-### Parallel Execution (DEFAULT behavior)
+const SISYPHUS_PARALLEL_EXECUTION = `### Parallel Execution (DEFAULT behavior)
 
 **Explore/Librarian = Grep, not consultants.
 
@@ -182,64 +153,16 @@ STOP searching when:
 - 2 search iterations yielded no new useful data
 - Direct answer found
 
-**DO NOT over-explore. Time is precious.**
+**DO NOT over-explore. Time is precious.**`
 
----
-
-## Phase 2B - Implementation
+const SISYPHUS_PHASE2B_PRE_IMPLEMENTATION = `## Phase 2B - Implementation
 
 ### Pre-Implementation:
 1. If task has 2+ steps → Create todo list IMMEDIATELY, IN SUPER DETAIL. No announcements—just create it.
 2. Mark current task \`in_progress\` before starting
-3. Mark \`completed\` as soon as done (don't batch) - OBSESSIVELY TRACK YOUR WORK USING TODO TOOLS
+3. Mark \`completed\` as soon as done (don't batch) - OBSESSIVELY TRACK YOUR WORK USING TODO TOOLS`
 
-### Frontend Files: Decision Gate (NOT a blind block)
-
-Frontend files (.tsx, .jsx, .vue, .svelte, .css, etc.) require **classification before action**.
-
-#### Step 1: Classify the Change Type
-
-| Change Type | Examples | Action |
-|-------------|----------|--------|
-| **Visual/UI/UX** | Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images | **DELEGATE** to \`frontend-ui-ux-engineer\` |
-| **Pure Logic** | API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic | **CAN handle directly** |
-| **Mixed** | Component changes both visual AND logic | **Split**: handle logic yourself, delegate visual to \`frontend-ui-ux-engineer\` |
-
-#### Step 2: Ask Yourself
-
-Before touching any frontend file, think:
-> "Is this change about **how it LOOKS** or **how it WORKS**?"
-
-- **LOOKS** (colors, sizes, positions, animations) → DELEGATE
-- **WORKS** (data flow, API integration, state) → Handle directly
-
-#### Quick Reference Examples
-
-| File | Change | Type | Action |
-|------|--------|------|--------|
-| \`Button.tsx\` | Change color blue→green | Visual | DELEGATE |
-| \`Button.tsx\` | Add onClick API call | Logic | Direct |
-| \`UserList.tsx\` | Add loading spinner animation | Visual | DELEGATE |
-| \`UserList.tsx\` | Fix pagination logic bug | Logic | Direct |
-| \`Modal.tsx\` | Make responsive for mobile | Visual | DELEGATE |
-| \`Modal.tsx\` | Add form validation logic | Logic | Direct |
-
-#### When in Doubt → DELEGATE if ANY of these keywords involved:
-style, className, tailwind, color, background, border, shadow, margin, padding, width, height, flex, grid, animation, transition, hover, responsive, font-size, icon, svg
-
-### Delegation Table:
-
-| Domain | Delegate To | Trigger |
-|--------|-------------|---------|
-| Explore | \`explore\` | Find existing codebase structure, patterns and styles |
-| Frontend UI/UX | \`frontend-ui-ux-engineer\` | Visual changes only (styling, layout, animation). Pure logic changes in frontend files → handle directly |
-| Librarian | \`librarian\` | Unfamiliar packages / libraries, struggles at weird behaviour (to find existing implementation of opensource) |
-| Documentation | \`document-writer\` | README, API docs, guides |
-| Architecture decisions | \`oracle\` | Multi-system tradeoffs, unfamiliar patterns |
-| Self-review | \`oracle\` | After completing significant implementation |
-| Hard debugging | \`oracle\` | After 2+ failed fix attempts |
-
-### Delegation Prompt Structure (MANDATORY - ALL 7 sections):
+const SISYPHUS_DELEGATION_PROMPT_STRUCTURE = `### Delegation Prompt Structure (MANDATORY - ALL 7 sections):
 
 When delegating, your prompt MUST include:
 
@@ -259,9 +182,9 @@ AFTER THE WORK YOU DELEGATED SEEMS DONE, ALWAYS VERIFY THE RESULTS AS FOLLOWING:
 - EXPECTED RESULT CAME OUT?
 - DID THE AGENT FOLLOWED "MUST DO" AND "MUST NOT DO" REQUIREMENTS?
 
-**Vague prompts = rejected. Be exhaustive.**
+**Vague prompts = rejected. Be exhaustive.**`
 
-### GitHub Workflow (CRITICAL - When mentioned in issues/PRs):
+const SISYPHUS_GITHUB_WORKFLOW = `### GitHub Workflow (CRITICAL - When mentioned in issues/PRs):
 
 When you're mentioned in GitHub issues or asked to "look into" something and "create PR":
 
@@ -294,9 +217,9 @@ When you're mentioned in GitHub issues or asked to "look into" something and "cr
 **EMPHASIS**: "Look into" does NOT mean "just investigate and report back." 
 It means "investigate, understand, implement a solution, and create a PR."
 
-**If the user says "look into X and create PR", they expect a PR, not just analysis.**
+**If the user says "look into X and create PR", they expect a PR, not just analysis.**`
 
-### Code Changes:
+const SISYPHUS_CODE_CHANGES = `### Code Changes:
 - Match existing patterns (if codebase is disciplined)
 - Propose approach first (if codebase is chaotic)
 - Never suppress type errors with \`as any\`, \`@ts-ignore\`, \`@ts-expect-error\`
@@ -322,11 +245,9 @@ If project has build/test commands, run them at task completion.
 | Test run | Pass (or explicit note of pre-existing failures) |
 | Delegation | Agent result received and verified |
 
-**NO EVIDENCE = NOT COMPLETE.**
+**NO EVIDENCE = NOT COMPLETE.**`
 
----
-
-## Phase 2C - Failure Recovery
+const SISYPHUS_PHASE2C = `## Phase 2C - Failure Recovery
 
 ### When Fixes Fail:
 
@@ -342,11 +263,9 @@ If project has build/test commands, run them at task completion.
 4. **CONSULT** Oracle with full failure context
 5. If Oracle cannot resolve → **ASK USER** before proceeding
 
-**Never**: Leave code in broken state, continue hoping it'll work, delete failing tests to "pass"
+**Never**: Leave code in broken state, continue hoping it'll work, delete failing tests to "pass"`
 
----
-
-## Phase 3 - Completion
+const SISYPHUS_PHASE3 = `## Phase 3 - Completion
 
 A task is complete when:
 - [ ] All planned todo items marked done
@@ -361,41 +280,9 @@ If verification fails:
 
 ### Before Delivering Final Answer:
 - Cancel ALL running background tasks: \`background_cancel(all=true)\`
-- This conserves resources and ensures clean workflow completion
+- This conserves resources and ensures clean workflow completion`
 
-</Behavior_Instructions>
-
-<Oracle_Usage>
-## Oracle — Your Senior Engineering Advisor (GPT-5.2)
-
-Oracle is an expensive, high-quality reasoning model. Use it wisely.
-
-### WHEN to Consult:
-
-| Trigger | Action |
-|---------|--------|
-| Complex architecture design | Oracle FIRST, then implement |
-| After completing significant work | Oracle review before marking complete |
-| 2+ failed fix attempts | Oracle for debugging guidance |
-| Unfamiliar code patterns | Oracle to explain behavior |
-| Security/performance concerns | Oracle for analysis |
-| Multi-system tradeoffs | Oracle for architectural decision |
-
-### WHEN NOT to Consult:
-
-- Simple file operations (use direct tools)
-- First attempt at any fix (try yourself first)
-- Questions answerable from code you've read
-- Trivial decisions (variable names, formatting)
-- Things you can infer from existing code patterns
-
-### Usage Pattern:
-Briefly announce "Consulting Oracle for [reason]" before invocation.
-
-**Exception**: This is the ONLY case where you announce before acting. For all other work, start immediately without status updates.
-</Oracle_Usage>
-
-<Task_Management>
+const SISYPHUS_TASK_MANAGEMENT = `<Task_Management>
 ## Todo Management (CRITICAL)
 
 **DEFAULT BEHAVIOR**: Create todos BEFORE starting any non-trivial task. This is your PRIMARY coordination mechanism.
@@ -450,9 +337,9 @@ I want to make sure I understand correctly.
 
 Should I proceed with [recommendation], or would you prefer differently?
 \`\`\`
-</Task_Management>
+</Task_Management>`
 
-<Tone_and_Style>
+const SISYPHUS_TONE_AND_STYLE = `<Tone_and_Style>
 ## Communication Style
 
 ### Be Concise
@@ -492,31 +379,9 @@ If the user's approach seems problematic:
 - If user is terse, be terse
 - If user wants detail, provide detail
 - Adapt to their communication preference
-</Tone_and_Style>
+</Tone_and_Style>`
 
-<Constraints>
-## Hard Blocks (NEVER violate)
-
-| Constraint | No Exceptions |
-|------------|---------------|
-| Frontend VISUAL changes (styling, layout, animation) | Always delegate to \`frontend-ui-ux-engineer\` |
-| Type error suppression (\`as any\`, \`@ts-ignore\`) | Never |
-| Commit without explicit request | Never |
-| Speculate about unread code | Never |
-| Leave code in broken state after failures | Never |
-
-## Anti-Patterns (BLOCKING violations)
-
-| Category | Forbidden |
-|----------|-----------|
-| **Type Safety** | \`as any\`, \`@ts-ignore\`, \`@ts-expect-error\` |
-| **Error Handling** | Empty catch blocks \`catch(e) {}\` |
-| **Testing** | Deleting failing tests to "pass" |
-| **Search** | Firing agents for single-line typos or obvious syntax errors |
-| **Frontend** | Direct edit to visual/styling code (logic changes OK) |
-| **Debugging** | Shotgun debugging, random changes |
-
-## Soft Guidelines
+const SISYPHUS_SOFT_GUIDELINES = `## Soft Guidelines
 
 - Prefer existing libraries over new dependencies
 - Prefer small, focused changes over large refactors
@@ -525,14 +390,107 @@ If the user's approach seems problematic:
 
 `
 
-export function createSisyphusAgent(model: string = DEFAULT_MODEL): AgentConfig {
+function buildDynamicSisyphusPrompt(
+  availableAgents: AvailableAgent[],
+  availableTools: AvailableTool[] = [],
+  availableSkills: AvailableSkill[] = []
+): string {
+  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
+  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
+  const exploreSection = buildExploreSection(availableAgents)
+  const librarianSection = buildLibrarianSection(availableAgents)
+  const frontendSection = buildFrontendSection(availableAgents)
+  const delegationTable = buildDelegationTable(availableAgents)
+  const oracleSection = buildOracleSection(availableAgents)
+  const hardBlocks = buildHardBlocksSection(availableAgents)
+  const antiPatterns = buildAntiPatternsSection(availableAgents)
+
+  const sections = [
+    SISYPHUS_ROLE_SECTION,
+    "<Behavior_Instructions>",
+    "",
+    "## Phase 0 - Intent Gate (EVERY message)",
+    "",
+    keyTriggers,
+    "",
+    SISYPHUS_PHASE0_STEP1_3,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE1,
+    "",
+    "---",
+    "",
+    "## Phase 2A - Exploration & Research",
+    "",
+    toolSelection,
+    "",
+    exploreSection,
+    "",
+    librarianSection,
+    "",
+    SISYPHUS_PARALLEL_EXECUTION,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE2B_PRE_IMPLEMENTATION,
+    "",
+    frontendSection,
+    "",
+    delegationTable,
+    "",
+    SISYPHUS_DELEGATION_PROMPT_STRUCTURE,
+    "",
+    SISYPHUS_GITHUB_WORKFLOW,
+    "",
+    SISYPHUS_CODE_CHANGES,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE2C,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE3,
+    "",
+    "</Behavior_Instructions>",
+    "",
+    oracleSection,
+    "",
+    SISYPHUS_TASK_MANAGEMENT,
+    "",
+    SISYPHUS_TONE_AND_STYLE,
+    "",
+    "<Constraints>",
+    hardBlocks,
+    "",
+    antiPatterns,
+    "",
+    SISYPHUS_SOFT_GUIDELINES,
+  ]
+
+  return sections.filter((s) => s !== "").join("\n")
+}
+
+export function createSisyphusAgent(
+  model: string = DEFAULT_MODEL,
+  availableAgents?: AvailableAgent[],
+  availableToolNames?: string[],
+  availableSkills?: AvailableSkill[]
+): AgentConfig {
+  const tools = availableToolNames ? categorizeTools(availableToolNames) : []
+  const skills = availableSkills ?? []
+  const prompt = availableAgents
+    ? buildDynamicSisyphusPrompt(availableAgents, tools, skills)
+    : buildDynamicSisyphusPrompt([], tools, skills)
+
   const base = {
     description:
       "Sisyphus - Powerful AI orchestrator from OhMyOpenCode. Plans obsessively with todos, assesses search complexity before exploration, delegates strategically to specialized agents. Uses explore for internal code (parallel-friendly), librarian only for external docs, and always delegates UI work to frontend engineer.",
     mode: "primary" as const,
     model,
     maxTokens: 64000,
-    prompt: SISYPHUS_SYSTEM_PROMPT,
+    prompt,
     color: "#00CED1",
   }
 

src/agents/types.ts

@@ -2,6 +2,56 @@ import type { AgentConfig } from "@opencode-ai/sdk"
 
 export type AgentFactory = (model?: string) => AgentConfig
 
+/**
+ * Agent category for grouping in Sisyphus prompt sections
+ */
+export type AgentCategory = "exploration" | "specialist" | "advisor" | "utility"
+
+/**
+ * Cost classification for Tool Selection table
+ */
+export type AgentCost = "FREE" | "CHEAP" | "EXPENSIVE"
+
+/**
+ * Delegation trigger for Sisyphus prompt's Delegation Table
+ */
+export interface DelegationTrigger {
+  /** Domain of work (e.g., "Frontend UI/UX") */
+  domain: string
+  /** When to delegate (e.g., "Visual changes only...") */
+  trigger: string
+}
+
+/**
+ * Metadata for generating Sisyphus prompt sections dynamically
+ * This allows adding/removing agents without manually updating the Sisyphus prompt
+ */
+export interface AgentPromptMetadata {
+  /** Category for grouping in prompt sections */
+  category: AgentCategory
+
+  /** Cost classification for Tool Selection table */
+  cost: AgentCost
+
+  /** Domain triggers for Delegation Table */
+  triggers: DelegationTrigger[]
+
+  /** When to use this agent (for detailed sections) */
+  useWhen?: string[]
+
+  /** When NOT to use this agent */
+  avoidWhen?: string[]
+
+  /** Optional dedicated prompt section (markdown) - for agents like Oracle that have special sections */
+  dedicatedSection?: string
+
+  /** Nickname/alias used in prompt (e.g., "Oracle" instead of "oracle") */
+  promptAlias?: string
+
+  /** Key triggers that should appear in Phase 0 (e.g., "External library mentioned → fire librarian") */
+  keyTrigger?: string
+}
+
 export function isGptModel(model: string): boolean {
   return model.startsWith("openai/") || model.startsWith("github-copilot/gpt-")
 }

src/agents/utils.ts

@@ -1,12 +1,13 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
-import type { BuiltinAgentName, AgentOverrideConfig, AgentOverrides, AgentFactory } from "./types"
+import type { BuiltinAgentName, AgentOverrideConfig, AgentOverrides, AgentFactory, AgentPromptMetadata } from "./types"
 import { createSisyphusAgent } from "./sisyphus"
-import { createOracleAgent } from "./oracle"
-import { createLibrarianAgent } from "./librarian"
-import { createExploreAgent } from "./explore"
-import { createFrontendUiUxEngineerAgent } from "./frontend-ui-ux-engineer"
-import { createDocumentWriterAgent } from "./document-writer"
-import { createMultimodalLookerAgent } from "./multimodal-looker"
+import { createOracleAgent, ORACLE_PROMPT_METADATA } from "./oracle"
+import { createLibrarianAgent, LIBRARIAN_PROMPT_METADATA } from "./librarian"
+import { createExploreAgent, EXPLORE_PROMPT_METADATA } from "./explore"
+import { createFrontendUiUxEngineerAgent, FRONTEND_PROMPT_METADATA } from "./frontend-ui-ux-engineer"
+import { createDocumentWriterAgent, DOCUMENT_WRITER_PROMPT_METADATA } from "./document-writer"
+import { createMultimodalLookerAgent, MULTIMODAL_LOOKER_PROMPT_METADATA } from "./multimodal-looker"
+import type { AvailableAgent } from "./sisyphus-prompt-builder"
 import { deepMerge } from "../shared"
 
 type AgentSource = AgentFactory | AgentConfig
@@ -21,6 +22,19 @@ const agentSources: Record<BuiltinAgentName, AgentSource> = {
   "multimodal-looker": createMultimodalLookerAgent,
 }
 
+/**
+ * Metadata for each agent, used to build Sisyphus's dynamic prompt sections
+ * (Delegation Table, Tool Selection, Key Triggers, etc.)
+ */
+const agentMetadata: Partial<Record<BuiltinAgentName, AgentPromptMetadata>> = {
+  oracle: ORACLE_PROMPT_METADATA,
+  librarian: LIBRARIAN_PROMPT_METADATA,
+  explore: EXPLORE_PROMPT_METADATA,
+  "frontend-ui-ux-engineer": FRONTEND_PROMPT_METADATA,
+  "document-writer": DOCUMENT_WRITER_PROMPT_METADATA,
+  "multimodal-looker": MULTIMODAL_LOOKER_PROMPT_METADATA,
+}
+
 function isFactory(source: AgentSource): source is AgentFactory {
   return typeof source === "function"
 }
@@ -29,18 +43,17 @@ function buildAgent(source: AgentSource, model?: string): AgentConfig {
   return isFactory(source) ? source(model) : source
 }
 
-export function createEnvContext(directory: string): string {
+/**
+ * Creates OmO-specific environment context (time, timezone, locale).
+ * Note: Working directory, platform, and date are already provided by OpenCode's system.ts,
+ * so we only include fields that OpenCode doesn't provide to avoid duplication.
+ * See: https://github.com/code-yeongyu/oh-my-opencode/issues/379
+ */
+export function createEnvContext(): string {
   const now = new Date()
   const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
   const locale = Intl.DateTimeFormat().resolvedOptions().locale
 
-  const dateStr = now.toLocaleDateString("en-US", {
-    weekday: "short",
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  })
-
   const timeStr = now.toLocaleTimeString("en-US", {
     hour: "2-digit",
     minute: "2-digit",
@@ -48,18 +61,12 @@ export function createEnvContext(directory: string): string {
     hour12: true,
   })
 
-  const platform = process.platform as "darwin" | "linux" | "win32" | string
-
   return `
-Here is some useful information about the environment you are running in:
-<env>
-  Working directory: ${directory}
-  Platform: ${platform}
-  Today's date: ${dateStr} (NOT 2024, NEVEREVER 2024)
+<omo-env>
   Current time: ${timeStr}
   Timezone: ${timezone}
   Locale: ${locale}
-</env>`
+</omo-env>`
 }
 
 function mergeAgentConfig(
@@ -83,21 +90,21 @@ export function createBuiltinAgents(
   systemDefaultModel?: string
 ): Record<string, AgentConfig> {
   const result: Record<string, AgentConfig> = {}
+  const availableAgents: AvailableAgent[] = []
 
   for (const [name, source] of Object.entries(agentSources)) {
     const agentName = name as BuiltinAgentName
 
-    if (disabledAgents.includes(agentName)) {
-      continue
-    }
+    if (agentName === "Sisyphus") continue
+    if (disabledAgents.includes(agentName)) continue
 
     const override = agentOverrides[agentName]
-    const model = override?.model ?? (agentName === "Sisyphus" ? systemDefaultModel : undefined)
+    const model = override?.model
 
     let config = buildAgent(source, model)
 
-    if ((agentName === "Sisyphus" || agentName === "librarian") && directory && config.prompt) {
-      const envContext = createEnvContext(directory)
+    if (agentName === "librarian" && directory && config.prompt) {
+      const envContext = createEnvContext()
       config = { ...config, prompt: config.prompt + envContext }
     }
 
@@ -106,6 +113,33 @@ export function createBuiltinAgents(
     }
 
     result[name] = config
+
+    const metadata = agentMetadata[agentName]
+    if (metadata) {
+      availableAgents.push({
+        name: agentName,
+        description: config.description ?? "",
+        metadata,
+      })
+    }
+  }
+
+  if (!disabledAgents.includes("Sisyphus")) {
+    const sisyphusOverride = agentOverrides["Sisyphus"]
+    const sisyphusModel = sisyphusOverride?.model ?? systemDefaultModel
+
+    let sisyphusConfig = createSisyphusAgent(sisyphusModel, availableAgents)
+
+    if (directory && sisyphusConfig.prompt) {
+      const envContext = createEnvContext()
+      sisyphusConfig = { ...sisyphusConfig, prompt: sisyphusConfig.prompt + envContext }
+    }
+
+    if (sisyphusOverride) {
+      sisyphusConfig = mergeAgentConfig(sisyphusConfig, sisyphusOverride)
+    }
+
+    result["Sisyphus"] = sisyphusConfig
   }
 
   return result

src/auth/AGENTS.md

@@ -0,0 +1,57 @@
+# AUTH KNOWLEDGE BASE
+
+## OVERVIEW
+
+Google Antigravity OAuth for Gemini models. Token management, fetch interception, thinking block extraction.
+
+## STRUCTURE
+
+```
+auth/
+└── antigravity/
+    ├── plugin.ts         # Main export, hooks registration
+    ├── oauth.ts          # OAuth flow, token acquisition
+    ├── token.ts          # Token storage, refresh logic
+    ├── fetch.ts          # Fetch interceptor (621 lines)
+    ├── response.ts       # Response transformation (598 lines)
+    ├── thinking.ts       # Thinking block extraction (571 lines)
+    ├── thought-signature-store.ts  # Signature caching
+    ├── message-converter.ts        # Format conversion
+    ├── request.ts        # Request building
+    ├── project.ts        # Project ID management
+    ├── tools.ts          # OAuth tool registration
+    ├── constants.ts      # API endpoints, model mappings
+    └── types.ts
+```
+
+## KEY COMPONENTS
+
+| File | Purpose |
+|------|---------|
+| fetch.ts | URL rewriting, token injection, retries |
+| thinking.ts | Extract `<antThinking>` blocks |
+| response.ts | Streaming SSE parsing |
+| oauth.ts | Browser-based OAuth flow |
+| token.ts | Token persistence, expiry |
+
+## HOW IT WORKS
+
+1. **Intercept**: fetch.ts intercepts Anthropic/Google requests
+2. **Rewrite**: URLs → Antigravity proxy endpoints
+3. **Auth**: Bearer token from stored OAuth credentials
+4. **Response**: Streaming parsed, thinking blocks extracted
+5. **Transform**: Normalized for OpenCode
+
+## FEATURES
+
+- Multi-account (up to 10 Google accounts)
+- Auto-fallback on rate limit
+- Thinking blocks preserved
+- Antigravity proxy for AI Studio access
+
+## ANTI-PATTERNS
+
+- Direct API calls (use fetch interceptor)
+- Tokens in code (use token.ts storage)
+- Ignoring refresh (check expiry first)
+- Blocking on OAuth (always async)

src/cli/AGENTS.md

@@ -0,0 +1,68 @@
+# CLI KNOWLEDGE BASE
+
+## OVERVIEW
+
+CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runtime launcher. Entry: `bunx oh-my-opencode`.
+
+## STRUCTURE
+
+```
+cli/
+├── index.ts              # Commander.js entry, subcommand routing
+├── install.ts            # Interactive TUI installer (477 lines)
+├── config-manager.ts     # JSONC parsing, env detection (669 lines)
+├── types.ts              # CLI-specific types
+├── doctor/               # Health check system
+│   ├── index.ts          # Doctor command entry
+│   ├── constants.ts      # Check categories
+│   ├── types.ts          # Check result interfaces
+│   └── checks/           # 17+ individual checks
+├── get-local-version/    # Version detection
+└── run/                  # OpenCode session launcher
+```
+
+## CLI COMMANDS
+
+| Command | Purpose |
+|---------|---------|
+| `install` | Interactive setup wizard |
+| `doctor` | Environment health checks |
+| `run` | Launch OpenCode session |
+
+## DOCTOR CHECKS
+
+17+ checks in `doctor/checks/`:
+- version.ts (OpenCode >= 1.0.150)
+- config.ts (plugin registered)
+- bun.ts, node.ts, git.ts
+- anthropic-auth.ts, openai-auth.ts, google-auth.ts
+- lsp-*.ts, mcp-*.ts
+
+## CONFIG-MANAGER (669 lines)
+
+- JSONC support (comments, trailing commas)
+- Multi-source: User (~/.config/opencode/) + Project (.opencode/)
+- Zod validation
+- Legacy format migration
+- Error aggregation for doctor
+
+## HOW TO ADD CHECK
+
+1. Create `src/cli/doctor/checks/my-check.ts`:
+   ```typescript
+   export const myCheck: DoctorCheck = {
+     name: "my-check",
+     category: "environment",
+     check: async () => {
+       return { status: "pass" | "warn" | "fail", message: "..." }
+     }
+   }
+   ```
+2. Add to `src/cli/doctor/checks/index.ts`
+
+## ANTI-PATTERNS
+
+- Blocking prompts in non-TTY (check `process.stdout.isTTY`)
+- Hardcoded paths (use shared utilities)
+- JSON.parse for user files (use parseJsonc)
+- Silent failures in doctor checks

src/cli/config-manager.test.ts

@@ -11,11 +11,9 @@ describe("config-manager ANTIGRAVITY_PROVIDER_CONFIG", () => {
     expect(models).toBeTruthy()
 
     const required = [
-      "gemini-3-pro-high",
-      "gemini-3-pro-medium",
-      "gemini-3-pro-low",
-      "gemini-3-flash",
-      "gemini-3-flash-lite",
+      "antigravity-gemini-3-pro-high",
+      "antigravity-gemini-3-pro-low",
+      "antigravity-gemini-3-flash",
     ]
 
     for (const key of required) {

src/cli/config-manager.ts

@@ -1,18 +1,59 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs"
-import { homedir } from "node:os"
 import { join } from "node:path"
-import { parseJsonc } from "../shared"
+import {
+  parseJsonc,
+  getOpenCodeConfigPaths,
+  type OpenCodeBinaryType,
+  type OpenCodeConfigPaths,
+} from "../shared"
 import type { ConfigMergeResult, DetectedConfig, InstallConfig } from "./types"
 
-const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
-const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
-const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
-const OPENCODE_PACKAGE_JSON = join(OPENCODE_CONFIG_DIR, "package.json")
-const OMO_CONFIG = join(OPENCODE_CONFIG_DIR, "oh-my-opencode.json")
-
 const OPENCODE_BINARIES = ["opencode", "opencode-desktop"] as const
 
-const CHATGPT_HOTFIX_REPO = "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
+interface ConfigContext {
+  binary: OpenCodeBinaryType
+  version: string | null
+  paths: OpenCodeConfigPaths
+}
+
+let configContext: ConfigContext | null = null
+
+export function initConfigContext(binary: OpenCodeBinaryType, version: string | null): void {
+  const paths = getOpenCodeConfigPaths({ binary, version })
+  configContext = { binary, version, paths }
+}
+
+export function getConfigContext(): ConfigContext {
+  if (!configContext) {
+    const paths = getOpenCodeConfigPaths({ binary: "opencode", version: null })
+    configContext = { binary: "opencode", version: null, paths }
+  }
+  return configContext
+}
+
+export function resetConfigContext(): void {
+  configContext = null
+}
+
+function getConfigDir(): string {
+  return getConfigContext().paths.configDir
+}
+
+function getConfigJson(): string {
+  return getConfigContext().paths.configJson
+}
+
+function getConfigJsonc(): string {
+  return getConfigContext().paths.configJsonc
+}
+
+function getPackageJson(): string {
+  return getConfigContext().paths.packageJson
+}
+
+function getOmoConfig(): string {
+  return getConfigContext().paths.omoConfig
+}
 
 const BUN_INSTALL_TIMEOUT_SECONDS = 60
 const BUN_INSTALL_TIMEOUT_MS = BUN_INSTALL_TIMEOUT_SECONDS * 1000
@@ -76,13 +117,16 @@ interface OpenCodeConfig {
 }
 
 export function detectConfigFormat(): { format: ConfigFormat; path: string } {
-  if (existsSync(OPENCODE_JSONC)) {
-    return { format: "jsonc", path: OPENCODE_JSONC }
+  const configJsonc = getConfigJsonc()
+  const configJson = getConfigJson()
+
+  if (existsSync(configJsonc)) {
+    return { format: "jsonc", path: configJsonc }
   }
-  if (existsSync(OPENCODE_JSON)) {
-    return { format: "json", path: OPENCODE_JSON }
+  if (existsSync(configJson)) {
+    return { format: "json", path: configJson }
   }
-  return { format: "none", path: OPENCODE_JSON }
+  return { format: "none", path: configJson }
 }
 
 interface ParseConfigResult {
@@ -129,8 +173,9 @@ function parseConfigWithError(path: string): ParseConfigResult {
 }
 
 function ensureConfigDir(): void {
-  if (!existsSync(OPENCODE_CONFIG_DIR)) {
-    mkdirSync(OPENCODE_CONFIG_DIR, { recursive: true })
+  const configDir = getConfigDir()
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true })
   }
 }
 
@@ -138,7 +183,7 @@ export function addPluginToOpenCodeConfig(): ConfigMergeResult {
   try {
     ensureConfigDir()
   } catch (err) {
-    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+    return { success: false, configPath: getConfigDir(), error: formatErrorWithSuggestion(err, "create config directory") }
   }
 
   const { format, path } = detectConfigFormat()
@@ -229,31 +274,33 @@ export function generateOmoConfig(installConfig: InstallConfig): Record<string,
   const agents: Record<string, Record<string, unknown>> = {}
 
   if (!installConfig.hasClaude) {
-    agents["Sisyphus"] = { model: "opencode/big-pickle" }
+    agents["Sisyphus"] = { model: "opencode/glm-4.7-free" }
   }
 
+  agents["librarian"] = { model: "opencode/glm-4.7-free" }
+
+  // Gemini models use `antigravity-` prefix for explicit Antigravity quota routing
+  // @see ANTIGRAVITY_PROVIDER_CONFIG comments for rationale
   if (installConfig.hasGemini) {
-    agents["librarian"] = { model: "google/gemini-3-flash" }
-    agents["explore"] = { model: "google/gemini-3-flash" }
+    agents["explore"] = { model: "google/antigravity-gemini-3-flash" }
   } else if (installConfig.hasClaude && installConfig.isMax20) {
     agents["explore"] = { model: "anthropic/claude-haiku-4-5" }
   } else {
-    agents["librarian"] = { model: "opencode/big-pickle" }
-    agents["explore"] = { model: "opencode/big-pickle" }
+    agents["explore"] = { model: "opencode/glm-4.7-free" }
   }
 
   if (!installConfig.hasChatGPT) {
     agents["oracle"] = {
-      model: installConfig.hasClaude ? "anthropic/claude-opus-4-5" : "opencode/big-pickle",
+      model: installConfig.hasClaude ? "anthropic/claude-opus-4-5" : "opencode/glm-4.7-free",
     }
   }
 
   if (installConfig.hasGemini) {
-    agents["frontend-ui-ux-engineer"] = { model: "google/gemini-3-pro-high" }
-    agents["document-writer"] = { model: "google/gemini-3-flash" }
-    agents["multimodal-looker"] = { model: "google/gemini-3-flash" }
+    agents["frontend-ui-ux-engineer"] = { model: "google/antigravity-gemini-3-pro-high" }
+    agents["document-writer"] = { model: "google/antigravity-gemini-3-flash" }
+    agents["multimodal-looker"] = { model: "google/antigravity-gemini-3-flash" }
   } else {
-    const fallbackModel = installConfig.hasClaude ? "anthropic/claude-opus-4-5" : "opencode/big-pickle"
+    const fallbackModel = installConfig.hasClaude ? "anthropic/claude-opus-4-5" : "opencode/glm-4.7-free"
     agents["frontend-ui-ux-engineer"] = { model: fallbackModel }
     agents["document-writer"] = { model: fallbackModel }
     agents["multimodal-looker"] = { model: fallbackModel }
@@ -270,50 +317,52 @@ export function writeOmoConfig(installConfig: InstallConfig): ConfigMergeResult
   try {
     ensureConfigDir()
   } catch (err) {
-    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+    return { success: false, configPath: getConfigDir(), error: formatErrorWithSuggestion(err, "create config directory") }
   }
 
+  const omoConfigPath = getOmoConfig()
+
   try {
     const newConfig = generateOmoConfig(installConfig)
 
-    if (existsSync(OMO_CONFIG)) {
+    if (existsSync(omoConfigPath)) {
       try {
-        const stat = statSync(OMO_CONFIG)
-        const content = readFileSync(OMO_CONFIG, "utf-8")
+        const stat = statSync(omoConfigPath)
+        const content = readFileSync(omoConfigPath, "utf-8")
 
         if (stat.size === 0 || isEmptyOrWhitespace(content)) {
-          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
-          return { success: true, configPath: OMO_CONFIG }
+          writeFileSync(omoConfigPath, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: omoConfigPath }
         }
 
         const existing = parseJsonc<Record<string, unknown>>(content)
         if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
-          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
-          return { success: true, configPath: OMO_CONFIG }
+          writeFileSync(omoConfigPath, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: omoConfigPath }
         }
 
         delete existing.agents
         const merged = deepMerge(existing, newConfig)
-        writeFileSync(OMO_CONFIG, JSON.stringify(merged, null, 2) + "\n")
+        writeFileSync(omoConfigPath, JSON.stringify(merged, null, 2) + "\n")
       } catch (parseErr) {
         if (parseErr instanceof SyntaxError) {
-          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
-          return { success: true, configPath: OMO_CONFIG }
+          writeFileSync(omoConfigPath, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: omoConfigPath }
         }
         throw parseErr
       }
     } else {
-      writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+      writeFileSync(omoConfigPath, JSON.stringify(newConfig, null, 2) + "\n")
     }
 
-    return { success: true, configPath: OMO_CONFIG }
+    return { success: true, configPath: omoConfigPath }
   } catch (err) {
-    return { success: false, configPath: OMO_CONFIG, error: formatErrorWithSuggestion(err, "write oh-my-opencode config") }
+    return { success: false, configPath: omoConfigPath, error: formatErrorWithSuggestion(err, "write oh-my-opencode config") }
   }
 }
 
 interface OpenCodeBinaryResult {
-  binary: string
+  binary: OpenCodeBinaryType
   version: string
 }
 
@@ -327,7 +376,9 @@ async function findOpenCodeBinaryWithVersion(): Promise<OpenCodeBinaryResult | n
       const output = await new Response(proc.stdout).text()
       await proc.exited
       if (proc.exitCode === 0) {
-        return { binary, version: output.trim() }
+        const version = output.trim()
+        initConfigContext(binary, version)
+        return { binary, version }
       }
     } catch {
       continue
@@ -350,7 +401,7 @@ export async function addAuthPlugins(config: InstallConfig): Promise<ConfigMerge
   try {
     ensureConfigDir()
   } catch (err) {
-    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+    return { success: false, configPath: getConfigDir(), error: formatErrorWithSuggestion(err, "create config directory") }
   }
 
   const { format, path } = detectConfigFormat()
@@ -390,46 +441,6 @@ export async function addAuthPlugins(config: InstallConfig): Promise<ConfigMerge
   }
 }
 
-export function setupChatGPTHotfix(): ConfigMergeResult {
-  try {
-    ensureConfigDir()
-  } catch (err) {
-    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
-  }
-
-  try {
-    let packageJson: Record<string, unknown> = {}
-    if (existsSync(OPENCODE_PACKAGE_JSON)) {
-      try {
-        const stat = statSync(OPENCODE_PACKAGE_JSON)
-        const content = readFileSync(OPENCODE_PACKAGE_JSON, "utf-8")
-
-        if (stat.size > 0 && !isEmptyOrWhitespace(content)) {
-          packageJson = JSON.parse(content)
-          if (typeof packageJson !== "object" || packageJson === null || Array.isArray(packageJson)) {
-            packageJson = {}
-          }
-        }
-      } catch (parseErr) {
-        if (parseErr instanceof SyntaxError) {
-          packageJson = {}
-        } else {
-          throw parseErr
-        }
-      }
-    }
-
-    const deps = (packageJson.dependencies ?? {}) as Record<string, string>
-    deps["opencode-openai-codex-auth"] = CHATGPT_HOTFIX_REPO
-    packageJson.dependencies = deps
-
-    writeFileSync(OPENCODE_PACKAGE_JSON, JSON.stringify(packageJson, null, 2) + "\n")
-    return { success: true, configPath: OPENCODE_PACKAGE_JSON }
-  } catch (err) {
-    return { success: false, configPath: OPENCODE_PACKAGE_JSON, error: formatErrorWithSuggestion(err, "setup ChatGPT hotfix in package.json") }
-  }
-}
-
 export interface BunInstallResult {
   success: boolean
   timedOut?: boolean
@@ -444,7 +455,7 @@ export async function runBunInstall(): Promise<boolean> {
 export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
   try {
     const proc = Bun.spawn(["bun", "install"], {
-      cwd: OPENCODE_CONFIG_DIR,
+      cwd: getConfigDir(),
       stdout: "pipe",
       stderr: "pipe",
     })
@@ -488,45 +499,44 @@ export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
   }
 }
 
+/**
+ * Antigravity Provider Configuration
+ *
+ * IMPORTANT: Model names MUST use `antigravity-` prefix for stability.
+ *
+ * The opencode-antigravity-auth plugin supports two naming conventions:
+ * - `antigravity-gemini-3-pro-high` (RECOMMENDED, explicit Antigravity quota routing)
+ * - `gemini-3-pro-high` (LEGACY, backward compatible but may break in future)
+ *
+ * Legacy names rely on Gemini CLI using `-preview` suffix for disambiguation.
+ * If Google removes `-preview`, legacy names may route to wrong quota.
+ *
+ * @see https://github.com/NoeFabris/opencode-antigravity-auth#migration-guide-v127
+ */
 export const ANTIGRAVITY_PROVIDER_CONFIG = {
   google: {
     name: "Google",
-    // NOTE: opencode-antigravity-auth expects full model specs (name/limit/modalities).
-    // If these are incomplete, models may appear but fail at runtime (e.g. 404).
     models: {
-      "gemini-3-pro-high": {
+      "antigravity-gemini-3-pro-high": {
         name: "Gemini 3 Pro High (Antigravity)",
         thinking: true,
         attachment: true,
         limit: { context: 1048576, output: 65535 },
         modalities: { input: ["text", "image", "pdf"], output: ["text"] },
       },
-      "gemini-3-pro-medium": {
-        name: "Gemini 3 Pro Medium (Antigravity)",
-        thinking: true,
-        attachment: true,
-        limit: { context: 1048576, output: 65535 },
-        modalities: { input: ["text", "image", "pdf"], output: ["text"] },
-      },
-      "gemini-3-pro-low": {
+      "antigravity-gemini-3-pro-low": {
         name: "Gemini 3 Pro Low (Antigravity)",
         thinking: true,
         attachment: true,
         limit: { context: 1048576, output: 65535 },
         modalities: { input: ["text", "image", "pdf"], output: ["text"] },
       },
-      "gemini-3-flash": {
+      "antigravity-gemini-3-flash": {
         name: "Gemini 3 Flash (Antigravity)",
         attachment: true,
         limit: { context: 1048576, output: 65536 },
         modalities: { input: ["text", "image", "pdf"], output: ["text"] },
       },
-      "gemini-3-flash-lite": {
-        name: "Gemini 3 Flash Lite (Antigravity)",
-        attachment: true,
-        limit: { context: 1048576, output: 65536 },
-        modalities: { input: ["text", "image", "pdf"], output: ["text"] },
-      },
     },
   },
 }
@@ -534,12 +544,48 @@ export const ANTIGRAVITY_PROVIDER_CONFIG = {
 const CODEX_PROVIDER_CONFIG = {
   openai: {
     name: "OpenAI",
-    api: "codex",
+    options: {
+      reasoningEffort: "medium",
+      reasoningSummary: "auto",
+      textVerbosity: "medium",
+      include: ["reasoning.encrypted_content"],
+      store: false,
+    },
     models: {
-      "gpt-5.2": { name: "GPT-5.2" },
-      "o3": { name: "o3", thinking: true },
-      "o4-mini": { name: "o4-mini", thinking: true },
-      "codex-1": { name: "Codex-1" },
+      "gpt-5.2": {
+        name: "GPT 5.2 (OAuth)",
+        limit: { context: 272000, output: 128000 },
+        modalities: { input: ["text", "image"], output: ["text"] },
+        variants: {
+          none: { reasoningEffort: "none", reasoningSummary: "auto", textVerbosity: "medium" },
+          low: { reasoningEffort: "low", reasoningSummary: "auto", textVerbosity: "medium" },
+          medium: { reasoningEffort: "medium", reasoningSummary: "auto", textVerbosity: "medium" },
+          high: { reasoningEffort: "high", reasoningSummary: "detailed", textVerbosity: "medium" },
+          xhigh: { reasoningEffort: "xhigh", reasoningSummary: "detailed", textVerbosity: "medium" },
+        },
+      },
+      "gpt-5.2-codex": {
+        name: "GPT 5.2 Codex (OAuth)",
+        limit: { context: 272000, output: 128000 },
+        modalities: { input: ["text", "image"], output: ["text"] },
+        variants: {
+          low: { reasoningEffort: "low", reasoningSummary: "auto", textVerbosity: "medium" },
+          medium: { reasoningEffort: "medium", reasoningSummary: "auto", textVerbosity: "medium" },
+          high: { reasoningEffort: "high", reasoningSummary: "detailed", textVerbosity: "medium" },
+          xhigh: { reasoningEffort: "xhigh", reasoningSummary: "detailed", textVerbosity: "medium" },
+        },
+      },
+      "gpt-5.1-codex-max": {
+        name: "GPT 5.1 Codex Max (OAuth)",
+        limit: { context: 272000, output: 128000 },
+        modalities: { input: ["text", "image"], output: ["text"] },
+        variants: {
+          low: { reasoningEffort: "low", reasoningSummary: "detailed", textVerbosity: "medium" },
+          medium: { reasoningEffort: "medium", reasoningSummary: "detailed", textVerbosity: "medium" },
+          high: { reasoningEffort: "high", reasoningSummary: "detailed", textVerbosity: "medium" },
+          xhigh: { reasoningEffort: "xhigh", reasoningSummary: "detailed", textVerbosity: "medium" },
+        },
+      },
     },
   },
 }
@@ -548,7 +594,7 @@ export function addProviderConfig(config: InstallConfig): ConfigMergeResult {
   try {
     ensureConfigDir()
   } catch (err) {
-    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+    return { success: false, configPath: getConfigDir(), error: formatErrorWithSuggestion(err, "create config directory") }
   }
 
   const { format, path } = detectConfigFormat()
@@ -622,17 +668,18 @@ export function detectCurrentConfig(): DetectedConfig {
   result.hasGemini = plugins.some((p) => p.startsWith("opencode-antigravity-auth"))
   result.hasChatGPT = plugins.some((p) => p.startsWith("opencode-openai-codex-auth"))
 
-  if (!existsSync(OMO_CONFIG)) {
+  const omoConfigPath = getOmoConfig()
+  if (!existsSync(omoConfigPath)) {
     return result
   }
 
   try {
-    const stat = statSync(OMO_CONFIG)
+    const stat = statSync(omoConfigPath)
     if (stat.size === 0) {
       return result
     }
 
-    const content = readFileSync(OMO_CONFIG, "utf-8")
+    const content = readFileSync(omoConfigPath, "utf-8")
     if (isEmptyOrWhitespace(content)) {
       return result
     }
@@ -644,17 +691,17 @@ export function detectCurrentConfig(): DetectedConfig {
 
     const agents = omoConfig.agents ?? {}
 
-    if (agents["Sisyphus"]?.model === "opencode/big-pickle") {
+    if (agents["Sisyphus"]?.model === "opencode/glm-4.7-free") {
       result.hasClaude = false
       result.isMax20 = false
-    } else if (agents["librarian"]?.model === "opencode/big-pickle") {
+    } else if (agents["librarian"]?.model === "opencode/glm-4.7-free") {
       result.hasClaude = true
       result.isMax20 = false
     }
 
     if (agents["oracle"]?.model?.startsWith("anthropic/")) {
       result.hasChatGPT = false
-    } else if (agents["oracle"]?.model === "opencode/big-pickle") {
+    } else if (agents["oracle"]?.model === "opencode/glm-4.7-free") {
       result.hasChatGPT = false
     }
 

src/cli/doctor/checks/gh.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as gh from "./gh"
+
+describe("gh cli check", () => {
+  describe("getGhCliInfo", () => {
+    it("returns gh cli info structure", async () => {
+      // #given
+      // #when checking gh cli info
+      const info = await gh.getGhCliInfo()
+
+      // #then should return valid info structure
+      expect(typeof info.installed).toBe("boolean")
+      expect(info.authenticated === true || info.authenticated === false).toBe(true)
+      expect(Array.isArray(info.scopes)).toBe(true)
+    })
+  })
+
+  describe("checkGhCli", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns warn when gh is not installed", async () => {
+      // #given gh not installed
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: false,
+        version: null,
+        path: null,
+        authenticated: false,
+        username: null,
+        scopes: [],
+        error: null,
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should warn (optional)
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("Not installed")
+      expect(result.details).toContain("Install: https://cli.github.com/")
+    })
+
+    it("returns warn when gh is installed but not authenticated", async () => {
+      // #given gh installed but not authenticated
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: true,
+        version: "2.40.0",
+        path: "/usr/local/bin/gh",
+        authenticated: false,
+        username: null,
+        scopes: [],
+        error: "not logged in",
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should warn about auth
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("2.40.0")
+      expect(result.message).toContain("not authenticated")
+      expect(result.details).toContain("Authenticate: gh auth login")
+    })
+
+    it("returns pass when gh is installed and authenticated", async () => {
+      // #given gh installed and authenticated
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: true,
+        version: "2.40.0",
+        path: "/usr/local/bin/gh",
+        authenticated: true,
+        username: "octocat",
+        scopes: ["repo", "read:org"],
+        error: null,
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("2.40.0")
+      expect(result.message).toContain("octocat")
+      expect(result.details).toContain("Account: octocat")
+      expect(result.details).toContain("Scopes: repo, read:org")
+    })
+  })
+
+  describe("getGhCliCheckDefinition", () => {
+    it("returns correct check definition", () => {
+      // #given
+      // #when getting definition
+      const def = gh.getGhCliCheckDefinition()
+
+      // #then should have correct properties
+      expect(def.id).toBe("gh-cli")
+      expect(def.name).toBe("GitHub CLI")
+      expect(def.category).toBe("tools")
+      expect(def.critical).toBe(false)
+      expect(typeof def.check).toBe("function")
+    })
+  })
+})

src/cli/doctor/checks/gh.ts

@@ -0,0 +1,171 @@
+import type { CheckResult, CheckDefinition } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+
+export interface GhCliInfo {
+  installed: boolean
+  version: string | null
+  path: string | null
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}
+
+async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
+  try {
+    const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return { exists: true, path: output.trim() }
+    }
+  } catch {
+    // intentionally empty - binary not found
+  }
+  return { exists: false, path: null }
+}
+
+async function getGhVersion(): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["gh", "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      const match = output.match(/gh version (\S+)/)
+      return match?.[1] ?? output.trim().split("\n")[0]
+    }
+  } catch {
+    // intentionally empty - version unavailable
+  }
+  return null
+}
+
+async function getGhAuthStatus(): Promise<{
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}> {
+  try {
+    const proc = Bun.spawn(["gh", "auth", "status"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GH_NO_UPDATE_NOTIFIER: "1" },
+    })
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    await proc.exited
+
+    const output = stderr || stdout
+
+    if (proc.exitCode === 0) {
+      const usernameMatch = output.match(/Logged in to github\.com account (\S+)/)
+      const username = usernameMatch?.[1]?.replace(/[()]/g, "") ?? null
+
+      const scopesMatch = output.match(/Token scopes?:\s*(.+)/i)
+      const scopes = scopesMatch?.[1]
+        ? scopesMatch[1]
+            .split(/,\s*/)
+            .map((s) => s.replace(/['"]/g, "").trim())
+            .filter(Boolean)
+        : []
+
+      return { authenticated: true, username, scopes, error: null }
+    }
+
+    const errorMatch = output.match(/error[:\s]+(.+)/i)
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: errorMatch?.[1]?.trim() ?? "Not authenticated",
+    }
+  } catch (err) {
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: err instanceof Error ? err.message : "Failed to check auth status",
+    }
+  }
+}
+
+export async function getGhCliInfo(): Promise<GhCliInfo> {
+  const binaryCheck = await checkBinaryExists("gh")
+
+  if (!binaryCheck.exists) {
+    return {
+      installed: false,
+      version: null,
+      path: null,
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: null,
+    }
+  }
+
+  const [version, authStatus] = await Promise.all([getGhVersion(), getGhAuthStatus()])
+
+  return {
+    installed: true,
+    version,
+    path: binaryCheck.path,
+    authenticated: authStatus.authenticated,
+    username: authStatus.username,
+    scopes: authStatus.scopes,
+    error: authStatus.error,
+  }
+}
+
+export async function checkGhCli(): Promise<CheckResult> {
+  const info = await getGhCliInfo()
+  const name = CHECK_NAMES[CHECK_IDS.GH_CLI]
+
+  if (!info.installed) {
+    return {
+      name,
+      status: "warn",
+      message: "Not installed (optional)",
+      details: [
+        "GitHub CLI is used by librarian agent and scripts",
+        "Install: https://cli.github.com/",
+      ],
+    }
+  }
+
+  if (!info.authenticated) {
+    return {
+      name,
+      status: "warn",
+      message: `${info.version ?? "installed"} - not authenticated`,
+      details: [
+        info.path ? `Path: ${info.path}` : null,
+        "Authenticate: gh auth login",
+        info.error ? `Error: ${info.error}` : null,
+      ].filter((d): d is string => d !== null),
+    }
+  }
+
+  const details: string[] = []
+  if (info.path) details.push(`Path: ${info.path}`)
+  if (info.username) details.push(`Account: ${info.username}`)
+  if (info.scopes.length > 0) details.push(`Scopes: ${info.scopes.join(", ")}`)
+
+  return {
+    name,
+    status: "pass",
+    message: `${info.version ?? "installed"} - authenticated as ${info.username ?? "unknown"}`,
+    details: details.length > 0 ? details : undefined,
+  }
+}
+
+export function getGhCliCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.GH_CLI,
+    name: CHECK_NAMES[CHECK_IDS.GH_CLI],
+    category: "tools",
+    check: checkGhCli,
+    critical: false,
+  }
+}

src/cli/doctor/checks/index.ts

@@ -4,6 +4,7 @@ import { getPluginCheckDefinition } from "./plugin"
 import { getConfigCheckDefinition } from "./config"
 import { getAuthCheckDefinitions } from "./auth"
 import { getDependencyCheckDefinitions } from "./dependencies"
+import { getGhCliCheckDefinition } from "./gh"
 import { getLspCheckDefinition } from "./lsp"
 import { getMcpCheckDefinitions } from "./mcp"
 import { getVersionCheckDefinition } from "./version"
@@ -13,6 +14,7 @@ export * from "./plugin"
 export * from "./config"
 export * from "./auth"
 export * from "./dependencies"
+export * from "./gh"
 export * from "./lsp"
 export * from "./mcp"
 export * from "./version"
@@ -24,6 +26,7 @@ export function getAllCheckDefinitions(): CheckDefinition[] {
     getConfigCheckDefinition(),
     ...getAuthCheckDefinitions(),
     ...getDependencyCheckDefinitions(),
+    getGhCliCheckDefinition(),
     getLspCheckDefinition(),
     ...getMcpCheckDefinitions(),
     getVersionCheckDefinition(),

src/cli/doctor/checks/mcp.test.ts

@@ -9,11 +9,10 @@ describe("mcp check", () => {
       const servers = mcp.getBuiltinMcpInfo()
 
       // #then should include expected servers
-      expect(servers.length).toBe(3)
+      expect(servers.length).toBe(2)
       expect(servers.every((s) => s.type === "builtin")).toBe(true)
       expect(servers.every((s) => s.enabled === true)).toBe(true)
       expect(servers.map((s) => s.id)).toContain("context7")
-      expect(servers.map((s) => s.id)).toContain("websearch_exa")
       expect(servers.map((s) => s.id)).toContain("grep_app")
     })
   })
@@ -37,7 +36,7 @@ describe("mcp check", () => {
 
       // #then should pass
       expect(result.status).toBe("pass")
-      expect(result.message).toContain("3")
+      expect(result.message).toContain("2")
       expect(result.message).toContain("enabled")
     })
 
@@ -48,7 +47,6 @@ describe("mcp check", () => {
 
       // #then should list servers
       expect(result.details?.some((d) => d.includes("context7"))).toBe(true)
-      expect(result.details?.some((d) => d.includes("websearch_exa"))).toBe(true)
       expect(result.details?.some((d) => d.includes("grep_app"))).toBe(true)
     })
   })

src/cli/doctor/checks/mcp.ts

@@ -5,7 +5,7 @@ import type { CheckResult, CheckDefinition, McpServerInfo } from "../types"
 import { CHECK_IDS, CHECK_NAMES } from "../constants"
 import { parseJsonc } from "../../../shared"
 
-const BUILTIN_MCP_SERVERS = ["context7", "websearch_exa", "grep_app"]
+const BUILTIN_MCP_SERVERS = ["context7", "grep_app"]
 
 const MCP_CONFIG_PATHS = [
   join(homedir(), ".claude", ".mcp.json"),

src/cli/doctor/checks/plugin.ts

@@ -1,20 +1,16 @@
 import { existsSync, readFileSync } from "node:fs"
-import { homedir } from "node:os"
-import { join } from "node:path"
 import type { CheckResult, CheckDefinition, PluginInfo } from "../types"
 import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
-import { parseJsonc } from "../../../shared"
-
-const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
-const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
-const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
+import { parseJsonc, getOpenCodeConfigPaths } from "../../../shared"
 
 function detectConfigPath(): { path: string; format: "json" | "jsonc" } | null {
-  if (existsSync(OPENCODE_JSONC)) {
-    return { path: OPENCODE_JSONC, format: "jsonc" }
+  const paths = getOpenCodeConfigPaths({ binary: "opencode", version: null })
+
+  if (existsSync(paths.configJsonc)) {
+    return { path: paths.configJsonc, format: "jsonc" }
   }
-  if (existsSync(OPENCODE_JSON)) {
-    return { path: OPENCODE_JSON, format: "json" }
+  if (existsSync(paths.configJson)) {
+    return { path: paths.configJson, format: "json" }
   }
   return null
 }
@@ -81,13 +77,14 @@ export async function checkPluginRegistration(): Promise<CheckResult> {
   const info = getPluginInfo()
 
   if (!info.configPath) {
+    const expectedPaths = getOpenCodeConfigPaths({ binary: "opencode", version: null })
     return {
       name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
       status: "fail",
       message: "OpenCode config file not found",
       details: [
         "Run: bunx oh-my-opencode install",
-        `Expected: ${OPENCODE_JSON} or ${OPENCODE_JSONC}`,
+        `Expected: ${expectedPaths.configJson} or ${expectedPaths.configJsonc}`,
       ],
     }
   }

src/cli/doctor/checks/version.ts

@@ -1,76 +1,11 @@
-import { existsSync, readFileSync } from "node:fs"
-import { homedir } from "node:os"
-import { join } from "node:path"
 import type { CheckResult, CheckDefinition, VersionCheckInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
-import { parseJsonc } from "../../../shared"
-
-const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
-const OPENCODE_PACKAGE_JSON = join(OPENCODE_CONFIG_DIR, "package.json")
-const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
-const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
-
-async function fetchLatestVersion(): Promise<string | null> {
-  try {
-    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
-      signal: AbortSignal.timeout(5000),
-    })
-    if (!res.ok) return null
-    const data = (await res.json()) as { version: string }
-    return data.version
-  } catch {
-    return null
-  }
-}
-
-function getCurrentVersion(): {
-  version: string | null
-  isLocalDev: boolean
-  isPinned: boolean
-  pinnedVersion: string | null
-} {
-  const configPath = existsSync(OPENCODE_JSONC) ? OPENCODE_JSONC : OPENCODE_JSON
-
-  if (!existsSync(configPath)) {
-    return { version: null, isLocalDev: false, isPinned: false, pinnedVersion: null }
-  }
-
-  try {
-    const content = readFileSync(configPath, "utf-8")
-    const config = parseJsonc<{ plugin?: string[] }>(content)
-    const plugins = config.plugin ?? []
-
-    for (const plugin of plugins) {
-      if (plugin.startsWith("file:") && plugin.includes(PACKAGE_NAME)) {
-        return { version: "local-dev", isLocalDev: true, isPinned: false, pinnedVersion: null }
-      }
-      if (plugin.startsWith(`${PACKAGE_NAME}@`)) {
-        const pinnedVersion = plugin.split("@")[1]
-        return { version: pinnedVersion, isLocalDev: false, isPinned: true, pinnedVersion }
-      }
-      if (plugin === PACKAGE_NAME) {
-        if (existsSync(OPENCODE_PACKAGE_JSON)) {
-          try {
-            const pkgContent = readFileSync(OPENCODE_PACKAGE_JSON, "utf-8")
-            const pkg = JSON.parse(pkgContent) as { dependencies?: Record<string, string> }
-            const depVersion = pkg.dependencies?.[PACKAGE_NAME]
-            if (depVersion) {
-              const cleanVersion = depVersion.replace(/^[\^~]/, "")
-              return { version: cleanVersion, isLocalDev: false, isPinned: false, pinnedVersion: null }
-            }
-          } catch {
-            // intentionally empty - parse errors ignored
-          }
-        }
-        return { version: null, isLocalDev: false, isPinned: false, pinnedVersion: null }
-      }
-    }
-
-    return { version: null, isLocalDev: false, isPinned: false, pinnedVersion: null }
-  } catch {
-    return { version: null, isLocalDev: false, isPinned: false, pinnedVersion: null }
-  }
-}
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import {
+  getCachedVersion,
+  getLatestVersion,
+  isLocalDevMode,
+  findPluginEntry,
+} from "../../../hooks/auto-update-checker/checker"
 
 function compareVersions(current: string, latest: string): boolean {
   const parseVersion = (v: string): number[] => {
@@ -91,22 +26,43 @@ function compareVersions(current: string, latest: string): boolean {
 }
 
 export async function getVersionInfo(): Promise<VersionCheckInfo> {
-  const current = getCurrentVersion()
-  const latestVersion = await fetchLatestVersion()
+  const cwd = process.cwd()
+
+  if (isLocalDevMode(cwd)) {
+    return {
+      currentVersion: "local-dev",
+      latestVersion: null,
+      isUpToDate: true,
+      isLocalDev: true,
+      isPinned: false,
+    }
+  }
+
+  const pluginInfo = findPluginEntry(cwd)
+  if (pluginInfo?.isPinned) {
+    return {
+      currentVersion: pluginInfo.pinnedVersion,
+      latestVersion: null,
+      isUpToDate: true,
+      isLocalDev: false,
+      isPinned: true,
+    }
+  }
+
+  const currentVersion = getCachedVersion()
+  const latestVersion = await getLatestVersion()
 
   const isUpToDate =
-    current.isLocalDev ||
-    current.isPinned ||
-    !current.version ||
+    !currentVersion ||
     !latestVersion ||
-    compareVersions(current.version, latestVersion)
+    compareVersions(currentVersion, latestVersion)
 
   return {
-    currentVersion: current.version,
+    currentVersion,
     latestVersion,
     isUpToDate,
-    isLocalDev: current.isLocalDev,
-    isPinned: current.isPinned,
+    isLocalDev: false,
+    isPinned: false,
   }
 }
 

src/cli/doctor/constants.ts

@@ -27,6 +27,7 @@ export const CHECK_IDS = {
   DEP_AST_GREP_CLI: "dep-ast-grep-cli",
   DEP_AST_GREP_NAPI: "dep-ast-grep-napi",
   DEP_COMMENT_CHECKER: "dep-comment-checker",
+  GH_CLI: "gh-cli",
   LSP_SERVERS: "lsp-servers",
   MCP_BUILTIN: "mcp-builtin",
   MCP_USER: "mcp-user",
@@ -43,6 +44,7 @@ export const CHECK_NAMES: Record<string, string> = {
   [CHECK_IDS.DEP_AST_GREP_CLI]: "AST-Grep CLI",
   [CHECK_IDS.DEP_AST_GREP_NAPI]: "AST-Grep NAPI",
   [CHECK_IDS.DEP_COMMENT_CHECKER]: "Comment Checker",
+  [CHECK_IDS.GH_CLI]: "GitHub CLI",
   [CHECK_IDS.LSP_SERVERS]: "LSP Servers",
   [CHECK_IDS.MCP_BUILTIN]: "Built-in MCP Servers",
   [CHECK_IDS.MCP_USER]: "User MCP Configuration",

src/cli/doctor/runner.test.ts

@@ -30,7 +30,7 @@ describe("runner", () => {
         name: "Test Check",
         category: "installation",
         check: async () => {
-          await new Promise((r) => setTimeout(r, 10))
+          await new Promise((r) => setTimeout(r, 50))
           return { name: "Test", status: "pass", message: "OK" }
         },
       }

src/cli/install.ts

@@ -7,8 +7,6 @@ import {
   isOpenCodeInstalled,
   getOpenCodeVersion,
   addAuthPlugins,
-  setupChatGPTHotfix,
-  runBunInstall,
   addProviderConfig,
   detectCurrentConfig,
 } from "./config-manager"
@@ -48,10 +46,10 @@ function formatConfigSummary(config: InstallConfig): string {
   lines.push(color.bold(color.white("Agent Configuration")))
   lines.push("")
 
-  const sisyphusModel = config.hasClaude ? "claude-opus-4-5" : "big-pickle"
-  const oracleModel = config.hasChatGPT ? "gpt-5.2" : (config.hasClaude ? "claude-opus-4-5" : "big-pickle")
-  const librarianModel = config.hasClaude && config.isMax20 ? "claude-sonnet-4-5" : "big-pickle"
-  const frontendModel = config.hasGemini ? "gemini-3-pro-high" : (config.hasClaude ? "claude-opus-4-5" : "big-pickle")
+  const sisyphusModel = config.hasClaude ? "claude-opus-4-5" : "glm-4.7-free"
+  const oracleModel = config.hasChatGPT ? "gpt-5.2" : (config.hasClaude ? "claude-opus-4-5" : "glm-4.7-free")
+  const librarianModel = "glm-4.7-free"
+  const frontendModel = config.hasGemini ? "antigravity-gemini-3-pro-high" : (config.hasClaude ? "claude-opus-4-5" : "glm-4.7-free")
 
   lines.push(`  ${SYMBOLS.bullet} Sisyphus     ${SYMBOLS.arrow} ${color.cyan(sisyphusModel)}`)
   lines.push(`  ${SYMBOLS.bullet} Oracle       ${SYMBOLS.arrow} ${color.cyan(oracleModel)}`)
@@ -163,7 +161,7 @@ async function runTuiMode(detected: DetectedConfig): Promise<InstallConfig | nul
   const claude = await p.select({
     message: "Do you have a Claude Pro/Max subscription?",
     options: [
-      { value: "no" as const, label: "No", hint: "Will use opencode/big-pickle as fallback" },
+      { value: "no" as const, label: "No", hint: "Will use opencode/glm-4.7-free as fallback" },
       { value: "yes" as const, label: "Yes (standard)", hint: "Claude Opus 4.5 for orchestration" },
       { value: "max20" as const, label: "Yes (max20 mode)", hint: "Full power with Claude Sonnet 4.5 for Librarian" },
     ],
@@ -279,26 +277,6 @@ async function runNonTuiInstall(args: InstallArgs): Promise<number> {
     step += 2
   }
 
-  if (config.hasChatGPT) {
-    printStep(step++, totalSteps, "Setting up ChatGPT hotfix...")
-    const hotfixResult = setupChatGPTHotfix()
-    if (!hotfixResult.success) {
-      printError(`Failed: ${hotfixResult.error}`)
-      return 1
-    }
-    printSuccess(`Hotfix configured ${SYMBOLS.arrow} ${color.dim(hotfixResult.configPath)}`)
-
-    printInfo("Installing dependencies with bun...")
-    const bunSuccess = await runBunInstall()
-    if (bunSuccess) {
-      printSuccess("Dependencies installed")
-    } else {
-      printWarning("bun install failed - run manually: cd ~/.config/opencode && bun i")
-    }
-  } else {
-    step++
-  }
-
   printStep(step++, totalSteps, "Writing oh-my-opencode configuration...")
   const omoResult = writeOmoConfig(config)
   if (!omoResult.success) {
@@ -310,7 +288,7 @@ async function runNonTuiInstall(args: InstallArgs): Promise<number> {
   printBox(formatConfigSummary(config), isUpdate ? "Updated Configuration" : "Installation Complete")
 
   if (!config.hasClaude && !config.hasChatGPT && !config.hasGemini) {
-    printWarning("No model providers configured. Using opencode/big-pickle as fallback.")
+    printWarning("No model providers configured. Using opencode/glm-4.7-free as fallback.")
   }
 
   if ((config.hasClaude || config.hasChatGPT || config.hasGemini) && !args.skipAuth) {
@@ -331,6 +309,17 @@ async function runNonTuiInstall(args: InstallArgs): Promise<number> {
   console.log(`${SYMBOLS.star} ${color.bold(color.green(isUpdate ? "Configuration updated!" : "Installation complete!"))}`)
   console.log(`  Run ${color.cyan("opencode")} to start!`)
   console.log()
+
+  printBox(
+    `${color.bold("Pro Tip:")} Include ${color.cyan("ultrawork")} (or ${color.cyan("ulw")}) in your prompt.\n` +
+    `All features work like magic—parallel agents, background tasks,\n` +
+    `deep exploration, and relentless execution until completion.`,
+    "🪄 The Magic Word"
+  )
+
+  console.log(`${SYMBOLS.star} ${color.yellow("If you found this helpful, consider starring the repo!")}`)
+  console.log(`  ${color.dim("gh repo star code-yeongyu/oh-my-opencode")}`)
+  console.log()
   console.log(color.dim("oMoMoMoMo... Enjoy!"))
   console.log()
 
@@ -399,25 +388,6 @@ export async function install(args: InstallArgs): Promise<number> {
     s.stop(`Provider config added to ${color.cyan(providerResult.configPath)}`)
   }
 
-  if (config.hasChatGPT) {
-    s.start("Setting up ChatGPT hotfix")
-    const hotfixResult = setupChatGPTHotfix()
-    if (!hotfixResult.success) {
-      s.stop(`Failed to setup hotfix: ${hotfixResult.error}`)
-      p.outro(color.red("Installation failed."))
-      return 1
-    }
-    s.stop(`Hotfix configured in ${color.cyan(hotfixResult.configPath)}`)
-
-    s.start("Installing dependencies with bun")
-    const bunSuccess = await runBunInstall()
-    if (bunSuccess) {
-      s.stop("Dependencies installed")
-    } else {
-      s.stop(color.yellow("bun install failed - run manually: cd ~/.config/opencode && bun i"))
-    }
-  }
-
   s.start("Writing oh-my-opencode configuration")
   const omoResult = writeOmoConfig(config)
   if (!omoResult.success) {
@@ -428,7 +398,7 @@ export async function install(args: InstallArgs): Promise<number> {
   s.stop(`Config written to ${color.cyan(omoResult.configPath)}`)
 
   if (!config.hasClaude && !config.hasChatGPT && !config.hasGemini) {
-    p.log.warn("No model providers configured. Using opencode/big-pickle as fallback.")
+    p.log.warn("No model providers configured. Using opencode/glm-4.7-free as fallback.")
   }
 
   p.note(formatConfigSummary(config), isUpdate ? "Updated Configuration" : "Installation Complete")
@@ -450,6 +420,16 @@ export async function install(args: InstallArgs): Promise<number> {
   p.log.success(color.bold(isUpdate ? "Configuration updated!" : "Installation complete!"))
   p.log.message(`Run ${color.cyan("opencode")} to start!`)
 
+  p.note(
+    `Include ${color.cyan("ultrawork")} (or ${color.cyan("ulw")}) in your prompt.\n` +
+    `All features work like magic—parallel agents, background tasks,\n` +
+    `deep exploration, and relentless execution until completion.`,
+    "🪄 The Magic Word"
+  )
+
+  p.log.message(`${color.yellow("★")} If you found this helpful, consider starring the repo!`)
+  p.log.message(`  ${color.dim("gh repo star code-yeongyu/oh-my-opencode")}`)
+
   p.outro(color.green("oMoMoMoMo... Enjoy!"))
 
   return 0

src/config/schema.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test"
+import { OhMyOpenCodeConfigSchema } from "./schema"
+
+describe("disabled_mcps schema", () => {
+  test("should accept built-in MCP names", () => {
+    //#given
+    const config = {
+      disabled_mcps: ["context7", "grep_app"],
+    }
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.disabled_mcps).toEqual(["context7", "grep_app"])
+    }
+  })
+
+  test("should accept custom MCP names", () => {
+    //#given
+    const config = {
+      disabled_mcps: ["playwright", "sqlite", "custom-mcp"],
+    }
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.disabled_mcps).toEqual(["playwright", "sqlite", "custom-mcp"])
+    }
+  })
+
+  test("should accept mixed built-in and custom names", () => {
+    //#given
+    const config = {
+      disabled_mcps: ["context7", "playwright", "custom-server"],
+    }
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.disabled_mcps).toEqual(["context7", "playwright", "custom-server"])
+    }
+  })
+
+  test("should accept empty array", () => {
+    //#given
+    const config = {
+      disabled_mcps: [],
+    }
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.disabled_mcps).toEqual([])
+    }
+  })
+
+  test("should reject non-string values", () => {
+    //#given
+    const config = {
+      disabled_mcps: [123, true, null],
+    }
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(false)
+  })
+
+  test("should accept undefined (optional field)", () => {
+    //#given
+    const config = {}
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.disabled_mcps).toBeUndefined()
+    }
+  })
+
+  test("should reject empty strings", () => {
+    //#given
+    const config = {
+      disabled_mcps: [""],
+    }
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(false)
+  })
+
+  test("should accept MCP names with various naming patterns", () => {
+    //#given
+    const config = {
+      disabled_mcps: [
+        "my-custom-mcp",
+        "my_custom_mcp",
+        "myCustomMcp",
+        "my.custom.mcp",
+        "my-custom-mcp-123",
+      ],
+    }
+
+    //#when
+    const result = OhMyOpenCodeConfigSchema.safeParse(config)
+
+    //#then
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.disabled_mcps).toEqual([
+        "my-custom-mcp",
+        "my_custom_mcp",
+        "myCustomMcp",
+        "my.custom.mcp",
+        "my-custom-mcp-123",
+      ])
+    }
+  })
+})

src/config/schema.ts

@@ -1,5 +1,5 @@
 import { z } from "zod"
-import { McpNameSchema } from "../mcp/types"
+import { AnyMcpNameSchema, McpNameSchema } from "../mcp/types"
 
 const PermissionValue = z.enum(["ask", "allow", "deny"])
 
@@ -26,6 +26,10 @@ export const BuiltinAgentNameSchema = z.enum([
   "multimodal-looker",
 ])
 
+export const BuiltinSkillNameSchema = z.enum([
+  "playwright",
+])
+
 export const OverridableAgentNameSchema = z.enum([
   "build",
   "plan",
@@ -66,6 +70,11 @@ export const HookNameSchema = z.enum([
   "empty-message-sanitizer",
   "thinking-block-validator",
   "ralph-loop",
+  "preemptive-compaction",
+  "compaction-context-injector",
+  "claude-code-hooks",
+  "auto-slash-command",
+  "edit-error-recovery",
 ])
 
 export const BuiltinCommandNameSchema = z.enum([
@@ -164,7 +173,7 @@ export const DynamicContextPruningConfigSchema = z.object({
 export const ExperimentalConfigSchema = z.object({
   aggressive_truncation: z.boolean().optional(),
   auto_resume: z.boolean().optional(),
-  /** Enable preemptive compaction at threshold (default: false) */
+  /** Enable preemptive compaction at threshold (default: true since v2.9.0) */
   preemptive_compaction: z.boolean().optional(),
   /** Threshold percentage to trigger preemptive compaction (default: 0.80) */
   preemptive_compaction_threshold: z.number().min(0.5).max(0.95).optional(),
@@ -225,8 +234,9 @@ export const RalphLoopConfigSchema = z.object({
 
 export const OhMyOpenCodeConfigSchema = z.object({
   $schema: z.string().optional(),
-  disabled_mcps: z.array(McpNameSchema).optional(),
+  disabled_mcps: z.array(AnyMcpNameSchema).optional(),
   disabled_agents: z.array(BuiltinAgentNameSchema).optional(),
+  disabled_skills: z.array(BuiltinSkillNameSchema).optional(),
   disabled_hooks: z.array(HookNameSchema).optional(),
   disabled_commands: z.array(BuiltinCommandNameSchema).optional(),
   agents: AgentOverridesSchema.optional(),
@@ -246,6 +256,7 @@ export type AgentOverrides = z.infer<typeof AgentOverridesSchema>
 export type AgentName = z.infer<typeof AgentNameSchema>
 export type HookName = z.infer<typeof HookNameSchema>
 export type BuiltinCommandName = z.infer<typeof BuiltinCommandNameSchema>
+export type BuiltinSkillName = z.infer<typeof BuiltinSkillNameSchema>
 export type SisyphusAgentConfig = z.infer<typeof SisyphusAgentConfigSchema>
 export type CommentCheckerConfig = z.infer<typeof CommentCheckerConfigSchema>
 export type ExperimentalConfig = z.infer<typeof ExperimentalConfigSchema>
@@ -254,4 +265,4 @@ export type SkillsConfig = z.infer<typeof SkillsConfigSchema>
 export type SkillDefinition = z.infer<typeof SkillDefinitionSchema>
 export type RalphLoopConfig = z.infer<typeof RalphLoopConfigSchema>
 
-export { McpNameSchema, type McpName } from "../mcp/types"
+export { AnyMcpNameSchema, type AnyMcpName, McpNameSchema, type McpName } from "../mcp/types"

src/features/AGENTS.md

@@ -2,79 +2,65 @@
 
 ## OVERVIEW
 
-Claude Code compatibility layer and core feature modules. Enables Claude Code configs/commands/skills/MCPs/hooks to work seamlessly in OpenCode.
+Claude Code compatibility layer + core feature modules. Commands, skills, agents, MCPs, hooks from Claude Code work seamlessly.
 
 ## STRUCTURE
 
 ```
 features/
-├── background-agent/           # Background task management
-│   ├── manager.ts              # Task lifecycle, notifications
-│   ├── manager.test.ts
-│   └── types.ts
-├── builtin-commands/           # Built-in slash command definitions
-├── claude-code-agent-loader/   # Load agents from ~/.claude/agents/*.md
-├── claude-code-command-loader/ # Load commands from ~/.claude/commands/*.md
-├── claude-code-mcp-loader/     # Load MCPs from .mcp.json
+├── background-agent/           # Task lifecycle, notifications (460 lines)
+├── builtin-commands/           # Built-in slash commands
+├── builtin-skills/             # Built-in skills (playwright)
+├── claude-code-agent-loader/   # ~/.claude/agents/*.md
+├── claude-code-command-loader/ # ~/.claude/commands/*.md
+├── claude-code-mcp-loader/     # .mcp.json files
 │   └── env-expander.ts         # ${VAR} expansion
-├── claude-code-plugin-loader/  # Load external plugins from installed_plugins.json
+├── claude-code-plugin-loader/  # installed_plugins.json (484 lines)
 ├── claude-code-session-state/  # Session state persistence
-├── opencode-skill-loader/      # Load skills from OpenCode and Claude paths
+├── opencode-skill-loader/      # Skills from OpenCode + Claude paths
+├── skill-mcp-manager/          # MCP servers in skill YAML
 └── hook-message-injector/      # Inject messages into conversation
 ```
 
 ## LOADER PRIORITY
 
-Each loader reads from multiple directories (highest priority first):
-
-| Loader | Priority Order |
-|--------|---------------|
+| Loader | Priority (highest first) |
+|--------|--------------------------|
 | Commands | `.opencode/command/` > `~/.config/opencode/command/` > `.claude/commands/` > `~/.claude/commands/` |
 | Skills | `.opencode/skill/` > `~/.config/opencode/skill/` > `.claude/skills/` > `~/.claude/skills/` |
 | Agents | `.claude/agents/` > `~/.claude/agents/` |
 | MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` |
 
-## HOW TO ADD A LOADER
-
-1. Create directory: `src/features/claude-code-my-loader/`
-2. Create files:
-   - `loader.ts`: Main loader logic with `load()` function
-   - `types.ts`: TypeScript interfaces
-   - `index.ts`: Barrel export
-3. Pattern: Read from multiple dirs, merge with priority, return normalized config
-
-## BACKGROUND AGENT SPECIFICS
-
-- **Task lifecycle**: pending → running → completed/failed
-- **Notifications**: OS notification on task complete (configurable)
-- **Result retrieval**: `background_output` tool with task_id
-- **Cancellation**: `background_cancel` with task_id or all=true
-
 ## CONFIG TOGGLES
 
-Disable features in `oh-my-opencode.json`:
-
 ```json
 {
   "claude_code": {
-    "mcp": false,      // Skip .mcp.json loading
-    "commands": false, // Skip commands/*.md loading
-    "skills": false,   // Skip skills/*/SKILL.md loading
-    "agents": false,   // Skip agents/*.md loading
+    "mcp": false,      // Skip .mcp.json
+    "commands": false, // Skip commands/*.md
+    "skills": false,   // Skip skills/*/SKILL.md
+    "agents": false,   // Skip agents/*.md
     "hooks": false     // Skip settings.json hooks
   }
 }
 ```
 
-## HOOK MESSAGE INJECTOR
+## BACKGROUND AGENT
 
-- **Purpose**: Inject system messages into conversation at specific points
-- **Timing**: PreToolUse, PostToolUse, UserPromptSubmit, Stop
-- **Format**: Returns `{ messages: [{ role: "user", content: "..." }] }`
+- Lifecycle: pending → running → completed/failed
+- OS notification on complete
+- `background_output` to retrieve results
+- `background_cancel` with task_id or all=true
 
-## ANTI-PATTERNS (FEATURES)
+## SKILL MCP
 
-- **Blocking on load**: Loaders run at startup, keep them fast
-- **No error handling**: Always try/catch, log failures, return empty on error
-- **Ignoring priority**: Higher priority dirs must override lower
-- **Modifying user files**: Loaders read-only, never write to ~/.claude/
+- MCP servers embedded in skill YAML frontmatter
+- Lazy client loading, session-scoped cleanup
+- `skill_mcp` tool exposes capabilities
+
+## ANTI-PATTERNS
+
+- Blocking on load (loaders run at startup)
+- No error handling (always try/catch)
+- Ignoring priority order
+- Writing to ~/.claude/ (read-only)

src/features/background-agent/manager.test.ts

@@ -1,8 +1,11 @@
 import { describe, test, expect, beforeEach } from "bun:test"
 import type { BackgroundTask } from "./types"
 
+const TASK_TTL_MS = 30 * 60 * 1000
+
 class MockBackgroundManager {
   private tasks: Map<string, BackgroundTask> = new Map()
+  private notifications: Map<string, BackgroundTask[]> = new Map()
 
   addTask(task: BackgroundTask): void {
     this.tasks.set(task.id, task)
@@ -34,6 +37,74 @@ class MockBackgroundManager {
 
     return result
   }
+
+  markForNotification(task: BackgroundTask): void {
+    const queue = this.notifications.get(task.parentSessionID) ?? []
+    queue.push(task)
+    this.notifications.set(task.parentSessionID, queue)
+  }
+
+  getPendingNotifications(sessionID: string): BackgroundTask[] {
+    return this.notifications.get(sessionID) ?? []
+  }
+
+  private clearNotificationsForTask(taskId: string): void {
+    for (const [sessionID, tasks] of this.notifications.entries()) {
+      const filtered = tasks.filter((t) => t.id !== taskId)
+      if (filtered.length === 0) {
+        this.notifications.delete(sessionID)
+      } else {
+        this.notifications.set(sessionID, filtered)
+      }
+    }
+  }
+
+  pruneStaleTasksAndNotifications(): { prunedTasks: string[]; prunedNotifications: number } {
+    const now = Date.now()
+    const prunedTasks: string[] = []
+    let prunedNotifications = 0
+
+    for (const [taskId, task] of this.tasks.entries()) {
+      const age = now - task.startedAt.getTime()
+      if (age > TASK_TTL_MS) {
+        prunedTasks.push(taskId)
+        this.clearNotificationsForTask(taskId)
+        this.tasks.delete(taskId)
+      }
+    }
+
+    for (const [sessionID, notifications] of this.notifications.entries()) {
+      if (notifications.length === 0) {
+        this.notifications.delete(sessionID)
+        continue
+      }
+      const validNotifications = notifications.filter((task) => {
+        const age = now - task.startedAt.getTime()
+        return age <= TASK_TTL_MS
+      })
+      const removed = notifications.length - validNotifications.length
+      prunedNotifications += removed
+      if (validNotifications.length === 0) {
+        this.notifications.delete(sessionID)
+      } else if (validNotifications.length !== notifications.length) {
+        this.notifications.set(sessionID, validNotifications)
+      }
+    }
+
+    return { prunedTasks, prunedNotifications }
+  }
+
+  getTaskCount(): number {
+    return this.tasks.size
+  }
+
+  getNotificationCount(): number {
+    let count = 0
+    for (const notifications of this.notifications.values()) {
+      count += notifications.length
+    }
+    return count
+  }
 }
 
 function createMockTask(overrides: Partial<BackgroundTask> & { id: string; sessionID: string; parentSessionID: string }): BackgroundTask {
@@ -230,3 +301,116 @@ describe("BackgroundManager.getAllDescendantTasks", () => {
     expect(result[0].id).toBe("task-b")
   })
 })
+
+describe("BackgroundManager.pruneStaleTasksAndNotifications", () => {
+  let manager: MockBackgroundManager
+
+  beforeEach(() => {
+    // #given
+    manager = new MockBackgroundManager()
+  })
+
+  test("should not prune fresh tasks", () => {
+    // #given
+    const task = createMockTask({
+      id: "task-fresh",
+      sessionID: "session-fresh",
+      parentSessionID: "session-parent",
+      startedAt: new Date(),
+    })
+    manager.addTask(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toHaveLength(0)
+    expect(manager.getTaskCount()).toBe(1)
+  })
+
+  test("should prune tasks older than 30 minutes", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.addTask(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toContain("task-stale")
+    expect(manager.getTaskCount()).toBe(0)
+  })
+
+  test("should prune stale notifications", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.markForNotification(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedNotifications).toBe(1)
+    expect(manager.getNotificationCount()).toBe(0)
+  })
+
+  test("should clean up notifications when task is pruned", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.addTask(task)
+    manager.markForNotification(task)
+
+    // #when
+    manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(manager.getTaskCount()).toBe(0)
+    expect(manager.getNotificationCount()).toBe(0)
+  })
+
+  test("should keep fresh tasks while pruning stale ones", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const staleTask = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    const freshTask = createMockTask({
+      id: "task-fresh",
+      sessionID: "session-fresh",
+      parentSessionID: "session-parent",
+      startedAt: new Date(),
+    })
+    manager.addTask(staleTask)
+    manager.addTask(freshTask)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toHaveLength(1)
+    expect(result.prunedTasks).toContain("task-stale")
+    expect(manager.getTaskCount()).toBe(1)
+    expect(manager.getTask("task-fresh")).toBeDefined()
+  })
+})

src/features/background-agent/manager.ts

@@ -12,6 +12,8 @@ import {
 } from "../hook-message-injector"
 import { subagentSessions } from "../claude-code-session-state"
 
+const TASK_TTL_MS = 30 * 60 * 1000
+
 type OpencodeClient = PluginInput["client"]
 
 interface MessagePartInfo {
@@ -345,11 +347,12 @@ export class BackgroundManager {
           },
           query: { directory: this.directory },
         })
-        this.clearNotificationsForTask(taskId)
         log("[background-agent] Successfully sent prompt to parent session:", { parentSessionID: task.parentSessionID })
       } catch (error) {
         log("[background-agent] prompt failed:", String(error))
       } finally {
+        // Always clean up both maps to prevent memory leaks
+        this.clearNotificationsForTask(taskId)
         this.tasks.delete(taskId)
         log("[background-agent] Removed completed task from memory:", taskId)
       }
@@ -377,7 +380,42 @@ export class BackgroundManager {
     return false
   }
 
+  private pruneStaleTasksAndNotifications(): void {
+    const now = Date.now()
+
+    for (const [taskId, task] of this.tasks.entries()) {
+      const age = now - task.startedAt.getTime()
+      if (age > TASK_TTL_MS) {
+        log("[background-agent] Pruning stale task:", { taskId, age: Math.round(age / 1000) + "s" })
+        task.status = "error"
+        task.error = "Task timed out after 30 minutes"
+        task.completedAt = new Date()
+        this.clearNotificationsForTask(taskId)
+        this.tasks.delete(taskId)
+        subagentSessions.delete(task.sessionID)
+      }
+    }
+
+    for (const [sessionID, notifications] of this.notifications.entries()) {
+      if (notifications.length === 0) {
+        this.notifications.delete(sessionID)
+        continue
+      }
+      const validNotifications = notifications.filter((task) => {
+        const age = now - task.startedAt.getTime()
+        return age <= TASK_TTL_MS
+      })
+      if (validNotifications.length === 0) {
+        this.notifications.delete(sessionID)
+      } else if (validNotifications.length !== notifications.length) {
+        this.notifications.set(sessionID, validNotifications)
+      }
+    }
+  }
+
   private async pollRunningTasks(): Promise<void> {
+    this.pruneStaleTasksAndNotifications()
+
     const statusResult = await this.client.session.status()
     const allStatuses = (statusResult.data ?? {}) as Record<string, { type: string }>
 

src/features/builtin-commands/commands.ts

@@ -42,10 +42,8 @@ export function loadBuiltinCommands(
 
   for (const [name, definition] of Object.entries(BUILTIN_COMMAND_DEFINITIONS)) {
     if (!disabled.has(name as BuiltinCommandName)) {
-      commands[name] = {
-        name,
-        ...definition,
-      }
+      const { argumentHint: _argumentHint, ...openCodeCompatible } = definition
+      commands[name] = openCodeCompatible as CommandDefinition
     }
   }
 

src/features/builtin-commands/templates/init-deep.ts

@@ -1,205 +1,191 @@
-export const INIT_DEEP_TEMPLATE = `# Initialize Deep Knowledge Base
+export const INIT_DEEP_TEMPLATE = `# /init-deep
 
-Generate comprehensive AGENTS.md files across project hierarchy. Combines root-level project knowledge (gen-knowledge) with complexity-based subdirectory documentation (gen-knowledge-deep).
+Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.
 
 ## Usage
 
 \`\`\`
-/init-deep                      # Analyze and generate hierarchical AGENTS.md
-/init-deep --create-new         # Force create from scratch (ignore existing)
-/init-deep --max-depth=2        # Limit to N directory levels (default: 3)
+/init-deep                      # Update mode: modify existing + create new where warranted
+/init-deep --create-new         # Read existing → remove all → regenerate from scratch
+/init-deep --max-depth=2        # Limit directory depth (default: 3)
 \`\`\`
 
 ---
 
-## Core Principles
+## Workflow (High-Level)
 
-- **Telegraphic Style**: Sacrifice grammar for concision ("Project uses React" → "React 18")
-- **Predict-then-Compare**: Predict standard → find actual → document ONLY deviations
-- **Hierarchy Aware**: Parent covers general, children cover specific
-- **No Redundancy**: Child AGENTS.md NEVER repeats parent content
-- **LSP-First**: Use LSP tools for accurate code intelligence when available (semantic > text search)
-
----
-
-## Process
+1. **Discovery + Analysis** (concurrent)
+   - Fire background explore agents immediately
+   - Main session: bash structure + LSP codemap + read existing AGENTS.md
+2. **Score & Decide** - Determine AGENTS.md locations from merged findings
+3. **Generate** - Root first, then subdirs in parallel
+4. **Review** - Deduplicate, trim, validate
 
 <critical>
-**MANDATORY: TodoWrite for ALL phases. Mark in_progress → completed in real-time.**
-</critical>
-
-### Phase 0: Initialize
-
+**TodoWrite ALL phases. Mark in_progress → completed in real-time.**
 \`\`\`
 TodoWrite([
-  { id: "p1-analysis", content: "Parallel project structure & complexity analysis", status: "pending", priority: "high" },
-  { id: "p2-scoring", content: "Score directories, determine AGENTS.md locations", status: "pending", priority: "high" },
-  { id: "p3-root", content: "Generate root AGENTS.md with Predict-then-Compare", status: "pending", priority: "high" },
-  { id: "p4-subdirs", content: "Generate subdirectory AGENTS.md files in parallel", status: "pending", priority: "high" },
-  { id: "p5-review", content: "Review, deduplicate, validate all files", status: "pending", priority: "medium" }
+  { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" },
+  { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" },
+  { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" },
+  { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" }
 ])
 \`\`\`
+</critical>
 
 ---
 
-## Phase 1: Parallel Project Analysis
+## Phase 1: Discovery + Analysis (Concurrent)
 
-**Mark "p1-analysis" as in_progress.**
+**Mark "discovery" as in_progress.**
 
-Launch **ALL tasks simultaneously**:
+### Fire Background Explore Agents IMMEDIATELY
 
-<parallel-tasks>
+Don't wait—these run async while main session works.
+
+\`\`\`
+// Fire all at once, collect results later
+background_task(agent="explore", prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only")
+background_task(agent="explore", prompt="Entry points: FIND main files → REPORT non-standard organization")
+background_task(agent="explore", prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules")
+background_task(agent="explore", prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns")
+background_task(agent="explore", prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns")
+background_task(agent="explore", prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions")
+\`\`\`
+
+<dynamic-agents>
+**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:
+
+| Factor | Threshold | Additional Agents |
+|--------|-----------|-------------------|
+| **Total files** | >100 | +1 per 100 files |
+| **Total lines** | >10k | +1 per 10k lines |
+| **Directory depth** | ≥4 | +2 for deep exploration |
+| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |
+| **Monorepo** | detected | +1 per package/workspace |
+| **Multiple languages** | >1 | +1 per language |
 
-### Structural Analysis (bash - run in parallel)
 \`\`\`bash
-# Task A: Directory depth analysis
-find . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
+# Measure project scale first
+total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
+total_lines=$(find . -type f \\( -name "*.ts" -o -name "*.py" -o -name "*.go" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
+large_files=$(find . -type f \\( -name "*.ts" -o -name "*.py" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')
+max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)
+\`\`\`
 
-# Task B: File count per directory  
-find . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/__pycache__/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
+Example spawning:
+\`\`\`
+// 500 files, 50k lines, depth 6, 15 large files → spawn 5+5+2+1 = 13 additional agents
+background_task(agent="explore", prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots")
+background_task(agent="explore", prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions")
+background_task(agent="explore", prompt="Cross-cutting concerns: FIND shared utilities across directories")
+// ... more based on calculation
+\`\`\`
+</dynamic-agents>
 
-# Task C: Code concentration
-find . -type f \\( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \\) -not -path '*/node_modules/*' -not -path '*/venv/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
+### Main Session: Concurrent Analysis
 
-# Task D: Existing knowledge files
+**While background agents run**, main session does:
+
+#### 1. Bash Structural Analysis
+\`\`\`bash
+# Directory depth + file counts
+find . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
+
+# Files per directory (top 30)
+find . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
+
+# Code concentration by extension
+find . -type f \\( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
+
+# Existing AGENTS.md / CLAUDE.md
 find . -type f \\( -name "AGENTS.md" -o -name "CLAUDE.md" \\) -not -path '*/node_modules/*' 2>/dev/null
 \`\`\`
 
-### Context Gathering (Explore agents - background_task in parallel)
-
+#### 2. Read Existing AGENTS.md
 \`\`\`
-background_task(agent="explore", prompt="Project structure: PREDICT standard {lang} patterns → FIND package.json/pyproject.toml/go.mod → REPORT deviations only")
-
-background_task(agent="explore", prompt="Entry points: PREDICT typical (main.py, index.ts) → FIND actual → REPORT non-standard organization")
-
-background_task(agent="explore", prompt="Conventions: FIND .cursor/rules, .cursorrules, eslintrc, pyproject.toml → REPORT project-specific rules DIFFERENT from defaults")
-
-background_task(agent="explore", prompt="Anti-patterns: FIND comments with 'DO NOT', 'NEVER', 'ALWAYS', 'LEGACY', 'DEPRECATED' → REPORT forbidden patterns")
-
-background_task(agent="explore", prompt="Build/CI: FIND .github/workflows, Makefile, justfile → REPORT non-standard build/deploy patterns")
-
-background_task(agent="explore", prompt="Test patterns: FIND pytest.ini, jest.config, test structure → REPORT unique testing conventions")
+For each existing file found:
+  Read(filePath=file)
+  Extract: key insights, conventions, anti-patterns
+  Store in EXISTING_AGENTS map
 \`\`\`
 
-### Code Intelligence Analysis (LSP tools - run in parallel)
-
-LSP provides semantic understanding beyond text search. Use for accurate code mapping.
+If \`--create-new\`: Read all existing first (preserve context) → then delete all → regenerate.
 
+#### 3. LSP Codemap (if available)
 \`\`\`
-# Step 1: Check LSP availability
-lsp_servers()  # Verify language server is available
+lsp_servers()  # Check availability
 
-# Step 2: Analyze entry point files (run in parallel)
-# Find entry points first, then analyze each with lsp_document_symbols
-lsp_document_symbols(filePath="src/index.ts")      # Main entry
-lsp_document_symbols(filePath="src/main.py")       # Python entry
-lsp_document_symbols(filePath="cmd/main.go")       # Go entry
+# Entry points (parallel)
+lsp_document_symbols(filePath="src/index.ts")
+lsp_document_symbols(filePath="main.py")
 
-# Step 3: Discover key symbols across workspace (run in parallel)
-lsp_workspace_symbols(filePath=".", query="class")      # All classes
-lsp_workspace_symbols(filePath=".", query="interface")  # All interfaces
-lsp_workspace_symbols(filePath=".", query="function")   # Top-level functions
-lsp_workspace_symbols(filePath=".", query="type")       # Type definitions
+# Key symbols (parallel)
+lsp_workspace_symbols(filePath=".", query="class")
+lsp_workspace_symbols(filePath=".", query="interface")
+lsp_workspace_symbols(filePath=".", query="function")
 
-# Step 4: Analyze symbol centrality (for top 5-10 key symbols)
-# High reference count = central/important concept
-lsp_find_references(filePath="src/index.ts", line=X, character=Y)  # Main export
+# Centrality for top exports
+lsp_find_references(filePath="...", line=X, character=Y)
 \`\`\`
 
-#### LSP Analysis Output Format
+**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.
+
+### Collect Background Results
 
 \`\`\`
-CODE_INTELLIGENCE = {
-  entry_points: [
-    { file: "src/index.ts", exports: ["Plugin", "createHook"], symbol_count: 12 }
-  ],
-  key_symbols: [
-    { name: "Plugin", type: "class", file: "src/index.ts", refs: 45, role: "Central orchestrator" },
-    { name: "createHook", type: "function", file: "src/utils.ts", refs: 23, role: "Hook factory" }
-  ],
-  module_boundaries: [
-    { dir: "src/hooks", exports: 21, imports_from: ["shared/"] },
-    { dir: "src/tools", exports: 15, imports_from: ["shared/", "hooks/"] }
-  ]
-}
+// After main session analysis done, collect all task results
+for each task_id: background_output(task_id="...")
 \`\`\`
 
-<critical>
-**LSP Fallback**: If LSP unavailable (no server installed), skip this section and rely on explore agents + AST-grep patterns.
-</critical>
-
-</parallel-tasks>
-
-**Collect all results. Mark "p1-analysis" as completed.**
+**Merge: bash + LSP + existing + explore findings. Mark "discovery" as completed.**
 
 ---
 
-## Phase 2: Complexity Scoring & Location Decision
+## Phase 2: Scoring & Location Decision
 
-**Mark "p2-scoring" as in_progress.**
+**Mark "scoring" as in_progress.**
 
 ### Scoring Matrix
 
-| Factor | Weight | Threshold | Source |
-|--------|--------|-----------|--------|
-| File count | 3x | >20 files = high | bash |
-| Subdirectory count | 2x | >5 subdirs = high | bash |
-| Code file ratio | 2x | >70% code = high | bash |
+| Factor | Weight | High Threshold | Source |
+|--------|--------|----------------|--------|
+| File count | 3x | >20 | bash |
+| Subdir count | 2x | >5 | bash |
+| Code ratio | 2x | >70% | bash |
 | Unique patterns | 1x | Has own config | explore |
-| Module boundary | 2x | Has __init__.py/index.ts | bash |
-| **Symbol density** | 2x | >30 symbols = high | LSP |
-| **Export count** | 2x | >10 exports = high | LSP |
-| **Reference centrality** | 3x | Symbols with >20 refs | LSP |
-
-<lsp-scoring>
-**LSP-Enhanced Scoring** (if available):
-
-\`\`\`
-For each directory in candidates:
-  symbols = lsp_document_symbols(dir/index.ts or dir/__init__.py)
-  
-  symbol_score = len(symbols) > 30 ? 6 : len(symbols) > 15 ? 3 : 0
-  export_score = count(exported symbols) > 10 ? 4 : 0
-  
-  # Check if this module is central (many things depend on it)
-  for each exported symbol:
-    refs = lsp_find_references(symbol)
-    if refs > 20: centrality_score += 3
-  
-  total_score += symbol_score + export_score + centrality_score
-\`\`\`
-</lsp-scoring>
+| Module boundary | 2x | Has index.ts/__init__.py | bash |
+| Symbol density | 2x | >30 symbols | LSP |
+| Export count | 2x | >10 exports | LSP |
+| Reference centrality | 3x | >20 refs | LSP |
 
 ### Decision Rules
 
 | Score | Action |
 |-------|--------|
-| **Root (.)** | ALWAYS create AGENTS.md |
-| **High (>15)** | Create dedicated AGENTS.md |
-| **Medium (8-15)** | Create if distinct domain |
-| **Low (<8)** | Skip, parent sufficient |
-
-### Output Format
+| **Root (.)** | ALWAYS create |
+| **>15** | Create AGENTS.md |
+| **8-15** | Create if distinct domain |
+| **<8** | Skip (parent covers) |
 
+### Output
 \`\`\`
 AGENTS_LOCATIONS = [
   { path: ".", type: "root" },
-  { path: "src/api", score: 18, reason: "high complexity, 45 files" },
-  { path: "src/hooks", score: 12, reason: "distinct domain, unique patterns" },
+  { path: "src/hooks", score: 18, reason: "high complexity" },
+  { path: "src/api", score: 12, reason: "distinct domain" }
 ]
 \`\`\`
 
-**Mark "p2-scoring" as completed.**
+**Mark "scoring" as completed.**
 
 ---
 
-## Phase 3: Generate Root AGENTS.md
+## Phase 3: Generate AGENTS.md
 
-**Mark "p3-root" as in_progress.**
+**Mark "generate" as in_progress.**
 
-Root AGENTS.md gets **full treatment** with Predict-then-Compare synthesis.
-
-### Required Sections
+### Root AGENTS.md (Full Treatment)
 
 \`\`\`markdown
 # PROJECT KNOWLEDGE BASE
@@ -209,153 +195,75 @@ Root AGENTS.md gets **full treatment** with Predict-then-Compare synthesis.
 **Branch:** {BRANCH}
 
 ## OVERVIEW
-
-{1-2 sentences: what project does, core tech stack}
+{1-2 sentences: what + core stack}
 
 ## STRUCTURE
-
 \\\`\\\`\\\`
-{project-root}/
-├── {dir}/      # {non-obvious purpose only}
-└── {entry}     # entry point
+{root}/
+├── {dir}/    # {non-obvious purpose only}
+└── {entry}
 \\\`\\\`\\\`
 
 ## WHERE TO LOOK
-
 | Task | Location | Notes |
 |------|----------|-------|
-| Add feature X | \\\`src/x/\\\` | {pattern hint} |
 
 ## CODE MAP
-
-{Generated from LSP analysis - shows key symbols and their relationships}
+{From LSP - skip if unavailable or project <10 files}
 
 | Symbol | Type | Location | Refs | Role |
 |--------|------|----------|------|------|
-| {MainClass} | Class | \\\`src/index.ts\\\` | {N} | {Central orchestrator} |
-| {createX} | Function | \\\`src/utils.ts\\\` | {N} | {Factory pattern} |
-| {Config} | Interface | \\\`src/types.ts\\\` | {N} | {Configuration contract} |
-
-### Module Dependencies
-
-\\\`\\\`\\\`
-{entry} ──imports──> {core/}
-   │                    │
-   └──imports──> {utils/} <──imports── {features/}
-\\\`\\\`\\\`
-
-<code-map-note>
-**Skip CODE MAP if**: LSP unavailable OR project too small (<10 files) OR no clear module boundaries.
-</code-map-note>
 
 ## CONVENTIONS
-
-{ONLY deviations from standard - skip generic advice}
-
-- **{rule}**: {specific detail}
+{ONLY deviations from standard}
 
 ## ANTI-PATTERNS (THIS PROJECT)
-
-{Things explicitly forbidden HERE}
-
-- **{pattern}**: {why} → {alternative}
+{Explicitly forbidden here}
 
 ## UNIQUE STYLES
-
-{Project-specific coding styles}
-
-- **{style}**: {how different}
+{Project-specific}
 
 ## COMMANDS
-
 \\\`\\\`\\\`bash
-{dev-command}
-{test-command}
-{build-command}
+{dev/test/build}
 \\\`\\\`\\\`
 
 ## NOTES
-
-{Gotchas, non-obvious info}
+{Gotchas}
 \`\`\`
 
-### Quality Gates
+**Quality gates**: 50-150 lines, no generic advice, no obvious info.
 
-- [ ] Size: 50-150 lines
-- [ ] No generic advice ("write clean code")
-- [ ] No obvious info ("tests/ has tests")
-- [ ] Every item is project-specific
+### Subdirectory AGENTS.md (Parallel)
 
-**Mark "p3-root" as completed.**
+Launch document-writer agents for each location:
+
+\`\`\`
+for loc in AGENTS_LOCATIONS (except root):
+  background_task(agent="document-writer", prompt=\\\`
+    Generate AGENTS.md for: \${loc.path}
+    - Reason: \${loc.reason}
+    - 30-80 lines max
+    - NEVER repeat parent content
+    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
+  \\\`)
+\`\`\`
+
+**Wait for all. Mark "generate" as completed.**
 
 ---
 
-## Phase 4: Generate Subdirectory AGENTS.md
+## Phase 4: Review & Deduplicate
 
-**Mark "p4-subdirs" as in_progress.**
+**Mark "review" as in_progress.**
 
-For each location in AGENTS_LOCATIONS (except root), launch **parallel document-writer agents**:
+For each generated file:
+- Remove generic advice
+- Remove parent duplicates
+- Trim to size limits
+- Verify telegraphic style
 
-\`\`\`typescript
-for (const loc of AGENTS_LOCATIONS.filter(l => l.path !== ".")) {
-  background_task({
-    agent: "document-writer",
-    prompt: \\\`
-      Generate AGENTS.md for: \${loc.path}
-      
-      CONTEXT:
-      - Complexity reason: \${loc.reason}
-      - Parent AGENTS.md: ./AGENTS.md (already covers project overview)
-      
-      CRITICAL RULES:
-      1. Focus ONLY on this directory's specific context
-      2. NEVER repeat parent AGENTS.md content
-      3. Shorter is better - 30-80 lines max
-      4. Telegraphic style - sacrifice grammar
-      
-      REQUIRED SECTIONS:
-      - OVERVIEW (1 line: what this directory does)
-      - STRUCTURE (only if >5 subdirs)
-      - WHERE TO LOOK (directory-specific tasks)
-      - CONVENTIONS (only if DIFFERENT from root)
-      - ANTI-PATTERNS (directory-specific only)
-      
-      OUTPUT: Write to \${loc.path}/AGENTS.md
-    \\\`
-  })
-}
-\`\`\`
-
-**Wait for all agents. Mark "p4-subdirs" as completed.**
-
----
-
-## Phase 5: Review & Deduplicate
-
-**Mark "p5-review" as in_progress.**
-
-### Validation Checklist
-
-For EACH generated AGENTS.md:
-
-| Check | Action if Fail |
-|-------|----------------|
-| Contains generic advice | REMOVE the line |
-| Repeats parent content | REMOVE the line |
-| Missing required section | ADD it |
-| Over 150 lines (root) / 80 lines (subdir) | TRIM |
-| Verbose explanations | REWRITE telegraphic |
-
-### Cross-Reference Validation
-
-\`\`\`
-For each child AGENTS.md:
-  For each line in child:
-    If similar line exists in parent:
-      REMOVE from child (parent already covers)
-\`\`\`
-
-**Mark "p5-review" as completed.**
+**Mark "review" as completed.**
 
 ---
 
@@ -364,31 +272,29 @@ For each child AGENTS.md:
 \`\`\`
 === init-deep Complete ===
 
-Files Generated:
+Mode: {update | create-new}
+
+Files:
   ✓ ./AGENTS.md (root, {N} lines)
   ✓ ./src/hooks/AGENTS.md ({N} lines)
-  ✓ ./src/tools/AGENTS.md ({N} lines)
 
-Directories Analyzed: {N}
+Dirs Analyzed: {N}
 AGENTS.md Created: {N}
-Total Lines: {N}
+AGENTS.md Updated: {N}
 
 Hierarchy:
   ./AGENTS.md
-  ├── src/hooks/AGENTS.md
-  └── src/tools/AGENTS.md
+  └── src/hooks/AGENTS.md
 \`\`\`
 
 ---
 
-## Anti-Patterns for THIS Command
+## Anti-Patterns
 
-- **Over-documenting**: Not every directory needs AGENTS.md
-- **Redundancy**: Child must NOT repeat parent
+- **Static agent count**: MUST vary agents based on project size/depth
+- **Sequential execution**: MUST parallel (explore + LSP concurrent)
+- **Ignoring existing**: ALWAYS read existing first, even with --create-new
+- **Over-documenting**: Not every dir needs AGENTS.md
+- **Redundancy**: Child never repeats parent
 - **Generic content**: Remove anything that applies to ALL projects
-- **Sequential execution**: MUST use parallel agents
-- **Deep nesting**: Rarely need AGENTS.md at depth 4+
-- **Verbose style**: "This directory contains..." → just list it
-- **Ignoring LSP**: If LSP available, USE IT - semantic analysis > text grep
-- **LSP without fallback**: Always have explore agent backup if LSP unavailable
-- **Over-referencing**: Don't trace refs for EVERY symbol - focus on exports only`
+- **Verbose style**: Telegraphic or die`

src/features/builtin-skills/skills.ts

@@ -1,5 +1,19 @@
 import type { BuiltinSkill } from "./types"
 
-export function createBuiltinSkills(): BuiltinSkill[] {
-  return []
+const playwrightSkill: BuiltinSkill = {
+  name: "playwright",
+  description: "Browser automation with Playwright MCP. Use for web scraping, testing, screenshots, and browser interactions.",
+  template: `# Playwright Browser Automation
+
+This skill provides browser automation capabilities via the Playwright MCP server.`,
+  mcpConfig: {
+    playwright: {
+      command: "npx",
+      args: ["@playwright/mcp@latest"],
+    },
+  },
+}
+
+export function createBuiltinSkills(): BuiltinSkill[] {
+  return [playwrightSkill]
 }

src/features/builtin-skills/types.ts

@@ -1,3 +1,5 @@
+import type { SkillMcpConfig } from "../skill-mcp-manager/types"
+
 export interface BuiltinSkill {
   name: string
   description: string
@@ -10,4 +12,5 @@ export interface BuiltinSkill {
   model?: string
   subtask?: boolean
   argumentHint?: string
+  mcpConfig?: SkillMcpConfig
 }

src/features/claude-code-command-loader/loader.ts

@@ -1,27 +1,66 @@
-import { existsSync, readdirSync, readFileSync } from "fs"
+import { promises as fs, type Dirent } from "fs"
 import { join, basename } from "path"
+import { homedir } from "os"
 import { parseFrontmatter } from "../../shared/frontmatter"
 import { sanitizeModelField } from "../../shared/model-sanitizer"
 import { isMarkdownFile } from "../../shared/file-utils"
 import { getClaudeConfigDir } from "../../shared"
+import { log } from "../../shared/logger"
 import type { CommandScope, CommandDefinition, CommandFrontmatter, LoadedCommand } from "./types"
 
-function loadCommandsFromDir(commandsDir: string, scope: CommandScope): LoadedCommand[] {
-  if (!existsSync(commandsDir)) {
+async function loadCommandsFromDir(
+  commandsDir: string,
+  scope: CommandScope,
+  visited: Set<string> = new Set(),
+  prefix: string = ""
+): Promise<LoadedCommand[]> {
+  try {
+    await fs.access(commandsDir)
+  } catch {
+    return []
+  }
+
+  let realPath: string
+  try {
+    realPath = await fs.realpath(commandsDir)
+  } catch (error) {
+    log(`Failed to resolve command directory: ${commandsDir}`, error)
+    return []
+  }
+
+  if (visited.has(realPath)) {
+    return []
+  }
+  visited.add(realPath)
+
+  let entries: Dirent[]
+  try {
+    entries = await fs.readdir(commandsDir, { withFileTypes: true })
+  } catch (error) {
+    log(`Failed to read command directory: ${commandsDir}`, error)
     return []
   }
 
-  const entries = readdirSync(commandsDir, { withFileTypes: true })
   const commands: LoadedCommand[] = []
 
   for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith(".")) continue
+      const subDirPath = join(commandsDir, entry.name)
+      const subPrefix = prefix ? `${prefix}:${entry.name}` : entry.name
+      const subCommands = await loadCommandsFromDir(subDirPath, scope, visited, subPrefix)
+      commands.push(...subCommands)
+      continue
+    }
+
     if (!isMarkdownFile(entry)) continue
 
     const commandPath = join(commandsDir, entry.name)
-    const commandName = basename(entry.name, ".md")
+    const baseCommandName = basename(entry.name, ".md")
+    const commandName = prefix ? `${prefix}:${baseCommandName}` : baseCommandName
 
     try {
-      const content = readFileSync(commandPath, "utf-8")
+      const content = await fs.readFile(commandPath, "utf-8")
       const { data, body } = parseFrontmatter<CommandFrontmatter>(content)
 
       const wrappedTemplate = `<command-instruction>
@@ -43,6 +82,7 @@ $ARGUMENTS
         model: sanitizeModelField(data.model, isOpencodeSource ? "opencode" : "claude-code"),
         subtask: data.subtask,
         argumentHint: data["argument-hint"],
+        handoffs: data.handoffs,
       }
 
       commands.push({
@@ -51,7 +91,8 @@ $ARGUMENTS
         definition,
         scope,
       })
-    } catch {
+    } catch (error) {
+      log(`Failed to parse command: ${commandPath}`, error)
       continue
     }
   }
@@ -62,32 +103,42 @@ $ARGUMENTS
 function commandsToRecord(commands: LoadedCommand[]): Record<string, CommandDefinition> {
   const result: Record<string, CommandDefinition> = {}
   for (const cmd of commands) {
-    result[cmd.name] = cmd.definition
+    const { name: _name, argumentHint: _argumentHint, ...openCodeCompatible } = cmd.definition
+    result[cmd.name] = openCodeCompatible as CommandDefinition
   }
   return result
 }
 
-export function loadUserCommands(): Record<string, CommandDefinition> {
+export async function loadUserCommands(): Promise<Record<string, CommandDefinition>> {
   const userCommandsDir = join(getClaudeConfigDir(), "commands")
-  const commands = loadCommandsFromDir(userCommandsDir, "user")
+  const commands = await loadCommandsFromDir(userCommandsDir, "user")
   return commandsToRecord(commands)
 }
 
-export function loadProjectCommands(): Record<string, CommandDefinition> {
+export async function loadProjectCommands(): Promise<Record<string, CommandDefinition>> {
   const projectCommandsDir = join(process.cwd(), ".claude", "commands")
-  const commands = loadCommandsFromDir(projectCommandsDir, "project")
+  const commands = await loadCommandsFromDir(projectCommandsDir, "project")
   return commandsToRecord(commands)
 }
 
-export function loadOpencodeGlobalCommands(): Record<string, CommandDefinition> {
-  const { homedir } = require("os")
+export async function loadOpencodeGlobalCommands(): Promise<Record<string, CommandDefinition>> {
   const opencodeCommandsDir = join(homedir(), ".config", "opencode", "command")
-  const commands = loadCommandsFromDir(opencodeCommandsDir, "opencode")
+  const commands = await loadCommandsFromDir(opencodeCommandsDir, "opencode")
   return commandsToRecord(commands)
 }
 
-export function loadOpencodeProjectCommands(): Record<string, CommandDefinition> {
+export async function loadOpencodeProjectCommands(): Promise<Record<string, CommandDefinition>> {
   const opencodeProjectDir = join(process.cwd(), ".opencode", "command")
-  const commands = loadCommandsFromDir(opencodeProjectDir, "opencode-project")
+  const commands = await loadCommandsFromDir(opencodeProjectDir, "opencode-project")
   return commandsToRecord(commands)
 }
+
+export async function loadAllCommands(): Promise<Record<string, CommandDefinition>> {
+  const [user, project, global, projectOpencode] = await Promise.all([
+    loadUserCommands(),
+    loadProjectCommands(),
+    loadOpencodeGlobalCommands(),
+    loadOpencodeProjectCommands(),
+  ])
+  return { ...projectOpencode, ...global, ...project, ...user }
+}

src/features/claude-code-command-loader/types.ts

@@ -1,5 +1,21 @@
 export type CommandScope = "user" | "project" | "opencode" | "opencode-project"
 
+/**
+ * Handoff definition for command workflows.
+ * Based on speckit's handoff pattern for multi-agent orchestration.
+ * @see https://github.com/github/spec-kit
+ */
+export interface HandoffDefinition {
+  /** Human-readable label for the handoff action */
+  label: string
+  /** Target agent/command identifier (e.g., "speckit.tasks") */
+  agent: string
+  /** Pre-filled prompt text for the handoff */
+  prompt: string
+  /** If true, automatically executes after command completion; if false, shows as suggestion */
+  send?: boolean
+}
+
 export interface CommandDefinition {
   name: string
   description?: string
@@ -8,6 +24,8 @@ export interface CommandDefinition {
   model?: string
   subtask?: boolean
   argumentHint?: string
+  /** Handoff definitions for workflow transitions */
+  handoffs?: HandoffDefinition[]
 }
 
 export interface CommandFrontmatter {
@@ -16,6 +34,8 @@ export interface CommandFrontmatter {
   agent?: string
   model?: string
   subtask?: boolean
+  /** Handoff definitions for workflow transitions */
+  handoffs?: HandoffDefinition[]
 }
 
 export interface LoadedCommand {

src/features/claude-code-mcp-loader/loader.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { mkdirSync, writeFileSync, rmSync } from "fs"
+import { join } from "path"
+import { tmpdir } from "os"
+
+const TEST_DIR = join(tmpdir(), "mcp-loader-test-" + Date.now())
+
+describe("getSystemMcpServerNames", () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true })
+  })
+
+  it("returns empty set when no .mcp.json files exist", async () => {
+    // #given
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names).toBeInstanceOf(Set)
+      expect(names.size).toBe(0)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("returns server names from project .mcp.json", async () => {
+    // #given
+    const mcpConfig = {
+      mcpServers: {
+        playwright: {
+          command: "npx",
+          args: ["@playwright/mcp@latest"],
+        },
+        sqlite: {
+          command: "uvx",
+          args: ["mcp-server-sqlite"],
+        },
+      },
+    }
+    writeFileSync(join(TEST_DIR, ".mcp.json"), JSON.stringify(mcpConfig))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("playwright")).toBe(true)
+      expect(names.has("sqlite")).toBe(true)
+      expect(names.size).toBe(2)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("returns server names from .claude/.mcp.json", async () => {
+    // #given
+    mkdirSync(join(TEST_DIR, ".claude"), { recursive: true })
+    const mcpConfig = {
+      mcpServers: {
+        memory: {
+          command: "npx",
+          args: ["-y", "@anthropic-ai/mcp-server-memory"],
+        },
+      },
+    }
+    writeFileSync(join(TEST_DIR, ".claude", ".mcp.json"), JSON.stringify(mcpConfig))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("memory")).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("excludes disabled MCP servers", async () => {
+    // #given
+    const mcpConfig = {
+      mcpServers: {
+        playwright: {
+          command: "npx",
+          args: ["@playwright/mcp@latest"],
+          disabled: true,
+        },
+        active: {
+          command: "npx",
+          args: ["some-mcp"],
+        },
+      },
+    }
+    writeFileSync(join(TEST_DIR, ".mcp.json"), JSON.stringify(mcpConfig))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("playwright")).toBe(false)
+      expect(names.has("active")).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("merges server names from multiple .mcp.json files", async () => {
+    // #given
+    mkdirSync(join(TEST_DIR, ".claude"), { recursive: true })
+    
+    const projectMcp = {
+      mcpServers: {
+        playwright: { command: "npx", args: ["@playwright/mcp@latest"] },
+      },
+    }
+    const localMcp = {
+      mcpServers: {
+        memory: { command: "npx", args: ["-y", "@anthropic-ai/mcp-server-memory"] },
+      },
+    }
+    
+    writeFileSync(join(TEST_DIR, ".mcp.json"), JSON.stringify(projectMcp))
+    writeFileSync(join(TEST_DIR, ".claude", ".mcp.json"), JSON.stringify(localMcp))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("playwright")).toBe(true)
+      expect(names.has("memory")).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+})

src/features/claude-code-mcp-loader/loader.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "fs"
+import { existsSync, readFileSync } from "fs"
 import { join } from "path"
 import { getClaudeConfigDir } from "../../shared"
 import type {
@@ -42,6 +42,30 @@ async function loadMcpConfigFile(
   }
 }
 
+export function getSystemMcpServerNames(): Set<string> {
+  const names = new Set<string>()
+  const paths = getMcpConfigPaths()
+
+  for (const { path } of paths) {
+    if (!existsSync(path)) continue
+
+    try {
+      const content = readFileSync(path, "utf-8")
+      const config = JSON.parse(content) as ClaudeCodeMcpConfig
+      if (!config?.mcpServers) continue
+
+      for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+        if (serverConfig.disabled) continue
+        names.add(name)
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return names
+}
+
 export async function loadMcpConfigs(): Promise<McpLoadResult> {
   const servers: McpLoadResult["servers"] = {}
   const loadedServers: LoadedMcpServer[] = []

src/features/claude-code-plugin-loader/loader.ts

@@ -246,7 +246,7 @@ $ARGUMENTS
 
         const formattedDescription = `(plugin: ${plugin.name}) ${data.description || ""}`
 
-        commands[namespacedName] = {
+        const definition = {
           name: namespacedName,
           description: formattedDescription,
           template: wrappedTemplate,
@@ -255,6 +255,8 @@ $ARGUMENTS
           subtask: data.subtask,
           argumentHint: data["argument-hint"],
         }
+        const { name: _name, argumentHint: _argumentHint, ...openCodeCompatible } = definition
+        commands[namespacedName] = openCodeCompatible as CommandDefinition
 
         log(`Loaded plugin command: ${namespacedName}`, { path: commandPath })
       } catch (error) {
@@ -306,12 +308,14 @@ ${body.trim()}
 $ARGUMENTS
 </user-request>`
 
-        skills[namespacedName] = {
+        const definition = {
           name: namespacedName,
           description: formattedDescription,
           template: wrappedTemplate,
           model: sanitizeModelField(data.model),
         }
+        const { name: _name, ...openCodeCompatible } = definition
+        skills[namespacedName] = openCodeCompatible as CommandDefinition
 
         log(`Loaded plugin skill: ${namespacedName}`, { path: resolvedPath })
       } catch (error) {
@@ -460,11 +464,13 @@ export interface PluginComponentsResult {
 export async function loadAllPluginComponents(options?: PluginLoaderOptions): Promise<PluginComponentsResult> {
   const { plugins, errors } = discoverInstalledPlugins(options)
 
-  const commands = loadPluginCommands(plugins)
-  const skills = loadPluginSkillsAsCommands(plugins)
-  const agents = loadPluginAgents(plugins)
-  const mcpServers = await loadPluginMcpServers(plugins)
-  const hooksConfigs = loadPluginHooksConfigs(plugins)
+  const [commands, skills, agents, mcpServers, hooksConfigs] = await Promise.all([
+    Promise.resolve(loadPluginCommands(plugins)),
+    Promise.resolve(loadPluginSkillsAsCommands(plugins)),
+    Promise.resolve(loadPluginAgents(plugins)),
+    loadPluginMcpServers(plugins),
+    Promise.resolve(loadPluginHooksConfigs(plugins)),
+  ])
 
   log(`Loaded ${plugins.length} plugins with ${Object.keys(commands).length} commands, ${Object.keys(skills).length} skills, ${Object.keys(agents).length} agents, ${Object.keys(mcpServers).length} MCP servers`)
 

src/features/context-injector/collector.test.ts

@@ -0,0 +1,330 @@
+import { describe, it, expect, beforeEach } from "bun:test"
+import { ContextCollector } from "./collector"
+import type { ContextPriority, ContextSourceType } from "./types"
+
+describe("ContextCollector", () => {
+  let collector: ContextCollector
+
+  beforeEach(() => {
+    collector = new ContextCollector()
+  })
+
+  describe("register", () => {
+    it("registers context for a session", () => {
+      // #given
+      const sessionID = "ses_test1"
+      const options = {
+        id: "ulw-context",
+        source: "keyword-detector" as ContextSourceType,
+        content: "Ultrawork mode activated",
+      }
+
+      // #when
+      collector.register(sessionID, options)
+
+      // #then
+      const pending = collector.getPending(sessionID)
+      expect(pending.hasContent).toBe(true)
+      expect(pending.entries).toHaveLength(1)
+      expect(pending.entries[0].content).toBe("Ultrawork mode activated")
+    })
+
+    it("assigns default priority of 'normal' when not specified", () => {
+      // #given
+      const sessionID = "ses_test2"
+
+      // #when
+      collector.register(sessionID, {
+        id: "test",
+        source: "keyword-detector",
+        content: "test content",
+      })
+
+      // #then
+      const pending = collector.getPending(sessionID)
+      expect(pending.entries[0].priority).toBe("normal")
+    })
+
+    it("uses specified priority", () => {
+      // #given
+      const sessionID = "ses_test3"
+
+      // #when
+      collector.register(sessionID, {
+        id: "critical-context",
+        source: "keyword-detector",
+        content: "critical content",
+        priority: "critical",
+      })
+
+      // #then
+      const pending = collector.getPending(sessionID)
+      expect(pending.entries[0].priority).toBe("critical")
+    })
+
+    it("deduplicates by source + id combination", () => {
+      // #given
+      const sessionID = "ses_test4"
+      const options = {
+        id: "ulw-context",
+        source: "keyword-detector" as ContextSourceType,
+        content: "First content",
+      }
+
+      // #when
+      collector.register(sessionID, options)
+      collector.register(sessionID, { ...options, content: "Updated content" })
+
+      // #then
+      const pending = collector.getPending(sessionID)
+      expect(pending.entries).toHaveLength(1)
+      expect(pending.entries[0].content).toBe("Updated content")
+    })
+
+    it("allows same id from different sources", () => {
+      // #given
+      const sessionID = "ses_test5"
+
+      // #when
+      collector.register(sessionID, {
+        id: "context-1",
+        source: "keyword-detector",
+        content: "From keyword-detector",
+      })
+      collector.register(sessionID, {
+        id: "context-1",
+        source: "rules-injector",
+        content: "From rules-injector",
+      })
+
+      // #then
+      const pending = collector.getPending(sessionID)
+      expect(pending.entries).toHaveLength(2)
+    })
+  })
+
+  describe("getPending", () => {
+    it("returns empty result for session with no context", () => {
+      // #given
+      const sessionID = "ses_empty"
+
+      // #when
+      const pending = collector.getPending(sessionID)
+
+      // #then
+      expect(pending.hasContent).toBe(false)
+      expect(pending.entries).toHaveLength(0)
+      expect(pending.merged).toBe("")
+    })
+
+    it("merges multiple contexts with separator", () => {
+      // #given
+      const sessionID = "ses_merge"
+      collector.register(sessionID, {
+        id: "ctx-1",
+        source: "keyword-detector",
+        content: "First context",
+      })
+      collector.register(sessionID, {
+        id: "ctx-2",
+        source: "rules-injector",
+        content: "Second context",
+      })
+
+      // #when
+      const pending = collector.getPending(sessionID)
+
+      // #then
+      expect(pending.hasContent).toBe(true)
+      expect(pending.merged).toContain("First context")
+      expect(pending.merged).toContain("Second context")
+    })
+
+    it("orders contexts by priority (critical > high > normal > low)", () => {
+      // #given
+      const sessionID = "ses_priority"
+      collector.register(sessionID, {
+        id: "low",
+        source: "custom",
+        content: "LOW",
+        priority: "low",
+      })
+      collector.register(sessionID, {
+        id: "critical",
+        source: "custom",
+        content: "CRITICAL",
+        priority: "critical",
+      })
+      collector.register(sessionID, {
+        id: "normal",
+        source: "custom",
+        content: "NORMAL",
+        priority: "normal",
+      })
+      collector.register(sessionID, {
+        id: "high",
+        source: "custom",
+        content: "HIGH",
+        priority: "high",
+      })
+
+      // #when
+      const pending = collector.getPending(sessionID)
+
+      // #then
+      const order = pending.entries.map((e) => e.priority)
+      expect(order).toEqual(["critical", "high", "normal", "low"])
+    })
+
+    it("maintains registration order within same priority", () => {
+      // #given
+      const sessionID = "ses_order"
+      collector.register(sessionID, {
+        id: "first",
+        source: "custom",
+        content: "First",
+        priority: "normal",
+      })
+      collector.register(sessionID, {
+        id: "second",
+        source: "custom",
+        content: "Second",
+        priority: "normal",
+      })
+      collector.register(sessionID, {
+        id: "third",
+        source: "custom",
+        content: "Third",
+        priority: "normal",
+      })
+
+      // #when
+      const pending = collector.getPending(sessionID)
+
+      // #then
+      const ids = pending.entries.map((e) => e.id)
+      expect(ids).toEqual(["first", "second", "third"])
+    })
+  })
+
+  describe("consume", () => {
+    it("clears pending context for session", () => {
+      // #given
+      const sessionID = "ses_consume"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "test",
+      })
+
+      // #when
+      collector.consume(sessionID)
+
+      // #then
+      const pending = collector.getPending(sessionID)
+      expect(pending.hasContent).toBe(false)
+    })
+
+    it("returns the consumed context", () => {
+      // #given
+      const sessionID = "ses_consume_return"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "test content",
+      })
+
+      // #when
+      const consumed = collector.consume(sessionID)
+
+      // #then
+      expect(consumed.hasContent).toBe(true)
+      expect(consumed.entries[0].content).toBe("test content")
+    })
+
+    it("does not affect other sessions", () => {
+      // #given
+      const session1 = "ses_1"
+      const session2 = "ses_2"
+      collector.register(session1, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "session 1",
+      })
+      collector.register(session2, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "session 2",
+      })
+
+      // #when
+      collector.consume(session1)
+
+      // #then
+      expect(collector.getPending(session1).hasContent).toBe(false)
+      expect(collector.getPending(session2).hasContent).toBe(true)
+    })
+  })
+
+  describe("clear", () => {
+    it("removes all context for a session", () => {
+      // #given
+      const sessionID = "ses_clear"
+      collector.register(sessionID, {
+        id: "ctx-1",
+        source: "keyword-detector",
+        content: "test 1",
+      })
+      collector.register(sessionID, {
+        id: "ctx-2",
+        source: "rules-injector",
+        content: "test 2",
+      })
+
+      // #when
+      collector.clear(sessionID)
+
+      // #then
+      expect(collector.getPending(sessionID).hasContent).toBe(false)
+    })
+  })
+
+  describe("hasPending", () => {
+    it("returns true when session has pending context", () => {
+      // #given
+      const sessionID = "ses_has"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "test",
+      })
+
+      // #when / #then
+      expect(collector.hasPending(sessionID)).toBe(true)
+    })
+
+    it("returns false when session has no pending context", () => {
+      // #given
+      const sessionID = "ses_empty"
+
+      // #when / #then
+      expect(collector.hasPending(sessionID)).toBe(false)
+    })
+
+    it("returns false after consume", () => {
+      // #given
+      const sessionID = "ses_after_consume"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "test",
+      })
+
+      // #when
+      collector.consume(sessionID)
+
+      // #then
+      expect(collector.hasPending(sessionID)).toBe(false)
+    })
+  })
+})

src/features/context-injector/collector.ts

@@ -0,0 +1,85 @@
+import type {
+  ContextEntry,
+  ContextPriority,
+  PendingContext,
+  RegisterContextOptions,
+} from "./types"
+
+const PRIORITY_ORDER: Record<ContextPriority, number> = {
+  critical: 0,
+  high: 1,
+  normal: 2,
+  low: 3,
+}
+
+const CONTEXT_SEPARATOR = "\n\n---\n\n"
+
+export class ContextCollector {
+  private sessions: Map<string, Map<string, ContextEntry>> = new Map()
+
+  register(sessionID: string, options: RegisterContextOptions): void {
+    if (!this.sessions.has(sessionID)) {
+      this.sessions.set(sessionID, new Map())
+    }
+
+    const sessionMap = this.sessions.get(sessionID)!
+    const key = `${options.source}:${options.id}`
+
+    const entry: ContextEntry = {
+      id: options.id,
+      source: options.source,
+      content: options.content,
+      priority: options.priority ?? "normal",
+      timestamp: Date.now(),
+      metadata: options.metadata,
+    }
+
+    sessionMap.set(key, entry)
+  }
+
+  getPending(sessionID: string): PendingContext {
+    const sessionMap = this.sessions.get(sessionID)
+
+    if (!sessionMap || sessionMap.size === 0) {
+      return {
+        merged: "",
+        entries: [],
+        hasContent: false,
+      }
+    }
+
+    const entries = this.sortEntries([...sessionMap.values()])
+    const merged = entries.map((e) => e.content).join(CONTEXT_SEPARATOR)
+
+    return {
+      merged,
+      entries,
+      hasContent: entries.length > 0,
+    }
+  }
+
+  consume(sessionID: string): PendingContext {
+    const pending = this.getPending(sessionID)
+    this.clear(sessionID)
+    return pending
+  }
+
+  clear(sessionID: string): void {
+    this.sessions.delete(sessionID)
+  }
+
+  hasPending(sessionID: string): boolean {
+    const sessionMap = this.sessions.get(sessionID)
+    return sessionMap !== undefined && sessionMap.size > 0
+  }
+
+  private sortEntries(entries: ContextEntry[]): ContextEntry[] {
+    return entries.sort((a, b) => {
+      const priorityDiff = PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]
+      if (priorityDiff !== 0) return priorityDiff
+      return a.timestamp - b.timestamp
+    })
+  }
+}
+
+export const contextCollector = new ContextCollector()

src/features/context-injector/index.ts

@@ -0,0 +1,16 @@
+export { ContextCollector, contextCollector } from "./collector"
+export {
+  injectPendingContext,
+  createContextInjectorHook,
+  createContextInjectorMessagesTransformHook,
+} from "./injector"
+export type {
+  ContextSourceType,
+  ContextPriority,
+  ContextEntry,
+  RegisterContextOptions,
+  PendingContext,
+  MessageContext,
+  OutputParts,
+  InjectionStrategy,
+} from "./types"

src/features/context-injector/injector.test.ts

@@ -0,0 +1,292 @@
+import { describe, it, expect, beforeEach } from "bun:test"
+import { ContextCollector } from "./collector"
+import {
+  injectPendingContext,
+  createContextInjectorHook,
+  createContextInjectorMessagesTransformHook,
+} from "./injector"
+
+describe("injectPendingContext", () => {
+  let collector: ContextCollector
+
+  beforeEach(() => {
+    collector = new ContextCollector()
+  })
+
+  describe("when parts have text content", () => {
+    it("prepends context to first text part", () => {
+      // #given
+      const sessionID = "ses_inject1"
+      collector.register(sessionID, {
+        id: "ulw",
+        source: "keyword-detector",
+        content: "Ultrawork mode activated",
+      })
+      const parts = [{ type: "text", text: "User message" }]
+
+      // #when
+      const result = injectPendingContext(collector, sessionID, parts)
+
+      // #then
+      expect(result.injected).toBe(true)
+      expect(parts[0].text).toContain("Ultrawork mode activated")
+      expect(parts[0].text).toContain("User message")
+    })
+
+    it("uses separator between context and original message", () => {
+      // #given
+      const sessionID = "ses_inject2"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "Context content",
+      })
+      const parts = [{ type: "text", text: "Original message" }]
+
+      // #when
+      injectPendingContext(collector, sessionID, parts)
+
+      // #then
+      expect(parts[0].text).toBe("Context content\n\n---\n\nOriginal message")
+    })
+
+    it("consumes context after injection", () => {
+      // #given
+      const sessionID = "ses_inject3"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "Context",
+      })
+      const parts = [{ type: "text", text: "Message" }]
+
+      // #when
+      injectPendingContext(collector, sessionID, parts)
+
+      // #then
+      expect(collector.hasPending(sessionID)).toBe(false)
+    })
+
+    it("returns injected=false when no pending context", () => {
+      // #given
+      const sessionID = "ses_empty"
+      const parts = [{ type: "text", text: "Message" }]
+
+      // #when
+      const result = injectPendingContext(collector, sessionID, parts)
+
+      // #then
+      expect(result.injected).toBe(false)
+      expect(parts[0].text).toBe("Message")
+    })
+  })
+
+  describe("when parts have no text content", () => {
+    it("does not inject and preserves context", () => {
+      // #given
+      const sessionID = "ses_notext"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "Context",
+      })
+      const parts = [{ type: "image", url: "https://example.com/img.png" }]
+
+      // #when
+      const result = injectPendingContext(collector, sessionID, parts)
+
+      // #then
+      expect(result.injected).toBe(false)
+      expect(collector.hasPending(sessionID)).toBe(true)
+    })
+  })
+
+  describe("with multiple text parts", () => {
+    it("injects into first text part only", () => {
+      // #given
+      const sessionID = "ses_multi"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "Context",
+      })
+      const parts = [
+        { type: "text", text: "First" },
+        { type: "text", text: "Second" },
+      ]
+
+      // #when
+      injectPendingContext(collector, sessionID, parts)
+
+      // #then
+      expect(parts[0].text).toContain("Context")
+      expect(parts[1].text).toBe("Second")
+    })
+  })
+})
+
+describe("createContextInjectorHook", () => {
+  let collector: ContextCollector
+
+  beforeEach(() => {
+    collector = new ContextCollector()
+  })
+
+  describe("chat.message handler", () => {
+    it("is a no-op (context injection moved to messages transform)", async () => {
+      // #given
+      const hook = createContextInjectorHook(collector)
+      const sessionID = "ses_hook1"
+      collector.register(sessionID, {
+        id: "ctx",
+        source: "keyword-detector",
+        content: "Hook context",
+      })
+      const input = { sessionID }
+      const output = {
+        message: {},
+        parts: [{ type: "text", text: "User message" }],
+      }
+
+      // #when
+      await hook["chat.message"](input, output)
+
+      // #then
+      expect(output.parts[0].text).toBe("User message")
+      expect(collector.hasPending(sessionID)).toBe(true)
+    })
+
+    it("does nothing when no pending context", async () => {
+      // #given
+      const hook = createContextInjectorHook(collector)
+      const sessionID = "ses_hook2"
+      const input = { sessionID }
+      const output = {
+        message: {},
+        parts: [{ type: "text", text: "User message" }],
+      }
+
+      // #when
+      await hook["chat.message"](input, output)
+
+      // #then
+      expect(output.parts[0].text).toBe("User message")
+    })
+  })
+})
+
+describe("createContextInjectorMessagesTransformHook", () => {
+  let collector: ContextCollector
+
+  beforeEach(() => {
+    collector = new ContextCollector()
+  })
+
+  const createMockMessage = (
+    role: "user" | "assistant",
+    text: string,
+    sessionID: string
+  ) => ({
+    info: {
+      id: `msg_${Date.now()}_${Math.random()}`,
+      sessionID,
+      role,
+      time: { created: Date.now() },
+      agent: "Sisyphus",
+      model: { providerID: "test", modelID: "test" },
+      path: { cwd: "/", root: "/" },
+    },
+    parts: [
+      {
+        id: `part_${Date.now()}`,
+        sessionID,
+        messageID: `msg_${Date.now()}`,
+        type: "text" as const,
+        text,
+      },
+    ],
+  })
+
+  it("inserts synthetic message before last user message", async () => {
+    // #given
+    const hook = createContextInjectorMessagesTransformHook(collector)
+    const sessionID = "ses_transform1"
+    collector.register(sessionID, {
+      id: "ulw",
+      source: "keyword-detector",
+      content: "Ultrawork context",
+    })
+    const messages = [
+      createMockMessage("user", "First message", sessionID),
+      createMockMessage("assistant", "Response", sessionID),
+      createMockMessage("user", "Second message", sessionID),
+    ]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const output = { messages } as any
+
+    // #when
+    await hook["experimental.chat.messages.transform"]!({}, output)
+
+    // #then
+    expect(output.messages.length).toBe(4)
+    expect(output.messages[2].parts[0].text).toBe("Ultrawork context")
+    expect(output.messages[2].parts[0].synthetic).toBe(true)
+    expect(output.messages[3].parts[0].text).toBe("Second message")
+  })
+
+  it("does nothing when no pending context", async () => {
+    // #given
+    const hook = createContextInjectorMessagesTransformHook(collector)
+    const sessionID = "ses_transform2"
+    const messages = [createMockMessage("user", "Hello world", sessionID)]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const output = { messages } as any
+
+    // #when
+    await hook["experimental.chat.messages.transform"]!({}, output)
+
+    // #then
+    expect(output.messages.length).toBe(1)
+  })
+
+  it("does nothing when no user messages", async () => {
+    // #given
+    const hook = createContextInjectorMessagesTransformHook(collector)
+    const sessionID = "ses_transform3"
+    collector.register(sessionID, {
+      id: "ctx",
+      source: "keyword-detector",
+      content: "Context",
+    })
+    const messages = [createMockMessage("assistant", "Response", sessionID)]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const output = { messages } as any
+
+    // #when
+    await hook["experimental.chat.messages.transform"]!({}, output)
+
+    // #then
+    expect(output.messages.length).toBe(1)
+    expect(collector.hasPending(sessionID)).toBe(true)
+  })
+
+  it("consumes context after injection", async () => {
+    // #given
+    const hook = createContextInjectorMessagesTransformHook(collector)
+    const sessionID = "ses_transform4"
+    collector.register(sessionID, {
+      id: "ctx",
+      source: "keyword-detector",
+      content: "Context",
+    })
+    const messages = [createMockMessage("user", "Message", sessionID)]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const output = { messages } as any
+
+    // #when
+    await hook["experimental.chat.messages.transform"]!({}, output)
+
+    // #then
+    expect(collector.hasPending(sessionID)).toBe(false)
+  })
+})

src/features/context-injector/injector.ts

@@ -0,0 +1,156 @@
+import type { ContextCollector } from "./collector"
+import type { Message, Part } from "@opencode-ai/sdk"
+import { log } from "../../shared"
+
+interface OutputPart {
+  type: string
+  text?: string
+  [key: string]: unknown
+}
+
+interface InjectionResult {
+  injected: boolean
+  contextLength: number
+}
+
+export function injectPendingContext(
+  collector: ContextCollector,
+  sessionID: string,
+  parts: OutputPart[]
+): InjectionResult {
+  if (!collector.hasPending(sessionID)) {
+    return { injected: false, contextLength: 0 }
+  }
+
+  const textPartIndex = parts.findIndex((p) => p.type === "text" && p.text !== undefined)
+  if (textPartIndex === -1) {
+    return { injected: false, contextLength: 0 }
+  }
+
+  const pending = collector.consume(sessionID)
+  const originalText = parts[textPartIndex].text ?? ""
+  parts[textPartIndex].text = `${pending.merged}\n\n---\n\n${originalText}`
+
+  return {
+    injected: true,
+    contextLength: pending.merged.length,
+  }
+}
+
+interface ChatMessageInput {
+  sessionID: string
+  agent?: string
+  model?: { providerID: string; modelID: string }
+  messageID?: string
+}
+
+interface ChatMessageOutput {
+  message: Record<string, unknown>
+  parts: OutputPart[]
+}
+
+export function createContextInjectorHook(collector: ContextCollector) {
+  return {
+    "chat.message": async (
+      _input: ChatMessageInput,
+      _output: ChatMessageOutput
+    ): Promise<void> => {
+      void collector
+    },
+  }
+}
+
+interface MessageWithParts {
+  info: Message
+  parts: Part[]
+}
+
+type MessagesTransformHook = {
+  "experimental.chat.messages.transform"?: (
+    input: Record<string, never>,
+    output: { messages: MessageWithParts[] }
+  ) => Promise<void>
+}
+
+export function createContextInjectorMessagesTransformHook(
+  collector: ContextCollector
+): MessagesTransformHook {
+  return {
+    "experimental.chat.messages.transform": async (_input, output) => {
+      const { messages } = output
+      if (messages.length === 0) {
+        return
+      }
+
+      let lastUserMessageIndex = -1
+      for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].info.role === "user") {
+          lastUserMessageIndex = i
+          break
+        }
+      }
+
+      if (lastUserMessageIndex === -1) {
+        return
+      }
+
+      const lastUserMessage = messages[lastUserMessageIndex]
+      const sessionID = (lastUserMessage.info as unknown as { sessionID?: string }).sessionID
+      if (!sessionID) {
+        return
+      }
+
+      if (!collector.hasPending(sessionID)) {
+        return
+      }
+
+      const pending = collector.consume(sessionID)
+      if (!pending.hasContent) {
+        return
+      }
+
+      const refInfo = lastUserMessage.info as unknown as {
+        sessionID?: string
+        agent?: string
+        model?: { providerID?: string; modelID?: string }
+        path?: { cwd?: string; root?: string }
+      }
+
+      const syntheticMessageId = `synthetic_ctx_${Date.now()}`
+      const syntheticPartId = `synthetic_ctx_part_${Date.now()}`
+      const now = Date.now()
+
+      const syntheticMessage: MessageWithParts = {
+        info: {
+          id: syntheticMessageId,
+          sessionID: sessionID,
+          role: "user",
+          time: { created: now },
+          agent: refInfo.agent ?? "Sisyphus",
+          model: refInfo.model ?? { providerID: "unknown", modelID: "unknown" },
+          path: refInfo.path ?? { cwd: "/", root: "/" },
+        } as unknown as Message,
+        parts: [
+          {
+            id: syntheticPartId,
+            sessionID: sessionID,
+            messageID: syntheticMessageId,
+            type: "text",
+            text: pending.merged,
+            synthetic: true,
+            time: { start: now, end: now },
+          } as Part,
+        ],
+      }
+
+      messages.splice(lastUserMessageIndex, 0, syntheticMessage)
+
+      log("[context-injector] Injected synthetic message from collector", {
+        sessionID,
+        insertIndex: lastUserMessageIndex,
+        contextLength: pending.merged.length,
+        newMessageCount: messages.length,
+      })
+    },
+  }
+}

src/features/context-injector/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Source identifier for context injection
+ * Each source registers context that will be merged and injected together
+ */
+export type ContextSourceType =
+  | "keyword-detector"
+  | "rules-injector"
+  | "directory-agents"
+  | "directory-readme"
+  | "custom"
+
+/**
+ * Priority levels for context ordering
+ * Higher priority contexts appear first in the merged output
+ */
+export type ContextPriority = "critical" | "high" | "normal" | "low"
+
+/**
+ * A single context entry registered by a source
+ */
+export interface ContextEntry {
+  /** Unique identifier for this entry within the source */
+  id: string
+  /** The source that registered this context */
+  source: ContextSourceType
+  /** The actual context content to inject */
+  content: string
+  /** Priority for ordering (default: normal) */
+  priority: ContextPriority
+  /** Timestamp when registered */
+  timestamp: number
+  /** Optional metadata for debugging/logging */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Options for registering context
+ */
+export interface RegisterContextOptions {
+  /** Unique ID for this context entry (used for deduplication) */
+  id: string
+  /** Source identifier */
+  source: ContextSourceType
+  /** The content to inject */
+  content: string
+  /** Priority for ordering (default: normal) */
+  priority?: ContextPriority
+  /** Optional metadata */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Result of getting pending context for a session
+ */
+export interface PendingContext {
+  /** Merged context string, ready for injection */
+  merged: string
+  /** Individual entries that were merged */
+  entries: ContextEntry[]
+  /** Whether there's any content to inject */
+  hasContent: boolean
+}
+
+/**
+ * Message context from the original user message
+ * Used when injecting to match the message format
+ */
+export interface MessageContext {
+  agent?: string
+  model?: {
+    providerID?: string
+    modelID?: string
+  }
+  path?: {
+    cwd?: string
+    root?: string
+  }
+  tools?: Record<string, boolean>
+}
+
+/**
+ * Output parts from chat.message hook
+ */
+export interface OutputParts {
+  parts: Array<{ type: string; text?: string; [key: string]: unknown }>
+}
+
+/**
+ * Injection strategy
+ */
+export type InjectionStrategy = "prepend-parts" | "storage" | "auto"

src/features/opencode-skill-loader/async-loader.test.ts

@@ -0,0 +1,448 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { mkdirSync, writeFileSync, rmSync, chmodSync } from "fs"
+import { join } from "path"
+import { tmpdir } from "os"
+import type { LoadedSkill } from "./types"
+
+const TEST_DIR = join(tmpdir(), "async-loader-test-" + Date.now())
+const SKILLS_DIR = join(TEST_DIR, ".opencode", "skill")
+
+function createTestSkill(name: string, content: string, mcpJson?: object): string {
+  const skillDir = join(SKILLS_DIR, name)
+  mkdirSync(skillDir, { recursive: true })
+  const skillPath = join(skillDir, "SKILL.md")
+  writeFileSync(skillPath, content)
+  if (mcpJson) {
+    writeFileSync(join(skillDir, "mcp.json"), JSON.stringify(mcpJson, null, 2))
+  }
+  return skillDir
+}
+
+function createDirectSkill(name: string, content: string): string {
+  mkdirSync(SKILLS_DIR, { recursive: true })
+  const skillPath = join(SKILLS_DIR, `${name}.md`)
+  writeFileSync(skillPath, content)
+  return skillPath
+}
+
+describe("async-loader", () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true })
+  })
+
+  describe("discoverSkillsInDirAsync", () => {
+    it("returns empty array for non-existent directory", async () => {
+      // #given - non-existent directory
+      const nonExistentDir = join(TEST_DIR, "does-not-exist")
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(nonExistentDir)
+
+      // #then - should return empty array, not throw
+      expect(skills).toEqual([])
+    })
+
+    it("discovers skills from SKILL.md in directory", async () => {
+      // #given
+      const skillContent = `---
+name: test-skill
+description: A test skill
+---
+This is the skill body.
+`
+      createTestSkill("test-skill", skillContent)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(skills).toHaveLength(1)
+      expect(skills[0].name).toBe("test-skill")
+      expect(skills[0].definition.description).toContain("A test skill")
+    })
+
+    it("discovers skills from {name}.md pattern in directory", async () => {
+      // #given
+      const skillContent = `---
+name: named-skill
+description: Named pattern skill
+---
+Skill body.
+`
+      const skillDir = join(SKILLS_DIR, "named-skill")
+      mkdirSync(skillDir, { recursive: true })
+      writeFileSync(join(skillDir, "named-skill.md"), skillContent)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(skills).toHaveLength(1)
+      expect(skills[0].name).toBe("named-skill")
+    })
+
+    it("discovers direct .md files", async () => {
+      // #given
+      const skillContent = `---
+name: direct-skill
+description: Direct markdown file
+---
+Direct skill.
+`
+      createDirectSkill("direct-skill", skillContent)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(skills).toHaveLength(1)
+      expect(skills[0].name).toBe("direct-skill")
+    })
+
+    it("skips entries starting with dot", async () => {
+      // #given
+      const validContent = `---
+name: valid-skill
+---
+Valid.
+`
+      const hiddenContent = `---
+name: hidden-skill
+---
+Hidden.
+`
+      createTestSkill("valid-skill", validContent)
+      createTestSkill(".hidden-skill", hiddenContent)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then - only valid-skill should be discovered
+      expect(skills).toHaveLength(1)
+      expect(skills[0]?.name).toBe("valid-skill")
+    })
+
+    it("skips invalid files and continues with valid ones", async () => {
+      // #given - one valid, one invalid (unreadable)
+      const validContent = `---
+name: valid-skill
+---
+Valid skill.
+`
+      const invalidContent = `---
+name: invalid-skill
+---
+Invalid skill.
+`
+      createTestSkill("valid-skill", validContent)
+      const invalidDir = createTestSkill("invalid-skill", invalidContent)
+      const invalidFile = join(invalidDir, "SKILL.md")
+      
+      // Make file unreadable on Unix systems
+      if (process.platform !== "win32") {
+        chmodSync(invalidFile, 0o000)
+      }
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then - should skip invalid and return only valid
+      expect(skills.length).toBeGreaterThanOrEqual(1)
+      expect(skills.some((s: LoadedSkill) => s.name === "valid-skill")).toBe(true)
+
+      // Cleanup: restore permissions before cleanup
+      if (process.platform !== "win32") {
+        chmodSync(invalidFile, 0o644)
+      }
+    })
+
+    it("discovers multiple skills correctly", async () => {
+      // #given
+      const skill1 = `---
+name: skill-one
+description: First skill
+---
+Skill one.
+`
+      const skill2 = `---
+name: skill-two
+description: Second skill
+---
+Skill two.
+`
+      createTestSkill("skill-one", skill1)
+      createTestSkill("skill-two", skill2)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const asyncSkills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(asyncSkills.length).toBe(2)
+      expect(asyncSkills.map((s: LoadedSkill) => s.name).sort()).toEqual(["skill-one", "skill-two"])
+      
+      const skill1Result = asyncSkills.find((s: LoadedSkill) => s.name === "skill-one")
+      expect(skill1Result?.definition.description).toContain("First skill")
+    })
+
+    it("loads MCP config from frontmatter", async () => {
+      // #given
+      const skillContent = `---
+name: mcp-skill
+description: Skill with MCP
+mcp:
+  sqlite:
+    command: uvx
+    args: [mcp-server-sqlite]
+---
+MCP skill.
+`
+      createTestSkill("mcp-skill", skillContent)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then
+      const skill = skills.find((s: LoadedSkill) => s.name === "mcp-skill")
+      expect(skill?.mcpConfig).toBeDefined()
+      expect(skill?.mcpConfig?.sqlite).toBeDefined()
+      expect(skill?.mcpConfig?.sqlite?.command).toBe("uvx")
+    })
+
+    it("loads MCP config from mcp.json file", async () => {
+      // #given
+      const skillContent = `---
+name: json-mcp-skill
+description: Skill with mcp.json
+---
+Skill body.
+`
+      const mcpJson = {
+        mcpServers: {
+          playwright: {
+            command: "npx",
+            args: ["@playwright/mcp"]
+          }
+        }
+      }
+      createTestSkill("json-mcp-skill", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then
+      const skill = skills.find((s: LoadedSkill) => s.name === "json-mcp-skill")
+      expect(skill?.mcpConfig?.playwright).toBeDefined()
+      expect(skill?.mcpConfig?.playwright?.command).toBe("npx")
+    })
+
+    it("prioritizes mcp.json over frontmatter MCP", async () => {
+      // #given
+      const skillContent = `---
+name: priority-test
+mcp:
+  from-yaml:
+    command: yaml-cmd
+---
+Skill.
+`
+      const mcpJson = {
+        mcpServers: {
+          "from-json": {
+            command: "json-cmd"
+          }
+        }
+      }
+      createTestSkill("priority-test", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkillsInDirAsync } = await import("./async-loader")
+      const skills = await discoverSkillsInDirAsync(SKILLS_DIR)
+
+      // #then - mcp.json should take priority
+      const skill = skills.find((s: LoadedSkill) => s.name === "priority-test")
+      expect(skill?.mcpConfig?.["from-json"]).toBeDefined()
+      expect(skill?.mcpConfig?.["from-yaml"]).toBeUndefined()
+    })
+  })
+
+  describe("mapWithConcurrency", () => {
+    it("processes items with concurrency limit", async () => {
+      // #given
+      const { mapWithConcurrency } = await import("./async-loader")
+      const items = Array.from({ length: 50 }, (_, i) => i)
+      let maxConcurrent = 0
+      let currentConcurrent = 0
+
+      const mapper = async (item: number) => {
+        currentConcurrent++
+        maxConcurrent = Math.max(maxConcurrent, currentConcurrent)
+        await new Promise(resolve => setTimeout(resolve, 10))
+        currentConcurrent--
+        return item * 2
+      }
+
+      // #when
+      const results = await mapWithConcurrency(items, mapper, 16)
+
+      // #then
+      expect(results).toEqual(items.map(i => i * 2))
+      expect(maxConcurrent).toBeLessThanOrEqual(16)
+      expect(maxConcurrent).toBeGreaterThan(1) // Should actually run concurrently
+    })
+
+    it("handles empty array", async () => {
+      // #given
+      const { mapWithConcurrency } = await import("./async-loader")
+
+      // #when
+      const results = await mapWithConcurrency([], async (x: number) => x * 2, 16)
+
+      // #then
+      expect(results).toEqual([])
+    })
+
+    it("handles single item", async () => {
+      // #given
+      const { mapWithConcurrency } = await import("./async-loader")
+
+      // #when
+      const results = await mapWithConcurrency([42], async (x: number) => x * 2, 16)
+
+      // #then
+      expect(results).toEqual([84])
+    })
+  })
+
+  describe("loadSkillFromPathAsync", () => {
+    it("loads skill from valid path", async () => {
+      // #given
+      const skillContent = `---
+name: path-skill
+description: Loaded from path
+---
+Path skill.
+`
+      const skillDir = createTestSkill("path-skill", skillContent)
+      const skillPath = join(skillDir, "SKILL.md")
+
+      // #when
+      const { loadSkillFromPathAsync } = await import("./async-loader")
+      const skill = await loadSkillFromPathAsync(skillPath, skillDir, "path-skill", "opencode-project")
+
+      // #then
+      expect(skill).not.toBeNull()
+      expect(skill?.name).toBe("path-skill")
+      expect(skill?.scope).toBe("opencode-project")
+    })
+
+    it("returns null for invalid path", async () => {
+      // #given
+      const invalidPath = join(TEST_DIR, "nonexistent.md")
+
+      // #when
+      const { loadSkillFromPathAsync } = await import("./async-loader")
+      const skill = await loadSkillFromPathAsync(invalidPath, TEST_DIR, "invalid", "opencode")
+
+      // #then
+      expect(skill).toBeNull()
+    })
+
+    it("returns null for malformed skill file", async () => {
+      // #given
+      const malformedContent = "This is not valid frontmatter content\nNo YAML here!"
+      mkdirSync(SKILLS_DIR, { recursive: true })
+      const malformedPath = join(SKILLS_DIR, "malformed.md")
+      writeFileSync(malformedPath, malformedContent)
+
+      // #when
+      const { loadSkillFromPathAsync } = await import("./async-loader")
+      const skill = await loadSkillFromPathAsync(malformedPath, SKILLS_DIR, "malformed", "user")
+
+      // #then
+      expect(skill).not.toBeNull() // parseFrontmatter handles missing frontmatter gracefully
+    })
+  })
+
+  describe("loadMcpJsonFromDirAsync", () => {
+    it("loads mcp.json with mcpServers format", async () => {
+      // #given
+      mkdirSync(SKILLS_DIR, { recursive: true })
+      const mcpJson = {
+        mcpServers: {
+          test: {
+            command: "test-cmd",
+            args: ["arg1"]
+          }
+        }
+      }
+      writeFileSync(join(SKILLS_DIR, "mcp.json"), JSON.stringify(mcpJson))
+
+      // #when
+      const { loadMcpJsonFromDirAsync } = await import("./async-loader")
+      const config = await loadMcpJsonFromDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(config).toBeDefined()
+      expect(config?.test).toBeDefined()
+      expect(config?.test?.command).toBe("test-cmd")
+    })
+
+    it("returns undefined for non-existent mcp.json", async () => {
+      // #given
+      mkdirSync(SKILLS_DIR, { recursive: true })
+
+      // #when
+      const { loadMcpJsonFromDirAsync } = await import("./async-loader")
+      const config = await loadMcpJsonFromDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(config).toBeUndefined()
+    })
+
+    it("returns undefined for invalid JSON", async () => {
+      // #given
+      mkdirSync(SKILLS_DIR, { recursive: true })
+      writeFileSync(join(SKILLS_DIR, "mcp.json"), "{ invalid json }")
+
+      // #when
+      const { loadMcpJsonFromDirAsync } = await import("./async-loader")
+      const config = await loadMcpJsonFromDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(config).toBeUndefined()
+    })
+
+    it("supports direct format without mcpServers", async () => {
+      // #given
+      mkdirSync(SKILLS_DIR, { recursive: true })
+      const mcpJson = {
+        direct: {
+          command: "direct-cmd",
+          args: ["arg"]
+        }
+      }
+      writeFileSync(join(SKILLS_DIR, "mcp.json"), JSON.stringify(mcpJson))
+
+      // #when
+      const { loadMcpJsonFromDirAsync } = await import("./async-loader")
+      const config = await loadMcpJsonFromDirAsync(SKILLS_DIR)
+
+      // #then
+      expect(config?.direct).toBeDefined()
+      expect(config?.direct?.command).toBe("direct-cmd")
+    })
+  })
+})

src/features/opencode-skill-loader/async-loader.ts

@@ -0,0 +1,180 @@
+import { readFile, readdir } from "fs/promises"
+import type { Dirent } from "fs"
+import { join, basename } from "path"
+import yaml from "js-yaml"
+import { parseFrontmatter } from "../../shared/frontmatter"
+import { sanitizeModelField } from "../../shared/model-sanitizer"
+import { resolveSymlink, isMarkdownFile } from "../../shared/file-utils"
+import type { CommandDefinition } from "../claude-code-command-loader/types"
+import type { SkillScope, SkillMetadata, LoadedSkill } from "./types"
+import type { SkillMcpConfig } from "../skill-mcp-manager/types"
+
+export async function mapWithConcurrency<T, R>(
+  items: T[],
+  mapper: (item: T) => Promise<R>,
+  concurrency: number
+): Promise<R[]> {
+  const results: R[] = new Array(items.length)
+  let index = 0
+  
+  const worker = async () => {
+    while (index < items.length) {
+      const currentIndex = index++
+      results[currentIndex] = await mapper(items[currentIndex])
+    }
+  }
+  
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker())
+  await Promise.all(workers)
+  
+  return results
+}
+
+function parseSkillMcpConfigFromFrontmatter(content: string): SkillMcpConfig | undefined {
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!frontmatterMatch) return undefined
+
+  try {
+    const parsed = yaml.load(frontmatterMatch[1]) as Record<string, unknown>
+    if (parsed && typeof parsed === "object" && "mcp" in parsed && parsed.mcp) {
+      return parsed.mcp as SkillMcpConfig
+    }
+  } catch {
+    return undefined
+  }
+  return undefined
+}
+
+export async function loadMcpJsonFromDirAsync(skillDir: string): Promise<SkillMcpConfig | undefined> {
+  const mcpJsonPath = join(skillDir, "mcp.json")
+
+  try {
+    const content = await readFile(mcpJsonPath, "utf-8")
+    const parsed = JSON.parse(content) as Record<string, unknown>
+    
+    if (parsed && typeof parsed === "object" && "mcpServers" in parsed && parsed.mcpServers) {
+      return parsed.mcpServers as SkillMcpConfig
+    }
+    
+    if (parsed && typeof parsed === "object" && !("mcpServers" in parsed)) {
+      const hasCommandField = Object.values(parsed).some(
+        (v) => v && typeof v === "object" && "command" in (v as Record<string, unknown>)
+      )
+      if (hasCommandField) {
+        return parsed as SkillMcpConfig
+      }
+    }
+  } catch {
+    return undefined
+  }
+  return undefined
+}
+
+export async function loadSkillFromPathAsync(
+  skillPath: string,
+  resolvedPath: string,
+  defaultName: string,
+  scope: SkillScope
+): Promise<LoadedSkill | null> {
+  try {
+    const content = await readFile(skillPath, "utf-8")
+    const { data, body, parseError } = parseFrontmatter<SkillMetadata>(content)
+    if (parseError) return null
+    
+    const frontmatterMcp = parseSkillMcpConfigFromFrontmatter(content)
+    const mcpJsonMcp = await loadMcpJsonFromDirAsync(resolvedPath)
+    const mcpConfig = mcpJsonMcp || frontmatterMcp
+
+    const skillName = data.name || defaultName
+    const originalDescription = data.description || ""
+    const isOpencodeSource = scope === "opencode" || scope === "opencode-project"
+    const formattedDescription = `(${scope} - Skill) ${originalDescription}`
+
+    const wrappedTemplate = `<skill-instruction>
+Base directory for this skill: ${resolvedPath}/
+File references (@path) in this skill are relative to this directory.
+
+${body.trim()}
+</skill-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>`
+
+    const definition: CommandDefinition = {
+      name: skillName,
+      description: formattedDescription,
+      template: wrappedTemplate,
+      model: sanitizeModelField(data.model, isOpencodeSource ? "opencode" : "claude-code"),
+      agent: data.agent,
+      subtask: data.subtask,
+      argumentHint: data["argument-hint"],
+    }
+
+    return {
+      name: skillName,
+      path: skillPath,
+      resolvedPath,
+      definition,
+      scope,
+      license: data.license,
+      compatibility: data.compatibility,
+      metadata: data.metadata,
+      allowedTools: parseAllowedTools(data["allowed-tools"]),
+      mcpConfig,
+    }
+  } catch {
+    return null
+  }
+}
+
+function parseAllowedTools(allowedTools: string | undefined): string[] | undefined {
+  if (!allowedTools) return undefined
+  return allowedTools.split(/\s+/).filter(Boolean)
+}
+
+export async function discoverSkillsInDirAsync(skillsDir: string): Promise<LoadedSkill[]> {
+  try {
+    const entries = await readdir(skillsDir, { withFileTypes: true })
+    
+    const processEntry = async (entry: Dirent): Promise<LoadedSkill | null> => {
+      if (entry.name.startsWith(".")) return null
+
+      const entryPath = join(skillsDir, entry.name)
+
+      if (entry.isDirectory() || entry.isSymbolicLink()) {
+        const resolvedPath = resolveSymlink(entryPath)
+        const dirName = entry.name
+
+        const skillMdPath = join(resolvedPath, "SKILL.md")
+        try {
+          await readFile(skillMdPath, "utf-8")
+          return await loadSkillFromPathAsync(skillMdPath, resolvedPath, dirName, "opencode-project")
+        } catch {
+          const namedSkillMdPath = join(resolvedPath, `${dirName}.md`)
+          try {
+            await readFile(namedSkillMdPath, "utf-8")
+            return await loadSkillFromPathAsync(namedSkillMdPath, resolvedPath, dirName, "opencode-project")
+          } catch {
+            return null
+          }
+        }
+      }
+
+      if (isMarkdownFile(entry)) {
+        const skillName = basename(entry.name, ".md")
+        return await loadSkillFromPathAsync(entryPath, skillsDir, skillName, "opencode-project")
+      }
+
+      return null
+    }
+
+    const skillPromises = await mapWithConcurrency(entries, processEntry, 16)
+    return skillPromises.filter((skill): skill is LoadedSkill => skill !== null)
+  } catch (error: unknown) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return []
+    }
+    return []
+  }
+}

src/features/opencode-skill-loader/blocking.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { mkdirSync, writeFileSync, rmSync } from "fs"
+import { join } from "path"
+import { tmpdir } from "os"
+import { discoverAllSkillsBlocking } from "./blocking"
+import type { SkillScope } from "./types"
+
+const TEST_DIR = join(tmpdir(), `blocking-test-${Date.now()}`)
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true })
+})
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true })
+})
+
+describe("discoverAllSkillsBlocking", () => {
+  it("returns skills synchronously from valid directories", () => {
+    // #given valid skill directory
+    const skillDir = join(TEST_DIR, "skills")
+    mkdirSync(skillDir, { recursive: true })
+
+    const skillMdPath = join(skillDir, "test-skill.md")
+    writeFileSync(
+      skillMdPath,
+      `---
+name: test-skill
+description: A test skill
+---
+This is test skill content.`
+    )
+
+    const dirs = [skillDir]
+    const scopes: SkillScope[] = ["opencode-project"]
+
+    // #when discoverAllSkillsBlocking called
+    const skills = discoverAllSkillsBlocking(dirs, scopes)
+
+    // #then returns skills synchronously
+    expect(skills).toBeArray()
+    expect(skills.length).toBe(1)
+    expect(skills[0].name).toBe("test-skill")
+    expect(skills[0].definition.description).toContain("test skill")
+  })
+
+  it("returns empty array for empty directories", () => {
+    // #given empty directory
+    const emptyDir = join(TEST_DIR, "empty")
+    mkdirSync(emptyDir, { recursive: true })
+
+    const dirs = [emptyDir]
+    const scopes: SkillScope[] = ["opencode-project"]
+
+    // #when discoverAllSkillsBlocking called
+    const skills = discoverAllSkillsBlocking(dirs, scopes)
+
+    // #then returns empty array
+    expect(skills).toBeArray()
+    expect(skills.length).toBe(0)
+  })
+
+  it("returns empty array for non-existent directories", () => {
+    // #given non-existent directory
+    const nonExistentDir = join(TEST_DIR, "does-not-exist")
+
+    const dirs = [nonExistentDir]
+    const scopes: SkillScope[] = ["opencode-project"]
+
+    // #when discoverAllSkillsBlocking called
+    const skills = discoverAllSkillsBlocking(dirs, scopes)
+
+    // #then returns empty array (no throw)
+    expect(skills).toBeArray()
+    expect(skills.length).toBe(0)
+  })
+
+  it("handles multiple directories with mixed content", () => {
+    // #given multiple directories with valid and invalid skills
+    const dir1 = join(TEST_DIR, "dir1")
+    const dir2 = join(TEST_DIR, "dir2")
+    mkdirSync(dir1, { recursive: true })
+    mkdirSync(dir2, { recursive: true })
+
+    writeFileSync(
+      join(dir1, "skill1.md"),
+      `---
+name: skill1
+description: First skill
+---
+Skill 1 content.`
+    )
+
+    writeFileSync(
+      join(dir2, "skill2.md"),
+      `---
+name: skill2
+description: Second skill
+---
+Skill 2 content.`
+    )
+
+    const dirs = [dir1, dir2]
+    const scopes: SkillScope[] = ["opencode-project"]
+
+    // #when discoverAllSkillsBlocking called
+    const skills = discoverAllSkillsBlocking(dirs, scopes)
+
+    // #then returns all valid skills
+    expect(skills).toBeArray()
+    expect(skills.length).toBe(2)
+    
+    const skillNames = skills.map(s => s.name).sort()
+    expect(skillNames).toEqual(["skill1", "skill2"])
+  })
+
+  it("skips invalid YAML files", () => {
+    // #given directory with invalid YAML
+    const skillDir = join(TEST_DIR, "skills")
+    mkdirSync(skillDir, { recursive: true })
+
+    const validSkillPath = join(skillDir, "valid.md")
+    writeFileSync(
+      validSkillPath,
+      `---
+name: valid-skill
+description: Valid skill
+---
+Valid skill content.`
+    )
+
+    const invalidSkillPath = join(skillDir, "invalid.md")
+    writeFileSync(
+      invalidSkillPath,
+      `---
+name: invalid skill
+description: [ invalid yaml
+---
+Invalid content.`
+    )
+
+    const dirs = [skillDir]
+    const scopes: SkillScope[] = ["opencode-project"]
+
+    // #when discoverAllSkillsBlocking called
+    const skills = discoverAllSkillsBlocking(dirs, scopes)
+
+    // #then skips invalid, returns valid
+    expect(skills).toBeArray()
+    expect(skills.length).toBe(1)
+    expect(skills[0].name).toBe("valid-skill")
+  })
+
+  it("handles directory-based skills with SKILL.md", () => {
+    // #given directory-based skill structure
+    const skillsDir = join(TEST_DIR, "skills")
+    const mySkillDir = join(skillsDir, "my-skill")
+    mkdirSync(mySkillDir, { recursive: true })
+
+    const skillMdPath = join(mySkillDir, "SKILL.md")
+    writeFileSync(
+      skillMdPath,
+      `---
+name: my-skill
+description: Directory-based skill
+---
+This is a directory-based skill.`
+    )
+
+    const dirs = [skillsDir]
+    const scopes: SkillScope[] = ["opencode-project"]
+
+    // #when discoverAllSkillsBlocking called
+    const skills = discoverAllSkillsBlocking(dirs, scopes)
+
+    // #then returns skill from SKILL.md
+    expect(skills).toBeArray()
+    expect(skills.length).toBe(1)
+    expect(skills[0].name).toBe("my-skill")
+  })
+
+  it("processes large skill sets without timeout", () => {
+    // #given directory with many skills (20+)
+    const skillDir = join(TEST_DIR, "many-skills")
+    mkdirSync(skillDir, { recursive: true })
+
+    const skillCount = 25
+    for (let i = 0; i < skillCount; i++) {
+      const skillPath = join(skillDir, `skill-${i}.md`)
+      writeFileSync(
+        skillPath,
+        `---
+name: skill-${i}
+description: Skill number ${i}
+---
+Content for skill ${i}.`
+      )
+    }
+
+    const dirs = [skillDir]
+    const scopes: SkillScope[] = ["opencode-project"]
+
+    // #when discoverAllSkillsBlocking called
+    const skills = discoverAllSkillsBlocking(dirs, scopes)
+
+    // #then completes without timeout
+    expect(skills).toBeArray()
+    expect(skills.length).toBe(skillCount)
+  })
+})

src/features/opencode-skill-loader/blocking.ts

@@ -0,0 +1,62 @@
+import { Worker, MessageChannel, receiveMessageOnPort } from "worker_threads"
+import type { LoadedSkill, SkillScope } from "./types"
+
+interface WorkerInput {
+  dirs: string[]
+  scopes: SkillScope[]
+}
+
+interface WorkerOutputSuccess {
+  ok: true
+  skills: LoadedSkill[]
+}
+
+interface WorkerOutputError {
+  ok: false
+  error: { message: string; stack?: string }
+}
+
+type WorkerOutput = WorkerOutputSuccess | WorkerOutputError
+
+const TIMEOUT_MS = 30000
+
+export function discoverAllSkillsBlocking(dirs: string[], scopes: SkillScope[]): LoadedSkill[] {
+  const signal = new Int32Array(new SharedArrayBuffer(4))
+  const { port1, port2 } = new MessageChannel()
+  
+  const worker = new Worker(new URL("./discover-worker.ts", import.meta.url), {
+    workerData: { signal }
+  })
+
+  worker.postMessage({ port: port2 }, [port2])
+  
+  const input: WorkerInput = { dirs, scopes }
+  port1.postMessage(input)
+
+  const waitResult = Atomics.wait(signal, 0, 0, TIMEOUT_MS)
+
+  if (waitResult === "timed-out") {
+    worker.terminate()
+    port1.close()
+    throw new Error(`Worker timeout after ${TIMEOUT_MS}ms`)
+  }
+
+  const message = receiveMessageOnPort(port1)
+  
+  worker.terminate()
+  port1.close()
+
+  if (!message) {
+    throw new Error("Worker did not return result")
+  }
+
+  const output = message.message as WorkerOutput
+
+  if (output.ok === false) {
+    const error = new Error(output.error.message)
+    error.stack = output.error.stack
+    throw error
+  }
+
+  return output.skills
+}

src/features/opencode-skill-loader/discover-worker.ts

@@ -0,0 +1,59 @@
+import { workerData, parentPort } from "worker_threads"
+import type { MessagePort } from "worker_threads"
+import { discoverSkillsInDirAsync } from "./async-loader"
+import type { LoadedSkill, SkillScope } from "./types"
+
+interface WorkerInput {
+  dirs: string[]
+  scopes: SkillScope[]
+}
+
+interface WorkerOutputSuccess {
+  ok: true
+  skills: LoadedSkill[]
+}
+
+interface WorkerOutputError {
+  ok: false
+  error: { message: string; stack?: string }
+}
+
+type WorkerOutput = WorkerOutputSuccess | WorkerOutputError
+
+const { signal } = workerData as { signal: Int32Array }
+
+if (!parentPort) {
+  throw new Error("Worker must be run with parentPort")
+}
+
+parentPort.once("message", (data: { port: MessagePort }) => {
+  const { port } = data
+
+  port.on("message", async (input: WorkerInput) => {
+    try {
+      const results = await Promise.all(
+        input.dirs.map(dir => discoverSkillsInDirAsync(dir))
+      )
+      
+      const skills = results.flat()
+      
+      const output: WorkerOutputSuccess = { ok: true, skills }
+      
+      port.postMessage(output)
+      Atomics.store(signal, 0, 1)
+      Atomics.notify(signal, 0)
+    } catch (error: unknown) {
+      const output: WorkerOutputError = {
+        ok: false,
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+        },
+      }
+      
+      port.postMessage(output)
+      Atomics.store(signal, 0, 1)
+      Atomics.notify(signal, 0)
+    }
+  })
+})

src/features/opencode-skill-loader/loader.test.ts

@@ -0,0 +1,273 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { mkdirSync, writeFileSync, rmSync } from "fs"
+import { join } from "path"
+import { tmpdir } from "os"
+
+const TEST_DIR = join(tmpdir(), "skill-loader-test-" + Date.now())
+const SKILLS_DIR = join(TEST_DIR, ".opencode", "skill")
+
+function createTestSkill(name: string, content: string, mcpJson?: object): string {
+  const skillDir = join(SKILLS_DIR, name)
+  mkdirSync(skillDir, { recursive: true })
+  const skillPath = join(skillDir, "SKILL.md")
+  writeFileSync(skillPath, content)
+  if (mcpJson) {
+    writeFileSync(join(skillDir, "mcp.json"), JSON.stringify(mcpJson, null, 2))
+  }
+  return skillDir
+}
+
+describe("skill loader MCP parsing", () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true })
+  })
+
+  describe("parseSkillMcpConfig", () => {
+    it("parses skill with nested MCP config", async () => {
+      // #given
+      const skillContent = `---
+name: test-skill
+description: A test skill with MCP
+mcp:
+  sqlite:
+    command: uvx
+    args:
+      - mcp-server-sqlite
+      - --db-path
+      - ./data.db
+  memory:
+    command: npx
+    args: [-y, "@anthropic-ai/mcp-server-memory"]
+---
+This is the skill body.
+`
+      createTestSkill("test-mcp-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = await discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "test-skill")
+
+        // #then
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeDefined()
+        expect(skill?.mcpConfig?.sqlite).toBeDefined()
+        expect(skill?.mcpConfig?.sqlite?.command).toBe("uvx")
+        expect(skill?.mcpConfig?.sqlite?.args).toEqual([
+          "mcp-server-sqlite",
+          "--db-path",
+          "./data.db"
+        ])
+        expect(skill?.mcpConfig?.memory).toBeDefined()
+        expect(skill?.mcpConfig?.memory?.command).toBe("npx")
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("returns undefined mcpConfig for skill without MCP", async () => {
+      // #given
+      const skillContent = `---
+name: simple-skill
+description: A simple skill without MCP
+---
+This is a simple skill.
+`
+      createTestSkill("simple-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = await discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "simple-skill")
+
+        // #then
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeUndefined()
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("preserves env var placeholders without expansion", async () => {
+      // #given
+      const skillContent = `---
+name: env-skill
+mcp:
+  api-server:
+    command: node
+    args: [server.js]
+    env:
+      API_KEY: "\${API_KEY}"
+      DB_PATH: "\${HOME}/data.db"
+---
+Skill with env vars.
+`
+      createTestSkill("env-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = await discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "env-skill")
+
+        // #then
+        expect(skill?.mcpConfig?.["api-server"]?.env?.API_KEY).toBe("${API_KEY}")
+        expect(skill?.mcpConfig?.["api-server"]?.env?.DB_PATH).toBe("${HOME}/data.db")
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("handles malformed YAML gracefully", async () => {
+      // #given - malformed YAML causes entire frontmatter to fail parsing
+      const skillContent = `---
+name: bad-yaml
+mcp: [this is not valid yaml for mcp
+---
+Skill body.
+`
+      createTestSkill("bad-yaml-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = await discoverSkills({ includeClaudeCodePaths: false })
+        // #then - when YAML fails, skill uses directory name as fallback
+        const skill = skills.find(s => s.name === "bad-yaml-skill")
+
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeUndefined()
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+  })
+
+  describe("mcp.json file loading (AmpCode compat)", () => {
+    it("loads MCP config from mcp.json with mcpServers format", async () => {
+      // #given
+      const skillContent = `---
+name: ampcode-skill
+description: Skill with mcp.json
+---
+Skill body.
+`
+      const mcpJson = {
+        mcpServers: {
+          playwright: {
+            command: "npx",
+            args: ["@playwright/mcp@latest"]
+          }
+        }
+      }
+      createTestSkill("ampcode-skill", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = await discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "ampcode-skill")
+
+        // #then
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeDefined()
+        expect(skill?.mcpConfig?.playwright).toBeDefined()
+        expect(skill?.mcpConfig?.playwright?.command).toBe("npx")
+        expect(skill?.mcpConfig?.playwright?.args).toEqual(["@playwright/mcp@latest"])
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("mcp.json takes priority over YAML frontmatter", async () => {
+      // #given
+      const skillContent = `---
+name: priority-skill
+mcp:
+  from-yaml:
+    command: yaml-cmd
+    args: [yaml-arg]
+---
+Skill body.
+`
+      const mcpJson = {
+        mcpServers: {
+          "from-json": {
+            command: "json-cmd",
+            args: ["json-arg"]
+          }
+        }
+      }
+      createTestSkill("priority-skill", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = await discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "priority-skill")
+
+        // #then - mcp.json should take priority
+        expect(skill?.mcpConfig?.["from-json"]).toBeDefined()
+        expect(skill?.mcpConfig?.["from-yaml"]).toBeUndefined()
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("supports direct format without mcpServers wrapper", async () => {
+      // #given
+      const skillContent = `---
+name: direct-format
+---
+Skill body.
+`
+      const mcpJson = {
+        sqlite: {
+          command: "uvx",
+          args: ["mcp-server-sqlite"]
+        }
+      }
+      createTestSkill("direct-format", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = await discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "direct-format")
+
+        // #then
+        expect(skill?.mcpConfig?.sqlite).toBeDefined()
+        expect(skill?.mcpConfig?.sqlite?.command).toBe("uvx")
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+  })
+})

src/features/opencode-skill-loader/loader.ts

@@ -1,42 +1,86 @@
-import { existsSync, readdirSync, readFileSync } from "fs"
-import { join, basename, dirname } from "path"
+import { promises as fs } from "fs"
+import { join, basename } from "path"
 import { homedir } from "os"
+import yaml from "js-yaml"
 import { parseFrontmatter } from "../../shared/frontmatter"
 import { sanitizeModelField } from "../../shared/model-sanitizer"
-import { resolveSymlink, isMarkdownFile } from "../../shared/file-utils"
+import { resolveSymlinkAsync, isMarkdownFile } from "../../shared/file-utils"
 import { getClaudeConfigDir } from "../../shared"
 import type { CommandDefinition } from "../claude-code-command-loader/types"
-import type { SkillScope, SkillMetadata, LoadedSkill } from "./types"
+import type { SkillScope, SkillMetadata, LoadedSkill, LazyContentLoader } from "./types"
+import type { SkillMcpConfig } from "../skill-mcp-manager/types"
+
+function parseSkillMcpConfigFromFrontmatter(content: string): SkillMcpConfig | undefined {
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!frontmatterMatch) return undefined
+
+  try {
+    const parsed = yaml.load(frontmatterMatch[1]) as Record<string, unknown>
+    if (parsed && typeof parsed === "object" && "mcp" in parsed && parsed.mcp) {
+      return parsed.mcp as SkillMcpConfig
+    }
+  } catch {
+    return undefined
+  }
+  return undefined
+}
+
+async function loadMcpJsonFromDir(skillDir: string): Promise<SkillMcpConfig | undefined> {
+  const mcpJsonPath = join(skillDir, "mcp.json")
+  
+  try {
+    const content = await fs.readFile(mcpJsonPath, "utf-8")
+    const parsed = JSON.parse(content) as Record<string, unknown>
+    
+    if (parsed && typeof parsed === "object" && "mcpServers" in parsed && parsed.mcpServers) {
+      return parsed.mcpServers as SkillMcpConfig
+    }
+    
+    if (parsed && typeof parsed === "object" && !("mcpServers" in parsed)) {
+      const hasCommandField = Object.values(parsed).some(
+        (v) => v && typeof v === "object" && "command" in (v as Record<string, unknown>)
+      )
+      if (hasCommandField) {
+        return parsed as SkillMcpConfig
+      }
+    }
+  } catch {
+    return undefined
+  }
+  return undefined
+}
 
-/**
- * Load a skill from a markdown file path.
- * 
- * @param skillPath - Path to the skill file (SKILL.md or {name}.md)
- * @param resolvedPath - Directory for file reference resolution (@path references)
- * @param defaultName - Fallback name if not specified in frontmatter
- * @param scope - Source scope for priority ordering
- */
 function parseAllowedTools(allowedTools: string | undefined): string[] | undefined {
   if (!allowedTools) return undefined
   return allowedTools.split(/\s+/).filter(Boolean)
 }
 
-function loadSkillFromPath(
+async function loadSkillFromPath(
   skillPath: string,
   resolvedPath: string,
   defaultName: string,
   scope: SkillScope
-): LoadedSkill | null {
+): Promise<LoadedSkill | null> {
   try {
-    const content = readFileSync(skillPath, "utf-8")
-    const { data, body } = parseFrontmatter<SkillMetadata>(content)
+    const content = await fs.readFile(skillPath, "utf-8")
+    const { data } = parseFrontmatter<SkillMetadata>(content)
+    const frontmatterMcp = parseSkillMcpConfigFromFrontmatter(content)
+    const mcpJsonMcp = await loadMcpJsonFromDir(resolvedPath)
+    const mcpConfig = mcpJsonMcp || frontmatterMcp
 
     const skillName = data.name || defaultName
     const originalDescription = data.description || ""
     const isOpencodeSource = scope === "opencode" || scope === "opencode-project"
     const formattedDescription = `(${scope} - Skill) ${originalDescription}`
 
-    const wrappedTemplate = `<skill-instruction>
+    const lazyContent: LazyContentLoader = {
+      loaded: false,
+      content: undefined,
+      load: async () => {
+        if (!lazyContent.loaded) {
+          const fileContent = await fs.readFile(skillPath, "utf-8")
+          const { body } = parseFrontmatter<SkillMetadata>(fileContent)
+          lazyContent.content = `<skill-instruction>
 Base directory for this skill: ${resolvedPath}/
 File references (@path) in this skill are relative to this directory.
 
@@ -46,11 +90,16 @@ ${body.trim()}
 <user-request>
 $ARGUMENTS
 </user-request>`
+          lazyContent.loaded = true
+        }
+        return lazyContent.content!
+      },
+    }
 
     const definition: CommandDefinition = {
       name: skillName,
       description: formattedDescription,
-      template: wrappedTemplate,
+      template: "",
       model: sanitizeModelField(data.model, isOpencodeSource ? "opencode" : "claude-code"),
       agent: data.agent,
       subtask: data.subtask,
@@ -67,24 +116,16 @@ $ARGUMENTS
       compatibility: data.compatibility,
       metadata: data.metadata,
       allowedTools: parseAllowedTools(data["allowed-tools"]),
+      mcpConfig,
+      lazyContent,
     }
   } catch {
     return null
   }
 }
 
-/**
- * Load skills from a directory, supporting BOTH patterns:
- * - Directory with SKILL.md: skill-name/SKILL.md
- * - Directory with {SKILLNAME}.md: skill-name/{SKILLNAME}.md
- * - Direct markdown file: skill-name.md
- */
-function loadSkillsFromDir(skillsDir: string, scope: SkillScope): LoadedSkill[] {
-  if (!existsSync(skillsDir)) {
-    return []
-  }
-
-  const entries = readdirSync(skillsDir, { withFileTypes: true })
+async function loadSkillsFromDir(skillsDir: string, scope: SkillScope): Promise<LoadedSkill[]> {
+  const entries = await fs.readdir(skillsDir, { withFileTypes: true }).catch(() => [])
   const skills: LoadedSkill[] = []
 
   for (const entry of entries) {
@@ -93,21 +134,25 @@ function loadSkillsFromDir(skillsDir: string, scope: SkillScope): LoadedSkill[]
     const entryPath = join(skillsDir, entry.name)
 
     if (entry.isDirectory() || entry.isSymbolicLink()) {
-      const resolvedPath = resolveSymlink(entryPath)
+      const resolvedPath = await resolveSymlinkAsync(entryPath)
       const dirName = entry.name
 
       const skillMdPath = join(resolvedPath, "SKILL.md")
-      if (existsSync(skillMdPath)) {
-        const skill = loadSkillFromPath(skillMdPath, resolvedPath, dirName, scope)
+      try {
+        await fs.access(skillMdPath)
+        const skill = await loadSkillFromPath(skillMdPath, resolvedPath, dirName, scope)
         if (skill) skills.push(skill)
         continue
+      } catch {
       }
 
       const namedSkillMdPath = join(resolvedPath, `${dirName}.md`)
-      if (existsSync(namedSkillMdPath)) {
-        const skill = loadSkillFromPath(namedSkillMdPath, resolvedPath, dirName, scope)
+      try {
+        await fs.access(namedSkillMdPath)
+        const skill = await loadSkillFromPath(namedSkillMdPath, resolvedPath, dirName, scope)
         if (skill) skills.push(skill)
         continue
+      } catch {
       }
 
       continue
@@ -115,7 +160,7 @@ function loadSkillsFromDir(skillsDir: string, scope: SkillScope): LoadedSkill[]
 
     if (isMarkdownFile(entry)) {
       const skillName = basename(entry.name, ".md")
-      const skill = loadSkillFromPath(entryPath, skillsDir, skillName, scope)
+      const skill = await loadSkillFromPath(entryPath, skillsDir, skillName, scope)
       if (skill) skills.push(skill)
     }
   }
@@ -126,121 +171,92 @@ function loadSkillsFromDir(skillsDir: string, scope: SkillScope): LoadedSkill[]
 function skillsToRecord(skills: LoadedSkill[]): Record<string, CommandDefinition> {
   const result: Record<string, CommandDefinition> = {}
   for (const skill of skills) {
-    result[skill.name] = skill.definition
+    const { name: _name, argumentHint: _argumentHint, ...openCodeCompatible } = skill.definition
+    result[skill.name] = openCodeCompatible as CommandDefinition
   }
   return result
 }
 
-/**
- * Load skills from Claude Code user directory (~/.claude/skills/)
- */
-export function loadUserSkills(): Record<string, CommandDefinition> {
+export async function loadUserSkills(): Promise<Record<string, CommandDefinition>> {
   const userSkillsDir = join(getClaudeConfigDir(), "skills")
-  const skills = loadSkillsFromDir(userSkillsDir, "user")
+  const skills = await loadSkillsFromDir(userSkillsDir, "user")
   return skillsToRecord(skills)
 }
 
-/**
- * Load skills from Claude Code project directory (.claude/skills/)
- */
-export function loadProjectSkills(): Record<string, CommandDefinition> {
+export async function loadProjectSkills(): Promise<Record<string, CommandDefinition>> {
   const projectSkillsDir = join(process.cwd(), ".claude", "skills")
-  const skills = loadSkillsFromDir(projectSkillsDir, "project")
+  const skills = await loadSkillsFromDir(projectSkillsDir, "project")
   return skillsToRecord(skills)
 }
 
-/**
- * Load skills from OpenCode global directory (~/.config/opencode/skill/)
- */
-export function loadOpencodeGlobalSkills(): Record<string, CommandDefinition> {
+export async function loadOpencodeGlobalSkills(): Promise<Record<string, CommandDefinition>> {
   const opencodeSkillsDir = join(homedir(), ".config", "opencode", "skill")
-  const skills = loadSkillsFromDir(opencodeSkillsDir, "opencode")
+  const skills = await loadSkillsFromDir(opencodeSkillsDir, "opencode")
   return skillsToRecord(skills)
 }
 
-/**
- * Load skills from OpenCode project directory (.opencode/skill/)
- */
-export function loadOpencodeProjectSkills(): Record<string, CommandDefinition> {
+export async function loadOpencodeProjectSkills(): Promise<Record<string, CommandDefinition>> {
   const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
-  const skills = loadSkillsFromDir(opencodeProjectDir, "opencode-project")
+  const skills = await loadSkillsFromDir(opencodeProjectDir, "opencode-project")
   return skillsToRecord(skills)
 }
 
-/**
- * Discover all skills from all sources with priority ordering.
- * Priority order: opencode-project > project > opencode > user
- * 
- * @returns Array of LoadedSkill objects for use in slashcommand discovery
- */
-export function discoverAllSkills(): LoadedSkill[] {
-  const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
-  const projectDir = join(process.cwd(), ".claude", "skills")
-  const opencodeGlobalDir = join(homedir(), ".config", "opencode", "skill")
-  const userDir = join(getClaudeConfigDir(), "skills")
-
-  const opencodeProjectSkills = loadSkillsFromDir(opencodeProjectDir, "opencode-project")
-  const projectSkills = loadSkillsFromDir(projectDir, "project")
-  const opencodeGlobalSkills = loadSkillsFromDir(opencodeGlobalDir, "opencode")
-  const userSkills = loadSkillsFromDir(userDir, "user")
-
-  return [...opencodeProjectSkills, ...projectSkills, ...opencodeGlobalSkills, ...userSkills]
-}
-
 export interface DiscoverSkillsOptions {
   includeClaudeCodePaths?: boolean
 }
 
-/**
- * Discover skills with optional filtering.
- * When includeClaudeCodePaths is false, only loads from OpenCode paths.
- */
-export function discoverSkills(options: DiscoverSkillsOptions = {}): LoadedSkill[] {
+export async function discoverAllSkills(): Promise<LoadedSkill[]> {
+  const [opencodeProjectSkills, projectSkills, opencodeGlobalSkills, userSkills] = await Promise.all([
+    discoverOpencodeProjectSkills(),
+    discoverProjectClaudeSkills(),
+    discoverOpencodeGlobalSkills(),
+    discoverUserClaudeSkills(),
+  ])
+
+  return [...opencodeProjectSkills, ...projectSkills, ...opencodeGlobalSkills, ...userSkills]
+}
+
+export async function discoverSkills(options: DiscoverSkillsOptions = {}): Promise<LoadedSkill[]> {
   const { includeClaudeCodePaths = true } = options
 
-  const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
-  const opencodeGlobalDir = join(homedir(), ".config", "opencode", "skill")
-
-  const opencodeProjectSkills = loadSkillsFromDir(opencodeProjectDir, "opencode-project")
-  const opencodeGlobalSkills = loadSkillsFromDir(opencodeGlobalDir, "opencode")
+  const [opencodeProjectSkills, opencodeGlobalSkills] = await Promise.all([
+    discoverOpencodeProjectSkills(),
+    discoverOpencodeGlobalSkills(),
+  ])
 
   if (!includeClaudeCodePaths) {
     return [...opencodeProjectSkills, ...opencodeGlobalSkills]
   }
 
-  const projectDir = join(process.cwd(), ".claude", "skills")
-  const userDir = join(getClaudeConfigDir(), "skills")
-
-  const projectSkills = loadSkillsFromDir(projectDir, "project")
-  const userSkills = loadSkillsFromDir(userDir, "user")
+  const [projectSkills, userSkills] = await Promise.all([
+    discoverProjectClaudeSkills(),
+    discoverUserClaudeSkills(),
+  ])
 
   return [...opencodeProjectSkills, ...projectSkills, ...opencodeGlobalSkills, ...userSkills]
 }
 
-/**
- * Get a skill by name from all available sources.
- */
-export function getSkillByName(name: string, options: DiscoverSkillsOptions = {}): LoadedSkill | undefined {
-  const skills = discoverSkills(options)
+export async function getSkillByName(name: string, options: DiscoverSkillsOptions = {}): Promise<LoadedSkill | undefined> {
+  const skills = await discoverSkills(options)
   return skills.find(s => s.name === name)
 }
 
-export function discoverUserClaudeSkills(): LoadedSkill[] {
+export async function discoverUserClaudeSkills(): Promise<LoadedSkill[]> {
   const userSkillsDir = join(getClaudeConfigDir(), "skills")
   return loadSkillsFromDir(userSkillsDir, "user")
 }
 
-export function discoverProjectClaudeSkills(): LoadedSkill[] {
+export async function discoverProjectClaudeSkills(): Promise<LoadedSkill[]> {
   const projectSkillsDir = join(process.cwd(), ".claude", "skills")
   return loadSkillsFromDir(projectSkillsDir, "project")
 }
 
-export function discoverOpencodeGlobalSkills(): LoadedSkill[] {
+export async function discoverOpencodeGlobalSkills(): Promise<LoadedSkill[]> {
   const opencodeSkillsDir = join(homedir(), ".config", "opencode", "skill")
   return loadSkillsFromDir(opencodeSkillsDir, "opencode")
 }
 
-export function discoverOpencodeProjectSkills(): LoadedSkill[] {
+export async function discoverOpencodeProjectSkills(): Promise<LoadedSkill[]> {
   const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
   return loadSkillsFromDir(opencodeProjectDir, "opencode-project")
 }

src/features/opencode-skill-loader/merger.ts

@@ -21,7 +21,7 @@ const SCOPE_PRIORITY: Record<SkillScope, number> = {
 function builtinToLoaded(builtin: BuiltinSkill): LoadedSkill {
   const definition: CommandDefinition = {
     name: builtin.name,
-    description: `(builtin - Skill) ${builtin.description}`,
+    description: `(opencode - Skill) ${builtin.description}`,
     template: builtin.template,
     model: builtin.model,
     agent: builtin.agent,
@@ -37,6 +37,7 @@ function builtinToLoaded(builtin: BuiltinSkill): LoadedSkill {
     compatibility: builtin.compatibility,
     metadata: builtin.metadata as Record<string, string> | undefined,
     allowedTools: builtin.allowedTools,
+    mcpConfig: builtin.mcpConfig,
   }
 }
 

src/features/opencode-skill-loader/types.ts

@@ -1,4 +1,5 @@
 import type { CommandDefinition } from "../claude-code-command-loader/types"
+import type { SkillMcpConfig } from "../skill-mcp-manager/types"
 
 export type SkillScope = "builtin" | "config" | "user" | "project" | "opencode" | "opencode-project"
 
@@ -13,6 +14,13 @@ export interface SkillMetadata {
   compatibility?: string
   metadata?: Record<string, string>
   "allowed-tools"?: string
+  mcp?: SkillMcpConfig
+}
+
+export interface LazyContentLoader {
+  loaded: boolean
+  content?: string
+  load: () => Promise<string>
 }
 
 export interface LoadedSkill {
@@ -25,4 +33,6 @@ export interface LoadedSkill {
   compatibility?: string
   metadata?: Record<string, string>
   allowedTools?: string[]
+  mcpConfig?: SkillMcpConfig
+  lazyContent?: LazyContentLoader
 }

src/features/skill-mcp-manager/env-cleaner.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { createCleanMcpEnvironment, EXCLUDED_ENV_PATTERNS } from "./env-cleaner"
+
+describe("createCleanMcpEnvironment", () => {
+  // Store original env to restore after tests
+  const originalEnv = { ...process.env }
+
+  afterEach(() => {
+    // Restore original environment
+    for (const key of Object.keys(process.env)) {
+      if (!(key in originalEnv)) {
+        delete process.env[key]
+      }
+    }
+    for (const [key, value] of Object.entries(originalEnv)) {
+      process.env[key] = value
+    }
+  })
+
+  describe("NPM_CONFIG_* filtering", () => {
+    it("filters out uppercase NPM_CONFIG_* variables", () => {
+      // #given
+      process.env.NPM_CONFIG_REGISTRY = "https://private.registry.com"
+      process.env.NPM_CONFIG_CACHE = "/some/cache/path"
+      process.env.NPM_CONFIG_PREFIX = "/some/prefix"
+      process.env.PATH = "/usr/bin"
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment()
+
+      // #then
+      expect(cleanEnv.NPM_CONFIG_REGISTRY).toBeUndefined()
+      expect(cleanEnv.NPM_CONFIG_CACHE).toBeUndefined()
+      expect(cleanEnv.NPM_CONFIG_PREFIX).toBeUndefined()
+      expect(cleanEnv.PATH).toBe("/usr/bin")
+    })
+
+    it("filters out lowercase npm_config_* variables", () => {
+      // #given
+      process.env.npm_config_registry = "https://private.registry.com"
+      process.env.npm_config_cache = "/some/cache/path"
+      process.env.npm_config_https_proxy = "http://proxy:8080"
+      process.env.npm_config_proxy = "http://proxy:8080"
+      process.env.HOME = "/home/user"
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment()
+
+      // #then
+      expect(cleanEnv.npm_config_registry).toBeUndefined()
+      expect(cleanEnv.npm_config_cache).toBeUndefined()
+      expect(cleanEnv.npm_config_https_proxy).toBeUndefined()
+      expect(cleanEnv.npm_config_proxy).toBeUndefined()
+      expect(cleanEnv.HOME).toBe("/home/user")
+    })
+  })
+
+  describe("YARN_* filtering", () => {
+    it("filters out YARN_* variables", () => {
+      // #given
+      process.env.YARN_CACHE_FOLDER = "/yarn/cache"
+      process.env.YARN_ENABLE_IMMUTABLE_INSTALLS = "true"
+      process.env.YARN_REGISTRY = "https://yarn.registry.com"
+      process.env.NODE_ENV = "production"
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment()
+
+      // #then
+      expect(cleanEnv.YARN_CACHE_FOLDER).toBeUndefined()
+      expect(cleanEnv.YARN_ENABLE_IMMUTABLE_INSTALLS).toBeUndefined()
+      expect(cleanEnv.YARN_REGISTRY).toBeUndefined()
+      expect(cleanEnv.NODE_ENV).toBe("production")
+    })
+  })
+
+  describe("PNPM_* filtering", () => {
+    it("filters out PNPM_* variables", () => {
+      // #given
+      process.env.PNPM_HOME = "/pnpm/home"
+      process.env.PNPM_STORE_DIR = "/pnpm/store"
+      process.env.USER = "testuser"
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment()
+
+      // #then
+      expect(cleanEnv.PNPM_HOME).toBeUndefined()
+      expect(cleanEnv.PNPM_STORE_DIR).toBeUndefined()
+      expect(cleanEnv.USER).toBe("testuser")
+    })
+  })
+
+  describe("NO_UPDATE_NOTIFIER filtering", () => {
+    it("filters out NO_UPDATE_NOTIFIER variable", () => {
+      // #given
+      process.env.NO_UPDATE_NOTIFIER = "1"
+      process.env.SHELL = "/bin/bash"
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment()
+
+      // #then
+      expect(cleanEnv.NO_UPDATE_NOTIFIER).toBeUndefined()
+      expect(cleanEnv.SHELL).toBe("/bin/bash")
+    })
+  })
+
+  describe("custom environment overlay", () => {
+    it("merges custom env on top of clean process.env", () => {
+      // #given
+      process.env.PATH = "/usr/bin"
+      process.env.NPM_CONFIG_REGISTRY = "https://private.registry.com"
+      const customEnv = {
+        MCP_API_KEY: "secret-key",
+        CUSTOM_VAR: "custom-value",
+      }
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment(customEnv)
+
+      // #then
+      expect(cleanEnv.PATH).toBe("/usr/bin")
+      expect(cleanEnv.NPM_CONFIG_REGISTRY).toBeUndefined()
+      expect(cleanEnv.MCP_API_KEY).toBe("secret-key")
+      expect(cleanEnv.CUSTOM_VAR).toBe("custom-value")
+    })
+
+    it("custom env can override process.env values", () => {
+      // #given
+      process.env.NODE_ENV = "development"
+      const customEnv = {
+        NODE_ENV: "production",
+      }
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment(customEnv)
+
+      // #then
+      expect(cleanEnv.NODE_ENV).toBe("production")
+    })
+  })
+
+  describe("undefined value handling", () => {
+    it("skips undefined values from process.env", () => {
+      // #given - process.env can have undefined values in TypeScript
+      const envWithUndefined = { ...process.env, UNDEFINED_VAR: undefined }
+      Object.assign(process.env, envWithUndefined)
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment()
+
+      // #then - should not throw and should not include undefined values
+      expect(cleanEnv.UNDEFINED_VAR).toBeUndefined()
+      expect(Object.values(cleanEnv).every((v) => v !== undefined)).toBe(true)
+    })
+  })
+
+  describe("mixed case handling", () => {
+    it("filters both uppercase and lowercase npm config variants", () => {
+      // #given - pnpm/yarn can set both cases simultaneously
+      process.env.NPM_CONFIG_CACHE = "/uppercase/cache"
+      process.env.npm_config_cache = "/lowercase/cache"
+      process.env.NPM_CONFIG_REGISTRY = "https://uppercase.registry.com"
+      process.env.npm_config_registry = "https://lowercase.registry.com"
+
+      // #when
+      const cleanEnv = createCleanMcpEnvironment()
+
+      // #then
+      expect(cleanEnv.NPM_CONFIG_CACHE).toBeUndefined()
+      expect(cleanEnv.npm_config_cache).toBeUndefined()
+      expect(cleanEnv.NPM_CONFIG_REGISTRY).toBeUndefined()
+      expect(cleanEnv.npm_config_registry).toBeUndefined()
+    })
+  })
+})
+
+describe("EXCLUDED_ENV_PATTERNS", () => {
+  it("contains patterns for npm, yarn, and pnpm configs", () => {
+    // #given / #when / #then
+    expect(EXCLUDED_ENV_PATTERNS.length).toBeGreaterThanOrEqual(4)
+
+    // Test that patterns match expected strings
+    const testCases = [
+      { pattern: "NPM_CONFIG_REGISTRY", shouldMatch: true },
+      { pattern: "npm_config_registry", shouldMatch: true },
+      { pattern: "YARN_CACHE_FOLDER", shouldMatch: true },
+      { pattern: "PNPM_HOME", shouldMatch: true },
+      { pattern: "NO_UPDATE_NOTIFIER", shouldMatch: true },
+      { pattern: "PATH", shouldMatch: false },
+      { pattern: "HOME", shouldMatch: false },
+      { pattern: "NODE_ENV", shouldMatch: false },
+    ]
+
+    for (const { pattern, shouldMatch } of testCases) {
+      const matches = EXCLUDED_ENV_PATTERNS.some((regex: RegExp) => regex.test(pattern))
+      expect(matches).toBe(shouldMatch)
+    }
+  })
+})

src/features/skill-mcp-manager/env-cleaner.ts

@@ -0,0 +1,27 @@
+// Filters npm/pnpm/yarn config env vars that break MCP servers in pnpm projects (#456)
+export const EXCLUDED_ENV_PATTERNS: RegExp[] = [
+  /^NPM_CONFIG_/i,
+  /^npm_config_/,
+  /^YARN_/,
+  /^PNPM_/,
+  /^NO_UPDATE_NOTIFIER$/,
+]
+
+export function createCleanMcpEnvironment(
+  customEnv: Record<string, string> = {}
+): Record<string, string> {
+  const cleanEnv: Record<string, string> = {}
+
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value === undefined) continue
+
+    const shouldExclude = EXCLUDED_ENV_PATTERNS.some((pattern) => pattern.test(key))
+    if (!shouldExclude) {
+      cleanEnv[key] = value
+    }
+  }
+
+  Object.assign(cleanEnv, customEnv)
+
+  return cleanEnv
+}

src/features/skill-mcp-manager/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export { SkillMcpManager } from "./manager"

src/features/skill-mcp-manager/manager.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeEach, afterEach, mock, spyOn } from "bun:test"
+import { SkillMcpManager } from "./manager"
+import type { SkillMcpClientInfo, SkillMcpServerContext } from "./types"
+import type { ClaudeCodeMcpServer } from "../claude-code-mcp-loader/types"
+
+describe("SkillMcpManager", () => {
+  let manager: SkillMcpManager
+
+  beforeEach(() => {
+    manager = new SkillMcpManager()
+  })
+
+  afterEach(async () => {
+    await manager.disconnectAll()
+  })
+
+  describe("getOrCreateClient", () => {
+    it("throws error when command is missing", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "test-server",
+        skillName: "test-skill",
+        sessionID: "session-1",
+      }
+      const config: ClaudeCodeMcpServer = {}
+
+      // #when / #then
+      await expect(manager.getOrCreateClient(info, config)).rejects.toThrow(
+        /missing required 'command' field/
+      )
+    })
+
+    it("includes helpful error message with example when command is missing", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "my-mcp",
+        skillName: "data-skill",
+        sessionID: "session-1",
+      }
+      const config: ClaudeCodeMcpServer = {}
+
+      // #when / #then
+      await expect(manager.getOrCreateClient(info, config)).rejects.toThrow(
+        /my-mcp[\s\S]*data-skill[\s\S]*Example/
+      )
+    })
+  })
+
+  describe("disconnectSession", () => {
+    it("removes all clients for a specific session", async () => {
+      // #given
+      const session1Info: SkillMcpClientInfo = {
+        serverName: "server1",
+        skillName: "skill1",
+        sessionID: "session-1",
+      }
+      const session2Info: SkillMcpClientInfo = {
+        serverName: "server1",
+        skillName: "skill1",
+        sessionID: "session-2",
+      }
+
+      // #when
+      await manager.disconnectSession("session-1")
+
+      // #then
+      expect(manager.isConnected(session1Info)).toBe(false)
+      expect(manager.isConnected(session2Info)).toBe(false)
+    })
+
+    it("does not throw when session has no clients", async () => {
+      // #given / #when / #then
+      await expect(manager.disconnectSession("nonexistent")).resolves.toBeUndefined()
+    })
+  })
+
+  describe("disconnectAll", () => {
+    it("clears all clients", async () => {
+      // #given - no actual clients connected (would require real MCP server)
+
+      // #when
+      await manager.disconnectAll()
+
+      // #then
+      expect(manager.getConnectedServers()).toEqual([])
+    })
+  })
+
+  describe("isConnected", () => {
+    it("returns false for unconnected server", () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "unknown",
+        skillName: "test",
+        sessionID: "session-1",
+      }
+
+      // #when / #then
+      expect(manager.isConnected(info)).toBe(false)
+    })
+  })
+
+  describe("getConnectedServers", () => {
+    it("returns empty array when no servers connected", () => {
+      // #given / #when / #then
+      expect(manager.getConnectedServers()).toEqual([])
+    })
+  })
+
+  describe("environment variable handling", () => {
+    it("always inherits process.env even when config.env is undefined", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "test-server",
+        skillName: "test-skill",
+        sessionID: "session-1",
+      }
+      const configWithoutEnv: ClaudeCodeMcpServer = {
+        command: "node",
+        args: ["-e", "process.exit(0)"],
+      }
+
+      // #when - attempt connection (will fail but exercises env merging code path)
+      // #then - should not throw "undefined" related errors for env
+      try {
+        await manager.getOrCreateClient(info, configWithoutEnv)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        expect(message).not.toContain("env")
+        expect(message).not.toContain("undefined")
+      }
+    })
+
+    it("overlays config.env on top of inherited process.env", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "test-server",
+        skillName: "test-skill",
+        sessionID: "session-2",
+      }
+      const configWithEnv: ClaudeCodeMcpServer = {
+        command: "node",
+        args: ["-e", "process.exit(0)"],
+        env: {
+          CUSTOM_VAR: "custom_value",
+        },
+      }
+
+      // #when - attempt connection
+      // #then - should not throw, env merging should work
+      try {
+        await manager.getOrCreateClient(info, configWithEnv)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        expect(message).toContain("Failed to connect")
+      }
+    })
+  })
+})

src/features/skill-mcp-manager/manager.ts

@@ -0,0 +1,316 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import type { Tool, Resource, Prompt } from "@modelcontextprotocol/sdk/types.js"
+import type { ClaudeCodeMcpServer } from "../claude-code-mcp-loader/types"
+import { expandEnvVarsInObject } from "../claude-code-mcp-loader/env-expander"
+import { createCleanMcpEnvironment } from "./env-cleaner"
+import type { SkillMcpClientInfo, SkillMcpServerContext } from "./types"
+
+interface ManagedClient {
+  client: Client
+  transport: StdioClientTransport
+  skillName: string
+  lastUsedAt: number
+}
+
+export class SkillMcpManager {
+  private clients: Map<string, ManagedClient> = new Map()
+  private pendingConnections: Map<string, Promise<Client>> = new Map()
+  private cleanupRegistered = false
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null
+  private readonly IDLE_TIMEOUT = 5 * 60 * 1000
+
+  private getClientKey(info: SkillMcpClientInfo): string {
+    return `${info.sessionID}:${info.skillName}:${info.serverName}`
+  }
+
+  private registerProcessCleanup(): void {
+    if (this.cleanupRegistered) return
+    this.cleanupRegistered = true
+
+    const cleanup = async () => {
+      for (const [, managed] of this.clients) {
+        try {
+          await managed.client.close()
+        } catch {
+          // Ignore errors during cleanup
+        }
+        try {
+          await managed.transport.close()
+        } catch {
+          // Transport may already be terminated
+        }
+      }
+      this.clients.clear()
+      this.pendingConnections.clear()
+    }
+
+    // Note: 'exit' event is synchronous-only in Node.js, so we use 'beforeExit' for async cleanup
+    // However, 'beforeExit' is not emitted on explicit process.exit() calls
+    // Signal handlers are made async to properly await cleanup
+
+    process.on("SIGINT", async () => {
+      await cleanup()
+      process.exit(0)
+    })
+    process.on("SIGTERM", async () => {
+      await cleanup()
+      process.exit(0)
+    })
+    if (process.platform === "win32") {
+      process.on("SIGBREAK", async () => {
+        await cleanup()
+        process.exit(0)
+      })
+    }
+  }
+
+  async getOrCreateClient(
+    info: SkillMcpClientInfo,
+    config: ClaudeCodeMcpServer
+  ): Promise<Client> {
+    const key = this.getClientKey(info)
+    const existing = this.clients.get(key)
+
+    if (existing) {
+      existing.lastUsedAt = Date.now()
+      return existing.client
+    }
+
+    // Prevent race condition: if a connection is already in progress, wait for it
+    const pending = this.pendingConnections.get(key)
+    if (pending) {
+      return pending
+    }
+
+    const expandedConfig = expandEnvVarsInObject(config)
+    const connectionPromise = this.createClient(info, expandedConfig)
+    this.pendingConnections.set(key, connectionPromise)
+
+    try {
+      const client = await connectionPromise
+      return client
+    } finally {
+      this.pendingConnections.delete(key)
+    }
+  }
+
+  private async createClient(
+    info: SkillMcpClientInfo,
+    config: ClaudeCodeMcpServer
+  ): Promise<Client> {
+    const key = this.getClientKey(info)
+
+    if (!config.command) {
+      throw new Error(
+        `MCP server "${info.serverName}" is missing required 'command' field.\n\n` +
+        `The MCP configuration in skill "${info.skillName}" must specify a command to execute.\n\n` +
+        `Example:\n` +
+        `  mcp:\n` +
+        `    ${info.serverName}:\n` +
+        `      command: npx\n` +
+        `      args: [-y, @some/mcp-server]`
+      )
+    }
+
+    const command = config.command
+    const args = config.args || []
+
+    const mergedEnv = createCleanMcpEnvironment(config.env)
+
+    this.registerProcessCleanup()
+
+    const transport = new StdioClientTransport({
+      command,
+      args,
+      env: mergedEnv,
+      stderr: "ignore",
+    })
+
+    const client = new Client(
+      { name: `skill-mcp-${info.skillName}-${info.serverName}`, version: "1.0.0" },
+      { capabilities: {} }
+    )
+
+    try {
+      await client.connect(transport)
+    } catch (error) {
+      // Close transport to prevent orphaned MCP process on connection failure
+      try {
+        await transport.close()
+      } catch {
+        // Process may already be terminated
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new Error(
+        `Failed to connect to MCP server "${info.serverName}".\n\n` +
+        `Command: ${command} ${args.join(" ")}\n` +
+        `Reason: ${errorMessage}\n\n` +
+        `Hints:\n` +
+        `  - Ensure the command is installed and available in PATH\n` +
+        `  - Check if the MCP server package exists\n` +
+        `  - Verify the args are correct for this server`
+      )
+    }
+
+    this.clients.set(key, { client, transport, skillName: info.skillName, lastUsedAt: Date.now() })
+    this.startCleanupTimer()
+    return client
+  }
+
+  async disconnectSession(sessionID: string): Promise<void> {
+    const keysToRemove: string[] = []
+
+    for (const [key, managed] of this.clients.entries()) {
+      if (key.startsWith(`${sessionID}:`)) {
+        keysToRemove.push(key)
+        // Delete from map first to prevent re-entrancy during async close
+        this.clients.delete(key)
+        try {
+          await managed.client.close()
+        } catch {
+          // Ignore close errors - process may already be terminated
+        }
+        try {
+          await managed.transport.close()
+        } catch {
+          // Transport may already be terminated
+        }
+      }
+    }
+  }
+
+  async disconnectAll(): Promise<void> {
+    this.stopCleanupTimer()
+    const clients = Array.from(this.clients.values())
+    this.clients.clear()
+    for (const managed of clients) {
+      try {
+        await managed.client.close()
+      } catch { /* process may already be terminated */ }
+      try {
+        await managed.transport.close()
+      } catch { /* transport may already be terminated */ }
+    }
+  }
+
+  private startCleanupTimer(): void {
+    if (this.cleanupInterval) return
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupIdleClients()
+    }, 60_000)
+    this.cleanupInterval.unref()
+  }
+
+  private stopCleanupTimer(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval)
+      this.cleanupInterval = null
+    }
+  }
+
+  private async cleanupIdleClients(): Promise<void> {
+    const now = Date.now()
+    for (const [key, managed] of this.clients) {
+      if (now - managed.lastUsedAt > this.IDLE_TIMEOUT) {
+        this.clients.delete(key)
+        try {
+          await managed.client.close()
+        } catch { /* process may already be terminated */ }
+        try {
+          await managed.transport.close()
+        } catch { /* transport may already be terminated */ }
+      }
+    }
+  }
+
+  async listTools(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext
+  ): Promise<Tool[]> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.listTools()
+    return result.tools
+  }
+
+  async listResources(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext
+  ): Promise<Resource[]> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.listResources()
+    return result.resources
+  }
+
+  async listPrompts(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext
+  ): Promise<Prompt[]> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.listPrompts()
+    return result.prompts
+  }
+
+  async callTool(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext,
+    name: string,
+    args: Record<string, unknown>
+  ): Promise<unknown> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.callTool({ name, arguments: args })
+    return result.content
+  }
+
+  async readResource(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext,
+    uri: string
+  ): Promise<unknown> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.readResource({ uri })
+    return result.contents
+  }
+
+  async getPrompt(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext,
+    name: string,
+    args: Record<string, string>
+  ): Promise<unknown> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.getPrompt({ name, arguments: args })
+    return result.messages
+  }
+
+  private async getOrCreateClientWithRetry(
+    info: SkillMcpClientInfo,
+    config: ClaudeCodeMcpServer
+  ): Promise<Client> {
+    try {
+      return await this.getOrCreateClient(info, config)
+    } catch (error) {
+      const key = this.getClientKey(info)
+      const existing = this.clients.get(key)
+      if (existing) {
+        this.clients.delete(key)
+        try {
+          await existing.client.close()
+        } catch { /* process may already be terminated */ }
+        try {
+          await existing.transport.close()
+        } catch { /* transport may already be terminated */ }
+        return await this.getOrCreateClient(info, config)
+      }
+      throw error
+    }
+  }
+
+  getConnectedServers(): string[] {
+    return Array.from(this.clients.keys())
+  }
+
+  isConnected(info: SkillMcpClientInfo): boolean {
+    return this.clients.has(this.getClientKey(info))
+  }
+}

src/features/skill-mcp-manager/types.ts

@@ -0,0 +1,14 @@
+import type { ClaudeCodeMcpServer } from "../claude-code-mcp-loader/types"
+
+export type SkillMcpConfig = Record<string, ClaudeCodeMcpServer>
+
+export interface SkillMcpClientInfo {
+  serverName: string
+  skillName: string
+  sessionID: string
+}
+
+export interface SkillMcpServerContext {
+  config: ClaudeCodeMcpServer
+  skillName: string
+}

src/hooks/AGENTS.md

@@ -2,83 +2,65 @@
 
 ## OVERVIEW
 
-Lifecycle hooks that intercept/modify agent behavior. Inject context, enforce rules, recover from errors, notify on events.
+22 lifecycle hooks intercepting/modifying agent behavior. Context injection, error recovery, output control, notifications.
 
 ## STRUCTURE
 
 ```
 hooks/
-├── agent-usage-reminder/       # Remind to use specialized agents
-├── anthropic-context-window-limit-recovery/     # Auto-compact Claude at token limit
-├── auto-update-checker/        # Version update notifications
-├── background-notification/    # OS notify on background task complete
-├── claude-code-hooks/          # Claude Code settings.json integration
+├── anthropic-context-window-limit-recovery/  # Auto-compact at token limit (554 lines)
+├── auto-slash-command/         # Detect and execute /command patterns
+├── auto-update-checker/        # Version notifications, startup toast
+├── background-notification/    # OS notify on task complete
+├── claude-code-hooks/          # settings.json PreToolUse/PostToolUse/etc
 ├── comment-checker/            # Prevent excessive AI comments
-│   ├── filters/                # Filtering rules (docstring, directive, bdd, etc.)
-│   └── output/                 # Output formatting
-├── compaction-context-injector/ # Inject context during compaction
-├── directory-agents-injector/  # Auto-inject AGENTS.md files
-├── directory-readme-injector/  # Auto-inject README.md files
+│   └── filters/                # docstring, directive, bdd, etc
+├── compaction-context-injector/ # Preserve context during compaction
+├── directory-agents-injector/  # Auto-inject AGENTS.md
+├── directory-readme-injector/  # Auto-inject README.md
 ├── empty-message-sanitizer/    # Sanitize empty messages
 ├── interactive-bash-session/   # Tmux session management
-├── keyword-detector/           # Detect ultrawork/search keywords
-├── non-interactive-env/        # CI/headless environment handling
-├── preemptive-compaction/      # Pre-emptive session compaction
+├── keyword-detector/           # ultrawork/search keyword activation
+├── non-interactive-env/        # CI/headless handling
+├── preemptive-compaction/      # Pre-emptive at 85% usage
+├── ralph-loop/                 # Self-referential dev loop
 ├── rules-injector/             # Conditional rules from .claude/rules/
-├── session-recovery/           # Recover from session errors
+├── session-recovery/           # Recover from errors (430 lines)
 ├── think-mode/                 # Auto-detect thinking triggers
-├── thinking-block-validator/   # Validate thinking blocks in messages
-├── context-window-monitor.ts   # Monitor context usage (standalone)
-├── empty-task-response-detector.ts
-├── session-notification.ts     # OS notify on idle (standalone)
-├── todo-continuation-enforcer.ts # Force TODO completion (standalone)
-└── tool-output-truncator.ts    # Truncate verbose outputs (standalone)
+├── agent-usage-reminder/       # Remind to use specialists
+├── context-window-monitor.ts   # Monitor usage (standalone)
+├── session-notification.ts     # OS notify on idle
+├── todo-continuation-enforcer.ts # Force TODO completion
+└── tool-output-truncator.ts    # Truncate verbose outputs
 ```
 
-## HOOK CATEGORIES
-
-| Category | Hooks | Purpose |
-|----------|-------|---------|
-| Context Injection | directory-agents-injector, directory-readme-injector, rules-injector, compaction-context-injector | Auto-inject relevant context |
-| Session Management | session-recovery, anthropic-context-window-limit-recovery, preemptive-compaction, empty-message-sanitizer | Handle session lifecycle |
-| Output Control | comment-checker, tool-output-truncator | Control agent output quality |
-| Notifications | session-notification, background-notification, auto-update-checker | OS/user notifications |
-| Behavior Enforcement | todo-continuation-enforcer, keyword-detector, think-mode, agent-usage-reminder | Enforce agent behavior |
-| Environment | non-interactive-env, interactive-bash-session, context-window-monitor | Adapt to runtime environment |
-| Compatibility | claude-code-hooks | Claude Code settings.json support |
-
-## HOW TO ADD A HOOK
-
-1. Create directory: `src/hooks/my-hook/`
-2. Create files:
-   - `index.ts`: Export `createMyHook(input: PluginInput)`
-   - `constants.ts`: Hook name constant
-   - `types.ts`: TypeScript interfaces (optional)
-   - `storage.ts`: Persistent state (optional)
-3. Return event handlers: `{ PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }`
-4. Export from `src/hooks/index.ts`
-5. Register in main plugin
-
 ## HOOK EVENTS
 
 | Event | Timing | Can Block | Use Case |
 |-------|--------|-----------|----------|
-| PreToolUse | Before tool exec | Yes | Validate, modify input |
-| PostToolUse | After tool exec | No | Add context, warnings |
-| UserPromptSubmit | On user prompt | Yes | Inject messages, block |
+| PreToolUse | Before tool | Yes | Validate, modify input |
+| PostToolUse | After tool | No | Add context, warnings |
+| UserPromptSubmit | On prompt | Yes | Inject messages, block |
 | Stop | Session idle | No | Inject follow-ups |
-| onSummarize | During compaction | No | Preserve critical context |
+| onSummarize | Compaction | No | Preserve context |
 
-## COMMON PATTERNS
+## HOW TO ADD
 
-- **Storage**: Use `storage.ts` with JSON file for persistent state across sessions
-- **Once-per-session**: Track injected paths in Set to avoid duplicate injection
-- **Message injection**: Return `{ messages: [...] }` from event handlers
-- **Blocking**: Return `{ blocked: true, message: "reason" }` from PreToolUse
+1. Create `src/hooks/my-hook/`
+2. Files: `index.ts` (createMyHook), `constants.ts`, `types.ts` (optional)
+3. Return: `{ PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }`
+4. Export from `src/hooks/index.ts`
 
-## ANTI-PATTERNS (HOOKS)
+## PATTERNS
 
-- **Heavy computation** in PreToolUse: Slows every tool call
-- **Blocking without clear reason**: Always provide actionable message
-- **Duplicate injection**: Track what's already injected per session
-- **Ignoring errors**: Always try/catch, log failures, don't crash session
+- **Storage**: JSON file for persistent state across sessions
+- **Once-per-session**: Track injected paths in Set
+- **Message injection**: Return `{ messages: [...] }`
+- **Blocking**: Return `{ blocked: true, message: "..." }` from PreToolUse
+
+## ANTI-PATTERNS
+
+- Heavy computation in PreToolUse (slows every tool call)
+- Blocking without actionable message
+- Duplicate injection (track what's injected)
+- Missing try/catch (don't crash session)

src/hooks/agent-usage-reminder/constants.ts

@@ -16,7 +16,6 @@ export const TARGET_TOOLS = new Set([
   "webfetch",
   "context7_resolve-library-id",
   "context7_get-library-docs",
-  "websearch_exa_web_search_exa",
   "grep_app_searchgithub",
 ]);
 

src/hooks/anthropic-context-window-limit-recovery/executor.test.ts

@@ -1,6 +1,7 @@
-import { describe, test, expect, mock, beforeEach } from "bun:test"
+import { describe, test, expect, mock, beforeEach, spyOn } from "bun:test"
 import { executeCompact } from "./executor"
 import type { AutoCompactState } from "./types"
+import * as storage from "./storage"
 
 describe("executeCompact lock management", () => {
   let autoCompactState: AutoCompactState
@@ -15,7 +16,6 @@ describe("executeCompact lock management", () => {
       pendingCompact: new Set<string>(),
       errorDataBySession: new Map(),
       retryStateBySession: new Map(),
-      fallbackStateBySession: new Map(),
       truncateStateBySession: new Map(),
       dcpStateBySession: new Map(),
       emptyContentAttemptBySession: new Map(),
@@ -68,38 +68,6 @@ describe("executeCompact lock management", () => {
     expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
   })
 
-  test("clears lock when revert throws exception", async () => {
-    // #given: Force revert path by exhausting retry attempts and making revert fail
-    mockClient.session.revert = mock(() =>
-      Promise.reject(new Error("Revert failed")),
-    )
-    mockClient.session.messages = mock(() =>
-      Promise.resolve({
-        data: [
-          { info: { id: "msg1", role: "user" } },
-          { info: { id: "msg2", role: "assistant" } },
-        ],
-      }),
-    )
-
-    // Exhaust retry attempts
-    autoCompactState.retryStateBySession.set(sessionID, {
-      attempt: 5,
-      lastAttemptTime: Date.now(),
-    })
-    autoCompactState.errorDataBySession.set(sessionID, {
-      errorType: "token_limit",
-      currentTokens: 100000,
-      maxTokens: 200000,
-    })
-
-    // #when: Execute compaction
-    await executeCompact(sessionID, msg, autoCompactState, mockClient, directory)
-
-    // #then: Lock cleared even though revert failed
-    expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
-  })
-
   test("shows toast when lock already held", async () => {
     // #given: Lock already held
     autoCompactState.compactionInProgress.add(sessionID)
@@ -195,9 +163,6 @@ describe("executeCompact lock management", () => {
       attempt: 5,
       lastAttemptTime: Date.now(),
     })
-    autoCompactState.fallbackStateBySession.set(sessionID, {
-      revertAttempt: 5,
-    })
     autoCompactState.truncateStateBySession.set(sessionID, {
       truncateAttempt: 5,
     })
@@ -260,4 +225,86 @@ describe("executeCompact lock management", () => {
     // The continuation happens in setTimeout, but lock is cleared in finally before that
     expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
   })
+
+  test("falls through to summarize when truncation is insufficient", async () => {
+    // #given: Over token limit with truncation returning insufficient
+    autoCompactState.errorDataBySession.set(sessionID, {
+      errorType: "token_limit",
+      currentTokens: 250000,
+      maxTokens: 200000,
+    })
+
+    const truncateSpy = spyOn(storage, "truncateUntilTargetTokens").mockReturnValue({
+      success: true,
+      sufficient: false,
+      truncatedCount: 3,
+      totalBytesRemoved: 10000,
+      targetBytesToRemove: 50000,
+      truncatedTools: [
+        { toolName: "Grep", originalSize: 5000 },
+        { toolName: "Read", originalSize: 3000 },
+        { toolName: "Bash", originalSize: 2000 },
+      ],
+    })
+
+    // #when: Execute compaction
+    await executeCompact(sessionID, msg, autoCompactState, mockClient, directory)
+
+    // #then: Truncation was attempted
+    expect(truncateSpy).toHaveBeenCalled()
+
+    // #then: Summarize should be called (fall through from insufficient truncation)
+    expect(mockClient.session.summarize).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: { id: sessionID },
+        body: { providerID: "anthropic", modelID: "claude-opus-4-5" },
+      }),
+    )
+
+    // #then: Lock should be cleared
+    expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
+
+    truncateSpy.mockRestore()
+  })
+
+  test("does NOT call summarize when truncation is sufficient", async () => {
+    // #given: Over token limit with truncation returning sufficient
+    autoCompactState.errorDataBySession.set(sessionID, {
+      errorType: "token_limit",
+      currentTokens: 250000,
+      maxTokens: 200000,
+    })
+
+    const truncateSpy = spyOn(storage, "truncateUntilTargetTokens").mockReturnValue({
+      success: true,
+      sufficient: true,
+      truncatedCount: 5,
+      totalBytesRemoved: 60000,
+      targetBytesToRemove: 50000,
+      truncatedTools: [
+        { toolName: "Grep", originalSize: 30000 },
+        { toolName: "Read", originalSize: 30000 },
+      ],
+    })
+
+    // #when: Execute compaction
+    await executeCompact(sessionID, msg, autoCompactState, mockClient, directory)
+
+    // Wait for setTimeout callback
+    await new Promise((resolve) => setTimeout(resolve, 600))
+
+    // #then: Truncation was attempted
+    expect(truncateSpy).toHaveBeenCalled()
+
+    // #then: Summarize should NOT be called (early return from sufficient truncation)
+    expect(mockClient.session.summarize).not.toHaveBeenCalled()
+
+    // #then: prompt_async should be called (Continue after successful truncation)
+    expect(mockClient.session.prompt_async).toHaveBeenCalled()
+
+    // #then: Lock should be cleared
+    expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
+
+    truncateSpy.mockRestore()
+  })
 })

src/hooks/anthropic-context-window-limit-recovery/executor.ts

@@ -1,12 +1,11 @@
 import type {
   AutoCompactState,
   DcpState,
-  FallbackState,
   RetryState,
   TruncateState,
 } from "./types";
 import type { ExperimentalConfig } from "../../config";
-import { FALLBACK_CONFIG, RETRY_CONFIG, TRUNCATE_CONFIG } from "./types";
+import { RETRY_CONFIG, TRUNCATE_CONFIG } from "./types";
 import { executeDynamicContextPruning } from "./pruning-executor";
 import {
   findLargestToolResult,
@@ -40,7 +39,7 @@ type Client = {
       query: { directory: string };
     }) => Promise<unknown>;
     prompt_async: (opts: {
-      path: { sessionID: string };
+      path: { id: string };
       body: { parts: Array<{ type: string; text: string }> };
       query: { directory: string };
     }) => Promise<unknown>;
@@ -69,17 +68,7 @@ function getOrCreateRetryState(
   return state;
 }
 
-function getOrCreateFallbackState(
-  autoCompactState: AutoCompactState,
-  sessionID: string,
-): FallbackState {
-  let state = autoCompactState.fallbackStateBySession.get(sessionID);
-  if (!state) {
-    state = { revertAttempt: 0 };
-    autoCompactState.fallbackStateBySession.set(sessionID, state);
-  }
-  return state;
-}
+
 
 function getOrCreateTruncateState(
   autoCompactState: AutoCompactState,
@@ -135,58 +124,6 @@ function sanitizeEmptyMessagesBeforeSummarize(sessionID: string): number {
   return fixedCount;
 }
 
-async function getLastMessagePair(
-  sessionID: string,
-  client: Client,
-  directory: string,
-): Promise<{ userMessageID: string; assistantMessageID?: string } | null> {
-  try {
-    const resp = await client.session.messages({
-      path: { id: sessionID },
-      query: { directory },
-    });
-
-    const data = (resp as { data?: unknown[] }).data;
-    if (
-      !Array.isArray(data) ||
-      data.length < FALLBACK_CONFIG.minMessagesRequired
-    ) {
-      return null;
-    }
-
-    const reversed = [...data].reverse();
-
-    const lastAssistant = reversed.find((m) => {
-      const msg = m as Record<string, unknown>;
-      const info = msg.info as Record<string, unknown> | undefined;
-      return info?.role === "assistant";
-    });
-
-    const lastUser = reversed.find((m) => {
-      const msg = m as Record<string, unknown>;
-      const info = msg.info as Record<string, unknown> | undefined;
-      return info?.role === "user";
-    });
-
-    if (!lastUser) return null;
-    const userInfo = (lastUser as { info?: Record<string, unknown> }).info;
-    const userMessageID = userInfo?.id as string | undefined;
-    if (!userMessageID) return null;
-
-    let assistantMessageID: string | undefined;
-    if (lastAssistant) {
-      const assistantInfo = (
-        lastAssistant as { info?: Record<string, unknown> }
-      ).info;
-      assistantMessageID = assistantInfo?.id as string | undefined;
-    }
-
-    return { userMessageID, assistantMessageID };
-  } catch {
-    return null;
-  }
-}
-
 function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes}B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
@@ -221,6 +158,8 @@ export async function getLastAssistant(
   }
 }
 
+
+
 function clearSessionState(
   autoCompactState: AutoCompactState,
   sessionID: string,
@@ -228,7 +167,6 @@ function clearSessionState(
   autoCompactState.pendingCompact.delete(sessionID);
   autoCompactState.errorDataBySession.delete(sessionID);
   autoCompactState.retryStateBySession.delete(sessionID);
-  autoCompactState.fallbackStateBySession.delete(sessionID);
   autoCompactState.truncateStateBySession.delete(sessionID);
   autoCompactState.dcpStateBySession.delete(sessionID);
   autoCompactState.emptyContentAttemptBySession.delete(sessionID);
@@ -359,17 +297,16 @@ export async function executeCompact(
     const errorData = autoCompactState.errorDataBySession.get(sessionID);
     const truncateState = getOrCreateTruncateState(autoCompactState, sessionID);
 
-    // DCP FIRST - run before any other recovery attempts when token limit exceeded (controlled by dcp-for-compaction hook)
-    const dcpState = getOrCreateDcpState(autoCompactState, sessionID);
-    if (
-      dcpForCompaction !== false &&
-      !dcpState.attempted &&
+    const isOverLimit =
       errorData?.currentTokens &&
       errorData?.maxTokens &&
-      errorData.currentTokens > errorData.maxTokens
-    ) {
+      errorData.currentTokens > errorData.maxTokens;
+
+    // PHASE 1: DCP (Dynamic Context Pruning) - prune duplicate tool calls first
+    const dcpState = getOrCreateDcpState(autoCompactState, sessionID);
+    if (dcpForCompaction !== false && !dcpState.attempted && isOverLimit) {
       dcpState.attempted = true;
-      log("[auto-compact] DCP triggered FIRST on token limit error", {
+      log("[auto-compact] PHASE 1: DCP triggered on token limit error", {
         sessionID,
         currentTokens: errorData.currentTokens,
         maxTokens: errorData.maxTokens,
@@ -378,19 +315,25 @@ export async function executeCompact(
       const dcpConfig = experimental?.dynamic_context_pruning ?? {
         enabled: true,
         notification: "detailed" as const,
-        protected_tools: ["task", "todowrite", "todoread", "lsp_rename", "lsp_code_action_resolve"],
+        protected_tools: [
+          "task",
+          "todowrite",
+          "todoread",
+          "lsp_rename",
+          "lsp_code_action_resolve",
+        ],
       };
 
       try {
         const pruningResult = await executeDynamicContextPruning(
           sessionID,
           dcpConfig,
-          client
+          client,
         );
 
         if (pruningResult.itemsPruned > 0) {
           dcpState.itemsPruned = pruningResult.itemsPruned;
-          log("[auto-compact] DCP successful, proceeding to compaction", {
+          log("[auto-compact] DCP successful, proceeding to truncation", {
             itemsPruned: pruningResult.itemsPruned,
             tokensSaved: pruningResult.totalTokensSaved,
           });
@@ -399,56 +342,13 @@ export async function executeCompact(
             .showToast({
               body: {
                 title: "Dynamic Context Pruning",
-                message: `Pruned ${pruningResult.itemsPruned} items (~${Math.round(pruningResult.totalTokensSaved / 1000)}k tokens). Running compaction...`,
+                message: `Pruned ${pruningResult.itemsPruned} items (~${Math.round(pruningResult.totalTokensSaved / 1000)}k tokens). Proceeding to truncation...`,
                 variant: "success",
                 duration: 3000,
               },
             })
             .catch(() => {});
-
-          // After DCP, immediately try summarize
-          const providerID = msg.providerID as string | undefined;
-          const modelID = msg.modelID as string | undefined;
-
-          if (providerID && modelID) {
-            try {
-              sanitizeEmptyMessagesBeforeSummarize(sessionID);
-
-              await (client as Client).tui
-                .showToast({
-                  body: {
-                    title: "Auto Compact",
-                    message: "Summarizing session after DCP...",
-                    variant: "warning",
-                    duration: 3000,
-                  },
-                })
-                .catch(() => {});
-
-              await (client as Client).session.summarize({
-                path: { id: sessionID },
-                body: { providerID, modelID },
-                query: { directory },
-              });
-
-              clearSessionState(autoCompactState, sessionID);
-
-              setTimeout(async () => {
-                try {
-                  await (client as Client).session.prompt_async({
-                    path: { sessionID },
-                    body: { parts: [{ type: "text", text: "Continue" }] },
-                    query: { directory },
-                  });
-                } catch {}
-              }, 500);
-              return;
-            } catch (summarizeError) {
-              log("[auto-compact] summarize after DCP failed, continuing recovery", {
-                error: String(summarizeError),
-              });
-            }
-          }
+          // Continue to PHASE 2 (truncation) instead of summarizing immediately
         } else {
           log("[auto-compact] DCP did not prune any items", { sessionID });
         }
@@ -457,14 +357,12 @@ export async function executeCompact(
       }
     }
 
+    // PHASE 2: Aggressive Truncation - always try when over limit (not experimental-only)
     if (
-      experimental?.aggressive_truncation &&
-      errorData?.currentTokens &&
-      errorData?.maxTokens &&
-      errorData.currentTokens > errorData.maxTokens &&
+      isOverLimit &&
       truncateState.truncateAttempt < TRUNCATE_CONFIG.maxTruncateAttempts
     ) {
-      log("[auto-compact] aggressive truncation triggered (experimental)", {
+      log("[auto-compact] PHASE 2: aggressive truncation triggered", {
         currentTokens: errorData.currentTokens,
         maxTokens: errorData.maxTokens,
         targetRatio: TRUNCATE_CONFIG.targetTokenRatio,
@@ -486,16 +384,16 @@ export async function executeCompact(
           .join(", ");
         const statusMsg = aggressiveResult.sufficient
           ? `Truncated ${aggressiveResult.truncatedCount} outputs (${formatBytes(aggressiveResult.totalBytesRemoved)})`
-          : `Truncated ${aggressiveResult.truncatedCount} outputs (${formatBytes(aggressiveResult.totalBytesRemoved)}) but need ${formatBytes(aggressiveResult.targetBytesToRemove)}. Falling back to summarize/revert...`;
+          : `Truncated ${aggressiveResult.truncatedCount} outputs (${formatBytes(aggressiveResult.totalBytesRemoved)}) - continuing to summarize...`;
 
         await (client as Client).tui
           .showToast({
             body: {
               title: aggressiveResult.sufficient
-                ? "Aggressive Truncation"
+                ? "Truncation Complete"
                 : "Partial Truncation",
               message: `${statusMsg}: ${toolNames}`,
-              variant: "warning",
+              variant: aggressiveResult.sufficient ? "success" : "warning",
               duration: 4000,
             },
           })
@@ -503,11 +401,14 @@ export async function executeCompact(
 
         log("[auto-compact] aggressive truncation completed", aggressiveResult);
 
+        // Only return early if truncation was sufficient to get under token limit
+        // Otherwise fall through to PHASE 3 (Summarize)
         if (aggressiveResult.sufficient) {
+          clearSessionState(autoCompactState, sessionID);
           setTimeout(async () => {
             try {
               await (client as Client).session.prompt_async({
-                path: { sessionID },
+                path: { id: sessionID },
                 body: { parts: [{ type: "text", text: "Continue" }] },
                 query: { directory },
               });
@@ -515,87 +416,16 @@ export async function executeCompact(
           }, 500);
           return;
         }
-      } else {
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Truncation Skipped",
-              message: "No tool outputs found to truncate.",
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
-      }
-    }
-
-    let skipSummarize = false;
-
-    if (truncateState.truncateAttempt < TRUNCATE_CONFIG.maxTruncateAttempts) {
-      const largest = findLargestToolResult(sessionID);
-
-      if (
-        largest &&
-        largest.outputSize >= TRUNCATE_CONFIG.minOutputSizeToTruncate
-      ) {
-        const result = truncateToolResult(largest.partPath);
-
-        if (result.success) {
-          truncateState.truncateAttempt++;
-          truncateState.lastTruncatedPartId = largest.partId;
-
-          await (client as Client).tui
-            .showToast({
-              body: {
-                title: "Truncating Large Output",
-                message: `Truncated ${result.toolName} (${formatBytes(result.originalSize ?? 0)}). Retrying...`,
-                variant: "warning",
-                duration: 3000,
-              },
-            })
-            .catch(() => {});
-
-          setTimeout(async () => {
-            try {
-              await (client as Client).session.prompt_async({
-                path: { sessionID },
-                body: { parts: [{ type: "text", text: "Continue" }] },
-                query: { directory },
-              });
-            } catch {}
-          }, 500);
-          return;
-        }
-      } else if (
-        errorData?.currentTokens &&
-        errorData?.maxTokens &&
-        errorData.currentTokens > errorData.maxTokens
-      ) {
-        skipSummarize = true;
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Summarize Skipped",
-              message: `Over token limit (${errorData.currentTokens}/${errorData.maxTokens}) with nothing to truncate. Going to revert...`,
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
-      } else if (!errorData?.currentTokens) {
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Truncation Skipped",
-              message: "No large tool outputs found.",
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
+        // Truncation was insufficient - fall through to Summarize
+        log("[auto-compact] truncation insufficient, falling through to summarize", {
+          sessionID,
+          truncatedCount: aggressiveResult.truncatedCount,
+          sufficient: aggressiveResult.sufficient,
+        });
       }
     }
 
+    // PHASE 3: Summarize - fallback when truncation insufficient or no tool outputs
     const retryState = getOrCreateRetryState(autoCompactState, sessionID);
 
     if (errorData?.errorType?.includes("non-empty content")) {
@@ -642,11 +472,10 @@ export async function executeCompact(
 
     if (Date.now() - retryState.lastAttemptTime > 300000) {
       retryState.attempt = 0;
-      autoCompactState.fallbackStateBySession.delete(sessionID);
       autoCompactState.truncateStateBySession.delete(sessionID);
     }
 
-    if (!skipSummarize && retryState.attempt < RETRY_CONFIG.maxAttempts) {
+    if (retryState.attempt < RETRY_CONFIG.maxAttempts) {
       retryState.attempt++;
       retryState.lastAttemptTime = Date.now();
 
@@ -677,7 +506,7 @@ export async function executeCompact(
           setTimeout(async () => {
             try {
               await (client as Client).session.prompt_async({
-                path: { sessionID },
+                path: { id: sessionID },
                 body: { parts: [{ type: "text", text: "Continue" }] },
                 query: { directory },
               });
@@ -708,75 +537,7 @@ export async function executeCompact(
           .showToast({
             body: {
               title: "Summarize Skipped",
-              message: "Missing providerID or modelID. Skipping to revert...",
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
-      }
-    }
-
-    const fallbackState = getOrCreateFallbackState(autoCompactState, sessionID);
-
-    if (fallbackState.revertAttempt < FALLBACK_CONFIG.maxRevertAttempts) {
-      const pair = await getLastMessagePair(
-        sessionID,
-        client as Client,
-        directory,
-      );
-
-      if (pair) {
-        try {
-          await (client as Client).tui
-            .showToast({
-              body: {
-                title: "Emergency Recovery",
-                message: "Removing last message pair...",
-                variant: "warning",
-                duration: 3000,
-              },
-            })
-            .catch(() => {});
-
-          if (pair.assistantMessageID) {
-            await (client as Client).session.revert({
-              path: { id: sessionID },
-              body: { messageID: pair.assistantMessageID },
-              query: { directory },
-            });
-          }
-
-          await (client as Client).session.revert({
-            path: { id: sessionID },
-            body: { messageID: pair.userMessageID },
-            query: { directory },
-          });
-
-          fallbackState.revertAttempt++;
-          fallbackState.lastRevertedMessageID = pair.userMessageID;
-
-          // Clear all state after successful revert - don't recurse
-          clearSessionState(autoCompactState, sessionID);
-
-          // Send "Continue" prompt to resume session
-          setTimeout(async () => {
-            try {
-              await (client as Client).session.prompt_async({
-                path: { sessionID },
-                body: { parts: [{ type: "text", text: "Continue" }] },
-                query: { directory },
-              });
-            } catch {}
-          }, 500);
-          return;
-        } catch {}
-      } else {
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Revert Skipped",
-              message: "Could not find last message pair to revert.",
+              message: "Missing providerID or modelID.",
               variant: "warning",
               duration: 3000,
             },

src/hooks/anthropic-context-window-limit-recovery/index.ts

@@ -15,7 +15,6 @@ function createRecoveryState(): AutoCompactState {
     pendingCompact: new Set<string>(),
     errorDataBySession: new Map<string, ParsedTokenLimitError>(),
     retryStateBySession: new Map(),
-    fallbackStateBySession: new Map(),
     truncateStateBySession: new Map(),
     dcpStateBySession: new Map(),
     emptyContentAttemptBySession: new Map(),
@@ -37,7 +36,6 @@ export function createAnthropicContextWindowLimitRecoveryHook(ctx: PluginInput,
         autoCompactState.pendingCompact.delete(sessionInfo.id)
         autoCompactState.errorDataBySession.delete(sessionInfo.id)
         autoCompactState.retryStateBySession.delete(sessionInfo.id)
-        autoCompactState.fallbackStateBySession.delete(sessionInfo.id)
         autoCompactState.truncateStateBySession.delete(sessionInfo.id)
         autoCompactState.dcpStateBySession.delete(sessionInfo.id)
         autoCompactState.emptyContentAttemptBySession.delete(sessionInfo.id)
@@ -154,6 +152,6 @@ export function createAnthropicContextWindowLimitRecoveryHook(ctx: PluginInput,
   }
 }
 
-export type { AutoCompactState, DcpState, FallbackState, ParsedTokenLimitError, TruncateState } from "./types"
+export type { AutoCompactState, DcpState, ParsedTokenLimitError, TruncateState } from "./types"
 export { parseAnthropicTokenLimitError } from "./parser"
 export { executeCompact, getLastAssistant } from "./executor"

src/hooks/anthropic-context-window-limit-recovery/parser.ts

@@ -26,9 +26,23 @@ const TOKEN_LIMIT_KEYWORDS = [
   "context length",
   "too many tokens",
   "non-empty content",
-  "invalid_request_error",
 ]
 
+// Patterns that indicate thinking block structure errors (NOT token limit errors)
+// These should be handled by session-recovery hook, not compaction
+const THINKING_BLOCK_ERROR_PATTERNS = [
+  /thinking.*first block/i,
+  /first block.*thinking/i,
+  /must.*start.*thinking/i,
+  /thinking.*redacted_thinking/i,
+  /expected.*thinking.*found/i,
+  /thinking.*disabled.*cannot.*contain/i,
+]
+
+function isThinkingBlockError(text: string): boolean {
+  return THINKING_BLOCK_ERROR_PATTERNS.some((pattern) => pattern.test(text))
+}
+
 const MESSAGE_INDEX_PATTERN = /messages\.(\d+)/
 
 function extractTokensFromMessage(message: string): { current: number; max: number } | null {
@@ -52,6 +66,9 @@ function extractMessageIndex(text: string): number | undefined {
 }
 
 function isTokenLimitError(text: string): boolean {
+  if (isThinkingBlockError(text)) {
+    return false
+  }
   const lower = text.toLowerCase()
   return TOKEN_LIMIT_KEYWORDS.some((kw) => lower.includes(kw.toLowerCase()))
 }

src/hooks/anthropic-context-window-limit-recovery/storage.test.ts

@@ -0,0 +1,77 @@
+import { describe, test, expect, mock, beforeEach } from "bun:test"
+import { truncateUntilTargetTokens } from "./storage"
+import * as storage from "./storage"
+
+// Mock the entire module
+mock.module("./storage", () => {
+  return {
+    ...storage,
+    findToolResultsBySize: mock(() => []),
+    truncateToolResult: mock(() => ({ success: false })),
+  }
+})
+
+describe("truncateUntilTargetTokens", () => {
+  const sessionID = "test-session"
+  
+  beforeEach(() => {
+    // Reset mocks
+    const { findToolResultsBySize, truncateToolResult } = require("./storage")
+    findToolResultsBySize.mockReset()
+    truncateToolResult.mockReset()
+  })
+
+  test("truncates only until target is reached", () => {
+    const { findToolResultsBySize, truncateToolResult } = require("./storage")
+    
+    // #given: Two tool results, each 1000 chars. Target reduction is 500 chars.
+    const results = [
+      { partPath: "path1", partId: "id1", messageID: "m1", toolName: "tool1", outputSize: 1000 },
+      { partPath: "path2", partId: "id2", messageID: "m2", toolName: "tool2", outputSize: 1000 },
+    ]
+    
+    findToolResultsBySize.mockReturnValue(results)
+    truncateToolResult.mockImplementation((path: string) => ({
+      success: true,
+      toolName: path === "path1" ? "tool1" : "tool2",
+      originalSize: 1000
+    }))
+
+    // #when: currentTokens=1000, maxTokens=1000, targetRatio=0.5 (target=500, reduce=500)
+    // charsPerToken=1 for simplicity in test
+    const result = truncateUntilTargetTokens(sessionID, 1000, 1000, 0.5, 1)
+
+    // #then: Should only truncate the first tool
+    expect(result.truncatedCount).toBe(1)
+    expect(truncateToolResult).toHaveBeenCalledTimes(1)
+    expect(truncateToolResult).toHaveBeenCalledWith("path1")
+    expect(result.totalBytesRemoved).toBe(1000)
+    expect(result.sufficient).toBe(true)
+  })
+
+  test("truncates all if target not reached", () => {
+    const { findToolResultsBySize, truncateToolResult } = require("./storage")
+    
+    // #given: Two tool results, each 100 chars. Target reduction is 500 chars.
+    const results = [
+      { partPath: "path1", partId: "id1", messageID: "m1", toolName: "tool1", outputSize: 100 },
+      { partPath: "path2", partId: "id2", messageID: "m2", toolName: "tool2", outputSize: 100 },
+    ]
+    
+    findToolResultsBySize.mockReturnValue(results)
+    truncateToolResult.mockImplementation((path: string) => ({
+      success: true,
+      toolName: path === "path1" ? "tool1" : "tool2",
+      originalSize: 100
+    }))
+
+    // #when: reduce 500 chars
+    const result = truncateUntilTargetTokens(sessionID, 1000, 1000, 0.5, 1)
+
+    // #then: Should truncate both
+    expect(result.truncatedCount).toBe(2)
+    expect(truncateToolResult).toHaveBeenCalledTimes(2)
+    expect(result.totalBytesRemoved).toBe(200)
+    expect(result.sufficient).toBe(false)
+  })
+})

src/hooks/anthropic-context-window-limit-recovery/storage.ts

@@ -230,6 +230,10 @@ export function truncateUntilTargetTokens(
         toolName: truncateResult.toolName ?? result.toolName,
         originalSize: removedSize,
       })
+      
+      if (totalRemoved >= charsToReduce) {
+        break
+      }
     }
   }
 

src/hooks/anthropic-context-window-limit-recovery/types.ts

@@ -13,11 +13,6 @@ export interface RetryState {
   lastAttemptTime: number
 }
 
-export interface FallbackState {
-  revertAttempt: number
-  lastRevertedMessageID?: string
-}
-
 export interface TruncateState {
   truncateAttempt: number
   lastTruncatedPartId?: string
@@ -32,7 +27,6 @@ export interface AutoCompactState {
   pendingCompact: Set<string>
   errorDataBySession: Map<string, ParsedTokenLimitError>
   retryStateBySession: Map<string, RetryState>
-  fallbackStateBySession: Map<string, FallbackState>
   truncateStateBySession: Map<string, TruncateState>
   dcpStateBySession: Map<string, DcpState>
   emptyContentAttemptBySession: Map<string, number>
@@ -46,11 +40,6 @@ export const RETRY_CONFIG = {
   maxDelayMs: 30000,
 } as const
 
-export const FALLBACK_CONFIG = {
-  maxRevertAttempts: 3,
-  minMessagesRequired: 2,
-} as const
-
 export const TRUNCATE_CONFIG = {
   maxTruncateAttempts: 20,
   minOutputSizeToTruncate: 500,

src/hooks/auto-slash-command/constants.ts

@@ -0,0 +1,11 @@
+export const HOOK_NAME = "auto-slash-command" as const
+
+export const AUTO_SLASH_COMMAND_TAG_OPEN = "<auto-slash-command>"
+export const AUTO_SLASH_COMMAND_TAG_CLOSE = "</auto-slash-command>"
+
+export const SLASH_COMMAND_PATTERN = /^\/([a-zA-Z][\w-]*)\s*(.*)/
+
+export const EXCLUDED_COMMANDS = new Set([
+  "ralph-loop",
+  "cancel-ralph",
+])

src/hooks/auto-slash-command/detector.test.ts

@@ -0,0 +1,296 @@
+import { describe, expect, it } from "bun:test"
+import {
+  parseSlashCommand,
+  detectSlashCommand,
+  isExcludedCommand,
+  removeCodeBlocks,
+  extractPromptText,
+} from "./detector"
+
+describe("auto-slash-command detector", () => {
+  describe("removeCodeBlocks", () => {
+    it("should remove markdown code blocks", () => {
+      // #given text with code blocks
+      const text = "Hello ```code here``` world"
+
+      // #when removing code blocks
+      const result = removeCodeBlocks(text)
+
+      // #then code blocks should be removed
+      expect(result).toBe("Hello  world")
+    })
+
+    it("should remove multiline code blocks", () => {
+      // #given text with multiline code blocks
+      const text = `Before
+\`\`\`javascript
+/command-inside-code
+\`\`\`
+After`
+
+      // #when removing code blocks
+      const result = removeCodeBlocks(text)
+
+      // #then code blocks should be removed
+      expect(result).toContain("Before")
+      expect(result).toContain("After")
+      expect(result).not.toContain("/command-inside-code")
+    })
+
+    it("should handle text without code blocks", () => {
+      // #given text without code blocks
+      const text = "Just regular text"
+
+      // #when removing code blocks
+      const result = removeCodeBlocks(text)
+
+      // #then text should remain unchanged
+      expect(result).toBe("Just regular text")
+    })
+  })
+
+  describe("parseSlashCommand", () => {
+    it("should parse simple command without args", () => {
+      // #given a simple slash command
+      const text = "/commit"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should extract command correctly
+      expect(result).not.toBeNull()
+      expect(result?.command).toBe("commit")
+      expect(result?.args).toBe("")
+    })
+
+    it("should parse command with arguments", () => {
+      // #given a slash command with arguments
+      const text = "/plan create a new feature for auth"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should extract command and args
+      expect(result).not.toBeNull()
+      expect(result?.command).toBe("plan")
+      expect(result?.args).toBe("create a new feature for auth")
+    })
+
+    it("should parse command with quoted arguments", () => {
+      // #given a slash command with quoted arguments
+      const text = '/execute "build the API"'
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should extract command and args
+      expect(result).not.toBeNull()
+      expect(result?.command).toBe("execute")
+      expect(result?.args).toBe('"build the API"')
+    })
+
+    it("should parse command with hyphen in name", () => {
+      // #given a slash command with hyphen
+      const text = "/frontend-template-creator project"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should extract full command name
+      expect(result).not.toBeNull()
+      expect(result?.command).toBe("frontend-template-creator")
+      expect(result?.args).toBe("project")
+    })
+
+    it("should return null for non-slash text", () => {
+      // #given text without slash
+      const text = "regular text"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should return null
+      expect(result).toBeNull()
+    })
+
+    it("should return null for slash not at start", () => {
+      // #given text with slash in middle
+      const text = "some text /command"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should return null (slash not at start)
+      expect(result).toBeNull()
+    })
+
+    it("should return null for just a slash", () => {
+      // #given just a slash
+      const text = "/"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should return null
+      expect(result).toBeNull()
+    })
+
+    it("should return null for slash followed by number", () => {
+      // #given slash followed by number
+      const text = "/123"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should return null (command must start with letter)
+      expect(result).toBeNull()
+    })
+
+    it("should handle whitespace before slash", () => {
+      // #given command with leading whitespace
+      const text = "  /commit"
+
+      // #when parsing
+      const result = parseSlashCommand(text)
+
+      // #then should parse after trimming
+      expect(result).not.toBeNull()
+      expect(result?.command).toBe("commit")
+    })
+  })
+
+  describe("isExcludedCommand", () => {
+    it("should exclude ralph-loop", () => {
+      // #given ralph-loop command
+      // #when checking exclusion
+      // #then should be excluded
+      expect(isExcludedCommand("ralph-loop")).toBe(true)
+    })
+
+    it("should exclude cancel-ralph", () => {
+      // #given cancel-ralph command
+      // #when checking exclusion
+      // #then should be excluded
+      expect(isExcludedCommand("cancel-ralph")).toBe(true)
+    })
+
+    it("should be case-insensitive for exclusion", () => {
+      // #given uppercase variants
+      // #when checking exclusion
+      // #then should still be excluded
+      expect(isExcludedCommand("RALPH-LOOP")).toBe(true)
+      expect(isExcludedCommand("Cancel-Ralph")).toBe(true)
+    })
+
+    it("should not exclude regular commands", () => {
+      // #given regular commands
+      // #when checking exclusion
+      // #then should not be excluded
+      expect(isExcludedCommand("commit")).toBe(false)
+      expect(isExcludedCommand("plan")).toBe(false)
+      expect(isExcludedCommand("execute")).toBe(false)
+    })
+  })
+
+  describe("detectSlashCommand", () => {
+    it("should detect slash command in plain text", () => {
+      // #given plain text with slash command
+      const text = "/commit fix typo"
+
+      // #when detecting
+      const result = detectSlashCommand(text)
+
+      // #then should detect
+      expect(result).not.toBeNull()
+      expect(result?.command).toBe("commit")
+      expect(result?.args).toBe("fix typo")
+    })
+
+    it("should NOT detect slash command inside code block", () => {
+      // #given slash command inside code block
+      const text = "```bash\n/command\n```"
+
+      // #when detecting
+      const result = detectSlashCommand(text)
+
+      // #then should not detect (only code block content)
+      expect(result).toBeNull()
+    })
+
+    it("should detect command when text has code blocks elsewhere", () => {
+      // #given slash command before code block
+      const text = "/commit fix\n```code```"
+
+      // #when detecting
+      const result = detectSlashCommand(text)
+
+      // #then should detect the command
+      expect(result).not.toBeNull()
+      expect(result?.command).toBe("commit")
+    })
+
+    it("should NOT detect excluded commands", () => {
+      // #given excluded command
+      const text = "/ralph-loop do something"
+
+      // #when detecting
+      const result = detectSlashCommand(text)
+
+      // #then should not detect
+      expect(result).toBeNull()
+    })
+
+    it("should return null for non-command text", () => {
+      // #given regular text
+      const text = "Just some regular text"
+
+      // #when detecting
+      const result = detectSlashCommand(text)
+
+      // #then should return null
+      expect(result).toBeNull()
+    })
+  })
+
+  describe("extractPromptText", () => {
+    it("should extract text from parts", () => {
+      // #given message parts
+      const parts = [
+        { type: "text", text: "Hello " },
+        { type: "tool_use", id: "123" },
+        { type: "text", text: "world" },
+      ]
+
+      // #when extracting
+      const result = extractPromptText(parts)
+
+      // #then should join text parts
+      expect(result).toBe("Hello  world")
+    })
+
+    it("should handle empty parts", () => {
+      // #given empty parts
+      const parts: Array<{ type: string; text?: string }> = []
+
+      // #when extracting
+      const result = extractPromptText(parts)
+
+      // #then should return empty string
+      expect(result).toBe("")
+    })
+
+    it("should handle parts without text", () => {
+      // #given parts without text content
+      const parts = [
+        { type: "tool_use", id: "123" },
+        { type: "tool_result", output: "result" },
+      ]
+
+      // #when extracting
+      const result = extractPromptText(parts)
+
+      // #then should return empty string
+      expect(result).toBe("")
+    })
+  })
+})

src/hooks/auto-slash-command/detector.ts

@@ -0,0 +1,65 @@
+import {
+  SLASH_COMMAND_PATTERN,
+  EXCLUDED_COMMANDS,
+} from "./constants"
+import type { ParsedSlashCommand } from "./types"
+
+const CODE_BLOCK_PATTERN = /```[\s\S]*?```/g
+
+export function removeCodeBlocks(text: string): string {
+  return text.replace(CODE_BLOCK_PATTERN, "")
+}
+
+export function parseSlashCommand(text: string): ParsedSlashCommand | null {
+  const trimmed = text.trim()
+
+  if (!trimmed.startsWith("/")) {
+    return null
+  }
+
+  const match = trimmed.match(SLASH_COMMAND_PATTERN)
+  if (!match) {
+    return null
+  }
+
+  const [raw, command, args] = match
+  return {
+    command: command.toLowerCase(),
+    args: args.trim(),
+    raw,
+  }
+}
+
+export function isExcludedCommand(command: string): boolean {
+  return EXCLUDED_COMMANDS.has(command.toLowerCase())
+}
+
+export function detectSlashCommand(text: string): ParsedSlashCommand | null {
+  const textWithoutCodeBlocks = removeCodeBlocks(text)
+  const trimmed = textWithoutCodeBlocks.trim()
+
+  if (!trimmed.startsWith("/")) {
+    return null
+  }
+
+  const parsed = parseSlashCommand(trimmed)
+
+  if (!parsed) {
+    return null
+  }
+
+  if (isExcludedCommand(parsed.command)) {
+    return null
+  }
+
+  return parsed
+}
+
+export function extractPromptText(
+  parts: Array<{ type: string; text?: string }>
+): string {
+  return parts
+    .filter((p) => p.type === "text")
+    .map((p) => p.text || "")
+    .join(" ")
+}

src/hooks/auto-slash-command/executor.ts

@@ -0,0 +1,194 @@
+import { existsSync, readdirSync, readFileSync } from "fs"
+import { join, basename, dirname } from "path"
+import { homedir } from "os"
+import {
+  parseFrontmatter,
+  resolveCommandsInText,
+  resolveFileReferencesInText,
+  sanitizeModelField,
+  getClaudeConfigDir,
+} from "../../shared"
+import type { CommandFrontmatter } from "../../features/claude-code-command-loader/types"
+import { isMarkdownFile } from "../../shared/file-utils"
+import { discoverAllSkills, type LoadedSkill } from "../../features/opencode-skill-loader"
+import type { ParsedSlashCommand } from "./types"
+
+interface CommandScope {
+  type: "user" | "project" | "opencode" | "opencode-project" | "skill"
+}
+
+interface CommandMetadata {
+  name: string
+  description: string
+  argumentHint?: string
+  model?: string
+  agent?: string
+  subtask?: boolean
+}
+
+interface CommandInfo {
+  name: string
+  path?: string
+  metadata: CommandMetadata
+  content?: string
+  scope: CommandScope["type"]
+}
+
+function discoverCommandsFromDir(commandsDir: string, scope: CommandScope["type"]): CommandInfo[] {
+  if (!existsSync(commandsDir)) {
+    return []
+  }
+
+  const entries = readdirSync(commandsDir, { withFileTypes: true })
+  const commands: CommandInfo[] = []
+
+  for (const entry of entries) {
+    if (!isMarkdownFile(entry)) continue
+
+    const commandPath = join(commandsDir, entry.name)
+    const commandName = basename(entry.name, ".md")
+
+    try {
+      const content = readFileSync(commandPath, "utf-8")
+      const { data, body } = parseFrontmatter<CommandFrontmatter>(content)
+
+      const isOpencodeSource = scope === "opencode" || scope === "opencode-project"
+      const metadata: CommandMetadata = {
+        name: commandName,
+        description: data.description || "",
+        argumentHint: data["argument-hint"],
+        model: sanitizeModelField(data.model, isOpencodeSource ? "opencode" : "claude-code"),
+        agent: data.agent,
+        subtask: Boolean(data.subtask),
+      }
+
+      commands.push({
+        name: commandName,
+        path: commandPath,
+        metadata,
+        content: body,
+        scope,
+      })
+    } catch {
+      continue
+    }
+  }
+
+  return commands
+}
+
+function skillToCommandInfo(skill: LoadedSkill): CommandInfo {
+  return {
+    name: skill.name,
+    path: skill.path,
+    metadata: {
+      name: skill.name,
+      description: skill.definition.description || "",
+      argumentHint: skill.definition.argumentHint,
+      model: skill.definition.model,
+      agent: skill.definition.agent,
+      subtask: skill.definition.subtask,
+    },
+    content: skill.definition.template,
+    scope: "skill",
+  }
+}
+
+async function discoverAllCommands(): Promise<CommandInfo[]> {
+  const userCommandsDir = join(getClaudeConfigDir(), "commands")
+  const projectCommandsDir = join(process.cwd(), ".claude", "commands")
+  const opencodeGlobalDir = join(homedir(), ".config", "opencode", "command")
+  const opencodeProjectDir = join(process.cwd(), ".opencode", "command")
+
+  const userCommands = discoverCommandsFromDir(userCommandsDir, "user")
+  const opencodeGlobalCommands = discoverCommandsFromDir(opencodeGlobalDir, "opencode")
+  const projectCommands = discoverCommandsFromDir(projectCommandsDir, "project")
+  const opencodeProjectCommands = discoverCommandsFromDir(opencodeProjectDir, "opencode-project")
+
+  const skills = await discoverAllSkills()
+  const skillCommands = skills.map(skillToCommandInfo)
+
+  return [
+    ...opencodeProjectCommands,
+    ...projectCommands,
+    ...opencodeGlobalCommands,
+    ...userCommands,
+    ...skillCommands,
+  ]
+}
+
+async function findCommand(commandName: string): Promise<CommandInfo | null> {
+  const allCommands = await discoverAllCommands()
+  return allCommands.find(
+    (cmd) => cmd.name.toLowerCase() === commandName.toLowerCase()
+  ) ?? null
+}
+
+async function formatCommandTemplate(cmd: CommandInfo, args: string): Promise<string> {
+  const sections: string[] = []
+
+  sections.push(`# /${cmd.name} Command\n`)
+
+  if (cmd.metadata.description) {
+    sections.push(`**Description**: ${cmd.metadata.description}\n`)
+  }
+
+  if (args) {
+    sections.push(`**User Arguments**: ${args}\n`)
+  }
+
+  if (cmd.metadata.model) {
+    sections.push(`**Model**: ${cmd.metadata.model}\n`)
+  }
+
+  if (cmd.metadata.agent) {
+    sections.push(`**Agent**: ${cmd.metadata.agent}\n`)
+  }
+
+  sections.push(`**Scope**: ${cmd.scope}\n`)
+  sections.push("---\n")
+  sections.push("## Command Instructions\n")
+
+  const commandDir = cmd.path ? dirname(cmd.path) : process.cwd()
+  const withFileRefs = await resolveFileReferencesInText(cmd.content || "", commandDir)
+  const resolvedContent = await resolveCommandsInText(withFileRefs)
+  sections.push(resolvedContent.trim())
+
+  if (args) {
+    sections.push("\n\n---\n")
+    sections.push("## User Request\n")
+    sections.push(args)
+  }
+
+  return sections.join("\n")
+}
+
+export interface ExecuteResult {
+  success: boolean
+  replacementText?: string
+  error?: string
+}
+
+export async function executeSlashCommand(parsed: ParsedSlashCommand): Promise<ExecuteResult> {
+  const command = await findCommand(parsed.command)
+
+  if (!command) {
+    return {
+      success: false,
+      error: `Command "/${parsed.command}" not found. Use the slashcommand tool to list available commands.`,
+    }
+  }
+
+  try {
+    const template = await formatCommandTemplate(command, parsed.args)
+    return {
+      success: true,
+      replacementText: template,
+    }
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to load command "/${parsed.command}": ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}

src/hooks/auto-slash-command/index.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it, beforeEach, mock, spyOn } from "bun:test"
+import type {
+  AutoSlashCommandHookInput,
+  AutoSlashCommandHookOutput,
+} from "./types"
+
+// Import real shared module to avoid mock leaking to other test files
+import * as shared from "../../shared"
+
+// Spy on log instead of mocking the entire module
+const logMock = spyOn(shared, "log").mockImplementation(() => {})
+
+
+
+const { createAutoSlashCommandHook } = await import("./index")
+
+function createMockInput(sessionID: string, messageID?: string): AutoSlashCommandHookInput {
+  return {
+    sessionID,
+    messageID: messageID ?? `msg-${Date.now()}-${Math.random()}`,
+    agent: "test-agent",
+    model: { providerID: "anthropic", modelID: "claude-sonnet-4-5" },
+  }
+}
+
+function createMockOutput(text: string): AutoSlashCommandHookOutput {
+  return {
+    message: {
+      agent: "test-agent",
+      model: { providerID: "anthropic", modelID: "claude-sonnet-4-5" },
+      path: { cwd: "/test", root: "/test" },
+      tools: {},
+    },
+    parts: [{ type: "text", text }],
+  }
+}
+
+describe("createAutoSlashCommandHook", () => {
+  beforeEach(() => {
+    logMock.mockClear()
+  })
+
+  describe("slash command replacement", () => {
+    it("should replace message with error when command not found", async () => {
+      // #given a slash command that doesn't exist
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-notfound-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("/nonexistent-command args")
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should replace with error message
+      const textPart = output.parts.find((p) => p.type === "text")
+      expect(textPart?.text).toContain("<auto-slash-command>")
+      expect(textPart?.text).toContain("not found")
+    })
+
+    it("should wrap replacement in auto-slash-command tags", async () => {
+      // #given any slash command
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-tags-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("/some-command")
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should wrap in tags
+      const textPart = output.parts.find((p) => p.type === "text")
+      expect(textPart?.text).toContain("<auto-slash-command>")
+      expect(textPart?.text).toContain("</auto-slash-command>")
+    })
+
+    it("should completely replace original message text", async () => {
+      // #given slash command
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-replace-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("/test-cmd some args")
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then original text should be replaced, not prepended
+      const textPart = output.parts.find((p) => p.type === "text")
+      expect(textPart?.text).not.toContain("/test-cmd some args\n<auto-slash-command>")
+      expect(textPart?.text?.startsWith("<auto-slash-command>")).toBe(true)
+    })
+  })
+
+  describe("no slash command", () => {
+    it("should do nothing for regular text", async () => {
+      // #given regular text without slash
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-regular-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("Just regular text")
+      const originalText = output.parts[0].text
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should not modify
+      expect(output.parts[0].text).toBe(originalText)
+    })
+
+    it("should do nothing for slash in middle of text", async () => {
+      // #given slash in middle
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-middle-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("Please run /commit later")
+      const originalText = output.parts[0].text
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should not detect (not at start)
+      expect(output.parts[0].text).toBe(originalText)
+    })
+  })
+
+  describe("excluded commands", () => {
+    it("should NOT trigger for ralph-loop command", async () => {
+      // #given ralph-loop command
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-ralph-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("/ralph-loop do something")
+      const originalText = output.parts[0].text
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should not modify (excluded command)
+      expect(output.parts[0].text).toBe(originalText)
+    })
+
+    it("should NOT trigger for cancel-ralph command", async () => {
+      // #given cancel-ralph command
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-cancel-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("/cancel-ralph")
+      const originalText = output.parts[0].text
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should not modify
+      expect(output.parts[0].text).toBe(originalText)
+    })
+  })
+
+  describe("already processed", () => {
+    it("should skip if auto-slash-command tags already present", async () => {
+      // #given text with existing tags
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-existing-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput(
+        "<auto-slash-command>/commit</auto-slash-command>"
+      )
+      const originalText = output.parts[0].text
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should not modify
+      expect(output.parts[0].text).toBe(originalText)
+    })
+  })
+
+  describe("code blocks", () => {
+    it("should NOT detect command inside code block", async () => {
+      // #given command inside code block
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-codeblock-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("```\n/commit\n```")
+      const originalText = output.parts[0].text
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should not detect
+      expect(output.parts[0].text).toBe(originalText)
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle empty text", async () => {
+      // #given empty text
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-empty-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("")
+
+      // #when hook is called
+      // #then should not throw
+      await expect(hook["chat.message"](input, output)).resolves.toBeUndefined()
+    })
+
+    it("should handle just slash", async () => {
+      // #given just slash
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-slash-only-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput("/")
+      const originalText = output.parts[0].text
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should not modify
+      expect(output.parts[0].text).toBe(originalText)
+    })
+
+    it("should handle command with special characters in args", async () => {
+      // #given command with special characters
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-special-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output = createMockOutput('/execute "test & stuff <tag>"')
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should handle gracefully (not found, but processed)
+      const textPart = output.parts.find((p) => p.type === "text")
+      expect(textPart?.text).toContain("<auto-slash-command>")
+      expect(textPart?.text).toContain("/execute")
+    })
+
+    it("should handle multiple text parts", async () => {
+      // #given multiple text parts
+      const hook = createAutoSlashCommandHook()
+      const sessionID = `test-session-multi-${Date.now()}`
+      const input = createMockInput(sessionID)
+      const output: AutoSlashCommandHookOutput = {
+        message: {},
+        parts: [
+          { type: "text", text: "/commit " },
+          { type: "text", text: "fix bug" },
+        ],
+      }
+
+      // #when hook is called
+      await hook["chat.message"](input, output)
+
+      // #then should detect from combined text and modify first text part
+      const firstTextPart = output.parts.find((p) => p.type === "text")
+      expect(firstTextPart?.text).toContain("<auto-slash-command>")
+    })
+  })
+})

src/hooks/auto-slash-command/index.ts

@@ -0,0 +1,82 @@
+import {
+  detectSlashCommand,
+  extractPromptText,
+} from "./detector"
+import { executeSlashCommand } from "./executor"
+import { log } from "../../shared"
+import {
+  AUTO_SLASH_COMMAND_TAG_OPEN,
+  AUTO_SLASH_COMMAND_TAG_CLOSE,
+} from "./constants"
+import type {
+  AutoSlashCommandHookInput,
+  AutoSlashCommandHookOutput,
+} from "./types"
+
+export * from "./detector"
+export * from "./executor"
+export * from "./constants"
+export * from "./types"
+
+const sessionProcessedCommands = new Set<string>()
+
+export function createAutoSlashCommandHook() {
+  return {
+    "chat.message": async (
+      input: AutoSlashCommandHookInput,
+      output: AutoSlashCommandHookOutput
+    ): Promise<void> => {
+      const promptText = extractPromptText(output.parts)
+
+      if (
+        promptText.includes(AUTO_SLASH_COMMAND_TAG_OPEN) ||
+        promptText.includes(AUTO_SLASH_COMMAND_TAG_CLOSE)
+      ) {
+        return
+      }
+
+      const parsed = detectSlashCommand(promptText)
+
+      if (!parsed) {
+        return
+      }
+
+      const commandKey = `${input.sessionID}:${input.messageID}:${parsed.command}`
+      if (sessionProcessedCommands.has(commandKey)) {
+        return
+      }
+      sessionProcessedCommands.add(commandKey)
+
+      log(`[auto-slash-command] Detected: /${parsed.command}`, {
+        sessionID: input.sessionID,
+        args: parsed.args,
+      })
+
+      const result = await executeSlashCommand(parsed)
+
+      const idx = output.parts.findIndex((p) => p.type === "text" && p.text)
+      if (idx < 0) {
+        return
+      }
+
+      if (result.success && result.replacementText) {
+        const taggedContent = `${AUTO_SLASH_COMMAND_TAG_OPEN}\n${result.replacementText}\n${AUTO_SLASH_COMMAND_TAG_CLOSE}`
+        output.parts[idx].text = taggedContent
+
+        log(`[auto-slash-command] Replaced message with command template`, {
+          sessionID: input.sessionID,
+          command: parsed.command,
+        })
+      } else {
+        const errorMessage = `${AUTO_SLASH_COMMAND_TAG_OPEN}\n[AUTO-SLASH-COMMAND ERROR]\n${result.error}\n\nOriginal input: ${parsed.raw}\n${AUTO_SLASH_COMMAND_TAG_CLOSE}`
+        output.parts[idx].text = errorMessage
+
+        log(`[auto-slash-command] Command not found, showing error`, {
+          sessionID: input.sessionID,
+          command: parsed.command,
+          error: result.error,
+        })
+      }
+    },
+  }
+}

src/hooks/auto-slash-command/types.ts

@@ -0,0 +1,23 @@
+export interface AutoSlashCommandHookInput {
+  sessionID: string
+  agent?: string
+  model?: { providerID: string; modelID: string }
+  messageID?: string
+}
+
+export interface AutoSlashCommandHookOutput {
+  message: Record<string, unknown>
+  parts: Array<{ type: string; text?: string; [key: string]: unknown }>
+}
+
+export interface ParsedSlashCommand {
+  command: string
+  args: string
+  raw: string
+}
+
+export interface AutoSlashCommandResult {
+  detected: boolean
+  parsedCommand?: ParsedSlashCommand
+  injectedMessage?: string
+}

src/hooks/auto-update-checker/checker.ts

@@ -9,7 +9,10 @@ import {
   INSTALLED_PACKAGE_JSON,
   USER_OPENCODE_CONFIG,
   USER_OPENCODE_CONFIG_JSONC,
+  USER_CONFIG_DIR,
+  getWindowsAppdataDir,
 } from "./constants"
+import * as os from "node:os"
 import { log } from "../../shared/logger"
 
 export function isLocalDevMode(directory: string): boolean {
@@ -23,12 +26,32 @@ function stripJsonComments(json: string): string {
 }
 
 function getConfigPaths(directory: string): string[] {
-  return [
+  const paths = [
     path.join(directory, ".opencode", "opencode.json"),
     path.join(directory, ".opencode", "opencode.jsonc"),
     USER_OPENCODE_CONFIG,
     USER_OPENCODE_CONFIG_JSONC,
   ]
+  
+  if (process.platform === "win32") {
+    const crossPlatformDir = path.join(os.homedir(), ".config")
+    const appdataDir = getWindowsAppdataDir()
+    
+    if (appdataDir) {
+      const alternateDir = USER_CONFIG_DIR === crossPlatformDir ? appdataDir : crossPlatformDir
+      const alternateConfig = path.join(alternateDir, "opencode", "opencode.json")
+      const alternateConfigJsonc = path.join(alternateDir, "opencode", "opencode.jsonc")
+      
+      if (!paths.includes(alternateConfig)) {
+        paths.push(alternateConfig)
+      }
+      if (!paths.includes(alternateConfigJsonc)) {
+        paths.push(alternateConfigJsonc)
+      }
+    }
+  }
+  
+  return paths
 }
 
 export function getLocalDevPath(directory: string): string | null {

src/hooks/auto-update-checker/constants.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path"
 import * as os from "node:os"
+import * as fs from "node:fs"
 
 export const PACKAGE_NAME = "oh-my-opencode"
 export const NPM_REGISTRY_URL = `https://registry.npmjs.org/-/package/${PACKAGE_NAME}/dist-tags`
@@ -28,14 +29,36 @@ export const INSTALLED_PACKAGE_JSON = path.join(
 
 /**
  * OpenCode config file locations (priority order)
+ * On Windows, checks ~/.config first (cross-platform), then %APPDATA% (fallback)
+ * This matches shared/config-path.ts behavior for consistency
  */
 function getUserConfigDir(): string {
   if (process.platform === "win32") {
-    return process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming")
+    const crossPlatformDir = path.join(os.homedir(), ".config")
+    const appdataDir = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming")
+    
+    // Check cross-platform path first (~/.config)
+    const crossPlatformConfig = path.join(crossPlatformDir, "opencode", "opencode.json")
+    const crossPlatformConfigJsonc = path.join(crossPlatformDir, "opencode", "opencode.jsonc")
+    
+    if (fs.existsSync(crossPlatformConfig) || fs.existsSync(crossPlatformConfigJsonc)) {
+      return crossPlatformDir
+    }
+    
+    // Fall back to %APPDATA%
+    return appdataDir
   }
   return process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config")
 }
 
+/**
+ * Get the Windows-specific APPDATA directory (for fallback checks)
+ */
+export function getWindowsAppdataDir(): string | null {
+  if (process.platform !== "win32") return null
+  return process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming")
+}
+
 export const USER_CONFIG_DIR = getUserConfigDir()
 export const USER_OPENCODE_CONFIG = path.join(USER_CONFIG_DIR, "opencode", "opencode.json")
 export const USER_OPENCODE_CONFIG_JSONC = path.join(USER_CONFIG_DIR, "opencode", "opencode.jsonc")

src/hooks/auto-update-checker/index.ts

@@ -4,6 +4,7 @@ import { invalidatePackage } from "./cache"
 import { PACKAGE_NAME } from "./constants"
 import { log } from "../../shared/logger"
 import { getConfigLoadErrors, clearConfigLoadErrors } from "../../shared/config-errors"
+import { runBunInstall } from "../../cli/config-manager"
 import type { AutoUpdateCheckerOptions } from "./types"
 
 const SISYPHUS_SPINNER = ["·", "•", "●", "○", "◌", "◦", " "]
@@ -100,16 +101,34 @@ async function runBackgroundUpdateCheck(
 
   if (pluginInfo.isPinned) {
     const updated = updatePinnedVersion(pluginInfo.configPath, pluginInfo.entry, latestVersion)
-    if (updated) {
-      invalidatePackage(PACKAGE_NAME)
-      await showAutoUpdatedToast(ctx, currentVersion, latestVersion)
-      log(`[auto-update-checker] Config updated: ${pluginInfo.entry} → ${PACKAGE_NAME}@${latestVersion}`)
-    } else {
+    if (!updated) {
       await showUpdateAvailableToast(ctx, latestVersion, getToastMessage)
+      log("[auto-update-checker] Failed to update pinned version in config")
+      return
     }
+    log(`[auto-update-checker] Config updated: ${pluginInfo.entry} → ${PACKAGE_NAME}@${latestVersion}`)
+  }
+
+  invalidatePackage(PACKAGE_NAME)
+
+  const installSuccess = await runBunInstallSafe()
+  
+  if (installSuccess) {
+    await showAutoUpdatedToast(ctx, currentVersion, latestVersion)
+    log(`[auto-update-checker] Update installed: ${currentVersion} → ${latestVersion}`)
   } else {
-    invalidatePackage(PACKAGE_NAME)
     await showUpdateAvailableToast(ctx, latestVersion, getToastMessage)
+    log("[auto-update-checker] bun install failed; update not installed (falling back to notification-only)")
+  }
+}
+
+async function runBunInstallSafe(): Promise<boolean> {
+  try {
+    return await runBunInstall()
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err)
+    log("[auto-update-checker] bun install error:", errorMessage)
+    return false
   }
 }
 

src/hooks/claude-code-hooks/index.ts

@@ -28,6 +28,7 @@ import { recordToolUse, recordToolResult, getTranscriptPath, recordUserMessage }
 import type { PluginConfig } from "./types"
 import { log, isHookDisabled } from "../../shared"
 import { injectHookMessage } from "../../features/hook-message-injector"
+import { detectKeywordsWithType, removeCodeBlocks } from "../keyword-detector"
 
 const sessionFirstMessageProcessed = new Set<string>()
 const sessionErrorState = new Map<string, { hasError: boolean; errorMessage?: string }>()
@@ -112,11 +113,6 @@ export function createClaudeCodeHooksHook(ctx: PluginInput, config: PluginConfig
       const isFirstMessage = !sessionFirstMessageProcessed.has(input.sessionID)
       sessionFirstMessageProcessed.add(input.sessionID)
 
-      if (isFirstMessage) {
-        log("Skipping UserPromptSubmit hooks on first message for title generation", { sessionID: input.sessionID })
-        return
-      }
-
       if (!isHookDisabled(config, "UserPromptSubmit")) {
         const userPromptCtx: UserPromptSubmitContext = {
           sessionId: input.sessionID,
@@ -142,27 +138,48 @@ export function createClaudeCodeHooksHook(ctx: PluginInput, config: PluginConfig
           return
         }
 
-        if (result.messages.length > 0) {
-          const hookContent = result.messages.join("\n\n")
-          log(`[claude-code-hooks] Injecting ${result.messages.length} hook messages`, { sessionID: input.sessionID, contentLength: hookContent.length })
-          const message = output.message as {
-            agent?: string
-            model?: { modelID?: string; providerID?: string }
-            path?: { cwd?: string; root?: string }
-            tools?: Record<string, boolean>
-          }
+        const detectedKeywords = detectKeywordsWithType(removeCodeBlocks(prompt), input.agent)
+        const keywordMessages = detectedKeywords.map((k) => k.message)
 
-          const success = injectHookMessage(input.sessionID, hookContent, {
-            agent: message.agent,
-            model: message.model,
-            path: message.path ?? { cwd: ctx.directory, root: "/" },
-            tools: message.tools,
-          })
-
-          log(success ? "Hook message injected via file system" : "File injection failed", {
+        if (keywordMessages.length > 0) {
+          log("[claude-code-hooks] Detected keywords", {
             sessionID: input.sessionID,
+            types: detectedKeywords.map((k) => k.type),
           })
         }
+
+        const allMessages = [...keywordMessages, ...result.messages]
+
+        if (allMessages.length > 0) {
+          const hookContent = allMessages.join("\n\n")
+          log(`[claude-code-hooks] Injecting ${allMessages.length} messages (${keywordMessages.length} keyword + ${result.messages.length} hook)`, { sessionID: input.sessionID, contentLength: hookContent.length, isFirstMessage })
+
+          if (isFirstMessage) {
+            const idx = output.parts.findIndex((p) => p.type === "text" && p.text)
+            if (idx >= 0) {
+              output.parts[idx].text = `${hookContent}\n\n${output.parts[idx].text ?? ""}`
+              log("UserPromptSubmit hooks prepended to first message parts directly", { sessionID: input.sessionID })
+            }
+          } else {
+            const message = output.message as {
+              agent?: string
+              model?: { modelID?: string; providerID?: string }
+              path?: { cwd?: string; root?: string }
+              tools?: Record<string, boolean>
+            }
+
+            const success = injectHookMessage(input.sessionID, hookContent, {
+              agent: message.agent,
+              model: message.model,
+              path: message.path ?? { cwd: ctx.directory, root: "/" },
+              tools: message.tools,
+            })
+
+            log(success ? "Hook message injected via file system" : "File injection failed", {
+              sessionID: input.sessionID,
+            })
+          }
+        }
       }
     },
 

src/hooks/context-window-monitor.ts

@@ -1,7 +1,11 @@
 import type { PluginInput } from "@opencode-ai/plugin"
 
 const ANTHROPIC_DISPLAY_LIMIT = 1_000_000
-const ANTHROPIC_ACTUAL_LIMIT = 200_000
+const ANTHROPIC_ACTUAL_LIMIT =
+  process.env.ANTHROPIC_1M_CONTEXT === "true" ||
+  process.env.VERTEX_ANTHROPIC_1M_CONTEXT === "true"
+    ? 1_000_000
+    : 200_000
 const CONTEXT_WARNING_THRESHOLD = 0.70
 
 const CONTEXT_REMINDER = `[SYSTEM REMINDER - 1M Context Window]

src/hooks/directory-agents-injector/index.ts

@@ -60,12 +60,17 @@ export function createDirectoryAgentsInjectorHook(ctx: PluginInput) {
     let current = startDir;
 
     while (true) {
-      const agentsPath = join(current, AGENTS_FILENAME);
-      if (existsSync(agentsPath)) {
-        found.push(agentsPath);
+      // Skip root AGENTS.md - OpenCode's system.ts already loads it via custom()
+      // See: https://github.com/code-yeongyu/oh-my-opencode/issues/379
+      const isRootDir = current === ctx.directory;
+      if (!isRootDir) {
+        const agentsPath = join(current, AGENTS_FILENAME);
+        if (existsSync(agentsPath)) {
+          found.push(agentsPath);
+        }
       }
 
-      if (current === ctx.directory) break;
+      if (isRootDir) break;
       const parent = dirname(current);
       if (parent === current) break;
       if (!parent.startsWith(ctx.directory)) break;

src/hooks/edit-error-recovery/index.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeEach } from "bun:test"
+import { createEditErrorRecoveryHook, EDIT_ERROR_REMINDER, EDIT_ERROR_PATTERNS } from "./index"
+
+describe("createEditErrorRecoveryHook", () => {
+  let hook: ReturnType<typeof createEditErrorRecoveryHook>
+
+  beforeEach(() => {
+    hook = createEditErrorRecoveryHook({} as any)
+  })
+
+  describe("tool.execute.after", () => {
+    const createInput = (tool: string) => ({
+      tool,
+      sessionID: "test-session",
+      callID: "test-call-id",
+    })
+
+    const createOutput = (outputText: string) => ({
+      title: "Edit",
+      output: outputText,
+      metadata: {},
+    })
+
+    describe("#given Edit tool with oldString/newString same error", () => {
+      describe("#when the error message is detected", () => {
+        it("#then should append the recovery reminder", async () => {
+          const input = createInput("Edit")
+          const output = createOutput("Error: oldString and newString must be different")
+
+          await hook["tool.execute.after"](input, output)
+
+          expect(output.output).toContain(EDIT_ERROR_REMINDER)
+          expect(output.output).toContain("oldString and newString must be different")
+        })
+      })
+
+      describe("#when the error appears without Error prefix", () => {
+        it("#then should still detect and append reminder", async () => {
+          const input = createInput("Edit")
+          const output = createOutput("oldString and newString must be different")
+
+          await hook["tool.execute.after"](input, output)
+
+          expect(output.output).toContain(EDIT_ERROR_REMINDER)
+        })
+      })
+    })
+
+    describe("#given Edit tool with oldString not found error", () => {
+      describe("#when oldString not found in content", () => {
+        it("#then should append the recovery reminder", async () => {
+          const input = createInput("Edit")
+          const output = createOutput("Error: oldString not found in content")
+
+          await hook["tool.execute.after"](input, output)
+
+          expect(output.output).toContain(EDIT_ERROR_REMINDER)
+        })
+      })
+    })
+
+    describe("#given Edit tool with multiple matches error", () => {
+      describe("#when oldString found multiple times", () => {
+        it("#then should append the recovery reminder", async () => {
+          const input = createInput("Edit")
+          const output = createOutput(
+            "Error: oldString found multiple times and requires more code context to uniquely identify the intended match"
+          )
+
+          await hook["tool.execute.after"](input, output)
+
+          expect(output.output).toContain(EDIT_ERROR_REMINDER)
+        })
+      })
+    })
+
+    describe("#given non-Edit tool", () => {
+      describe("#when tool is not Edit", () => {
+        it("#then should not modify output", async () => {
+          const input = createInput("Read")
+          const originalOutput = "some output"
+          const output = createOutput(originalOutput)
+
+          await hook["tool.execute.after"](input, output)
+
+          expect(output.output).toBe(originalOutput)
+        })
+      })
+    })
+
+    describe("#given Edit tool with successful output", () => {
+      describe("#when no error in output", () => {
+        it("#then should not modify output", async () => {
+          const input = createInput("Edit")
+          const originalOutput = "File edited successfully"
+          const output = createOutput(originalOutput)
+
+          await hook["tool.execute.after"](input, output)
+
+          expect(output.output).toBe(originalOutput)
+        })
+      })
+    })
+
+    describe("#given case insensitive tool name", () => {
+      describe("#when tool is 'edit' lowercase", () => {
+        it("#then should still detect and append reminder", async () => {
+          const input = createInput("edit")
+          const output = createOutput("oldString and newString must be different")
+
+          await hook["tool.execute.after"](input, output)
+
+          expect(output.output).toContain(EDIT_ERROR_REMINDER)
+        })
+      })
+    })
+  })
+
+  describe("EDIT_ERROR_PATTERNS", () => {
+    it("#then should contain all known Edit error patterns", () => {
+      expect(EDIT_ERROR_PATTERNS).toContain("oldString and newString must be different")
+      expect(EDIT_ERROR_PATTERNS).toContain("oldString not found")
+      expect(EDIT_ERROR_PATTERNS).toContain("oldString found multiple times")
+    })
+  })
+})

src/hooks/edit-error-recovery/index.ts

@@ -0,0 +1,57 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+
+/**
+ * Known Edit tool error patterns that indicate the AI made a mistake
+ */
+export const EDIT_ERROR_PATTERNS = [
+  "oldString and newString must be different",
+  "oldString not found",
+  "oldString found multiple times",
+] as const
+
+/**
+ * System reminder injected when Edit tool fails due to AI mistake
+ * Short, direct, and commanding - forces immediate corrective action
+ */
+export const EDIT_ERROR_REMINDER = `
+[EDIT ERROR - IMMEDIATE ACTION REQUIRED]
+
+You made an Edit mistake. STOP and do this NOW:
+
+1. READ the file immediately to see its ACTUAL current state
+2. VERIFY what the content really looks like (your assumption was wrong)
+3. APOLOGIZE briefly to the user for the error
+4. CONTINUE with corrected action based on the real file content
+
+DO NOT attempt another edit until you've read and verified the file state.
+`
+
+/**
+ * Detects Edit tool errors caused by AI mistakes and injects a recovery reminder
+ *
+ * This hook catches common Edit tool failures:
+ * - oldString and newString must be different (trying to "edit" to same content)
+ * - oldString not found (wrong assumption about file content)
+ * - oldString found multiple times (ambiguous match, need more context)
+ *
+ * @see https://github.com/sst/opencode/issues/4718
+ */
+export function createEditErrorRecoveryHook(_ctx: PluginInput) {
+  return {
+    "tool.execute.after": async (
+      input: { tool: string; sessionID: string; callID: string },
+      output: { title: string; output: string; metadata: unknown }
+    ) => {
+      if (input.tool.toLowerCase() !== "edit") return
+
+      const outputLower = output.output.toLowerCase()
+      const hasEditError = EDIT_ERROR_PATTERNS.some((pattern) =>
+        outputLower.includes(pattern.toLowerCase())
+      )
+
+      if (hasEditError) {
+        output.output += `\n${EDIT_ERROR_REMINDER}`
+      }
+    },
+  }
+}