refactor(aliases): migrate to pattern-based model alias resolution

Move from hardcoded exact aliases to pattern-based canonicalization:

- Populate PATTERN_ALIAS_RULES with regex patterns for:
  - Claude thinking variants (claude-opus-4-6-thinking → claude-opus-4-6)
  - Gemini tier suffixes (gemini-3.1-pro-{high,low} → gemini-3.1-pro)
- Add stripProviderPrefixForAliasLookup() for provider-prefixed models
  (anthropic/claude-sonnet-4-6 → claude-sonnet-4-6 for capability lookup)
- Preserve requestedModelID (with prefix) for API transport
- Reduce EXACT_ALIAS_RULES to exceptional cases only
  (gemini-3-pro-{high,low} → gemini-3-pro-preview)
- Comprehensive test coverage for patterns, prefix stripping, negatives

Addresses Discussion #2835 (pattern matching architecture)
Related to PR #2834 (alias guardrails)

41 targeted tests pass, 4467 full suite tests pass, tsc clean.

.github/workflows/publish.yml

@@ -57,6 +57,7 @@ jobs:
           bun test src/cli/doctor/format-default.test.ts
           bun test src/tools/call-omo-agent/sync-executor.test.ts
           bun test src/tools/call-omo-agent/session-creator.test.ts
+          bun test src/tools/session-manager
           bun test src/features/opencode-skill-loader/loader.test.ts
           bun test src/hooks/anthropic-context-window-limit-recovery/recovery-hook.test.ts
           bun test src/hooks/anthropic-context-window-limit-recovery/executor.test.ts
@@ -66,9 +67,8 @@ jobs:
           # Enumerate subdirectories/files explicitly to EXCLUDE mock-heavy files
           # that were already run in isolation above.
           # Excluded from src/cli: doctor/formatter.test.ts, doctor/format-default.test.ts
-          # Excluded from src/tools: call-omo-agent/sync-executor.test.ts, call-omo-agent/session-creator.test.ts
+          # Excluded from src/tools: call-omo-agent/sync-executor.test.ts, call-omo-agent/session-creator.test.ts, session-manager (all)
           # Excluded from src/hooks/anthropic-context-window-limit-recovery: recovery-hook.test.ts, executor.test.ts
-          # Excluded from src/tools: call-omo-agent/sync-executor.test.ts, call-omo-agent/session-creator.test.ts
           bun test bin script src/config src/mcp src/index.test.ts \
             src/agents src/shared \
             src/cli/run src/cli/config-manager src/cli/mcp-oauth \
@@ -77,7 +77,7 @@ jobs:
             src/cli/doctor/runner.test.ts src/cli/doctor/checks \
             src/tools/ast-grep src/tools/background-task src/tools/delegate-task \
             src/tools/glob src/tools/grep src/tools/interactive-bash \
-            src/tools/look-at src/tools/lsp src/tools/session-manager \
+            src/tools/look-at src/tools/lsp \
             src/tools/skill src/tools/skill-mcp src/tools/slashcommand src/tools/task \
             src/tools/call-omo-agent/background-agent-executor.test.ts \
             src/tools/call-omo-agent/background-executor.test.ts \

.github/workflows/refresh-model-capabilities.yml

@@ -0,0 +1,46 @@
+name: Refresh Model Capabilities
+
+on:
+  schedule:
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    if: github.repository == 'code-yeongyu/oh-my-openagent'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          BUN_INSTALL_ALLOW_SCRIPTS: "@ast-grep/napi"
+
+      - name: Refresh bundled model capabilities snapshot
+        run: bun run build:model-capabilities
+
+      - name: Validate capability guardrails
+        run: bun run test:model-capabilities
+
+      - name: Create refresh pull request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "chore: refresh model capabilities snapshot"
+          title: "chore: refresh model capabilities snapshot"
+          body: |
+            Automated refresh of `src/generated/model-capabilities.generated.json` from `https://models.dev/api.json`.
+
+            This keeps the bundled capability snapshot aligned with upstream model metadata without relying on manual refreshes.
+          branch: automation/refresh-model-capabilities
+          delete-branch: true
+          labels: |
+            maintenance

.gitignore

@@ -36,3 +36,4 @@ test-injection/
 notepad.md
 oauth-success.html
 *.bun-build
+.omx/

.opencode/skills/github-triage/SKILL.md

@@ -79,47 +79,65 @@ Pass `REPO`, `REPORT_DIR`, and `COMMIT_SHA` to every subagent.
 
 ---
 
-## Phase 1: Fetch All Open Items
+---
 
-<fetch>
-Paginate if 500 results returned.
+## Phase 1: Fetch All Open Items (CORRECTED)
+
+**IMPORTANT:** `body` and `comments` fields may contain control characters that break jq parsing. Fetch basic metadata first, then fetch full details per-item in subagents.
 
 ```bash
-ISSUES=$(gh issue list --repo $REPO --state open --limit 500 \
-  --json number,title,state,createdAt,updatedAt,labels,author,body,comments)
-ISSUE_LEN=$(echo "$ISSUES" | jq length)
-if [ "$ISSUE_LEN" -eq 500 ]; then
-  LAST_DATE=$(echo "$ISSUES" | jq -r '.[-1].createdAt')
+# Step 1: Fetch basic metadata (without body/comments to avoid JSON parsing issues)
+ISSUES_LIST=$(gh issue list --repo $REPO --state open --limit 500 \
+  --json number,title,labels,author,createdAt)
+ISSUE_COUNT=$(echo "$ISSUES_LIST" | jq length)
+
+# Paginate if needed
+if [ "$ISSUE_COUNT" -eq 500 ]; then
+  LAST_DATE=$(echo "$ISSUES_LIST" | jq -r '.[-1].createdAt')
   while true; do
     PAGE=$(gh issue list --repo $REPO --state open --limit 500 \
       --search "created:<$LAST_DATE" \
-      --json number,title,state,createdAt,updatedAt,labels,author,body,comments)
-    PAGE_LEN=$(echo "$PAGE" | jq length)
-    [ "$PAGE_LEN" -eq 0 ] && break
-    ISSUES=$(echo "[$ISSUES, $PAGE]" | jq -s 'add | unique_by(.number)')
-    [ "$PAGE_LEN" -lt 500 ] && break
+      --json number,title,labels,author,createdAt)
+    PAGE_COUNT=$(echo "$PAGE" | jq length)
+    [ "$PAGE_COUNT" -eq 0 ] && break
+    ISSUES_LIST=$(echo "$ISSUES_LIST" "$PAGE" | jq -s '.[0] + .[1] | unique_by(.number)')
+    ISSUE_COUNT=$(echo "$ISSUES_LIST" | jq length)
+    [ "$PAGE_COUNT" -lt 500 ] && break
     LAST_DATE=$(echo "$PAGE" | jq -r '.[-1].createdAt')
   done
 fi
 
-PRS=$(gh pr list --repo $REPO --state open --limit 500 \
-  --json number,title,state,createdAt,updatedAt,labels,author,body,headRefName,baseRefName,isDraft,mergeable,reviewDecision,statusCheckRollup)
-PR_LEN=$(echo "$PRS" | jq length)
-if [ "$PR_LEN" -eq 500 ]; then
-  LAST_DATE=$(echo "$PRS" | jq -r '.[-1].createdAt')
+# Same for PRs
+PRS_LIST=$(gh pr list --repo $REPO --state open --limit 500 \
+  --json number,title,labels,author,headRefName,baseRefName,isDraft,createdAt)
+PR_COUNT=$(echo "$PRS_LIST" | jq length)
+
+if [ "$PR_COUNT" -eq 500 ]; then
+  LAST_DATE=$(echo "$PRS_LIST" | jq -r '.[-1].createdAt')
   while true; do
     PAGE=$(gh pr list --repo $REPO --state open --limit 500 \
       --search "created:<$LAST_DATE" \
-      --json number,title,state,createdAt,updatedAt,labels,author,body,headRefName,baseRefName,isDraft,mergeable,reviewDecision,statusCheckRollup)
-    PAGE_LEN=$(echo "$PAGE" | jq length)
-    [ "$PAGE_LEN" -eq 0 ] && break
-    PRS=$(echo "[$PRS, $PAGE]" | jq -s 'add | unique_by(.number)')
-    [ "$PAGE_LEN" -lt 500 ] && break
+      --json number,title,labels,author,headRefName,baseRefName,isDraft,createdAt)
+    PAGE_COUNT=$(echo "$PAGE" | jq length)
+    [ "$PAGE_COUNT" -eq 0 ] && break
+    PRS_LIST=$(echo "$PRS_LIST" "$PAGE" | jq -s '.[0] + .[1] | unique_by(.number)')
+    PR_COUNT=$(echo "$PRS_LIST" | jq length)
+    [ "$PAGE_COUNT" -lt 500 ] && break
     LAST_DATE=$(echo "$PAGE" | jq -r '.[-1].createdAt')
   done
 fi
+
+echo "Total issues: $ISSUE_COUNT, Total PRs: $PR_COUNT"
 ```
-</fetch>
+
+**LARGE REPOSITORY HANDLING:**
+If total items exceeds 50, you MUST process ALL items. Use the pagination code above to fetch every single open issue and PR.
+**DO NOT** sample or limit to 50 items - process the entire backlog.
+
+Example: If there are 500 open issues, spawn 500 subagents. If there are 1000 open PRs, spawn 1000 subagents.
+
+**Note:** Background task system will queue excess tasks automatically.
+
 
 ---
 
@@ -136,7 +154,36 @@ fi
 
 ---
 
-## Phase 3: Spawn Subagents
+## Phase 3: Spawn Subagents (Individual Tool Calls)
+
+**CRITICAL: Create tasks ONE BY ONE using individual `task_create` tool calls. NEVER batch or script.**
+
+For each item, execute these steps sequentially:
+
+### Step 3.1: Create Task Record
+```typescript
+task_create(
+  subject="Triage: #{number} {title}",
+  description="GitHub {issue|PR} triage analysis - {type}",
+  metadata={"type": "{ISSUE_QUESTION|ISSUE_BUG|ISSUE_FEATURE|ISSUE_OTHER|PR_BUGFIX|PR_OTHER}", "number": {number}}
+)
+```
+
+### Step 3.2: Spawn Analysis Subagent (Background)
+```typescript
+task(
+  category="quick",
+  run_in_background=true,
+  load_skills=[],
+  prompt=SUBAGENT_PROMPT
+)
+```
+
+**ABSOLUTE RULES for Subagents:**
+- **ONLY ANALYZE** - Never take action on GitHub (no comments, merges, closes)
+- **READ-ONLY** - Use tools only for reading code/GitHub data
+- **WRITE REPORT ONLY** - Output goes to `{REPORT_DIR}/{issue|pr}-{number}.md` via Write tool
+- **EVIDENCE REQUIRED** - Every claim must have GitHub permalink as proof
 
 ```
 For each item:
@@ -170,6 +217,7 @@ ABSOLUTE RULES (violating ANY = critical failure):
 - Your ONLY writable output: {REPORT_DIR}/{issue|pr}-{number}.md via the Write tool
 ```
 
+
 ---
 
 ### ISSUE_QUESTION

AGENTS.md

@@ -4,7 +4,7 @@
 
 ## OVERVIEW
 
-OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 46 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1268 TypeScript files, 160k LOC.
+OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 48 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1268 TypeScript files, 160k LOC.
 
 ## STRUCTURE
 
@@ -14,14 +14,14 @@ oh-my-opencode/
 │   ├── index.ts              # Plugin entry: loadConfig → createManagers → createTools → createHooks → createPluginInterface
 │   ├── plugin-config.ts      # JSONC multi-level config: user → project → defaults (Zod v4)
 │   ├── agents/               # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
-│   ├── hooks/                # 46 hooks across 45 directories + 11 standalone files
+│   ├── hooks/                # 48 lifecycle hooks across dedicated modules and standalone files
 │   ├── tools/                # 26 tools across 15 directories
 │   ├── features/             # 19 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.)
 │   ├── shared/               # 95+ utility files in 13 categories
 │   ├── config/               # Zod v4 schema system (24 files)
 │   ├── cli/                  # CLI: install, run, doctor, mcp-oauth (Commander.js)
 │   ├── mcp/                  # 3 built-in remote MCPs (websearch, context7, grep_app)
-│   ├── plugin/               # 8 OpenCode hook handlers + 46 hook composition
+│   ├── plugin/               # 8 OpenCode hook handlers + 48 hook composition
 │   └── plugin-handlers/      # 6-phase config loading pipeline
 ├── packages/                 # Monorepo: cli-runner, 12 platform binaries
 └── local-ignore/             # Dev-only test fixtures
@@ -34,7 +34,7 @@ OhMyOpenCodePlugin(ctx)
   ├─→ loadPluginConfig()         # JSONC parse → project/user merge → Zod validate → migrate
   ├─→ createManagers()           # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
   ├─→ createTools()              # SkillContext + AvailableCategories + ToolRegistry (26 tools)
-  ├─→ createHooks()              # 3-tier: Core(37) + Continuation(7) + Skill(2) = 46 hooks
+  ├─→ createHooks()              # 3-tier: Core(39) + Continuation(7) + Skill(2) = 48 hooks
   └─→ createPluginInterface()    # 8 OpenCode hook handlers → PluginInterface
 ```
 
@@ -97,7 +97,7 @@ Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom
 - **Test pattern**: Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style (nested describe with `#given`/`#when`/`#then` prefixes)
 - **CI test split**: mock-heavy tests run in isolation (separate `bun test` processes), rest in batch
 - **Factory pattern**: `createXXX()` for all tools, hooks, agents
