fix: restore await on metadata call in create-background-task (#2441)

fix(hashline-edit): remove array type from lines union to fix Gemini Vertex schema validation

README.md

@@ -37,7 +37,7 @@
 <div align="center">
 
 [![GitHub Release](https://img.shields.io/github/v/release/code-yeongyu/oh-my-openagent?color=369eff&labelColor=black&logo=github&style=flat-square)](https://github.com/code-yeongyu/oh-my-openagent/releases)
-[![npm downloads](https://img.shields.io/npm/dt/oh-my-opencode?color=ff6b35&labelColor=black&style=flat-square)](https://www.npmjs.com/package/oh-my-opencode)
+[![npm downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fohmyopenagent.com%2Fapi%2Fnpm-downloads&style=flat-square)](https://www.npmjs.com/package/oh-my-openagent)
 [![GitHub Contributors](https://img.shields.io/github/contributors/code-yeongyu/oh-my-openagent?color=c4f042&labelColor=black&style=flat-square)](https://github.com/code-yeongyu/oh-my-openagent/graphs/contributors)
 [![GitHub Forks](https://img.shields.io/github/forks/code-yeongyu/oh-my-openagent?color=8ae8ff&labelColor=black&style=flat-square)](https://github.com/code-yeongyu/oh-my-openagent/network/members)
 [![GitHub Stars](https://img.shields.io/github/stars/code-yeongyu/oh-my-openagent?color=ffcb47&labelColor=black&style=flat-square)](https://github.com/code-yeongyu/oh-my-openagent/stargazers)
@@ -181,7 +181,7 @@ When Sisyphus delegates to a subagent, it doesn't pick a model. It picks a **cat
 | `quick`              | Single-file changes, typos         |
 | `ultrabrain`         | Hard logic, architecture decisions |
 
-Agent says what kind of work. Harness picks the right model. You touch nothing.
+Agent says what kind of work. Harness picks the right model. `ultrabrain` now routes to GPT-5.4 xhigh by default. You touch nothing.
 
 ### Claude Code Compatibility
 
@@ -310,7 +310,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, Comment Checker, Think Mode, and more
+- **Productivity Features**: Ralph Loop, Todo Enforcer, GPT permission-tail continuation, 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
@@ -327,7 +327,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, all configurable via `disabled_hooks`
+- **Hooks**: 25+ built-in hooks, including `gpt-permission-continuation`, 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

assets/oh-my-opencode.schema.json

@@ -43,7 +43,57 @@
     "disabled_hooks": {
       "type": "array",
       "items": {
-        "type": "string"
+        "type": "string",
+        "enum": [
+          "gpt-permission-continuation",
+          "todo-continuation-enforcer",
+          "context-window-monitor",
+          "session-recovery",
+          "session-notification",
+          "comment-checker",
+          "tool-output-truncator",
+          "question-label-truncator",
+          "directory-agents-injector",
+          "directory-readme-injector",
+          "empty-task-response-detector",
+          "think-mode",
+          "model-fallback",
+          "anthropic-context-window-limit-recovery",
+          "preemptive-compaction",
+          "rules-injector",
+          "background-notification",
+          "auto-update-checker",
+          "startup-toast",
+          "keyword-detector",
+          "agent-usage-reminder",
+          "non-interactive-env",
+          "interactive-bash-session",
+          "thinking-block-validator",
+          "ralph-loop",
+          "category-skill-reminder",
+          "compaction-context-injector",
+          "compaction-todo-preserver",
+          "claude-code-hooks",
+          "auto-slash-command",
+          "edit-error-recovery",
+          "json-error-recovery",
+          "delegate-task-retry",
+          "prometheus-md-only",
+          "sisyphus-junior-notepad",
+          "no-sisyphus-gpt",
+          "no-hephaestus-non-gpt",
+          "start-work",
+          "atlas",
+          "unstable-agent-babysitter",
+          "task-resume-info",
+          "stop-continuation-guard",
+          "tasks-todowrite-disabler",
+          "runtime-fallback",
+          "write-existing-file-guard",
+          "anthropic-effort",
+          "hashline-read-enhancer",
+          "read-image-resizer"
+        ]
       }
     },
     "disabled_commands": {
@@ -3678,6 +3728,16 @@
             "minimum": 0
           }
         },
+        "maxDepth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "maxDescendants": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
         "staleTimeoutMs": {
           "type": "number",
           "minimum": 60000
@@ -3732,11 +3792,16 @@
         "include_co_authored_by": {
           "default": true,
           "type": "boolean"
+        },
+        "git_env_prefix": {
+          "default": "GIT_MASTER=1",
+          "type": "string"
         }
       },
       "required": [
         "commit_footer",
-        "include_co_authored_by"
+        "include_co_authored_by",
+        "git_env_prefix"
       ],
       "additionalProperties": false
     },

docs/guide/agent-model-matching.md

@@ -147,11 +147,11 @@ When agents delegate work, they don't pick a model name — they pick a **catego
 | Category             | When Used                  | Fallback Chain                               |
 | -------------------- | -------------------------- | -------------------------------------------- |
 | `visual-engineering` | Frontend, UI, CSS, design  | Gemini 3.1 Pro → GLM 5 → Claude Opus         |
-| `ultrabrain`         | Maximum reasoning needed   | GPT-5.3 Codex → Gemini 3.1 Pro → Claude Opus |
+| `ultrabrain`         | Maximum reasoning needed   | GPT-5.4 → Gemini 3.1 Pro → Claude Opus       |
 | `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 → GPT-5-Nano     |
-| `unspecified-high`   | General complex work       | GPT-5.4 → Claude Opus → GLM 5 → K2P5         |
+| `unspecified-high`   | General complex work       | Claude Opus → GPT-5.4 (high) → GLM 5 → K2P5  |
 | `unspecified-low`    | General standard work      | Claude Sonnet → GPT-5.3 Codex → Gemini Flash |
 | `writing`            | Text, docs, prose          | Gemini Flash → Claude Sonnet                 |
 
@@ -190,7 +190,7 @@ See the [Orchestration System Guide](./orchestration.md) for how agents dispatch
   "categories": {
     "quick": { "model": "opencode/gpt-5-nano" },
     "unspecified-low": { "model": "anthropic/claude-sonnet-4-6" },
-    "unspecified-high": { "model": "openai/gpt-5.4-high" },
+    "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
     "visual-engineering": {
       "model": "google/gemini-3.1-pro",
       "variant": "high",

docs/guide/orchestration.md

@@ -296,12 +296,12 @@ task({ category: "quick", prompt: "..." }); // "Just get it done fast"
 | Category             | Model                  | When to Use                                                 |
 | -------------------- | ---------------------- | ----------------------------------------------------------- |
 | `visual-engineering` | Gemini 3.1 Pro         | Frontend, UI/UX, design, styling, animation                 |
-| `ultrabrain`         | GPT-5.3 Codex (xhigh)  | Deep logical reasoning, complex architecture decisions      |
+| `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             |
 | `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`   | GPT-5.4 (high)         | Tasks that don't fit other categories, high effort          |
+| `unspecified-high`   | Claude Opus 4.6 (max)  | Tasks that don't fit other categories, high effort          |
 | `writing`            | Gemini 3 Flash         | Documentation, prose, technical writing                     |
 
 ### Skills: Domain-Specific Instructions

docs/guide/overview.md

@@ -101,7 +101,7 @@ Use Hephaestus when you need deep architectural reasoning, complex debugging acr
 
 - **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.
 - **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.3 Codex. `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 Haiku. 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
@@ -193,13 +193,13 @@ You can override specific agents or categories in your config:
     },
 
     // General high-effort work
-    "unspecified-high": { "model": "openai/gpt-5.4", "variant": "high" },
+    "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
 
     // Quick tasks: use the cheapest models
     "quick": { "model": "anthropic/claude-haiku-4-5" },
 
-    // Deep reasoning: GPT-5.3-codex
-    "ultrabrain": { "model": "openai/gpt-5.3-codex", "variant": "xhigh" },
+    // Deep reasoning: GPT-5.4
+    "ultrabrain": { "model": "openai/gpt-5.4", "variant": "xhigh" },
   },
 }
 ```

docs/reference/configuration.md

@@ -100,7 +100,7 @@ Here's a practical starting configuration:
     "unspecified-low": { "model": "anthropic/claude-sonnet-4-6" },
 
     // unspecified-high — complex work
-    "unspecified-high": { "model": "openai/gpt-5.4-high" },
+    "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
 
     // writing — docs/prose
     "writing": { "model": "google/gemini-3-flash" },
@@ -225,12 +225,12 @@ Domain-specific model delegation used by the `task()` tool. When Sisyphus delega
 | Category             | Default Model                   | Description                                    |
 | -------------------- | ------------------------------- | ---------------------------------------------- |
 | `visual-engineering` | `google/gemini-3.1-pro` (high)  | Frontend, UI/UX, design, animation             |
-| `ultrabrain`         | `openai/gpt-5.3-codex` (xhigh)  | Deep logical reasoning, complex architecture   |
+| `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 |
 | `unspecified-low`    | `anthropic/claude-sonnet-4-6`   | General tasks, low effort                      |
-| `unspecified-high`   | `openai/gpt-5.4` (high)         | General tasks, high effort                     |
+| `unspecified-high`   | `anthropic/claude-opus-4-6` (max) | General tasks, high effort                   |
 | `writing`            | `google/gemini-3-flash`         | Documentation, prose, technical writing        |
 
 > **Note**: Built-in defaults only apply if the category is present in your config. Otherwise the system default model is used.
@@ -283,12 +283,12 @@ Disable categories: `{ "disabled_categories": ["ultrabrain"] }`
 | Category               | Default Model       | Provider Priority                                              |
 | ---------------------- | ------------------- | -------------------------------------------------------------- |
 | **visual-engineering** | `gemini-3.1-pro`    | `gemini-3.1-pro` → `glm-5` → `claude-opus-4-6`                 |
-| **ultrabrain**         | `gpt-5.3-codex`     | `gpt-5.3-codex` → `gemini-3.1-pro` → `claude-opus-4-6`         |
+| **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`       |
-| **unspecified-high**   | `gpt-5.4`           | `gpt-5.4` → `claude-opus-4-6` → `glm-5` → `k2p5` → `kimi-k2.5` |
+| **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`                         |
 
 Run `bunx oh-my-opencode doctor --verbose` to see effective model resolution for your config.
@@ -418,14 +418,15 @@ Disable built-in skills: `{ "disabled_skills": ["playwright"] }`
 Disable built-in hooks via `disabled_hooks`:
 
 ```json
-{ "disabled_hooks": ["comment-checker", "agent-usage-reminder"] }
+{ "disabled_hooks": ["comment-checker", "gpt-permission-continuation"] }
 ```
 
-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`
+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`
 
 **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

@@ -108,12 +108,12 @@ By combining these two concepts, you can generate optimal agents through `task`.
 | Category             | Default Model                   | Use Cases                                                                                                                   |
 | -------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `visual-engineering` | `google/gemini-3.1-pro`         | Frontend, UI/UX, design, styling, animation                                                                                 |
-| `ultrabrain`         | `openai/gpt-5.3-codex` (xhigh)  | Deep logical reasoning, complex architecture decisions requiring extensive analysis                                         |
+| `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                                                       |
 | `unspecified-low`    | `anthropic/claude-sonnet-4-6`   | Tasks that don't fit other categories, low effort required                                                                  |
-| `unspecified-high`   | `openai/gpt-5.4` (high)         | Tasks that don't fit other categories, high 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                                                                                     |
 
 ### Usage
@@ -332,7 +332,7 @@ You can create powerful specialized agents by combining Categories and Skills.
 
 - **Category**: `ultrabrain`
 - **load_skills**: `[]` (pure reasoning)
-- **Effect**: Leverages GPT-5.3 Codex's logical reasoning for in-depth system architecture analysis.
+- **Effect**: Leverages GPT-5.4 xhigh reasoning for in-depth system architecture analysis.
 
 #### The Maintainer (Quick Fixes)
 
@@ -680,6 +680,7 @@ 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.                                                                                                        |
@@ -734,6 +735,7 @@ 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.  |
@@ -785,10 +787,12 @@ Disable specific hooks in config:
 
 ```json
 {
-  "disabled_hooks": ["comment-checker", "auto-update-checker"]
+  "disabled_hooks": ["comment-checker", "gpt-permission-continuation"]
 }
 ```
 
+Use `gpt-permission-continuation` when you want GPT sessions to stop at permission-seeking endings instead of auto-resuming.
+
 ## MCPs
 
 ### Built-in MCPs

src/agents/anti-duplication.test.ts

@@ -0,0 +1,106 @@
+/// <reference types="bun-types" />
+
+import { describe, it, expect } from "bun:test"
+import { buildAntiDuplicationSection } from "./dynamic-agent-prompt-builder"
+import { METIS_SYSTEM_PROMPT } from "./metis"
+
+describe("buildAntiDuplicationSection", () => {
+  it("#given no arguments #when building anti-duplication section #then returns comprehensive rule section", () => {
+    //#given: no special configuration needed
+
+    //#when: building the anti-duplication section
+    const result = buildAntiDuplicationSection()
+
+    //#then: should contain the anti-duplication rule with all key concepts
+    expect(result).toContain("Anti-Duplication Rule")
+    expect(result).toContain("CRITICAL")
+    expect(result).toContain("DO NOT perform the same search yourself")
+  })
+
+  it("#given no arguments #when building #then explicitly forbids manual re-search after delegation", () => {
+    //#given: no special configuration
+
+    //#when: building the section
+    const result = buildAntiDuplicationSection()
+
+    //#then: should explicitly list forbidden behaviors
+    expect(result).toContain("FORBIDDEN")
+    expect(result).toContain("manually grep/search for the same information")
+    expect(result).toContain("Re-doing the research")
+  })
+
+  it("#given no arguments #when building #then allows non-overlapping work", () => {
+    //#given: no special configuration
+
+    //#when: building the section
+    const result = buildAntiDuplicationSection()
+
+    //#then: should explicitly allow non-overlapping work
+    expect(result).toContain("ALLOWED")
+    expect(result).toContain("non-overlapping work")
+    expect(result).toContain("work that doesn't depend on the delegated research")
+  })
+
+  it("#given no arguments #when building #then includes wait-for-results instructions", () => {
+    //#given: no special configuration
+
+    //#when: building the section
+    const result = buildAntiDuplicationSection()
+
+    //#then: should include instructions for waiting properly
+    expect(result).toContain("Wait for Results Properly")
+    expect(result).toContain("End your response")
+    expect(result).toContain("Wait for the completion notification")
+    expect(result).toContain("background_output")
+  })
+
+  it("#given no arguments #when building #then explains why this matters", () => {
+    //#given: no special configuration
+
+    //#when: building the section
+    const result = buildAntiDuplicationSection()
+
+    //#then: should explain the purpose
+    expect(result).toContain("Why This Matters")
+    expect(result).toContain("Wasted tokens")
+    expect(result).toContain("Confusion")
+    expect(result).toContain("Efficiency")
+  })
+
+  it("#given no arguments #when building #then provides code examples", () => {
+    //#given: no special configuration
+
+    //#when: building the section
+    const result = buildAntiDuplicationSection()
+
+    //#then: should include examples
+    expect(result).toContain("Example")
+    expect(result).toContain("WRONG")
+    expect(result).toContain("CORRECT")
+    expect(result).toContain("task(subagent_type=")
+  })
+
+  it("#given no arguments #when building #then uses proper markdown formatting", () => {
+    //#given: no special configuration
+
+    //#when: building the section
+    const result = buildAntiDuplicationSection()
+
+    //#then: should be wrapped in Anti_Duplication tag
+    expect(result).toContain("<Anti_Duplication>")
+    expect(result).toContain("</Anti_Duplication>")
+  })
+})
+
+describe("METIS_SYSTEM_PROMPT anti-duplication coverage", () => {
+  it("#given the system prompt #when reading delegated exploration rules #then includes anti-duplication guidance", () => {
+    // given
+    const prompt = METIS_SYSTEM_PROMPT
+
+    // when / then
+    expect(prompt).toContain("<Anti_Duplication>")
+    expect(prompt).toContain("Anti-Duplication Rule")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+    expect(prompt).toContain("non-overlapping work")
+  })
+})

src/agents/atlas/atlas-prompt.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect } from "bun:test"
+import { ATLAS_SYSTEM_PROMPT } from "./default"
+import { ATLAS_GPT_SYSTEM_PROMPT } from "./gpt"
+import { ATLAS_GEMINI_SYSTEM_PROMPT } from "./gemini"
+
+describe("Atlas prompts auto-continue policy", () => {
+  test("default variant should forbid asking user for continuation confirmation", () => {
+    // given
+    const prompt = ATLAS_SYSTEM_PROMPT
+
+    // when
+    const lowerPrompt = prompt.toLowerCase()
+
+    // then
+    expect(lowerPrompt).toContain("auto-continue policy")
+    expect(lowerPrompt).toContain("never ask the user")
+    expect(lowerPrompt).toContain("should i continue")
+    expect(lowerPrompt).toContain("proceed to next task")
+    expect(lowerPrompt).toContain("approval-style")
+    expect(lowerPrompt).toContain("auto-continue immediately")
+  })
+
+  test("gpt variant should forbid asking user for continuation confirmation", () => {
+    // given
+    const prompt = ATLAS_GPT_SYSTEM_PROMPT
+
+    // when
+    const lowerPrompt = prompt.toLowerCase()
+
+    // then
+    expect(lowerPrompt).toContain("auto-continue policy")
+    expect(lowerPrompt).toContain("never ask the user")
+    expect(lowerPrompt).toContain("should i continue")
+    expect(lowerPrompt).toContain("proceed to next task")
+    expect(lowerPrompt).toContain("approval-style")
+    expect(lowerPrompt).toContain("auto-continue immediately")
+  })
+
+  test("gemini variant should forbid asking user for continuation confirmation", () => {
+    // given
+    const prompt = ATLAS_GEMINI_SYSTEM_PROMPT
+
+    // when
+    const lowerPrompt = prompt.toLowerCase()
+
+    // then
+    expect(lowerPrompt).toContain("auto-continue policy")
+    expect(lowerPrompt).toContain("never ask the user")
+    expect(lowerPrompt).toContain("should i continue")
+    expect(lowerPrompt).toContain("proceed to next task")
+    expect(lowerPrompt).toContain("approval-style")
+    expect(lowerPrompt).toContain("auto-continue immediately")
+  })
+
+  test("all variants should require immediate continuation after verification passes", () => {
+    // given
+    const prompts = [ATLAS_SYSTEM_PROMPT, ATLAS_GPT_SYSTEM_PROMPT, ATLAS_GEMINI_SYSTEM_PROMPT]
+
+    // when / then
+    for (const prompt of prompts) {
+      const lowerPrompt = prompt.toLowerCase()
+      expect(lowerPrompt).toMatch(/auto-continue immediately after verification/)
+      expect(lowerPrompt).toMatch(/immediately delegate next task/)
+    }
+  })
+
+  test("all variants should define when user interaction is actually needed", () => {
+    // given
+    const prompts = [ATLAS_SYSTEM_PROMPT, ATLAS_GPT_SYSTEM_PROMPT, ATLAS_GEMINI_SYSTEM_PROMPT]
+
+    // when / then
+    for (const prompt of prompts) {
+      const lowerPrompt = prompt.toLowerCase()
+      expect(lowerPrompt).toMatch(/only pause.*truly blocked/)
+      expect(lowerPrompt).toMatch(/plan needs clarification|blocked by external/)
+    }
+  })
+})
+
+describe("Atlas prompts anti-duplication coverage", () => {
+  test("all variants should include anti-duplication rules for delegated exploration", () => {
+    // given
+    const prompts = [ATLAS_SYSTEM_PROMPT, ATLAS_GPT_SYSTEM_PROMPT, ATLAS_GEMINI_SYSTEM_PROMPT]
+
+    // when / then
+    for (const prompt of prompts) {
+      expect(prompt).toContain("<Anti_Duplication>")
+      expect(prompt).toContain("Anti-Duplication Rule")
+      expect(prompt).toContain("DO NOT perform the same search yourself")
+      expect(prompt).toContain("non-overlapping work")
+    }
+  })
+})
+
+describe("Atlas prompts plan path consistency", () => {
+  test("default variant should use .sisyphus/plans/{plan-name}.md path", () => {
+    // given
+    const prompt = ATLAS_SYSTEM_PROMPT
+
+    // when / then
+    expect(prompt).toContain(".sisyphus/plans/{plan-name}.md")
+    expect(prompt).not.toContain(".sisyphus/tasks/{plan-name}.yaml")
+    expect(prompt).not.toContain(".sisyphus/tasks/")
+  })
+
+  test("gpt variant should use .sisyphus/plans/{plan-name}.md path", () => {
+    // given
+    const prompt = ATLAS_GPT_SYSTEM_PROMPT
+
+    // when / then
+    expect(prompt).toContain(".sisyphus/plans/{plan-name}.md")
+    expect(prompt).not.toContain(".sisyphus/tasks/")
+  })
+
+  test("gemini variant should use .sisyphus/plans/{plan-name}.md path", () => {
+    // given
+    const prompt = ATLAS_GEMINI_SYSTEM_PROMPT
+
+    // when / then
+    expect(prompt).toContain(".sisyphus/plans/{plan-name}.md")
+    expect(prompt).not.toContain(".sisyphus/tasks/")
+  })
+
+  test("all variants should read plan file after verification", () => {
+    // given
+    const prompts = [ATLAS_SYSTEM_PROMPT, ATLAS_GPT_SYSTEM_PROMPT, ATLAS_GEMINI_SYSTEM_PROMPT]
+
+    // when / then
+    for (const prompt of prompts) {
+      expect(prompt).toMatch(/read[\s\S]*?\.sisyphus\/plans\//)
+    }
+  })
+})

src/agents/atlas/default.ts

@@ -8,6 +8,8 @@
  * - Extended reasoning sections
  */
 
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
+
 export const ATLAS_SYSTEM_PROMPT = `
 <identity>
 You are Atlas - the Master Orchestrator from OhMyOpenCode.
@@ -24,6 +26,8 @@ Implementation tasks are the means. Final Wave approval is the goal.
 One task per delegation. Parallel when independent. Verify everything.
 </mission>
 
+${buildAntiDuplicationSection()}
+
 <delegation_system>
 ## How to Delegate
 
@@ -100,6 +104,29 @@ Every \`task()\` prompt MUST include ALL 6 sections:
 **If your prompt is under 30 lines, it's TOO SHORT.**
 </delegation_system>
 
+<auto_continue>
+## AUTO-CONTINUE POLICY (STRICT)
+
+**CRITICAL: NEVER ask the user "should I continue", "proceed to next task", or any approval-style questions between plan steps.**
+
+**You MUST auto-continue immediately after verification passes:**
+- After any delegation completes and passes verification → Immediately delegate next task
+- Do NOT wait for user input, do NOT ask "should I continue"
+- Only pause or ask if you are truly blocked by missing information, an external dependency, or a critical failure
+
+**The only time you ask the user:**
+- Plan needs clarification or modification before execution
+- Blocked by an external dependency beyond your control
+- Critical failure prevents any further progress
+
+**Auto-continue examples:**
+- Task A done → Verify → Pass → Immediately start Task B
+- Task fails → Retry 3x → Still fails → Document → Move to next independent task
+- NEVER: "Should I continue to the next task?"
+
+**This is NOT optional. This is core to your role as orchestrator.**
+</auto_continue>
+
 <workflow>
 ## Step 0: Register Tracking
 

src/agents/atlas/gemini.ts

@@ -8,6 +8,8 @@
  * - Consequence-driven framing (Gemini ignores soft warnings)
  */
 
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
+
 export const ATLAS_GEMINI_SYSTEM_PROMPT = `
 <identity>
 You are Atlas - Master Orchestrator from OhMyOpenCode.
@@ -51,6 +53,8 @@ Implementation tasks are the means. Final Wave approval is the goal.
 - **Your creativity should go into ORCHESTRATION QUALITY, not implementation decisions.**
 </scope_and_design_constraints>
 
+${buildAntiDuplicationSection()}
+
 <delegation_system>
 ## How to Delegate
 
@@ -117,6 +121,29 @@ Every \`task()\` prompt MUST include ALL 6 sections:
 **Minimum 30 lines per delegation prompt. Under 30 lines = the subagent WILL fail.**
 </delegation_system>
 
+<auto_continue>
+## AUTO-CONTINUE POLICY (STRICT)
+
+**CRITICAL: NEVER ask the user "should I continue", "proceed to next task", or any approval-style questions between plan steps.**
+
+**You MUST auto-continue immediately after verification passes:**
+- After any delegation completes and passes verification → Immediately delegate next task
+- Do NOT wait for user input, do NOT ask "should I continue"
+- Only pause or ask if you are truly blocked by missing information, an external dependency, or a critical failure
+
+**The only time you ask the user:**
+- Plan needs clarification or modification before execution
+- Blocked by an external dependency beyond your control
+- Critical failure prevents any further progress
+
+**Auto-continue examples:**
+- Task A done → Verify → Pass → Immediately start Task B
+- Task fails → Retry 3x → Still fails → Document → Move to next independent task
+- NEVER: "Should I continue to the next task?"
+
+**This is NOT optional. This is core to your role as orchestrator.**
+</auto_continue>
+
 <workflow>
 ## Step 0: Register Tracking
 

src/agents/atlas/gpt.ts

@@ -8,6 +8,8 @@
  * - Scope discipline (no extra features)
  */
 
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
+
 export const ATLAS_GPT_SYSTEM_PROMPT = `
 <identity>
 You are Atlas - Master Orchestrator from OhMyOpenCode.
@@ -40,9 +42,10 @@ Implementation tasks are the means. Final Wave approval is the goal.
 </scope_and_design_constraints>
 
 <uncertainty_and_ambiguity>
-- If a task is ambiguous or underspecified:
+- During initial plan analysis, if a task is ambiguous or underspecified:
   - Ask 1-3 precise clarifying questions, OR
   - State your interpretation explicitly and proceed with the simplest approach.
+- Once execution has started, do NOT stop to ask for continuation or approval between steps.
 - Never fabricate task details, file paths, or requirements.
 - Prefer language like "Based on the plan..." instead of absolute claims.
 - When unsure about parallelization, default to sequential execution.
@@ -60,6 +63,8 @@ Implementation tasks are the means. Final Wave approval is the goal.
   3. \`Read\` for changed files
 </tool_usage_rules>
 
+${buildAntiDuplicationSection()}
+
 <delegation_system>
 ## Delegation API
 
@@ -126,6 +131,29 @@ Every \`task()\` prompt MUST include ALL 6 sections:
 **Minimum 30 lines per delegation prompt.**
 </delegation_system>
 
+<auto_continue>
+## AUTO-CONTINUE POLICY (STRICT)
+
+**CRITICAL: NEVER ask the user "should I continue", "proceed to next task", or any approval-style questions between plan steps.**
+
+**You MUST auto-continue immediately after verification passes:**
+- After any delegation completes and passes verification → Immediately delegate next task
+- Do NOT wait for user input, do NOT ask "should I continue"
+- Only pause or ask if you are truly blocked by missing information, an external dependency, or a critical failure
+
+**The only time you ask the user:**
+- Plan needs clarification or modification before execution
+- Blocked by an external dependency beyond your control
+- Critical failure prevents any further progress
+
+**Auto-continue examples:**
+- Task A done → Verify → Pass → Immediately start Task B
+- Task fails → Retry 3x → Still fails → Document → Move to next independent task
+- NEVER: "Should I continue to the next task?"
+
+**This is NOT optional. This is core to your role as orchestrator.**
+</auto_continue>
+
 <workflow>
 ## Step 0: Register Tracking
 

src/agents/builtin-agents.ts

@@ -115,6 +115,7 @@ export async function createBuiltinAgents(
     browserProvider,
     uiSelectedModel,
     availableModels,
+    isFirstRunNoCache,
     disabledSkills,
     disableOmoEnv,
   })

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

@@ -7,7 +7,7 @@ import { AGENT_MODEL_REQUIREMENTS, isModelAvailable } from "../../shared"
 import { buildAgent, isFactory } from "../agent-builder"
 import { applyOverrides } from "./agent-overrides"
 import { applyEnvironmentContext } from "./environment-context"
-import { applyModelResolution } from "./model-resolution"
+import { applyModelResolution, getFirstFallbackModel } from "./model-resolution"
 
 export function collectPendingBuiltinAgents(input: {
   agentSources: Record<BuiltinAgentName, import("../agent-builder").AgentSource>
@@ -21,6 +21,7 @@ export function collectPendingBuiltinAgents(input: {
   browserProvider?: BrowserAutomationProvider
   uiSelectedModel?: string
   availableModels: Set<string>
+  isFirstRunNoCache: boolean
   disabledSkills?: Set<string>
   useTaskSystem?: boolean
   disableOmoEnv?: boolean
@@ -37,6 +38,7 @@ export function collectPendingBuiltinAgents(input: {
     browserProvider,
     uiSelectedModel,
     availableModels,
+    isFirstRunNoCache,
     disabledSkills,
     disableOmoEnv = false,
   } = input
@@ -66,13 +68,16 @@ export function collectPendingBuiltinAgents(input: {
 
     const isPrimaryAgent = isFactory(source) && source.mode === "primary"
 
-    const resolution = applyModelResolution({
+    let resolution = applyModelResolution({
       uiSelectedModel: (isPrimaryAgent && !override?.model) ? uiSelectedModel : undefined,
       userModel: override?.model,
       requirement,
       availableModels,
       systemDefaultModel,
     })
+    if (!resolution && isFirstRunNoCache && !override?.model) {
+      resolution = getFirstFallbackModel(requirement)
+    }
     if (!resolution) continue
     const { model, variant: resolvedVariant } = resolution
 

src/agents/delegation-trust-prompt.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test"
+import { createSisyphusAgent } from "./sisyphus"
+import { createHephaestusAgent } from "./hephaestus"
+import { buildSisyphusJuniorPrompt } from "./sisyphus-junior/agent"
+import {
+  buildAntiDuplicationSection,
+  buildExploreSection,
+  type AvailableAgent,
+} from "./dynamic-agent-prompt-builder"
+
+const exploreAgent = {
+  name: "explore",
+  description: "Contextual grep specialist",
+  metadata: {
+    category: "advisor",
+    cost: "FREE",
+    promptAlias: "Explore",
+    triggers: [],
+    useWhen: ["Multiple search angles needed"],
+    avoidWhen: ["Single keyword search is enough"],
+  },
+} satisfies AvailableAgent
+
+describe("delegation trust prompt rules", () => {
+  test("buildAntiDuplicationSection explains overlap is forbidden", () => {
+    // given
+    const section = buildAntiDuplicationSection()
+
+    // when / then
+    expect(section).toContain("DO NOT perform the same search yourself")
+    expect(section).toContain("non-overlapping work")
+    expect(section).toContain("End your response")
+  })
+
+  test("buildExploreSection includes delegation trust rule", () => {
+    // given
+    const agents = [exploreAgent]
+
+    // when
+    const section = buildExploreSection(agents)
+
+    // then
+    expect(section).toContain("Delegation Trust Rule")
+    expect(section).toContain("do **not** manually perform that same search yourself")
+  })
+
+  test("Sisyphus prompt forbids duplicate delegated exploration", () => {
+    // given
+    const agent = createSisyphusAgent("anthropic/claude-sonnet-4-6", [exploreAgent])
+
+    // when
+    const prompt = agent.prompt
+
+    // then
+    expect(prompt).toContain("Continue only with non-overlapping work")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Hephaestus prompt forbids duplicate delegated exploration", () => {
+    // given
+    const agent = createHephaestusAgent("openai/gpt-5.2", [exploreAgent])
+
+    // when
+    const prompt = agent.prompt
+
+    // then
+    expect(prompt).toContain("Continue only with non-overlapping work after launching background agents")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Hephaestus GPT-5.4 prompt forbids duplicate delegated exploration", () => {
+    // given
+    const agent = createHephaestusAgent("openai/gpt-5.4", [exploreAgent])
+
+    // when
+    const prompt = agent.prompt
+
+    // then
+    expect(prompt).toContain("continue only with non-overlapping work while they search")
+    expect(prompt).toContain("Continue only with non-overlapping work after launching background agents")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Hephaestus GPT-5.3 Codex prompt forbids duplicate delegated exploration", () => {
+    // given
+    const agent = createHephaestusAgent("openai/gpt-5.3-codex", [exploreAgent])
+
+    // when
+    const prompt = agent.prompt
+
+    // then
+    expect(prompt).toContain("continue only with non-overlapping work while they search")
+    expect(prompt).toContain("Continue only with non-overlapping work after launching background agents")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Sisyphus-Junior GPT prompt forbids duplicate delegated exploration", () => {
+    // given
+    const prompt = buildSisyphusJuniorPrompt("openai/gpt-5.2", false)
+
+    // when / then
+    expect(prompt).toContain("continue only with non-overlapping work while they search")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Sisyphus GPT-5.4 prompt forbids duplicate delegated exploration", () => {
+    // given
+    const agent = createSisyphusAgent("openai/gpt-5.4", [exploreAgent])
+
+    // when
+    const prompt = agent.prompt
+
+    // then
+    expect(prompt).toContain("do only non-overlapping work simultaneously")
+    expect(prompt).toContain("Continue only with non-overlapping work")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Sisyphus-Junior GPT-5.4 prompt forbids duplicate delegated exploration", () => {
+    // given
+    const prompt = buildSisyphusJuniorPrompt("openai/gpt-5.4", false)
+
+    // when / then
+    expect(prompt).toContain("continue only with non-overlapping work while they search")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Sisyphus-Junior GPT-5.3 Codex prompt forbids duplicate delegated exploration", () => {
+    // given
+    const prompt = buildSisyphusJuniorPrompt("openai/gpt-5.3-codex", false)
+
+    // when / then
+    expect(prompt).toContain("continue only with non-overlapping work while they search")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+
+  test("Sisyphus-Junior Gemini prompt forbids duplicate delegated exploration", () => {
+    // given
+    const prompt = buildSisyphusJuniorPrompt("google/gemini-3.1-pro", false)
+
+    // when / then
+    expect(prompt).toContain("continue only with non-overlapping work while they search")
+    expect(prompt).toContain("DO NOT perform the same search yourself")
+  })
+})

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

@@ -118,6 +118,8 @@ export function buildExploreSection(agents: AvailableAgent[]): string {
 
 Use it as a **peer tool**, not a fallback. Fire liberally for discovery, not for files you already know.
 
+**Delegation Trust Rule:** Once you fire an explore agent for a search, do **not** manually perform that same search yourself. Use direct tools only for non-overlapping work or when you intentionally skipped delegation.
+
 **Use Direct Tools when:**
 ${avoidWhen.map((w) => `- ${w}`).join("\n")}
 
@@ -335,6 +337,7 @@ export function buildAntiPatternsSection(): string {
     "- **Search**: Firing agents for single-line typos or obvious syntax errors",
     "- **Debugging**: Shotgun debugging, random changes",
     "- **Background Tasks**: Polling `background_output` on running tasks — end response and wait for notification",
+    "- **Delegation Duplication**: Delegating exploration to explore/librarian and then manually doing the same search yourself",
     "- **Oracle**: Delivering answer without collecting Oracle results",
   ]
 
@@ -470,3 +473,52 @@ export function buildUltraworkSection(
 
   return lines.join("\n")
 }
+
+// Anti-duplication section for agent prompts
+export function buildAntiDuplicationSection(): string {
+  return `<Anti_Duplication>
+## Anti-Duplication Rule (CRITICAL)
+
+Once you delegate exploration to explore/librarian agents, **DO NOT perform the same search yourself**.
+
+### What this means:
+
+**FORBIDDEN:**
+- After firing explore/librarian, manually grep/search for the same information
+- Re-doing the research the agents were just tasked with
+- "Just quickly checking" the same files the background agents are checking
+
+**ALLOWED:**
+- Continue with **non-overlapping work** — work that doesn't depend on the delegated research
+- Work on unrelated parts of the codebase
+- Preparation work (e.g., setting up files, configs) that can proceed independently
+
+### Wait for Results Properly:
+
+When you need the delegated results but they're not ready:
+
+1. **End your response** — do NOT continue with work that depends on those results
+2. **Wait for the completion notification** — the system will trigger your next turn
+3. **Then** collect results via \`background_output(task_id="...")\`
+4. **Do NOT** impatiently re-search the same topics while waiting
+
+### Why This Matters:
+
+- **Wasted tokens**: Duplicate exploration wastes your context budget
+- **Confusion**: You might contradict the agent's findings
+- **Efficiency**: The whole point of delegation is parallel throughput
+
+### Example:
+
+\`\`\`typescript
+// WRONG: After delegating, re-doing the search
+task(subagent_type="explore", run_in_background=true, ...)
+// Then immediately grep for the same thing yourself — FORBIDDEN
+
+// CORRECT: Continue non-overlapping work
+task(subagent_type="explore", run_in_background=true, ...)
+// Work on a different, unrelated file while they search
+// End your response and wait for the notification
+\`\`\`
+</Anti_Duplication>`
+}

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

@@ -18,6 +18,7 @@ import {
   buildHardBlocksSection,
   buildAntiPatternsSection,
   buildToolCallFormatSection,
+  buildAntiDuplicationSection,
   categorizeTools,
 } from "../dynamic-agent-prompt-builder";
 const MODE: AgentMode = "all";
@@ -156,7 +157,7 @@ Asking the user is the LAST resort after exhausting creative alternatives.
 - Run verification (lint, tests, build) WITHOUT asking
 - Make decisions. Course-correct only on CONCRETE failure
 - Note assumptions in final message, not as questions mid-work
-- Need context? Fire explore/librarian in background IMMEDIATELY — keep working while they search
+- Need context? Fire explore/librarian in background IMMEDIATELY — continue only with non-overlapping work while they search
 - User asks "did you do X?" and you didn't → Acknowledge briefly, DO X immediately
 - 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
@@ -292,11 +293,13 @@ Prompt structure for each agent:
 - Fire 2-5 explore agents in parallel for any non-trivial codebase question
 - Parallelize independent file reads — don't read files one at a time
 - NEVER use \`run_in_background=false\` for explore/librarian
-- Continue your work immediately after launching background agents
+- Continue only with non-overlapping work after launching background agents
 - Collect results with \`background_output(task_id="...")\` when needed
 - BEFORE final answer, cancel DISPOSABLE tasks individually: \`background_cancel(taskId="bg_explore_xxx")\`, \`background_cancel(taskId="bg_librarian_xxx")\`
 - **NEVER use \`background_cancel(all=true)\`** — it kills tasks whose results you haven't collected yet
 
+${buildAntiDuplicationSection()}
+
 ### Search Stop Conditions
 
 STOP searching when:

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

@@ -16,6 +16,7 @@ import {
   buildOracleSection,
   buildHardBlocksSection,
   buildAntiPatternsSection,
+  buildAntiDuplicationSection,
 } from "../dynamic-agent-prompt-builder";
 
 function buildTodoDisciplineSection(useTaskSystem: boolean): string {
@@ -115,7 +116,7 @@ When blocked: try a different approach → decompose the problem → challenge a
 - Run verification (lint, tests, build) WITHOUT asking
 - Make decisions. Course-correct only on CONCRETE failure
 - Note assumptions in final message, not as questions mid-work
-- Need context? Fire explore/librarian in background IMMEDIATELY — keep working while they search
+- Need context? Fire explore/librarian in background IMMEDIATELY — continue only with non-overlapping work while they search
 - User asks "did you do X?" and you didn't → Acknowledge briefly, DO X immediately
 - 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
@@ -241,11 +242,13 @@ Prompt structure for each agent:
 - Fire 2-5 explore agents in parallel for any non-trivial codebase question
 - Parallelize independent file reads — don't read files one at a time
 - NEVER use \`run_in_background=false\` for explore/librarian
-- Continue your work immediately after launching background agents
+- Continue only with non-overlapping work after launching background agents
 - Collect results with \`background_output(task_id="...")\` when needed
 - BEFORE final answer, cancel DISPOSABLE tasks individually: \`background_cancel(taskId="bg_explore_xxx")\`, \`background_cancel(taskId="bg_librarian_xxx")\`
 - **NEVER use \`background_cancel(all=true)\`** — it kills tasks whose results you haven't collected yet
 
+${buildAntiDuplicationSection()}
+
 ### Search Stop Conditions
 
 STOP searching when you have enough context, the same information keeps appearing, 2 search iterations yielded nothing new, or a direct answer was found. Do not over-explore.

src/agents/hephaestus/gpt.ts

@@ -16,6 +16,7 @@ import {
   buildOracleSection,
   buildHardBlocksSection,
   buildAntiPatternsSection,
+  buildAntiDuplicationSection,
 } from "../dynamic-agent-prompt-builder";
 
 function buildTodoDisciplineSection(useTaskSystem: boolean): string {
@@ -109,7 +110,7 @@ Asking the user is the LAST resort after exhausting creative alternatives.
 - Run verification (lint, tests, build) WITHOUT asking
 - Make decisions. Course-correct only on CONCRETE failure
 - Note assumptions in final message, not as questions mid-work
-- Need context? Fire explore/librarian in background IMMEDIATELY — keep working while they search
+- Need context? Fire explore/librarian in background IMMEDIATELY — continue only with non-overlapping work while they search
 
 ## Hard Constraints
 
@@ -194,11 +195,13 @@ task(subagent_type="librarian", run_in_background=true, load_skills=[], descript
 - Fire 2-5 explore agents in parallel for any non-trivial codebase question
 - Parallelize independent file reads — don't read files one at a time
 - NEVER use \`run_in_background=false\` for explore/librarian
-- Continue your work immediately after launching background agents
+- Continue only with non-overlapping work after launching background agents
 - Collect results with \`background_output(task_id="...")\` when needed
 - BEFORE final answer, cancel DISPOSABLE tasks individually
 - **NEVER use \`background_cancel(all=true)\`**
 
+${buildAntiDuplicationSection()}
+
 ### Search Stop Conditions
 
 STOP searching when:

src/agents/metis.ts

@@ -1,5 +1,6 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
 import type { AgentMode, AgentPromptMetadata } from "./types"
+import { buildAntiDuplicationSection } from "./dynamic-agent-prompt-builder"
 import { createAgentToolRestrictions } from "../shared/permission-compat"
 
 const MODE: AgentMode = "subagent"
@@ -25,6 +26,8 @@ export const METIS_SYSTEM_PROMPT = `# Metis - Pre-Planning Consultant
 - **READ-ONLY**: You analyze, question, advise. You do NOT implement or modify files.
 - **OUTPUT**: Your analysis feeds into Prometheus (planner). Be actionable.
 
+${buildAntiDuplicationSection()}
+
 ---
 
 ## PHASE 0: INTENT CLASSIFICATION (MANDATORY FIRST STEP)

src/agents/prometheus-prompt.test.ts

@@ -1,5 +1,7 @@
 import { describe, test, expect } from "bun:test"
 import { PROMETHEUS_SYSTEM_PROMPT } from "./prometheus"
+import { PROMETHEUS_GPT_SYSTEM_PROMPT } from "./prometheus/gpt"
+import { PROMETHEUS_GEMINI_SYSTEM_PROMPT } from "./prometheus/gemini"
 
 describe("PROMETHEUS_SYSTEM_PROMPT Momus invocation policy", () => {
   test("should direct providing ONLY the file path string when invoking Momus", () => {
@@ -82,3 +84,22 @@ describe("PROMETHEUS_SYSTEM_PROMPT zero human intervention", () => {
     expect(lowerPrompt).toMatch(/zero acceptance criteria require human/)
   })
 })
+
+describe("Prometheus prompts anti-duplication coverage", () => {
+  test("all variants should include anti-duplication rules for delegated exploration", () => {
+    // given
+    const prompts = [
+      PROMETHEUS_SYSTEM_PROMPT,
+      PROMETHEUS_GPT_SYSTEM_PROMPT,
+      PROMETHEUS_GEMINI_SYSTEM_PROMPT,
+    ]
+
+    // when / then
+    for (const prompt of prompts) {
+      expect(prompt).toContain("<Anti_Duplication>")
+      expect(prompt).toContain("Anti-Duplication Rule")
+      expect(prompt).toContain("DO NOT perform the same search yourself")
+      expect(prompt).toContain("non-overlapping work")
+    }
+  })
+})

src/agents/prometheus/gemini.ts

@@ -9,6 +9,8 @@
  * - Tool-call mandate for every phase transition
  */
 
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
+
 export const PROMETHEUS_GEMINI_SYSTEM_PROMPT = `
 <identity>
 You are Prometheus - Strategic Planning Consultant from OhMyOpenCode.
@@ -43,6 +45,8 @@ A plan is "decision complete" when the implementer needs ZERO judgment calls —
 This is your north star quality metric.
 </mission>
 
+${buildAntiDuplicationSection()}
+
 <core_principles>
 ## Three Principles
 
@@ -325,4 +329,4 @@ You are Prometheus, the strategic planning consultant. You bring foresight and s
 
 export function getGeminiPrometheusPrompt(): string {
   return PROMETHEUS_GEMINI_SYSTEM_PROMPT
-}
+}

src/agents/prometheus/gpt.ts

@@ -8,6 +8,8 @@
  * - Principle-driven: Decision Complete, Explore Before Asking, Two Kinds of Unknowns
  */
 
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder";
+
 export const PROMETHEUS_GPT_SYSTEM_PROMPT = `
 <identity>
 You are Prometheus - Strategic Planning Consultant from OhMyOpenCode.
@@ -25,6 +27,8 @@ A plan is "decision complete" when the implementer needs ZERO judgment calls —
 This is your north star quality metric.
 </mission>
 
+${buildAntiDuplicationSection()}
+
 <core_principles>
 ## Three Principles (Read First)
 

src/agents/prometheus/interview-mode.ts

@@ -5,6 +5,8 @@
  * Includes intent classification, research patterns, and anti-patterns.
  */
 
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
+
 export const PROMETHEUS_INTERVIEW_MODE = `# PHASE 1: INTERVIEW MODE (DEFAULT)
 
 ## Step 0: Intent Classification (EVERY request)
@@ -29,6 +31,8 @@ Before diving into consultation, classify the work intent. This determines your
 - **Simple** (1-2 files, clear scope, <30 min work) — **Lightweight**: 1-2 targeted questions → propose approach.
 - **Complex** (3+ files, multiple components, architectural impact) — **Full consultation**: Intent-specific deep interview.
 
+${buildAntiDuplicationSection()}
+
 ---
 
 ## Intent-Specific Interview Strategies

src/agents/sisyphus-junior/default.ts

@@ -8,6 +8,7 @@
  */
 
 import { resolvePromptAppend } from "../builtin-agents/resolve-file-uri"
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
 
 export function buildDefaultSisyphusJuniorPrompt(
   useTaskSystem: boolean,
@@ -23,6 +24,8 @@ Sisyphus-Junior - Focused executor from OhMyOpenCode.
 Execute tasks directly.
 </Role>
 
+${buildAntiDuplicationSection()}
+
 ${todoDiscipline}
 
 <Verification>

src/agents/sisyphus-junior/gemini.ts

@@ -9,6 +9,7 @@
  */
 
 import { resolvePromptAppend } from "../builtin-agents/resolve-file-uri"
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
 
 export function buildGeminiSisyphusJuniorPrompt(
   useTaskSystem: boolean,
@@ -58,7 +59,7 @@ Before responding, ask yourself: What tools do I need to call? What am I assumin
 - Run verification (lint, tests, build) WITHOUT asking
 - Make decisions. Course-correct only on CONCRETE failure
 - Note assumptions in final message, not as questions mid-work
-- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — keep working while they search
+- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — continue only with non-overlapping work while they search
 
 ## Scope Discipline
 
@@ -77,13 +78,15 @@ Before responding, ask yourself: What tools do I need to call? What am I assumin
 
 <tool_usage_rules>
 - Parallelize independent tool calls: multiple file reads, grep searches, agent fires — all at once
-- Explore/Librarian via call_omo_agent = background research. Fire them and keep working
+- Explore/Librarian via call_omo_agent = background research. Fire them and continue only with non-overlapping work
 - After any file edit: restate what changed, where, and what validation follows
 - Prefer tools over guessing whenever you need specific data (files, configs, patterns)
 - ALWAYS use tools over internal knowledge for file contents, project state, and verification
 - **DO NOT SKIP tool calls because you think you already know the answer. You DON'T.**
 </tool_usage_rules>
 
+${buildAntiDuplicationSection()}
+
 ${taskDiscipline}
 
 ## Progress Updates

src/agents/sisyphus-junior/gpt-5-3-codex.ts

@@ -7,6 +7,7 @@
  */
 
 import { resolvePromptAppend } from "../builtin-agents/resolve-file-uri"
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
 
 export function buildGpt53CodexSisyphusJuniorPrompt(
   useTaskSystem: boolean,
@@ -40,7 +41,7 @@ When blocked: try a different approach → decompose the problem → challenge a
 - Run verification (lint, tests, build) WITHOUT asking
 - Make decisions. Course-correct only on CONCRETE failure
 - Note assumptions in final message, not as questions mid-work
-- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — keep working while they search
+- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — continue only with non-overlapping work while they search
 
 ## Scope Discipline
 
@@ -58,12 +59,14 @@ When blocked: try a different approach → decompose the problem → challenge a
 
 <tool_usage_rules>
 - Parallelize independent tool calls: multiple file reads, grep searches, agent fires — all at once
-- Explore/Librarian via call_omo_agent = background research. Fire them and keep working
+- Explore/Librarian via call_omo_agent = background research. Fire them and continue only with non-overlapping work
 - After any file edit: restate what changed, where, and what validation follows
 - Prefer tools over guessing whenever you need specific data (files, configs, patterns)
 - ALWAYS use tools over internal knowledge for file contents, project state, and verification
 </tool_usage_rules>
 
+${buildAntiDuplicationSection()}
+
 ${taskDiscipline}
 
 ## Progress Updates

src/agents/sisyphus-junior/gpt-5-4.ts

@@ -10,6 +10,7 @@
  */
 
 import { resolvePromptAppend } from "../builtin-agents/resolve-file-uri";
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder";
 
 export function buildGpt54SisyphusJuniorPrompt(
   useTaskSystem: boolean,
@@ -43,7 +44,7 @@ When blocked: try a different approach → decompose the problem → challenge a
 - Run verification (lint, tests, build) WITHOUT asking
 - Make decisions. Course-correct only on CONCRETE failure
 - Note assumptions in final message, not as questions mid-work
-- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — keep working while they search
+- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — continue only with non-overlapping work while they search
 
 ## Scope Discipline
 
@@ -62,12 +63,14 @@ When blocked: try a different approach → decompose the problem → challenge a
 
 <tool_usage_rules>
 - Parallelize independent tool calls: multiple file reads, grep searches, agent fires — all at once
-- Explore/Librarian via call_omo_agent = background research. Fire them and keep working
+- Explore/Librarian via call_omo_agent = background research. Fire them and continue only with non-overlapping work
 - After any file edit: restate what changed, where, and what validation follows
 - Prefer tools over guessing whenever you need specific data (files, configs, patterns)
 - ALWAYS use tools over internal knowledge for file contents, project state, and verification
 </tool_usage_rules>
 
+${buildAntiDuplicationSection()}
+
 ${taskDiscipline}
 
 ## Progress Updates

src/agents/sisyphus-junior/gpt.ts

@@ -8,6 +8,7 @@
  */
 
 import { resolvePromptAppend } from "../builtin-agents/resolve-file-uri"
+import { buildAntiDuplicationSection } from "../dynamic-agent-prompt-builder"
 
 export function buildGptSisyphusJuniorPrompt(
   useTaskSystem: boolean,
@@ -41,7 +42,7 @@ When blocked: try a different approach → decompose the problem → challenge a
 - Run verification (lint, tests, build) WITHOUT asking
 - Make decisions. Course-correct only on CONCRETE failure
 - Note assumptions in final message, not as questions mid-work
-- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — keep working while they search
+- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — continue only with non-overlapping work while they search
 
 ## Scope Discipline
 
@@ -59,12 +60,14 @@ When blocked: try a different approach → decompose the problem → challenge a
 
 <tool_usage_rules>
 - Parallelize independent tool calls: multiple file reads, grep searches, agent fires — all at once
-- Explore/Librarian via call_omo_agent = background research. Fire them and keep working
+- Explore/Librarian via call_omo_agent = background research. Fire them and continue only with non-overlapping work
 - After any file edit: restate what changed, where, and what validation follows
 - Prefer tools over guessing whenever you need specific data (files, configs, patterns)
 - ALWAYS use tools over internal knowledge for file contents, project state, and verification
 </tool_usage_rules>
 
+${buildAntiDuplicationSection()}
+
 ${taskDiscipline}
 
 ## Progress Updates

src/agents/sisyphus.ts

@@ -37,6 +37,7 @@ import {
   buildAntiPatternsSection,
   buildParallelDelegationSection,
   buildNonClaudePlannerSection,
+  buildAntiDuplicationSection,
   categorizeTools,
 } from "./dynamic-agent-prompt-builder";
 
@@ -225,17 +226,21 @@ task(subagent_type="explore", run_in_background=true, load_skills=[], descriptio
 // Reference Grep (external)
 task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find JWT security docs", prompt="I'm implementing JWT auth and need current security best practices to choose token storage (httpOnly cookies vs localStorage) and set expiration policy. Find: OWASP auth guidelines, recommended token lifetimes, refresh token rotation strategies, common JWT vulnerabilities. Skip 'what is JWT' tutorials — production security guidance only.")
 task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find Express auth patterns", prompt="I'm building Express auth middleware and need production-quality patterns to structure my middleware chain. Find how established Express apps (1000+ stars) handle: middleware ordering, token refresh, role-based access control, auth error propagation. Skip basic tutorials — I need battle-tested patterns with proper error handling.")
+// Continue only with non-overlapping work. If none exists, end your response and wait for completion.
 // WRONG: Sequential or blocking
 result = task(..., run_in_background=false)  // Never wait synchronously for explore/librarian
 \`\`\`
 
 ### Background Result Collection:
 1. Launch parallel agents \u2192 receive task_ids
-2. If you have DIFFERENT independent work \u2192 do it now
-3. Otherwise \u2192 **END YOUR RESPONSE.**
-4. System sends \`<system-reminder>\` on completion \u2192 triggers your next turn
-5. Collect via \`background_output(task_id="...")\`
-6. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+2. Continue only with non-overlapping work
+   - If you have DIFFERENT independent work \u2192 do it now
+   - Otherwise \u2192 **END YOUR RESPONSE.**
+3. System sends \`<system-reminder>\` on each task completion — then call \`background_output(task_id="...")\`
+4. Need results not yet ready? **End your response.** The notification will trigger your next turn.
+5. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+
+${buildAntiDuplicationSection()}
 
 ### Search Stop Conditions
 

src/agents/sisyphus/default.ts

@@ -21,6 +21,7 @@ import {
   buildAntiPatternsSection,
   buildParallelDelegationSection,
   buildNonClaudePlannerSection,
+  buildAntiDuplicationSection,
   categorizeTools,
 } from "../dynamic-agent-prompt-builder";
 
@@ -319,7 +320,7 @@ task(subagent_type="explore", run_in_background=true, load_skills=[], descriptio
 // Reference Grep (external)
 task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find JWT security docs", prompt="I'm implementing JWT auth and need current security best practices to choose token storage (httpOnly cookies vs localStorage) and set expiration policy. Find: OWASP auth guidelines, recommended token lifetimes, refresh token rotation strategies, common JWT vulnerabilities. Skip 'what is JWT' tutorials — production security guidance only.")
 task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find Express auth patterns", prompt="I'm building Express auth middleware and need production-quality patterns to structure my middleware chain. Find how established Express apps (1000+ stars) handle: middleware ordering, token refresh, role-based access control, auth error propagation. Skip basic tutorials — I need battle-tested patterns with proper error handling.")
-// Continue working immediately. System notifies on completion — collect with background_output then.
+// Continue only with non-overlapping work. If none exists, end your response and wait for completion.
 
 // WRONG: Sequential or blocking
 result = task(..., run_in_background=false)  // Never wait synchronously for explore/librarian
@@ -327,11 +328,14 @@ result = task(..., run_in_background=false)  // Never wait synchronously for exp
 
 ### Background Result Collection:
 1. Launch parallel agents → receive task_ids
-2. If you have DIFFERENT independent work → do it now
-3. Otherwise → **END YOUR RESPONSE.**
-4. System sends \`<system-reminder>\` on completion → triggers your next turn
-5. Collect via \`background_output(task_id="...")\`
-6. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+2. Continue only with non-overlapping work
+   - If you have DIFFERENT independent work → do it now
+   - Otherwise → **END YOUR RESPONSE.**
+3. System sends \`<system-reminder>\` on completion → triggers your next turn
+4. Collect via \`background_output(task_id="...")\`
+5. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+
+${buildAntiDuplicationSection()}
 
 ### Search Stop Conditions
 

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

@@ -37,6 +37,7 @@ import {
   buildOracleSection,
   buildHardBlocksSection,
   buildAntiPatternsSection,
+  buildAntiDuplicationSection,
   buildNonClaudePlannerSection,
   categorizeTools,
 } from "../dynamic-agent-prompt-builder";
@@ -233,7 +234,7 @@ ${librarianSection}
 <tool_method>
 - Fire 2-5 explore/librarian agents in parallel for any non-trivial codebase question.
 - Parallelize independent file reads — NEVER read files one at a time when you know multiple paths.
-- When delegating AND doing direct work: do both simultaneously.
+- When delegating AND doing direct work: do only non-overlapping work simultaneously.
 </tool_method>
 
 Explore and Librarian agents are background grep — always \`run_in_background=true\`, always parallel.
@@ -246,11 +247,14 @@ Each agent prompt should include:
 
 Background result collection:
 1. Launch parallel agents → receive task_ids
-2. If you have DIFFERENT independent work → do it now
-3. Otherwise → **END YOUR RESPONSE.**
-4. System sends \`<system-reminder>\` on completion → triggers your next turn
-5. Collect via \`background_output(task_id="...")\`
-6. Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+2. Continue only with non-overlapping work
+   - If you have DIFFERENT independent work → do it now
+   - Otherwise → **END YOUR RESPONSE.**
+3. System sends \`<system-reminder>\` on completion → triggers your next turn
+4. Collect via \`background_output(task_id="...")\`
+5. Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+
+${buildAntiDuplicationSection()}
 
 Stop searching when: you have enough context, same info repeating, 2 iterations with no new data, or direct answer found.
 </explore>`;

src/agents/utils.test.ts

@@ -483,17 +483,23 @@ describe("createBuiltinAgents without systemDefaultModel", () => {
      cacheSpy.mockRestore?.()
    })
 
-   test("agents NOT created when no cache and no systemDefaultModel (first run without defaults)", async () => {
-     // #given
-     const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(null)
+  test("oracle is created on first run when no cache and no systemDefaultModel", async () => {
+    // #given
+    const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(null)
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(new Set())
 
-     // #when
-     const agents = await createBuiltinAgents([], {}, undefined, undefined)
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, undefined)
 
-     // #then
-     expect(agents.oracle).toBeUndefined()
-     cacheSpy.mockRestore?.()
-   })
+      // #then
+      expect(agents.oracle).toBeDefined()
+      expect(agents.oracle.model).toBe("openai/gpt-5.4")
+    } finally {
+      fetchSpy.mockRestore()
+      cacheSpy.mockRestore()
+    }
+  })
 
   test("sisyphus created via connected cache fallback when all providers available", async () => {
     // #given

src/cli/cli-program.ts

@@ -69,6 +69,7 @@ program
    .passThroughOptions()
   .description("Run opencode with todo/background task completion enforcement")
   .option("-a, --agent <name>", "Agent to use (default: from CLI/env/config, fallback: Sisyphus)")
+  .option("-m, --model <provider/model>", "Model override (e.g., anthropic/claude-sonnet-4)")
   .option("-d, --directory <path>", "Working directory")
   .option("-p, --port <port>", "Server port (attaches if port already in use)", parseInt)
   .option("--attach <url>", "Attach to existing opencode server URL")
@@ -86,6 +87,8 @@ Examples:
   $ bunx oh-my-opencode run --json "Fix the bug" | jq .sessionId
   $ bunx oh-my-opencode run --on-complete "notify-send Done" "Fix the bug"
   $ bunx oh-my-opencode run --session-id ses_abc123 "Continue the work"
+  $ bunx oh-my-opencode run --model anthropic/claude-sonnet-4 "Fix the bug"
+  $ bunx oh-my-opencode run --agent Sisyphus --model openai/gpt-5.4 "Implement feature X"
 
 Agent resolution order:
   1) --agent flag
@@ -108,6 +111,7 @@ Unlike 'opencode run', this command waits until:
     const runOptions: RunOptions = {
       message,
       agent: options.agent,
+      model: options.model,
       directory: options.directory,
       port: options.port,
       attach: options.attach,

src/cli/config-manager/bun-install.test.ts

@@ -1,10 +1,37 @@
-import { beforeEach, afterEach, describe, expect, it, spyOn } from "bun:test"
+/// <reference types="bun-types" />
+
 import * as fs from "node:fs"
+
+import { afterEach, beforeEach, describe, expect, it, jest, spyOn } from "bun:test"
+
 import * as dataPath from "../../shared/data-path"
 import * as logger from "../../shared/logger"
 import * as spawnHelpers from "../../shared/spawn-with-windows-hide"
+import type { BunInstallResult } from "./bun-install"
 import { runBunInstallWithDetails } from "./bun-install"
 
+type CreateProcOptions = {
+  exitCode?: number | null
+  exited?: Promise<number>
+  kill?: () => void
+  output?: {
+    stdout?: string
+    stderr?: string
+  }
+}
+
+function createProc(options: CreateProcOptions = {}): ReturnType<typeof spawnHelpers.spawnWithWindowsHide> {
+  const exitCode = options.exitCode ?? 0
+
+  return {
+    exited: options.exited ?? Promise.resolve(exitCode),
+    exitCode,
+    stdout: options.output?.stdout !== undefined ? new Blob([options.output.stdout]).stream() : undefined,
+    stderr: options.output?.stderr !== undefined ? new Blob([options.output.stderr]).stream() : undefined,
+    kill: options.kill ?? (() => {}),
+  } satisfies ReturnType<typeof spawnHelpers.spawnWithWindowsHide>
+}
+
 describe("runBunInstallWithDetails", () => {
   let getOpenCodeCacheDirSpy: ReturnType<typeof spyOn>
   let logSpy: ReturnType<typeof spyOn>
@@ -14,11 +41,7 @@ describe("runBunInstallWithDetails", () => {
   beforeEach(() => {
     getOpenCodeCacheDirSpy = spyOn(dataPath, "getOpenCodeCacheDir").mockReturnValue("/tmp/opencode-cache")
     logSpy = spyOn(logger, "log").mockImplementation(() => {})
-    spawnWithWindowsHideSpy = spyOn(spawnHelpers, "spawnWithWindowsHide").mockReturnValue({
-      exited: Promise.resolve(0),
-      exitCode: 0,
-      kill: () => {},
-    } as ReturnType<typeof spawnHelpers.spawnWithWindowsHide>)
+    spawnWithWindowsHideSpy = spyOn(spawnHelpers, "spawnWithWindowsHide").mockReturnValue(createProc())
     existsSyncSpy = spyOn(fs, "existsSync").mockReturnValue(true)
   })
 
@@ -29,15 +52,119 @@ describe("runBunInstallWithDetails", () => {
     existsSyncSpy.mockRestore()
   })
 
-  it("runs bun install in the OpenCode cache directory", async () => {
-    const result = await runBunInstallWithDetails()
+  describe("#given the cache workspace exists", () => {
+    describe("#when bun install uses inherited output", () => {
+      it("#then runs bun install in the cache directory", async () => {
+        // given
 
-    expect(result).toEqual({ success: true })
-    expect(getOpenCodeCacheDirSpy).toHaveBeenCalledTimes(1)
-    expect(spawnWithWindowsHideSpy).toHaveBeenCalledWith(["bun", "install"], {
-      cwd: "/tmp/opencode-cache",
-      stdout: "inherit",
-      stderr: "inherit",
+        // when
+        const result = await runBunInstallWithDetails()
+
+        // then
+        expect(result).toEqual({ success: true })
+        expect(getOpenCodeCacheDirSpy).toHaveBeenCalledTimes(1)
+        expect(spawnWithWindowsHideSpy).toHaveBeenCalledWith(["bun", "install"], {
+          cwd: "/tmp/opencode-cache",
+          stdout: "inherit",
+          stderr: "inherit",
+        })
+      })
+    })
+
+    describe("#when bun install uses piped output", () => {
+      it("#then passes pipe mode to the spawned process", async () => {
+        // given
+
+        // when
+        const result = await runBunInstallWithDetails({ outputMode: "pipe" })
+
+        // then
+        expect(result).toEqual({ success: true })
+        expect(spawnWithWindowsHideSpy).toHaveBeenCalledWith(["bun", "install"], {
+          cwd: "/tmp/opencode-cache",
+          stdout: "pipe",
+          stderr: "pipe",
+        })
+      })
+    })
+
+    describe("#when piped bun install fails", () => {
+      it("#then logs captured stdout and stderr", async () => {
+        // given
+        spawnWithWindowsHideSpy.mockReturnValue(
+          createProc({
+            exitCode: 1,
+            output: {
+              stdout: "resolved 10 packages",
+              stderr: "network error",
+            },
+          })
+        )
+
+        // when
+        const result = await runBunInstallWithDetails({ outputMode: "pipe" })
+
+        // then
+        expect(result).toEqual({
+          success: false,
+          error: "bun install failed with exit code 1",
+        })
+        expect(logSpy).toHaveBeenCalledWith("[bun-install] Captured output from failed bun install", {
+          stdout: "resolved 10 packages",
+          stderr: "network error",
+        })
+      })
+    })
+
+    describe("#when the install times out and proc.exited never resolves", () => {
+      it("#then returns timedOut true without hanging", async () => {
+        // given
+        jest.useFakeTimers()
+
+        let killCallCount = 0
+        spawnWithWindowsHideSpy.mockReturnValue(
+          createProc({
+            exitCode: null,
+            exited: new Promise<number>(() => {}),
+            kill: () => {
+              killCallCount += 1
+            },
+          })
+        )
+
+        try {
+          // when
+          const resultPromise = runBunInstallWithDetails({ outputMode: "pipe" })
+          jest.advanceTimersByTime(60_000)
+          jest.runOnlyPendingTimers()
+          await Promise.resolve()
+
+          const outcome = await Promise.race([
+            resultPromise.then((result) => ({
+              status: "resolved" as const,
+              result,
+            })),
+            new Promise<{ status: "pending" }>((resolve) => {
+              queueMicrotask(() => resolve({ status: "pending" }))
+            }),
+          ])
+
+          // then
+          if (outcome.status === "pending") {
+            throw new Error("runBunInstallWithDetails did not resolve after timing out")
+          }
+
+          expect(outcome.result).toEqual({
+            success: false,
+            timedOut: true,
+            error: 'bun install timed out after 60 seconds. Try running manually: cd "/tmp/opencode-cache" && bun i',
+          } satisfies BunInstallResult)
+          expect(killCallCount).toBe(1)
+        } finally {
+          jest.clearAllTimers()
+          jest.useRealTimers()
+        }
+      })
     })
   })
 })

src/cli/config-manager/bun-install.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs"
+
 import { getOpenCodeCacheDir } from "../../shared/data-path"
 import { log } from "../../shared/logger"
 import { spawnWithWindowsHide } from "../../shared/spawn-with-windows-hide"
@@ -6,6 +7,26 @@ import { spawnWithWindowsHide } from "../../shared/spawn-with-windows-hide"
 const BUN_INSTALL_TIMEOUT_SECONDS = 60
 const BUN_INSTALL_TIMEOUT_MS = BUN_INSTALL_TIMEOUT_SECONDS * 1000
 
+type BunInstallOutputMode = "inherit" | "pipe"
+
+interface RunBunInstallOptions {
+  outputMode?: BunInstallOutputMode
+}
+
+interface BunInstallOutput {
+  stdout: string
+  stderr: string
+}
+
+declare function setTimeout(callback: () => void, delay?: number): number
+declare function clearTimeout(timeout: number): void
+
+type ProcessOutputStream = ReturnType<typeof spawnWithWindowsHide>["stdout"]
+
+declare const Bun: {
+  readableStreamToText(stream: NonNullable<ProcessOutputStream>): Promise<string>
+}
+
 export interface BunInstallResult {
   success: boolean
   timedOut?: boolean
@@ -17,7 +38,33 @@ export async function runBunInstall(): Promise<boolean> {
   return result.success
 }
 
-export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
+function readProcessOutput(stream: ProcessOutputStream): Promise<string> {
+  if (!stream) {
+    return Promise.resolve("")
+  }
+
+  return Bun.readableStreamToText(stream)
+}
+
+function logCapturedOutputOnFailure(outputMode: BunInstallOutputMode, output: BunInstallOutput): void {
+  if (outputMode !== "pipe") {
+    return
+  }
+
+  const stdout = output.stdout.trim()
+  const stderr = output.stderr.trim()
+  if (!stdout && !stderr) {
+    return
+  }
+
+  log("[bun-install] Captured output from failed bun install", {
+    stdout,
+    stderr,
+  })
+}
+
+export async function runBunInstallWithDetails(options?: RunBunInstallOptions): Promise<BunInstallResult> {
+  const outputMode = options?.outputMode ?? "inherit"
   const cacheDir = getOpenCodeCacheDir()
   const packageJsonPath = `${cacheDir}/package.json`
 
@@ -31,17 +78,23 @@ export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
   try {
     const proc = spawnWithWindowsHide(["bun", "install"], {
       cwd: cacheDir,
-      stdout: "inherit",
-      stderr: "inherit",
+      stdout: outputMode,
+      stderr: outputMode,
     })
 
-    let timeoutId: ReturnType<typeof setTimeout>
+    const outputPromise = Promise.all([readProcessOutput(proc.stdout), readProcessOutput(proc.stderr)]).then(
+      ([stdout, stderr]) => ({ stdout, stderr })
+    )
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined
     const timeoutPromise = new Promise<"timeout">((resolve) => {
       timeoutId = setTimeout(() => resolve("timeout"), BUN_INSTALL_TIMEOUT_MS)
     })
     const exitPromise = proc.exited.then(() => "completed" as const)
     const result = await Promise.race([exitPromise, timeoutPromise])
-    clearTimeout(timeoutId!)
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
 
     if (result === "timeout") {
       try {
@@ -49,6 +102,17 @@ export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
       } catch (err) {
         log("[cli/install] Failed to kill timed out bun install process:", err)
       }
+
+      if (outputMode === "pipe") {
+        void outputPromise
+          .then((output) => {
+            logCapturedOutputOnFailure(outputMode, output)
+          })
+          .catch((err) => {
+            log("[bun-install] Failed to read captured output after timeout:", err)
+          })
+      }
+
       return {
         success: false,
         timedOut: true,
@@ -56,7 +120,11 @@ export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
       }
     }
 
+    const output = await outputPromise
+
     if (proc.exitCode !== 0) {
+      logCapturedOutputOnFailure(outputMode, output)
+
       return {
         success: false,
         error: `bun install failed with exit code ${proc.exitCode}`,

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

@@ -1,8 +1,111 @@
-import { describe, expect, it } from "bun:test"
+import { afterEach, describe, expect, it } from "bun:test"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
 
-import { getSuggestedInstallTag } from "./system-loaded-version"
+import { PACKAGE_NAME } from "../constants"
+
+const systemLoadedVersionModulePath = "./system-loaded-version?system-loaded-version-test"
+
+const { getLoadedPluginVersion, getSuggestedInstallTag }: typeof import("./system-loaded-version") =
+  await import(systemLoadedVersionModulePath)
+
+const originalOpencodeConfigDir = process.env.OPENCODE_CONFIG_DIR
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME
+const temporaryDirectories: string[] = []
+
+function createTemporaryDirectory(prefix: string): string {
+  const directory = mkdtempSync(join(tmpdir(), prefix))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+function writeJson(filePath: string, value: Record<string, string | Record<string, string>>): void {
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, JSON.stringify(value), "utf-8")
+}
+
+afterEach(() => {
+  if (originalOpencodeConfigDir === undefined) {
+    delete process.env.OPENCODE_CONFIG_DIR
+  } else {
+    process.env.OPENCODE_CONFIG_DIR = originalOpencodeConfigDir
+  }
+
+  if (originalXdgCacheHome === undefined) {
+    delete process.env.XDG_CACHE_HOME
+  } else {
+    process.env.XDG_CACHE_HOME = originalXdgCacheHome
+  }
+
+  for (const directory of temporaryDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true })
+  }
+})
 
 describe("system loaded version", () => {
+  describe("getLoadedPluginVersion", () => {
+    it("prefers the config directory when both installs exist", () => {
+      //#given
+      const configDir = createTemporaryDirectory("omo-config-")
+      const cacheHome = createTemporaryDirectory("omo-cache-")
+      const cacheDir = join(cacheHome, "opencode")
+
+      process.env.OPENCODE_CONFIG_DIR = configDir
+      process.env.XDG_CACHE_HOME = cacheHome
+
+      writeJson(join(configDir, "package.json"), {
+        dependencies: { [PACKAGE_NAME]: "1.2.3" },
+      })
+      writeJson(join(configDir, "node_modules", PACKAGE_NAME, "package.json"), {
+        version: "1.2.3",
+      })
+      writeJson(join(cacheDir, "package.json"), {
+        dependencies: { [PACKAGE_NAME]: "9.9.9" },
+      })
+      writeJson(join(cacheDir, "node_modules", PACKAGE_NAME, "package.json"), {
+        version: "9.9.9",
+      })
+
+      //#when
+      const loadedVersion = getLoadedPluginVersion()
+
+      //#then
+      expect(loadedVersion.cacheDir).toBe(configDir)
+      expect(loadedVersion.cachePackagePath).toBe(join(configDir, "package.json"))
+      expect(loadedVersion.installedPackagePath).toBe(join(configDir, "node_modules", PACKAGE_NAME, "package.json"))
+      expect(loadedVersion.expectedVersion).toBe("1.2.3")
+      expect(loadedVersion.loadedVersion).toBe("1.2.3")
+    })
+
+    it("falls back to the cache directory for legacy installs", () => {
+      //#given
+      const configDir = createTemporaryDirectory("omo-config-")
+      const cacheHome = createTemporaryDirectory("omo-cache-")
+      const cacheDir = join(cacheHome, "opencode")
+
+      process.env.OPENCODE_CONFIG_DIR = configDir
+      process.env.XDG_CACHE_HOME = cacheHome
+
+      writeJson(join(cacheDir, "package.json"), {
+        dependencies: { [PACKAGE_NAME]: "2.3.4" },
+      })
+      writeJson(join(cacheDir, "node_modules", PACKAGE_NAME, "package.json"), {
+        version: "2.3.4",
+      })
+
+      //#when
+      const loadedVersion = getLoadedPluginVersion()
+
+      //#then
+      expect(loadedVersion.cacheDir).toBe(cacheDir)
+      expect(loadedVersion.cachePackagePath).toBe(join(cacheDir, "package.json"))
+      expect(loadedVersion.installedPackagePath).toBe(join(cacheDir, "node_modules", PACKAGE_NAME, "package.json"))
+      expect(loadedVersion.expectedVersion).toBe("2.3.4")
+      expect(loadedVersion.loadedVersion).toBe("2.3.4")
+    })
+  })
+
   describe("getSuggestedInstallTag", () => {
     it("returns prerelease channel when current version is prerelease", () => {
       //#given

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

@@ -5,7 +5,7 @@ import { join } from "node:path"
 import { getLatestVersion } from "../../../hooks/auto-update-checker/checker"
 import { extractChannel } from "../../../hooks/auto-update-checker"
 import { PACKAGE_NAME } from "../constants"
-import { getOpenCodeCacheDir, parseJsonc } from "../../../shared"
+import { getOpenCodeCacheDir, getOpenCodeConfigPaths, parseJsonc } from "../../../shared"
 
 interface PackageJsonShape {
   version?: string
@@ -54,9 +54,24 @@ function normalizeVersion(value: string | undefined): string | null {
 }
 
 export function getLoadedPluginVersion(): LoadedVersionInfo {
+  const configPaths = getOpenCodeConfigPaths({ binary: "opencode" })
   const cacheDir = resolveOpenCodeCacheDir()
-  const cachePackagePath = join(cacheDir, "package.json")
-  const installedPackagePath = join(cacheDir, "node_modules", PACKAGE_NAME, "package.json")
+  const candidates = [
+    {
+      cacheDir: configPaths.configDir,
+      cachePackagePath: configPaths.packageJson,
+      installedPackagePath: join(configPaths.configDir, "node_modules", PACKAGE_NAME, "package.json"),
+    },
+    {
+      cacheDir,
+      cachePackagePath: join(cacheDir, "package.json"),
+      installedPackagePath: join(cacheDir, "node_modules", PACKAGE_NAME, "package.json"),
+    },
+  ]
+
+  const selectedCandidate = candidates.find((candidate) => existsSync(candidate.installedPackagePath)) ?? candidates[0]
+
+  const { cacheDir: selectedDir, cachePackagePath, installedPackagePath } = selectedCandidate
 
   const cachePackage = readPackageJson(cachePackagePath)
   const installedPackage = readPackageJson(installedPackagePath)
@@ -65,7 +80,7 @@ export function getLoadedPluginVersion(): LoadedVersionInfo {
   const loadedVersion = normalizeVersion(installedPackage?.version)
 
   return {
-    cacheDir,
+    cacheDir: selectedDir,
     cachePackagePath,
     installedPackagePath,
     expectedVersion,

src/cli/run/index.ts

@@ -1,5 +1,6 @@
 export { run } from "./runner"
 export { resolveRunAgent } from "./agent-resolver"
+export { resolveRunModel } from "./model-resolver"
 export { createServerConnection } from "./server-connection"
 export { resolveSession } from "./session-resolver"
 export { createJsonOutputManager } from "./json-output"

src/cli/run/model-resolver.test.ts

@@ -0,0 +1,83 @@
+/// <reference types="bun-types" />
+
+import { describe, it, expect } from "bun:test"
+import { resolveRunModel } from "./model-resolver"
+
+describe("resolveRunModel", () => {
+  it("given no model string, when resolved, then returns undefined", () => {
+    // given
+    const modelString = undefined
+
+    // when
+    const result = resolveRunModel(modelString)
+
+    // then
+    expect(result).toBeUndefined()
+  })
+
+  it("given empty string, when resolved, then throws Error", () => {
+    // given
+    const modelString = ""
+
+    // when
+    const resolve = () => resolveRunModel(modelString)
+
+    // then
+    expect(resolve).toThrow()
+  })
+
+  it("given valid 'anthropic/claude-sonnet-4', when resolved, then returns correct object", () => {
+    // given
+    const modelString = "anthropic/claude-sonnet-4"
+
+    // when
+    const result = resolveRunModel(modelString)
+
+    // then
+    expect(result).toEqual({ providerID: "anthropic", modelID: "claude-sonnet-4" })
+  })
+
+  it("given nested slashes 'openai/gpt-5.3/preview', when resolved, then modelID is 'gpt-5.3/preview'", () => {
+    // given
+    const modelString = "openai/gpt-5.3/preview"
+
+    // when
+    const result = resolveRunModel(modelString)
+
+    // then
+    expect(result).toEqual({ providerID: "openai", modelID: "gpt-5.3/preview" })
+  })
+
+  it("given no slash 'claude-sonnet-4', when resolved, then throws Error", () => {
+    // given
+    const modelString = "claude-sonnet-4"
+
+    // when
+    const resolve = () => resolveRunModel(modelString)
+
+    // then
+    expect(resolve).toThrow()
+  })
+
+  it("given empty provider '/claude-sonnet-4', when resolved, then throws Error", () => {
+    // given
+    const modelString = "/claude-sonnet-4"
+
+    // when
+    const resolve = () => resolveRunModel(modelString)
+
+    // then
+    expect(resolve).toThrow()
+  })
+
+  it("given trailing slash 'anthropic/', when resolved, then throws Error", () => {
+    // given
+    const modelString = "anthropic/"
+
+    // when
+    const resolve = () => resolveRunModel(modelString)
+
+    // then
+    expect(resolve).toThrow()
+  })
+})

src/cli/run/model-resolver.ts

@@ -0,0 +1,29 @@
+export function resolveRunModel(
+  modelString?: string
+): { providerID: string; modelID: string } | undefined {
+  if (modelString === undefined) {
+    return undefined
+  }
+
+  const trimmed = modelString.trim()
+  if (trimmed.length === 0) {
+    throw new Error("Model string cannot be empty")
+  }
+
+  const parts = trimmed.split("/")
+  if (parts.length < 2) {
+    throw new Error("Model string must be in 'provider/model' format")
+  }
+
+  const providerID = parts[0]
+  if (providerID.length === 0) {
+    throw new Error("Provider cannot be empty")
+  }
+
+  const modelID = parts.slice(1).join("/")
+  if (modelID.length === 0) {
+    throw new Error("Model ID cannot be empty")
+  }
+
+  return { providerID, modelID }
+}

src/cli/run/poll-for-completion.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, mock, spyOn } from "bun:test"
+import { afterEach, beforeEach, describe, it, expect, mock, spyOn } from "bun:test"
 import type { RunContext, Todo, ChildSession, SessionStatus } from "./types"
 import { createEventState } from "./events"
 import { pollForCompletion } from "./poll-for-completion"
@@ -30,11 +30,26 @@ const createMockContext = (overrides: {
   }
 }
 
+let consoleLogSpy: ReturnType<typeof spyOn>
+let consoleErrorSpy: ReturnType<typeof spyOn>
+
+function abortAfter(abortController: AbortController, delayMs: number): void {
+  setTimeout(() => abortController.abort(), delayMs)
+}
+
+beforeEach(() => {
+  consoleLogSpy = spyOn(console, "log").mockImplementation(() => {})
+  consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {})
+})
+
+afterEach(() => {
+  consoleLogSpy.mockRestore()
+  consoleErrorSpy.mockRestore()
+})
+
 describe("pollForCompletion", () => {
   it("requires consecutive stability checks before exiting - not immediate", async () => {
     //#given - 0 todos, 0 children, session idle, meaningful work done
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -56,8 +71,6 @@ describe("pollForCompletion", () => {
 
   it("does not check completion during stabilization period after first meaningful work", async () => {
     //#given - session idle, meaningful work done, but stabilization period not elapsed
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -65,7 +78,7 @@ describe("pollForCompletion", () => {
     const abortController = new AbortController()
 
     //#when - abort after 50ms (within the 60ms stabilization period)
-    setTimeout(() => abortController.abort(), 50)
+    abortAfter(abortController, 50)
     const result = await pollForCompletion(ctx, eventState, abortController, {
       pollIntervalMs: 10,
       requiredConsecutive: 3,
@@ -80,8 +93,6 @@ describe("pollForCompletion", () => {
 
   it("does not exit when currentTool is set - resets consecutive counter", async () => {
     //#given
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -90,7 +101,7 @@ describe("pollForCompletion", () => {
     const abortController = new AbortController()
 
     //#when - abort after enough time to verify it didn't exit
-    setTimeout(() => abortController.abort(), 100)
+    abortAfter(abortController, 100)
     const result = await pollForCompletion(ctx, eventState, abortController, {
       pollIntervalMs: 10,
       requiredConsecutive: 3,
@@ -105,8 +116,6 @@ describe("pollForCompletion", () => {
 
   it("resets consecutive counter when session becomes busy between checks", async () => {
     //#given
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -147,8 +156,6 @@ describe("pollForCompletion", () => {
 
   it("returns 1 on session error", async () => {
     //#given
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -169,14 +176,12 @@ describe("pollForCompletion", () => {
 
   it("returns 130 when aborted", async () => {
     //#given
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     const abortController = new AbortController()
 
     //#when
-    setTimeout(() => abortController.abort(), 50)
+    abortAfter(abortController, 50)
     const result = await pollForCompletion(ctx, eventState, abortController, {
       pollIntervalMs: 10,
       requiredConsecutive: 3,
@@ -188,8 +193,6 @@ describe("pollForCompletion", () => {
 
   it("does not check completion when hasReceivedMeaningfulWork is false", async () => {
     //#given
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -197,7 +200,7 @@ describe("pollForCompletion", () => {
     const abortController = new AbortController()
 
     //#when
-    setTimeout(() => abortController.abort(), 100)
+    abortAfter(abortController, 100)
     const result = await pollForCompletion(ctx, eventState, abortController, {
       pollIntervalMs: 10,
       requiredConsecutive: 3,
@@ -211,8 +214,6 @@ describe("pollForCompletion", () => {
 
   it("falls back to session.status API when idle event is missing", async () => {
     //#given - mainSessionIdle not set by events, but status API says idle
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext({
       statuses: {
         "test-session": { type: "idle" },
@@ -236,8 +237,6 @@ describe("pollForCompletion", () => {
 
   it("allows silent completion after stabilization when no meaningful work is received", async () => {
     //#given - session is idle and stable but no assistant message/tool event arrived
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -257,8 +256,6 @@ describe("pollForCompletion", () => {
 
   it("uses default stabilization to avoid indefinite wait when no meaningful work arrives", async () => {
     //#given - idle with no meaningful work and no explicit minStabilization override
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -277,8 +274,6 @@ describe("pollForCompletion", () => {
 
   it("coerces non-positive stabilization values to default stabilization", async () => {
     //#given - explicit zero stabilization should still wait for default window
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -286,7 +281,7 @@ describe("pollForCompletion", () => {
     const abortController = new AbortController()
 
     //#when - abort before default 1s window elapses
-    setTimeout(() => abortController.abort(), 100)
+    abortAfter(abortController, 100)
     const result = await pollForCompletion(ctx, eventState, abortController, {
       pollIntervalMs: 10,
       requiredConsecutive: 1,
@@ -299,8 +294,6 @@ describe("pollForCompletion", () => {
 
   it("simulates race condition: brief idle with 0 todos does not cause immediate exit", async () => {
     //#given - simulate Sisyphus outputting text, session goes idle briefly, then tool fires
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true
@@ -323,7 +316,7 @@ describe("pollForCompletion", () => {
     )
 
     //#when - abort after tool stays in-flight
-    setTimeout(() => abortController.abort(), 200)
+    abortAfter(abortController, 200)
     const result = await pollForCompletion(ctx, eventState, abortController, {
       pollIntervalMs: 10,
       requiredConsecutive: 3,
@@ -335,8 +328,6 @@ describe("pollForCompletion", () => {
 
   it("returns 1 when session errors while not idle (error not masked by idle gate)", async () => {
     //#given - mainSessionIdle=false, mainSessionError=true, lastError="crash"
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = false
@@ -359,8 +350,6 @@ describe("pollForCompletion", () => {
 
   it("returns 1 when session errors while tool is active (error not masked by tool gate)", async () => {
     //#given - mainSessionIdle=true, currentTool="bash", mainSessionError=true
-    spyOn(console, "log").mockImplementation(() => {})
-    spyOn(console, "error").mockImplementation(() => {})
     const ctx = createMockContext()
     const eventState = createEventState()
     eventState.mainSessionIdle = true

src/cli/run/runner.ts

@@ -7,6 +7,7 @@ import { resolveSession } from "./session-resolver"
 import { createJsonOutputManager } from "./json-output"
 import { executeOnCompleteHook } from "./on-complete-hook"
 import { resolveRunAgent } from "./agent-resolver"
+import { resolveRunModel } from "./model-resolver"
 import { pollForCompletion } from "./poll-for-completion"
 import { loadAgentProfileColors } from "./agent-profile-colors"
 import { suppressRunInput } from "./stdin-suppression"
@@ -46,6 +47,7 @@ export async function run(options: RunOptions): Promise<number> {
 
   const pluginConfig = loadPluginConfig(directory, { command: "run" })
   const resolvedAgent = resolveRunAgent(options, pluginConfig)
+  const resolvedModel = resolveRunModel(options.model)
   const abortController = new AbortController()
 
   try {
@@ -78,6 +80,10 @@ export async function run(options: RunOptions): Promise<number> {
 
       console.log(pc.dim(`Session: ${sessionID}`))
 
+      if (resolvedModel) {
+        console.log(pc.dim(`Model: ${resolvedModel.providerID}/${resolvedModel.modelID}`))
+      }
+
       const ctx: RunContext = {
         client,
         sessionID,
@@ -96,6 +102,7 @@ export async function run(options: RunOptions): Promise<number> {
         path: { id: sessionID },
         body: {
           agent: resolvedAgent,
+          ...(resolvedModel ? { model: resolvedModel } : {}),
           tools: {
             question: false,
           },

src/cli/run/types.ts

@@ -4,6 +4,7 @@ export type { OpencodeClient }
 export interface RunOptions {
   message: string
   agent?: string
+  model?: string
   timestamp?: boolean
   verbose?: boolean
   directory?: string

src/config/schema.test.ts

@@ -884,6 +884,25 @@ describe("GitMasterConfigSchema", () => {
     //#then
     expect(result.success).toBe(false)
   })
+
+  test("accepts shell-safe git_env_prefix", () => {
+    const config = { git_env_prefix: "MY_HOOK=active" }
+
+    const result = GitMasterConfigSchema.safeParse(config)
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.git_env_prefix).toBe("MY_HOOK=active")
+    }
+  })
+
+  test("rejects git_env_prefix with shell metacharacters", () => {
+    const config = { git_env_prefix: "A=1; rm -rf /" }
+
+    const result = GitMasterConfigSchema.safeParse(config)
+
+    expect(result.success).toBe(false)
+  })
 })
 
 describe("skills schema", () => {

src/config/schema.ts

@@ -10,6 +10,7 @@ export * from "./schema/commands"
 export * from "./schema/dynamic-context-pruning"
 export * from "./schema/experimental"
 export * from "./schema/fallback-models"
+export * from "./schema/git-env-prefix"
 export * from "./schema/git-master"
 export * from "./schema/hooks"
 export * from "./schema/notification"

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

@@ -3,6 +3,54 @@ import { ZodError } from "zod/v4"
 import { BackgroundTaskConfigSchema } from "./background-task"
 
 describe("BackgroundTaskConfigSchema", () => {
+  describe("maxDepth", () => {
+    describe("#given valid maxDepth (3)", () => {
+      test("#when parsed #then returns correct value", () => {
+        const result = BackgroundTaskConfigSchema.parse({ maxDepth: 3 })
+
+        expect(result.maxDepth).toBe(3)
+      })
+    })
+
+    describe("#given maxDepth below minimum (0)", () => {
+      test("#when parsed #then throws ZodError", () => {
+        let thrownError: unknown
+
+        try {
+          BackgroundTaskConfigSchema.parse({ maxDepth: 0 })
+        } catch (error) {
+          thrownError = error
+        }
+
+        expect(thrownError).toBeInstanceOf(ZodError)
+      })
+    })
+  })
+
+  describe("maxDescendants", () => {
+    describe("#given valid maxDescendants (50)", () => {
+      test("#when parsed #then returns correct value", () => {
+        const result = BackgroundTaskConfigSchema.parse({ maxDescendants: 50 })
+
+        expect(result.maxDescendants).toBe(50)
+      })
+    })
+
+    describe("#given maxDescendants below minimum (0)", () => {
+      test("#when parsed #then throws ZodError", () => {
+        let thrownError: unknown
+
+        try {
+          BackgroundTaskConfigSchema.parse({ maxDescendants: 0 })
+        } catch (error) {
+          thrownError = error
+        }
+
+        expect(thrownError).toBeInstanceOf(ZodError)
+      })
+    })
+  })
+
   describe("syncPollTimeoutMs", () => {
     describe("#given valid syncPollTimeoutMs (120000)", () => {
       test("#when parsed #then returns correct value", () => {

src/config/schema/background-task.ts

@@ -4,9 +4,11 @@ export const BackgroundTaskConfigSchema = z.object({
   defaultConcurrency: z.number().min(1).optional(),
   providerConcurrency: z.record(z.string(), z.number().min(0)).optional(),
   modelConcurrency: z.record(z.string(), z.number().min(0)).optional(),
+  maxDepth: z.number().int().min(1).optional(),
+  maxDescendants: z.number().int().min(1).optional(),
   /** Stale timeout in milliseconds - interrupt tasks with no activity for this duration (default: 180000 = 3 minutes, minimum: 60000 = 1 minute) */
   staleTimeoutMs: z.number().min(60000).optional(),
-  /** Timeout for tasks that never received any progress update, falling back to startedAt (default: 600000 = 10 minutes, minimum: 60000 = 1 minute) */
+  /** Timeout for tasks that never received any progress update, falling back to startedAt (default: 1800000 = 30 minutes, minimum: 60000 = 1 minute) */
   messageStalenessTimeoutMs: z.number().min(60000).optional(),
   syncPollTimeoutMs: z.number().min(60000).optional(),
 })

src/config/schema/git-env-prefix.ts

@@ -0,0 +1,28 @@
+import { z } from "zod"
+
+const GIT_ENV_ASSIGNMENT_PATTERN =
+	/^(?:[A-Za-z_][A-Za-z0-9_]*=[A-Za-z0-9_-]*)(?: [A-Za-z_][A-Za-z0-9_]*=[A-Za-z0-9_-]*)*$/
+
+export const GIT_ENV_PREFIX_VALIDATION_MESSAGE =
+	'git_env_prefix must be empty or use shell-safe env assignments like "GIT_MASTER=1"'
+
+export function isValidGitEnvPrefix(value: string): boolean {
+	if (value === "") {
+		return true
+	}
+
+	return GIT_ENV_ASSIGNMENT_PATTERN.test(value)
+}
+
+export function assertValidGitEnvPrefix(value: string): string {
+	if (!isValidGitEnvPrefix(value)) {
+		throw new Error(GIT_ENV_PREFIX_VALIDATION_MESSAGE)
+	}
+
+	return value
+}
+
+export const GitEnvPrefixSchema = z
+	.string()
+	.refine(isValidGitEnvPrefix, { message: GIT_ENV_PREFIX_VALIDATION_MESSAGE })
+	.default("GIT_MASTER=1")

src/config/schema/git-master.ts

@@ -1,10 +1,14 @@
 import { z } from "zod"
 
+import { GitEnvPrefixSchema } from "./git-env-prefix"
+
 export const GitMasterConfigSchema = z.object({
   /** Add "Ultraworked with Sisyphus" footer to commit messages (default: true). Can be boolean or custom string. */
   commit_footer: z.union([z.boolean(), z.string()]).default(true),
   /** Add "Co-authored-by: Sisyphus" trailer to commit messages (default: true) */
   include_co_authored_by: z.boolean().default(true),
+  /** Environment variable prefix for all git commands (default: "GIT_MASTER=1"). Set to "" to disable. Allows custom git hooks to detect git-master skill usage. */
+  git_env_prefix: GitEnvPrefixSchema,
 })
 
 export type GitMasterConfig = z.infer<typeof GitMasterConfigSchema>

src/config/schema/hooks.ts

@@ -1,6 +1,7 @@
 import { z } from "zod"
 
 export const HookNameSchema = z.enum([
+  "gpt-permission-continuation",
   "todo-continuation-enforcer",
   "context-window-monitor",
   "session-recovery",

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

@@ -11,6 +11,7 @@ import { CommentCheckerConfigSchema } from "./comment-checker"
 import { BuiltinCommandNameSchema } from "./commands"
 import { ExperimentalConfigSchema } from "./experimental"
 import { GitMasterConfigSchema } from "./git-master"
+import { HookNameSchema } from "./hooks"
 import { NotificationConfigSchema } from "./notification"
 import { RalphLoopConfigSchema } from "./ralph-loop"
 import { RuntimeFallbackConfigSchema } from "./runtime-fallback"
@@ -30,7 +31,7 @@ export const OhMyOpenCodeConfigSchema = z.object({
   disabled_mcps: z.array(AnyMcpNameSchema).optional(),
   disabled_agents: z.array(z.string()).optional(),
   disabled_skills: z.array(BuiltinSkillNameSchema).optional(),
-  disabled_hooks: z.array(z.string()).optional(),
+  disabled_hooks: z.array(HookNameSchema).optional(),
   disabled_commands: z.array(BuiltinCommandNameSchema).optional(),
   /** Disable specific tools by name (e.g., ["todowrite", "todoread"]) */
   disabled_tools: z.array(z.string()).optional(),

src/features/background-agent/compaction-aware-message-resolver.test.ts

@@ -2,7 +2,15 @@ import { describe, test, expect, beforeEach, afterEach } from "bun:test"
 import { mkdtempSync, writeFileSync, rmSync } from "node:fs"
 import { join } from "node:path"
 import { tmpdir } from "node:os"
-import { isCompactionAgent, findNearestMessageExcludingCompaction } from "./compaction-aware-message-resolver"
+import {
+  isCompactionAgent,
+  findNearestMessageExcludingCompaction,
+  resolvePromptContextFromSessionMessages,
+} from "./compaction-aware-message-resolver"
+import {
+  clearCompactionAgentConfigCheckpoint,
+  setCompactionAgentConfigCheckpoint,
+} from "../../shared/compaction-agent-config-checkpoint"
 
 describe("isCompactionAgent", () => {
   describe("#given agent name variations", () => {
@@ -65,6 +73,7 @@ describe("findNearestMessageExcludingCompaction", () => {
 
   afterEach(() => {
     rmSync(tempDir, { force: true, recursive: true })
+    clearCompactionAgentConfigCheckpoint("ses_checkpoint")
   })
 
   describe("#given directory with messages", () => {
@@ -186,5 +195,65 @@ describe("findNearestMessageExcludingCompaction", () => {
       expect(result).not.toBeNull()
       expect(result?.agent).toBe("newer")
     })
+
+    test("merges partial metadata from multiple recent messages", () => {
+      // given
+      writeFileSync(
+        join(tempDir, "003.json"),
+        JSON.stringify({ model: { providerID: "anthropic", modelID: "claude-opus-4-1" } }),
+      )
+      writeFileSync(join(tempDir, "002.json"), JSON.stringify({ agent: "atlas" }))
+      writeFileSync(join(tempDir, "001.json"), JSON.stringify({ tools: { bash: true } }))
+
+      // when
+      const result = findNearestMessageExcludingCompaction(tempDir)
+
+      // then
+      expect(result).toEqual({
+        agent: "atlas",
+        model: { providerID: "anthropic", modelID: "claude-opus-4-1" },
+        tools: { bash: true },
+      })
+    })
+
+    test("fills missing metadata from compaction checkpoint", () => {
+      // given
+      setCompactionAgentConfigCheckpoint("ses_checkpoint", {
+        agent: "sisyphus",
+        model: { providerID: "openai", modelID: "gpt-5" },
+      })
+      writeFileSync(join(tempDir, "001.json"), JSON.stringify({ tools: { bash: true } }))
+
+      // when
+      const result = findNearestMessageExcludingCompaction(tempDir, "ses_checkpoint")
+
+      // then
+      expect(result).toEqual({
+        agent: "sisyphus",
+        model: { providerID: "openai", modelID: "gpt-5" },
+        tools: { bash: true },
+      })
+    })
+  })
+})
+
+describe("resolvePromptContextFromSessionMessages", () => {
+  test("merges partial prompt context from recent SDK messages", () => {
+    // given
+    const messages = [
+      { info: { agent: "atlas" } },
+      { info: { model: { providerID: "anthropic", modelID: "claude-opus-4-1" } } },
+      { info: { tools: { bash: true } } },
+    ]
+
+    // when
+    const result = resolvePromptContextFromSessionMessages(messages)
+
+    // then
+    expect(result).toEqual({
+      agent: "atlas",
+      model: { providerID: "anthropic", modelID: "claude-opus-4-1" },
+      tools: { bash: true },
+    })
   })
 })

src/features/background-agent/compaction-aware-message-resolver.ts

@@ -1,6 +1,21 @@
 import { readdirSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 import type { StoredMessage } from "../hook-message-injector"
+import { getCompactionAgentConfigCheckpoint } from "../../shared/compaction-agent-config-checkpoint"
+
+type SessionMessage = {
+  info?: {
+    agent?: string
+    model?: {
+      providerID?: string
+      modelID?: string
+      variant?: string
+    }
+    providerID?: string
+    modelID?: string
+    tools?: StoredMessage["tools"]
+  }
+}
 
 export function isCompactionAgent(agent: string | undefined): boolean {
   return agent?.trim().toLowerCase() === "compaction"
@@ -16,42 +31,121 @@ function hasFullAgentAndModel(message: StoredMessage): boolean {
 function hasPartialAgentOrModel(message: StoredMessage): boolean {
   const hasAgent = !!message.agent && !isCompactionAgent(message.agent)
   const hasModel = !!message.model?.providerID && !!message.model?.modelID
-  return hasAgent || hasModel
+  return hasAgent || hasModel || !!message.tools
 }
 
-export function findNearestMessageExcludingCompaction(messageDir: string): StoredMessage | null {
-  try {
-    const files = readdirSync(messageDir)
-      .filter((name) => name.endsWith(".json"))
-      .sort()
-      .reverse()
-
-    for (const file of files) {
-      try {
-        const content = readFileSync(join(messageDir, file), "utf-8")
-        const parsed = JSON.parse(content) as StoredMessage
-        if (hasFullAgentAndModel(parsed)) {
-          return parsed
-        }
-      } catch {
-        continue
-      }
-    }
-
-    for (const file of files) {
-      try {
-        const content = readFileSync(join(messageDir, file), "utf-8")
-        const parsed = JSON.parse(content) as StoredMessage
-        if (hasPartialAgentOrModel(parsed)) {
-          return parsed
-        }
-      } catch {
-        continue
-      }
-    }
-  } catch {
+function convertSessionMessageToStoredMessage(message: SessionMessage): StoredMessage | null {
+  const info = message.info
+  if (!info) {
     return null
   }
 
-  return null
+  const providerID = info.model?.providerID ?? info.providerID
+  const modelID = info.model?.modelID ?? info.modelID
+
+  return {
+    ...(info.agent ? { agent: info.agent } : {}),
+    ...(providerID && modelID
+      ? {
+          model: {
+            providerID,
+            modelID,
+            ...(info.model?.variant ? { variant: info.model.variant } : {}),
+          },
+        }
+      : {}),
+    ...(info.tools ? { tools: info.tools } : {}),
+  }
+}
+
+function mergeStoredMessages(
+  messages: Array<StoredMessage | null>,
+  sessionID?: string,
+): StoredMessage | null {
+  const merged: StoredMessage = {}
+
+  for (const message of messages) {
+    if (!message || isCompactionAgent(message.agent)) {
+      continue
+    }
+
+    if (!merged.agent && message.agent) {
+      merged.agent = message.agent
+    }
+
+    if (!merged.model?.providerID && message.model?.providerID && message.model.modelID) {
+      merged.model = {
+        providerID: message.model.providerID,
+        modelID: message.model.modelID,
+        ...(message.model.variant ? { variant: message.model.variant } : {}),
+      }
+    }
+
+    if (!merged.tools && message.tools) {
+      merged.tools = message.tools
+    }
+
+    if (hasFullAgentAndModel(merged) && merged.tools) {
+      break
+    }
+  }
+
+  const checkpoint = sessionID
+    ? getCompactionAgentConfigCheckpoint(sessionID)
+    : undefined
+
+  if (!merged.agent && checkpoint?.agent) {
+    merged.agent = checkpoint.agent
+  }
+
+  if (!merged.model && checkpoint?.model) {
+    merged.model = {
+      providerID: checkpoint.model.providerID,
+      modelID: checkpoint.model.modelID,
+    }
+  }
+
+  if (!merged.tools && checkpoint?.tools) {
+    merged.tools = checkpoint.tools
+  }
+
+  return hasPartialAgentOrModel(merged) ? merged : null
+}
+
+export function resolvePromptContextFromSessionMessages(
+  messages: SessionMessage[],
+  sessionID?: string,
+): StoredMessage | null {
+  const convertedMessages = messages
+    .map(convertSessionMessageToStoredMessage)
+    .reverse()
+
+  return mergeStoredMessages(convertedMessages, sessionID)
+}
+
+export function findNearestMessageExcludingCompaction(
+  messageDir: string,
+  sessionID?: string,
+): StoredMessage | null {
+  try {
+    const files = readdirSync(messageDir)
+      .filter((name: string) => name.endsWith(".json"))
+      .sort()
+      .reverse()
+
+    const messages: Array<StoredMessage | null> = []
+
+    for (const file of files) {
+      try {
+        const content = readFileSync(join(messageDir, file), "utf-8")
+        messages.push(JSON.parse(content) as StoredMessage)
+      } catch {
+        continue
+      }
+    }
+
+    return mergeStoredMessages(messages, sessionID)
+  } catch {
+    return null
+  }
 }

src/features/background-agent/constants.ts

@@ -4,7 +4,7 @@ import type { BackgroundTask, LaunchInput } from "./types"
 export const TASK_TTL_MS = 30 * 60 * 1000
 export const MIN_STABILITY_TIME_MS = 10 * 1000
 export const DEFAULT_STALE_TIMEOUT_MS = 180_000
-export const DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS = 600_000
+export const DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS = 1_800_000
 export const MIN_RUNTIME_BEFORE_STALE_MS = 30_000
 export const MIN_IDLE_TIME_MS = 5000
 export const POLLING_INTERVAL_MS = 3000

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

@@ -0,0 +1,60 @@
+declare const require: (name: string) => any
+const { describe, expect, test, mock } = require("bun:test")
+
+import { DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS } from "./constants"
+import { checkAndInterruptStaleTasks } from "./task-poller"
+import type { BackgroundTask } from "./types"
+
+function createRunningTask(startedAt: Date): BackgroundTask {
+  return {
+    id: "task-1",
+    sessionID: "ses-1",
+    parentSessionID: "parent-ses-1",
+    parentMessageID: "msg-1",
+    description: "test",
+    prompt: "test",
+    agent: "explore",
+    status: "running",
+    startedAt,
+    progress: undefined,
+  }
+}
+
+describe("DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS", () => {
+  test("uses a 30 minute default", () => {
+    // #given
+    const expectedTimeout = 30 * 60 * 1000
+
+    // #when
+    const timeout = DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS
+
+    // #then
+    expect(timeout).toBe(expectedTimeout)
+  })
+
+  test("does not interrupt a never-updated task after 15 minutes when config is omitted", async () => {
+    // #given
+    const task = createRunningTask(new Date(Date.now() - 15 * 60 * 1000))
+    const client = {
+      session: {
+        abort: mock(() => Promise.resolve()),
+      },
+    }
+    const concurrencyManager = {
+      release: mock(() => {}),
+    }
+    const notifyParentSession = mock(() => Promise.resolve())
+
+    // #when
+    await checkAndInterruptStaleTasks({
+      tasks: [task],
+      client: client as never,
+      config: undefined,
+      concurrencyManager: concurrencyManager as never,
+      notifyParentSession,
+    })
+
+    // #then
+    expect(task.status).toBe("running")
+  })
+})

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

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test"
+import { tmpdir } from "node:os"
+
+import type { PluginInput } from "@opencode-ai/plugin"
+
+import { BackgroundManager } from "./manager"
+
+describe("BackgroundManager session permission", () => {
+  test("passes explicit session permission rules to child session creation", async () => {
+    // given
+    const createCalls: Array<Record<string, unknown>> = []
+    const client = {
+      session: {
+        get: async () => ({ data: { directory: "/parent" } }),
+        create: async (input: Record<string, unknown>) => {
+          createCalls.push(input)
+          return { data: { id: "ses_child" } }
+        },
+        promptAsync: async () => ({}),
+        abort: async () => ({}),
+      },
+    }
+    const manager = new BackgroundManager({ client, directory: tmpdir() } as unknown as PluginInput)
+
+    // when
+    await manager.launch({
+      description: "Test task",
+      prompt: "Do something",
+      agent: "explore",
+      parentSessionID: "ses_parent",
+      parentMessageID: "msg_parent",
+      sessionPermission: [
+        { permission: "question", action: "deny", pattern: "*" },
+      ],
+    })
+    await new Promise(resolve => setTimeout(resolve, 50))
+    manager.shutdown()
+
+    // then
+    expect(createCalls).toHaveLength(1)
+    expect(createCalls[0]?.body).toEqual({
+      parentID: "ses_parent",
+      title: "Test task (@explore subagent)",
+      permission: [
+        { permission: "question", action: "deny", pattern: "*" },
+      ],
+    })
+  })
+})

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

@@ -224,6 +224,12 @@ function stubNotifyParentSession(manager: BackgroundManager): void {
   ;(manager as unknown as { notifyParentSession: () => Promise<void> }).notifyParentSession = async () => {}
 }
 
+async function flushBackgroundNotifications(): Promise<void> {
+  for (let i = 0; i < 6; i++) {
+    await Promise.resolve()
+  }
+}
+
 function createToastRemoveTaskTracker(): { removeTaskCalls: string[]; resetToastManager: () => void } {
   _resetTaskToastManagerForTesting()
   const toastManager = initTaskToastManager({
@@ -1306,11 +1312,20 @@ describe("BackgroundManager.tryCompleteTask", () => {
     expect(abortedSessionIDs).toEqual(["session-1"])
   })
 
-  test("should clean pendingByParent even when notifyParentSession throws", async () => {
+  test("should clean pendingByParent even when promptAsync notification fails", async () => {
     // given
-    ;(manager as unknown as { notifyParentSession: () => Promise<void> }).notifyParentSession = async () => {
-      throw new Error("notify failed")
+    const client = {
+      session: {
+        prompt: async () => ({}),
+        promptAsync: async () => {
+          throw new Error("notify failed")
+        },
+        abort: async () => ({}),
+        messages: async () => ({ data: [] }),
+      },
     }
+    manager.shutdown()
+    manager = new BackgroundManager({ client, directory: tmpdir() } as unknown as PluginInput)
 
     const task: BackgroundTask = {
       id: "task-pending-cleanup",
@@ -1518,7 +1533,7 @@ describe("BackgroundManager.tryCompleteTask", () => {
     // then
     expect(rejectedCount).toBe(0)
     expect(promptBodies.length).toBe(2)
-    expect(promptBodies.some((b) => b.noReply === false)).toBe(true)
+    expect(promptBodies.filter((body) => body.noReply === false)).toHaveLength(1)
   })
 })
 
@@ -1731,6 +1746,32 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
      }
    }
 
+  function createMockClientWithSessionChain(
+      sessions: Record<string, { directory: string; parentID?: string }>,
+      options?: { sessionLookupError?: Error }
+    ) {
+      return {
+        session: {
+          create: async (_args?: any) => ({ data: { id: `ses_${crypto.randomUUID()}` } }),
+          get: async ({ path }: { path: { id: string } }) => {
+            if (options?.sessionLookupError) {
+              throw options.sessionLookupError
+            }
+
+            return {
+              data: sessions[path.id] ?? { directory: "/test/dir" },
+            }
+          },
+          prompt: async () => ({}),
+          promptAsync: async () => ({}),
+          messages: async () => ({ data: [] }),
+          todo: async () => ({ data: [] }),
+          status: async () => ({ data: {} }),
+          abort: async () => ({}),
+        },
+      }
+    }
+
   beforeEach(() => {
     // given
     mockClient = createMockClient()
@@ -1925,6 +1966,151 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
         expect(updatedTask.startedAt.getTime()).toBeGreaterThanOrEqual(queuedAt.getTime())
       }
     })
+
+    test("should track rootSessionID and spawnDepth from the parent chain", async () => {
+      // given
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain({
+            "session-depth-2": { directory: "/test/dir", parentID: "session-depth-1" },
+            "session-depth-1": { directory: "/test/dir", parentID: "session-root" },
+            "session-root": { directory: "/test/dir" },
+          }),
+          directory: tmpdir(),
+        } as unknown as PluginInput,
+        { maxDepth: 3 },
+      )
+
+      const input = {
+        description: "Test task",
+        prompt: "Do something",
+        agent: "test-agent",
+        parentSessionID: "session-depth-2",
+        parentMessageID: "parent-message",
+      }
+
+      // when
+      const task = await manager.launch(input)
+
+      // then
+      expect(task.rootSessionID).toBe("session-root")
+      expect(task.spawnDepth).toBe(3)
+    })
+
+    test("should block launches that exceed maxDepth", async () => {
+      // given
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain({
+            "session-depth-3": { directory: "/test/dir", parentID: "session-depth-2" },
+            "session-depth-2": { directory: "/test/dir", parentID: "session-depth-1" },
+            "session-depth-1": { directory: "/test/dir", parentID: "session-root" },
+            "session-root": { directory: "/test/dir" },
+          }),
+          directory: tmpdir(),
+        } as unknown as PluginInput,
+        { maxDepth: 3 },
+      )
+
+      const input = {
+        description: "Test task",
+        prompt: "Do something",
+        agent: "test-agent",
+        parentSessionID: "session-depth-3",
+        parentMessageID: "parent-message",
+      }
+
+      // when
+      const result = manager.launch(input)
+
+      // then
+      await expect(result).rejects.toThrow("background_task.maxDepth=3")
+    })
+
+    test("should block launches when maxDescendants is reached", async () => {
+      // given
+      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",
+      }
+
+      await manager.launch(input)
+
+      // when
+      const result = manager.launch(input)
+
+      // then
+      await expect(result).rejects.toThrow("background_task.maxDescendants=1")
+    })
+
+    test("should consume descendant quota for reserved sync spawns", async () => {
+      // given
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain({
+            "session-root": { directory: "/test/dir" },
+          }),
+          directory: tmpdir(),
+        } as unknown as PluginInput,
+        { maxDescendants: 1 },
+      )
+
+      await manager.reserveSubagentSpawn("session-root")
+
+      // when
+      const result = manager.assertCanSpawn("session-root")
+
+      // then
+      await expect(result).rejects.toThrow("background_task.maxDescendants=1")
+    })
+
+    test("should fail closed when session lineage lookup fails", async () => {
+      // given
+      manager.shutdown()
+      manager = new BackgroundManager(
+        {
+          client: createMockClientWithSessionChain(
+            {
+              "session-root": { directory: "/test/dir" },
+            },
+            { sessionLookupError: new Error("session lookup failed") }
+          ),
+          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",
+      }
+
+      // when
+      const result = manager.launch(input)
+
+      // then
+      await expect(result).rejects.toThrow("background_task.maxDescendants cannot be enforced safely")
+    })
   })
 
   describe("pending task can be cancelled", () => {
@@ -2026,7 +2212,6 @@ describe("BackgroundManager - Non-blocking Queue Integration", () => {
     test("should cancel running task and release concurrency", async () => {
       // given
       const manager = createBackgroundManager()
-      stubNotifyParentSession(manager)
 
       const concurrencyManager = getConcurrencyManager(manager)
       const concurrencyKey = "test-provider/test-model"
@@ -2984,7 +3169,7 @@ describe("BackgroundManager.shutdown session abort", () => {
 })
 
 describe("BackgroundManager.handleEvent - session.deleted cascade", () => {
-  test("should cancel descendant tasks when parent session is deleted", () => {
+  test("should cancel descendant tasks and keep them until delayed cleanup", async () => {
     // given
     const manager = createBackgroundManager()
     const parentSessionID = "session-parent"
@@ -3031,21 +3216,26 @@ describe("BackgroundManager.handleEvent - session.deleted cascade", () => {
       properties: { info: { id: parentSessionID } },
     })
 
+    await flushBackgroundNotifications()
+
     // then
-    expect(taskMap.has(childTask.id)).toBe(false)
-    expect(taskMap.has(siblingTask.id)).toBe(false)
-    expect(taskMap.has(grandchildTask.id)).toBe(false)
+    expect(taskMap.has(childTask.id)).toBe(true)
+    expect(taskMap.has(siblingTask.id)).toBe(true)
+    expect(taskMap.has(grandchildTask.id)).toBe(true)
     expect(taskMap.has(unrelatedTask.id)).toBe(true)
     expect(childTask.status).toBe("cancelled")
     expect(siblingTask.status).toBe("cancelled")
     expect(grandchildTask.status).toBe("cancelled")
     expect(pendingByParent.get(parentSessionID)).toBeUndefined()
     expect(pendingByParent.get("session-child")).toBeUndefined()
+    expect(getCompletionTimers(manager).has(childTask.id)).toBe(true)
+    expect(getCompletionTimers(manager).has(siblingTask.id)).toBe(true)
+    expect(getCompletionTimers(manager).has(grandchildTask.id)).toBe(true)
 
     manager.shutdown()
   })
 
-  test("should remove tasks from toast manager when session is deleted", () => {
+  test("should remove cancelled tasks from toast manager while preserving delayed cleanup", async () => {
     //#given
     const { removeTaskCalls, resetToastManager } = createToastRemoveTaskTracker()
     const manager = createBackgroundManager()
@@ -3074,9 +3264,13 @@ describe("BackgroundManager.handleEvent - session.deleted cascade", () => {
       properties: { info: { id: parentSessionID } },
     })
 
+    await flushBackgroundNotifications()
+
     //#then
     expect(removeTaskCalls).toContain(childTask.id)
     expect(removeTaskCalls).toContain(grandchildTask.id)
+    expect(getCompletionTimers(manager).has(childTask.id)).toBe(true)
+    expect(getCompletionTimers(manager).has(grandchildTask.id)).toBe(true)
 
     manager.shutdown()
     resetToastManager()
@@ -3139,7 +3333,7 @@ describe("BackgroundManager.handleEvent - session.error", () => {
     return task
   }
 
-  test("sets task to error, releases concurrency, and cleans up", async () => {
+  test("sets task to error, releases concurrency, and keeps it until delayed cleanup", async () => {
     //#given
     const manager = createBackgroundManager()
     const concurrencyManager = getConcurrencyManager(manager)
@@ -3172,18 +3366,21 @@ describe("BackgroundManager.handleEvent - session.error", () => {
       },
     })
 
+    await flushBackgroundNotifications()
+
     //#then
     expect(task.status).toBe("error")
     expect(task.error).toBe("Model not found: kimi-for-coding/k2p5.")
     expect(task.completedAt).toBeInstanceOf(Date)
     expect(concurrencyManager.getCount(concurrencyKey)).toBe(0)
-    expect(getTaskMap(manager).has(task.id)).toBe(false)
+    expect(getTaskMap(manager).has(task.id)).toBe(true)
     expect(getPendingByParent(manager).get(task.parentSessionID)).toBeUndefined()
+    expect(getCompletionTimers(manager).has(task.id)).toBe(true)
 
     manager.shutdown()
   })
 
-  test("removes errored task from toast manager", () => {
+  test("should remove errored task from toast manager while preserving delayed cleanup", async () => {
     //#given
     const { removeTaskCalls, resetToastManager } = createToastRemoveTaskTracker()
     const manager = createBackgroundManager()
@@ -3205,8 +3402,11 @@ describe("BackgroundManager.handleEvent - session.error", () => {
       },
     })
 
+    await flushBackgroundNotifications()
+
     //#then
     expect(removeTaskCalls).toContain(task.id)
+    expect(getCompletionTimers(manager).has(task.id)).toBe(true)
 
     manager.shutdown()
     resetToastManager()
@@ -3489,7 +3689,7 @@ describe("BackgroundManager.pruneStaleTasksAndNotifications - removes pruned tas
     manager.shutdown()
   })
 
-  test("removes stale task from toast manager", () => {
+  test("removes stale task from toast manager", async () => {
     //#given
     const { removeTaskCalls, resetToastManager } = createToastRemoveTaskTracker()
     const manager = createBackgroundManager()
@@ -3504,6 +3704,7 @@ describe("BackgroundManager.pruneStaleTasksAndNotifications - removes pruned tas
 
     //#when
     pruneStaleTasksAndNotificationsForTest(manager)
+    await flushBackgroundNotifications()
 
     //#then
     expect(removeTaskCalls).toContain(staleTask.id)
@@ -3511,6 +3712,53 @@ describe("BackgroundManager.pruneStaleTasksAndNotifications - removes pruned tas
     manager.shutdown()
     resetToastManager()
   })
+
+  test("keeps stale task until notification cleanup after notifying parent", async () => {
+    //#given
+    const notifications: string[] = []
+    const { removeTaskCalls, resetToastManager } = createToastRemoveTaskTracker()
+    const client = {
+      session: {
+        prompt: async () => ({}),
+        promptAsync: async (args: { path: { id: string }; body: Record<string, unknown> & { noReply?: boolean; parts?: unknown[] } }) => {
+          const firstPart = args.body.parts?.[0]
+          if (firstPart && typeof firstPart === "object" && "text" in firstPart && typeof firstPart.text === "string") {
+            notifications.push(firstPart.text)
+          }
+          return {}
+        },
+        abort: async () => ({}),
+        messages: async () => ({ data: [] }),
+      },
+    }
+    const manager = new BackgroundManager({ client, directory: tmpdir() } as unknown as PluginInput)
+    const staleTask = createMockTask({
+      id: "task-stale-notify-cleanup",
+      sessionID: "session-stale-notify-cleanup",
+      parentSessionID: "parent-stale-notify-cleanup",
+      status: "running",
+      startedAt: new Date(Date.now() - 31 * 60 * 1000),
+    })
+    getTaskMap(manager).set(staleTask.id, staleTask)
+    getPendingByParent(manager).set(staleTask.parentSessionID, new Set([staleTask.id]))
+
+    //#when
+    pruneStaleTasksAndNotificationsForTest(manager)
+    await flushBackgroundNotifications()
+
+    //#then
+    const retainedTask = getTaskMap(manager).get(staleTask.id)
+    expect(retainedTask?.status).toBe("error")
+    expect(getTaskMap(manager).has(staleTask.id)).toBe(true)
+    expect(notifications).toHaveLength(1)
+    expect(notifications[0]).toContain("[ALL BACKGROUND TASKS COMPLETE]")
+    expect(notifications[0]).toContain(staleTask.description)
+    expect(getCompletionTimers(manager).has(staleTask.id)).toBe(true)
+    expect(removeTaskCalls).toContain(staleTask.id)
+
+    manager.shutdown()
+    resetToastManager()
+  })
 })
 
 describe("BackgroundManager.completionTimers - Memory Leak Fix", () => {
@@ -3614,7 +3862,7 @@ describe("BackgroundManager.completionTimers - Memory Leak Fix", () => {
     expect(completionTimers.size).toBe(0)
   })
 
-  test("should cancel timer when task is deleted via session.deleted", () => {
+  test("should preserve cleanup timer when terminal task session is deleted", () => {
     // given
     const manager = createBackgroundManager()
     const task: BackgroundTask = {
@@ -3643,7 +3891,7 @@ describe("BackgroundManager.completionTimers - Memory Leak Fix", () => {
     })
 
     // then
-    expect(completionTimers.has(task.id)).toBe(false)
+    expect(completionTimers.has(task.id)).toBe(true)
 
     manager.shutdown()
   })

src/features/background-agent/manager.ts

@@ -41,13 +41,24 @@ import {
 } from "./error-classifier"
 import { tryFallbackRetry } from "./fallback-retry-handler"
 import { registerManagerForCleanup, unregisterManagerForCleanup } from "./process-cleanup"
-import { isCompactionAgent, findNearestMessageExcludingCompaction } from "./compaction-aware-message-resolver"
+import {
+  findNearestMessageExcludingCompaction,
+  resolvePromptContextFromSessionMessages,
+} from "./compaction-aware-message-resolver"
 import { handleSessionIdleBackgroundEvent } from "./session-idle-event-handler"
 import { MESSAGE_STORAGE } from "../hook-message-injector"
 import { join } from "node:path"
 import { pruneStaleTasksAndNotifications } from "./task-poller"
 import { checkAndInterruptStaleTasks } from "./task-poller"
 import { removeTaskToastTracking } from "./remove-task-toast-tracking"
+import {
+  createSubagentDepthLimitError,
+  createSubagentDescendantLimitError,
+  getMaxRootSessionSpawnBudget,
+  getMaxSubagentDepth,
+  resolveSubagentSpawnContext,
+  type SubagentSpawnContext,
+} from "./subagent-spawn-limits"
 
 type OpencodeClient = PluginInput["client"]
 
@@ -112,6 +123,7 @@ export class BackgroundManager {
   private completionTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
   private idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
   private notificationQueueByParent: Map<string, Promise<void>> = new Map()
+  private rootDescendantCounts: Map<string, number>
   private enableParentSessionNotifications: boolean
   readonly taskHistory = new TaskHistory()
 
@@ -136,10 +148,77 @@ export class BackgroundManager {
     this.tmuxEnabled = options?.tmuxConfig?.enabled ?? false
     this.onSubagentSessionCreated = options?.onSubagentSessionCreated
     this.onShutdown = options?.onShutdown
+    this.rootDescendantCounts = new Map()
     this.enableParentSessionNotifications = options?.enableParentSessionNotifications ?? true
     this.registerProcessCleanup()
   }
 
+  async assertCanSpawn(parentSessionID: string): Promise<SubagentSpawnContext> {
+    const spawnContext = await resolveSubagentSpawnContext(this.client, parentSessionID)
+    const maxDepth = getMaxSubagentDepth(this.config)
+    if (spawnContext.childDepth > maxDepth) {
+      throw createSubagentDepthLimitError({
+        childDepth: spawnContext.childDepth,
+        maxDepth,
+        parentSessionID,
+        rootSessionID: spawnContext.rootSessionID,
+      })
+    }
+
+    const maxRootSessionSpawnBudget = getMaxRootSessionSpawnBudget(this.config)
+    const descendantCount = this.rootDescendantCounts.get(spawnContext.rootSessionID) ?? 0
+    if (descendantCount >= maxRootSessionSpawnBudget) {
+      throw createSubagentDescendantLimitError({
+        rootSessionID: spawnContext.rootSessionID,
+        descendantCount,
+        maxDescendants: maxRootSessionSpawnBudget,
+      })
+    }
+
+    return spawnContext
+  }
+
+  async reserveSubagentSpawn(parentSessionID: string): Promise<{
+    spawnContext: SubagentSpawnContext
+    descendantCount: number
+    commit: () => number
+    rollback: () => void
+  }> {
+    const spawnContext = await this.assertCanSpawn(parentSessionID)
+    const descendantCount = this.registerRootDescendant(spawnContext.rootSessionID)
+    let settled = false
+
+    return {
+      spawnContext,
+      descendantCount,
+      commit: () => {
+        settled = true
+        return descendantCount
+      },
+      rollback: () => {
+        if (settled) return
+        settled = true
+        this.unregisterRootDescendant(spawnContext.rootSessionID)
+      },
+    }
+  }
+
+  private registerRootDescendant(rootSessionID: string): number {
+    const nextCount = (this.rootDescendantCounts.get(rootSessionID) ?? 0) + 1
+    this.rootDescendantCounts.set(rootSessionID, nextCount)
+    return nextCount
+  }
+
+  private unregisterRootDescendant(rootSessionID: string): void {
+    const currentCount = this.rootDescendantCounts.get(rootSessionID) ?? 0
+    if (currentCount <= 1) {
+      this.rootDescendantCounts.delete(rootSessionID)
+      return
+    }
+
+    this.rootDescendantCounts.set(rootSessionID, currentCount - 1)
+  }
+
   async launch(input: LaunchInput): Promise<BackgroundTask> {
     log("[background-agent] launch() called with:", {
       agent: input.agent,
@@ -152,61 +231,79 @@ export class BackgroundManager {
       throw new Error("Agent parameter is required")
     }
 
-    // Create task immediately with status="pending"
-    const task: BackgroundTask = {
-      id: `bg_${crypto.randomUUID().slice(0, 8)}`,
-      status: "pending",
-      queuedAt: new Date(),
-      // Do NOT set startedAt - will be set when running
-      // Do NOT set sessionID - will be set when running
-      description: input.description,
-      prompt: input.prompt,
-      agent: input.agent,
-      parentSessionID: input.parentSessionID,
-      parentMessageID: input.parentMessageID,
-      parentModel: input.parentModel,
-      parentAgent: input.parentAgent,
-      parentTools: input.parentTools,
-      model: input.model,
-      fallbackChain: input.fallbackChain,
-      attemptCount: 0,
-      category: input.category,
-    }
+    const spawnReservation = await this.reserveSubagentSpawn(input.parentSessionID)
 
-    this.tasks.set(task.id, task)
-    this.taskHistory.record(input.parentSessionID, { id: task.id, agent: input.agent, description: input.description, status: "pending", category: input.category })
-
-    // Track for batched notifications immediately (pending state)
-    if (input.parentSessionID) {
-      const pending = this.pendingByParent.get(input.parentSessionID) ?? new Set()
-      pending.add(task.id)
-      this.pendingByParent.set(input.parentSessionID, pending)
-    }
-
-    // Add to queue
-    const key = this.getConcurrencyKeyFromInput(input)
-    const queue = this.queuesByKey.get(key) ?? []
-    queue.push({ task, input })
-    this.queuesByKey.set(key, queue)
-
-    log("[background-agent] Task queued:", { taskId: task.id, key, queueLength: queue.length })
-
-    const toastManager = getTaskToastManager()
-    if (toastManager) {
-      toastManager.addTask({
-        id: task.id,
-        description: input.description,
-        agent: input.agent,
-        isBackground: true,
-        status: "queued",
-        skills: input.skills,
+    try {
+      log("[background-agent] spawn guard passed", {
+        parentSessionID: input.parentSessionID,
+        rootSessionID: spawnReservation.spawnContext.rootSessionID,
+        childDepth: spawnReservation.spawnContext.childDepth,
+        descendantCount: spawnReservation.descendantCount,
       })
+
+      // Create task immediately with status="pending"
+      const task: BackgroundTask = {
+        id: `bg_${crypto.randomUUID().slice(0, 8)}`,
+        status: "pending",
+        queuedAt: new Date(),
+        rootSessionID: spawnReservation.spawnContext.rootSessionID,
+        // Do NOT set startedAt - will be set when running
+        // Do NOT set sessionID - will be set when running
+        description: input.description,
+        prompt: input.prompt,
+        agent: input.agent,
+        spawnDepth: spawnReservation.spawnContext.childDepth,
+        parentSessionID: input.parentSessionID,
+        parentMessageID: input.parentMessageID,
+        parentModel: input.parentModel,
+        parentAgent: input.parentAgent,
+        parentTools: input.parentTools,
+        model: input.model,
+        fallbackChain: input.fallbackChain,
+        attemptCount: 0,
+        category: input.category,
+      }
+
+      this.tasks.set(task.id, task)
+      this.taskHistory.record(input.parentSessionID, { id: task.id, agent: input.agent, description: input.description, status: "pending", category: input.category })
+
+      // Track for batched notifications immediately (pending state)
+      if (input.parentSessionID) {
+        const pending = this.pendingByParent.get(input.parentSessionID) ?? new Set()
+        pending.add(task.id)
+        this.pendingByParent.set(input.parentSessionID, pending)
+      }
+
+      // Add to queue
+      const key = this.getConcurrencyKeyFromInput(input)
+      const queue = this.queuesByKey.get(key) ?? []
+      queue.push({ task, input })
+      this.queuesByKey.set(key, queue)
+
+      log("[background-agent] Task queued:", { taskId: task.id, key, queueLength: queue.length })
+
+      const toastManager = getTaskToastManager()
+      if (toastManager) {
+        toastManager.addTask({
+          id: task.id,
+          description: input.description,
+          agent: input.agent,
+          isBackground: true,
+          status: "queued",
+          skills: input.skills,
+        })
+      }
+
+      spawnReservation.commit()
+
+      // Trigger processing (fire-and-forget)
+      this.processKey(key)
+
+      return { ...task }
+    } catch (error) {
+      spawnReservation.rollback()
+      throw error
     }
-
-    // Trigger processing (fire-and-forget)
-    this.processKey(key)
-
-    return task
   }
 
   private async processKey(key: string): Promise<void> {
@@ -272,6 +369,7 @@ export class BackgroundManager {
       body: {
         parentID: input.parentSessionID,
         title: `${input.description} (@${input.agent} subagent)`,
+        ...(input.sessionPermission ? { permission: input.sessionPermission } : {}),
       } as Record<string, unknown>,
       query: {
         directory: parentDirectory,
@@ -394,7 +492,6 @@ export class BackgroundManager {
         }).catch(() => {})
 
         this.markForNotification(existingTask)
-        this.cleanupPendingByParent(existingTask)
         this.enqueueNotificationForParent(existingTask.parentSessionID, () => this.notifyParentSession(existingTask)).catch(err => {
           log("[background-agent] Failed to notify on error:", err)
         })
@@ -667,7 +764,6 @@ export class BackgroundManager {
       }
 
       this.markForNotification(existingTask)
-      this.cleanupPendingByParent(existingTask)
       this.enqueueNotificationForParent(existingTask.parentSessionID, () => this.notifyParentSession(existingTask)).catch(err => {
         log("[background-agent] Failed to notify on resume error:", err)
       })
@@ -810,16 +906,14 @@ export class BackgroundManager {
         this.idleDeferralTimers.delete(task.id)
       }
 
-      this.cleanupPendingByParent(task)
-      this.tasks.delete(task.id)
-      this.clearNotificationsForTask(task.id)
-      const toastManager = getTaskToastManager()
-      if (toastManager) {
-        toastManager.removeTask(task.id)
-      }
       if (task.sessionID) {
-        subagentSessions.delete(task.sessionID)
+        SessionCategoryRegistry.remove(task.sessionID)
       }
+
+      this.markForNotification(task)
+      this.enqueueNotificationForParent(task.parentSessionID, () => this.notifyParentSession(task)).catch(err => {
+        log("[background-agent] Error in notifyParentSession for errored task:", { taskId: task.id, error: err })
+      })
     }
 
     if (event.type === "session.deleted") {
@@ -840,47 +934,32 @@ export class BackgroundManager {
 
       if (tasksToCancel.size === 0) return
 
+      const deletedSessionIDs = new Set<string>([sessionID])
+      for (const task of tasksToCancel.values()) {
+        if (task.sessionID) {
+          deletedSessionIDs.add(task.sessionID)
+        }
+      }
+
       for (const task of tasksToCancel.values()) {
         if (task.status === "running" || task.status === "pending") {
           void this.cancelTask(task.id, {
             source: "session.deleted",
             reason: "Session deleted",
-            skipNotification: true,
+          }).then(() => {
+            if (deletedSessionIDs.has(task.parentSessionID)) {
+              this.pendingNotifications.delete(task.parentSessionID)
+            }
           }).catch(err => {
+            if (deletedSessionIDs.has(task.parentSessionID)) {
+              this.pendingNotifications.delete(task.parentSessionID)
+            }
             log("[background-agent] Failed to cancel task on session.deleted:", { taskId: task.id, error: err })
           })
         }
-
-        const existingTimer = this.completionTimers.get(task.id)
-        if (existingTimer) {
-          clearTimeout(existingTimer)
-          this.completionTimers.delete(task.id)
-        }
-
-        const idleTimer = this.idleDeferralTimers.get(task.id)
-        if (idleTimer) {
-          clearTimeout(idleTimer)
-          this.idleDeferralTimers.delete(task.id)
-        }
-
-        this.cleanupPendingByParent(task)
-        this.tasks.delete(task.id)
-        this.clearNotificationsForTask(task.id)
-        const toastManager = getTaskToastManager()
-        if (toastManager) {
-          toastManager.removeTask(task.id)
-        }
-        if (task.sessionID) {
-          subagentSessions.delete(task.sessionID)
-        }
-      }
-
-      for (const task of tasksToCancel.values()) {
-        if (task.parentSessionID) {
-          this.pendingNotifications.delete(task.parentSessionID)
-        }
       }
 
+      this.rootDescendantCounts.delete(sessionID)
       SessionCategoryRegistry.remove(sessionID)
     }
 
@@ -1100,8 +1179,6 @@ export class BackgroundManager {
       this.idleDeferralTimers.delete(task.id)
     }
 
-    this.cleanupPendingByParent(task)
-
     if (abortSession && task.sessionID) {
       this.client.session.abort({
         path: { id: task.sessionID },
@@ -1208,9 +1285,6 @@ export class BackgroundManager {
 
     this.markForNotification(task)
 
-    // Ensure pending tracking is cleaned up even if notification fails
-    this.cleanupPendingByParent(task)
-
     const idleTimer = this.idleDeferralTimers.get(task.id)
     if (idleTimer) {
       clearTimeout(idleTimer)
@@ -1266,7 +1340,10 @@ export class BackgroundManager {
         this.pendingByParent.delete(task.parentSessionID)
       }
     } else {
-      allComplete = true
+      remainingCount = Array.from(this.tasks.values())
+        .filter(t => t.parentSessionID === task.parentSessionID && t.id !== task.id && (t.status === "running" || t.status === "pending"))
+        .length
+      allComplete = remainingCount === 0
     }
 
     const completedTasks = allComplete
@@ -1274,7 +1351,13 @@ export class BackgroundManager {
         .filter(t => t.parentSessionID === task.parentSessionID && t.status !== "running" && t.status !== "pending")
       : []
 
-    const statusText = task.status === "completed" ? "COMPLETED" : task.status === "interrupt" ? "INTERRUPTED" : "CANCELLED"
+    const statusText = task.status === "completed"
+      ? "COMPLETED"
+      : task.status === "interrupt"
+        ? "INTERRUPTED"
+        : task.status === "error"
+          ? "ERROR"
+          : "CANCELLED"
     const errorInfo = task.error ? `\n**Error:** ${task.error}` : ""
 
     let notification: string
@@ -1322,20 +1405,20 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
               tools?: Record<string, boolean | "allow" | "deny" | "ask">
             }
           }>)
-          for (let i = messages.length - 1; i >= 0; i--) {
-            const info = messages[i].info
-            if (isCompactionAgent(info?.agent)) {
-              continue
-            }
-            const normalizedTools = isRecord(info?.tools)
-              ? normalizePromptTools(info.tools as Record<string, boolean | "allow" | "deny" | "ask">)
+          const promptContext = resolvePromptContextFromSessionMessages(
+            messages,
+            task.parentSessionID,
+          )
+          const normalizedTools = isRecord(promptContext?.tools)
+            ? normalizePromptTools(promptContext.tools)
+            : undefined
+
+          if (promptContext?.agent || promptContext?.model || normalizedTools) {
+            agent = promptContext?.agent ?? task.parentAgent
+            model = promptContext?.model?.providerID && promptContext.model.modelID
+              ? { providerID: promptContext.model.providerID, modelID: promptContext.model.modelID }
               : undefined
-            if (info?.agent || info?.model || (info?.modelID && info?.providerID) || normalizedTools) {
-              agent = info?.agent ?? task.parentAgent
-              model = info?.model ?? (info?.providerID && info?.modelID ? { providerID: info.providerID, modelID: info.modelID } : undefined)
-              tools = normalizedTools ?? tools
-              break
-            }
+            tools = normalizedTools ?? tools
           }
         } catch (error) {
           if (isAbortedSessionError(error)) {
@@ -1345,7 +1428,9 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
             })
           }
           const messageDir = join(MESSAGE_STORAGE, task.parentSessionID)
-          const currentMessage = messageDir ? findNearestMessageExcludingCompaction(messageDir) : null
+          const currentMessage = messageDir
+            ? findNearestMessageExcludingCompaction(messageDir, task.parentSessionID)
+            : null
           agent = currentMessage?.agent ?? task.parentAgent
           model = currentMessage?.model?.providerID && currentMessage?.model?.modelID
             ? { providerID: currentMessage.model.providerID, modelID: currentMessage.model.modelID }
@@ -1405,8 +1490,13 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
         }
         const timer = setTimeout(() => {
           this.completionTimers.delete(taskId)
-          if (this.tasks.has(taskId)) {
+          const taskToRemove = this.tasks.get(taskId)
+          if (taskToRemove) {
             this.clearNotificationsForTask(taskId)
+            if (taskToRemove.sessionID) {
+              subagentSessions.delete(taskToRemove.sessionID)
+              SessionCategoryRegistry.remove(taskToRemove.sessionID)
+            }
             this.tasks.delete(taskId)
             log("[background-agent] Removed completed task from memory:", taskId)
           }
@@ -1416,14 +1506,6 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
     }
   }
 
-  private formatDuration(start: Date, end?: Date): string {
-    return formatDuration(start, end)
-  }
-
-  private isAbortedSessionError(error: unknown): boolean {
-    return isAbortedSessionError(error)
-  }
-
   private hasRunningTasks(): boolean {
     for (const task of this.tasks.values()) {
       if (task.status === "running") return true
@@ -1441,12 +1523,22 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
         task.status = "error"
         task.error = errorMessage
         task.completedAt = new Date()
+        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)
           task.concurrencyKey = undefined
         }
         removeTaskToastTracking(task.id)
-        this.cleanupPendingByParent(task)
+        const existingTimer = this.completionTimers.get(taskId)
+        if (existingTimer) {
+          clearTimeout(existingTimer)
+          this.completionTimers.delete(taskId)
+        }
+        const idleTimer = this.idleDeferralTimers.get(taskId)
+        if (idleTimer) {
+          clearTimeout(idleTimer)
+          this.idleDeferralTimers.delete(taskId)
+        }
         if (wasPending) {
           const key = task.model
             ? `${task.model.providerID}/${task.model.modelID}`
@@ -1462,16 +1554,10 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
             }
           }
         }
-        this.clearNotificationsForTask(taskId)
-        const toastManager = getTaskToastManager()
-        if (toastManager) {
-          toastManager.removeTask(taskId)
-        }
-        this.tasks.delete(taskId)
-        if (task.sessionID) {
-          subagentSessions.delete(task.sessionID)
-          SessionCategoryRegistry.remove(task.sessionID)
-        }
+        this.markForNotification(task)
+        this.enqueueNotificationForParent(task.parentSessionID, () => this.notifyParentSession(task)).catch(err => {
+          log("[background-agent] Error in notifyParentSession for stale-pruned task:", { taskId: task.id, error: err })
+        })
       },
     })
   }
@@ -1619,6 +1705,7 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
     this.pendingNotifications.clear()
     this.pendingByParent.clear()
     this.notificationQueueByParent.clear()
+    this.rootDescendantCounts.clear()
     this.queuesByKey.clear()
     this.processingKeys.clear()
     this.unregisterProcessCleanup()

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

@@ -3,7 +3,7 @@ import { describe, test, expect } from "bun:test"
 import { createTask, startTask } from "./spawner"
 
 describe("background-agent spawner.startTask", () => {
-  test("does not override parent session permission rules when creating child session", async () => {
+  test("applies explicit child session permission rules when creating child session", async () => {
     //#given
     const createCalls: any[] = []
     const parentPermission = [
@@ -41,6 +41,9 @@ describe("background-agent spawner.startTask", () => {
         parentModel: task.parentModel,
         parentAgent: task.parentAgent,
         model: task.model,
+        sessionPermission: [
+          { permission: "question", action: "deny", pattern: "*" },
+        ],
       },
     }
 
@@ -57,6 +60,8 @@ describe("background-agent spawner.startTask", () => {
 
     //#then
     expect(createCalls).toHaveLength(1)
-    expect(createCalls[0]?.body?.permission).toBeUndefined()
+    expect(createCalls[0]?.body?.permission).toEqual([
+      { permission: "question", action: "deny", pattern: "*" },
+    ])
   })
 })

src/features/background-agent/spawner.ts

@@ -61,6 +61,7 @@ export async function startTask(
   const createResult = await client.session.create({
     body: {
       parentID: input.parentSessionID,
+      ...(input.sessionPermission ? { permission: input.sessionPermission } : {}),
     } as Record<string, unknown>,
     query: {
       directory: parentDirectory,

src/features/background-agent/subagent-spawn-limits.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test"
+import type { OpencodeClient } from "./constants"
+import { resolveSubagentSpawnContext } from "./subagent-spawn-limits"
+
+function createMockClient(sessionGet: OpencodeClient["session"]["get"]): OpencodeClient {
+  return {
+    session: {
+      get: sessionGet,
+    },
+  } as OpencodeClient
+}
+
+describe("resolveSubagentSpawnContext", () => {
+  describe("#given session.get returns an SDK error response", () => {
+    test("throws a fail-closed spawn blocked error", async () => {
+      // given
+      const client = createMockClient(async () => ({
+        error: "lookup failed",
+        data: undefined,
+      }))
+
+      // when
+      const result = resolveSubagentSpawnContext(client, "parent-session")
+
+      // then
+      await expect(result).rejects.toThrow(/background_task\.maxDescendants cannot be enforced safely.*lookup failed/)
+    })
+  })
+
+  describe("#given session.get returns no session data", () => {
+    test("throws a fail-closed spawn blocked error", async () => {
+      // given
+      const client = createMockClient(async () => ({
+        data: undefined,
+      }))
+
+      // when
+      const result = resolveSubagentSpawnContext(client, "parent-session")
+
+      // then
+      await expect(result).rejects.toThrow(/background_task\.maxDescendants cannot be enforced safely.*No session data returned/)
+    })
+  })
+})

src/features/background-agent/subagent-spawn-limits.ts

@@ -0,0 +1,95 @@
+import type { BackgroundTaskConfig } from "../../config/schema"
+import type { OpencodeClient } from "./constants"
+
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 3
+export const DEFAULT_MAX_ROOT_SESSION_SPAWN_BUDGET = 50
+
+export interface SubagentSpawnContext {
+  rootSessionID: string
+  parentDepth: number
+  childDepth: number
+}
+
+export function getMaxSubagentDepth(config?: BackgroundTaskConfig): number {
+  return config?.maxDepth ?? DEFAULT_MAX_SUBAGENT_DEPTH
+}
+
+export function getMaxRootSessionSpawnBudget(config?: BackgroundTaskConfig): number {
+  return config?.maxDescendants ?? DEFAULT_MAX_ROOT_SESSION_SPAWN_BUDGET
+}
+
+export async function resolveSubagentSpawnContext(
+  client: OpencodeClient,
+  parentSessionID: string
+): Promise<SubagentSpawnContext> {
+  const visitedSessionIDs = new Set<string>()
+  let rootSessionID = parentSessionID
+  let currentSessionID = parentSessionID
+  let parentDepth = 0
+
+  while (true) {
+    if (visitedSessionIDs.has(currentSessionID)) {
+      throw new Error(`Detected a session parent cycle while resolving ${parentSessionID}`)
+    }
+
+    visitedSessionIDs.add(currentSessionID)
+
+    let nextParentSessionID: string | undefined
+    try {
+      const response = await client.session.get({
+        path: { id: currentSessionID },
+      })
+      if (response.error) {
+        throw new Error(String(response.error))
+      }
+
+      if (!response.data) {
+        throw new Error("No session data returned")
+      }
+
+      nextParentSessionID = response.data.parentID
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      throw new Error(
+        `Subagent spawn blocked: failed to resolve session lineage for ${parentSessionID}, so background_task.maxDescendants cannot be enforced safely. ${reason}`
+      )
+    }
+
+    if (!nextParentSessionID) {
+      rootSessionID = currentSessionID
+      break
+    }
+
+    currentSessionID = nextParentSessionID
+    parentDepth += 1
+  }
+
+  return {
+    rootSessionID,
+    parentDepth,
+    childDepth: parentDepth + 1,
+  }
+}
+
+export function createSubagentDepthLimitError(input: {
+  childDepth: number
+  maxDepth: number
+  parentSessionID: string
+  rootSessionID: string
+}): Error {
+  const { childDepth, maxDepth, parentSessionID, rootSessionID } = input
+  return new Error(
+    `Subagent spawn blocked: child depth ${childDepth} exceeds background_task.maxDepth=${maxDepth}. Parent session: ${parentSessionID}. Root session: ${rootSessionID}. Continue in an existing subagent session instead of spawning another.`
+  )
+}
+
+export function createSubagentDescendantLimitError(input: {
+  rootSessionID: string
+  descendantCount: number
+  maxDescendants: number
+}): Error {
+  const { rootSessionID, descendantCount, maxDescendants } = input
+  return new Error(
+    `Subagent spawn blocked: root session ${rootSessionID} already has ${descendantCount} descendants, which meets background_task.maxDescendants=${maxDescendants}. Reuse an existing session instead of spawning another.`
+  )
+}

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

@@ -1,4 +1,5 @@
-import { describe, it, expect, mock } from "bun:test"
+declare const require: (name: string) => any
+const { describe, it, expect, mock } = require("bun:test")
 
 import { checkAndInterruptStaleTasks, pruneStaleTasksAndNotifications } from "./task-poller"
 import type { BackgroundTask } from "./types"
@@ -116,13 +117,13 @@ describe("checkAndInterruptStaleTasks", () => {
   })
 
   it("should use DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS when messageStalenessTimeoutMs is not configured", async () => {
-    //#given — task started 15 minutes ago, no config for messageStalenessTimeoutMs
+    //#given — task started 35 minutes ago, no config for messageStalenessTimeoutMs
     const task = createRunningTask({
-      startedAt: new Date(Date.now() - 15 * 60 * 1000),
+      startedAt: new Date(Date.now() - 35 * 60 * 1000),
       progress: undefined,
     })
 
-    //#when — default is 10 minutes (600_000ms)
+    //#when — default is 30 minutes (1_800_000ms)
     await checkAndInterruptStaleTasks({
       tasks: [task],
       client: mockClient as never,
@@ -419,6 +420,21 @@ describe("checkAndInterruptStaleTasks", () => {
 })
 
 describe("pruneStaleTasksAndNotifications", () => {
+  function createTerminalTask(overrides: Partial<BackgroundTask> = {}): BackgroundTask {
+    return {
+      id: "terminal-task",
+      parentSessionID: "parent",
+      parentMessageID: "msg",
+      description: "terminal",
+      prompt: "terminal",
+      agent: "explore",
+      status: "completed",
+      startedAt: new Date(Date.now() - 40 * 60 * 1000),
+      completedAt: new Date(Date.now() - 31 * 60 * 1000),
+      ...overrides,
+    }
+  }
+
   it("should prune tasks that exceeded TTL", () => {
     //#given
     const tasks = new Map<string, BackgroundTask>()
@@ -447,4 +463,52 @@ describe("pruneStaleTasksAndNotifications", () => {
     //#then
     expect(pruned).toContain("old-task")
   })
+
+  it("should prune terminal tasks when completion time exceeds terminal TTL", () => {
+    //#given
+    const tasks = new Map<string, BackgroundTask>()
+    const terminalStatuses: BackgroundTask["status"][] = ["completed", "error", "cancelled", "interrupt"]
+
+    for (const status of terminalStatuses) {
+      tasks.set(status, createTerminalTask({
+        id: status,
+        description: status,
+        prompt: status,
+        status,
+      }))
+    }
+
+    const pruned: string[] = []
+
+    //#when
+    pruneStaleTasksAndNotifications({
+      tasks,
+      notifications: new Map<string, BackgroundTask[]>(),
+      onTaskPruned: (taskId) => pruned.push(taskId),
+    })
+
+    //#then
+    expect(pruned).toEqual([])
+    expect(Array.from(tasks.keys())).toEqual([])
+  })
+
+  it("should keep terminal tasks with pending notifications until notification cleanup", () => {
+    //#given
+    const task = createTerminalTask()
+    const tasks = new Map<string, BackgroundTask>([[task.id, task]])
+    const notifications = new Map<string, BackgroundTask[]>([[task.parentSessionID, [task]]])
+    const pruned: string[] = []
+
+    //#when
+    pruneStaleTasksAndNotifications({
+      tasks,
+      notifications,
+      onTaskPruned: (taskId) => pruned.push(taskId),
+    })
+
+    //#then
+    expect(pruned).toEqual([])
+    expect(tasks.has(task.id)).toBe(true)
+    expect(notifications.has(task.parentSessionID)).toBe(false)
+  })
 })

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

@@ -13,6 +13,15 @@ import {
 } from "./constants"
 import { removeTaskToastTracking } from "./remove-task-toast-tracking"
 
+const TERMINAL_TASK_TTL_MS = 30 * 60 * 1000
+
+const TERMINAL_TASK_STATUSES = new Set<BackgroundTask["status"]>([
+  "completed",
+  "error",
+  "cancelled",
+  "interrupt",
+])
+
 export function pruneStaleTasksAndNotifications(args: {
   tasks: Map<string, BackgroundTask>
   notifications: Map<string, BackgroundTask[]>
@@ -20,8 +29,29 @@ export function pruneStaleTasksAndNotifications(args: {
 }): void {
   const { tasks, notifications, onTaskPruned } = args
   const now = Date.now()
+  const tasksWithPendingNotifications = new Set<string>()
+
+  for (const queued of notifications.values()) {
+    for (const task of queued) {
+      tasksWithPendingNotifications.add(task.id)
+    }
+  }
 
   for (const [taskId, task] of tasks.entries()) {
+    if (TERMINAL_TASK_STATUSES.has(task.status)) {
+      if (tasksWithPendingNotifications.has(taskId)) continue
+
+      const completedAt = task.completedAt?.getTime()
+      if (!completedAt) continue
+
+      const age = now - completedAt
+      if (age <= TERMINAL_TASK_TTL_MS) continue
+
+      removeTaskToastTracking(taskId)
+      tasks.delete(taskId)
+      continue
+    }
+
     const timestamp = task.status === "pending"
       ? task.queuedAt?.getTime()
       : task.startedAt?.getTime()

src/features/background-agent/types.ts

@@ -1,4 +1,5 @@
 import type { FallbackEntry } from "../../shared/model-requirements"
+import type { SessionPermissionRule } from "../../shared/question-denied-session-permission"
 
 export type BackgroundTaskStatus =
   | "pending"
@@ -19,11 +20,13 @@ export interface TaskProgress {
 export interface BackgroundTask {
   id: string
   sessionID?: string
+  rootSessionID?: string
   parentSessionID: string
   parentMessageID: string
   description: string
   prompt: string
   agent: string
+  spawnDepth?: number
   status: BackgroundTaskStatus
   queuedAt?: Date
   startedAt?: Date
@@ -72,6 +75,7 @@ export interface LaunchInput {
   skills?: string[]
   skillContent?: string
   category?: string
+  sessionPermission?: SessionPermissionRule[]
 }
 
 export interface ResumeInput {

src/features/claude-code-agent-loader/claude-model-mapper.test.ts

@@ -0,0 +1,108 @@
+/// <reference types="bun-types" />
+
+import { describe, it, expect } from "bun:test"
+import { mapClaudeModelToOpenCode } from "./claude-model-mapper"
+
+describe("mapClaudeModelToOpenCode", () => {
+  describe("#given undefined or empty input", () => {
+    it("#when called with undefined #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode(undefined)).toBeUndefined()
+    })
+
+    it("#when called with empty string #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode("")).toBeUndefined()
+    })
+
+    it("#when called with whitespace-only string #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode("   ")).toBeUndefined()
+    })
+  })
+
+  describe("#given Claude Code alias", () => {
+    it("#when called with sonnet #then maps to anthropic claude-sonnet-4-6 object", () => {
+      expect(mapClaudeModelToOpenCode("sonnet")).toEqual({ providerID: "anthropic", modelID: "claude-sonnet-4-6" })
+    })
+
+    it("#when called with opus #then maps to anthropic claude-opus-4-6 object", () => {
+      expect(mapClaudeModelToOpenCode("opus")).toEqual({ providerID: "anthropic", modelID: "claude-opus-4-6" })
+    })
+
+    it("#when called with haiku #then maps to anthropic claude-haiku-4-5 object", () => {
+      expect(mapClaudeModelToOpenCode("haiku")).toEqual({ providerID: "anthropic", modelID: "claude-haiku-4-5" })
+    })
+
+    it("#when called with Sonnet (capitalized) #then maps case-insensitively to object", () => {
+      expect(mapClaudeModelToOpenCode("Sonnet")).toEqual({ providerID: "anthropic", modelID: "claude-sonnet-4-6" })
+    })
+  })
+
+  describe("#given inherit", () => {
+    it("#when called with inherit #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode("inherit")).toBeUndefined()
+    })
+  })
+
+  describe("#given bare Claude model name", () => {
+    it("#when called with claude-sonnet-4-5-20250514 #then adds anthropic object format", () => {
+      expect(mapClaudeModelToOpenCode("claude-sonnet-4-5-20250514")).toEqual({ providerID: "anthropic", modelID: "claude-sonnet-4-5-20250514" })
+    })
+
+    it("#when called with claude-opus-4-6 #then adds anthropic object format", () => {
+      expect(mapClaudeModelToOpenCode("claude-opus-4-6")).toEqual({ providerID: "anthropic", modelID: "claude-opus-4-6" })
+    })
+
+    it("#when called with claude-haiku-4-5-20251001 #then adds anthropic object format", () => {
+      expect(mapClaudeModelToOpenCode("claude-haiku-4-5-20251001")).toEqual({ providerID: "anthropic", modelID: "claude-haiku-4-5-20251001" })
+    })
+
+    it("#when called with claude-3-5-sonnet-20241022 #then adds anthropic object format", () => {
+      expect(mapClaudeModelToOpenCode("claude-3-5-sonnet-20241022")).toEqual({ providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" })
+    })
+  })
+
+  describe("#given model with dot version numbers", () => {
+    it("#when called with claude-3.5-sonnet #then normalizes dots and returns object format", () => {
+      expect(mapClaudeModelToOpenCode("claude-3.5-sonnet")).toEqual({ providerID: "anthropic", modelID: "claude-3-5-sonnet" })
+    })
+
+    it("#when called with claude-3.5-sonnet-20241022 #then normalizes dots and returns object format", () => {
+      expect(mapClaudeModelToOpenCode("claude-3.5-sonnet-20241022")).toEqual({ providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" })
+    })
+  })
+
+  describe("#given model already in provider/model format", () => {
+    it("#when called with anthropic/claude-sonnet-4-6 #then splits into object format", () => {
+      expect(mapClaudeModelToOpenCode("anthropic/claude-sonnet-4-6")).toEqual({ providerID: "anthropic", modelID: "claude-sonnet-4-6" })
+    })
+
+    it("#when called with openai/gpt-5.2 #then splits into object format", () => {
+      expect(mapClaudeModelToOpenCode("openai/gpt-5.2")).toEqual({ providerID: "openai", modelID: "gpt-5.2" })
+    })
+  })
+
+  describe("#given non-Claude bare model", () => {
+    it("#when called with gpt-5.2 #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode("gpt-5.2")).toBeUndefined()
+    })
+
+    it("#when called with gemini-3-flash #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode("gemini-3-flash")).toBeUndefined()
+    })
+  })
+
+  describe("#given prototype property name", () => {
+    it("#when called with constructor #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode("constructor")).toBeUndefined()
+    })
+
+    it("#when called with toString #then returns undefined", () => {
+      expect(mapClaudeModelToOpenCode("toString")).toBeUndefined()
+    })
+  })
+
+  describe("#given model with leading/trailing whitespace", () => {
+    it("#when called with padded string #then trims before returning object format", () => {
+      expect(mapClaudeModelToOpenCode("  claude-sonnet-4-6  ")).toEqual({ providerID: "anthropic", modelID: "claude-sonnet-4-6" })
+    })
+  })
+})

src/features/claude-code-agent-loader/claude-model-mapper.ts

@@ -0,0 +1,39 @@
+import { normalizeModelFormat } from "../../shared/model-format-normalizer"
+import { normalizeModelID } from "../../shared/model-normalization"
+
+const ANTHROPIC_PREFIX = "anthropic/"
+
+const CLAUDE_CODE_ALIAS_MAP = new Map<string, string>([
+  ["sonnet", `${ANTHROPIC_PREFIX}claude-sonnet-4-6`],
+  ["opus", `${ANTHROPIC_PREFIX}claude-opus-4-6`],
+  ["haiku", `${ANTHROPIC_PREFIX}claude-haiku-4-5`],
+])
+
+function mapClaudeModelString(model: string | undefined): string | undefined {
+  if (!model) return undefined
+
+  const trimmed = model.trim()
+  if (trimmed.length === 0) return undefined
+
+  if (trimmed === "inherit") return undefined
+
+  const aliasResult = CLAUDE_CODE_ALIAS_MAP.get(trimmed.toLowerCase())
+  if (aliasResult) return aliasResult
+
+  if (trimmed.includes("/")) return trimmed
+
+  const normalized = normalizeModelID(trimmed)
+
+  if (normalized.startsWith("claude-")) {
+    return `${ANTHROPIC_PREFIX}${normalized}`
+  }
+
+  return undefined
+}
+
+export function mapClaudeModelToOpenCode(
+  model: string | undefined
+): { providerID: string; modelID: string } | undefined {
+  const mappedModel = mapClaudeModelString(model)
+  return mappedModel ? normalizeModelFormat(mappedModel) : undefined
+}

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

@@ -1,10 +1,10 @@
 import { existsSync, readdirSync, readFileSync } from "fs"
 import { join, basename } from "path"
-import type { AgentConfig } from "@opencode-ai/sdk"
 import { parseFrontmatter } from "../../shared/frontmatter"
 import { isMarkdownFile } from "../../shared/file-utils"
 import { getClaudeConfigDir } from "../../shared"
-import type { AgentScope, AgentFrontmatter, LoadedAgent } from "./types"
+import type { AgentScope, AgentFrontmatter, ClaudeCodeAgentConfig, LoadedAgent } from "./types"
+import { mapClaudeModelToOpenCode } from "./claude-model-mapper"
 
 function parseToolsConfig(toolsStr?: string): Record<string, boolean> | undefined {
   if (!toolsStr) return undefined
@@ -42,10 +42,13 @@ function loadAgentsFromDir(agentsDir: string, scope: AgentScope): LoadedAgent[]
 
        const formattedDescription = `(${scope}) ${originalDescription}`
 
-       const config: AgentConfig = {
+       const mappedModelOverride = mapClaudeModelToOpenCode(data.model)
+
+       const config: ClaudeCodeAgentConfig = {
          description: formattedDescription,
          mode: data.mode || "subagent",
          prompt: body.trim(),
+         ...(mappedModelOverride ? { model: mappedModelOverride } : {}),
        }
 
        const toolsConfig = parseToolsConfig(data.tools)
@@ -67,22 +70,22 @@ function loadAgentsFromDir(agentsDir: string, scope: AgentScope): LoadedAgent[]
   return agents
 }
 
-export function loadUserAgents(): Record<string, AgentConfig> {
+export function loadUserAgents(): Record<string, ClaudeCodeAgentConfig> {
   const userAgentsDir = join(getClaudeConfigDir(), "agents")
   const agents = loadAgentsFromDir(userAgentsDir, "user")
 
-  const result: Record<string, AgentConfig> = {}
+  const result: Record<string, ClaudeCodeAgentConfig> = {}
   for (const agent of agents) {
     result[agent.name] = agent.config
   }
   return result
 }
 
-export function loadProjectAgents(directory?: string): Record<string, AgentConfig> {
+export function loadProjectAgents(directory?: string): Record<string, ClaudeCodeAgentConfig> {
   const projectAgentsDir = join(directory ?? process.cwd(), ".claude", "agents")
   const agents = loadAgentsFromDir(projectAgentsDir, "project")
 
-  const result: Record<string, AgentConfig> = {}
+  const result: Record<string, ClaudeCodeAgentConfig> = {}
   for (const agent of agents) {
     result[agent.name] = agent.config
   }

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

@@ -2,6 +2,10 @@ import type { AgentConfig } from "@opencode-ai/sdk"
 
 export type AgentScope = "user" | "project"
 
+export type ClaudeCodeAgentConfig = Omit<AgentConfig, "model"> & {
+  model?: string | { providerID: string; modelID: string }
+}
+
 export interface AgentFrontmatter {
   name?: string
   description?: string
@@ -13,6 +17,6 @@ export interface AgentFrontmatter {
 export interface LoadedAgent {
   name: string
   path: string
-  config: AgentConfig
+  config: ClaudeCodeAgentConfig
   scope: AgentScope
 }

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

@@ -1,10 +1,10 @@
 import { existsSync, readdirSync, readFileSync } from "fs"
 import { basename, join } from "path"
-import type { AgentConfig } from "@opencode-ai/sdk"
 import { parseFrontmatter } from "../../shared/frontmatter"
 import { isMarkdownFile } from "../../shared/file-utils"
 import { log } from "../../shared/logger"
-import type { AgentFrontmatter } from "../claude-code-agent-loader/types"
+import type { AgentFrontmatter, ClaudeCodeAgentConfig } from "../claude-code-agent-loader/types"
+import { mapClaudeModelToOpenCode } from "../claude-code-agent-loader/claude-model-mapper"
 import type { LoadedPlugin } from "./types"
 
 function parseToolsConfig(toolsStr?: string): Record<string, boolean> | undefined {
@@ -24,8 +24,8 @@ function parseToolsConfig(toolsStr?: string): Record<string, boolean> | undefine
   return result
 }
 
-export function loadPluginAgents(plugins: LoadedPlugin[]): Record<string, AgentConfig> {
-  const agents: Record<string, AgentConfig> = {}
+export function loadPluginAgents(plugins: LoadedPlugin[]): Record<string, ClaudeCodeAgentConfig> {
+  const agents: Record<string, ClaudeCodeAgentConfig> = {}
 
   for (const plugin of plugins) {
     if (!plugin.agentsDir || !existsSync(plugin.agentsDir)) continue
@@ -46,10 +46,13 @@ export function loadPluginAgents(plugins: LoadedPlugin[]): Record<string, AgentC
         const originalDescription = data.description || ""
         const formattedDescription = `(plugin: ${plugin.name}) ${originalDescription}`
 
-        const config: AgentConfig = {
+        const mappedModelOverride = mapClaudeModelToOpenCode(data.model)
+
+        const config: ClaudeCodeAgentConfig = {
           description: formattedDescription,
           mode: "subagent",
           prompt: body.trim(),
+          ...(mappedModelOverride ? { model: mappedModelOverride } : {}),
         }
 
         const toolsConfig = parseToolsConfig(data.tools)

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

@@ -1,7 +1,7 @@
 import { log } from "../../shared/logger"
-import type { AgentConfig } from "@opencode-ai/sdk"
 import type { CommandDefinition } from "../claude-code-command-loader/types"
 import type { McpServerConfig } from "../claude-code-mcp-loader/types"
+import type { ClaudeCodeAgentConfig } from "../claude-code-agent-loader/types"
 import type { HooksConfig, LoadedPlugin, PluginLoadError, PluginLoaderOptions } from "./types"
 import { discoverInstalledPlugins } from "./discovery"
 import { loadPluginCommands } from "./command-loader"
@@ -20,7 +20,7 @@ export { loadPluginHooksConfigs } from "./hook-loader"
 export interface PluginComponentsResult {
   commands: Record<string, CommandDefinition>
   skills: Record<string, CommandDefinition>
-  agents: Record<string, AgentConfig>
+  agents: Record<string, ClaudeCodeAgentConfig>
   mcpServers: Record<string, McpServerConfig>
   hooksConfigs: HooksConfig[]
   plugins: LoadedPlugin[]

src/features/opencode-skill-loader/git-master-template-injection.test.ts

@@ -0,0 +1,155 @@
+/// <reference types="bun-types" />
+
+import { describe, it, expect } from "bun:test"
+import { injectGitMasterConfig } from "./git-master-template-injection"
+
+const SAMPLE_TEMPLATE = [
+	"# Git Master Agent",
+	"",
+	"## MODE DETECTION (FIRST STEP)",
+	"",
+	"Analyze the request.",
+	"",
+	"```bash",
+	"git status",
+	"git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null",
+	"MERGE_BASE=$(git merge-base HEAD main)",
+	"GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash $MERGE_BASE",
+	"```",
+	"",
+	"```",
+	"</execution>",
+].join("\n")
+
+describe("#given git_env_prefix config", () => {
+	describe("#when default config (GIT_MASTER=1)", () => {
+		it("#then injects env prefix section before MODE DETECTION", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE, {
+				commit_footer: false,
+				include_co_authored_by: false,
+				git_env_prefix: "GIT_MASTER=1",
+			})
+
+			expect(result).toContain("## GIT COMMAND PREFIX (MANDATORY)")
+			expect(result).toContain("GIT_MASTER=1 git status")
+			expect(result).toContain("GIT_MASTER=1 git commit")
+			expect(result).toContain("GIT_MASTER=1 git push")
+			expect(result).toContain("EVERY git command MUST be prefixed with `GIT_MASTER=1`")
+
+			const prefixIndex = result.indexOf("## GIT COMMAND PREFIX")
+			const modeIndex = result.indexOf("## MODE DETECTION")
+			expect(prefixIndex).toBeLessThan(modeIndex)
+		})
+	})
+
+	describe("#when git_env_prefix is empty string", () => {
+		it("#then does NOT inject env prefix section", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE, {
+				commit_footer: false,
+				include_co_authored_by: false,
+				git_env_prefix: "",
+			})
+
+			expect(result).not.toContain("## GIT COMMAND PREFIX")
+			expect(result).not.toContain("GIT_MASTER=1")
+			expect(result).not.toContain("git_env_prefix")
+		})
+	})
+
+	describe("#when git_env_prefix is custom value", () => {
+		it("#then injects custom prefix in section", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE, {
+				commit_footer: false,
+				include_co_authored_by: false,
+				git_env_prefix: "MY_HOOK=active",
+			})
+
+			expect(result).toContain("MY_HOOK=active git status")
+			expect(result).toContain("MY_HOOK=active git commit")
+			expect(result).not.toContain("GIT_MASTER=1")
+		})
+	})
+
+	describe("#when git_env_prefix contains shell metacharacters", () => {
+		it("#then rejects the malicious value", () => {
+			expect(() =>
+				injectGitMasterConfig(SAMPLE_TEMPLATE, {
+					commit_footer: false,
+					include_co_authored_by: false,
+					git_env_prefix: "A=1; rm -rf /",
+				})
+			).toThrow('git_env_prefix must be empty or use shell-safe env assignments like "GIT_MASTER=1"')
+		})
+	})
+
+	describe("#when no config provided", () => {
+		it("#then uses default GIT_MASTER=1 prefix", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE)
+
+			expect(result).toContain("GIT_MASTER=1 git status")
+			expect(result).toContain("## GIT COMMAND PREFIX (MANDATORY)")
+		})
+	})
+})
+
+describe("#given git_env_prefix with commit footer", () => {
+	describe("#when both env prefix and footer are enabled", () => {
+		it("#then commit examples include the env prefix", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE, {
+				commit_footer: true,
+				include_co_authored_by: false,
+				git_env_prefix: "GIT_MASTER=1",
+			})
+
+			expect(result).toContain("GIT_MASTER=1 git commit")
+			expect(result).toContain("Ultraworked with [Sisyphus]")
+		})
+	})
+
+	describe("#when the template already contains bare git commands in bash blocks", () => {
+		it("#then prefixes every git invocation in the final output", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE, {
+				commit_footer: false,
+				include_co_authored_by: false,
+				git_env_prefix: "GIT_MASTER=1",
+			})
+
+			expect(result).toContain("GIT_MASTER=1 git status")
+			expect(result).toContain(
+				"GIT_MASTER=1 git merge-base HEAD main 2>/dev/null || GIT_MASTER=1 git merge-base HEAD master 2>/dev/null"
+			)
+			expect(result).toContain("MERGE_BASE=$(GIT_MASTER=1 git merge-base HEAD main)")
+			expect(result).toContain(
+				"GIT_SEQUENCE_EDITOR=: GIT_MASTER=1 git rebase -i --autosquash $MERGE_BASE"
+			)
+		})
+	})
+
+	describe("#when env prefix disabled but footer enabled", () => {
+		it("#then commit examples have no env prefix", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE, {
+				commit_footer: true,
+				include_co_authored_by: false,
+				git_env_prefix: "",
+			})
+
+			expect(result).not.toContain("GIT_MASTER=1 git commit")
+			expect(result).toContain("git commit -m")
+			expect(result).toContain("Ultraworked with [Sisyphus]")
+		})
+	})
+
+	describe("#when both env prefix and co-author are enabled", () => {
+		it("#then commit example includes prefix, footer, and co-author", () => {
+			const result = injectGitMasterConfig(SAMPLE_TEMPLATE, {
+				commit_footer: true,
+				include_co_authored_by: true,
+				git_env_prefix: "GIT_MASTER=1",
+			})
+
+			expect(result).toContain("GIT_MASTER=1 git commit")
+			expect(result).toContain("Ultraworked with [Sisyphus]")
+			expect(result).toContain("Co-authored-by: Sisyphus")
+		})
+	})
+})

src/features/opencode-skill-loader/git-master-template-injection.ts

@@ -1,14 +1,88 @@
-import type { GitMasterConfig } from "../../config/schema"
+import { assertValidGitEnvPrefix, type GitMasterConfig } from "../../config/schema"
+
+const BASH_CODE_BLOCK_PATTERN = /```bash\r?\n([\s\S]*?)```/g
+const LEADING_GIT_COMMAND_PATTERN = /^([ \t]*(?:[A-Za-z_][A-Za-z0-9_]*=[^ \t]+\s+)*)git(?=[ \t]|$)/gm
+const INLINE_GIT_COMMAND_PATTERN = /([;&|()][ \t]*)git(?=[ \t]|$)/g
 
 export function injectGitMasterConfig(template: string, config?: GitMasterConfig): string {
 	const commitFooter = config?.commit_footer ?? true
 	const includeCoAuthoredBy = config?.include_co_authored_by ?? true
+	const gitEnvPrefix = assertValidGitEnvPrefix(config?.git_env_prefix ?? "GIT_MASTER=1")
 
-	if (!commitFooter && !includeCoAuthoredBy) {
-		return template
+	let result = gitEnvPrefix ? injectGitEnvPrefix(template, gitEnvPrefix) : template
+
+	if (commitFooter || includeCoAuthoredBy) {
+		const injection = buildCommitFooterInjection(commitFooter, includeCoAuthoredBy, gitEnvPrefix)
+		const insertionPoint = result.indexOf("```\n</execution>")
+
+		result =
+			insertionPoint !== -1
+				? result.slice(0, insertionPoint) +
+					"```\n\n" +
+					injection +
+					"\n</execution>" +
+					result.slice(insertionPoint + "```\n</execution>".length)
+				: result + "\n\n" + injection
 	}
 
+	return gitEnvPrefix ? prefixGitCommandsInBashCodeBlocks(result, gitEnvPrefix) : result
+}
+
+function injectGitEnvPrefix(template: string, prefix: string): string {
+	const envPrefixSection = [
+		"## GIT COMMAND PREFIX (MANDATORY)",
+		"",
+		`<git_env_prefix>`,
+		`**EVERY git command MUST be prefixed with \`${prefix}\`.**`,
+		"",
+		"This allows custom git hooks to detect when git-master skill is active.",
+		"",
+		"```bash",
+		`${prefix} git status`,
+		`${prefix} git add <files>`,
+		`${prefix} git commit -m "message"`,
+		`${prefix} git push`,
+		`${prefix} git rebase ...`,
+		`${prefix} git log ...`,
+		"```",
+		"",
+		"**NO EXCEPTIONS. Every `git` invocation must include this prefix.**",
+		`</git_env_prefix>`,
+	].join("\n")
+
+	const modeDetectionMarker = "## MODE DETECTION (FIRST STEP)"
+	const markerIndex = template.indexOf(modeDetectionMarker)
+	if (markerIndex !== -1) {
+		return (
+			template.slice(0, markerIndex) +
+			envPrefixSection +
+			"\n\n---\n\n" +
+			template.slice(markerIndex)
+		)
+	}
+
+	return envPrefixSection + "\n\n---\n\n" + template
+}
+
+function prefixGitCommandsInBashCodeBlocks(template: string, prefix: string): string {
+	return template.replace(BASH_CODE_BLOCK_PATTERN, (block, codeBlock: string) => {
+		return block.replace(codeBlock, prefixGitCommandsInCodeBlock(codeBlock, prefix))
+	})
+}
+
+function prefixGitCommandsInCodeBlock(codeBlock: string, prefix: string): string {
+	return codeBlock
+		.replace(LEADING_GIT_COMMAND_PATTERN, `$1${prefix} git`)
+		.replace(INLINE_GIT_COMMAND_PATTERN, `$1${prefix} git`)
+}
+
+function buildCommitFooterInjection(
+	commitFooter: boolean | string,
+	includeCoAuthoredBy: boolean,
+	gitEnvPrefix: string,
+): string {
 	const sections: string[] = []
+	const cmdPrefix = gitEnvPrefix ? `${gitEnvPrefix} ` : ""
 
 	sections.push("### 5.5 Commit Footer & Co-Author")
 	sections.push("")
@@ -43,7 +117,7 @@ export function injectGitMasterConfig(template: string, config?: GitMasterConfig
 		sections.push("**Example (both enabled):**")
 		sections.push("```bash")
 		sections.push(
-			`git commit -m "{Commit Message}" -m "${footerText}" -m "Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>"`
+			`${cmdPrefix}git commit -m "{Commit Message}" -m "${footerText}" -m "Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>"`
 		)
 		sections.push("```")
 	} else if (commitFooter) {
@@ -53,29 +127,16 @@ export function injectGitMasterConfig(template: string, config?: GitMasterConfig
 				: "Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)"
 		sections.push("**Example:**")
 		sections.push("```bash")
-		sections.push(`git commit -m "{Commit Message}" -m "${footerText}"`)
+		sections.push(`${cmdPrefix}git commit -m "{Commit Message}" -m "${footerText}"`)
 		sections.push("```")
 	} else if (includeCoAuthoredBy) {
 		sections.push("**Example:**")
 		sections.push("```bash")
 		sections.push(
-			"git commit -m \"{Commit Message}\" -m \"Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>\""
+			`${cmdPrefix}git commit -m "{Commit Message}" -m "Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>"`
 		)
 		sections.push("```")
 	}
 
-	const injection = sections.join("\n")
-
-	const insertionPoint = template.indexOf("```\n</execution>")
-	if (insertionPoint !== -1) {
-		return (
-			template.slice(0, insertionPoint) +
-			"```\n\n" +
-			injection +
-			"\n</execution>" +
-			template.slice(insertionPoint + "```\n</execution>".length)
-		)
-	}
-
-	return template + "\n\n" + injection
+	return sections.join("\n")
 }

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

@@ -228,6 +228,7 @@ describe("resolveMultipleSkillsAsync", () => {
 			gitMasterConfig: {
 				commit_footer: false,
 				include_co_authored_by: false,
+				git_env_prefix: "GIT_MASTER=1",
 			},
 		}
 
@@ -249,6 +250,7 @@ describe("resolveMultipleSkillsAsync", () => {
 			gitMasterConfig: {
 				commit_footer: true,
 				include_co_authored_by: true,
+				git_env_prefix: "GIT_MASTER=1",
 			},
 		}
 
@@ -269,6 +271,7 @@ describe("resolveMultipleSkillsAsync", () => {
 			gitMasterConfig: {
 				commit_footer: true,
 				include_co_authored_by: false,
+				git_env_prefix: "GIT_MASTER=1",
 			},
 		}
 
@@ -302,6 +305,7 @@ describe("resolveMultipleSkillsAsync", () => {
 			gitMasterConfig: {
 				commit_footer: false,
 				include_co_authored_by: true,
+				git_env_prefix: "GIT_MASTER=1",
 			},
 		}
 
@@ -322,6 +326,7 @@ describe("resolveMultipleSkillsAsync", () => {
 			gitMasterConfig: {
 				commit_footer: customFooter,
 				include_co_authored_by: false,
+				git_env_prefix: "GIT_MASTER=1",
 			},
 		}
 
@@ -341,6 +346,7 @@ describe("resolveMultipleSkillsAsync", () => {
 			gitMasterConfig: {
 				commit_footer: true,
 				include_co_authored_by: false,
+				git_env_prefix: "GIT_MASTER=1",
 			},
 		}
 

src/features/tmux-subagent/index.ts

@@ -10,6 +10,7 @@ export * from "./session-status-parser"
 export * from "./session-message-count"
 export * from "./session-ready-waiter"
 export * from "./types"
+export * from "./pane-state-parser"
 export * from "./pane-state-querier"
 export * from "./decision-engine"
 export * from "./action-executor"

src/features/tmux-subagent/pane-state-parser.test.ts

@@ -0,0 +1,72 @@
+/// <reference path="../../../bun-test.d.ts" />
+
+import { describe, expect, it } from "bun:test"
+import { parsePaneStateOutput } from "./pane-state-parser"
+
+describe("parsePaneStateOutput", () => {
+  it("rejects malformed integer fields", () => {
+    // given
+    const stdout = "%0\t120oops\t40\t0\t0\t1\t120\t40\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).toBe(null)
+  })
+
+  it("rejects negative integer fields", () => {
+    // given
+    const stdout = "%0\t-1\t40\t0\t0\t1\t120\t40\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).toBe(null)
+  })
+
+  it("rejects empty integer fields", () => {
+    // given
+    const stdout = "%0\t\t40\t0\t0\t1\t120\t40\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).toBe(null)
+  })
+
+  it("rejects non-binary active flags", () => {
+    // given
+    const stdout = "%0\t120\t40\t0\t0\tx\t120\t40\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).toBe(null)
+  })
+
+  it("rejects numeric active flags other than zero or one", () => {
+    // given
+    const stdout = "%0\t120\t40\t0\t0\t2\t120\t40\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).toBe(null)
+  })
+
+  it("rejects empty active flags", () => {
+    // given
+    const stdout = "%0\t120\t40\t0\t0\t\t120\t40\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).toBe(null)
+  })
+})

src/features/tmux-subagent/pane-state-parser.ts

@@ -0,0 +1,135 @@
+import type { TmuxPaneInfo } from "./types"
+
+const MANDATORY_PANE_FIELD_COUNT = 8
+
+type ParsedPaneState = {
+  windowWidth: number
+  windowHeight: number
+  panes: TmuxPaneInfo[]
+}
+
+type ParsedPaneLine = {
+  pane: TmuxPaneInfo
+  windowWidth: number
+  windowHeight: number
+}
+
+type MandatoryPaneFields = [
+  paneId: string,
+  widthString: string,
+  heightString: string,
+  leftString: string,
+  topString: string,
+  activeString: string,
+  windowWidthString: string,
+  windowHeightString: string,
+]
+
+export function parsePaneStateOutput(stdout: string): ParsedPaneState | null {
+  const lines = stdout
+    .split("\n")
+    .map((line) => line.replace(/\r$/, ""))
+    .filter((line) => line.length > 0)
+
+  if (lines.length === 0) return null
+
+  const parsedPaneLines = lines
+    .map(parsePaneLine)
+    .filter((parsedPaneLine): parsedPaneLine is ParsedPaneLine => parsedPaneLine !== null)
+
+  if (parsedPaneLines.length === 0) return null
+
+  const latestPaneLine = parsedPaneLines[parsedPaneLines.length - 1]
+  if (!latestPaneLine) return null
+
+  return {
+    windowWidth: latestPaneLine.windowWidth,
+    windowHeight: latestPaneLine.windowHeight,
+    panes: parsedPaneLines.map(({ pane }) => pane),
+  }
+}
+
+function parsePaneLine(line: string): ParsedPaneLine | null {
+  const fields = line.split("\t")
+  const mandatoryFields = getMandatoryPaneFields(fields)
+  if (!mandatoryFields) return null
+
+  const [paneId, widthString, heightString, leftString, topString, activeString, windowWidthString, windowHeightString] = mandatoryFields
+
+  const width = parseInteger(widthString)
+  const height = parseInteger(heightString)
+  const left = parseInteger(leftString)
+  const top = parseInteger(topString)
+  const isActive = parseActiveValue(activeString)
+  const windowWidth = parseInteger(windowWidthString)
+  const windowHeight = parseInteger(windowHeightString)
+
+  if (
+    width === null ||
+    height === null ||
+    left === null ||
+    top === null ||
+    isActive === null ||
+    windowWidth === null ||
+    windowHeight === null
+  ) {
+    return null
+  }
+
+  return {
+    pane: {
+      paneId,
+      width,
+      height,
+      left,
+      top,
+      title: fields.slice(MANDATORY_PANE_FIELD_COUNT).join("\t"),
+      isActive,
+    },
+    windowWidth,
+    windowHeight,
+  }
+}
+
+function getMandatoryPaneFields(fields: string[]): MandatoryPaneFields | null {
+  if (fields.length < MANDATORY_PANE_FIELD_COUNT) return null
+
+  const [paneId, widthString, heightString, leftString, topString, activeString, windowWidthString, windowHeightString] = fields
+
+  if (
+    paneId === undefined ||
+    widthString === undefined ||
+    heightString === undefined ||
+    leftString === undefined ||
+    topString === undefined ||
+    activeString === undefined ||
+    windowWidthString === undefined ||
+    windowHeightString === undefined
+  ) {
+    return null
+  }
+
+  return [
+    paneId,
+    widthString,
+    heightString,
+    leftString,
+    topString,
+    activeString,
+    windowWidthString,
+    windowHeightString,
+  ]
+}
+
+function parseInteger(value: string): number | null {
+  if (!/^\d+$/.test(value)) return null
+
+  const parsedValue = Number.parseInt(value, 10)
+  return Number.isNaN(parsedValue) ? null : parsedValue
+}
+
+function parseActiveValue(value: string): boolean | null {
+  if (value === "1") return true
+  if (value === "0") return false
+  return null
+}

src/features/tmux-subagent/pane-state-querier.test.ts

@@ -0,0 +1,75 @@
+/// <reference types="bun-types/test" />
+
+import { describe, expect, it } from "bun:test"
+import { parsePaneStateOutput } from "./pane-state-parser"
+
+describe("parsePaneStateOutput", () => {
+  it("accepts a single pane when tmux omits the empty trailing title field", () => {
+    // given
+    const stdout = "%0\t120\t40\t0\t0\t1\t120\t40\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).not.toBe(null)
+    expect(result).toEqual({
+      windowWidth: 120,
+      windowHeight: 40,
+      panes: [
+        {
+          paneId: "%0",
+          width: 120,
+          height: 40,
+          left: 0,
+          top: 0,
+          title: "",
+          isActive: true,
+        },
+      ],
+    })
+  })
+
+  it("handles CRLF line endings without dropping panes", () => {
+    // given
+    const stdout = "%0\t120\t40\t0\t0\t1\t120\t40\r\n%1\t60\t40\t60\t0\t0\t120\t40\tagent\r\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).not.toBe(null)
+    expect(result?.panes).toEqual([
+      {
+        paneId: "%0",
+        width: 120,
+        height: 40,
+        left: 0,
+        top: 0,
+        title: "",
+        isActive: true,
+      },
+      {
+        paneId: "%1",
+        width: 60,
+        height: 40,
+        left: 60,
+        top: 0,
+        title: "agent",
+        isActive: false,
+      },
+    ])
+  })
+
+  it("preserves tabs inside pane titles", () => {
+    // given
+    const stdout = "%0\t120\t40\t0\t0\t1\t120\t40\ttitle\twith\ttabs\n"
+
+    // when
+    const result = parsePaneStateOutput(stdout)
+
+    // then
+    expect(result).not.toBe(null)
+    expect(result?.panes[0]?.title).toBe("title\twith\ttabs")
+  })
+})

src/features/tmux-subagent/pane-state-querier.ts

@@ -1,5 +1,6 @@
 import { spawn } from "bun"
 import type { WindowState, TmuxPaneInfo } from "./types"
+import { parsePaneStateOutput } from "./pane-state-parser"
 import { getTmuxPath } from "../../tools/interactive-bash/tmux-path-resolver"
 import { log } from "../../shared"
 
@@ -27,32 +28,18 @@ export async function queryWindowState(sourcePaneId: string): Promise<WindowStat
     return null
   }
 
-  const lines = stdout.trim().replace(/\r/g, "").split("\n").filter(Boolean)
-  if (lines.length === 0) return null
-
-  let windowWidth = 0
-  let windowHeight = 0
-  const panes: TmuxPaneInfo[] = []
-
-  for (const line of lines) {
-		const fields = line.split("\t")
-		if (fields.length < 8) continue
-
-		const [paneId, widthStr, heightStr, leftStr, topStr, activeStr, windowWidthStr, windowHeightStr] = fields
-		const title = fields.length > 8 ? fields.slice(8).join("\t") : ""
-    const width = parseInt(widthStr, 10)
-    const height = parseInt(heightStr, 10)
-    const left = parseInt(leftStr, 10)
-    const top = parseInt(topStr, 10)
-    const isActive = activeStr === "1"
-    windowWidth = parseInt(windowWidthStr, 10)
-    windowHeight = parseInt(windowHeightStr, 10)
-
-    if (!isNaN(width) && !isNaN(left) && !isNaN(height) && !isNaN(top)) {
-      panes.push({ paneId, width, height, left, top, title, isActive })
-    }
+  const parsedPaneState = parsePaneStateOutput(stdout)
+  if (!parsedPaneState) {
+    log("[pane-state-querier] failed to parse pane state output", {
+      sourcePaneId,
+    })
+    return null
   }
 
+  const { panes } = parsedPaneState
+  const windowWidth = parsedPaneState.windowWidth
+  const windowHeight = parsedPaneState.windowHeight
+
   panes.sort((a, b) => a.left - b.left || a.top - b.top)
 
   const mainPane = panes.reduce<TmuxPaneInfo | null>((selected, pane) => {

src/hooks/atlas/idle-event.ts

@@ -110,6 +110,7 @@ function scheduleRetry(input: {
     const currentProgress = getPlanProgress(currentBoulder.active_plan)
     if (currentProgress.isComplete) return
     if (options?.isContinuationStopped?.(sessionID)) return
+    if (options?.shouldSkipContinuation?.(sessionID)) return
     if (hasRunningBackgroundTasks(sessionID, options)) return
 
     await injectContinuation({
@@ -192,6 +193,11 @@ export async function handleAtlasSessionIdle(input: {
     return
   }
 
+  if (options?.shouldSkipContinuation?.(sessionID)) {
+    log(`[${HOOK_NAME}] Skipped: another continuation hook already injected`, { sessionID })
+    return
+  }
+
   if (sessionState.lastContinuationInjectedAt && now - sessionState.lastContinuationInjectedAt < CONTINUATION_COOLDOWN_MS) {
     scheduleRetry({ ctx, sessionID, sessionState, options })
     log(`[${HOOK_NAME}] Skipped: continuation cooldown active`, {

src/hooks/atlas/index.test.ts

@@ -1042,6 +1042,37 @@ describe("atlas hook", () => {
        expect(mockInput._promptMock).not.toHaveBeenCalled()
      })
 
+     test("should skip when another continuation hook already injected", async () => {
+       // given - boulder state with incomplete plan
+       const planPath = join(TEST_DIR, "test-plan.md")
+       writeFileSync(planPath, "# Plan\n- [ ] Task 1\n- [ ] Task 2")
+
+       const state: BoulderState = {
+         active_plan: planPath,
+         started_at: "2026-01-02T10:00:00Z",
+         session_ids: [MAIN_SESSION_ID],
+         plan_name: "test-plan",
+       }
+       writeBoulderState(TEST_DIR, state)
+
+       const mockInput = createMockPluginInput()
+       const hook = createAtlasHook(mockInput, {
+         directory: TEST_DIR,
+         shouldSkipContinuation: (sessionID: string) => sessionID === MAIN_SESSION_ID,
+       })
+
+       // when
+       await hook.handler({
+         event: {
+           type: "session.idle",
+           properties: { sessionID: MAIN_SESSION_ID },
+         },
+       })
+
+       // then - should not call prompt because another continuation already handled it
+       expect(mockInput._promptMock).not.toHaveBeenCalled()
+     })
+
     test("should clear abort state on message.updated", async () => {
       // given - boulder with incomplete plan
       const planPath = join(TEST_DIR, "test-plan.md")

src/hooks/atlas/types.ts

@@ -7,6 +7,7 @@ export interface AtlasHookOptions {
   directory: string
   backgroundManager?: BackgroundManager
   isContinuationStopped?: (sessionID: string) => boolean
+  shouldSkipContinuation?: (sessionID: string) => boolean
   agentOverrides?: AgentOverrides
   /** Enable auto-commit after each atomic task completion (default: true) */
   autoCommit?: boolean

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

@@ -6,3 +6,4 @@ export { getCachedVersion } from "./checker/cached-version"
 export { updatePinnedVersion, revertPinnedVersion } from "./checker/pinned-version-updater"
 export { getLatestVersion } from "./checker/latest-version"
 export { checkForUpdate } from "./checker/check-for-update"
+export { syncCachePackageJsonToIntent } from "./checker/sync-package-json"

src/hooks/auto-update-checker/checker/sync-package-json.test.ts

@@ -0,0 +1,226 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test"
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { PluginEntryInfo } from "./plugin-entry"
+
+const TEST_CACHE_DIR = join(import.meta.dir, "__test-sync-cache__")
+
+mock.module("../constants", () => ({
+  CACHE_DIR: TEST_CACHE_DIR,
+  PACKAGE_NAME: "oh-my-opencode",
+}))
+
+mock.module("../../../shared/logger", () => ({
+  log: () => {},
+}))
+
+function resetTestCache(currentVersion = "3.10.0"): void {
+  if (existsSync(TEST_CACHE_DIR)) {
+    rmSync(TEST_CACHE_DIR, { recursive: true, force: true })
+  }
+
+  mkdirSync(TEST_CACHE_DIR, { recursive: true })
+  writeFileSync(
+    join(TEST_CACHE_DIR, "package.json"),
+    JSON.stringify({ dependencies: { "oh-my-opencode": currentVersion, other: "1.0.0" } }, null, 2)
+  )
+}
+
+function cleanupTestCache(): void {
+  if (existsSync(TEST_CACHE_DIR)) {
+    rmSync(TEST_CACHE_DIR, { recursive: true, force: true })
+  }
+}
+
+function readCachePackageJsonVersion(): string | undefined {
+  const content = readFileSync(join(TEST_CACHE_DIR, "package.json"), "utf-8")
+  const pkg = JSON.parse(content) as { dependencies?: Record<string, string> }
+  return pkg.dependencies?.["oh-my-opencode"]
+}
+
+describe("syncCachePackageJsonToIntent", () => {
+  beforeEach(() => {
+    resetTestCache()
+  })
+
+  afterEach(() => {
+    cleanupTestCache()
+  })
+
+  describe("#given cache package.json with pinned semver version", () => {
+    describe("#when opencode.json intent is latest tag", () => {
+      it("#then updates package.json to use latest", async () => {
+        const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+        const pluginInfo: PluginEntryInfo = {
+          entry: "oh-my-opencode@latest",
+          isPinned: false,
+          pinnedVersion: "latest",
+          configPath: "/tmp/opencode.json",
+        }
+
+        //#when
+        const result = syncCachePackageJsonToIntent(pluginInfo)
+
+        //#then
+        expect(result).toBe(true)
+        expect(readCachePackageJsonVersion()).toBe("latest")
+      })
+    })
+
+    describe("#when opencode.json intent is next tag", () => {
+      it("#then updates package.json to use next", async () => {
+        const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+        const pluginInfo: PluginEntryInfo = {
+          entry: "oh-my-opencode@next",
+          isPinned: false,
+          pinnedVersion: "next",
+          configPath: "/tmp/opencode.json",
+        }
+
+        //#when
+        const result = syncCachePackageJsonToIntent(pluginInfo)
+
+        //#then
+        expect(result).toBe(true)
+        expect(readCachePackageJsonVersion()).toBe("next")
+      })
+    })
+
+    describe("#when opencode.json has no version (implies latest)", () => {
+      it("#then updates package.json to use latest", async () => {
+        const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+        const pluginInfo: PluginEntryInfo = {
+          entry: "oh-my-opencode",
+          isPinned: false,
+          pinnedVersion: null,
+          configPath: "/tmp/opencode.json",
+        }
+
+        //#when
+        const result = syncCachePackageJsonToIntent(pluginInfo)
+
+        //#then
+        expect(result).toBe(true)
+        expect(readCachePackageJsonVersion()).toBe("latest")
+      })
+    })
+  })
+
+  describe("#given cache package.json already matches intent", () => {
+    it("#then returns false without modifying package.json", async () => {
+      //#given
+      resetTestCache("latest")
+      const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+      const pluginInfo: PluginEntryInfo = {
+        entry: "oh-my-opencode@latest",
+        isPinned: false,
+        pinnedVersion: "latest",
+        configPath: "/tmp/opencode.json",
+      }
+
+      //#when
+      const result = syncCachePackageJsonToIntent(pluginInfo)
+
+      //#then
+      expect(result).toBe(false)
+      expect(readCachePackageJsonVersion()).toBe("latest")
+    })
+  })
+
+  describe("#given cache package.json does not exist", () => {
+    it("#then returns false", async () => {
+      //#given
+      cleanupTestCache()
+      const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+      const pluginInfo: PluginEntryInfo = {
+        entry: "oh-my-opencode@latest",
+        isPinned: false,
+        pinnedVersion: "latest",
+        configPath: "/tmp/opencode.json",
+      }
+
+      //#when
+      const result = syncCachePackageJsonToIntent(pluginInfo)
+
+      //#then
+      expect(result).toBe(false)
+    })
+  })
+
+  describe("#given plugin not in cache package.json dependencies", () => {
+    it("#then returns false", async () => {
+      //#given
+      cleanupTestCache()
+      mkdirSync(TEST_CACHE_DIR, { recursive: true })
+      writeFileSync(
+        join(TEST_CACHE_DIR, "package.json"),
+        JSON.stringify({ dependencies: { other: "1.0.0" } }, null, 2)
+      )
+
+      const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+      const pluginInfo: PluginEntryInfo = {
+        entry: "oh-my-opencode@latest",
+        isPinned: false,
+        pinnedVersion: "latest",
+        configPath: "/tmp/opencode.json",
+      }
+
+      //#when
+      const result = syncCachePackageJsonToIntent(pluginInfo)
+
+      //#then
+      expect(result).toBe(false)
+    })
+  })
+
+  describe("#given user explicitly pinned a different semver", () => {
+    it("#then updates package.json to new version", async () => {
+      //#given
+      resetTestCache("3.9.0")
+      const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+      const pluginInfo: PluginEntryInfo = {
+        entry: "oh-my-opencode@3.10.0",
+        isPinned: true,
+        pinnedVersion: "3.10.0",
+        configPath: "/tmp/opencode.json",
+      }
+
+      //#when
+      const result = syncCachePackageJsonToIntent(pluginInfo)
+
+      //#then
+      expect(result).toBe(true)
+      expect(readCachePackageJsonVersion()).toBe("3.10.0")
+    })
+  })
+
+  describe("#given other dependencies exist in cache package.json", () => {
+    it("#then preserves other dependencies while updating the plugin", async () => {
+      //#given
+      const { syncCachePackageJsonToIntent } = await import("./sync-package-json")
+
+      const pluginInfo: PluginEntryInfo = {
+        entry: "oh-my-opencode@latest",
+        isPinned: false,
+        pinnedVersion: "latest",
+        configPath: "/tmp/opencode.json",
+      }
+
+      //#when
+      syncCachePackageJsonToIntent(pluginInfo)
+
+      //#then
+      const content = readFileSync(join(TEST_CACHE_DIR, "package.json"), "utf-8")
+      const pkg = JSON.parse(content) as { dependencies?: Record<string, string> }
+      expect(pkg.dependencies?.other).toBe("1.0.0")
+      expect(pkg.dependencies?.["oh-my-opencode"]).toBe("latest")
+    })
+  })
+})

src/hooks/auto-update-checker/checker/sync-package-json.ts

@@ -0,0 +1,63 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { CACHE_DIR, PACKAGE_NAME } from "../constants"
+import { log } from "../../../shared/logger"
+import type { PluginEntryInfo } from "./plugin-entry"
+
+interface CachePackageJson {
+  dependencies?: Record<string, string>
+}
+
+function getIntentVersion(pluginInfo: PluginEntryInfo): string {
+  if (!pluginInfo.pinnedVersion) {
+    return "latest"
+  }
+  return pluginInfo.pinnedVersion
+}
+
+/**
+ * Sync cache package.json to match opencode.json plugin intent before bun install.
+ *
+ * OpenCode pins resolved versions in cache package.json (e.g., "3.11.0" instead of "latest").
+ * When auto-update detects a newer version and runs `bun install`, it re-resolves the pinned
+ * version instead of the user's declared tag, causing updates to silently fail.
+ *
+ * @returns true if package.json was updated, false otherwise
+ */
+export function syncCachePackageJsonToIntent(pluginInfo: PluginEntryInfo): boolean {
+  const cachePackageJsonPath = path.join(CACHE_DIR, "package.json")
+
+  if (!fs.existsSync(cachePackageJsonPath)) {
+    log("[auto-update-checker] Cache package.json not found, nothing to sync")
+    return false
+  }
+
+  try {
+    const content = fs.readFileSync(cachePackageJsonPath, "utf-8")
+    const pkgJson = JSON.parse(content) as CachePackageJson
+
+    if (!pkgJson.dependencies?.[PACKAGE_NAME]) {
+      log("[auto-update-checker] Plugin not in cache package.json dependencies, nothing to sync")
+      return false
+    }
+
+    const currentVersion = pkgJson.dependencies[PACKAGE_NAME]
+    const intentVersion = getIntentVersion(pluginInfo)
+
+    if (currentVersion === intentVersion) {
+      log("[auto-update-checker] Cache package.json already matches intent:", intentVersion)
+      return false
+    }
+
+    log(
+      `[auto-update-checker] Syncing cache package.json: "${currentVersion}" → "${intentVersion}"`
+    )
+
+    pkgJson.dependencies[PACKAGE_NAME] = intentVersion
+    fs.writeFileSync(cachePackageJsonPath, JSON.stringify(pkgJson, null, 2))
+    return true
+  } catch (err) {
+    log("[auto-update-checker] Failed to sync cache package.json:", err)
+    return false
+  }
+}

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

@@ -54,6 +54,26 @@ function createPluginInput() {
   } as never
 }
 
+async function flushScheduledWork(): Promise<void> {
+  await new Promise<void>((resolve) => {
+    setTimeout(resolve, 0)
+  })
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+function runSessionCreatedEvent(
+  hook: ReturnType<HookFactory>,
+  properties?: { info?: { parentID?: string } }
+): void {
+  hook.event({
+    event: {
+      type: "session.created",
+      properties,
+    },
+  })
+}
+
 beforeEach(() => {
   mockShowConfigErrorsIfAny.mockClear()
   mockShowModelCacheWarningIfNeeded.mockClear()
@@ -85,13 +105,8 @@ describe("createAutoUpdateCheckerHook", () => {
     })
 
     //#when - session.created event arrives
-    hook.event({
-      event: {
-        type: "session.created",
-        properties: { info: { parentID: undefined } },
-      },
-    })
-    await new Promise((resolve) => setTimeout(resolve, 50))
+    runSessionCreatedEvent(hook, { info: { parentID: undefined } })
+    await flushScheduledWork()
 
     //#then - no update checker side effects run
     expect(mockShowConfigErrorsIfAny).not.toHaveBeenCalled()
@@ -108,12 +123,8 @@ describe("createAutoUpdateCheckerHook", () => {
     const hook = createAutoUpdateCheckerHook(createPluginInput())
 
     //#when - session.created event arrives on primary session
-    hook.event({
-      event: {
-        type: "session.created",
-      },
-    })
-    await new Promise((resolve) => setTimeout(resolve, 50))
+    runSessionCreatedEvent(hook)
+    await flushScheduledWork()
 
     //#then - startup checks, toast, and background check run
     expect(mockShowConfigErrorsIfAny).toHaveBeenCalledTimes(1)
@@ -129,13 +140,8 @@ describe("createAutoUpdateCheckerHook", () => {
     const hook = createAutoUpdateCheckerHook(createPluginInput())
 
     //#when - session.created event contains parentID
-    hook.event({
-      event: {
-        type: "session.created",
-        properties: { info: { parentID: "parent-123" } },
-      },
-    })
-    await new Promise((resolve) => setTimeout(resolve, 50))
+    runSessionCreatedEvent(hook, { info: { parentID: "parent-123" } })
+    await flushScheduledWork()
 
     //#then - no startup actions run
     expect(mockShowConfigErrorsIfAny).not.toHaveBeenCalled()
@@ -152,17 +158,9 @@ describe("createAutoUpdateCheckerHook", () => {
     const hook = createAutoUpdateCheckerHook(createPluginInput())
 
     //#when - session.created event is fired twice
-    hook.event({
-      event: {
-        type: "session.created",
-      },
-    })
-    hook.event({
-      event: {
-        type: "session.created",
-      },
-    })
-    await new Promise((resolve) => setTimeout(resolve, 50))
+    runSessionCreatedEvent(hook)
+    runSessionCreatedEvent(hook)
+    await flushScheduledWork()
 
     //#then - side effects execute only once
     expect(mockShowConfigErrorsIfAny).toHaveBeenCalledTimes(1)
@@ -179,12 +177,8 @@ describe("createAutoUpdateCheckerHook", () => {
     const hook = createAutoUpdateCheckerHook(createPluginInput())
 
     //#when - session.created event arrives
-    hook.event({
-      event: {
-        type: "session.created",
-      },
-    })
-    await new Promise((resolve) => setTimeout(resolve, 50))
+    runSessionCreatedEvent(hook)
+    await flushScheduledWork()
 
     //#then - local dev toast is shown and background check is skipped
     expect(mockShowConfigErrorsIfAny).toHaveBeenCalledTimes(1)
@@ -206,7 +200,7 @@ describe("createAutoUpdateCheckerHook", () => {
         type: "session.deleted",
       },
     })
-    await new Promise((resolve) => setTimeout(resolve, 50))
+    await flushScheduledWork()
 
     //#then - no startup actions run
     expect(mockShowConfigErrorsIfAny).not.toHaveBeenCalled()
@@ -225,12 +219,8 @@ describe("createAutoUpdateCheckerHook", () => {
     })
 
     //#when - session.created event arrives
-    hook.event({
-      event: {
-        type: "session.created",
-      },
-    })
-    await new Promise((resolve) => setTimeout(resolve, 50))
+    runSessionCreatedEvent(hook)
+    await flushScheduledWork()
 
     //#then - startup toast includes sisyphus wording
     expect(mockShowVersionToast).toHaveBeenCalledTimes(1)

src/hooks/auto-update-checker/hook/background-update-check.test.ts

@@ -1,6 +1,12 @@
-import type { PluginInput } from "@opencode-ai/plugin"
+/// <reference types="bun-types" />
+
+import type { BunInstallResult } from "../../../cli/config-manager"
 import { beforeEach, describe, expect, it, mock } from "bun:test"
 
+type PluginInput = {
+  directory: string
+}
+
 type PluginEntry = {
   entry: string
   isPinned: boolean
@@ -24,8 +30,14 @@ const mockFindPluginEntry = mock((_directory: string): PluginEntry | null => cre
 const mockGetCachedVersion = mock((): string | null => "3.4.0")
 const mockGetLatestVersion = mock(async (): Promise<string | null> => "3.5.0")
 const mockExtractChannel = mock(() => "latest")
-const mockInvalidatePackage = mock(() => {})
-const mockRunBunInstall = mock(async () => true)
+const operationOrder: string[] = []
+const mockSyncCachePackageJsonToIntent = mock((_pluginEntry: PluginEntry) => {
+  operationOrder.push("sync")
+})
+const mockInvalidatePackage = mock((_packageName: string) => {
+  operationOrder.push("invalidate")
+})
+const mockRunBunInstallWithDetails = mock(async (): Promise<BunInstallResult> => ({ success: true }))
 const mockShowUpdateAvailableToast = mock(
   async (_ctx: PluginInput, _latestVersion: string, _getToastMessage: ToastMessageGetter): Promise<void> => {}
 )
@@ -38,10 +50,11 @@ mock.module("../checker", () => ({
   getCachedVersion: mockGetCachedVersion,
   getLatestVersion: mockGetLatestVersion,
   revertPinnedVersion: mock(() => false),
+  syncCachePackageJsonToIntent: mockSyncCachePackageJsonToIntent,
 }))
 mock.module("../version-channel", () => ({ extractChannel: mockExtractChannel }))
 mock.module("../cache", () => ({ invalidatePackage: mockInvalidatePackage }))
-mock.module("../../../cli/config-manager", () => ({ runBunInstall: mockRunBunInstall }))
+mock.module("../../../cli/config-manager", () => ({ runBunInstallWithDetails: mockRunBunInstallWithDetails }))
 mock.module("./update-toasts", () => ({
   showUpdateAvailableToast: mockShowUpdateAvailableToast,
   showAutoUpdatedToast: mockShowAutoUpdatedToast,
@@ -51,83 +64,89 @@ mock.module("../../../shared/logger", () => ({ log: () => {} }))
 const modulePath = "./background-update-check?test"
 const { runBackgroundUpdateCheck } = await import(modulePath)
 
+const mockContext = { directory: "/test" } as PluginInput
+const getToastMessage: ToastMessageGetter = (isUpdate, version) =>
+  isUpdate ? `Update to ${version}` : "Up to date"
+
+async function runCheck(autoUpdate = true): Promise<void> {
+  await runBackgroundUpdateCheck(mockContext, autoUpdate, getToastMessage)
+}
+
+function expectNoUpdateEffects(): void {
+  expect(mockShowUpdateAvailableToast).not.toHaveBeenCalled()
+  expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
+  expect(mockRunBunInstallWithDetails).not.toHaveBeenCalled()
+  expect(mockSyncCachePackageJsonToIntent).not.toHaveBeenCalled()
+  expect(mockInvalidatePackage).not.toHaveBeenCalled()
+}
+
 describe("runBackgroundUpdateCheck", () => {
-  const mockCtx = { directory: "/test" } as PluginInput
-  const getToastMessage: ToastMessageGetter = (isUpdate, version) =>
-    isUpdate ? `Update to ${version}` : "Up to date"
+  let pluginEntry: PluginEntry
 
   beforeEach(() => {
     mockFindPluginEntry.mockReset()
     mockGetCachedVersion.mockReset()
     mockGetLatestVersion.mockReset()
     mockExtractChannel.mockReset()
+    mockSyncCachePackageJsonToIntent.mockReset()
     mockInvalidatePackage.mockReset()
-    mockRunBunInstall.mockReset()
+    mockRunBunInstallWithDetails.mockReset()
     mockShowUpdateAvailableToast.mockReset()
     mockShowAutoUpdatedToast.mockReset()
 
-    mockFindPluginEntry.mockReturnValue(createPluginEntry())
+    operationOrder.length = 0
+
+    mockSyncCachePackageJsonToIntent.mockImplementation((_pluginEntry: PluginEntry) => {
+      operationOrder.push("sync")
+    })
+    mockInvalidatePackage.mockImplementation((_packageName: string) => {
+      operationOrder.push("invalidate")
+    })
+
+    pluginEntry = createPluginEntry()
+    mockFindPluginEntry.mockReturnValue(pluginEntry)
     mockGetCachedVersion.mockReturnValue("3.4.0")
     mockGetLatestVersion.mockResolvedValue("3.5.0")
     mockExtractChannel.mockReturnValue("latest")
-    mockRunBunInstall.mockResolvedValue(true)
+    mockRunBunInstallWithDetails.mockResolvedValue({ success: true })
   })
 
-  describe("#given no plugin entry found", () => {
-    it("returns early without showing any toast", async () => {
+  describe("#given no-op scenarios", () => {
+    it.each([
+      {
+        name: "plugin entry is missing",
+        setup: () => {
+          mockFindPluginEntry.mockReturnValue(null)
+        },
+      },
+      {
+        name: "no cached or pinned version exists",
+        setup: () => {
+          mockFindPluginEntry.mockReturnValue(createPluginEntry({ entry: "oh-my-opencode" }))
+          mockGetCachedVersion.mockReturnValue(null)
+        },
+      },
+      {
+        name: "latest version lookup fails",
+        setup: () => {
+          mockGetLatestVersion.mockResolvedValue(null)
+        },
+      },
+      {
+        name: "current version is already latest",
+        setup: () => {
+          mockGetLatestVersion.mockResolvedValue("3.4.0")
+        },
+      },
+    ])("returns without user-visible update effects when $name", async ({ setup }) => {
       //#given
-      mockFindPluginEntry.mockReturnValue(null)
-      //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
-      //#then
-      expect(mockFindPluginEntry).toHaveBeenCalledTimes(1)
-      expect(mockShowUpdateAvailableToast).not.toHaveBeenCalled()
-      expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
-      expect(mockRunBunInstall).not.toHaveBeenCalled()
-    })
-  })
+      setup()
 
-  describe("#given no version available", () => {
-    it("returns early when neither cached nor pinned version exists", async () => {
-      //#given
-      mockFindPluginEntry.mockReturnValue(createPluginEntry({ entry: "oh-my-opencode" }))
-      mockGetCachedVersion.mockReturnValue(null)
       //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
-      //#then
-      expect(mockGetCachedVersion).toHaveBeenCalledTimes(1)
-      expect(mockGetLatestVersion).not.toHaveBeenCalled()
-      expect(mockShowUpdateAvailableToast).not.toHaveBeenCalled()
-      expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
-    })
-  })
+      await runCheck()
 
-  describe("#given latest version fetch fails", () => {
-    it("returns early without toasts", async () => {
-      //#given
-      mockGetLatestVersion.mockResolvedValue(null)
-      //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
       //#then
-      expect(mockGetLatestVersion).toHaveBeenCalledWith("latest")
-      expect(mockRunBunInstall).not.toHaveBeenCalled()
-      expect(mockShowUpdateAvailableToast).not.toHaveBeenCalled()
-      expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
-    })
-  })
-
-  describe("#given already on latest version", () => {
-    it("returns early without any action", async () => {
-      //#given
-      mockGetCachedVersion.mockReturnValue("3.4.0")
-      mockGetLatestVersion.mockResolvedValue("3.4.0")
-      //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
-      //#then
-      expect(mockGetLatestVersion).toHaveBeenCalledTimes(1)
-      expect(mockRunBunInstall).not.toHaveBeenCalled()
-      expect(mockShowUpdateAvailableToast).not.toHaveBeenCalled()
-      expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
+      expectNoUpdateEffects()
     })
   })
 
@@ -136,11 +155,12 @@ describe("runBackgroundUpdateCheck", () => {
       //#given
       const autoUpdate = false
       //#when
-      await runBackgroundUpdateCheck(mockCtx, autoUpdate, getToastMessage)
+      await runCheck(autoUpdate)
       //#then
-      expect(mockShowUpdateAvailableToast).toHaveBeenCalledWith(mockCtx, "3.5.0", getToastMessage)
-      expect(mockRunBunInstall).not.toHaveBeenCalled()
+      expect(mockShowUpdateAvailableToast).toHaveBeenCalledWith(mockContext, "3.5.0", getToastMessage)
+      expect(mockRunBunInstallWithDetails).not.toHaveBeenCalled()
       expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
+      expect(operationOrder).toEqual([])
     })
   })
 
@@ -149,10 +169,10 @@ describe("runBackgroundUpdateCheck", () => {
       //#given
       mockFindPluginEntry.mockReturnValue(createPluginEntry({ isPinned: true, pinnedVersion: "3.4.0" }))
       //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
+      await runCheck()
       //#then
       expect(mockShowUpdateAvailableToast).toHaveBeenCalledTimes(1)
-      expect(mockRunBunInstall).not.toHaveBeenCalled()
+      expect(mockRunBunInstallWithDetails).not.toHaveBeenCalled()
       expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
     })
 
@@ -166,7 +186,7 @@ describe("runBackgroundUpdateCheck", () => {
         }
       )
       //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
+      await runCheck()
       //#then
       expect(mockShowUpdateAvailableToast).toHaveBeenCalledTimes(1)
       expect(capturedToastMessage).toBeDefined()
@@ -182,27 +202,33 @@ describe("runBackgroundUpdateCheck", () => {
   describe("#given unpinned with auto-update and install succeeds", () => {
     it("invalidates cache, installs, and shows auto-updated toast", async () => {
       //#given
-      mockRunBunInstall.mockResolvedValue(true)
+      mockRunBunInstallWithDetails.mockResolvedValue({ success: true })
       //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
+      await runCheck()
       //#then
+      expect(mockSyncCachePackageJsonToIntent).toHaveBeenCalledWith(pluginEntry)
       expect(mockInvalidatePackage).toHaveBeenCalledTimes(1)
-      expect(mockRunBunInstall).toHaveBeenCalledTimes(1)
-      expect(mockShowAutoUpdatedToast).toHaveBeenCalledWith(mockCtx, "3.4.0", "3.5.0")
+      expect(mockRunBunInstallWithDetails).toHaveBeenCalledTimes(1)
+      expect(mockRunBunInstallWithDetails).toHaveBeenCalledWith({ outputMode: "pipe" })
+      expect(mockShowAutoUpdatedToast).toHaveBeenCalledWith(mockContext, "3.4.0", "3.5.0")
       expect(mockShowUpdateAvailableToast).not.toHaveBeenCalled()
+      expect(operationOrder).toEqual(["sync", "invalidate"])
     })
   })
 
   describe("#given unpinned with auto-update and install fails", () => {
     it("falls back to notification-only toast", async () => {
       //#given
-      mockRunBunInstall.mockResolvedValue(false)
+      mockRunBunInstallWithDetails.mockResolvedValue({ success: false, error: "install failed" })
       //#when
-      await runBackgroundUpdateCheck(mockCtx, true, getToastMessage)
+      await runCheck()
       //#then
-      expect(mockRunBunInstall).toHaveBeenCalledTimes(1)
-      expect(mockShowUpdateAvailableToast).toHaveBeenCalledWith(mockCtx, "3.5.0", getToastMessage)
+      expect(mockRunBunInstallWithDetails).toHaveBeenCalledTimes(1)
+      expect(mockRunBunInstallWithDetails).toHaveBeenCalledWith({ outputMode: "pipe" })
+      expect(mockSyncCachePackageJsonToIntent).toHaveBeenCalledWith(pluginEntry)
+      expect(mockShowUpdateAvailableToast).toHaveBeenCalledWith(mockContext, "3.5.0", getToastMessage)
       expect(mockShowAutoUpdatedToast).not.toHaveBeenCalled()
+      expect(operationOrder).toEqual(["sync", "invalidate"])
     })
   })
 })

src/hooks/auto-update-checker/hook/background-update-check.ts

@@ -1,10 +1,10 @@
 import type { PluginInput } from "@opencode-ai/plugin"
-import { runBunInstall } from "../../../cli/config-manager"
+import { runBunInstallWithDetails } from "../../../cli/config-manager"
 import { log } from "../../../shared/logger"
 import { invalidatePackage } from "../cache"
 import { PACKAGE_NAME } from "../constants"
 import { extractChannel } from "../version-channel"
-import { findPluginEntry, getCachedVersion, getLatestVersion, revertPinnedVersion } from "../checker"
+import { findPluginEntry, getCachedVersion, getLatestVersion, revertPinnedVersion, syncCachePackageJsonToIntent } from "../checker"
 import { showAutoUpdatedToast, showUpdateAvailableToast } from "./update-toasts"
 
 function getPinnedVersionToastMessage(latestVersion: string): string {
@@ -13,7 +13,12 @@ function getPinnedVersionToastMessage(latestVersion: string): string {
 
 async function runBunInstallSafe(): Promise<boolean> {
   try {
-    return await runBunInstall()
+    const result = await runBunInstallWithDetails({ outputMode: "pipe" })
+    if (!result.success && result.error) {
+      log("[auto-update-checker] bun install failed:", result.error)
+    }
+
+    return result.success
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err)
     log("[auto-update-checker] bun install error:", errorMessage)
@@ -65,6 +70,7 @@ export async function runBackgroundUpdateCheck(
     return
   }
 
+  syncCachePackageJsonToIntent(pluginInfo)
   invalidatePackage(PACKAGE_NAME)
 
   const installSuccess = await runBunInstallSafe()