-- **Hook tiers**: Session (23) → Tool-Guard (10) → Transform (4) → Continuation (7) → Skill (2)
+- **Hook tiers**: Session (23) → Tool-Guard (12) → Transform (4) → Continuation (7) → Skill (2)
 - **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all`
 - **Model resolution**: 4-step: override → category-default → provider-fallback → system-default
 - **Config format**: JSONC with comments, Zod v4 validation, snake_case keys

README.ja.md

@@ -4,6 +4,17 @@
 > コアメンテナーのQが負傷したため、今週は Issue/PR への返信とリリースが遅れる可能性があります。
 > ご理解とご支援に感謝します。
 
+> [!TIP]
+> **Building in Public**
+>
+> メンテナーが Jobdori を使い、oh-my-opencode をリアルタイムで開発・メンテナンスしています。Jobdori は OpenClaw をベースに大幅カスタマイズされた AI アシスタントです。
+> すべての機能開発、修正、Issue トリアージを Discord でライブでご覧いただけます。
+>
+> [![Building in Public](./.github/assets/building-in-public.png)](https://discord.gg/PUwSMR9XNk)
+>
+> [**→ #building-in-public で確認する**](https://discord.gg/PUwSMR9XNk)
+
+
 > [!NOTE]
 >
 > [![Sisyphus Labs - Sisyphus is the agent that codes like your team.](./.github/assets/sisyphuslabs.png?v=2)](https://sisyphuslabs.ai)

README.ko.md

@@ -4,6 +4,17 @@
 > 핵심 메인테이너 Q가 부상을 입어, 이번 주에는 이슈/PR 응답 및 릴리스가 지연될 수 있습니다.
 > 양해와 응원에 감사드립니다.
 
+> [!TIP]
+> **Building in Public**
+>
+> 메인테이너가 Jobdori를 통해 oh-my-opencode를 실시간으로 개발하고 있습니다. Jobdori는 OpenClaw를 기반으로 대폭 커스터마이징된 AI 어시스턴트입니다.
+> 모든 기능 개발, 버그 수정, 이슈 트리아지를 Discord에서 실시간으로 확인하세요.
+>
+> [![Building in Public](./.github/assets/building-in-public.png)](https://discord.gg/PUwSMR9XNk)
+>
+> [**→ #building-in-public에서 확인하기**](https://discord.gg/PUwSMR9XNk)
+
+
 > [!TIP]
 > 저희와 함께 하세요!
 >

README.md

@@ -1,3 +1,13 @@
+> [!TIP]
+> **Building in Public**
+>
+> The maintainer builds and maintains oh-my-opencode in real-time with Jobdori, an AI assistant built on a heavily customized fork of OpenClaw.
+> Every feature, every fix, every issue triage — live in our Discord.
+>
+> [![Building in Public](./.github/assets/building-in-public.png)](https://discord.gg/PUwSMR9XNk)
+>
+> [**→ Watch it happen in #building-in-public**](https://discord.gg/PUwSMR9XNk)
+
 > [!NOTE]
 >
 > [![Sisyphus Labs - Sisyphus is the agent that codes like your team.](./.github/assets/sisyphuslabs.png?v=2)](https://sisyphuslabs.ai)
@@ -304,7 +314,7 @@ See full [Features Documentation](docs/reference/features.md).
 - **Claude Code Compatibility**: Full hook system, commands, skills, agents, MCPs
 - **Built-in MCPs**: websearch (Exa), context7 (docs), grep_app (GitHub search)
 - **Session Tools**: List, read, search, and analyze session history
-- **Productivity Features**: Ralph Loop, Todo Enforcer, GPT permission-tail continuation, Comment Checker, Think Mode, and more
+- **Productivity Features**: Ralph Loop, Todo Enforcer, Comment Checker, Think Mode, and more
 - **Model Setup**: Agent-model matching is built into the [Installation Guide](docs/guide/installation.md#step-5-understand-your-model-setup)
 
 ## Configuration
@@ -321,7 +331,7 @@ See [Configuration Documentation](docs/reference/configuration.md).
 - **Sisyphus Agent**: Main orchestrator with Prometheus (Planner) and Metis (Plan Consultant)
 - **Background Tasks**: Configure concurrency limits per provider/model
 - **Categories**: Domain-specific task delegation (`visual`, `business-logic`, custom)
-- **Hooks**: 25+ built-in hooks, including `gpt-permission-continuation`, all configurable via `disabled_hooks`
+- **Hooks**: 25+ built-in hooks, all configurable via `disabled_hooks`
 - **MCPs**: Built-in websearch (Exa), context7 (docs), grep_app (GitHub search)
 - **LSP**: Full LSP support with refactoring tools
 - **Experimental**: Aggressive truncation, auto-resume, and more

README.ru.md

@@ -4,6 +4,17 @@
 > Ключевой мейнтейнер Q получил травму, поэтому на этой неделе ответы по issue/PR и релизы могут задерживаться.
 > Спасибо за терпение и поддержку.
 
+> [!TIP]
+> **Building in Public**
+>
+> Мейнтейнер разрабатывает и поддерживает oh-my-opencode в режиме реального времени с помощью Jobdori — ИИ-ассистента на базе глубоко кастомизированной версии OpenClaw.
+> Каждая фича, каждый фикс, каждый триаж issue — в прямом эфире в нашем Discord.
+>
+> [![Building in Public](./.github/assets/building-in-public.png)](https://discord.gg/PUwSMR9XNk)
+>
+> [**→ Смотрите в #building-in-public**](https://discord.gg/PUwSMR9XNk)
+
+
 > [!NOTE]
 >
 > [![Sisyphus Labs - Sisyphus is the agent that codes like your team.](./.github/assets/sisyphuslabs.png?v=2)](https://sisyphuslabs.ai)

README.zh-cn.md

@@ -4,6 +4,17 @@
 > 核心维护者 Q 因受伤，本周 issue/PR 回复和发布可能会延迟。
 > 感谢你的耐心与支持。
 
+> [!TIP]
+> **Building in Public**
+>
+> 维护者正在使用 Jobdori 实时开发和维护 oh-my-opencode。Jobdori 是基于 OpenClaw 深度定制的 AI 助手。
+> 每个功能开发、每次修复、每次 Issue 分类，都在 Discord 上实时进行。
+>
+> [![Building in Public](./.github/assets/building-in-public.png)](https://discord.gg/PUwSMR9XNk)
+>
+> [**→ 在 #building-in-public 频道中查看**](https://discord.gg/PUwSMR9XNk)
+
+
 > [!NOTE]
 >
 > [![Sisyphus Labs - Sisyphus is the agent that codes like your team.](./.github/assets/sisyphuslabs.png?v=2)](https://sisyphuslabs.ai)

docs/guide/agent-model-matching.md

@@ -8,7 +8,7 @@ Think of AI models as developers on a team. Each has a different brain, differen
 
 This isn't a bug. It's the foundation of the entire system.
 
-Oh My OpenCode assigns each agent a model that matches its _working style_ — like building a team where each person is in the role that fits their personality.
+Oh My OpenAgent assigns each agent a model that matches its _working style_ — like building a team where each person is in the role that fits their personality.
 
 ### Sisyphus: The Sociable Lead
 
@@ -92,10 +92,10 @@ These agents do grep, search, and retrieval. They intentionally use the fastest,
 
 | Agent                 | Role               | Fallback Chain                                 | Notes                                                 |
 | --------------------- | ------------------ | ---------------------------------------------- | ----------------------------------------------------- |
-| **Explore**           | Fast codebase grep | Grok Code Fast → opencode-go/minimax-m2.5 → MiniMax Free → Haiku → GPT-5-Nano | Speed is everything. Fire 10 in parallel.             |
-| **Librarian**         | Docs/code search   | opencode-go/minimax-m2.5 → MiniMax Free → Haiku → GPT-5-Nano                  | Doc retrieval doesn't need deep reasoning.            |
-| **Multimodal Looker** | Vision/screenshots | GPT-5.4 → opencode-go/kimi-k2.5 → GLM-4.6v → GPT-5-Nano                       | Uses the first available multimodal-capable fallback. |
-| **Sisyphus-Junior**   | Category executor  | Claude Sonnet → opencode-go/kimi-k2.5 → GPT-5.4 → Big Pickle                  | Handles delegated category tasks. Sonnet-tier default. |
+| **Explore**           | Fast codebase grep | Grok Code Fast → opencode-go/minimax-m2.7-highspeed → MiniMax M2.7 → Haiku → GPT-5-Nano | Speed is everything. Fire 10 in parallel.             |
+| **Librarian**         | Docs/code search   | opencode-go/minimax-m2.7 → MiniMax M2.7-highspeed → Haiku → GPT-5-Nano                  | Doc retrieval doesn't need deep reasoning.            |
+| **Multimodal Looker** | Vision/screenshots | GPT-5.4 → opencode-go/kimi-k2.5 → GLM-4.6v → GPT-5-Nano                                 | Uses the first available multimodal-capable fallback. |
+| **Sisyphus-Junior**   | Category executor  | Claude Sonnet → opencode-go/kimi-k2.5 → GPT-5.4 → MiniMax M2.7 → Big Pickle              | Handles delegated category tasks. Sonnet-tier default. |
 
 ---
 
@@ -121,6 +121,7 @@ Principle-driven, explicit reasoning, deep technical capability. Best for agents
 | ----------------- | ----------------------------------------------------------------------------------------------- |
 | **GPT-5.3 Codex** | Deep coding powerhouse. Autonomous exploration. Required for Hephaestus.                        |
 | **GPT-5.4**       | High intelligence, strategic reasoning. Default for Oracle, Momus, and a key fallback for Prometheus / Atlas. Uses xhigh variant for Momus. |
+| **GPT-5.4 Mini**  | Fast + strong reasoning. Good for lightweight autonomous tasks. Default for quick category. |
 | **GPT-5-Nano**    | Ultra-cheap, fast. Good for simple utility tasks.                                               |
 
 ### Other Models
@@ -130,7 +131,8 @@ Principle-driven, explicit reasoning, deep technical capability. Best for agents
 | **Gemini 3.1 Pro**   | Excels at visual/frontend tasks. Different reasoning style. Default for `visual-engineering` and `artistry`. |
 | **Gemini 3 Flash**   | Fast. Good for doc search and light tasks.                                                                   |
 | **Grok Code Fast 1** | Blazing fast code grep. Default for Explore agent.                                                           |
-| **MiniMax M2.5**     | Fast and smart. Good for utility tasks and search/retrieval.                                                 |
+| **MiniMax M2.7**     | Fast and smart. Good for utility tasks and search/retrieval. Upgraded from M2.5 with better reasoning.       |
+| **MiniMax M2.7 Highspeed** | Ultra-fast variant. Optimized for latency-sensitive tasks like codebase grep.                           |
 
 ### OpenCode Go
 
@@ -142,11 +144,11 @@ A premium subscription tier ($10/month) that provides reliable access to Chinese
 | ------------------------ | --------------------------------------------------------------------- |
 | **opencode-go/kimi-k2.5** | Vision-capable, Claude-like reasoning. Used by Sisyphus, Atlas, Sisyphus-Junior, Multimodal Looker. |
 | **opencode-go/glm-5**     | Text-only orchestration model. Used by Oracle, Prometheus, Metis, Momus.                           |
-| **opencode-go/minimax-m2.5** | Ultra-cheap, fast responses. Used by Librarian, Explore for utility work.                          |
+| **opencode-go/minimax-m2.7** | Ultra-cheap, fast responses. Used by Librarian, Explore, Atlas, Sisyphus-Junior for utility work.   |
 
 **When It Gets Used:**
 
-OpenCode Go models appear in fallback chains as intermediate options. They bridge the gap between premium Claude access and free-tier alternatives. The system tries OpenCode Go models before falling back to free tiers (MiniMax Free, Big Pickle) or GPT alternatives.
+OpenCode Go models appear in fallback chains as intermediate options. They bridge the gap between premium Claude access and free-tier alternatives. The system tries OpenCode Go models before falling back to free tiers (MiniMax M2.7-highspeed, Big Pickle) or GPT alternatives.
 
 **Go-Only Scenarios:**
 
@@ -154,7 +156,7 @@ Some model identifiers like `k2p5` (paid Kimi K2.5) and `glm-5` may only be avai
 
 ### About Free-Tier Fallbacks
 
-You may see model names like `kimi-k2.5-free`, `minimax-m2.5-free`, or `big-pickle` (GLM 4.6) in the source code or logs. These are free-tier versions of the same model families, served through the OpenCode Zen provider. They exist as lower-priority entries in fallback chains.
+You may see model names like `kimi-k2.5-free`, `minimax-m2.7-highspeed`, or `big-pickle` (GLM 4.6) in the source code or logs. These are free-tier or speed-optimized versions of the same model families. They exist as lower-priority entries in fallback chains.
 
 You don't need to configure them. The system includes them so it degrades gracefully when you don't have every paid subscription. If you have the paid version, the paid version is always preferred.
 
@@ -170,7 +172,7 @@ When agents delegate work, they don't pick a model name — they pick a **catego
 | `ultrabrain`         | Maximum reasoning needed   | GPT-5.4 → Gemini 3.1 Pro → Claude Opus → opencode-go/glm-5 |
 | `deep`               | Deep coding, complex logic | GPT-5.3 Codex → Claude Opus → Gemini 3.1 Pro |
 | `artistry`           | Creative, novel approaches | Gemini 3.1 Pro → Claude Opus → GPT-5.4       |
-| `quick`              | Simple, fast tasks         | Claude Haiku → Gemini Flash → opencode-go/minimax-m2.5 → GPT-5-Nano |
+| `quick`              | Simple, fast tasks         | GPT-5.4 Mini → Claude Haiku → Gemini Flash → opencode-go/minimax-m2.7 → GPT-5-Nano |
 | `unspecified-high`   | General complex work       | Claude Opus → GPT-5.4 → GLM 5 → K2P5 → opencode-go/glm-5 → Kimi K2.5 |
 | `unspecified-low`    | General standard work      | Claude Sonnet → GPT-5.3 Codex → opencode-go/kimi-k2.5 → Gemini Flash |
 | `writing`            | Text, docs, prose          | Gemini Flash → opencode-go/kimi-k2.5 → Claude Sonnet |
@@ -185,7 +187,7 @@ See the [Orchestration System Guide](./orchestration.md) for how agents dispatch
 
 ```jsonc
 {
-  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
 
   "agents": {
     // Main orchestrator: Claude Opus or Kimi K2.5 work best

docs/guide/installation.md

@@ -5,7 +5,7 @@
 Paste this into your llm agent session:
 
 ```
-Install and configure oh-my-opencode by following the instructions here:
+Install and configure oh-my-openagent by following the instructions here:
 https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
 ```
 
@@ -14,8 +14,8 @@ https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/do
 Run the interactive installer:
 
 ```bash
-bunx oh-my-opencode install # recommended
-npx oh-my-opencode install # alternative
+bunx oh-my-openagent install # recommended
+npx oh-my-openagent install # alternative
 ```
 
 > **Note**: The CLI ships with standalone binaries for all major platforms. No runtime (Bun/Node.js) is required for CLI execution after installation.
@@ -34,7 +34,7 @@ After you install it, you can read this [overview guide](./overview.md) to under
 > curl -fsSL https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
 > ```
 
-If you're an LLM Agent helping set up oh-my-opencode, Welcome! You'll now help your user to install the best agent harness, OhMyOpenCode. Tell user this with greetings, with test 'oMoMoMoMo...'
+If you're an LLM Agent helping set up oh-my-openagent, Welcome! You'll now help your user to install the best agent harness, OhMyOpenAgent. Tell user this with greetings, with test 'oMoMoMoMo...'
 
 follow these steps:
 
@@ -69,7 +69,7 @@ Ask the user these questions to determine CLI options:
    - If **no** → `--zai-coding-plan=no` (default)
 
 7. **Do you have an OpenCode Go subscription?**
-   - OpenCode Go is a $10/month subscription providing access to GLM-5, Kimi K2.5, and MiniMax M2.5 models
+   - OpenCode Go is a $10/month subscription providing access to GLM-5, Kimi K2.5, and MiniMax M2.7 models
    - If **yes** → `--opencode-go=yes`
    - If **no** → `--opencode-go=no` (default)
 
@@ -96,19 +96,19 @@ Spawn a subagent to handle installation and report back - to save context.
 Based on user's answers, run the CLI installer with appropriate flags:
 
 ```bash
-bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --gemini=<yes|no> --copilot=<yes|no> [--openai=<yes|no>] [--opencode-go=<yes|no>] [--opencode-zen=<yes|no>] [--zai-coding-plan=<yes|no>]
+bunx oh-my-openagent install --no-tui --claude=<yes|no|max20> --gemini=<yes|no> --copilot=<yes|no> [--openai=<yes|no>] [--opencode-go=<yes|no>] [--opencode-zen=<yes|no>] [--zai-coding-plan=<yes|no>]
 ```
 
 **Examples:**
 
-- User has all native subscriptions: `bunx oh-my-opencode install --no-tui --claude=max20 --openai=yes --gemini=yes --copilot=no`
-- User has only Claude: `bunx oh-my-opencode install --no-tui --claude=yes --gemini=no --copilot=no`
-- User has Claude + OpenAI: `bunx oh-my-opencode install --no-tui --claude=yes --openai=yes --gemini=no --copilot=no`
-- User has only GitHub Copilot: `bunx oh-my-opencode install --no-tui --claude=no --gemini=no --copilot=yes`
-- User has Z.ai for Librarian: `bunx oh-my-opencode install --no-tui --claude=yes --gemini=no --copilot=no --zai-coding-plan=yes`
-- User has only OpenCode Zen: `bunx oh-my-opencode install --no-tui --claude=no --gemini=no --copilot=no --opencode-zen=yes`
-- User has OpenCode Go only: `bunx oh-my-opencode install --no-tui --claude=no --openai=no --gemini=no --copilot=no --opencode-go=yes`
-- User has no subscriptions: `bunx oh-my-opencode install --no-tui --claude=no --gemini=no --copilot=no`
+- User has all native subscriptions: `bunx oh-my-openagent install --no-tui --claude=max20 --openai=yes --gemini=yes --copilot=no`
+- User has only Claude: `bunx oh-my-openagent install --no-tui --claude=yes --gemini=no --copilot=no`
+- User has Claude + OpenAI: `bunx oh-my-openagent install --no-tui --claude=yes --openai=yes --gemini=no --copilot=no`
+- User has only GitHub Copilot: `bunx oh-my-openagent install --no-tui --claude=no --gemini=no --copilot=yes`
+- User has Z.ai for Librarian: `bunx oh-my-openagent install --no-tui --claude=yes --gemini=no --copilot=no --zai-coding-plan=yes`
+- User has only OpenCode Zen: `bunx oh-my-openagent install --no-tui --claude=no --gemini=no --copilot=no --opencode-zen=yes`
+- User has OpenCode Go only: `bunx oh-my-openagent install --no-tui --claude=no --openai=no --gemini=no --copilot=no --opencode-go=yes`
+- User has no subscriptions: `bunx oh-my-openagent install --no-tui --claude=no --gemini=no --copilot=no`
 
 The CLI will:
 
@@ -120,7 +120,7 @@ The CLI will:
 
 ```bash
 opencode --version  # Should be 1.0.150 or higher
-cat ~/.config/opencode/opencode.json  # Should contain "oh-my-opencode" in plugin array
+cat ~/.config/opencode/opencode.json  # Should contain "oh-my-openagent" in plugin array
 ```
 
 ### Step 4: Configure Authentication
@@ -145,7 +145,7 @@ First, add the opencode-antigravity-auth plugin:
 
 ```json
 {
-  "plugin": ["oh-my-opencode", "opencode-antigravity-auth@latest"]
+  "plugin": ["oh-my-openagent", "opencode-antigravity-auth@latest"]
 }
 ```
 
@@ -154,9 +154,9 @@ First, add the opencode-antigravity-auth plugin:
 You'll also need full model settings in `opencode.json`.
 Read the [opencode-antigravity-auth documentation](https://github.com/NoeFabris/opencode-antigravity-auth), copy the full model configuration from the README, and merge carefully to avoid breaking the user's existing setup. The plugin now uses a **variant system** — models like `antigravity-gemini-3-pro` support `low`/`high` variants instead of separate `-low`/`-high` model entries.
 
-##### oh-my-opencode Agent Model Override
+##### oh-my-openagent Agent Model Override
 
-The `opencode-antigravity-auth` plugin uses different model names than the built-in Google auth. Override the agent models in `oh-my-opencode.json` (or `.opencode/oh-my-opencode.json`):
+The `opencode-antigravity-auth` plugin uses different model names than the built-in Google auth. Override the agent models in `oh-my-openagent.json` (or `.opencode/oh-my-openagent.json`):
 
 ```json
 {
@@ -176,7 +176,7 @@ The `opencode-antigravity-auth` plugin uses different model names than the built
 
 **Available models (Gemini CLI quota)**:
 
-- `google/gemini-2.5-flash`, `google/gemini-2.5-pro`, `google/gemini-3-flash-preview`, `google/gemini-3-pro-preview`
+- `google/gemini-2.5-flash`, `google/gemini-2.5-pro`, `google/gemini-3-flash-preview`, `google/gemini-3.1-pro-preview`
 
 > **Note**: Legacy tier-suffixed names like `google/antigravity-gemini-3-pro-high` still work but variants are recommended. Use `--variant=high` with the base model name instead.
 
@@ -201,11 +201,11 @@ GitHub Copilot is supported as a **fallback provider** when native providers are
 
 ##### Model Mappings
 
-When GitHub Copilot is the best available provider, oh-my-opencode uses these model assignments:
+When GitHub Copilot is the best available provider, oh-my-openagent uses these model assignments:
 
 | Agent         | Model                             |
 | ------------- | --------------------------------- |
-| **Sisyphus**  | `github-copilot/claude-opus-4-6`  |
+| **Sisyphus**  | `github-copilot/claude-opus-4.6`  |
 | **Oracle**    | `github-copilot/gpt-5.4`          |
 | **Explore**   | `github-copilot/grok-code-fast-1` |
 | **Librarian** | `github-copilot/gemini-3-flash`   |
@@ -227,7 +227,7 @@ If Z.ai is your main provider, the most important fallbacks are:
 
 #### OpenCode Zen
 
-OpenCode Zen provides access to `opencode/` prefixed models including `opencode/claude-opus-4-6`, `opencode/gpt-5.4`, `opencode/gpt-5.3-codex`, `opencode/gpt-5-nano`, `opencode/glm-5`, `opencode/big-pickle`, and `opencode/minimax-m2.5-free`.
+OpenCode Zen provides access to `opencode/` prefixed models including `opencode/claude-opus-4-6`, `opencode/gpt-5.4`, `opencode/gpt-5.3-codex`, `opencode/gpt-5-nano`, `opencode/glm-5`, `opencode/big-pickle`, and `opencode/minimax-m2.7-highspeed`.
 
 When OpenCode Zen is the best available provider (no native or Copilot), these models are used:
 
@@ -236,14 +236,14 @@ When OpenCode Zen is the best available provider (no native or Copilot), these m
 | **Sisyphus**  | `opencode/claude-opus-4-6`                           |
 | **Oracle**    | `opencode/gpt-5.4`                                   |
 | **Explore**   | `opencode/gpt-5-nano`                                |
-| **Librarian** | `opencode/minimax-m2.5-free` / `opencode/big-pickle` |
+| **Librarian** | `opencode/minimax-m2.7-highspeed` / `opencode/big-pickle` |
 
 ##### Setup
 
 Run the installer and select "Yes" for GitHub Copilot:
 
 ```bash
-bunx oh-my-opencode install
+bunx oh-my-openagent install
 # Select your subscriptions (Claude, ChatGPT, Gemini)
 # When prompted: "Do you have a GitHub Copilot subscription?" → Select "Yes"
 ```
@@ -251,7 +251,7 @@ bunx oh-my-opencode install
 Or use non-interactive mode:
 
 ```bash
-bunx oh-my-opencode install --no-tui --claude=no --openai=no --gemini=no --copilot=yes
+bunx oh-my-openagent install --no-tui --claude=no --openai=no --gemini=no --copilot=yes
 ```
 
 Then authenticate with GitHub:
@@ -263,7 +263,7 @@ opencode auth login
 
 ### Step 5: Understand Your Model Setup
 
-You've just configured oh-my-opencode. Here's what got set up and why.
+You've just configured oh-my-openagent. Here's what got set up and why.
 
 #### Model Families: What You're Working With
 
@@ -287,16 +287,17 @@ Not all models behave the same way. Understanding which models are "similar" hel
 | ----------------- | -------------------------------- | ------------------------------------------------- |
 | **GPT-5.3-codex** | openai, github-copilot, opencode | Deep coding powerhouse. Required for Hephaestus.  |
 | **GPT-5.4**       | openai, github-copilot, opencode | High intelligence. Default for Oracle.            |
+| **GPT-5.4 Mini**  | openai, github-copilot, opencode | Fast + strong reasoning. Default for quick category.     |
 | **GPT-5-Nano**    | opencode                         | Ultra-cheap, fast. Good for simple utility tasks. |
 
 **Different-Behavior Models**:
 
 | Model                 | Provider(s)                      | Notes                                                       |
 | --------------------- | -------------------------------- | ----------------------------------------------------------- |
-| **Gemini 3 Pro**      | google, github-copilot, opencode | Excels at visual/frontend tasks. Different reasoning style. |
+| **Gemini 3.1 Pro**    | google, github-copilot, opencode | Excels at visual/frontend tasks. Different reasoning style. |
 | **Gemini 3 Flash**    | google, github-copilot, opencode | Fast, good for doc search and light tasks.                  |
-| **MiniMax M2.5**      | venice                           | Fast and smart. Good for utility tasks.                     |
-| **MiniMax M2.5 Free** | opencode                         | Free-tier MiniMax. Fast for search/retrieval.               |
+| **MiniMax M2.7**      | venice, opencode-go              | Fast and smart. Good for utility tasks. Upgraded from M2.5. |
+| **MiniMax M2.7 Highspeed** | opencode                    | Ultra-fast MiniMax variant. Optimized for latency.          |
 
 **Speed-Focused Models**:
 
@@ -304,8 +305,8 @@ Not all models behave the same way. Understanding which models are "similar" hel
 | ----------------------- | ---------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Grok Code Fast 1**    | github-copilot, venice | Very fast      | Optimized for code grep/search. Default for Explore.                                                                                          |
 | **Claude Haiku 4.5**    | anthropic, opencode    | Fast           | Good balance of speed and intelligence.                                                                                                       |
-| **MiniMax M2.5 (Free)** | opencode, venice       | Fast           | Smart for its speed class.                                                                                                                    |
-| **GPT-5.3-codex-spark** | openai                 | Extremely fast | Blazing fast but compacts so aggressively that oh-my-opencode's context management doesn't work well with it. Not recommended for omo agents. |
+| **MiniMax M2.7 Highspeed** | opencode            | Very fast      | Ultra-fast MiniMax variant. Smart for its speed class.                                                                                        |
+| **GPT-5.3-codex-spark** | openai                 | Extremely fast | Blazing fast but compacts so aggressively that oh-my-openagent's context management doesn't work well with it. Not recommended for omo agents. |
 
 #### What Each Agent Does and Which Model It Got
 
@@ -316,7 +317,7 @@ Based on your subscriptions, here's how the agents were configured:
 | Agent        | Role             | Default Chain                                   | What It Does                                                                             |
 | ------------ | ---------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | **Sisyphus** | Main ultraworker | Opus (max) → Kimi K2.5 → GLM 5 → Big Pickle     | Primary coding agent. Orchestrates everything. **Never use GPT — no GPT prompt exists.** |
-| **Metis**    | Plan review      | Opus (max) → Kimi K2.5 → GPT-5.4 → Gemini 3 Pro | Reviews Prometheus plans for gaps.                                                       |
+| **Metis**    | Plan review      | Opus (max) → Kimi K2.5 → GPT-5.4 → Gemini 3.1 Pro | Reviews Prometheus plans for gaps.                                                       |
 
 **Dual-Prompt Agents** (auto-switch between Claude and GPT prompts):
 
@@ -326,7 +327,7 @@ Priority: **Claude > GPT > Claude-like models**
 
 | Agent          | Role              | Default Chain                                              | GPT Prompt?                                                      |
 | -------------- | ----------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- |
-| **Prometheus** | Strategic planner | Opus (max) → **GPT-5.4 (high)** → Kimi K2.5 → Gemini 3 Pro | Yes — XML-tagged, principle-driven (~300 lines vs ~1,100 Claude) |
+| **Prometheus** | Strategic planner | Opus (max) → **GPT-5.4 (high)** → Kimi K2.5 → Gemini 3.1 Pro | Yes — XML-tagged, principle-driven (~300 lines vs ~1,100 Claude) |
 | **Atlas**      | Todo orchestrator | **Kimi K2.5** → Sonnet → GPT-5.4                           | Yes — GPT-optimized todo management                              |
 
 **GPT-Native Agents** (built for GPT, don't override to Claude):
@@ -334,8 +335,8 @@ Priority: **Claude > GPT > Claude-like models**
 | Agent          | Role                   | Default Chain                          | Notes                                                  |
 | -------------- | ---------------------- | -------------------------------------- | ------------------------------------------------------ |
 | **Hephaestus** | Deep autonomous worker | GPT-5.3-codex (medium) only            | "Codex on steroids." No fallback. Requires GPT access. |
-| **Oracle**     | Architecture/debugging | GPT-5.4 (high) → Gemini 3 Pro → Opus   | High-IQ strategic backup. GPT preferred.               |
-| **Momus**      | High-accuracy reviewer | GPT-5.4 (medium) → Opus → Gemini 3 Pro | Verification agent. GPT preferred.                     |
+| **Oracle**     | Architecture/debugging | GPT-5.4 (high) → Gemini 3.1 Pro → Opus  | High-IQ strategic backup. GPT preferred.               |
+| **Momus**      | High-accuracy reviewer | GPT-5.4 (medium) → Opus → Gemini 3.1 Pro | Verification agent. GPT preferred.                     |
 
 **Utility Agents** (speed over intelligence):
 
@@ -343,8 +344,8 @@ These agents do search, grep, and retrieval. They intentionally use fast, cheap
 
 | Agent                 | Role               | Default Chain                                                          | Design Rationale                                               |
 | --------------------- | ------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
-| **Explore**           | Fast codebase grep | MiniMax M2.5 Free → Grok Code Fast → MiniMax M2.5 → Haiku → GPT-5-Nano | Speed is everything. Grok is blazing fast for grep.            |
-| **Librarian**         | Docs/code search   | MiniMax M2.5 Free → Gemini Flash → Big Pickle                          | Entirely free-tier. Doc retrieval doesn't need deep reasoning. |
+| **Explore**           | Fast codebase grep | Grok Code Fast → MiniMax M2.7-highspeed → MiniMax M2.7 → Haiku → GPT-5-Nano | Speed is everything. Grok is blazing fast for grep.            |
+| **Librarian**         | Docs/code search   | MiniMax M2.7 → MiniMax M2.7-highspeed → Haiku → GPT-5-Nano                   | Doc retrieval doesn't need deep reasoning. MiniMax is fast.    |
 | **Multimodal Looker** | Vision/screenshots | Kimi K2.5 → Kimi Free → Gemini Flash → GPT-5.4 → GLM-4.6v              | Kimi excels at multimodal understanding.                       |
 
 #### Why Different Models Need Different Prompts
@@ -364,7 +365,7 @@ This is why Prometheus and Atlas ship separate prompts per model family — they
 
 #### Custom Model Configuration
 
-If the user wants to override which model an agent uses, you can customize in `oh-my-opencode.json`:
+If the user wants to override which model an agent uses, you can customize in `oh-my-openagent.json`:
 
 ```jsonc
 {
@@ -406,7 +407,7 @@ GPT (5.3-codex, 5.2) > Claude Opus (decent fallback) > Gemini (acceptable)
 
 #### Provider Priority Chain
 
-When multiple providers are available, oh-my-opencode uses this priority:
+When multiple providers are available, oh-my-openagent uses this priority:
 
 ```
 Native (anthropic/, openai/, google/) > Kimi for Coding > GitHub Copilot > Venice > OpenCode Zen > Z.ai Coding Plan
@@ -424,7 +425,7 @@ Read this document again, think about you have done everything correctly.
 
 #### Say 'Congratulations! 🎉' to the user
 
-Say to user: Congratulations! 🎉 You have successfully set up OhMyOpenCode! Type `opencode` in your terminal to start using it.
+Say to user: Congratulations! 🎉 You have successfully set up OhMyOpenAgent! Type `opencode` in your terminal to start using it.
 
 #### Free advertising
 

docs/guide/orchestration.md

@@ -1,6 +1,6 @@
 # Orchestration System Guide
 
-Oh My OpenCode's orchestration system transforms a simple AI agent into a coordinated development team through **separation of planning and execution**.
+Oh My OpenAgent's orchestration system transforms a simple AI agent into a coordinated development team through **separation of planning and execution**.
 
 ---
 
@@ -298,7 +298,7 @@ task({ category: "quick", prompt: "..." }); // "Just get it done fast"
 | `visual-engineering` | Gemini 3.1 Pro         | Frontend, UI/UX, design, styling, animation                 |
 | `ultrabrain`         | GPT-5.4 (xhigh)        | Deep logical reasoning, complex architecture decisions      |
 | `artistry`           | Gemini 3.1 Pro (high)  | Highly creative or artistic tasks, novel ideas              |
-| `quick`              | Claude Haiku 4.5       | Trivial tasks - single file changes, typo fixes             |
+| `quick`              | GPT-5.4 Mini           | Trivial tasks - single file changes, typo fixes             |
 | `deep`               | GPT-5.3 Codex (medium) | Goal-oriented autonomous problem-solving, thorough research |
 | `unspecified-low`    | Claude Sonnet 4.6      | Tasks that don't fit other categories, low effort           |
 | `unspecified-high`   | Claude Opus 4.6 (max)  | Tasks that don't fit other categories, high effort          |
@@ -475,7 +475,7 @@ Use the `ulw` keyword in Sisyphus when:
 
 ## Configuration
 
-You can control related features in `oh-my-opencode.json`:
+You can control related features in `oh-my-openagent.json`:
 
 ```jsonc
 {

docs/guide/overview.md

@@ -1,6 +1,6 @@
-# What Is Oh My OpenCode?
+# What Is Oh My OpenAgent?
 
-Oh My OpenCode is a multi-model agent orchestration harness for OpenCode. It transforms a single AI agent into a coordinated development team that actually ships code.
+Oh My OpenAgent is a multi-model agent orchestration harness for OpenCode. It transforms a single AI agent into a coordinated development team that actually ships code.
 
 Not locked to Claude. Not locked to OpenAI. Not locked to anyone.
 
@@ -15,7 +15,7 @@ Just better results, cheaper models, real orchestration.
 Paste this into your LLM agent session:
 
 ```
-Install and configure oh-my-opencode by following the instructions here:
+Install and configure oh-my-openagent by following the instructions here:
 https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
 ```
 
@@ -41,13 +41,13 @@ We used to call this "Claude Code on steroids." That was wrong.
 
 This isn't about making Claude Code better. It's about breaking free from the idea that one model, one provider, one way of working is enough. Anthropic wants you locked in. OpenAI wants you locked in. Everyone wants you locked in.
 
-Oh My OpenCode doesn't play that game. It orchestrates across models, picking the right brain for the right job. Claude for orchestration. GPT for deep reasoning. Gemini for frontend. Haiku for quick tasks. All working together, automatically.
+Oh My OpenAgent doesn't play that game. It orchestrates across models, picking the right brain for the right job. Claude for orchestration. GPT for deep reasoning. Gemini for frontend. GPT-5.4 Mini for quick tasks. All working together, automatically.
 
 ---
 
 ## How It Works: Agent Orchestration
 
-Instead of one agent doing everything, Oh My OpenCode uses **specialized agents that delegate to each other** based on task type.
+Instead of one agent doing everything, Oh My OpenAgent uses **specialized agents that delegate to each other** based on task type.
 
 **The Architecture:**
 
@@ -99,9 +99,9 @@ Use Hephaestus when you need deep architectural reasoning, complex debugging acr
 
 **Why this beats vanilla Codex CLI:**
 
-- **Multi-model orchestration.** Pure Codex is single-model. OmO routes different tasks to different models automatically. GPT for deep reasoning. Gemini for frontend. Haiku for speed. The right brain for the right job.
+- **Multi-model orchestration.** Pure Codex is single-model. OmO routes different tasks to different models automatically. GPT for deep reasoning. Gemini for frontend. GPT-5.4 Mini for speed. The right brain for the right job.
 - **Background agents.** Fire 5+ agents in parallel. Something Codex simply cannot do. While one agent writes code, another researches patterns, another checks documentation. Like a real dev team.
-- **Category system.** Tasks are routed by intent, not model name. `visual-engineering` gets Gemini. `ultrabrain` gets GPT-5.4. `quick` gets Haiku. No manual juggling.
+- **Category system.** Tasks are routed by intent, not model name. `visual-engineering` gets Gemini. `ultrabrain` gets GPT-5.4. `quick` gets GPT-5.4 Mini. No manual juggling.
 - **Accumulated wisdom.** Subagents learn from previous results. Conventions discovered in task 1 are passed to task 5. Mistakes made early aren't repeated. The system gets smarter as it works.
 
 ### Prometheus: The Strategic Planner
@@ -154,7 +154,7 @@ Use Prometheus for multi-day projects, critical production changes, complex refa
 
 ## Agent Model Matching
 
-Different agents work best with different models. Oh My OpenCode automatically assigns optimal models, but you can customize everything.
+Different agents work best with different models. Oh My OpenAgent automatically assigns optimal models, but you can customize everything.
 
 ### Default Configuration
 
@@ -168,7 +168,7 @@ You can override specific agents or categories in your config:
 
 ```jsonc
 {
-  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
 
   "agents": {
     // Main orchestrator: Claude Opus or Kimi K2.5 work best
@@ -195,8 +195,8 @@ You can override specific agents or categories in your config:
     // General high-effort work
     "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
 
-    // Quick tasks: use the cheapest models
-    "quick": { "model": "anthropic/claude-haiku-4-5" },
+    // Quick tasks: use GPT-5.4-mini (fast and cheap)
+    "quick": { "model": "openai/gpt-5.4-mini" },
 
     // Deep reasoning: GPT-5.4
     "ultrabrain": { "model": "openai/gpt-5.4", "variant": "xhigh" },
@@ -220,8 +220,8 @@ You can override specific agents or categories in your config:
 
 **Different-behavior models**:
 
-- Gemini 3 Pro — excels at visual/frontend tasks
-- MiniMax M2.5 — fast and smart for utility tasks
+- Gemini 3.1 Pro — excels at visual/frontend tasks
+- MiniMax M2.7 / M2.7-highspeed — fast and smart for utility tasks
 - Grok Code Fast 1 — optimized for code grep/search
 
 See the [Agent-Model Matching Guide](./agent-model-matching.md) for complete details on which models work best for each agent, safe vs dangerous overrides, and provider priority chains.
@@ -232,7 +232,7 @@ See the [Agent-Model Matching Guide](./agent-model-matching.md) for complete det
 
 Claude Code is good. But it's a single agent running a single model doing everything alone.
 
-Oh My OpenCode turns that into a coordinated team:
+Oh My OpenAgent turns that into a coordinated team:
 
 **Parallel execution.** Claude Code processes one thing at a time. OmO fires background agents in parallel — research, implementation, and verification happening simultaneously. Like having 5 engineers instead of 1.
 
@@ -246,7 +246,7 @@ Oh My OpenCode turns that into a coordinated team:
 
 **Discipline enforcement.** Todo enforcer yanks idle agents back to work. Comment checker strips AI slop. Ralph Loop keeps going until 100% done. The system doesn't let the agent slack off.
 
-**The fundamental advantage.** Models have different temperaments. Claude thinks deeply. GPT reasons architecturally. Gemini visualizes. Haiku moves fast. Single-model tools force you to pick one personality for all tasks. Oh My OpenCode leverages them all, routing by task type. This isn't a temporary hack — it's the only architecture that makes sense as models specialize further. The gap between multi-model orchestration and single-model limitation widens every month. We're betting on that future.
+**The fundamental advantage.** Models have different temperaments. Claude thinks deeply. GPT reasons architecturally. Gemini visualizes. Haiku moves fast. Single-model tools force you to pick one personality for all tasks. Oh My OpenAgent leverages them all, routing by task type. This isn't a temporary hack — it's the only architecture that makes sense as models specialize further. The gap between multi-model orchestration and single-model limitation widens every month. We're betting on that future.
 
 ---
 
@@ -256,7 +256,7 @@ Before acting on any request, Sisyphus classifies your true intent.
 
 Are you asking for research? Implementation? Investigation? A fix? The Intent Gate figures out what you actually want, not just the literal words you typed. This means the agent understands context, nuance, and the real goal behind your request.
 
-Claude Code doesn't have this. It takes your prompt and runs. Oh My OpenCode thinks first, then acts.
+Claude Code doesn't have this. It takes your prompt and runs. Oh My OpenAgent thinks first, then acts.
 
 ---
 

docs/manifesto.md

@@ -1,6 +1,6 @@
 # Manifesto
 
-The principles and philosophy behind Oh My OpenCode.
+The principles and philosophy behind Oh My OpenAgent.
 
 ---
 
@@ -20,7 +20,7 @@ When you find yourself:
 
 That's not "human-AI collaboration." That's the AI failing to do its job.
 
-**Oh My OpenCode is built on this premise**: Human intervention during agentic work is fundamentally a wrong signal. If the system is designed correctly, the agent should complete the work without requiring you to babysit it.
+**Oh My OpenAgent is built on this premise**: Human intervention during agentic work is fundamentally a wrong signal. If the system is designed correctly, the agent should complete the work without requiring you to babysit it.
 
 ---
 
@@ -144,7 +144,7 @@ Human Intent → Agent Execution → Verified Result
           (intervention only on true failure)
 ```
 
-Everything in Oh My OpenCode is designed to make this loop work:
+Everything in Oh My OpenAgent is designed to make this loop work:
 
 | Feature | Purpose |
 |---------|---------|

docs/model-capabilities-maintenance.md

@@ -0,0 +1,33 @@
+# Model Capabilities Maintenance
+
+This project treats model capability resolution as a layered system:
+
+1. runtime metadata from connected providers
+2. `models.dev` bundled/runtime snapshot data
+3. explicit compatibility aliases
+4. heuristic fallback as the last resort
+
+## Internal policy
+
+- Built-in OmO agent/category requirement models must use canonical model IDs.
+- Aliases exist only to preserve compatibility with historical OmO names or provider-specific decorations.
+- New decorated names like `-high`, `-low`, or `-thinking` should not be added to built-in requirements when a canonical model ID plus structured settings can express the same thing.
+- If a provider or config input still uses an alias, normalize it at the edge and continue internally with the canonical ID.
+
+## When adding an alias
+
+- Add the alias rule to `src/shared/model-capability-aliases.ts`.
+- Include a rationale for why the alias exists.
+- Add or update tests so the alias is covered explicitly.
+- Ensure the alias canonical target exists in the bundled `models.dev` snapshot.
+
+## Guardrails
+
+`bun run test:model-capabilities` enforces the following invariants:
+
+- exact alias targets must exist in the bundled snapshot
+- exact alias keys must not silently become canonical `models.dev` IDs
+- pattern aliases must not rewrite canonical snapshot IDs
+- built-in requirement models must stay canonical and snapshot-backed
+
+The scheduled `refresh-model-capabilities` workflow runs these guardrails before opening an automated snapshot refresh PR.

docs/reference/cli.md

@@ -1,15 +1,15 @@
 # CLI Reference
 
-Complete reference for the `oh-my-opencode` command-line interface.
+Complete reference for the `oh-my-openagent` command-line interface.
 
 ## Basic Usage
 
 ```bash
 # Display help
-bunx oh-my-opencode
+bunx oh-my-openagent
 
 # Or with npx
-npx oh-my-opencode
+npx oh-my-openagent
 ```
 
 ## Commands
@@ -27,20 +27,20 @@ npx oh-my-opencode
 
 ## install
 
-Interactive installation tool for initial Oh-My-OpenCode setup. Provides a TUI based on `@clack/prompts`.
+Interactive installation tool for initial Oh-My-OpenAgent setup. Provides a TUI based on `@clack/prompts`.
 
 ### Usage
 
 ```bash
-bunx oh-my-opencode install
+bunx oh-my-openagent install
 ```
 
 ### Installation Process
 
 1. **Provider Selection**: Choose your AI provider (Claude, ChatGPT, or Gemini)
 2. **API Key Input**: Enter the API key for your selected provider
-3. **Configuration File Creation**: Generates `opencode.json` or `oh-my-opencode.json` files
-4. **Plugin Registration**: Automatically registers the oh-my-opencode plugin in OpenCode settings
+3. **Configuration File Creation**: Generates `opencode.json` or `oh-my-openagent.json` files
+4. **Plugin Registration**: Automatically registers the oh-my-openagent plugin in OpenCode settings
 
 ### Options
 
@@ -53,12 +53,12 @@ bunx oh-my-opencode install
 
 ## doctor
 
-Diagnoses your environment to ensure Oh-My-OpenCode is functioning correctly. Performs 17+ health checks.
+Diagnoses your environment to ensure Oh-My-OpenAgent is functioning correctly. Performs 17+ health checks.
 
 ### Usage
 
 ```bash
-bunx oh-my-opencode doctor
+bunx oh-my-openagent doctor
 ```
 
 ### Diagnostic Categories
@@ -83,10 +83,10 @@ bunx oh-my-opencode doctor
 ### Example Output
 
 ```
-oh-my-opencode doctor
+oh-my-openagent doctor
 
 ┌──────────────────────────────────────────────────┐
-│  Oh-My-OpenCode Doctor                           │
+│  Oh-My-OpenAgent Doctor                           │
 └──────────────────────────────────────────────────┘
 
 Installation
@@ -94,7 +94,7 @@ Installation
   ✓ Plugin registered in opencode.json
 
 Configuration
-  ✓ oh-my-opencode.json is valid
+  ✓ oh-my-openagent.json is valid
   ⚠ categories.visual-engineering: using default model
 
 Authentication
@@ -119,7 +119,7 @@ Executes OpenCode sessions and monitors task completion.
 ### Usage
 
 ```bash
-bunx oh-my-opencode run [prompt]
+bunx oh-my-openagent run [prompt]
 ```
 
 ### Options
@@ -148,16 +148,16 @@ Manages OAuth 2.1 authentication for remote MCP servers.
 
 ```bash
 # Login to an OAuth-protected MCP server
-bunx oh-my-opencode mcp oauth login <server-name> --server-url https://api.example.com
+bunx oh-my-openagent mcp oauth login <server-name> --server-url https://api.example.com
 
 # Login with explicit client ID and scopes
-bunx oh-my-opencode mcp oauth login my-api --server-url https://api.example.com --client-id my-client --scopes "read,write"
+bunx oh-my-openagent mcp oauth login my-api --server-url https://api.example.com --client-id my-client --scopes "read,write"
 
 # Remove stored OAuth tokens
-bunx oh-my-opencode mcp oauth logout <server-name>
+bunx oh-my-openagent mcp oauth logout <server-name>
 
 # Check OAuth token status
-bunx oh-my-opencode mcp oauth status [server-name]
+bunx oh-my-openagent mcp oauth status [server-name]
 ```
 
 ### Options
@@ -178,8 +178,8 @@ Tokens are stored in `~/.config/opencode/mcp-oauth.json` with `0600` permissions
 
 The CLI searches for configuration files in the following locations (in priority order):
 
-1. **Project Level**: `.opencode/oh-my-opencode.json`
-2. **User Level**: `~/.config/opencode/oh-my-opencode.json`
+1. **Project Level**: `.opencode/oh-my-openagent.json`
+2. **User Level**: `~/.config/opencode/oh-my-openagent.json`
 
 ### JSONC Support
 
@@ -219,17 +219,17 @@ bun install -g opencode@latest
 
 ```bash
 # Reinstall plugin
-bunx oh-my-opencode install
+bunx oh-my-openagent install
 ```
 
 ### Doctor Check Failures
 
 ```bash
 # Diagnose with detailed information
-bunx oh-my-opencode doctor --verbose
+bunx oh-my-openagent doctor --verbose
 
 # Check specific category only
-bunx oh-my-opencode doctor --category authentication
+bunx oh-my-openagent doctor --category authentication
 ```
 
 ---
@@ -240,10 +240,10 @@ Use the `--no-tui` option for CI/CD environments.
 
 ```bash
 # Run doctor in CI environment
-bunx oh-my-opencode doctor --no-tui --json
+bunx oh-my-openagent doctor --no-tui --json
 
 # Save results to file
-bunx oh-my-opencode doctor --json > doctor-report.json
+bunx oh-my-openagent doctor --json > doctor-report.json
 ```
 
 ---

docs/reference/configuration.md

@@ -1,6 +1,6 @@
 # Configuration Reference
 
-Complete reference for `oh-my-opencode.jsonc` configuration. This document covers every available option with examples.
+Complete reference for `oh-my-openagent.jsonc` configuration. This document covers every available option with examples.
 
 ---
 
@@ -44,13 +44,13 @@ Complete reference for `oh-my-opencode.jsonc` configuration. This document cover
 
 Priority order (project overrides user):
 
-1. `.opencode/oh-my-opencode.jsonc` / `.opencode/oh-my-opencode.json`
+1. `.opencode/oh-my-openagent.jsonc` / `.opencode/oh-my-openagent.json`
 2. User config (`.jsonc` preferred over `.json`):
 
 | Platform    | Path                                      |
 | ----------- | ----------------------------------------- |
-| macOS/Linux | `~/.config/opencode/oh-my-opencode.jsonc` |
-| Windows     | `%APPDATA%\opencode\oh-my-opencode.jsonc` |
+| macOS/Linux | `~/.config/opencode/oh-my-openagent.jsonc` |
+| Windows     | `%APPDATA%\opencode\oh-my-openagent.jsonc` |
 
 JSONC supports `// line comments`, `/* block comments */`, and trailing commas.
 
@@ -58,11 +58,11 @@ Enable schema autocomplete:
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json"
+  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json"
 }
 ```
 
-Run `bunx oh-my-opencode install` for guided setup. Run `opencode models` to list available models.
+Run `bunx oh-my-openagent install` for guided setup. Run `opencode models` to list available models.
 
 ### Quick Start Example
 
@@ -70,7 +70,7 @@ Here's a practical starting configuration:
 
 ```jsonc
 {
-  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
+  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
 
   "agents": {
     // Main orchestrator: Claude Opus or Kimi K2.5 work best
@@ -228,7 +228,7 @@ Domain-specific model delegation used by the `task()` tool. When Sisyphus delega
 | `ultrabrain`         | `openai/gpt-5.4` (xhigh)        | Deep logical reasoning, complex architecture   |
 | `deep`               | `openai/gpt-5.3-codex` (medium) | Autonomous problem-solving, thorough research  |
 | `artistry`           | `google/gemini-3.1-pro` (high)  | Creative/unconventional approaches             |
-| `quick`              | `anthropic/claude-haiku-4-5`    | Trivial tasks, typo fixes, single-file changes |
+| `quick`              | `openai/gpt-5.4-mini`           | Trivial tasks, typo fixes, single-file changes |
 | `unspecified-low`    | `anthropic/claude-sonnet-4-6`   | General tasks, low effort                      |
 | `unspecified-high`   | `anthropic/claude-opus-4-6` (max) | General tasks, high effort                   |
 | `writing`            | `google/gemini-3-flash`         | Documentation, prose, technical writing        |
@@ -270,8 +270,8 @@ Disable categories: `{ "disabled_categories": ["ultrabrain"] }`
 | **Sisyphus**          | `claude-opus-4-6`   | `claude-opus-4-6` → `glm-5` → `big-pickle`                                   |
 | **Hephaestus**        | `gpt-5.3-codex`     | `gpt-5.3-codex` → `gpt-5.4` (GitHub Copilot fallback)                        |
 | **oracle**            | `gpt-5.4`           | `gpt-5.4` → `gemini-3.1-pro` → `claude-opus-4-6`                             |
-| **librarian**         | `gemini-3-flash`    | `gemini-3-flash` → `minimax-m2.5-free` → `big-pickle`                        |
-| **explore**           | `grok-code-fast-1`  | `grok-code-fast-1` → `minimax-m2.5-free` → `claude-haiku-4-5` → `gpt-5-nano` |
+| **librarian**         | `minimax-m2.7`      | `minimax-m2.7` → `minimax-m2.7-highspeed` → `claude-haiku-4-5` → `gpt-5-nano` |
+| **explore**           | `grok-code-fast-1`  | `grok-code-fast-1` → `minimax-m2.7-highspeed` → `minimax-m2.7` → `claude-haiku-4-5` → `gpt-5-nano` |
 | **multimodal-looker** | `gpt-5.3-codex`     | `gpt-5.3-codex` → `k2p5` → `gemini-3-flash` → `glm-4.6v` → `gpt-5-nano`      |
 | **Prometheus**        | `claude-opus-4-6`   | `claude-opus-4-6` → `gpt-5.4` → `gemini-3.1-pro`                             |
 | **Metis**             | `claude-opus-4-6`   | `claude-opus-4-6` → `gpt-5.4` → `gemini-3.1-pro`                             |
@@ -286,12 +286,12 @@ Disable categories: `{ "disabled_categories": ["ultrabrain"] }`
 | **ultrabrain**         | `gpt-5.4`           | `gpt-5.4` → `gemini-3.1-pro` → `claude-opus-4-6`               |
 | **deep**               | `gpt-5.3-codex`     | `gpt-5.3-codex` → `claude-opus-4-6` → `gemini-3.1-pro`         |
 | **artistry**           | `gemini-3.1-pro`    | `gemini-3.1-pro` → `claude-opus-4-6` → `gpt-5.4`               |
-| **quick**              | `claude-haiku-4-5`  | `claude-haiku-4-5` → `gemini-3-flash` → `gpt-5-nano`           |
-| **unspecified-low**    | `claude-sonnet-4-6` | `claude-sonnet-4-6` → `gpt-5.3-codex` → `gemini-3-flash`       |
+| **quick**              | `gpt-5.4-mini`    | `gpt-5.4-mini` → `claude-haiku-4-5` → `gemini-3-flash` → `minimax-m2.7` → `gpt-5-nano` |
+| **unspecified-low**    | `claude-sonnet-4-6` | `claude-sonnet-4-6` → `gpt-5.3-codex` → `gemini-3-flash` → `minimax-m2.7` |
 | **unspecified-high**   | `claude-opus-4-6`   | `claude-opus-4-6` → `gpt-5.4 (high)` → `glm-5` → `k2p5` → `kimi-k2.5` |
-| **writing**            | `gemini-3-flash`    | `gemini-3-flash` → `claude-sonnet-4-6`                         |
+| **writing**            | `gemini-3-flash`    | `gemini-3-flash` → `claude-sonnet-4-6` → `minimax-m2.7`        |
 
-Run `bunx oh-my-opencode doctor --verbose` to see effective model resolution for your config.
+Run `bunx oh-my-openagent doctor --verbose` to see effective model resolution for your config.
 
 ---
 
@@ -418,15 +418,14 @@ Disable built-in skills: `{ "disabled_skills": ["playwright"] }`
 Disable built-in hooks via `disabled_hooks`:
 
 ```json
-{ "disabled_hooks": ["comment-checker", "gpt-permission-continuation"] }
+{ "disabled_hooks": ["comment-checker"] }
 ```
 
-Available hooks: `gpt-permission-continuation`, `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`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`, `auto-slash-command`, `sisyphus-junior-notepad`, `no-sisyphus-gpt`, `start-work`, `runtime-fallback`
+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`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`, `auto-slash-command`, `sisyphus-junior-notepad`, `no-sisyphus-gpt`, `start-work`, `runtime-fallback`
 
 **Notes:**
 
 - `directory-agents-injector` — auto-disabled on OpenCode 1.1.37+ (native AGENTS.md support)
-- `gpt-permission-continuation` — resumes GPT sessions only when the last assistant reply ends with a permission-seeking tail like `If you want, ...`. Disable it if you prefer GPT sessions to wait for explicit user follow-up.
 - `no-sisyphus-gpt` — **do not disable**. It blocks incompatible GPT models for Sisyphus while allowing the dedicated GPT-5.4 prompt path.
 - `startup-toast` is a sub-feature of `auto-update-checker`. Disable just the toast by adding `startup-toast` to `disabled_hooks`.
 

docs/reference/features.md

@@ -1,8 +1,8 @@
-# Oh-My-OpenCode Features Reference
+# Oh-My-OpenAgent Features Reference
 
 ## Agents
 
-Oh-My-OpenCode provides 11 specialized AI agents. Each has distinct expertise, optimized models, and tool permissions.
+Oh-My-OpenAgent provides 11 specialized AI agents. Each has distinct expertise, optimized models, and tool permissions.
 
 ### Core Agents
 
@@ -11,8 +11,8 @@ Oh-My-OpenCode provides 11 specialized AI agents. Each has distinct expertise, o
 | **Sisyphus**          | `claude-opus-4-6`  | The default orchestrator. Plans, delegates, and executes complex tasks using specialized subagents with aggressive parallel execution. Todo-driven workflow with extended thinking (32k budget). Fallback: `glm-5` → `big-pickle`.                                                                                                                               |
 | **Hephaestus**        | `gpt-5.3-codex`    | The Legitimate Craftsman. Autonomous deep worker inspired by AmpCode's deep mode. Goal-oriented execution with thorough research before action. Explores codebase patterns, completes tasks end-to-end without premature stopping. Named after the Greek god of forge and craftsmanship. Fallback: `gpt-5.4` on GitHub Copilot. Requires a GPT-capable provider. |
 | **Oracle**            | `gpt-5.4`          | Architecture decisions, code review, debugging. Read-only consultation with stellar logical reasoning and deep analysis. Inspired by AmpCode. Fallback: `gemini-3.1-pro` → `claude-opus-4-6`.                                                                                                                                                                    |
-| **Librarian**         | `gemini-3-flash`   | Multi-repo analysis, documentation lookup, OSS implementation examples. Deep codebase understanding with evidence-based answers. Fallback: `minimax-m2.5-free` → `big-pickle`.                                                                                                                                                                                   |
-| **Explore**           | `grok-code-fast-1` | Fast codebase exploration and contextual grep. Fallback: `minimax-m2.5-free` → `claude-haiku-4-5` → `gpt-5-nano`.                                                                                                                                                                                                                                                |
+| **Librarian**         | `minimax-m2.7`     | Multi-repo analysis, documentation lookup, OSS implementation examples. Deep codebase understanding with evidence-based answers. Fallback: `minimax-m2.7-highspeed` → `claude-haiku-4-5` → `gpt-5-nano`.                                                                                                                                                         |
+| **Explore**           | `grok-code-fast-1` | Fast codebase exploration and contextual grep. Fallback: `minimax-m2.7-highspeed` → `minimax-m2.7` → `claude-haiku-4-5` → `gpt-5-nano`.                                                                                                                                                                                                                          |
 | **Multimodal-Looker** | `gpt-5.3-codex`    | Visual content specialist. Analyzes PDFs, images, diagrams to extract information. Fallback: `k2p5` → `gemini-3-flash` → `glm-4.6v` → `gpt-5-nano`.                                                                                                                                                                                                              |
 
 ### Planning Agents
@@ -90,7 +90,7 @@ When running inside tmux:
 - Each pane shows agent output live
 - Auto-cleanup when agents complete
 
-Customize agent models, prompts, and permissions in `oh-my-opencode.json`.
+Customize agent models, prompts, and permissions in `oh-my-openagent.json`.
 
 ## Category System
 
@@ -111,7 +111,7 @@ By combining these two concepts, you can generate optimal agents through `task`.
 | `ultrabrain`         | `openai/gpt-5.4` (xhigh)        | Deep logical reasoning, complex architecture decisions requiring extensive analysis                                         |
 | `deep`               | `openai/gpt-5.3-codex` (medium) | Goal-oriented autonomous problem-solving. Thorough research before action. For hairy problems requiring deep understanding. |
 | `artistry`           | `google/gemini-3.1-pro` (high)  | Highly creative/artistic tasks, novel ideas                                                                                 |
-| `quick`              | `anthropic/claude-haiku-4-5`    | Trivial tasks - single file changes, typo fixes, simple modifications                                                       |
+| `quick`              | `openai/gpt-5.4-mini`           | Trivial tasks - single file changes, typo fixes, simple modifications                                                       |
 | `unspecified-low`    | `anthropic/claude-sonnet-4-6`   | Tasks that don't fit other categories, low effort required                                                                  |
 | `unspecified-high`   | `anthropic/claude-opus-4-6` (max) | Tasks that don't fit other categories, high effort required                                                               |
 | `writing`            | `google/gemini-3-flash`         | Documentation, prose, technical writing                                                                                     |
@@ -129,7 +129,7 @@ task({
 
 ### Custom Categories
 
-You can define custom categories in `oh-my-opencode.json`.
+You can define custom categories in `oh-my-openagent.json`.
 
 #### Category Configuration Schema
 
@@ -237,7 +237,7 @@ Skills provide specialized workflows with embedded MCP servers and detailed inst
 
 ### Browser Automation Options
 
-Oh-My-OpenCode provides two browser automation providers, configurable via `browser_automation_engine.provider`.
+Oh-My-OpenAgent provides two browser automation providers, configurable via `browser_automation_engine.provider`.
 
 #### Option 1: Playwright MCP (Default)
 
@@ -558,7 +558,7 @@ Requires `experimental.task_system: true` in config.
 
 #### Task System Details
 
-**Note on Claude Code Alignment**: This implementation follows Claude Code's internal Task tool signatures (`TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`) and field naming conventions (`subject`, `blockedBy`, `blocks`, etc.). However, Anthropic has not published official documentation for these tools. This is Oh My OpenCode's own implementation based on observed Claude Code behavior and internal specifications.
+**Note on Claude Code Alignment**: This implementation follows Claude Code's internal Task tool signatures (`TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`) and field naming conventions (`subject`, `blockedBy`, `blocks`, etc.). However, Anthropic has not published official documentation for these tools. This is Oh My OpenAgent's own implementation based on observed Claude Code behavior and internal specifications.
 
 **Task Schema**:
 
@@ -680,7 +680,6 @@ Hooks intercept and modify behavior at key points in the agent lifecycle across
 | **ralph-loop**              | Event + Message     | Manages self-referential loop continuation.                                                                                                                 |
 | **start-work**              | Message             | Handles /start-work command execution.                                                                                                                      |
 | **auto-slash-command**      | Message             | Automatically executes slash commands from prompts.                                                                                                         |
-| **gpt-permission-continuation** | Event           | Auto-continues GPT sessions when the final assistant reply ends with a permission-seeking tail such as `If you want, ...`.                               |
 | **stop-continuation-guard** | Event + Message     | Guards the stop-continuation mechanism.                                                                                                                     |
 | **category-skill-reminder** | Event + PostToolUse | Reminds agents about available category skills for delegation.                                                                                              |
 | **anthropic-effort**        | Params              | Adjusts Anthropic API effort level based on context.                                                                                                        |
@@ -735,7 +734,6 @@ Hooks intercept and modify behavior at key points in the agent lifecycle across
 
 | Hook                           | Event | Description                                                |
 | ------------------------------ | ----- | ---------------------------------------------------------- |
-| **gpt-permission-continuation** | Event | Continues GPT replies that end in a permission-seeking tail. |
 | **todo-continuation-enforcer** | Event | Enforces todo completion — yanks idle agents back to work. |
 | **compaction-todo-preserver**  | Event | Preserves todo state during session compaction.            |
 | **unstable-agent-babysitter**  | Event | Handles unstable agent behavior with recovery strategies.  |
@@ -787,12 +785,10 @@ Disable specific hooks in config:
 
 ```json
 {
-  "disabled_hooks": ["comment-checker", "gpt-permission-continuation"]
+  "disabled_hooks": ["comment-checker"]
 }
 ```
 
-Use `gpt-permission-continuation` when you want GPT sessions to stop at permission-seeking endings instead of auto-resuming.
-
 ## MCPs
 
 ### Built-in MCPs
@@ -848,7 +844,7 @@ When a skill MCP has `oauth` configured:
 Pre-authenticate via CLI:
 
 ```bash
-bunx oh-my-opencode mcp oauth login <server-name> --server-url https://api.example.com
+bunx oh-my-openagent mcp oauth login <server-name> --server-url https://api.example.com
 ```
 
 ## Context Injection

docs/superpowers/plans/2026-03-17-model-settings-compatibility-resolver.md

@@ -0,0 +1,86 @@
+# Model Settings Compatibility Resolver Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Centralize compatibility handling for `variant` and `reasoningEffort` so an already-selected model receives the best valid settings for that exact model.
+
+**Architecture:** Introduce a pure shared resolver in `src/shared/` that computes compatible settings and records downgrades/removals. Integrate it first in `chat.params`, then keep Claude-specific effort logic as a thin layer rather than a special-case policy owner.
+
+**Tech Stack:** TypeScript, Bun test, existing shared model normalization/utilities, OpenCode plugin `chat.params` path.
+
+---
+
+### Task 1: Create the pure compatibility resolver
+
+**Files:**
+- Create: `src/shared/model-settings-compatibility.ts`
+- Create: `src/shared/model-settings-compatibility.test.ts`
+- Modify: `src/shared/index.ts`
+
+- [ ] **Step 1: Write failing tests for exact keep behavior**
+- [ ] **Step 2: Write failing tests for downgrade behavior (`max` -> `high`, `xhigh` -> `high` where needed)**
+- [ ] **Step 3: Write failing tests for unsupported-value removal**
+- [ ] **Step 4: Write failing tests for model-family distinctions (Opus vs Sonnet/Haiku, GPT-family variants)**
+- [ ] **Step 5: Implement the pure resolver with explicit capability ladders**
+- [ ] **Step 6: Export the resolver from `src/shared/index.ts`**
+- [ ] **Step 7: Run `bun test src/shared/model-settings-compatibility.test.ts`**
+- [ ] **Step 8: Commit**
+
+### Task 2: Integrate resolver into chat.params
+
+**Files:**
+- Modify: `src/plugin/chat-params.ts`
+- Modify: `src/plugin/chat-params.test.ts`
+
+- [ ] **Step 1: Write failing tests showing `chat.params` applies resolver output to runtime settings**
+- [ ] **Step 2: Ensure tests cover both `variant` and `reasoningEffort` decisions**
+- [ ] **Step 3: Update `chat-params.ts` to call the shared resolver before hook-specific adjustments**
+- [ ] **Step 4: Preserve existing prompt-param-store merging behavior**
+- [ ] **Step 5: Run `bun test src/plugin/chat-params.test.ts`**
+- [ ] **Step 6: Commit**
+
+### Task 3: Re-scope anthropic-effort around the resolver
+
+**Files:**
+- Modify: `src/hooks/anthropic-effort/hook.ts`
+- Modify: `src/hooks/anthropic-effort/index.test.ts`
+
+- [ ] **Step 1: Write failing tests that codify the intended remaining Anthropic-specific behavior after centralization**
+- [ ] **Step 2: Reduce `anthropic-effort` to Claude/Anthropic-specific effort injection where still needed**
+- [ ] **Step 3: Remove duplicated compatibility policy from the hook if the shared resolver now owns it**
+- [ ] **Step 4: Run `bun test src/hooks/anthropic-effort/index.test.ts`**
+- [ ] **Step 5: Commit**
+
+### Task 4: Add integration/regression coverage across real request paths
+
+**Files:**
+- Modify: `src/plugin/chat-params.test.ts`
+- Modify: `src/hooks/anthropic-effort/index.test.ts`
+- Add tests only where needed in nearby suites
+
+- [ ] **Step 1: Add regression test for non-Opus Claude with `variant=max` resolving to compatible settings without ad hoc path-only logic**
+- [ ] **Step 2: Add regression test for GPT-style `reasoningEffort` compatibility**
+- [ ] **Step 3: Add regression test showing supported values remain unchanged**
+- [ ] **Step 4: Run the focused test set**
+- [ ] **Step 5: Commit**
+
+### Task 5: Verify full quality bar
+
+**Files:**
+- No intended code changes
+
+- [ ] **Step 1: Run `bun run typecheck`**
+- [ ] **Step 2: Run a focused suite for the touched files**
+- [ ] **Step 3: If clean, run `bun test`**
+- [ ] **Step 4: Review diff for accidental scope creep**
+- [ ] **Step 5: Commit any final cleanup**
+
+### Task 6: Prepare PR metadata
+
+**Files:**
+- No repo file change required unless docs are updated further
+
+- [ ] **Step 1: Write a human summary explaining this is settings compatibility, not model fallback**
+- [ ] **Step 2: Document scope: Phase 1 covers `variant` and `reasoningEffort` only**
+- [ ] **Step 3: Document explicit non-goals: no model switching, no automatic upscaling in Phase 1**
+- [ ] **Step 4: Request review**

docs/superpowers/specs/2026-03-17-model-settings-compatibility-design.md

@@ -0,0 +1,164 @@
+# Model Settings Compatibility Resolver Design
+
+## Goal
+
+Introduce a central resolver that takes an already-selected model and a set of desired model settings, then returns the best compatible configuration for that exact model.
+
+This is explicitly separate from model fallback.
+
+## Problem
+
+Today, logic for `variant` and `reasoningEffort` compatibility is scattered across multiple places:
+- `hooks/anthropic-effort`
+- `plugin/chat-params`
+- agent/category/fallback config layers
+- delegate/background prompt plumbing
+
+That creates inconsistent behavior:
+- some paths clamp unsupported levels
+- some paths pass them through unchanged
+- some paths silently drop them
+- some paths use model-family-specific assumptions that do not generalize
+
+The result is brittle request behavior even when the chosen model itself is valid.
+
+## Scope
+
+Phase 1 covers only:
+- `variant`
+- `reasoningEffort`
+
+Out of scope for Phase 1:
+- model fallback itself
+- `thinking`
+- `maxTokens`
+- `temperature`
+- `top_p`
+- automatic upward remapping of settings
+
+## Desired behavior
+
+Given a fixed model and desired settings:
+1. If a desired value is supported, keep it.
+2. If not supported, downgrade to the nearest lower compatible value.
+3. If no compatible value exists, drop the field.
+4. Do not switch models.
+5. Do not automatically upgrade settings in Phase 1.
+
+## Architecture
+
+Add a central module:
+- `src/shared/model-settings-compatibility.ts`
+
+Core API:
+
+```ts
+type DesiredModelSettings = {
+  variant?: string
+  reasoningEffort?: string
+}
+
+type ModelSettingsCompatibilityInput = {
+  providerID: string
+  modelID: string
+  desired: DesiredModelSettings
+}
+
+type ModelSettingsCompatibilityChange = {
+  field: "variant" | "reasoningEffort"
+  from: string
+  to?: string
+  reason: string
+}
+
+type ModelSettingsCompatibilityResult = {
+  variant?: string
+  reasoningEffort?: string
+  changes: ModelSettingsCompatibilityChange[]
+}
+```
+
+## Compatibility model
+
+Phase 1 should be **metadata-first where the platform exposes reliable capability data**, and only fall back to family-based rules when that metadata is absent.
+
+### Variant compatibility
+
+Preferred source of truth:
+- OpenCode/provider model metadata (`variants`)
+
+Fallback when metadata is unavailable:
+- family-based ladders
+
+Examples of fallback ladders:
+- Claude Opus family: `low`, `medium`, `high`, `max`
+- Claude Sonnet/Haiku family: `low`, `medium`, `high`
+- OpenAI GPT family: conservative family fallback only when metadata is missing
+- Unknown family: drop unsupported values conservatively
+
+### Reasoning effort compatibility
+
+Current Phase 1 source of truth:
+- conservative model/provider family heuristics
+
+Reason:
+- the currently available OpenCode SDK/provider metadata exposes model `variants`, but does not expose an equivalent per-model capability list for `reasoningEffort` levels
+
+Examples:
+- GPT/OpenAI-style models: `low`, `medium`, `high`, `xhigh` where supported by family heuristics
+- Claude family via current OpenCode path: treat `reasoningEffort` as unsupported in Phase 1 and remove it
+
+The resolver should remain pure model/settings logic only. Transport restrictions remain the responsibility of the request-building path.
+
+## Separation of concerns
+
+This design intentionally separates:
+- model selection (`resolveModel...`, fallback chains)
+- settings compatibility (this resolver)
+- request transport compatibility (`chat.params`, prompt body constraints)
+
+That keeps responsibilities clear:
+- choose model first
+- normalize settings second
+- build request third
+
+## First integration point
+
+Phase 1 should first integrate into `chat.params`.
+
+Why:
+- it is already the centralized path for request-time tuning
+- it can influence provider-facing options without leaking unsupported fields into prompt payload bodies
+- it avoids trying to patch every prompt constructor at once
+
+## Rollout plan
+
+### Phase 1
+- add resolver module and tests
+- integrate into `chat.params`
+- migrate `anthropic-effort` to either use the resolver or become a thin Claude-specific supplement around it
+
+### Phase 2
+- expand to `thinking`, `maxTokens`, `temperature`, `top_p`
+- formalize request-path capability tables if needed
+
+### Phase 3
+- centralize all variant/reasoning normalization away from scattered hooks and ad hoc callers
+
+## Risks
+
+- Overfitting family rules to current model naming conventions
+- Accidentally changing request semantics on paths that currently rely on implicit behavior
+- Mixing provider transport limitations with model capability logic
+
+## Mitigations
+
+- Keep resolver pure and narrowly scoped in Phase 1
+- Add explicit regression tests for keep/downgrade/drop decisions
+- Integrate at one central point first (`chat.params`)
+- Preserve existing behavior where desired values are already valid
+
+## Recommendation
+
+Proceed with the central resolver as a new, isolated implementation in a dedicated branch/worktree.
+This is the clean long-term path and is more reviewable than continuing to add special-case clamps in hooks.

docs/troubleshooting/ollama.md

@@ -4,7 +4,7 @@
 
 ### Problem
 
-When using Ollama as a provider with oh-my-opencode agents, you may encounter:
+When using Ollama as a provider with oh-my-openagent agents, you may encounter:
 
 ```
 JSON Parse error: Unexpected EOF
@@ -26,7 +26,7 @@ Claude Code SDK expects a single JSON object, not multiple NDJSON lines, causing
 **Why this happens:**
 - **Ollama API**: Returns streaming responses as NDJSON by design
 - **Claude Code SDK**: Doesn't properly handle NDJSON responses for tool calls
-- **oh-my-opencode**: Passes through the SDK's behavior (can't fix at this layer)
+- **oh-my-openagent**: Passes through the SDK's behavior (can't fix at this layer)
 
 ## Solutions
 
@@ -114,7 +114,7 @@ curl -s http://localhost:11434/api/chat \
 
 ## Related Issues
 
-- **oh-my-opencode**: https://github.com/code-yeongyu/oh-my-openagent/issues/1124
+- **oh-my-openagent**: https://github.com/code-yeongyu/oh-my-openagent/issues/1124
 - **Ollama API Docs**: https://github.com/ollama/ollama/blob/main/docs/api.md
 
 ## Getting Help

package.json

@@ -25,10 +25,12 @@
     "build:all": "bun run build && bun run build:binaries",
     "build:binaries": "bun run script/build-binaries.ts",
     "build:schema": "bun run script/build-schema.ts",
+    "build:model-capabilities": "bun run script/build-model-capabilities.ts",
     "clean": "rm -rf dist",
     "prepare": "bun run build",
     "postinstall": "node postinstall.mjs",
     "prepublishOnly": "bun run clean && bun run build",
+    "test:model-capabilities": "bun test src/shared/model-capability-aliases.test.ts src/shared/model-capability-guardrails.test.ts src/shared/model-capabilities.test.ts src/cli/doctor/checks/model-resolution.test.ts --bail",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },

script/build-binaries.ts

@@ -101,7 +101,9 @@ async function main() {
   console.log("\n✅ All platform binaries built successfully!\n");
 }
 
-main().catch((error) => {
-  console.error("Fatal error:", error);
-  process.exit(1);
-});
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  });
+}

script/build-model-capabilities.ts

@@ -0,0 +1,13 @@
+import { writeFileSync } from "fs"
+import { resolve } from "path"
+import {
+  fetchModelCapabilitiesSnapshot,
+  MODELS_DEV_SOURCE_URL,
+} from "../src/shared/model-capabilities-cache"
+
+const OUTPUT_PATH = resolve(import.meta.dir, "../src/generated/model-capabilities.generated.json")
+
+console.log(`Fetching model capabilities snapshot from ${MODELS_DEV_SOURCE_URL}...`)
+const snapshot = await fetchModelCapabilitiesSnapshot()
+writeFileSync(OUTPUT_PATH, `${JSON.stringify(snapshot, null, 2)}\n`)
+console.log(`Generated ${OUTPUT_PATH} with ${Object.keys(snapshot.models).length} models`)

signatures/cla.json

@@ -2239,6 +2239,94 @@
       "created_at": "2026-03-17T20:42:42Z",
       "repoId": 1108837393,
       "pullRequestNo": 2656
+    },
+    {
+      "name": "walioo",
+      "id": 25835823,
+      "comment_id": 4087098221,
+      "created_at": "2026-03-19T02:13:02Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2688
+    },
+    {
+      "name": "trafgals",
+      "id": 6454757,
+      "comment_id": 4087725932,
+      "created_at": "2026-03-19T04:22:32Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2690
+    },
+    {
+      "name": "tonymfer",
+      "id": 66512584,
+      "comment_id": 4091847232,
+      "created_at": "2026-03-19T17:13:49Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2701
+    },
+    {
+      "name": "nguyentamdat",
+      "id": 16253213,
+      "comment_id": 4096267323,
+      "created_at": "2026-03-20T07:34:22Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2718
+    },
+    {
+      "name": "whackur",
+      "id": 26926041,
+      "comment_id": 4102330445,
+      "created_at": "2026-03-21T05:27:17Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2733
+    },
+    {
+      "name": "ndaemy",
+      "id": 18691542,
+      "comment_id": 4103008804,
+      "created_at": "2026-03-21T10:18:22Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2734
+    },
+    {
+      "name": "0xYiliu",
+      "id": 3838688,
+      "comment_id": 4104738337,
+      "created_at": "2026-03-21T22:59:33Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2738
+    },
+    {
+      "name": "hunghoang3011",
+      "id": 65234777,
+      "comment_id": 4107900881,
+      "created_at": "2026-03-23T04:28:20Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2758
+    },
+    {
+      "name": "anas-asghar4831",
+      "id": 110368394,
+      "comment_id": 4128950310,
+      "created_at": "2026-03-25T18:48:19Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2837
+    },
+    {
+      "name": "clansty",
+      "id": 18461360,
+      "comment_id": 4129934858,
+      "created_at": "2026-03-25T21:33:35Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2839
+    },
+    {
+      "name": "ventsislav-georgiev",
+      "id": 5616486,
+      "comment_id": 4130417794,
+      "created_at": "2026-03-25T23:11:32Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 2840
     }
   ]
 }

src/AGENTS.md

@@ -14,7 +14,7 @@ Entry point `index.ts` orchestrates 5-step initialization: loadConfig → create
 | `plugin-config.ts` | JSONC parse, multi-level merge, Zod v4 validation |
 | `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler |
 | `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry (26 tools) |
-| `create-hooks.ts` | 3-tier: Core(37) + Continuation(7) + Skill(2) = 46 hooks |
+| `create-hooks.ts` | 3-tier: Core(39) + Continuation(7) + Skill(2) = 48 hooks |
 | `plugin-interface.ts` | 8 OpenCode hook handlers: config, tool, chat.message, chat.params, chat.headers, event, tool.execute.before, tool.execute.after |
 
 ## CONFIG LOADING
@@ -32,10 +32,10 @@ loadPluginConfig(directory, ctx)
 
 ```
 createHooks()
-  ├─→ createCoreHooks()           # 37 hooks
+  ├─→ createCoreHooks()           # 39 hooks
   │   ├─ createSessionHooks()     # 23: contextWindowMonitor, thinkMode, ralphLoop, modelFallback, runtimeFallback, noSisyphusGpt, noHephaestusNonGpt, anthropicEffort, intentGate...
-  │   ├─ createToolGuardHooks()   # 10: commentChecker, rulesInjector, writeExistingFileGuard, jsonErrorRecovery, hashlineReadEnhancer...
+  │   ├─ createToolGuardHooks()   # 12: commentChecker, rulesInjector, writeExistingFileGuard, jsonErrorRecovery, hashlineReadEnhancer...
   │   └─ createTransformHooks()   # 4: claudeCodeHooks, keywordDetector, contextInjector, thinkingBlockValidator
-  ├─→ createContinuationHooks()   # 7: todoContinuationEnforcer, atlas, stopContinuationGuard, ralphLoopActivator...
+  ├─→ createContinuationHooks()   # 7: todoContinuationEnforcer, atlas, stopContinuationGuard, compactionContextInjector...
   └─→ createSkillHooks()          # 2: categorySkillReminder, autoSlashCommand
 ```

src/agents/AGENTS.md

@@ -13,8 +13,8 @@ Agent factories following `createXXXAgent(model) → AgentConfig` pattern. Each
 | **Sisyphus** | claude-opus-4-6 max | 0.1 | all | k2p5 → kimi-k2.5 → gpt-5.4 medium → glm-5 → big-pickle | Main orchestrator, plans + delegates |
 | **Hephaestus** | gpt-5.3-codex medium | 0.1 | all | gpt-5.4 medium (copilot) | Autonomous deep worker |
 | **Oracle** | gpt-5.4 high | 0.1 | subagent | gemini-3.1-pro high → claude-opus-4-6 max | Read-only consultation |
-| **Librarian** | gemini-3-flash | 0.1 | subagent | minimax-m2.5-free → big-pickle | External docs/code search |
-| **Explore** | grok-code-fast-1 | 0.1 | subagent | minimax-m2.5-free → claude-haiku-4-5 → gpt-5-nano | Contextual grep |
+| **Librarian** | minimax-m2.7 | 0.1 | subagent | minimax-m2.7-highspeed → claude-haiku-4-5 → gpt-5-nano | External docs/code search |
+| **Explore** | grok-code-fast-1 | 0.1 | subagent | minimax-m2.7-highspeed → minimax-m2.7 → claude-haiku-4-5 → gpt-5-nano | Contextual grep |
 | **Multimodal-Looker** | gpt-5.3-codex medium | 0.1 | subagent | k2p5 → gemini-3-flash → glm-4.6v → gpt-5-nano | PDF/image analysis |
 | **Metis** | claude-opus-4-6 max | **0.3** | subagent | gpt-5.4 high → gemini-3.1-pro high | Pre-planning consultant |
 | **Momus** | gpt-5.4 xhigh | 0.1 | subagent | claude-opus-4-6 max → gemini-3.1-pro high | Plan reviewer |

src/agents/builtin-agents/agent-overrides.ts

@@ -44,6 +44,10 @@ export function mergeAgentConfig(
   const { prompt_append, ...rest } = migratedOverride
   const merged = deepMerge(base, rest as Partial<AgentConfig>)
 
+  if (merged.prompt && typeof merged.prompt === 'string' && merged.prompt.startsWith('file://')) {
+    merged.prompt = resolvePromptAppend(merged.prompt, directory)
+  }
+
   if (prompt_append && merged.prompt) {
     merged.prompt = merged.prompt + "\n" + resolvePromptAppend(prompt_append, directory)
   }

src/agents/builtin-agents/atlas-agent.ts

@@ -39,7 +39,7 @@ export function maybeCreateAtlasConfig(input: {
   const atlasRequirement = AGENT_MODEL_REQUIREMENTS["atlas"]
 
   const atlasResolution = applyModelResolution({
-    uiSelectedModel: orchestratorOverride?.model ? undefined : uiSelectedModel,
+    uiSelectedModel: orchestratorOverride?.model !== undefined ? undefined : uiSelectedModel,
     userModel: orchestratorOverride?.model,
     requirement: atlasRequirement,
     availableModels,

src/agents/builtin-agents/general-agents.ts

@@ -8,6 +8,7 @@ import { buildAgent, isFactory } from "../agent-builder"
 import { applyOverrides } from "./agent-overrides"
 import { applyEnvironmentContext } from "./environment-context"
 import { applyModelResolution, getFirstFallbackModel } from "./model-resolution"
+import { log } from "../../shared/logger"
 
 export function collectPendingBuiltinAgents(input: {
   agentSources: Record<BuiltinAgentName, import("../agent-builder").AgentSource>
@@ -69,13 +70,19 @@ export function collectPendingBuiltinAgents(input: {
     const isPrimaryAgent = isFactory(source) && source.mode === "primary"
 
     let resolution = applyModelResolution({
-      uiSelectedModel: (isPrimaryAgent && !override?.model) ? uiSelectedModel : undefined,
+      uiSelectedModel: (isPrimaryAgent && override?.model === undefined) ? uiSelectedModel : undefined,
       userModel: override?.model,
       requirement,
       availableModels,
       systemDefaultModel,
     })
-    if (!resolution && isFirstRunNoCache && !override?.model) {
+    if (!resolution) {
+      if (override?.model) {
+        log("[agent-registration] User-configured model could not be resolved, falling back", {
+          agent: agentName,
+          configuredModel: override.model,
+        })
+      }
       resolution = getFirstFallbackModel(requirement)
     }
     if (!resolution) continue

src/agents/builtin-agents/resolve-file-uri.test.ts

@@ -1,20 +1,32 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test"
 import { mkdirSync, rmSync, writeFileSync } from "node:fs"
-import { homedir, tmpdir } from "node:os"
+import * as os from "node:os"
+import { tmpdir } from "node:os"
 import { join } from "node:path"
-import { resolvePromptAppend } from "./resolve-file-uri"
+
+const originalHomedir = os.homedir.bind(os)
+let mockedHomeDir = ""
+let moduleImportCounter = 0
+let resolvePromptAppend: typeof import("./resolve-file-uri").resolvePromptAppend
+
+mock.module("node:os", () => ({
+  ...os,
+  homedir: () => mockedHomeDir || originalHomedir(),
+}))
 
 describe("resolvePromptAppend", () => {
   const fixtureRoot = join(tmpdir(), `resolve-file-uri-${Date.now()}`)
   const configDir = join(fixtureRoot, "config")
-  const homeFixtureDir = join(homedir(), `.resolve-file-uri-home-${Date.now()}`)
+  const homeFixtureRoot = join(fixtureRoot, "home")
+  const homeFixtureDir = join(homeFixtureRoot, "fixture-home")
 
   const absoluteFilePath = join(fixtureRoot, "absolute.txt")
   const relativeFilePath = join(configDir, "relative.txt")
   const spacedFilePath = join(fixtureRoot, "with space.txt")
   const homeFilePath = join(homeFixtureDir, "home.txt")
 
-  beforeAll(() => {
+  beforeAll(async () => {
+    mockedHomeDir = homeFixtureRoot
     mkdirSync(fixtureRoot, { recursive: true })
     mkdirSync(configDir, { recursive: true })
     mkdirSync(homeFixtureDir, { recursive: true })
@@ -23,11 +35,14 @@ describe("resolvePromptAppend", () => {
     writeFileSync(relativeFilePath, "relative-content", "utf8")
     writeFileSync(spacedFilePath, "encoded-content", "utf8")
     writeFileSync(homeFilePath, "home-content", "utf8")
+
+    moduleImportCounter += 1
+    ;({ resolvePromptAppend } = await import(`./resolve-file-uri?test=${moduleImportCounter}`))
   })
 
   afterAll(() => {
     rmSync(fixtureRoot, { recursive: true, force: true })
-    rmSync(homeFixtureDir, { recursive: true, force: true })
+    mock.restore()
   })
 
   test("returns non-file URI strings unchanged", () => {
@@ -65,7 +80,7 @@ describe("resolvePromptAppend", () => {
 
   test("resolves home directory URI path", () => {
     //#given
-    const input = `file://~/${homeFixtureDir.split("/").pop()}/home.txt`
+    const input = "file://~/fixture-home/home.txt"
 
     //#when
     const resolved = resolvePromptAppend(input)

src/agents/builtin-agents/sisyphus-agent.ts

@@ -52,7 +52,7 @@ export function maybeCreateSisyphusConfig(input: {
   if (disabledAgents.includes("sisyphus") || !meetsSisyphusAnyModelRequirement) return undefined
 
   let sisyphusResolution = applyModelResolution({
-    uiSelectedModel: sisyphusOverride?.model ? undefined : uiSelectedModel,
+    uiSelectedModel: sisyphusOverride?.model !== undefined ? undefined : uiSelectedModel,
     userModel: sisyphusOverride?.model,
     requirement: sisyphusRequirement,
     availableModels,

src/agents/dynamic-agent-prompt-builder.test.ts

@@ -181,7 +181,7 @@ describe("buildParallelDelegationSection", () => {
 
   it("#given non-Claude model with deep category #when building #then returns aggressive delegation section", () => {
     //#given
-    const model = "google/gemini-3-pro"
+    const model = "google/gemini-3.1-pro"
     const categories = [deepCategory, otherCategory]
 
     //#when
@@ -237,7 +237,7 @@ describe("buildParallelDelegationSection", () => {
 describe("buildNonClaudePlannerSection", () => {
   it("#given non-Claude model #when building #then returns plan agent section", () => {
     //#given
-    const model = "google/gemini-3-pro"
+    const model = "google/gemini-3.1-pro"
 
     //#when
     const result = buildNonClaudePlannerSection(model)
@@ -272,4 +272,3 @@ describe("buildNonClaudePlannerSection", () => {
   })
 })
 
-

src/agents/hephaestus/gpt-5-3-codex.ts

@@ -162,6 +162,10 @@ Asking the user is the LAST resort after exhausting creative alternatives.
 - User asks a question implying work → Answer briefly, DO the implied work in the same turn
 - You wrote a plan in your response → EXECUTE the plan before ending turn — plans are starting lines, not finish lines
 
+### Task Scope Clarification
+
+You handle multi-step sub-tasks of a SINGLE GOAL. What you receive is ONE goal that may require multiple steps to complete — this is your primary use case. Only reject when given MULTIPLE INDEPENDENT goals in one request.
+
 ## Hard Constraints
 
 ${hardBlocks}

src/agents/hephaestus/gpt-5-4.ts

@@ -121,6 +121,10 @@ When blocked: try a different approach → decompose the problem → challenge a
 - User asks a question implying work → Answer briefly, DO the implied work in the same turn
 - You wrote a plan in your response → EXECUTE the plan before ending turn — plans are starting lines, not finish lines
 
+### Task Scope Clarification
+
+You handle multi-step sub-tasks of a SINGLE GOAL. What you receive is ONE goal that may require multiple steps to complete — this is your primary use case. Only reject when given MULTIPLE INDEPENDENT goals in one request.
+
 ## Hard Constraints
 
 ${hardBlocks}

src/agents/hephaestus/gpt.ts

@@ -112,6 +112,10 @@ Asking the user is the LAST resort after exhausting creative alternatives.
 - Note assumptions in final message, not as questions mid-work
 - Need context? Fire explore/librarian in background IMMEDIATELY — continue only with non-overlapping work while they search
 
+### Task Scope Clarification
+
+You handle multi-step sub-tasks of a SINGLE GOAL. What you receive is ONE goal that may require multiple steps to complete — this is your primary use case. Only reject when given MULTIPLE INDEPENDENT goals in one request.
+
 ## Hard Constraints
 
 ${hardBlocks}

src/agents/prometheus/system-prompt.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "bun:test"
+import { getPrometheusPrompt } from "./system-prompt"
+
+describe("getPrometheusPrompt", () => {
+  describe("#given question tool is not disabled", () => {
+    describe("#when generating prompt", () => {
+      it("#then should include Question tool references", () => {
+        const prompt = getPrometheusPrompt(undefined, [])
+
+        expect(prompt).toContain("Question({")
+      })
+    })
+  })
+
+  describe("#given question tool is disabled via disabled_tools", () => {
+    describe("#when generating prompt", () => {
+      it("#then should strip Question tool code examples", () => {
+        const prompt = getPrometheusPrompt(undefined, ["question"])
+
+        expect(prompt).not.toContain("Question({")
+      })
+    })
+
+    describe("#when disabled_tools includes question among other tools", () => {
+      it("#then should strip Question tool code examples", () => {
+        const prompt = getPrometheusPrompt(undefined, ["todowrite", "question", "interactive_bash"])
+
+        expect(prompt).not.toContain("Question({")
+      })
+    })
+  })
+
+  describe("#given no disabled_tools provided", () => {
+    describe("#when generating prompt with undefined", () => {
+      it("#then should include Question tool references", () => {
+        const prompt = getPrometheusPrompt(undefined, undefined)
+
+        expect(prompt).toContain("Question({")
+      })
+    })
+  })
+})

src/agents/prometheus/system-prompt.ts

@@ -52,16 +52,34 @@ export function getPrometheusPromptSource(model?: string): PrometheusPromptSourc
  * Gemini models → Gemini-optimized prompt (aggressive tool-call enforcement, thinking checkpoints)
  * Default (Claude, etc.) → Claude-optimized prompt (modular sections)
  */
-export function getPrometheusPrompt(model?: string): string {
+export function getPrometheusPrompt(model?: string, disabledTools?: readonly string[]): string {
   const source = getPrometheusPromptSource(model)
+  const isQuestionDisabled = disabledTools?.includes("question") ?? false
 
+  let prompt: string
   switch (source) {
     case "gpt":
-      return getGptPrometheusPrompt()
+      prompt = getGptPrometheusPrompt()
+      break
     case "gemini":
-      return getGeminiPrometheusPrompt()
+      prompt = getGeminiPrometheusPrompt()
+      break
     case "default":
     default:
-      return PROMETHEUS_SYSTEM_PROMPT
+      prompt = PROMETHEUS_SYSTEM_PROMPT
   }
+
+  if (isQuestionDisabled) {
+    prompt = stripQuestionToolReferences(prompt)
+  }
+
+  return prompt
+}
+
+/**
+ * Removes Question tool usage examples from prompt text when question tool is disabled.
+ */
+function stripQuestionToolReferences(prompt: string): string {
+  // Remove Question({...}) code blocks (multi-line)
+  return prompt.replace(/```typescript\n\s*Question\(\{[\s\S]*?\}\)\s*\n```/g, "")
 }

src/agents/sisyphus-junior/default.ts

@@ -35,6 +35,11 @@ Task NOT complete without:
 - ${verificationText}
 </Verification>
 
+<Termination>
+STOP after first successful verification. Do NOT re-verify.
+Maximum status checks: 2. Then stop regardless.
+</Termination>
+
 <Style>
 - Start immediately. No acknowledgments.
 - Match user's communication style.

src/agents/types.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "bun:test";
-import { isGptModel, isGeminiModel, isGpt5_4Model } from "./types";
+import { isGptModel, isGeminiModel, isGpt5_4Model, isMiniMaxModel } from "./types";
 
 describe("isGpt5_4Model", () => {
   test("detects gpt-5.4 models", () => {
@@ -79,6 +79,28 @@ describe("isGptModel", () => {
   });
 });
 
+describe("isMiniMaxModel", () => {
+  test("detects minimax models with provider prefix", () => {
+    expect(isMiniMaxModel("opencode-go/minimax-m2.7")).toBe(true);
+    expect(isMiniMaxModel("opencode/minimax-m2.7-highspeed")).toBe(true);
+    expect(isMiniMaxModel("opencode-go/minimax-m2.5")).toBe(true);
+    expect(isMiniMaxModel("opencode/minimax-m2.5-free")).toBe(true);
+  });
+
+  test("detects minimax models without provider prefix", () => {
+    expect(isMiniMaxModel("minimax-m2.7")).toBe(true);
+    expect(isMiniMaxModel("minimax-m2.7-highspeed")).toBe(true);
+    expect(isMiniMaxModel("minimax-m2.5")).toBe(true);
+  });
+
+  test("does not match non-minimax models", () => {
+    expect(isMiniMaxModel("openai/gpt-5.4")).toBe(false);
+    expect(isMiniMaxModel("anthropic/claude-opus-4-6")).toBe(false);
+    expect(isMiniMaxModel("google/gemini-3.1-pro")).toBe(false);
+    expect(isMiniMaxModel("opencode-go/kimi-k2.5")).toBe(false);
+  });
+});
+
 describe("isGeminiModel", () => {
   test("#given google provider models #then returns true", () => {
     expect(isGeminiModel("google/gemini-3.1-pro")).toBe(true);

src/agents/types.ts

@@ -91,6 +91,11 @@ export function isGpt5_3CodexModel(model: string): boolean {
 
 const GEMINI_PROVIDERS = ["google/", "google-vertex/"];
 
+export function isMiniMaxModel(model: string): boolean {
+  const modelName = extractModelName(model).toLowerCase();
+  return modelName.includes("minimax");
+}
+
 export function isGeminiModel(model: string): boolean {
   if (GEMINI_PROVIDERS.some((prefix) => model.startsWith(prefix))) return true;
 
@@ -123,7 +128,7 @@ export type AgentName = BuiltinAgentName;
 export type AgentOverrideConfig = Partial<AgentConfig> & {
   prompt_append?: string;
   variant?: string;
-  fallback_models?: string | string[];
+  fallback_models?: string | (string | import("../config/schema/fallback-models").FallbackModelObject)[];
 };
 
 export type AgentOverrides = Partial<

src/cli/__snapshots__/model-fallback.test.ts.snap

@@ -248,8 +248,7 @@ exports[`generateModelConfig single native provider uses OpenAI models when only
       "variant": "medium",
     },
     "quick": {
-      "model": "openai/gpt-5.3-codex",
-      "variant": "low",
+      "model": "openai/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "openai/gpt-5.4",
@@ -334,8 +333,7 @@ exports[`generateModelConfig single native provider uses OpenAI models with isMa
       "variant": "medium",
     },
     "quick": {
-      "model": "openai/gpt-5.3-codex",
-      "variant": "low",
+      "model": "openai/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "openai/gpt-5.4",
@@ -533,7 +531,7 @@ exports[`generateModelConfig all native providers uses preferred models from fal
       "variant": "medium",
     },
     "quick": {
-      "model": "anthropic/claude-haiku-4-5",
+      "model": "openai/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "openai/gpt-5.4",
@@ -608,7 +606,7 @@ exports[`generateModelConfig all native providers uses preferred models with isM
       "variant": "medium",
     },
     "quick": {
-      "model": "anthropic/claude-haiku-4-5",
+      "model": "openai/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "openai/gpt-5.4",
@@ -684,7 +682,7 @@ exports[`generateModelConfig fallback providers uses OpenCode Zen models when on
       "variant": "medium",
     },
     "quick": {
-      "model": "opencode/claude-haiku-4-5",
+      "model": "opencode/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "opencode/gpt-5.4",
@@ -759,7 +757,7 @@ exports[`generateModelConfig fallback providers uses OpenCode Zen models with is
       "variant": "medium",
     },
     "quick": {
-      "model": "opencode/claude-haiku-4-5",
+      "model": "opencode/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "opencode/gpt-5.4",
@@ -830,7 +828,7 @@ exports[`generateModelConfig fallback providers uses GitHub Copilot models when
       "variant": "high",
     },
     "quick": {
-      "model": "github-copilot/claude-haiku-4.5",
+      "model": "github-copilot/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "github-copilot/gemini-3.1-pro-preview",
@@ -900,7 +898,7 @@ exports[`generateModelConfig fallback providers uses GitHub Copilot models with
       "variant": "high",
     },
     "quick": {
-      "model": "github-copilot/claude-haiku-4.5",
+      "model": "github-copilot/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "github-copilot/gemini-3.1-pro-preview",
@@ -1092,7 +1090,7 @@ exports[`generateModelConfig mixed provider scenarios uses Claude + OpenCode Zen
       "variant": "medium",
     },
     "quick": {
-      "model": "anthropic/claude-haiku-4-5",
+      "model": "opencode/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "opencode/gpt-5.4",
@@ -1167,7 +1165,7 @@ exports[`generateModelConfig mixed provider scenarios uses OpenAI + Copilot comb
       "variant": "medium",
     },
     "quick": {
-      "model": "github-copilot/claude-haiku-4.5",
+      "model": "openai/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "openai/gpt-5.4",
@@ -1375,7 +1373,7 @@ exports[`generateModelConfig mixed provider scenarios uses all fallback provider
       "variant": "medium",
     },
     "quick": {
-      "model": "github-copilot/claude-haiku-4.5",
+      "model": "github-copilot/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "opencode/gpt-5.4",
@@ -1453,7 +1451,7 @@ exports[`generateModelConfig mixed provider scenarios uses all providers togethe
       "variant": "medium",
     },
     "quick": {
-      "model": "anthropic/claude-haiku-4-5",
+      "model": "openai/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "openai/gpt-5.4",
@@ -1531,7 +1529,7 @@ exports[`generateModelConfig mixed provider scenarios uses all providers with is
       "variant": "medium",
     },
     "quick": {
-      "model": "anthropic/claude-haiku-4-5",
+      "model": "openai/gpt-5.4-mini",
     },
     "ultrabrain": {
       "model": "openai/gpt-5.4",

src/cli/cli-program.ts

@@ -3,6 +3,7 @@ import { install } from "./install"
 import { run } from "./run"
 import { getLocalVersion } from "./get-local-version"
 import { doctor } from "./doctor"
+import { refreshModelCapabilities } from "./refresh-model-capabilities"
 import { createMcpOAuthCommand } from "./mcp-oauth"
 import type { InstallArgs } from "./types"
 import type { RunOptions } from "./run"
@@ -42,7 +43,7 @@ Examples:
 Model Providers (Priority: Native > Copilot > OpenCode Zen > Z.ai > Kimi):
   Claude        Native anthropic/ models (Opus, Sonnet, Haiku)
   OpenAI        Native openai/ models (GPT-5.4 for Oracle)
-  Gemini        Native google/ models (Gemini 3 Pro, Flash)
+  Gemini        Native google/ models (Gemini 3.1 Pro, Flash)
   Copilot       github-copilot/ models (fallback)
   OpenCode Zen  opencode/ models (opencode/claude-opus-4-6, etc.)
    Z.ai          zai-coding-plan/glm-5 (visual-engineering fallback)
@@ -176,6 +177,21 @@ Examples:
     process.exit(exitCode)
   })
 
+program
+  .command("refresh-model-capabilities")
+  .description("Refresh the cached models.dev-based model capabilities snapshot")
+  .option("-d, --directory <path>", "Working directory to read oh-my-opencode config from")
+  .option("--source-url <url>", "Override the models.dev source URL")
+  .option("--json", "Output refresh summary as JSON")
+  .action(async (options) => {
+    const exitCode = await refreshModelCapabilities({
+      directory: options.directory,
+      sourceUrl: options.sourceUrl,
+      json: options.json ?? false,
+    })
+    process.exit(exitCode)
+  })
+
 program
   .command("version")
   .description("Show version information")

src/cli/doctor/checks/config.ts

@@ -2,15 +2,15 @@ import { readFileSync } from "node:fs"
 import { join } from "node:path"
 
 import { OhMyOpenCodeConfigSchema } from "../../../config"
-import { detectConfigFile, getOpenCodeConfigDir, parseJsonc } from "../../../shared"
+import { detectPluginConfigFile, getOpenCodeConfigDir, parseJsonc } from "../../../shared"
 import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
 import type { CheckResult, DoctorIssue } from "../types"
 import { loadAvailableModelsFromCache } from "./model-resolution-cache"
 import { getModelResolutionInfoWithOverrides } from "./model-resolution"
 import type { OmoConfig } from "./model-resolution-types"
 
-const USER_CONFIG_BASE = join(getOpenCodeConfigDir({ binary: "opencode" }), PACKAGE_NAME)
-const PROJECT_CONFIG_BASE = join(process.cwd(), ".opencode", PACKAGE_NAME)
+const USER_CONFIG_DIR = getOpenCodeConfigDir({ binary: "opencode" })
+const PROJECT_CONFIG_DIR = join(process.cwd(), ".opencode")
 
 interface ConfigValidationResult {
   exists: boolean
@@ -21,10 +21,10 @@ interface ConfigValidationResult {
 }
 
 function findConfigPath(): string | null {
-  const projectConfig = detectConfigFile(PROJECT_CONFIG_BASE)
+  const projectConfig = detectPluginConfigFile(PROJECT_CONFIG_DIR)
   if (projectConfig.format !== "none") return projectConfig.path
 
-  const userConfig = detectConfigFile(USER_CONFIG_BASE)
+  const userConfig = detectPluginConfigFile(USER_CONFIG_DIR)
   if (userConfig.format !== "none") return userConfig.path
 
   return null

src/cli/doctor/checks/model-resolution-config.ts

@@ -1,17 +1,13 @@
 import { readFileSync } from "node:fs"
 import { join } from "node:path"
-import { detectConfigFile, getOpenCodeConfigPaths, parseJsonc } from "../../../shared"
+import { detectPluginConfigFile, getOpenCodeConfigPaths, parseJsonc } from "../../../shared"
 import type { OmoConfig } from "./model-resolution-types"
 
-const PACKAGE_NAME = "oh-my-opencode"
-const USER_CONFIG_BASE = join(
-  getOpenCodeConfigPaths({ binary: "opencode", version: null }).configDir,
-  PACKAGE_NAME
-)
-const PROJECT_CONFIG_BASE = join(process.cwd(), ".opencode", PACKAGE_NAME)
+const USER_CONFIG_DIR = getOpenCodeConfigPaths({ binary: "opencode", version: null }).configDir
+const PROJECT_CONFIG_DIR = join(process.cwd(), ".opencode")
 
 export function loadOmoConfig(): OmoConfig | null {
-  const projectDetected = detectConfigFile(PROJECT_CONFIG_BASE)
+  const projectDetected = detectPluginConfigFile(PROJECT_CONFIG_DIR)
   if (projectDetected.format !== "none") {
     try {
       const content = readFileSync(projectDetected.path, "utf-8")
@@ -21,7 +17,7 @@ export function loadOmoConfig(): OmoConfig | null {
     }
   }
 
-  const userDetected = detectConfigFile(USER_CONFIG_BASE)
+  const userDetected = detectPluginConfigFile(USER_CONFIG_DIR)
   if (userDetected.format !== "none") {
     try {
       const content = readFileSync(userDetected.path, "utf-8")

src/cli/doctor/checks/model-resolution-details.ts

@@ -4,6 +4,10 @@ import { getOpenCodeCacheDir } from "../../../shared"
 import type { AvailableModelsInfo, ModelResolutionInfo, OmoConfig } from "./model-resolution-types"
 import { formatModelWithVariant, getCategoryEffectiveVariant, getEffectiveVariant } from "./model-resolution-variant"
 
+function formatCapabilityResolutionLabel(mode: string | undefined): string {
+  return mode ?? "unknown"
+}
+
 export function buildModelResolutionDetails(options: {
   info: ModelResolutionInfo
   available: AvailableModelsInfo
@@ -37,7 +41,7 @@ export function buildModelResolutionDetails(options: {
       agent.effectiveModel,
       getEffectiveVariant(agent.name, agent.requirement, options.config)
     )
-    details.push(`  ${marker} ${agent.name}: ${display}`)
+    details.push(`  ${marker} ${agent.name}: ${display} [capabilities: ${formatCapabilityResolutionLabel(agent.capabilityDiagnostics?.resolutionMode)}]`)
   }
   details.push("")
   details.push("Categories:")
@@ -47,7 +51,7 @@ export function buildModelResolutionDetails(options: {
       category.effectiveModel,
       getCategoryEffectiveVariant(category.name, category.requirement, options.config)
     )
-    details.push(`  ${marker} ${category.name}: ${display}`)
+    details.push(`  ${marker} ${category.name}: ${display} [capabilities: ${formatCapabilityResolutionLabel(category.capabilityDiagnostics?.resolutionMode)}]`)
   }
   details.push("")
   details.push("● = user override, ○ = provider fallback")

src/cli/doctor/checks/model-resolution-types.ts

@@ -1,3 +1,4 @@
+import type { ModelCapabilitiesDiagnostics } from "../../../shared/model-capabilities"
 import type { ModelRequirement } from "../../../shared/model-requirements"
 
 export interface AgentResolutionInfo {
@@ -7,6 +8,7 @@ export interface AgentResolutionInfo {
   userVariant?: string
   effectiveModel: string
   effectiveResolution: string
+  capabilityDiagnostics?: ModelCapabilitiesDiagnostics
 }
 
 export interface CategoryResolutionInfo {
@@ -16,6 +18,7 @@ export interface CategoryResolutionInfo {
   userVariant?: string
   effectiveModel: string
   effectiveResolution: string
+  capabilityDiagnostics?: ModelCapabilitiesDiagnostics
 }
 
 export interface ModelResolutionInfo {

src/cli/doctor/checks/model-resolution.test.ts

@@ -129,6 +129,61 @@ describe("model-resolution check", () => {
       expect(visual!.userOverride).toBe("google/gemini-3-flash-preview")
       expect(visual!.userVariant).toBe("high")
     })
+
+    it("attaches snapshot-backed capability diagnostics for built-in models", async () => {
+      const { getModelResolutionInfoWithOverrides } = await import("./model-resolution")
+
+      const info = getModelResolutionInfoWithOverrides({})
+      const sisyphus = info.agents.find((a) => a.name === "sisyphus")
+
+      expect(sisyphus).toBeDefined()
+      expect(sisyphus!.capabilityDiagnostics).toMatchObject({
+        resolutionMode: "snapshot-backed",
+        snapshot: { source: "bundled-snapshot" },
+      })
+    })
+
+    it("keeps provider-prefixed overrides for transport while capability diagnostics use pattern aliases", async () => {
+      const { getModelResolutionInfoWithOverrides } = await import("./model-resolution")
+
+      const info = getModelResolutionInfoWithOverrides({
+        categories: {
+          "visual-engineering": { model: "google/gemini-3.1-pro-high" },
+        },
+      })
+
+      const visual = info.categories.find((category) => category.name === "visual-engineering")
+      expect(visual).toBeDefined()
+      expect(visual!.effectiveModel).toBe("google/gemini-3.1-pro-high")
+      expect(visual!.capabilityDiagnostics).toMatchObject({
+        resolutionMode: "alias-backed",
+        canonicalization: {
+          source: "pattern-alias",
+          ruleID: "gemini-3.1-pro-tier-alias",
+        },
+      })
+    })
+
+    it("keeps provider-prefixed Claude overrides for transport while capability diagnostics canonicalize to bare IDs", async () => {
+      const { getModelResolutionInfoWithOverrides } = await import("./model-resolution")
+
+      const info = getModelResolutionInfoWithOverrides({
+        agents: {
+          oracle: { model: "anthropic/claude-opus-4-6-thinking" },
+        },
+      })
+
+      const oracle = info.agents.find((agent) => agent.name === "oracle")
+      expect(oracle).toBeDefined()
+      expect(oracle!.effectiveModel).toBe("anthropic/claude-opus-4-6-thinking")
+      expect(oracle!.capabilityDiagnostics).toMatchObject({
+        resolutionMode: "alias-backed",
+        canonicalization: {
+          source: "pattern-alias",
+          ruleID: "claude-thinking-legacy-alias",
+        },
+      })
+    })
   })
 
   describe("checkModelResolution", () => {
@@ -162,6 +217,23 @@ describe("model-resolution check", () => {
       expect(result.details!.some((d) => d.includes("Categories:"))).toBe(true)
       // Should have legend
       expect(result.details!.some((d) => d.includes("user override"))).toBe(true)
+      expect(result.details!.some((d) => d.includes("capabilities: snapshot-backed"))).toBe(true)
+    })
+
+    it("collects warnings when configured models rely on compatibility fallback", async () => {
+      const { collectCapabilityResolutionIssues, getModelResolutionInfoWithOverrides } = await import("./model-resolution")
+
+      const info = getModelResolutionInfoWithOverrides({
+        agents: {
+          oracle: { model: "custom/unknown-llm" },
+        },
+      })
+
+      const issues = collectCapabilityResolutionIssues(info)
+
+      expect(issues).toHaveLength(1)
+      expect(issues[0]?.title).toContain("compatibility fallback")
+      expect(issues[0]?.description).toContain("oracle=custom/unknown-llm")
     })
   })
 

src/cli/doctor/checks/model-resolution.ts

@@ -1,4 +1,5 @@
 import { AGENT_MODEL_REQUIREMENTS, CATEGORY_MODEL_REQUIREMENTS } from "../../../shared/model-requirements"
+import { getModelCapabilities } from "../../../shared/model-capabilities"
 import { CHECK_IDS, CHECK_NAMES } from "../constants"
 import type { CheckResult, DoctorIssue } from "../types"
 import { loadAvailableModelsFromCache } from "./model-resolution-cache"
@@ -7,16 +8,36 @@ import { buildModelResolutionDetails } from "./model-resolution-details"
 import { buildEffectiveResolution, getEffectiveModel } from "./model-resolution-effective-model"
 import type { AgentResolutionInfo, CategoryResolutionInfo, ModelResolutionInfo, OmoConfig } from "./model-resolution-types"
 
-export function getModelResolutionInfo(): ModelResolutionInfo {
-  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) => ({
-    name,
-    requirement,
-    effectiveModel: getEffectiveModel(requirement),
-    effectiveResolution: buildEffectiveResolution(requirement),
-  }))
+function parseProviderModel(value: string): { providerID: string; modelID: string } | null {
+  const slashIndex = value.indexOf("/")
+  if (slashIndex <= 0 || slashIndex === value.length - 1) {
+    return null
+  }
 
-  const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
-    ([name, requirement]) => ({
+  return {
+    providerID: value.slice(0, slashIndex),
+    modelID: value.slice(slashIndex + 1),
+  }
+}
+
+function attachCapabilityDiagnostics<T extends AgentResolutionInfo | CategoryResolutionInfo>(entry: T): T {
+  const parsed = parseProviderModel(entry.effectiveModel)
+  if (!parsed) {
+    return entry
+  }
+
+  return {
+    ...entry,
+    capabilityDiagnostics: getModelCapabilities({
+      providerID: parsed.providerID,
+      modelID: parsed.modelID,
+    }).diagnostics,
+  }
+}
+
+export function getModelResolutionInfo(): ModelResolutionInfo {
+  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) =>
+    attachCapabilityDiagnostics({
       name,
       requirement,
       effectiveModel: getEffectiveModel(requirement),
@@ -24,6 +45,16 @@ export function getModelResolutionInfo(): ModelResolutionInfo {
     })
   )
 
+  const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
+    ([name, requirement]) =>
+      attachCapabilityDiagnostics({
+        name,
+        requirement,
+        effectiveModel: getEffectiveModel(requirement),
+        effectiveResolution: buildEffectiveResolution(requirement),
+      })
+  )
+
   return { agents, categories }
 }
 
@@ -31,34 +62,60 @@ export function getModelResolutionInfoWithOverrides(config: OmoConfig): ModelRes
   const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) => {
     const userOverride = config.agents?.[name]?.model
     const userVariant = config.agents?.[name]?.variant
-    return {
+    return attachCapabilityDiagnostics({
       name,
       requirement,
       userOverride,
       userVariant,
       effectiveModel: getEffectiveModel(requirement, userOverride),
       effectiveResolution: buildEffectiveResolution(requirement, userOverride),
-    }
+    })
   })
 
   const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
     ([name, requirement]) => {
       const userOverride = config.categories?.[name]?.model
       const userVariant = config.categories?.[name]?.variant
-      return {
+      return attachCapabilityDiagnostics({
         name,
         requirement,
         userOverride,
         userVariant,
         effectiveModel: getEffectiveModel(requirement, userOverride),
         effectiveResolution: buildEffectiveResolution(requirement, userOverride),
-      }
+      })
     }
   )
 
   return { agents, categories }
 }
 
+export function collectCapabilityResolutionIssues(info: ModelResolutionInfo): DoctorIssue[] {
+  const issues: DoctorIssue[] = []
+  const allEntries = [...info.agents, ...info.categories]
+  const fallbackEntries = allEntries.filter((entry) => {
+    const mode = entry.capabilityDiagnostics?.resolutionMode
+    return mode === "alias-backed" || mode === "heuristic-backed" || mode === "unknown"
+  })
+
+  if (fallbackEntries.length === 0) {
+    return issues
+  }
+
+  const summary = fallbackEntries
+    .map((entry) => `${entry.name}=${entry.effectiveModel} (${entry.capabilityDiagnostics?.resolutionMode ?? "unknown"})`)
+    .join(", ")
+
+  issues.push({
+    title: "Configured models rely on compatibility fallback",
+    description: summary,
+    severity: "warning",
+    affects: fallbackEntries.map((entry) => entry.name),
+  })
+
+  return issues
+}
+
 export async function checkModels(): Promise<CheckResult> {
   const config = loadOmoConfig() ?? {}
   const info = getModelResolutionInfoWithOverrides(config)
@@ -75,6 +132,8 @@ export async function checkModels(): Promise<CheckResult> {
     })
   }
 
+  issues.push(...collectCapabilityResolutionIssues(info))
+
   const overrideCount =
     info.agents.filter((agent) => Boolean(agent.userOverride)).length +
     info.categories.filter((category) => Boolean(category.userOverride)).length

src/cli/doctor/checks/system-loaded-version.test.ts

@@ -1,9 +1,10 @@
 import { afterEach, describe, expect, it } from "bun:test"
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { dirname, join } from "node:path"
 
 import { PACKAGE_NAME } from "../constants"
+import { resolveSymlink } from "../../../shared/file-utils"
 
 const systemLoadedVersionModulePath = "./system-loaded-version?system-loaded-version-test"
 
@@ -104,6 +105,31 @@ describe("system loaded version", () => {
       expect(loadedVersion.expectedVersion).toBe("2.3.4")
       expect(loadedVersion.loadedVersion).toBe("2.3.4")
     })
+
+    it("resolves symlinked config directories before selecting install path", () => {
+      //#given
+      const realConfigDir = createTemporaryDirectory("omo-real-config-")
+      const symlinkBaseDir = createTemporaryDirectory("omo-symlink-base-")
+      const symlinkConfigDir = join(symlinkBaseDir, "config-link")
+
+      symlinkSync(realConfigDir, symlinkConfigDir, process.platform === "win32" ? "junction" : "dir")
+      process.env.OPENCODE_CONFIG_DIR = symlinkConfigDir
+
+      writeJson(join(realConfigDir, "package.json"), {
+        dependencies: { [PACKAGE_NAME]: "4.5.6" },
+      })
+      writeJson(join(realConfigDir, "node_modules", PACKAGE_NAME, "package.json"), {
+        version: "4.5.6",
+      })
+
+      //#when
+      const loadedVersion = getLoadedPluginVersion()
+
+      //#then
+      expect(loadedVersion.cacheDir).toBe(resolveSymlink(symlinkConfigDir))
+      expect(loadedVersion.expectedVersion).toBe("4.5.6")
+      expect(loadedVersion.loadedVersion).toBe("4.5.6")
+    })
   })
 
   describe("getSuggestedInstallTag", () => {

src/cli/doctor/checks/system-loaded-version.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { join } from "node:path"
-
+import { resolveSymlink } from "../../../shared/file-utils"
 import { getLatestVersion } from "../../../hooks/auto-update-checker/checker"
 import { extractChannel } from "../../../hooks/auto-update-checker"
 import { PACKAGE_NAME } from "../constants"
@@ -36,6 +36,11 @@ function resolveOpenCodeCacheDir(): string {
   return platformDefault
 }
 
+function resolveExistingDir(dirPath: string): string {
+  if (!existsSync(dirPath)) return dirPath
+  return resolveSymlink(dirPath)
+}
+
 function readPackageJson(filePath: string): PackageJsonShape | null {
   if (!existsSync(filePath)) return null
 
@@ -55,12 +60,13 @@ function normalizeVersion(value: string | undefined): string | null {
 
 export function getLoadedPluginVersion(): LoadedVersionInfo {
   const configPaths = getOpenCodeConfigPaths({ binary: "opencode" })
-  const cacheDir = resolveOpenCodeCacheDir()
+  const configDir = resolveExistingDir(configPaths.configDir)
+  const cacheDir = resolveExistingDir(resolveOpenCodeCacheDir())
   const candidates = [
     {
-      cacheDir: configPaths.configDir,
-      cachePackagePath: configPaths.packageJson,
-      installedPackagePath: join(configPaths.configDir, "node_modules", PACKAGE_NAME, "package.json"),
+      cacheDir: configDir,
+      cachePackagePath: join(configDir, "package.json"),
+      installedPackagePath: join(configDir, "node_modules", PACKAGE_NAME, "package.json"),
     },
     {
       cacheDir,

src/cli/install.test.ts

@@ -53,6 +53,14 @@ describe("install CLI - binary check behavior", () => {
     isOpenCodeInstalledSpy = spyOn(configManager, "isOpenCodeInstalled").mockResolvedValue(false)
     getOpenCodeVersionSpy = spyOn(configManager, "getOpenCodeVersion").mockResolvedValue(null)
 
+    // given mock npm fetch
+    globalThis.fetch = mock(() =>
+      Promise.resolve({
+        ok: true,
+        json: () => Promise.resolve({ latest: "3.0.0" }),
+      } as Response)
+    ) as unknown as typeof fetch
+
     const args: InstallArgs = {
       tui: false,
       claude: "yes",

src/cli/model-fallback.ts

@@ -55,7 +55,7 @@ export function generateModelConfig(config: InstallConfig): GeneratedOmoConfig {
   for (const [role, req] of Object.entries(CLI_AGENT_MODEL_REQUIREMENTS)) {
     if (role === "librarian") {
       if (avail.opencodeGo) {
-        agents[role] = { model: "opencode-go/minimax-m2.5" }
+        agents[role] = { model: "opencode-go/minimax-m2.7" }
       } else if (avail.zai) {
         agents[role] = { model: ZAI_MODEL }
       }
@@ -68,7 +68,7 @@ export function generateModelConfig(config: InstallConfig): GeneratedOmoConfig {
       } else if (avail.opencodeZen) {
         agents[role] = { model: "opencode/claude-haiku-4-5" }
       } else if (avail.opencodeGo) {
-        agents[role] = { model: "opencode-go/minimax-m2.5" }
+        agents[role] = { model: "opencode-go/minimax-m2.7" }
       } else if (avail.copilot) {
         agents[role] = { model: "github-copilot/gpt-5-mini" }
       } else {

src/cli/openai-only-model-catalog.test.ts

@@ -40,7 +40,7 @@ describe("generateModelConfig OpenAI-only model catalog", () => {
 
     // #then
     expect(result.categories?.artistry).toEqual({ model: "openai/gpt-5.4", variant: "xhigh" })
-    expect(result.categories?.quick).toEqual({ model: "openai/gpt-5.3-codex", variant: "low" })
+    expect(result.categories?.quick).toEqual({ model: "openai/gpt-5.4-mini" })
     expect(result.categories?.["visual-engineering"]).toEqual({ model: "openai/gpt-5.4", variant: "high" })
     expect(result.categories?.writing).toEqual({ model: "openai/gpt-5.4", variant: "medium" })
   })
@@ -53,8 +53,8 @@ describe("generateModelConfig OpenAI-only model catalog", () => {
     const result = generateModelConfig(config)
 
     // #then
-    expect(result.agents?.explore).toEqual({ model: "opencode-go/minimax-m2.5" })
-    expect(result.agents?.librarian).toEqual({ model: "opencode-go/minimax-m2.5" })
-    expect(result.categories?.quick).toEqual({ model: "opencode-go/minimax-m2.5" })
+    expect(result.agents?.explore).toEqual({ model: "opencode-go/minimax-m2.7" })
+    expect(result.agents?.librarian).toEqual({ model: "opencode-go/minimax-m2.7" })
+    expect(result.categories?.quick).toEqual({ model: "openai/gpt-5.4-mini" })
   })
 })

src/cli/openai-only-model-catalog.ts

@@ -7,7 +7,7 @@ const OPENAI_ONLY_AGENT_OVERRIDES: Record<string, AgentConfig> = {
 
 const OPENAI_ONLY_CATEGORY_OVERRIDES: Record<string, CategoryConfig> = {
   artistry: { model: "openai/gpt-5.4", variant: "xhigh" },
-  quick: { model: "openai/gpt-5.3-codex", variant: "low" },
+  quick: { model: "openai/gpt-5.4-mini" },
   "visual-engineering": { model: "openai/gpt-5.4", variant: "high" },
   writing: { model: "openai/gpt-5.4", variant: "medium" },
 }

src/cli/refresh-model-capabilities.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, mock } from "bun:test"
+
+import { refreshModelCapabilities } from "./refresh-model-capabilities"
+
+describe("refreshModelCapabilities", () => {
+  it("uses config source_url when CLI override is absent", async () => {
+    const loadConfig = mock(() => ({
+      model_capabilities: {
+        source_url: "https://mirror.example/api.json",
+      },
+    }))
+    const refreshCache = mock(async () => ({
+      generatedAt: "2026-03-25T00:00:00.000Z",
+      sourceUrl: "https://mirror.example/api.json",
+      models: {
+        "gpt-5.4": { id: "gpt-5.4" },
+      },
+    }))
+    let stdout = ""
+
+    const exitCode = await refreshModelCapabilities(
+      { directory: "/repo", json: false },
+      {
+        loadConfig,
+        refreshCache,
+        stdout: {
+          write: (chunk: string) => {
+            stdout += chunk
+            return true
+          },
+        } as never,
+        stderr: {
+          write: () => true,
+        } as never,
+      },
+    )
+
+    expect(exitCode).toBe(0)
+    expect(loadConfig).toHaveBeenCalledWith("/repo", null)
+    expect(refreshCache).toHaveBeenCalledWith({
+      sourceUrl: "https://mirror.example/api.json",
+    })
+    expect(stdout).toContain("Refreshed model capabilities cache (1 models)")
+  })
+
+  it("CLI sourceUrl overrides config and supports json output", async () => {
+    const refreshCache = mock(async () => ({
+      generatedAt: "2026-03-25T00:00:00.000Z",
+      sourceUrl: "https://override.example/api.json",
+      models: {
+        "gpt-5.4": { id: "gpt-5.4" },
+        "claude-opus-4-6": { id: "claude-opus-4-6" },
+      },
+    }))
+    let stdout = ""
+
+    const exitCode = await refreshModelCapabilities(
+      {
+        directory: "/repo",
+        json: true,
+        sourceUrl: "https://override.example/api.json",
+      },
+      {
+        loadConfig: () => ({}),
+        refreshCache,
+        stdout: {
+          write: (chunk: string) => {
+            stdout += chunk
+            return true
+          },
+        } as never,
+        stderr: {
+          write: () => true,
+        } as never,
+      },
+    )
+
+    expect(exitCode).toBe(0)
+    expect(refreshCache).toHaveBeenCalledWith({
+      sourceUrl: "https://override.example/api.json",
+    })
+    expect(JSON.parse(stdout)).toEqual({
+      sourceUrl: "https://override.example/api.json",
+      generatedAt: "2026-03-25T00:00:00.000Z",
+      modelCount: 2,
+    })
+  })
+
+  it("returns exit code 1 when refresh fails", async () => {
+    let stderr = ""
+
+    const exitCode = await refreshModelCapabilities(
+      { directory: "/repo" },
+      {
+        loadConfig: () => ({}),
+        refreshCache: async () => {
+          throw new Error("boom")
+        },
+        stdout: {
+          write: () => true,
+        } as never,
+        stderr: {
+          write: (chunk: string) => {
+            stderr += chunk
+            return true
+          },
+        } as never,
+      },
+    )
+
+    expect(exitCode).toBe(1)
+    expect(stderr).toContain("Failed to refresh model capabilities cache")
+  })
+})

src/cli/refresh-model-capabilities.ts

@@ -0,0 +1,51 @@
+import { loadPluginConfig } from "../plugin-config"
+import { refreshModelCapabilitiesCache } from "../shared/model-capabilities-cache"
+
+export type RefreshModelCapabilitiesOptions = {
+  directory?: string
+  json?: boolean
+  sourceUrl?: string
+}
+
+type RefreshModelCapabilitiesDeps = {
+  loadConfig?: typeof loadPluginConfig
+  refreshCache?: typeof refreshModelCapabilitiesCache
+  stdout?: Pick<typeof process.stdout, "write">
+  stderr?: Pick<typeof process.stderr, "write">
+}
+
+export async function refreshModelCapabilities(
+  options: RefreshModelCapabilitiesOptions,
+  deps: RefreshModelCapabilitiesDeps = {},
+): Promise<number> {
+  const directory = options.directory ?? process.cwd()
+  const loadConfig = deps.loadConfig ?? loadPluginConfig
+  const refreshCache = deps.refreshCache ?? refreshModelCapabilitiesCache
+  const stdout = deps.stdout ?? process.stdout
+  const stderr = deps.stderr ?? process.stderr
+
+  try {
+    const config = loadConfig(directory, null)
+    const sourceUrl = options.sourceUrl ?? config.model_capabilities?.source_url
+    const snapshot = await refreshCache({ sourceUrl })
+
+    const summary = {
+      sourceUrl: snapshot.sourceUrl,
+      generatedAt: snapshot.generatedAt,
+      modelCount: Object.keys(snapshot.models).length,
+    }
+
+    if (options.json) {
+      stdout.write(`${JSON.stringify(summary, null, 2)}\n`)
+    } else {
+      stdout.write(
+        `Refreshed model capabilities cache (${summary.modelCount} models) from ${summary.sourceUrl}\n`,
+      )
+    }
+
+    return 0
+  } catch (error) {
+    stderr.write(`Failed to refresh model capabilities cache: ${String(error)}\n`)
+    return 1
+  }
+}

src/cli/run/output-renderer.ts

@@ -45,26 +45,26 @@ export function writePaddedText(
     return { output: text, atLineStart: text.endsWith("\n") }
   }
 
-  let output = ""
+  const parts: string[] = []
   let lineStart = atLineStart
 
   for (let i = 0; i < text.length; i++) {
     const ch = text[i]
     if (lineStart) {
-      output += "  "
+      parts.push("  ")
       lineStart = false
     }
 
     if (ch === "\n") {
-      output += "  \n"
+      parts.push("  \n")
       lineStart = true
       continue
     }
 
-    output += ch
+    parts.push(ch)
   }
 
-  return { output, atLineStart: lineStart }
+  return { output: parts.join(""), atLineStart: lineStart }
 }
 
 function colorizeWithProfileColor(text: string, hexColor?: string): string {

src/cli/run/runner.test.ts

@@ -115,6 +115,42 @@ describe("waitForEventProcessorShutdown", () => {
   })
 })
 
+describe("run environment setup", () => {
+  let originalClient: string | undefined
+  let originalRunMode: string | undefined
+
+  beforeEach(() => {
+    originalClient = process.env.OPENCODE_CLIENT
+    originalRunMode = process.env.OPENCODE_CLI_RUN_MODE
+  })
+
+  afterEach(() => {
+    if (originalClient === undefined) {
+      delete process.env.OPENCODE_CLIENT
+    } else {
+      process.env.OPENCODE_CLIENT = originalClient
+    }
+    if (originalRunMode === undefined) {
+      delete process.env.OPENCODE_CLI_RUN_MODE
+    } else {
+      process.env.OPENCODE_CLI_RUN_MODE = originalRunMode
+    }
+  })
+
+  it("sets OPENCODE_CLIENT to 'run' to exclude question tool from registry", async () => {
+    //#given
+    delete process.env.OPENCODE_CLIENT
+
+    //#when - run() sets env vars synchronously before any async work
+    const { run } = await import(`./runner?env-setup-${Date.now()}`)
+    run({ message: "test" }).catch(() => {})
+
+    //#then
+    expect(String(process.env.OPENCODE_CLIENT)).toBe("run")
+    expect(String(process.env.OPENCODE_CLI_RUN_MODE)).toBe("true")
+  })
+})
+
 describe("run with invalid model", () => {
   it("given invalid --model value, when run, then returns exit code 1 with error message", async () => {
     // given

src/cli/run/runner.ts

@@ -31,6 +31,7 @@ export async function waitForEventProcessorShutdown(
 
 export async function run(options: RunOptions): Promise<number> {
   process.env.OPENCODE_CLI_RUN_MODE = "true"
+  process.env.OPENCODE_CLIENT = "run"
 
   const startTime = Date.now()
   const {

src/cli/tui-install-prompts.ts

@@ -54,7 +54,7 @@ export async function promptInstallConfig(detected: DetectedConfig): Promise<Ins
     message: "Will you integrate Google Gemini?",
     options: [
       { value: "no", label: "No", hint: "Frontend/docs agents will use fallback" },
-      { value: "yes", label: "Yes", hint: "Beautiful UI generation with Gemini 3 Pro" },
+      { value: "yes", label: "Yes", hint: "Beautiful UI generation with Gemini 3.1 Pro" },
     ],
     initialValue: initial.gemini,
   })

src/config/AGENTS.md

@@ -14,7 +14,7 @@ config/schema/
 ├── agent-names.ts              # BuiltinAgentNameSchema (11), OverridableAgentNameSchema (14)
 ├── agent-overrides.ts          # AgentOverrideConfigSchema (21 fields per agent)
 ├── categories.ts               # 8 built-in + custom categories
-├── hooks.ts                    # HookNameSchema (46 hooks)
+├── hooks.ts                    # HookNameSchema (48 hooks)
 ├── skills.ts                   # SkillsConfigSchema (sources, paths, recursive)
 ├── commands.ts                 # BuiltinCommandNameSchema
 ├── experimental.ts             # Feature flags (plugin_load_timeout_ms min 1000)

src/config/index.ts

@@ -19,5 +19,6 @@ export type {
   SisyphusConfig,
   SisyphusTasksConfig,
   RuntimeFallbackConfig,
+  ModelCapabilitiesConfig,
   FallbackModels,
 } from "./schema"

src/config/schema.test.ts

@@ -147,6 +147,37 @@ describe("disabled_mcps schema", () => {
   })
 })
 
+describe("OhMyOpenCodeConfigSchema - model_capabilities", () => {
+  test("accepts valid model capabilities config", () => {
+    const input = {
+      model_capabilities: {
+        enabled: true,
+        auto_refresh_on_start: true,
+        refresh_timeout_ms: 5000,
+        source_url: "https://models.dev/api.json",
+      },
+    }
+
+    const result = OhMyOpenCodeConfigSchema.safeParse(input)
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.model_capabilities).toEqual(input.model_capabilities)
+    }
+  })
+
+  test("rejects invalid model capabilities config", () => {
+    const result = OhMyOpenCodeConfigSchema.safeParse({
+      model_capabilities: {
+        refresh_timeout_ms: -1,
+        source_url: "not-a-url",
+      },
+    })
+
+    expect(result.success).toBe(false)
+  })
+})
+
 describe("AgentOverrideConfigSchema", () => {
   describe("category field", () => {
     test("accepts category as optional string", () => {
@@ -371,6 +402,26 @@ describe("CategoryConfigSchema", () => {
     }
   })
 
+  test("accepts reasoningEffort values none and minimal", () => {
+    // given
+    const noneConfig = { reasoningEffort: "none" }
+    const minimalConfig = { reasoningEffort: "minimal" }
+
+    // when
+    const noneResult = CategoryConfigSchema.safeParse(noneConfig)
+    const minimalResult = CategoryConfigSchema.safeParse(minimalConfig)
+
+    // then
+    expect(noneResult.success).toBe(true)
+    expect(minimalResult.success).toBe(true)
+    if (noneResult.success) {
+      expect(noneResult.data.reasoningEffort).toBe("none")
+    }
+    if (minimalResult.success) {
+      expect(minimalResult.data.reasoningEffort).toBe("minimal")
+    }
+  })
+
   test("rejects non-string variant", () => {
     // given
     const config = { model: "openai/gpt-5.4", variant: 123 }

src/config/schema.ts

@@ -13,6 +13,7 @@ export * from "./schema/fallback-models"
 export * from "./schema/git-env-prefix"
 export * from "./schema/git-master"
 export * from "./schema/hooks"
+export * from "./schema/model-capabilities"
 export * from "./schema/notification"
 export * from "./schema/oh-my-opencode-config"
 export * from "./schema/ralph-loop"

src/config/schema/agent-overrides.ts

@@ -35,7 +35,7 @@ export const AgentOverrideConfigSchema = z.object({
     })
     .optional(),
   /** Reasoning effort level (OpenAI). Overrides category and default settings. */
-  reasoningEffort: z.enum(["low", "medium", "high", "xhigh"]).optional(),
+  reasoningEffort: z.enum(["none", "minimal", "low", "medium", "high", "xhigh"]).optional(),
   /** Text verbosity level. */
   textVerbosity: z.enum(["low", "medium", "high"]).optional(),
   /** Provider-specific options. Passed directly to OpenCode SDK. */

src/config/schema/background-task-circuit-breaker.test.ts

@@ -8,27 +8,24 @@ describe("BackgroundTaskConfigSchema.circuitBreaker", () => {
       const result = BackgroundTaskConfigSchema.parse({
         circuitBreaker: {
           maxToolCalls: 150,
-          windowSize: 10,
-          repetitionThresholdPercent: 70,
+          consecutiveThreshold: 10,
         },
       })
-
       expect(result.circuitBreaker).toEqual({
         maxToolCalls: 150,
-        windowSize: 10,
-        repetitionThresholdPercent: 70,
+        consecutiveThreshold: 10,
       })
     })
   })
 
-  describe("#given windowSize below minimum", () => {
+  describe("#given consecutiveThreshold below minimum", () => {
     test("#when parsed #then throws ZodError", () => {
       let thrownError: unknown
 
       try {
         BackgroundTaskConfigSchema.parse({
           circuitBreaker: {
-            windowSize: 4,
+            consecutiveThreshold: 4,
           },
         })
       } catch (error) {
@@ -39,14 +36,14 @@ describe("BackgroundTaskConfigSchema.circuitBreaker", () => {
     })
   })
 
-  describe("#given repetitionThresholdPercent is zero", () => {
+  describe("#given consecutiveThreshold is zero", () => {
     test("#when parsed #then throws ZodError", () => {
       let thrownError: unknown
 
       try {
         BackgroundTaskConfigSchema.parse({
           circuitBreaker: {
-            repetitionThresholdPercent: 0,
+            consecutiveThreshold: 0,
           },
         })
       } catch (error) {

src/config/schema/background-task.ts

@@ -3,8 +3,7 @@ import { z } from "zod"
 const CircuitBreakerConfigSchema = z.object({
   enabled: z.boolean().optional(),
   maxToolCalls: z.number().int().min(10).optional(),
-  windowSize: z.number().int().min(5).optional(),
-  repetitionThresholdPercent: z.number().gt(0).max(100).optional(),
+  consecutiveThreshold: z.number().int().min(5).optional(),
 })
 
 export const BackgroundTaskConfigSchema = z.object({

src/config/schema/categories.ts

@@ -16,7 +16,7 @@ export const CategoryConfigSchema = z.object({
       budgetTokens: z.number().optional(),
     })
     .optional(),
-  reasoningEffort: z.enum(["low", "medium", "high", "xhigh"]).optional(),
+  reasoningEffort: z.enum(["none", "minimal", "low", "medium", "high", "xhigh"]).optional(),
   textVerbosity: z.enum(["low", "medium", "high"]).optional(),
   tools: z.record(z.string(), z.boolean()).optional(),
   prompt_append: z.string().optional(),

src/config/schema/fallback-models.ts

@@ -1,5 +1,25 @@
 import { z } from "zod"
 
-export const FallbackModelsSchema = z.union([z.string(), z.array(z.string())])
+export const FallbackModelObjectSchema = z.object({
+  model: z.string(),
+  variant: z.string().optional(),
+  reasoningEffort: z.enum(["none", "minimal", "low", "medium", "high", "xhigh"]).optional(),
+  temperature: z.number().min(0).max(2).optional(),
+  top_p: z.number().min(0).max(1).optional(),
+  maxTokens: z.number().optional(),
+  thinking: z
+    .object({
+      type: z.enum(["enabled", "disabled"]),
+      budgetTokens: z.number().optional(),
+    })
+    .optional(),
+})
+
+export type FallbackModelObject = z.infer<typeof FallbackModelObjectSchema>
+
+export const FallbackModelsSchema = z.union([
+  z.string(),
+  z.array(z.union([z.string(), FallbackModelObjectSchema])),
+])
 
 export type FallbackModels = z.infer<typeof FallbackModelsSchema>

src/config/schema/hooks.ts

@@ -1,7 +1,6 @@
 import { z } from "zod"
 
 export const HookNameSchema = z.enum([
-  "gpt-permission-continuation",
   "todo-continuation-enforcer",
   "context-window-monitor",
   "session-recovery",
@@ -52,6 +51,7 @@ export const HookNameSchema = z.enum([
   "hashline-read-enhancer",
   "read-image-resizer",
   "todo-description-override",
+  "webfetch-redirect-guard",
 ])
 
 export type HookName = z.infer<typeof HookNameSchema>

src/config/schema/model-capabilities.ts

@@ -0,0 +1,10 @@
+import { z } from "zod"
+
+export const ModelCapabilitiesConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  auto_refresh_on_start: z.boolean().optional(),
+  refresh_timeout_ms: z.number().int().positive().optional(),
+  source_url: z.string().url().optional(),
+})
+
+export type ModelCapabilitiesConfig = z.infer<typeof ModelCapabilitiesConfigSchema>

src/config/schema/oh-my-opencode-config.ts

@@ -12,6 +12,8 @@ import { BuiltinCommandNameSchema } from "./commands"
 import { ExperimentalConfigSchema } from "./experimental"
 import { GitMasterConfigSchema } from "./git-master"
 import { NotificationConfigSchema } from "./notification"
+import { OpenClawConfigSchema } from "./openclaw"
+import { ModelCapabilitiesConfigSchema } from "./model-capabilities"
 import { RalphLoopConfigSchema } from "./ralph-loop"
 import { RuntimeFallbackConfigSchema } from "./runtime-fallback"
 import { SkillsConfigSchema } from "./skills"
@@ -55,6 +57,8 @@ export const OhMyOpenCodeConfigSchema = z.object({
   runtime_fallback: z.union([z.boolean(), RuntimeFallbackConfigSchema]).optional(),
   background_task: BackgroundTaskConfigSchema.optional(),
   notification: NotificationConfigSchema.optional(),
+  model_capabilities: ModelCapabilitiesConfigSchema.optional(),
+  openclaw: OpenClawConfigSchema.optional(),
   babysitting: BabysittingConfigSchema.optional(),
   git_master: GitMasterConfigSchema.optional(),
   browser_automation_engine: BrowserAutomationConfigSchema.optional(),

src/config/schema/openclaw.ts

@@ -0,0 +1,50 @@
+import { z } from "zod"
+
+export const OpenClawGatewaySchema = z.object({
+  type: z.enum(["http", "command"]).default("http"),
+  // HTTP specific
+  url: z.string().optional(),
+  method: z.string().default("POST"),
+  headers: z.record(z.string(), z.string()).optional(),
+  // Command specific
+  command: z.string().optional(),
+  // Shared
+  timeout: z.number().optional(),
+})
+
+export const OpenClawHookSchema = z.object({
+  enabled: z.boolean().default(true),
+  gateway: z.string(),
+  instruction: z.string(),
+})
+
+export const OpenClawReplyListenerConfigSchema = z.object({
+  discordBotToken: z.string().optional(),
+  discordChannelId: z.string().optional(),
+  discordMention: z.string().optional(), // For allowed_mentions
+  authorizedDiscordUserIds: z.array(z.string()).default([]),
+
+  telegramBotToken: z.string().optional(),
+  telegramChatId: z.string().optional(),
+
+  pollIntervalMs: z.number().default(3000),
+  rateLimitPerMinute: z.number().default(10),
+  maxMessageLength: z.number().default(500),
+  includePrefix: z.boolean().default(true),
+})
+
+export const OpenClawConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+
+  // Outbound Configuration
+  gateways: z.record(z.string(), OpenClawGatewaySchema).default({}),
+  hooks: z.record(z.string(), OpenClawHookSchema).default({}),
+
+  // Inbound Configuration (Reply Listener)
+  replyListener: OpenClawReplyListenerConfigSchema.optional(),
+})
+
+export type OpenClawConfig = z.infer<typeof OpenClawConfigSchema>
+export type OpenClawGateway = z.infer<typeof OpenClawGatewaySchema>
+export type OpenClawHook = z.infer<typeof OpenClawHookSchema>
+export type OpenClawReplyListenerConfig = z.infer<typeof OpenClawReplyListenerConfigSchema>

src/features/background-agent/constants.ts

@@ -4,11 +4,10 @@ import type { BackgroundTask, LaunchInput } from "./types"
 export const TASK_TTL_MS = 30 * 60 * 1000
 export const TERMINAL_TASK_TTL_MS = 30 * 60 * 1000
 export const MIN_STABILITY_TIME_MS = 10 * 1000
-export const DEFAULT_STALE_TIMEOUT_MS = 1_200_000
-export const DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS = 1_800_000
-export const DEFAULT_MAX_TOOL_CALLS = 200
-export const DEFAULT_CIRCUIT_BREAKER_WINDOW_SIZE = 20
-export const DEFAULT_CIRCUIT_BREAKER_REPETITION_THRESHOLD_PERCENT = 80
+export const DEFAULT_STALE_TIMEOUT_MS = 2_700_000
+export const DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS = 3_600_000
+export const DEFAULT_MAX_TOOL_CALLS = 4000
+export const DEFAULT_CIRCUIT_BREAKER_CONSECUTIVE_THRESHOLD = 20
 export const DEFAULT_CIRCUIT_BREAKER_ENABLED = true
 export const MIN_RUNTIME_BEFORE_STALE_MS = 30_000
 export const MIN_IDLE_TIME_MS = 5000

src/features/background-agent/default-message-staleness-timeout.test.ts

@@ -21,9 +21,9 @@ function createRunningTask(startedAt: Date): BackgroundTask {
 }
 
 describe("DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS", () => {
-  test("uses a 30 minute default", () => {
+  test("uses a 60 minute default", () => {
     // #given
-    const expectedTimeout = 30 * 60 * 1000
+    const expectedTimeout = 60 * 60 * 1000
 
     // #when
     const timeout = DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS

src/features/background-agent/default-stale-timeout.test.ts

@@ -4,9 +4,9 @@ const { describe, expect, test } = require("bun:test")
 import { DEFAULT_STALE_TIMEOUT_MS } from "./constants"
 
 describe("DEFAULT_STALE_TIMEOUT_MS", () => {
-  test("uses a 20 minute default", () => {
+  test("uses a 45 minute default", () => {
     // #given
-    const expectedTimeout = 20 * 60 * 1000
+    const expectedTimeout = 45 * 60 * 1000
 
     // #when
     const timeout = DEFAULT_STALE_TIMEOUT_MS

src/features/background-agent/fallback-retry-handler.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, mock, beforeEach } from "bun:test"
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test"
 
 mock.module("../../shared", () => ({
   log: mock(() => {}),
@@ -19,6 +19,8 @@ mock.module("../../shared/provider-model-id-transform", () => ({
 
 import { tryFallbackRetry } from "./fallback-retry-handler"
 import { shouldRetryError } from "../../shared/model-error-classifier"
+import { selectFallbackProvider } from "../../shared/model-error-classifier"
+import { readProviderModelsCache } from "../../shared"
 import type { BackgroundTask } from "./types"
 import type { ConcurrencyManager } from "./concurrency"
 
@@ -80,8 +82,14 @@ function createDefaultArgs(taskOverrides: Partial<BackgroundTask> = {}) {
 }
 
 describe("tryFallbackRetry", () => {
+  afterAll(() => {
+    mock.restore()
+  })
+
   beforeEach(() => {
     ;(shouldRetryError as any).mockImplementation(() => true)
+    ;(selectFallbackProvider as any).mockImplementation((providers: string[]) => providers[0])
+    ;(readProviderModelsCache as any).mockReturnValue(null)
   })
 
   describe("#given retryable error with fallback chain", () => {
@@ -267,4 +275,24 @@ describe("tryFallbackRetry", () => {
       expect(args.task.attemptCount).toBe(2)
     })
   })
+
+  describe("#given disconnected fallback providers with connected preferred provider", () => {
+    test("keeps fallback entry and selects connected preferred provider", () => {
+      ;(readProviderModelsCache as any).mockReturnValueOnce({ connected: ["provider-a"] })
+      ;(selectFallbackProvider as any).mockImplementationOnce(
+        (_providers: string[], preferredProviderID?: string) => preferredProviderID ?? "provider-b",
+      )
+
+      const args = createDefaultArgs({
+        fallbackChain: [{ model: "fallback-model-1", providers: ["provider-b"], variant: undefined }],
+        model: { providerID: "provider-a", modelID: "original-model" },
+      })
+
+      const result = tryFallbackRetry(args)
+
+      expect(result).toBe(true)
+      expect(args.task.model?.providerID).toBe("provider-a")
+      expect(args.task.model?.modelID).toBe("fallback-model-1")
+    })
+  })
 })

src/features/background-agent/fallback-retry-handler.ts

@@ -35,10 +35,14 @@ export function tryFallbackRetry(args: {
   const providerModelsCache = readProviderModelsCache()
   const connectedProviders = providerModelsCache?.connected ?? readConnectedProvidersCache()
   const connectedSet = connectedProviders ? new Set(connectedProviders.map(p => p.toLowerCase())) : null
+  const preferredProvider = task.model?.providerID?.toLowerCase()
 
   const isReachable = (entry: FallbackEntry): boolean => {
     if (!connectedSet) return true
-    return entry.providers.some((p) => connectedSet.has(p.toLowerCase()))
+    if (entry.providers.some((provider) => connectedSet.has(provider.toLowerCase()))) {
+      return true
+    }
+    return preferredProvider ? connectedSet.has(preferredProvider) : false
   }
 
   let selectedAttemptCount = attemptCount

src/features/background-agent/loop-detector.test.ts

@@ -1,3 +1,5 @@
+/// <reference types="bun-types" />
+
 import { describe, expect, test } from "bun:test"
 import {
   createToolCallSignature,
@@ -19,7 +21,7 @@ function buildWindow(
 }
 
 function buildWindowWithInputs(
-  calls: Array<{ tool: string; input?: Record<string, unknown> }>,
+  calls: Array<{ tool: string; input?: Record<string, unknown> | null }>,
   override?: Parameters<typeof resolveCircuitBreakerSettings>[0]
 ) {
   const settings = resolveCircuitBreakerSettings(override)
@@ -37,16 +39,14 @@ describe("loop-detector", () => {
           maxToolCalls: 200,
           circuitBreaker: {
             maxToolCalls: 120,
-            windowSize: 10,
-            repetitionThresholdPercent: 70,
+            consecutiveThreshold: 7,
           },
         })
 
         expect(result).toEqual({
           enabled: true,
           maxToolCalls: 120,
-          windowSize: 10,
-          repetitionThresholdPercent: 70,
+          consecutiveThreshold: 7,
         })
       })
     })
@@ -56,8 +56,7 @@ describe("loop-detector", () => {
         const result = resolveCircuitBreakerSettings({
           circuitBreaker: {
             maxToolCalls: 100,
-            windowSize: 5,
-            repetitionThresholdPercent: 60,
+            consecutiveThreshold: 5,
           },
         })
 
@@ -71,8 +70,7 @@ describe("loop-detector", () => {
           circuitBreaker: {
             enabled: false,
             maxToolCalls: 100,
-            windowSize: 5,
-            repetitionThresholdPercent: 60,
+            consecutiveThreshold: 5,
           },
         })
 
@@ -86,8 +84,7 @@ describe("loop-detector", () => {
           circuitBreaker: {
             enabled: true,
             maxToolCalls: 100,
-            windowSize: 5,
-            repetitionThresholdPercent: 60,
+            consecutiveThreshold: 5,
           },
         })
 
@@ -151,55 +148,67 @@ describe("loop-detector", () => {
       })
     })
 
-    describe("#given the same tool dominates the recent window", () => {
+    describe("#given the same tool is called consecutively", () => {
       test("#when evaluated #then it triggers", () => {
-        const window = buildWindow([
-          "read",
-          "read",
-          "read",
-          "edit",
-          "read",
-          "read",
-          "read",
-          "read",
-          "grep",
-          "read",
-        ], {
-          circuitBreaker: {
-            windowSize: 10,
-            repetitionThresholdPercent: 80,
-          },
-        })
+        const window = buildWindowWithInputs(
+          Array.from({ length: 20 }, () => ({
+            tool: "read",
+            input: { filePath: "/src/same.ts" },
+          }))
+        )
 
         const result = detectRepetitiveToolUse(window)
 
         expect(result).toEqual({
           triggered: true,
           toolName: "read",
-          repeatedCount: 8,
-          sampleSize: 10,
-          thresholdPercent: 80,
+          repeatedCount: 20,
         })
       })
     })
 
-    describe("#given the window is not full yet", () => {
-      test("#when the current sample crosses the threshold #then it still triggers", () => {
-        const window = buildWindow(["read", "read", "edit", "read", "read", "read", "read", "read"], {
-          circuitBreaker: {
-            windowSize: 10,
-            repetitionThresholdPercent: 80,
-          },
-        })
+    describe("#given consecutive calls are interrupted by different tool", () => {
+      test("#when evaluated #then it does not trigger", () => {
+        const window = buildWindow([
+          ...Array.from({ length: 19 }, () => "read"),
+          "edit",
+          "read",
+        ])
 
         const result = detectRepetitiveToolUse(window)
 
+        expect(result).toEqual({ triggered: false })
+      })
+    })
+
+    describe("#given threshold boundary", () => {
+      test("#when below threshold #then it does not trigger", () => {
+        const belowThresholdWindow = buildWindowWithInputs(
+          Array.from({ length: 19 }, () => ({
+            tool: "read",
+            input: { filePath: "/src/same.ts" },
+          }))
+        )
+
+        const result = detectRepetitiveToolUse(belowThresholdWindow)
+
+        expect(result).toEqual({ triggered: false })
+      })
+
+      test("#when equal to threshold #then it triggers", () => {
+        const atThresholdWindow = buildWindowWithInputs(
+          Array.from({ length: 20 }, () => ({
+            tool: "read",
+            input: { filePath: "/src/same.ts" },
+          }))
+        )
+
+        const result = detectRepetitiveToolUse(atThresholdWindow)
+
         expect(result).toEqual({
           triggered: true,
           toolName: "read",
-          repeatedCount: 7,
-          sampleSize: 8,
-          thresholdPercent: 80,
+          repeatedCount: 20,
         })
       })
     })
@@ -210,9 +219,7 @@ describe("loop-detector", () => {
           tool: "read",
           input: { filePath: `/src/file-${i}.ts` },
         }))
-        const window = buildWindowWithInputs(calls, {
-          circuitBreaker: { windowSize: 20, repetitionThresholdPercent: 80 },
-        })
+        const window = buildWindowWithInputs(calls)
         const result = detectRepetitiveToolUse(window)
         expect(result.triggered).toBe(false)
       })
@@ -220,38 +227,36 @@ describe("loop-detector", () => {
 
     describe("#given same tool with identical file inputs", () => {
       test("#when evaluated #then it triggers with bare tool name", () => {
-        const calls = [
-          ...Array.from({ length: 16 }, () => ({ tool: "read", input: { filePath: "/src/same.ts" } })),
-          { tool: "grep", input: { pattern: "foo" } },
-          { tool: "edit", input: { filePath: "/src/other.ts" } },
-          { tool: "bash", input: { command: "ls" } },
-          { tool: "glob", input: { pattern: "**/*.ts" } },
-        ]
-        const window = buildWindowWithInputs(calls, {
-          circuitBreaker: { windowSize: 20, repetitionThresholdPercent: 80 },
-        })
+        const calls = Array.from({ length: 20 }, () => ({
+          tool: "read",
+          input: { filePath: "/src/same.ts" },
+        }))
+        const window = buildWindowWithInputs(calls)
         const result = detectRepetitiveToolUse(window)
-        expect(result.triggered).toBe(true)
-        expect(result.toolName).toBe("read")
-        expect(result.repeatedCount).toBe(16)
+        expect(result).toEqual({
+          triggered: true,
+          toolName: "read",
+          repeatedCount: 20,
+        })
       })
     })
 
-    describe("#given tool calls with no input", () => {
-      test("#when the same tool dominates #then falls back to name-only detection", () => {
-        const calls = [
-          ...Array.from({ length: 16 }, () => ({ tool: "read" })),
-          { tool: "grep" },
-          { tool: "edit" },
-          { tool: "bash" },
-          { tool: "glob" },
-        ]
-        const window = buildWindowWithInputs(calls, {
-          circuitBreaker: { windowSize: 20, repetitionThresholdPercent: 80 },
-        })
+    describe("#given tool calls with undefined input", () => {
+      test("#when evaluated #then it does not trigger", () => {
+        const calls = Array.from({ length: 20 }, () => ({ tool: "read" }))
+        const window = buildWindowWithInputs(calls)
         const result = detectRepetitiveToolUse(window)
-        expect(result.triggered).toBe(true)
-        expect(result.toolName).toBe("read")
+        expect(result).toEqual({ triggered: false })
+      })
+    })
+
+    describe("#given tool calls with null input", () => {
+      test("#when evaluated #then it does not trigger", () => {
+        const calls = Array.from({ length: 20 }, () => ({ tool: "read", input: null }))
+        const window = buildWindowWithInputs(calls)
+        const result = detectRepetitiveToolUse(window)
+
+        expect(result).toEqual({ triggered: false })
       })
     })
   })

src/features/background-agent/loop-detector.ts

@@ -1,8 +1,7 @@
 import type { BackgroundTaskConfig } from "../../config/schema"
 import {
   DEFAULT_CIRCUIT_BREAKER_ENABLED,
-  DEFAULT_CIRCUIT_BREAKER_REPETITION_THRESHOLD_PERCENT,
-  DEFAULT_CIRCUIT_BREAKER_WINDOW_SIZE,
+  DEFAULT_CIRCUIT_BREAKER_CONSECUTIVE_THRESHOLD,
   DEFAULT_MAX_TOOL_CALLS,
 } from "./constants"
 import type { ToolCallWindow } from "./types"
@@ -10,16 +9,13 @@ import type { ToolCallWindow } from "./types"
 export interface CircuitBreakerSettings {
   enabled: boolean
   maxToolCalls: number
-  windowSize: number
-  repetitionThresholdPercent: number
+  consecutiveThreshold: number
 }
 
 export interface ToolLoopDetectionResult {
   triggered: boolean
   toolName?: string
   repeatedCount?: number
-  sampleSize?: number
-  thresholdPercent?: number
 }
 
 export function resolveCircuitBreakerSettings(
@@ -29,10 +25,8 @@ export function resolveCircuitBreakerSettings(
     enabled: config?.circuitBreaker?.enabled ?? DEFAULT_CIRCUIT_BREAKER_ENABLED,
     maxToolCalls:
       config?.circuitBreaker?.maxToolCalls ?? config?.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS,
-    windowSize: config?.circuitBreaker?.windowSize ?? DEFAULT_CIRCUIT_BREAKER_WINDOW_SIZE,
-    repetitionThresholdPercent:
-      config?.circuitBreaker?.repetitionThresholdPercent ??
-      DEFAULT_CIRCUIT_BREAKER_REPETITION_THRESHOLD_PERCENT,
+    consecutiveThreshold:
+      config?.circuitBreaker?.consecutiveThreshold ?? DEFAULT_CIRCUIT_BREAKER_CONSECUTIVE_THRESHOLD,
   }
 }
 
@@ -42,14 +36,28 @@ export function recordToolCall(
   settings: CircuitBreakerSettings,
   toolInput?: Record<string, unknown> | null
 ): ToolCallWindow {
-  const previous = window?.toolSignatures ?? []
+  if (toolInput === undefined || toolInput === null) {
+    return {
+      lastSignature: `${toolName}::__unknown-input__`,
+      consecutiveCount: 1,
+      threshold: settings.consecutiveThreshold,
+    }
+  }
+
   const signature = createToolCallSignature(toolName, toolInput)
-  const toolSignatures = [...previous, signature].slice(-settings.windowSize)
+
+  if (window && window.lastSignature === signature) {
+    return {
+      lastSignature: signature,
+      consecutiveCount: window.consecutiveCount + 1,
+      threshold: settings.consecutiveThreshold,
+    }
+  }
 
   return {
-    toolSignatures,
-    windowSize: settings.windowSize,
-    thresholdPercent: settings.repetitionThresholdPercent,
+    lastSignature: signature,
+    consecutiveCount: 1,
+    threshold: settings.consecutiveThreshold,
   }
 }
 
@@ -82,46 +90,13 @@ export function createToolCallSignature(
 export function detectRepetitiveToolUse(
   window: ToolCallWindow | undefined
 ): ToolLoopDetectionResult {
-  if (!window || window.toolSignatures.length === 0) {
-    return { triggered: false }
-  }
-
-  const counts = new Map<string, number>()
-  for (const signature of window.toolSignatures) {
-    counts.set(signature, (counts.get(signature) ?? 0) + 1)
-  }
-
-  let repeatedTool: string | undefined
-  let repeatedCount = 0
-
-  for (const [toolName, count] of counts.entries()) {
-    if (count > repeatedCount) {
-      repeatedTool = toolName
-      repeatedCount = count
-    }
-  }
-
-  const sampleSize = window.toolSignatures.length
-  const minimumSampleSize = Math.min(
-    window.windowSize,
-    Math.ceil((window.windowSize * window.thresholdPercent) / 100)
-  )
-
-  if (sampleSize < minimumSampleSize) {
-    return { triggered: false }
-  }
-
-  const thresholdCount = Math.ceil((sampleSize * window.thresholdPercent) / 100)
-
-  if (!repeatedTool || repeatedCount < thresholdCount) {
+  if (!window || window.consecutiveCount < window.threshold) {
     return { triggered: false }
   }
 
   return {
     triggered: true,
-    toolName: repeatedTool.split("::")[0],
-    repeatedCount,
-    sampleSize,
-    thresholdPercent: window.thresholdPercent,
+    toolName: window.lastSignature.split("::")[0],
+    repeatedCount: window.consecutiveCount,
   }
 }

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

@@ -1,3 +1,5 @@
+/// <reference types="bun-types" />
+
 import { describe, expect, test } from "bun:test"
 import type { PluginInput } from "@opencode-ai/plugin"
 import { tmpdir } from "node:os"
@@ -38,12 +40,11 @@ async function flushAsyncWork() {
 }
 
 describe("BackgroundManager circuit breaker", () => {
-  describe("#given the same tool dominates the recent window", () => {
-    test("#when tool events arrive #then the task is cancelled early", async () => {
+  describe("#given flat-format tool events have no state.input", () => {
+    test("#when 20 consecutive read events arrive #then the task keeps running", async () => {
       const manager = createManager({
         circuitBreaker: {
-          windowSize: 20,
-          repetitionThresholdPercent: 80,
+          consecutiveThreshold: 20,
         },
       })
       const task: BackgroundTask = {
@@ -63,38 +64,17 @@ describe("BackgroundManager circuit breaker", () => {
       }
       getTaskMap(manager).set(task.id, task)
 
-      for (const toolName of [
-        "read",
-        "read",
-        "grep",
-        "read",
-        "edit",
-        "read",
-        "read",
-        "bash",
-        "read",
-        "read",
-        "read",
-        "glob",
-        "read",
-        "read",
-        "read",
-        "read",
-        "read",
-        "read",
-        "read",
-        "read",
-      ]) {
+      for (let i = 0; i < 20; i++) {
         manager.handleEvent({
           type: "message.part.updated",
-          properties: { sessionID: task.sessionID, type: "tool", tool: toolName },
+          properties: { sessionID: task.sessionID, type: "tool", tool: "read" },
         })
       }
 
       await flushAsyncWork()
 
-      expect(task.status).toBe("cancelled")
-      expect(task.error).toContain("repeatedly called read 16/20 times")
+      expect(task.status).toBe("running")
+      expect(task.progress?.toolCalls).toBe(20)
     })
   })
 
@@ -102,8 +82,7 @@ describe("BackgroundManager circuit breaker", () => {
     test("#when the window fills #then the task keeps running", async () => {
       const manager = createManager({
         circuitBreaker: {
-          windowSize: 10,
-          repetitionThresholdPercent: 80,
+          consecutiveThreshold: 10,
         },
       })
       const task: BackgroundTask = {
@@ -149,12 +128,11 @@ describe("BackgroundManager circuit breaker", () => {
   })
 
   describe("#given the absolute cap is configured lower than the repetition detector needs", () => {
-    test("#when the raw tool-call cap is reached #then the backstop still cancels the task", async () => {
+    test("#when repeated flat-format tool events reach maxToolCalls #then the backstop still cancels the task", async () => {
       const manager = createManager({
         maxToolCalls: 3,
         circuitBreaker: {
-          windowSize: 10,
-          repetitionThresholdPercent: 95,
+          consecutiveThreshold: 95,
         },
       })
       const task: BackgroundTask = {
@@ -174,10 +152,10 @@ describe("BackgroundManager circuit breaker", () => {
       }
       getTaskMap(manager).set(task.id, task)
 
-      for (const toolName of ["read", "grep", "edit"]) {
+      for (let i = 0; i < 3; i++) {
         manager.handleEvent({
           type: "message.part.updated",
-          properties: { sessionID: task.sessionID, type: "tool", tool: toolName },
+          properties: { sessionID: task.sessionID, type: "tool", tool: "read" },
         })
       }
 
@@ -193,8 +171,7 @@ describe("BackgroundManager circuit breaker", () => {
       const manager = createManager({
         maxToolCalls: 2,
         circuitBreaker: {
-          windowSize: 5,
-          repetitionThresholdPercent: 80,
+          consecutiveThreshold: 5,
         },
       })
       const task: BackgroundTask = {
@@ -233,7 +210,7 @@ describe("BackgroundManager circuit breaker", () => {
 
       expect(task.status).toBe("running")
       expect(task.progress?.toolCalls).toBe(1)
-      expect(task.progress?.countedToolPartIDs).toEqual(["tool-1"])
+      expect(task.progress?.countedToolPartIDs).toEqual(new Set(["tool-1"]))
     })
   })
 
@@ -241,8 +218,7 @@ describe("BackgroundManager circuit breaker", () => {
     test("#when tool events arrive with state.input #then task keeps running", async () => {
       const manager = createManager({
         circuitBreaker: {
-          windowSize: 20,
-          repetitionThresholdPercent: 80,
+          consecutiveThreshold: 20,
         },
       })
       const task: BackgroundTask = {
@@ -287,8 +263,7 @@ describe("BackgroundManager circuit breaker", () => {
     test("#when tool events arrive with state.input #then task is cancelled with bare tool name in error", async () => {
       const manager = createManager({
         circuitBreaker: {
-          windowSize: 20,
-          repetitionThresholdPercent: 80,
+          consecutiveThreshold: 20,
         },
       })
       const task: BackgroundTask = {
@@ -325,7 +300,7 @@ describe("BackgroundManager circuit breaker", () => {
       await flushAsyncWork()
 
       expect(task.status).toBe("cancelled")
-      expect(task.error).toContain("repeatedly called read")
+      expect(task.error).toContain("read 20 consecutive times")
       expect(task.error).not.toContain("::")
     })
   })
@@ -335,8 +310,7 @@ describe("BackgroundManager circuit breaker", () => {
       const manager = createManager({
         circuitBreaker: {
           enabled: false,
-          windowSize: 20,
-          repetitionThresholdPercent: 80,
+          consecutiveThreshold: 20,
         },
       })
       const task: BackgroundTask = {
@@ -379,8 +353,7 @@ describe("BackgroundManager circuit breaker", () => {
         maxToolCalls: 3,
         circuitBreaker: {
           enabled: false,
-          windowSize: 10,
-          repetitionThresholdPercent: 95,
+          consecutiveThreshold: 95,
         },
       })
       const task: BackgroundTask = {

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

@@ -153,4 +153,42 @@ describe("BackgroundManager pollRunningTasks", () => {
       expect(task.status).toBe("running")
     })
   })
+
+  describe("#given a running task whose session has terminal non-idle status", () => {
+    test('#when session status is "interrupted" #then completes the task', async () => {
+      //#given
+      const manager = createManagerWithClient({
+        status: async () => ({ data: { "ses-interrupted": { type: "interrupted" } } }),
+      })
+      const task = createRunningTask("ses-interrupted")
+      injectTask(manager, task)
+
+      //#when
+      const poll = (manager as unknown as { pollRunningTasks: () => Promise<void> }).pollRunningTasks
+      await poll.call(manager)
+      manager.shutdown()
+
+      //#then
+      expect(task.status).toBe("completed")
+      expect(task.completedAt).toBeDefined()
+    })
+
+    test('#when session status is an unknown type #then completes the task', async () => {
+      //#given
+      const manager = createManagerWithClient({
+        status: async () => ({ data: { "ses-unknown": { type: "some-weird-status" } } }),
+      })
+      const task = createRunningTask("ses-unknown")
+      injectTask(manager, task)
+
+      //#when
+      const poll = (manager as unknown as { pollRunningTasks: () => Promise<void> }).pollRunningTasks
+      await poll.call(manager)
+      manager.shutdown()
+
+      //#then
+      expect(task.status).toBe("completed")
+      expect(task.completedAt).toBeDefined()
+    })
+  })
 })

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

@@ -1,5 +1,6 @@
 declare const require: (name: string) => any
-const { describe, test, expect, beforeEach, afterEach } = require("bun:test")
+const { describe, test, expect, beforeEach, afterEach, spyOn } = require("bun:test")
+import { getSessionPromptParams, clearSessionPromptParams } from "../../shared/session-prompt-params-state"
 import { tmpdir } from "node:os"
 import type { PluginInput } from "@opencode-ai/plugin"
 import type { BackgroundTask, ResumeInput } from "./types"
@@ -1636,6 +1637,9 @@ describe("BackgroundManager.resume model persistence", () => {
    })
 
   afterEach(() => {
+    clearSessionPromptParams("session-1")
+    clearSessionPromptParams("session-advanced")
+    clearSessionPromptParams("session-2")
     manager.shutdown()
   })
 
@@ -1671,6 +1675,60 @@ describe("BackgroundManager.resume model persistence", () => {
     expect(promptCalls[0].body.agent).toBe("explore")
   })
 
+  test("should preserve promoted per-model settings when resuming a task", async () => {
+    // given - task resumed after fallback promotion
+    const taskWithAdvancedModel: BackgroundTask = {
+      id: "task-with-advanced-model",
+      sessionID: "session-advanced",
+      parentSessionID: "parent-session",
+      parentMessageID: "msg-1",
+      description: "task with advanced model settings",
+      prompt: "original prompt",
+      agent: "explore",
+      status: "completed",
+      startedAt: new Date(),
+      completedAt: new Date(),
+      model: {
+        providerID: "openai",
+        modelID: "gpt-5.4-preview",
+        variant: "minimal",
+        reasoningEffort: "high",
+        temperature: 0.25,
+        top_p: 0.55,
+        maxTokens: 8192,
+        thinking: { type: "disabled" },
+      },
+      concurrencyGroup: "explore",
+    }
+    getTaskMap(manager).set(taskWithAdvancedModel.id, taskWithAdvancedModel)
+
+    // when
+    await manager.resume({
+      sessionId: "session-advanced",
+      prompt: "continue the work",
+      parentSessionID: "parent-session-2",
+      parentMessageID: "msg-2",
+    })
+
+    // then
+    expect(promptCalls).toHaveLength(1)
+    expect(promptCalls[0].body.model).toEqual({
+      providerID: "openai",
+      modelID: "gpt-5.4-preview",
+    })
+    expect(promptCalls[0].body.variant).toBe("minimal")
+    expect(promptCalls[0].body.options).toBeUndefined()
+    expect(getSessionPromptParams("session-advanced")).toEqual({
+      temperature: 0.25,
+      topP: 0.55,
+      options: {
+        reasoningEffort: "high",
+        thinking: { type: "disabled" },
+        maxTokens: 8192,
+      },
+    })
+  })
+
   test("should NOT pass model when task has no model (backward compatibility)", async () => {
     // given - task without model (default behavior)
     const taskWithoutModel: BackgroundTask = {
@@ -1806,9 +1864,9 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
       expect(task.sessionID).toBeUndefined()
     })
 
-    test("should return immediately even with concurrency limit", async () => {
-      // given
-      const config = { defaultConcurrency: 1 }
+  test("should return immediately even with concurrency limit", async () => {
+    // given
+    const config = { defaultConcurrency: 1 }
       manager.shutdown()
       manager = new BackgroundManager({ client: mockClient, directory: tmpdir() } as unknown as PluginInput, config)
 
@@ -1828,9 +1886,76 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
 
       // then
       expect(endTime - startTime).toBeLessThan(100) // Should be instant
-      expect(task1.status).toBe("pending")
-      expect(task2.status).toBe("pending")
+    expect(task1.status).toBe("pending")
+    expect(task2.status).toBe("pending")
+  })
+
+  test("should keep agent when launch has model and keep agent without model", async () => {
+    // given
+    const promptBodies: Array<Record<string, unknown>> = []
+    let resolveFirstPromptStarted: (() => void) | undefined
+    let resolveSecondPromptStarted: (() => void) | undefined
+    const firstPromptStarted = new Promise<void>((resolve) => {
+      resolveFirstPromptStarted = resolve
     })
+    const secondPromptStarted = new Promise<void>((resolve) => {
+      resolveSecondPromptStarted = resolve
+    })
+    const customClient = {
+      session: {
+        create: async (_args?: unknown) => ({ data: { id: `ses_${crypto.randomUUID()}` } }),
+        get: async () => ({ data: { directory: "/test/dir" } }),
+        prompt: async () => ({}),
+        promptAsync: async (args: { path: { id: string }; body: Record<string, unknown> }) => {
+          promptBodies.push(args.body)
+          if (promptBodies.length === 1) {
+            resolveFirstPromptStarted?.()
+          }
+          if (promptBodies.length === 2) {
+            resolveSecondPromptStarted?.()
+          }
+          return {}
+        },
+        messages: async () => ({ data: [] }),
+        todo: async () => ({ data: [] }),
+        status: async () => ({ data: {} }),
+        abort: async () => ({}),
+      },
+    }
+    manager.shutdown()
+    manager = new BackgroundManager({ client: customClient, directory: tmpdir() } as unknown as PluginInput)
+
+    const launchInputWithModel = {
+      description: "Test task with model",
+      prompt: "Do something",
+      agent: "test-agent",
+      parentSessionID: "parent-session",
+      parentMessageID: "parent-message",
+      model: { providerID: "anthropic", modelID: "claude-opus-4-6" },
+    }
+    const launchInputWithoutModel = {
+      description: "Test task without model",
+      prompt: "Do something else",
+      agent: "test-agent",
+      parentSessionID: "parent-session",
+      parentMessageID: "parent-message",
+    }
+
+    // when
+    const taskWithModel = await manager.launch(launchInputWithModel)
+    await firstPromptStarted
+    const taskWithoutModel = await manager.launch(launchInputWithoutModel)
+    await secondPromptStarted
+
+    // then
+    expect(taskWithModel.status).toBe("pending")
+    expect(taskWithoutModel.status).toBe("pending")
+    expect(promptBodies).toHaveLength(2)
+    expect(promptBodies[0].model).toEqual({ providerID: "anthropic", modelID: "claude-opus-4-6" })
+    expect(promptBodies[0].agent).toBe("test-agent")
+    expect(promptBodies[1].agent).toBe("test-agent")
+    expect("model" in promptBodies[1]).toBe(false)
+  })
 
     test("should queue multiple tasks without blocking", async () => {
       // given
@@ -2359,6 +2484,133 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
       expect(abortCalls).toEqual([createdSessionID])
       expect(getConcurrencyManager(manager).getCount("test-agent")).toBe(0)
     })
+
+    test("should release descendant quota when task completes", async () => {
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain({
+            "session-root": { directory: "/test/dir" },
+          }),
+          directory: tmpdir(),
+        } as unknown as PluginInput,
+        { maxDescendants: 1 },
+      )
+      stubNotifyParentSession(manager)
+
+      const input = {
+        description: "Test task",
+        prompt: "Do something",
+        agent: "test-agent",
+        parentSessionID: "session-root",
+        parentMessageID: "parent-message",
+      }
+
+      const task = await manager.launch(input)
+      const internalTask = getTaskMap(manager).get(task.id)!
+      internalTask.status = "running"
+      internalTask.sessionID = "child-session-complete"
+      internalTask.rootSessionID = "session-root"
+
+      // Complete via internal method (session.status events go through the poller, not handleEvent)
+      await tryCompleteTaskForTest(manager, internalTask)
+
+      await expect(manager.launch(input)).resolves.toBeDefined()
+    })
+
+    test("should release descendant quota when running task is cancelled", async () => {
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain({
+            "session-root": { directory: "/test/dir" },
+          }),
+          directory: tmpdir(),
+        } as unknown as PluginInput,
+        { maxDescendants: 1 },
+      )
+
+      const input = {
+        description: "Test task",
+        prompt: "Do something",
+        agent: "test-agent",
+        parentSessionID: "session-root",
+        parentMessageID: "parent-message",
+      }
+
+      const task = await manager.launch(input)
+      const internalTask = getTaskMap(manager).get(task.id)!
+      internalTask.status = "running"
+      internalTask.sessionID = "child-session-cancel"
+
+      await manager.cancelTask(task.id)
+
+      await expect(manager.launch(input)).resolves.toBeDefined()
+    })
+
+    test("should release descendant quota when task errors", async () => {
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain({
+            "session-root": { directory: "/test/dir" },
+          }),
+          directory: tmpdir(),
+        } as unknown as PluginInput,
+        { maxDescendants: 1 },
+      )
+
+      const input = {
+        description: "Test task",
+        prompt: "Do something",
+        agent: "test-agent",
+        parentSessionID: "session-root",
+        parentMessageID: "parent-message",
+      }
+
+      const task = await manager.launch(input)
+      const internalTask = getTaskMap(manager).get(task.id)!
+      internalTask.status = "running"
+      internalTask.sessionID = "child-session-error"
+
+      manager.handleEvent({
+        type: "session.error",
+        properties: { sessionID: internalTask.sessionID, info: { id: internalTask.sessionID } },
+      })
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      await expect(manager.launch(input)).resolves.toBeDefined()
+    })
+
+    test("should not double-decrement quota when pending task is cancelled", async () => {
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain({
+            "session-root": { directory: "/test/dir" },
+          }),
+          directory: tmpdir(),
+        } as unknown as PluginInput,
+        { maxDescendants: 2 },
+      )
+
+      const input = {
+        description: "Test task",
+        prompt: "Do something",
+        agent: "test-agent",
+        parentSessionID: "session-root",
+        parentMessageID: "parent-message",
+      }
+
+      const task1 = await manager.launch(input)
+      const task2 = await manager.launch(input)
+
+      await manager.cancelTask(task1.id)
+      await manager.cancelTask(task2.id)
+
+      await expect(manager.launch(input)).resolves.toBeDefined()
+      await expect(manager.launch(input)).resolves.toBeDefined()
+    })
   })
 
   describe("pending task can be cancelled", () => {
@@ -2781,6 +3033,18 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
 })
 
 describe("BackgroundManager.checkAndInterruptStaleTasks", () => {
+  const originalDateNow = Date.now
+  let fixedTime: number
+
+  beforeEach(() => {
+    fixedTime = Date.now()
+    spyOn(globalThis.Date, "now").mockReturnValue(fixedTime)
+  })
+
+  afterEach(() => {
+    Date.now = originalDateNow
+  })
+
    test("should NOT interrupt task running less than 30 seconds (min runtime guard)", async () => {
      const client = {
        session: {
@@ -3027,10 +3291,10 @@ describe("BackgroundManager.checkAndInterruptStaleTasks", () => {
       prompt: "Test",
       agent: "test-agent",
       status: "running",
-      startedAt: new Date(Date.now() - 25 * 60 * 1000),
+      startedAt: new Date(Date.now() - 50 * 60 * 1000),
       progress: {
         toolCalls: 1,
-        lastUpdate: new Date(Date.now() - 21 * 60 * 1000),
+        lastUpdate: new Date(Date.now() - 46 * 60 * 1000),
       },
     }
 
@@ -4673,6 +4937,53 @@ describe("BackgroundManager - tool permission spread order", () => {
     manager.shutdown()
   })
 
+  test("startTask keeps agent when explicit model is configured", async () => {
+    //#given
+    const promptCalls: Array<{ path: { id: string }; body: Record<string, unknown> }> = []
+    const client = {
+      session: {
+        get: async () => ({ data: { directory: "/test/dir" } }),
+        create: async () => ({ data: { id: "session-1" } }),
+        promptAsync: async (args: { path: { id: string }; body: Record<string, unknown> }) => {
+          promptCalls.push(args)
+          return {}
+        },
+      },
+    }
+    const manager = new BackgroundManager({ client, directory: tmpdir() } as unknown as PluginInput)
+    const task: BackgroundTask = {
+      id: "task-explicit-model",
+      status: "pending",
+      queuedAt: new Date(),
+      description: "test task",
+      prompt: "test prompt",
+      agent: "sisyphus-junior",
+      parentSessionID: "parent-session",
+      parentMessageID: "parent-message",
+      model: { providerID: "openai", modelID: "gpt-5.4", variant: "medium" },
+    }
+    const input: import("./types").LaunchInput = {
+      description: task.description,
+      prompt: task.prompt,
+      agent: task.agent,
+      parentSessionID: task.parentSessionID,
+      parentMessageID: task.parentMessageID,
+      model: task.model,
+    }
+
+    //#when
+    await (manager as unknown as { startTask: (item: { task: BackgroundTask; input: import("./types").LaunchInput }) => Promise<void> })
+      .startTask({ task, input })
+
+    //#then
+    expect(promptCalls).toHaveLength(1)
+    expect(promptCalls[0].body.agent).toBe("sisyphus-junior")
+    expect(promptCalls[0].body.model).toEqual({ providerID: "openai", modelID: "gpt-5.4" })
+    expect(promptCalls[0].body.variant).toBe("medium")
+
+    manager.shutdown()
+  })
+
   test("resume respects explore agent restrictions", async () => {
     //#given
     let capturedTools: Record<string, unknown> | undefined
@@ -4717,4 +5028,48 @@ describe("BackgroundManager - tool permission spread order", () => {
 
     manager.shutdown()
   })
+
+  test("resume keeps agent when explicit model is configured", async () => {
+    //#given
+    let promptCall: { path: { id: string }; body: Record<string, unknown> } | undefined
+    const client = {
+      session: {
+        promptAsync: async (args: { path: { id: string }; body: Record<string, unknown> }) => {
+          promptCall = args
+          return {}
+        },
+        abort: async () => ({}),
+      },
+    }
+    const manager = new BackgroundManager({ client, directory: tmpdir() } as unknown as PluginInput)
+    const task: BackgroundTask = {
+      id: "task-explicit-model-resume",
+      sessionID: "session-3",
+      parentSessionID: "parent-session",
+      parentMessageID: "parent-message",
+      description: "resume task",
+      prompt: "resume prompt",
+      agent: "explore",
+      status: "completed",
+      startedAt: new Date(),
+      completedAt: new Date(),
+      model: { providerID: "anthropic", modelID: "claude-sonnet-4-20250514" },
+    }
+    getTaskMap(manager).set(task.id, task)
+
+    //#when
+    await manager.resume({
+      sessionId: "session-3",
+      prompt: "continue",
+      parentSessionID: "parent-session",
+      parentMessageID: "parent-message",
+    })
+
+    //#then
+    expect(promptCall).toBeDefined()
+    expect(promptCall?.body.agent).toBe("explore")
+    expect(promptCall?.body.model).toEqual({ providerID: "anthropic", modelID: "claude-sonnet-4-20250514" })
+
+    manager.shutdown()
+  })
 })

src/features/background-agent/manager.ts

@@ -15,6 +15,7 @@ import {
   resolveInheritedPromptTools,
   createInternalAgentTextPart,
 } from "../../shared"
+import { applySessionPromptParams } from "../../shared/session-prompt-params-helpers"
 import { setSessionTools } from "../../shared/session-tools-store"
 import { SessionCategoryRegistry } from "../../shared/session-category-registry"
 import { ConcurrencyManager } from "./concurrency"
@@ -52,10 +53,12 @@ import { join } from "node:path"
 import { pruneStaleTasksAndNotifications } from "./task-poller"
 import { checkAndInterruptStaleTasks } from "./task-poller"
 import { removeTaskToastTracking } from "./remove-task-toast-tracking"
+import { isActiveSessionStatus, isTerminalSessionStatus } from "./session-status-classifier"
 import {
   detectRepetitiveToolUse,
   recordToolCall,
   resolveCircuitBreakerSettings,
+  type CircuitBreakerSettings,
 } from "./loop-detector"
 import {
   createSubagentDepthLimitError,
@@ -151,6 +154,7 @@ export class BackgroundManager {
   private preStartDescendantReservations: Set<string>
   private enableParentSessionNotifications: boolean
   readonly taskHistory = new TaskHistory()
+  private cachedCircuitBreakerSettings?: CircuitBreakerSettings
 
   constructor(
     ctx: PluginInput,
@@ -501,14 +505,20 @@ export class BackgroundManager {
     })
 
     // Fire-and-forget prompt via promptAsync (no response body needed)
-    // Include model if caller provided one (e.g., from Sisyphus category configs)
-    // IMPORTANT: variant must be a top-level field in the body, NOT nested inside model
-    // OpenCode's PromptInput schema expects: { model: { providerID, modelID }, variant: "max" }
+    // OpenCode prompt payload accepts model provider/model IDs and top-level variant only.
+    // Temperature/topP and provider-specific options are applied through chat.params.
     const launchModel = input.model
-      ? { providerID: input.model.providerID, modelID: input.model.modelID }
+      ? {
+          providerID: input.model.providerID,
+          modelID: input.model.modelID,
+        }
       : undefined
     const launchVariant = input.model?.variant
 
+    if (input.model) {
+      applySessionPromptParams(sessionID, input.model)
+    }
+
     promptWithModelSuggestionRetry(this.client, {
       path: { id: sessionID },
       body: {
@@ -540,6 +550,9 @@ export class BackgroundManager {
           existingTask.error = errorMessage
         }
         existingTask.completedAt = new Date()
+        if (existingTask.rootSessionID) {
+          this.unregisterRootDescendant(existingTask.rootSessionID)
+        }
         if (existingTask.concurrencyKey) {
           this.concurrencyManager.release(existingTask.concurrencyKey)
           existingTask.concurrencyKey = undefined
@@ -779,13 +792,19 @@ export class BackgroundManager {
     })
 
     // Fire-and-forget prompt via promptAsync (no response body needed)
-    // Include model if task has one (preserved from original launch with category config)
-    // variant must be top-level in body, not nested inside model (OpenCode PromptInput schema)
+    // Resume uses the same PromptInput contract as launch: model IDs plus top-level variant.
     const resumeModel = existingTask.model
-      ? { providerID: existingTask.model.providerID, modelID: existingTask.model.modelID }
+      ? {
+          providerID: existingTask.model.providerID,
+          modelID: existingTask.model.modelID,
+        }
       : undefined
     const resumeVariant = existingTask.model?.variant
 
+    if (existingTask.model) {
+      applySessionPromptParams(existingTask.sessionID!, existingTask.model)
+    }
+
     this.client.session.promptAsync({
       path: { id: existingTask.sessionID },
       body: {
@@ -810,6 +829,9 @@ export class BackgroundManager {
       const errorMessage = error instanceof Error ? error.message : String(error)
       existingTask.error = errorMessage
       existingTask.completedAt = new Date()
+      if (existingTask.rootSessionID) {
+        this.unregisterRootDescendant(existingTask.rootSessionID)
+      }
 
       // Release concurrency on error to prevent slot leaks
       if (existingTask.concurrencyKey) {
@@ -900,23 +922,24 @@ export class BackgroundManager {
       task.progress.lastUpdate = new Date()
 
       if (partInfo?.type === "tool" || partInfo?.tool) {
-        const countedToolPartIDs = task.progress.countedToolPartIDs ?? []
+        const countedToolPartIDs = task.progress.countedToolPartIDs ?? new Set<string>()
         const shouldCountToolCall =
           !partInfo.id ||
           partInfo.state?.status !== "running" ||
-          !countedToolPartIDs.includes(partInfo.id)
+          !countedToolPartIDs.has(partInfo.id)
 
         if (!shouldCountToolCall) {
           return
         }
 
         if (partInfo.id && partInfo.state?.status === "running") {
-          task.progress.countedToolPartIDs = [...countedToolPartIDs, partInfo.id]
+          countedToolPartIDs.add(partInfo.id)
+          task.progress.countedToolPartIDs = countedToolPartIDs
         }
 
         task.progress.toolCalls += 1
         task.progress.lastTool = partInfo.tool
-        const circuitBreaker = resolveCircuitBreakerSettings(this.config)
+        const circuitBreaker = this.cachedCircuitBreakerSettings ?? (this.cachedCircuitBreakerSettings = resolveCircuitBreakerSettings(this.config))
         if (partInfo.tool) {
          task.progress.toolCallWindow = recordToolCall(
              task.progress.toolCallWindow,
@@ -928,18 +951,16 @@ export class BackgroundManager {
            if (circuitBreaker.enabled) {
              const loopDetection = detectRepetitiveToolUse(task.progress.toolCallWindow)
              if (loopDetection.triggered) {
-               log("[background-agent] Circuit breaker: repetitive tool usage detected", {
+               log("[background-agent] Circuit breaker: consecutive tool usage detected", {
                  taskId: task.id,
                  agent: task.agent,
                  sessionID,
                  toolName: loopDetection.toolName,
                  repeatedCount: loopDetection.repeatedCount,
-                 sampleSize: loopDetection.sampleSize,
-                 thresholdPercent: loopDetection.thresholdPercent,
                })
                void this.cancelTask(task.id, {
                  source: "circuit-breaker",
-                 reason: `Subagent repeatedly called ${loopDetection.toolName} ${loopDetection.repeatedCount}/${loopDetection.sampleSize} times in the recent tool-call window (${loopDetection.thresholdPercent}% threshold). This usually indicates an infinite loop. The task was automatically cancelled to prevent excessive token usage.`,
+                 reason: `Subagent called ${loopDetection.toolName} ${loopDetection.repeatedCount} consecutive times (threshold: ${circuitBreaker.consecutiveThreshold}). This usually indicates an infinite loop. The task was automatically cancelled to prevent excessive token usage.`,
                })
                return
              }
@@ -1007,6 +1028,9 @@ export class BackgroundManager {
       task.status = "error"
       task.error = errorMsg
       task.completedAt = new Date()
+      if (task.rootSessionID) {
+        this.unregisterRootDescendant(task.rootSessionID)
+      }
       this.taskHistory.record(task.parentSessionID, { id: task.id, sessionID: task.sessionID, agent: task.agent, description: task.description, status: "error", category: task.category, startedAt: task.startedAt, completedAt: task.completedAt })
 
       if (task.concurrencyKey) {
@@ -1339,8 +1363,12 @@ export class BackgroundManager {
       log("[background-agent] Cancelled pending task:", { taskId, key })
     }
 
+    const wasRunning = task.status === "running"
     task.status = "cancelled"
     task.completedAt = new Date()
+    if (wasRunning && task.rootSessionID) {
+      this.unregisterRootDescendant(task.rootSessionID)
+    }
     if (reason) {
       task.error = reason
     }
@@ -1461,6 +1489,10 @@ export class BackgroundManager {
     task.completedAt = new Date()
     this.taskHistory.record(task.parentSessionID, { id: task.id, sessionID: task.sessionID, agent: task.agent, description: task.description, status: "completed", category: task.category, startedAt: task.startedAt, completedAt: task.completedAt })
 
+    if (task.rootSessionID) {
+      this.unregisterRootDescendant(task.rootSessionID)
+    }
+
     removeTaskToastTracking(task.id)
 
     // Release concurrency BEFORE any async operations to prevent slot leaks
@@ -1699,6 +1731,9 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
         task.status = "error"
         task.error = errorMessage
         task.completedAt = new Date()
+        if (!wasPending && task.rootSessionID) {
+          this.unregisterRootDescendant(task.rootSessionID)
+        }
         this.taskHistory.record(task.parentSessionID, { id: task.id, sessionID: task.sessionID, agent: task.agent, description: task.description, status: "error", category: task.category, startedAt: task.startedAt, completedAt: task.completedAt })
         if (task.concurrencyKey) {
           this.concurrencyManager.release(task.concurrencyKey)
@@ -1782,11 +1817,9 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
           }
         }
 
-        // Match sync-session-poller pattern: only skip completion check when
-        // status EXISTS and is not idle (i.e., session is actively running).
-        // When sessionStatus is undefined, the session has completed and dropped
-        // from the status response — fall through to completion detection.
-        if (sessionStatus && sessionStatus.type !== "idle") {
+        // Only skip completion when session status is actively running.
+        // Unknown or terminal statuses (like "interrupted") fall through to completion.
+        if (sessionStatus && isActiveSessionStatus(sessionStatus.type)) {
           log("[background-agent] Session still running, relying on event-based progress:", {
             taskId: task.id,
             sessionID,
@@ -1796,6 +1829,24 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
           continue
         }
 
+        // Explicit terminal non-idle status (e.g., "interrupted") — complete immediately,
+        // skipping output validation (session will never produce more output).
+        // Unknown statuses fall through to the idle/gone path with output validation.
+        if (sessionStatus && isTerminalSessionStatus(sessionStatus.type)) {
+          await this.tryCompleteTask(task, `polling (terminal session status: ${sessionStatus.type})`)
+          continue
+        }
+
+        // Unknown non-idle status — not active, not terminal, not idle.
+        // Fall through to idle/gone completion path with output validation.
+        if (sessionStatus && sessionStatus.type !== "idle") {
+          log("[background-agent] Unknown session status, treating as potentially idle:", {
+            taskId: task.id,
+            sessionID,
+            sessionStatus: sessionStatus.type,
+          })
+        }
+
         // Session is idle or no longer in status response (completed/disappeared)
         const completionSource = sessionStatus?.type === "idle"
           ? "polling (idle status)"

src/features/background-agent/session-status-classifier.test.ts

@@ -0,0 +1,66 @@
+import { describe, test, expect, mock } from "bun:test"
+import { isActiveSessionStatus, isTerminalSessionStatus } from "./session-status-classifier"
+
+const mockLog = mock()
+mock.module("../../shared", () => ({ log: mockLog }))
+
+describe("isActiveSessionStatus", () => {
+  describe("#given a known active session status", () => {
+    test('#when type is "busy" #then returns true', () => {
+      expect(isActiveSessionStatus("busy")).toBe(true)
+    })
+
+    test('#when type is "retry" #then returns true', () => {
+      expect(isActiveSessionStatus("retry")).toBe(true)
+    })
+
+    test('#when type is "running" #then returns true', () => {
+      expect(isActiveSessionStatus("running")).toBe(true)
+    })
+  })
+
+  describe("#given a known terminal session status", () => {
+    test('#when type is "idle" #then returns false', () => {
+      expect(isActiveSessionStatus("idle")).toBe(false)
+    })
+
+    test('#when type is "interrupted" #then returns false and does not log', () => {
+      mockLog.mockClear()
+      expect(isActiveSessionStatus("interrupted")).toBe(false)
+      expect(mockLog).not.toHaveBeenCalled()
+    })
+  })
+
+  describe("#given an unknown session status", () => {
+    test('#when type is an arbitrary unknown string #then returns false and logs warning', () => {
+      mockLog.mockClear()
+      expect(isActiveSessionStatus("some-unknown-status")).toBe(false)
+      expect(mockLog).toHaveBeenCalledWith(
+        "[background-agent] Unknown session status type encountered:",
+        "some-unknown-status",
+      )
+    })
+
+    test('#when type is empty string #then returns false', () => {
+      expect(isActiveSessionStatus("")).toBe(false)
+    })
+  })
+})
+
+describe("isTerminalSessionStatus", () => {
+  test('#when type is "interrupted" #then returns true', () => {
+    expect(isTerminalSessionStatus("interrupted")).toBe(true)
+  })
+
+  test('#when type is "idle" #then returns false (idle is handled separately)', () => {
+    expect(isTerminalSessionStatus("idle")).toBe(false)
+  })
+
+  test('#when type is "busy" #then returns false', () => {
+    expect(isTerminalSessionStatus("busy")).toBe(false)
+  })
+
+  test('#when type is an unknown string #then returns false', () => {
+    expect(isTerminalSessionStatus("some-unknown")).toBe(false)
+  })
+})

src/features/background-agent/session-status-classifier.ts

@@ -0,0 +1,20 @@
+import { log } from "../../shared"
+
+const ACTIVE_SESSION_STATUSES = new Set(["busy", "retry", "running"])
+const KNOWN_TERMINAL_STATUSES = new Set(["idle", "interrupted"])
+
+export function isActiveSessionStatus(type: string): boolean {
+  if (ACTIVE_SESSION_STATUSES.has(type)) {
+    return true
+  }
+
+  if (!KNOWN_TERMINAL_STATUSES.has(type)) {
+    log("[background-agent] Unknown session status type encountered:", type)
+  }
+
+  return false
+}
+
+export function isTerminalSessionStatus(type: string): boolean {
+  return KNOWN_TERMINAL_STATUSES.has(type) && type !== "idle"
+}

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

@@ -1,33 +1,120 @@
-import { describe, test, expect } from "bun:test"
-
+import { describe, test, expect, mock, afterEach } from "bun:test"
 import { createTask, startTask } from "./spawner"
+import type { BackgroundTask } from "./types"
+import {
+  clearSessionPromptParams,
+  getSessionPromptParams,
+} from "../../shared/session-prompt-params-state"
 
-describe("background-agent spawner.startTask", () => {
-  test("applies explicit child session permission rules when creating child session", async () => {
+describe("background-agent spawner fallback model promotion", () => {
+  afterEach(() => {
+    clearSessionPromptParams("session-123")
+  })
+
+  test("passes promoted fallback model settings through supported prompt channels", async () => {
     //#given
-    const createCalls: any[] = []
-    const parentPermission = [
-      { permission: "question", action: "allow" as const, pattern: "*" },
-      { permission: "plan_enter", action: "deny" as const, pattern: "*" },
-    ]
+    let promptArgs: any
+    const client = {
+      session: {
+        get: mock(async () => ({ data: { directory: "/tmp/test" } })),
+        create: mock(async () => ({ data: { id: "session-123" } })),
+        promptAsync: mock(async (input: any) => {
+          promptArgs = input
+          return { data: {} }
+        }),
+      },
+    } as any
+
+    const concurrencyManager = {
+      release: mock(() => {}),
+    } as any
+
+    const onTaskError = mock(() => {})
+
+    const task: BackgroundTask = {
+      id: "bg_test123",
+      status: "pending",
+      queuedAt: new Date(),
+      description: "Test task",
+      prompt: "Do the thing",
+      agent: "oracle",
+      parentSessionID: "parent-1",
+      parentMessageID: "message-1",
+      model: {
+        providerID: "openai",
+        modelID: "gpt-5.4",
+        variant: "low",
+        reasoningEffort: "high",
+        temperature: 0.4,
+        top_p: 0.7,
+        maxTokens: 4096,
+        thinking: { type: "disabled" },
+      },
+    }
+
+    const input = {
+      description: "Test task",
+      prompt: "Do the thing",
+      agent: "oracle",
+      parentSessionID: "parent-1",
+      parentMessageID: "message-1",
+      model: task.model,
+    }
+
+    //#when
+    await startTask(
+      { task, input },
+      {
+        client,
+        directory: "/tmp/test",
+        concurrencyManager,
+        tmuxEnabled: false,
+        onTaskError,
+      },
+    )
+
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    //#then
+    expect(promptArgs.body.model).toEqual({
+      providerID: "openai",
+      modelID: "gpt-5.4",
+    })
+    expect(promptArgs.body.variant).toBe("low")
+    expect(promptArgs.body.options).toBeUndefined()
+    expect(getSessionPromptParams("session-123")).toEqual({
+      temperature: 0.4,
+      topP: 0.7,
+      options: {
+        reasoningEffort: "high",
+        thinking: { type: "disabled" },
+        maxTokens: 4096,
+      },
+    })
+  })
+
+  test("keeps agent when explicit model is configured", async () => {
+    //#given
+    const promptCalls: any[] = []
 
     const client = {
       session: {
-        get: async () => ({ data: { directory: "/parent/dir", permission: parentPermission } }),
-        create: async (args?: any) => {
-          createCalls.push(args)
-          return { data: { id: "ses_child" } }
+        get: async () => ({ data: { directory: "/parent/dir" } }),
+        create: async () => ({ data: { id: "ses_child" } }),
+        promptAsync: async (args?: any) => {
+          promptCalls.push(args)
+          return {}
         },
-        promptAsync: async () => ({}),
       },
     }
 
     const task = createTask({
       description: "Test task",
       prompt: "Do work",
-      agent: "explore",
+      agent: "sisyphus-junior",
       parentSessionID: "ses_parent",
       parentMessageID: "msg_parent",
+      model: { providerID: "openai", modelID: "gpt-5.4", variant: "medium" },
     })
 
     const item = {
@@ -41,9 +128,6 @@ describe("background-agent spawner.startTask", () => {
         parentModel: task.parentModel,
         parentAgent: task.parentAgent,
         model: task.model,
-        sessionPermission: [
-          { permission: "question", action: "deny", pattern: "*" },
-        ],
       },
     }
 
@@ -59,9 +143,12 @@ describe("background-agent spawner.startTask", () => {
     await startTask(item as any, ctx as any)
 
     //#then
-    expect(createCalls).toHaveLength(1)
-    expect(createCalls[0]?.body?.permission).toEqual([
-      { permission: "question", action: "deny", pattern: "*" },
-    ])
+    expect(promptCalls).toHaveLength(1)
+    expect(promptCalls[0]?.body?.agent).toBe("sisyphus-junior")
+    expect(promptCalls[0]?.body?.model).toEqual({
+      providerID: "openai",
+      modelID: "gpt-5.4",
+    })
+    expect(promptCalls[0]?.body?.variant).toBe("medium")
   })
 })

src/features/background-agent/spawner.ts

@@ -2,6 +2,7 @@ import type { BackgroundTask, LaunchInput, ResumeInput } from "./types"
 import type { OpencodeClient, OnSubagentSessionCreated, QueueItem } from "./constants"
 import { TMUX_CALLBACK_DELAY_MS } from "./constants"
 import { log, getAgentToolRestrictions, promptWithModelSuggestionRetry, createInternalAgentTextPart } from "../../shared"
+import { applySessionPromptParams } from "../../shared/session-prompt-params-helpers"
 import { subagentSessions } from "../claude-code-session-state"
 import { getTaskToastManager } from "../task-toast-manager"
 import { isInsideTmux } from "../../shared/tmux"
@@ -128,10 +129,15 @@ export async function startTask(
   })
 
   const launchModel = input.model
-    ? { providerID: input.model.providerID, modelID: input.model.modelID }
+    ? {
+        providerID: input.model.providerID,
+        modelID: input.model.modelID,
+      }
     : undefined
   const launchVariant = input.model?.variant
 
+  applySessionPromptParams(sessionID, input.model)
+
   promptWithModelSuggestionRetry(client, {
     path: { id: sessionID },
     body: {
@@ -213,10 +219,15 @@ export async function resumeTask(
   })
 
   const resumeModel = task.model
-    ? { providerID: task.model.providerID, modelID: task.model.modelID }
+    ? {
+        providerID: task.model.providerID,
+        modelID: task.model.modelID,
+      }
     : undefined
   const resumeVariant = task.model?.variant
 
+  applySessionPromptParams(task.sessionID, task.model)
+
   client.session.promptAsync({
     path: { id: task.sessionID },
     body: {

src/features/background-agent/task-poller.test.ts

@@ -1,5 +1,5 @@
 declare const require: (name: string) => any
-const { describe, it, expect, mock } = require("bun:test")
+const { describe, it, expect, mock, spyOn, beforeEach, afterEach } = require("bun:test")
 
 import { checkAndInterruptStaleTasks, pruneStaleTasksAndNotifications } from "./task-poller"
 import type { BackgroundTask } from "./types"
@@ -29,6 +29,18 @@ describe("checkAndInterruptStaleTasks", () => {
       ...overrides,
     }
   }
+  const originalDateNow = Date.now
+  let fixedTime: number
+
+  beforeEach(() => {
+    fixedTime = Date.now()
+    spyOn(globalThis.Date, "now").mockReturnValue(fixedTime)
+  })
+
+  afterEach(() => {
+    Date.now = originalDateNow
+  })
+
 
   it("should interrupt tasks with lastUpdate exceeding stale timeout", async () => {
     //#given
@@ -117,13 +129,13 @@ describe("checkAndInterruptStaleTasks", () => {
   })
 
   it("should use DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS when messageStalenessTimeoutMs is not configured", async () => {
-    //#given — task started 35 minutes ago, no config for messageStalenessTimeoutMs
+    //#given — task started 65 minutes ago, no config for messageStalenessTimeoutMs
     const task = createRunningTask({
-      startedAt: new Date(Date.now() - 35 * 60 * 1000),
+      startedAt: new Date(Date.now() - 65 * 60 * 1000),
       progress: undefined,
     })
 
-    //#when — default is 30 minutes (1_800_000ms)
+    //#when — default is 60 minutes (3_600_000ms)
     await checkAndInterruptStaleTasks({
       tasks: [task],
       client: mockClient as never,
@@ -417,6 +429,56 @@ describe("checkAndInterruptStaleTasks", () => {
     expect(task.status).toBe("cancelled")
     expect(onTaskInterrupted).toHaveBeenCalledWith(task)
   })
+
+  it('should NOT protect task when session has terminal non-idle status like "interrupted"', async () => {
+    //#given — lastUpdate is 5min old, session is "interrupted" (terminal, not active)
+    const task = createRunningTask({
+      startedAt: new Date(Date.now() - 300_000),
+      progress: {
+        toolCalls: 2,
+        lastUpdate: new Date(Date.now() - 300_000),
+      },
+    })
+
+    //#when — session status is "interrupted" (terminal)
+    await checkAndInterruptStaleTasks({
+      tasks: [task],
+      client: mockClient as never,
+      config: { staleTimeoutMs: 180_000 },
+      concurrencyManager: mockConcurrencyManager as never,
+      notifyParentSession: mockNotify,
+      sessionStatuses: { "ses-1": { type: "interrupted" } },
+    })
+
+    //#then — terminal statuses should not protect from stale timeout
+    expect(task.status).toBe("cancelled")
+    expect(task.error).toContain("Stale timeout")
+  })
+
+  it('should NOT protect task when session has unknown status type', async () => {
+    //#given — lastUpdate is 5min old, session has an unknown status
+    const task = createRunningTask({
+      startedAt: new Date(Date.now() - 300_000),
+      progress: {
+        toolCalls: 2,
+        lastUpdate: new Date(Date.now() - 300_000),
+      },
+    })
+
+    //#when — session has unknown status type
+    await checkAndInterruptStaleTasks({
+      tasks: [task],
+      client: mockClient as never,
+      config: { staleTimeoutMs: 180_000 },
+      concurrencyManager: mockConcurrencyManager as never,
+      notifyParentSession: mockNotify,
+      sessionStatuses: { "ses-1": { type: "some-weird-status" } },
+    })
+
+    //#then — unknown statuses should not protect from stale timeout
+    expect(task.status).toBe("cancelled")
+    expect(task.error).toContain("Stale timeout")
+  })
 })
 
 describe("pruneStaleTasksAndNotifications", () => {

src/features/background-agent/task-poller.ts

@@ -14,6 +14,7 @@ import {
 } from "./constants"
 import { removeTaskToastTracking } from "./remove-task-toast-tracking"
 
+import { isActiveSessionStatus } from "./session-status-classifier"
 const TERMINAL_TASK_STATUSES = new Set<BackgroundTask["status"]>([
   "completed",
   "error",
@@ -120,7 +121,7 @@ export async function checkAndInterruptStaleTasks(args: {
     if (!startedAt || !sessionID) continue
 
     const sessionStatus = sessionStatuses?.[sessionID]?.type
-    const sessionIsRunning = sessionStatus !== undefined && sessionStatus !== "idle"
+    const sessionIsRunning = sessionStatus !== undefined && isActiveSessionStatus(sessionStatus)
     const runtime = now - startedAt.getTime()
 
     if (!task.progress?.lastUpdate) {
@@ -129,7 +130,7 @@ export async function checkAndInterruptStaleTasks(args: {
 
       const staleMinutes = Math.round(runtime / 60000)
       task.status = "cancelled"
-      task.error = `Stale timeout (no activity for ${staleMinutes}min since start)`
+      task.error = `Stale timeout (no activity for ${staleMinutes}min since start). This is a FINAL cancellation - do NOT create a replacement task. If the timeout is too short, increase 'background_task.staleTimeoutMs' in .opencode/oh-my-opencode.json.`
       task.completedAt = new Date()
 
       if (task.concurrencyKey) {
@@ -158,10 +159,10 @@ export async function checkAndInterruptStaleTasks(args: {
     if (timeSinceLastUpdate <= staleTimeoutMs) continue
     if (task.status !== "running") continue
 
-    const staleMinutes = Math.round(timeSinceLastUpdate / 60000)
-    task.status = "cancelled"
-    task.error = `Stale timeout (no activity for ${staleMinutes}min)`
-    task.completedAt = new Date()
+     const staleMinutes = Math.round(timeSinceLastUpdate / 60000)
+     task.status = "cancelled"
+     task.error = `Stale timeout (no activity for ${staleMinutes}min). This is a FINAL cancellation - do NOT create a replacement task. If the timeout is too short, increase 'background_task.staleTimeoutMs' in .opencode/oh-my-opencode.json.`
+     task.completedAt = new Date()
 
     if (task.concurrencyKey) {
       concurrencyManager.release(task.concurrencyKey)

src/features/background-agent/types.ts

@@ -1,4 +1,5 @@
 import type { FallbackEntry } from "../../shared/model-requirements"
+import type { DelegatedModelConfig } from "../../shared/model-resolution-types"
 import type { SessionPermissionRule } from "../../shared/question-denied-session-permission"
 
 export type BackgroundTaskStatus =
@@ -10,16 +11,16 @@ export type BackgroundTaskStatus =
   | "interrupt"
 
 export interface ToolCallWindow {
-  toolSignatures: string[]
-  windowSize: number
-  thresholdPercent: number
+  lastSignature: string
+  consecutiveCount: number
+  threshold: number
 }
 
 export interface TaskProgress {
   toolCalls: number
   lastTool?: string
   toolCallWindow?: ToolCallWindow
-  countedToolPartIDs?: string[]
+  countedToolPartIDs?: Set<string>
   lastUpdate: Date
   lastMessage?: string
   lastMessageAt?: Date
@@ -43,7 +44,7 @@ export interface BackgroundTask {
   error?: string
   progress?: TaskProgress
   parentModel?: { providerID: string; modelID: string }
-  model?: { providerID: string; modelID: string; variant?: string }
+  model?: DelegatedModelConfig
   /** Fallback chain for runtime retry on model errors */
   fallbackChain?: FallbackEntry[]
   /** Number of fallback retry attempts made */
@@ -76,7 +77,7 @@ export interface LaunchInput {
   parentModel?: { providerID: string; modelID: string }
   parentAgent?: string
   parentTools?: Record<string, boolean>
-  model?: { providerID: string; modelID: string; variant?: string }
+  model?: DelegatedModelConfig
   /** Fallback chain for runtime retry on model errors */
   fallbackChain?: FallbackEntry[]
   isUnstableAgent?: boolean

src/features/boulder-state/index.ts

@@ -1,3 +1,4 @@
 export * from "./types"
 export * from "./constants"
 export * from "./storage"
+export * from "./top-level-task"

src/features/boulder-state/storage.test.ts

@@ -11,8 +11,11 @@ import {
   getPlanName,
   createBoulderState,
   findPrometheusPlans,
+  getTaskSessionState,
+  upsertTaskSessionState,
 } from "./storage"
 import type { BoulderState } from "./types"
+import { readCurrentTopLevelTask } from "./top-level-task"
 
 describe("boulder-state", () => {
   const TEST_DIR = join(tmpdir(), "boulder-state-test-" + Date.now())
@@ -134,6 +137,24 @@ describe("boulder-state", () => {
       expect(result?.session_ids).toEqual(["session-1", "session-2"])
       expect(result?.plan_name).toBe("my-plan")
     })
+
+    test("should default task_sessions to empty object when missing from JSON", () => {
+      // given - boulder.json without task_sessions field
+      const boulderFile = join(SISYPHUS_DIR, "boulder.json")
+      writeFileSync(boulderFile, JSON.stringify({
+        active_plan: "/path/to/plan.md",
+        started_at: "2026-01-01T00:00:00Z",
+        session_ids: ["session-1"],
+        plan_name: "plan",
+      }))
+
+      // when
+      const result = readBoulderState(TEST_DIR)
+
+      // then
+      expect(result).not.toBeNull()
+      expect(result!.task_sessions).toEqual({})
+    })
   })
 
   describe("writeBoulderState", () => {
@@ -249,6 +270,115 @@ describe("boulder-state", () => {
     })
   })
 
+  describe("task session state", () => {
+    test("should persist and read preferred session for a top-level plan task", () => {
+      // given - existing boulder state
+      const state: BoulderState = {
+        active_plan: "/plan.md",
+        started_at: "2026-01-02T10:00:00Z",
+        session_ids: ["session-1"],
+        plan_name: "plan",
+      }
+      writeBoulderState(TEST_DIR, state)
+
+      // when
+      upsertTaskSessionState(TEST_DIR, {
+        taskKey: "todo:1",
+        taskLabel: "1",
+        taskTitle: "Implement auth flow",
+        sessionId: "ses_task_123",
+        agent: "sisyphus-junior",
+        category: "deep",
+      })
+      const result = getTaskSessionState(TEST_DIR, "todo:1")
+
+      // then
+      expect(result).not.toBeNull()
+      expect(result?.session_id).toBe("ses_task_123")
+      expect(result?.task_title).toBe("Implement auth flow")
+      expect(result?.agent).toBe("sisyphus-junior")
+      expect(result?.category).toBe("deep")
+    })
+
+    test("should overwrite preferred session for the same top-level plan task", () => {
+      // given - existing boulder state with prior preferred session
+      const state: BoulderState = {
+        active_plan: "/plan.md",
+        started_at: "2026-01-02T10:00:00Z",
+        session_ids: ["session-1"],
+        plan_name: "plan",
+        task_sessions: {
+          "todo:1": {
+            task_key: "todo:1",
+            task_label: "1",
+            task_title: "Implement auth flow",
+            session_id: "ses_old",
+            updated_at: "2026-01-02T10:00:00Z",
+          },
+        },
+      }
+      writeBoulderState(TEST_DIR, state)
+
+      // when
+      upsertTaskSessionState(TEST_DIR, {
+        taskKey: "todo:1",
+        taskLabel: "1",
+        taskTitle: "Implement auth flow",
+        sessionId: "ses_new",
+      })
+      const result = getTaskSessionState(TEST_DIR, "todo:1")
+
+      // then
+      expect(result?.session_id).toBe("ses_new")
+    })
+  })
+
+  describe("readCurrentTopLevelTask", () => {
+    test("should return the first unchecked top-level task in TODOs", () => {
+      // given - plan with nested and top-level unchecked tasks
+      const planPath = join(TEST_DIR, "current-task-plan.md")
+      writeFileSync(planPath, `# Plan
+
+## TODOs
+- [x] 1. Finished task
+  - [ ] nested acceptance checkbox
+- [ ] 2. Current task
+
+## Final Verification Wave
+- [ ] F1. Final review
+`)
+
+      // when
+      const result = readCurrentTopLevelTask(planPath)
+
+      // then
+      expect(result).not.toBeNull()
+      expect(result?.key).toBe("todo:2")
+      expect(result?.title).toBe("Current task")
+    })
+
+    test("should fall back to final-wave task when implementation tasks are complete", () => {
+      // given - plan with only final-wave work remaining
+      const planPath = join(TEST_DIR, "final-wave-current-task-plan.md")
+      writeFileSync(planPath, `# Plan
+
+## TODOs
+- [x] 1. Finished task
+
+## Final Verification Wave
+- [ ] F1. Final review
+`)
+
+      // when
+      const result = readCurrentTopLevelTask(planPath)
+
+      // then
+      expect(result).not.toBeNull()
+      expect(result?.key).toBe("final-wave:f1")
+      expect(result?.title).toBe("Final review")
+    })
+  })
+
   describe("getPlanProgress", () => {
     test("should count completed and uncompleted checkboxes", () => {
       // given - plan file with checkboxes
@@ -351,7 +481,7 @@ describe("boulder-state", () => {
       expect(progress.isComplete).toBe(true)
     })
 
-    test("should return isComplete true for empty plan", () => {
+    test("should return isComplete false for empty plan", () => {
       // given - plan with no checkboxes
       const planPath = join(TEST_DIR, "empty-plan.md")
       writeFileSync(planPath, "# Plan\nNo tasks here")
@@ -361,7 +491,7 @@ describe("boulder-state", () => {
 
       // then
       expect(progress.total).toBe(0)
-      expect(progress.isComplete).toBe(true)
+      expect(progress.isComplete).toBe(false)
     })
 
     test("should handle non-existent file", () => {

src/features/boulder-state/storage.ts

@@ -6,9 +6,11 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs"
 import { dirname, join, basename } from "node:path"
-import type { BoulderState, PlanProgress } from "./types"
+import type { BoulderState, PlanProgress, TaskSessionState } from "./types"
 import { BOULDER_DIR, BOULDER_FILE, PROMETHEUS_PLANS_DIR } from "./constants"
 
+const RESERVED_KEYS = new Set(["__proto__", "prototype", "constructor"])
+
 export function getBoulderFilePath(directory: string): string {
   return join(directory, BOULDER_DIR, BOULDER_FILE)
 }
@@ -29,6 +31,9 @@ export function readBoulderState(directory: string): BoulderState | null {
     if (!Array.isArray(parsed.session_ids)) {
       parsed.session_ids = []
     }
+    if (!parsed.task_sessions || typeof parsed.task_sessions !== "object" || Array.isArray(parsed.task_sessions)) {
+      parsed.task_sessions = {}
+    }
     return parsed as BoulderState
   } catch {
     return null
@@ -85,6 +90,54 @@ export function clearBoulderState(directory: string): boolean {
   }
 }
 
+export function getTaskSessionState(directory: string, taskKey: string): TaskSessionState | null {
+  const state = readBoulderState(directory)
+  if (!state?.task_sessions) {
+    return null
+  }
+
+  return state.task_sessions[taskKey] ?? null
+}
+
+export function upsertTaskSessionState(
+  directory: string,
+  input: {
+    taskKey: string
+    taskLabel: string
+    taskTitle: string
+    sessionId: string
+    agent?: string
+    category?: string
+  },
+): BoulderState | null {
+  const state = readBoulderState(directory)
+  if (!state) {
+    return null
+  }
+
+  if (RESERVED_KEYS.has(input.taskKey)) {
+    return null
+  }
+
+  const taskSessions = state.task_sessions ?? {}
+  taskSessions[input.taskKey] = {
+    task_key: input.taskKey,
+    task_label: input.taskLabel,
+    task_title: input.taskTitle,
+    session_id: input.sessionId,
+    ...(input.agent !== undefined ? { agent: input.agent } : {}),
+    ...(input.category !== undefined ? { category: input.category } : {}),
+    updated_at: new Date().toISOString(),
+  }
+
+  state.task_sessions = taskSessions
+  if (writeBoulderState(directory, state)) {
+    return state
+  }
+
+  return null
+}
+
 /**
  * Find Prometheus plan files for this project.
  * Prometheus stores plans at: {project}/.sisyphus/plans/{name}.md
@@ -133,7 +186,7 @@ export function getPlanProgress(planPath: string): PlanProgress {
     return {
       total,
       completed,
-      isComplete: total === 0 || completed === total,
+      isComplete: total > 0 && completed === total,
     }
   } catch {
     return { total: 0, completed: 0, isComplete: true }

src/features/boulder-state/top-level-task.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, test } from "bun:test"
+import { writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+
+import { readCurrentTopLevelTask } from "./top-level-task"
+
+function writePlanFile(fileName: string, content: string): string {
+  const planPath = join(tmpdir(), fileName)
+  writeFileSync(planPath, content, "utf-8")
+  return planPath
+}
+
+describe("readCurrentTopLevelTask", () => {
+  test("returns first unchecked top-level task in TODOs", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-happy-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+- [x] 1. Done task
+- [ ] 2. Current task
+
+## Final Verification Wave
+- [ ] F1. Final review
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result).toEqual({
+      key: "todo:2",
+      section: "todo",
+      label: "2",
+      title: "Current task",
+    })
+  })
+
+  test("returns null when all tasks are checked", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-all-checked-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+- [x] 1. Done task
+- [x] 2. Another done task
+
+## Final Verification Wave
+- [x] F1. Final done review
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result).toBeNull()
+  })
+
+  test("returns null for empty plan file", () => {
+    // given
+    const planPath = writePlanFile(`top-level-task-empty-${Date.now()}.md`, "")
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result).toBeNull()
+  })
+
+  test("returns null when plan file does not exist", () => {
+    // given
+    const planPath = join(tmpdir(), `top-level-task-missing-${Date.now()}.md`)
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result).toBeNull()
+  })
+
+  test("skips nested or indented checkboxes", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-nested-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+- [x] 1. Done task
+  - [ ] nested should be ignored
+- [ ] 2. Top-level pending
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result?.key).toBe("todo:2")
+  })
+
+  test("falls back to Final Verification Wave when TODOs are all checked", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-fallback-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+- [x] 1. Done task
+- [x] 2. Done task
+
+## Final Verification Wave
+- [ ] F1. Final review pending
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result).toEqual({
+      key: "final-wave:f1",
+      section: "final-wave",
+      label: "F1",
+      title: "Final review pending",
+    })
+  })
+
+  test("selects the first unchecked task among mixed checked and unchecked TODOs", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-mixed-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+- [x] 1. Done task
+- [ ] 2. First unchecked
+- [ ] 3. Second unchecked
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result?.key).toBe("todo:2")
+    expect(result?.title).toBe("First unchecked")
+  })
+
+  test("ignores malformed labels and continues to next unchecked task", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-malformed-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+- [ ] no number prefix
+- [ ] 2. Valid task after malformed label
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result).toEqual({
+      key: "todo:2",
+      section: "todo",
+      label: "2",
+      title: "Valid task after malformed label",
+    })
+  })
+
+  test("supports unchecked tasks with asterisk bullets", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-asterisk-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+* [ ] 1. Task using asterisk bullet
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result?.key).toBe("todo:1")
+    expect(result?.title).toBe("Task using asterisk bullet")
+  })
+
+  test("returns final-wave task when plan has only Final Verification Wave section", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-final-only-${Date.now()}.md`,
+      `# Plan
+
+## Final Verification Wave
+- [ ] F2. Final-only task
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result).toEqual({
+      key: "final-wave:f2",
+      section: "final-wave",
+      label: "F2",
+      title: "Final-only task",
+    })
+  })
+
+  test("returns the first unchecked task when multiple unchecked tasks exist", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-multiple-${Date.now()}.md`,
+      `# Plan
+
+## TODOs
+- [ ] 1. First unchecked task
+- [ ] 2. Second unchecked task
+- [ ] 3. Third unchecked task
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result?.label).toBe("1")
+    expect(result?.title).toBe("First unchecked task")
+  })
+
+  test("ignores unchecked content in non-target sections during section transitions", () => {
+    // given
+    const planPath = writePlanFile(
+      `top-level-task-sections-${Date.now()}.md`,
+      `# Plan
+
+## Notes
+- [ ] 99. Should be ignored because section is not tracked
+
+## TODOs
+- [x] 1. Done implementation task
+
+## Decisions
+- [ ] 100. Should also be ignored
+
+## Final Verification Wave
+- [ ] F3. Final verification task
+`,
+    )
+
+    // when
+    const result = readCurrentTopLevelTask(planPath)
+
+    // then
+    expect(result?.key).toBe("final-wave:f3")
+    expect(result?.section).toBe("final-wave")
+  })
+})

src/features/boulder-state/top-level-task.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from "node:fs"
+
+import type { TopLevelTaskRef } from "./types"
+
+const TODO_HEADING_PATTERN = /^##\s+TODOs\b/i
+const FINAL_VERIFICATION_HEADING_PATTERN = /^##\s+Final Verification Wave\b/i
+const SECOND_LEVEL_HEADING_PATTERN = /^##\s+/
+const UNCHECKED_CHECKBOX_PATTERN = /^(\s*)[-*]\s*\[\s*\]\s*(.+)$/
+const TODO_TASK_PATTERN = /^(\d+)\.\s+(.+)$/
+const FINAL_WAVE_TASK_PATTERN = /^(F\d+)\.\s+(.+)$/i
+
+type PlanSection = "todo" | "final-wave" | "other"
+
+function buildTaskRef(
+  section: "todo" | "final-wave",
+  taskLabel: string,
+): TopLevelTaskRef | null {
+  const pattern = section === "todo" ? TODO_TASK_PATTERN : FINAL_WAVE_TASK_PATTERN
+  const match = taskLabel.match(pattern)
+  if (!match) {
+    return null
+  }
+
+  const rawLabel = match[1]
+  const title = match[2].trim()
+
+  return {
+    key: `${section}:${rawLabel.toLowerCase()}`,
+    section,
+    label: rawLabel,
+    title,
+  }
+}
+
+export function readCurrentTopLevelTask(planPath: string): TopLevelTaskRef | null {
+  if (!existsSync(planPath)) {
+    return null
+  }
+
+  try {
+    const content = readFileSync(planPath, "utf-8")
+    const lines = content.split(/\r?\n/)
+    let section: PlanSection = "other"
+
+    for (const line of lines) {
+      if (SECOND_LEVEL_HEADING_PATTERN.test(line)) {
+        section = TODO_HEADING_PATTERN.test(line)
+          ? "todo"
+          : FINAL_VERIFICATION_HEADING_PATTERN.test(line)
+            ? "final-wave"
+            : "other"
+      }
+
+      const uncheckedTaskMatch = line.match(UNCHECKED_CHECKBOX_PATTERN)
+      if (!uncheckedTaskMatch) {
+        continue
+      }
+
+      if (uncheckedTaskMatch[1].length > 0) {
+        continue
+      }
+
+      if (section !== "todo" && section !== "final-wave") {
+        continue
+      }
+
+      const taskRef = buildTaskRef(section, uncheckedTaskMatch[2].trim())
+      if (taskRef) {
+        return taskRef
+      }
+    }
+
+    return null
+  } catch {
+    return null
+  }
+}