oh-my-opencode-slim 2.0.0-beta.13 → 2.0.0-beta.15

package/README.md

@@ -2,8 +2,8 @@
   <a href="https://github.com/alvinunreal/oh-my-opencode-slim/stargazers">
     <img src="img/4k.png" alt="4K GitHub Stars Milestone" style="border-radius: 10px;">
   </a>
-  <h3>✨ V2 Beta Release: Background Orchestration Has Arrived ✨</h3>
-  <p><i>The orchestrator now schedules specialist agents in the background,<br>while <code>/deepwork</code> turns big goals into file-backed plans.<br>Beta testers: share your feedback with us on Telegram.</i></p>
+  <h3>✨ Default Background Orchestration Has Arrived ✨</h3>
+  <p><i>The orchestrator now manages the workflow and schedules specialist agents in the background,<br>while <code>/deepwork</code> turns big goals into file-backed plans.<br>Share feedback and questions with us on Telegram.</i></p>
 
   <p><b>Open Multi Agent Suite</b> · Mix any models · Auto delegate tasks</p>
 
@@ -15,7 +15,7 @@
   </p>
 
   <p>
-    <b>English</b> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja-JP.md">日本語</a>
+    <b>English</b> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja-JP.md">日本語</a> | <a href="README.ko-KR.md">한국어</a>
   </p>
 </div>
 
@@ -45,22 +45,31 @@ Install and configure oh-my-opencode-slim: https://raw.githubusercontent.com/alv
 bunx oh-my-opencode-slim@latest install
 ```
 
-### V2 Background-Orchestration Beta
+### Default Background Orchestration
 
-V2 changes the orchestrator from the default execution worker into a scheduler:
-it plans work, dispatches specialists as background tasks, receives completion
-events from OpenCode or checks status only when needed, then reconciles results
-before continuing. This requires OpenCode's native background subagent support,
-so beta users must start OpenCode with the experimental flag enabled.
+The orchestrator is now a workflow manager and scheduler, not the main coding
+worker: it plans work, dispatches specialists as background tasks, receives
+completion events from OpenCode or checks status only when needed, then
+reconciles results before continuing. This uses OpenCode's native background
+subagent support, so OpenCode must run with the background-subagents environment
+variable enabled.
 
 ```bash
-bunx oh-my-opencode-slim@beta install
-OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=1 opencode
+bunx oh-my-opencode-slim@beta install --background-subagents=yes
 ```
 
+The installer can set this up for you with
+`--background-subagents=ask|yes|no`. In an interactive TTY, the default is
+`ask`; in non-interactive mode, the default is `no`. Use
+`--background-subagents=yes` to opt in immediately or `--background-subagents=no`
+to skip. If you want the installer to write to a specific shell/profile file,
+add `--background-subagents-target=<path>`. After shell setup, restart your
+terminal or source the updated file before starting `opencode`; for a one-shot
+launch, run `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode`.
+
 ### Getting Started
 
-The installer generates both OpenAI and OpenCode Go presets, with OpenAI active by default. OpenAI uses `openai/gpt-5.5` for the higher-judgment agents and `openai/gpt-5.4-mini` for the faster scoped agents. To make OpenCode Go active during install, run `bunx oh-my-opencode-slim@latest install --preset=opencode-go` or change the default preset name in `~/.config/opencode/oh-my-opencode-slim.json` after installation.
+The installer generates both OpenAI and OpenCode Go presets, with OpenAI active by default. OpenAI uses `openai/gpt-5.5` for the workflow manager/scheduler and higher-judgment agents, and `openai/gpt-5.4-mini` for faster scoped specialists. To make OpenCode Go active during install, run `bunx oh-my-opencode-slim@latest install --preset=opencode-go` or change the default preset name in `~/.config/opencode/oh-my-opencode-slim.json` after installation.
 
 Then:
 
@@ -75,11 +84,19 @@ Then:
    opencode models --refresh
    ```
 3. **Open your plugin config** at `~/.config/opencode/oh-my-opencode-slim.json`
+   or `$OPENCODE_CONFIG_DIR/oh-my-opencode-slim.json` if you use a custom
+   OpenCode config directory
 
 4. **Update the models you want for each agent**
 
 > [!TIP]
-> It's **recommended** to understand how automatic delegation works. The **[Orchestrator prompt](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/src/agents/orchestrator.ts#L28)** contains the delegation rules, specialist routing logic, and the thresholds for when the main agent should hand work off to subagents. You can alway delegate manually by calling a subagent via: `@agentName <task>`
+> It's **recommended** to understand how background orchestration works. The **[Orchestrator prompt](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/src/agents/orchestrator.ts#L28)** contains the scheduler rules, specialist routing logic, and thresholds for when work should be assigned to background agents. You can always delegate manually by calling a subagent via: `@agentName <task>`
+
+### Legacy V1 note
+
+The current `@latest` package is the background-orchestration release. If a
+maintained V1 branch or tag is created later, it will be documented separately as
+historical compatibility guidance rather than part of the default install path.
 
 The default generated configuration includes both `openai` and `opencode-go` presets.
 
@@ -180,7 +197,7 @@ If any agent fails to respond, check your provider authentication and config fil
   </tr>
   <tr>
     <td colspan="2">
-      <b>Model Guidance:</b> Choose your default, strongest all-around coding model. Orchestrator is both the main coding agent and the delegator, so it needs strong implementation ability, good judgment, and reliable instruction-following.
+      <b>Model Guidance:</b> Choose your strongest planning and judgment model. Orchestrator is the workflow manager: it plans, schedules background specialists, reconciles results, and verifies outcomes, so it needs reliable instruction-following and high-level technical judgment more than raw worker throughput.
     </td>
   </tr>
 </table>
@@ -500,10 +517,9 @@ Use this section as a map: start with installation, then jump to features, confi
 | Doc | What it covers |
 |-----|----------------|
 | **[Council](docs/council.md)** | Run multiple models in parallel and synthesize a single answer with `@council` |
-| **[V2 Background Orchestration](docs/v2-background-orchestration.md)** | Scheduler-first orchestrator model built around native background subagents |
+| **[Background Orchestration](docs/v2-background-orchestration.md)** | Scheduler-first orchestrator model built around native background subagents |
 | **[Multiplexer Integration](docs/multiplexer-integration.md)** | Watch agents work live in Tmux or Zellij panes |
 | **[Session Management](docs/session-management.md)** | Reuse recent child-agent sessions with short aliases instead of starting over |
-| **[Todo Continuation](docs/todo-continuation.md)** | Auto-continue orchestrator sessions with cooldowns and safety checks |
 | **[Preset Switching](docs/preset-switching.md)** | Switch agent model presets at runtime with `/preset` |
 | **[Custom Agents](docs/configuration.md#custom-agents)** | Define your own specialists with custom prompts, models, MCP access, and Orchestrator delegation rules |
 | **[Codemap](docs/codemap.md)** | Generate hierarchical codemaps to understand large codebases faster |
@@ -517,7 +533,7 @@ Use this section as a map: start with installation, then jump to features, confi
 |-----|----------------|
 | **[Configuration](docs/configuration.md)** | Config file locations, JSONC support, prompt overrides, and full option reference |
 | **[Maintainer Guide](docs/maintainers.md)** | Issue triage rules, label meanings, support routing, and repo maintenance workflow |
-| **[Skills](docs/skills.md)** | Bundled skills such as `simplify`, `codemap`, and `clonedeps` |
+| **[Skills](docs/skills.md)** | Bundled skills such as `simplify`, `codemap`, `clonedeps`, `deepwork`, and `oh-my-opencode-slim` |
 | **[MCPs](docs/mcps.md)** | `websearch`, `context7`, `grep_app`, and how MCP permissions work per agent |
 | **[Tools](docs/tools.md)** | Built-in tool capabilities like `webfetch`, LSP tools, code search, and formatters |
 
@@ -538,7 +554,7 @@ Use this section as a map: start with installation, then jump to features, confi
   <p><sub>Every merged contribution leaves a mark on the realm.</sub></p>
 
   <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-53-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-58-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 </div>
 
@@ -619,6 +635,13 @@ Use this section as a map: start with installation, then jump to features, confi
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/yolo2h"><img src="https://avatars.githubusercontent.com/u/10754850?v=4?s=100" width="100px;" alt="Yolo"/><br /><sub><b>Yolo</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=yolo2h" title="Code">💻</a></td>
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/xinxingi"><img src="https://avatars.githubusercontent.com/u/49302071?v=4?s=100" width="100px;" alt="XinXing"/><br /><sub><b>XinXing</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=xinxingi" title="Code">💻</a></td>
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/eltociear"><img src="https://avatars.githubusercontent.com/u/22633385?v=4?s=100" width="100px;" alt="Ikko Eltociear Ashimine"/><br /><sub><b>Ikko Eltociear Ashimine</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=eltociear" title="Code">💻</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="https://github.com/dev-wantap"><img src="https://avatars.githubusercontent.com/u/69743540?v=4?s=100" width="100px;" alt="GWANWOO KIM"/><br /><sub><b>GWANWOO KIM</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=dev-wantap" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="16.66%"><a href="https://github.com/OmerFarukOruc"><img src="https://avatars.githubusercontent.com/u/7347742?v=4?s=100" width="100px;" alt="Omer Faruk Oruc"/><br /><sub><b>Omer Faruk Oruc</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=OmerFarukOruc" title="Code">💻</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="https://khallaf.uk/"><img src="https://avatars.githubusercontent.com/u/51155980?v=4?s=100" width="100px;" alt="Omar Mohamed Khallaf"/><br /><sub><b>Omar Mohamed Khallaf</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=omar-mohamed-khallaf" title="Code">💻</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="https://github.com/Qesire"><img src="https://avatars.githubusercontent.com/u/102657430?v=4?s=100" width="100px;" alt="Knowingthesea_Qesire"/><br /><sub><b>Knowingthesea_Qesire</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=Qesire" title="Code">💻</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="http://www.flyinghail.net/"><img src="https://avatars.githubusercontent.com/u/157430?v=4?s=100" width="100px;" alt="FENG Hao"/><br /><sub><b>FENG Hao</b></sub></a><br /><a href="https://github.com/alvinunreal/oh-my-opencode-slim/commits?author=flyinghail" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

package/README.zh-CN.md

@@ -1,9 +1,6 @@
 <div align="center">
-  <a href="https://github.com/alvinunreal/oh-my-opencode-slim/stargazers">
-    <img src="img/v2beta.webp" alt="V2 Beta Release" style="border-radius: 10px;">
-  </a>
-  <h3>✨ V2 Beta 版本：后台编排已上线 ✨</h3>
-  <p><i>编排者（Orchestrator）现在可在后台调度专家智能体，<br>同时 <code>/deepwork</code> 可以将宏大目标转化为基于文件的具体计划。<br>Beta 测试人员：请在 Telegram 上与我们分享您的反馈。</i></p>
+  <h3>✨ 默认后台编排已上线 ✨</h3>
+  <p><i>编排者（Orchestrator）现在作为工作流管理器在后台调度专家智能体，<br>同时 <code>/deepwork</code> 可以将宏大目标转化为基于文件的具体计划。<br>欢迎在 Telegram 上与我们分享反馈。</i></p>
 
   <p><b>开放式多智能体套件</b> · 混合任意模型 · 自动委派任务</p>
 
@@ -15,7 +12,7 @@
   </p>
 
   <p>
-    <a href="README.md">English</a> | <b>简体中文</b> | <a href="README.ja-JP.md">日本語</a>
+    <a href="README.md">English</a> | <b>简体中文</b> | <a href="README.ja-JP.md">日本語</a> | <a href="README.ko-KR.md">한국어</a>
   </p>
 </div>
 
@@ -43,16 +40,19 @@ Install and configure oh-my-opencode-slim: https://raw.githubusercontent.com/alv
 bunx oh-my-opencode-slim@latest install
 ```
 
-### V2 后台编排 Beta 版
+> **翻译状态说明：** 英文 README 是最新版本；此中文翻译可能仍有少量旧表述。
 
-V2 将编排者（Orchestrator）从默认的执行工作器转变为调度器：
-它规划工作、将专家作为后台任务分发、轮询其状态，并在继续执行之前核对结果。这需要 OpenCode 原生的后台子智能体支持，因此 Beta 版用户必须在启用实验性标志的情况下启动 OpenCode。
+### 默认后台编排
+
+当前版本将编排者（Orchestrator）从默认的执行工作器转变为调度器：
+它规划工作、将专家作为后台任务分发、按需检查状态，并在继续执行之前核对结果。这需要 OpenCode 原生的后台子智能体支持，因此请使用下方环境变量启动 OpenCode。
 
 ```bash
-bunx oh-my-opencode-slim@beta install
-OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=1 opencode
+bunx oh-my-opencode-slim@beta install --background-subagents=yes
 ```
 
+安装后请重启终端或 source 更新过的 shell 文件，然后再运行 `opencode`；也可以一次性使用 `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode` 启动。
+
 ### 入门指南
 
 安装程序会同时生成 OpenAI 和 OpenCode Go 的预设（Preset），默认启用 OpenAI 预设。OpenAI 使用 `openai/gpt-5.5` 作为具备高级判断力智能体的模型，并使用 `openai/gpt-5.4-mini` 作为响应更快速、针对具体任务智能体的模型。若要在安装过程中激活 OpenCode Go 预设，请运行 `bunx oh-my-opencode-slim@latest install --preset=opencode-go` 或在安装后修改 `~/.config/opencode/oh-my-opencode-slim.json` 文件中的默认预设名称。
@@ -74,7 +74,7 @@ OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=1 opencode
 4. **为您要分配的每个智能体更新模型配置**
 
 > [!TIP]
-> **强烈建议**了解自动委派（Automatic Delegation）的工作原理。**[编排者提示词 (Orchestrator prompt)](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/src/agents/orchestrator.ts#L28)** 包含了委派规则、专家路由逻辑，以及主智能体何时将工作转交给子智能体的阈值。您始终可以通过以下方式手动委派任务：`@智能体名称 <任务内容>`
+> **建议**了解后台编排的工作原理。**[编排者提示词 (Orchestrator prompt)](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/src/agents/orchestrator.ts#L28)** 包含调度规则、专家路由逻辑，以及何时应把工作分配给后台智能体的阈值。您始终可以通过以下方式手动委派任务：`@智能体名称 <任务内容>`
 
 默认生成的配置包含 `openai` 和 `opencode-go` 两个预设：
 
@@ -116,8 +116,10 @@ OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=1 opencode
 
 在完成安装与认证后，请验证所有智能体是否已正确配置并能够响应：
 
+请先确保已重启终端或 source 更新过的 shell 文件。环境变量生效后可运行 `opencode`；如果尚未更新当前 shell，请使用：
+
 ```bash
-opencode
+OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode
 ```
 
 然后运行：
@@ -495,10 +497,8 @@ ping all agents
 | **[Council (议会) (docs/council.md)](docs/council.md)** | 使用 `@council` 并行运行多个模型并合成单一答案 |
 | **[多路复用器集成 (docs/multiplexer-integration.md)](docs/multiplexer-integration.md)** | 在 Tmux 或 Zellij 窗格中实时观看智能体的工作过程 |
 | **[会话管理 (docs/session-management.md)](docs/session-management.md)** | 使用短别名复用最近的子智能体会话，而不是重新开始 |
-| **[待办事项持续执行 (docs/todo-continuation.md)](docs/todo-continuation.md)** | 具备冷却时间和安全检查的编排者会话自动持续执行 |
 | **[运行时预设切换 (docs/preset-switching.md)](docs/preset-switching.md)** | 在运行时使用 `/preset` 切换智能体模型预设 |
 | **[自定义智能体 (docs/configuration.md#custom-agents)](docs/configuration.md#custom-agents)** | 自定义专家智能体：配置独特的提示词、模型、MCP 权限和编排者委派规则 |
-| **[子任务 (docs/subtask.md)](docs/subtask.md)** | 使用 `/subtask` 运行受限的子工作器，并将结构化总结返回到主会话 |
 | **[代码地图 (Codemap) (docs/codemap.md)](docs/codemap.md)** | 生成层级代码地图，快速理解大型代码库 |
 | **[克隆依赖 (Clonedeps) (docs/clonedeps.md)](docs/clonedeps.md)** | 将选定的依赖源码克隆到被忽略的本地工作区中以供检查 |
 | **[访谈式生成 (Interview) (docs/interview.md)](docs/interview.md)** | 通过基于浏览器的问答流，将粗糙的想法转变为结构化的 Markdown 规范文档 |

package/dist/cli/background-subagents.d.ts

@@ -0,0 +1,13 @@
+export type BackgroundSubagentsMode = 'ask' | 'yes' | 'no';
+export type ShellKind = 'bash' | 'fish' | 'zsh';
+export declare function isBackgroundSubagentsEnabled(value: string | undefined): boolean;
+export declare function detectShellKind(shell: string | undefined): ShellKind | undefined;
+export declare function detectBackgroundSubagentsTarget(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function getBackgroundSubagentsBlock(targetPath: string): string;
+export declare function manualBackgroundSubagentsInstructions(options?: {
+    targetPath?: string;
+    shell?: ShellKind;
+}): string;
+export declare function expandHomePath(targetPath: string): string;
+export declare function upsertBackgroundSubagentsBlock(content: string, block: string): string;
+export declare function writeBackgroundSubagentsBlock(targetPath: string): void;

package/dist/cli/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env bun
-export {};
+import type { InstallArgs } from './types';
+export declare function parseArgs(args: string[]): InstallArgs;

package/dist/cli/index.js

@@ -100,7 +100,7 @@ function getConfigSearchDirs() {
   });
 }
 function getOpenCodeConfigPaths() {
-  const configDir = getDefaultOpenCodeConfigDir();
+  const configDir = getConfigDir();
   return [join(configDir, "opencode.json"), join(configDir, "opencode.jsonc")];
 }
 function getConfigJson() {
@@ -367,12 +367,6 @@ var DivoomConfigSchema = z2.object({
   posterizeBits: z2.number().int().min(1).max(8).default(3),
   gifs: z2.record(z2.string(), z2.string().min(1)).optional()
 });
-var TodoContinuationConfigSchema = z2.object({
-  maxContinuations: z2.number().int().min(1).max(50).default(5).describe("Maximum consecutive auto-continuations before stopping to ask user"),
-  cooldownMs: z2.number().int().min(0).max(30000).default(3000).describe("Delay in ms before auto-continuing (gives user time to abort)"),
-  autoEnable: z2.boolean().default(false).describe("Automatically enable auto-continue when the orchestrator session has enough todos"),
-  autoEnableThreshold: z2.number().int().min(1).max(50).default(4).describe("Number of todos that triggers auto-enable (only used when autoEnable is true)")
-});
 var FailoverConfigSchema = z2.object({
   enabled: z2.boolean().default(true),
   timeoutMs: z2.number().min(0).default(15000),
@@ -419,7 +413,6 @@ var PluginConfigSchema = z2.object({
   interview: InterviewConfigSchema.optional(),
   backgroundJobs: BackgroundJobsConfigSchema.optional(),
   divoom: DivoomConfigSchema.optional(),
-  todoContinuation: TodoContinuationConfigSchema.optional(),
   fallback: FailoverConfigSchema.optional(),
   council: CouncilConfigSchema.optional()
 }).superRefine((value, ctx) => {
@@ -479,6 +472,12 @@ var CUSTOM_SKILLS = [
     description: "Heavy/complex coding sessions and large modifications workflow",
     allowedAgents: ["orchestrator"],
     sourcePath: "src/skills/deepwork"
+  },
+  {
+    name: "oh-my-opencode-slim",
+    description: "Configure, customize, and safely improve oh-my-opencode-slim setups",
+    allowedAgents: ["orchestrator"],
+    sourcePath: "src/skills/oh-my-opencode-slim"
   }
 ];
 function getCustomSkillsDir() {
@@ -625,6 +624,12 @@ function generateLiteConfig(installConfig) {
 
 // src/cli/config-io.ts
 var PACKAGE_NAME = "oh-my-opencode-slim";
+var DEFAULT_OPENCODE_AGENTS_TO_DISABLE = [
+  "build",
+  "explore",
+  "general",
+  "plan"
+];
 function isString(value) {
   return typeof value === "string";
 }
@@ -705,17 +710,49 @@ function getPluginEntry() {
     return PACKAGE_NAME;
   }
 }
-function getOpenCodePluginCacheDir() {
+function getPinnedVersionFromConfig() {
+  try {
+    const { config } = parseConfig(getExistingConfigPath());
+    if (!config)
+      return;
+    for (const entry of getPlugins(config)) {
+      const spec = getPluginSpec(entry);
+      if (!spec)
+        continue;
+      if (spec === PACKAGE_NAME)
+        return;
+      if (spec.startsWith(`${PACKAGE_NAME}@`)) {
+        const version = spec.slice(PACKAGE_NAME.length + 1);
+        if (version && version !== "latest")
+          return version;
+      }
+    }
+  } catch {}
+  return;
+}
+function getVersionFromPackageRoot(packageRoot) {
+  try {
+    const packageJsonPath = join3(packageRoot, "package.json");
+    if (!existsSync3(packageJsonPath))
+      return;
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return pkg.version;
+  } catch {
+    return;
+  }
+}
+function getOpenCodePluginCacheDir(version) {
   const cacheDir = process.env.XDG_CACHE_HOME?.trim() || join3(homedir2(), ".cache");
-  return join3(cacheDir, "opencode", "packages", `${PACKAGE_NAME}@latest`);
+  const suffix = version ? `${PACKAGE_NAME}@${version}` : `${PACKAGE_NAME}@latest`;
+  return join3(cacheDir, "opencode", "packages", suffix);
 }
-function writeOpenCodePluginCacheManifest(cacheDir) {
+function writeOpenCodePluginCacheManifest(cacheDir, version = "latest") {
   try {
     writeFileSync(join3(cacheDir, "package.json"), JSON.stringify({
       name: `${PACKAGE_NAME}-cache`,
       private: true,
       dependencies: {
-        [PACKAGE_NAME]: "latest"
+        [PACKAGE_NAME]: version
       }
     }, null, 2));
     return null;
@@ -763,7 +800,10 @@ async function warmOpenCodePluginCache() {
   if (!packageRoot || !isPackageManagerInstall(packageRoot)) {
     return null;
   }
-  const cacheDir = getOpenCodePluginCacheDir();
+  const pinnedVersion = getPinnedVersionFromConfig();
+  const runningVersion = getVersionFromPackageRoot(packageRoot);
+  const cacheVersion = pinnedVersion ?? runningVersion;
+  const cacheDir = getOpenCodePluginCacheDir(cacheVersion);
   try {
     mkdirSync3(cacheDir, { recursive: true });
   } catch (err) {
@@ -773,7 +813,7 @@ async function warmOpenCodePluginCache() {
       error: `Failed to create OpenCode cache directory: ${err}`
     };
   }
-  const manifestError = writeOpenCodePluginCacheManifest(cacheDir);
+  const manifestError = writeOpenCodePluginCacheManifest(cacheDir, cacheVersion);
   if (manifestError)
     return manifestError;
   try {
@@ -956,8 +996,13 @@ function disableDefaultAgents() {
     }
     const config = parsedConfig ?? {};
     const agent = config.agent ?? {};
-    agent.explore = { disable: true };
-    agent.general = { disable: true };
+    for (const agentName of DEFAULT_OPENCODE_AGENTS_TO_DISABLE) {
+      const existing = agent[agentName];
+      agent[agentName] = {
+        ...existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {},
+        disable: true
+      };
+    }
     config.agent = agent;
     writeConfig(configPath, config);
     return { success: true, configPath };
@@ -1304,8 +1349,103 @@ Options:
 }
 
 // src/cli/install.ts
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import { createInterface } from "node:readline/promises";
+
+// src/cli/background-subagents.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname4, join as join5 } from "node:path";
+var ENV_NAME = "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS";
+var START_MARKER = "# >>> oh-my-opencode-slim background subagents >>>";
+var END_MARKER = "# <<< oh-my-opencode-slim background subagents <<<";
+function isBackgroundSubagentsEnabled(value) {
+  if (!value)
+    return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized !== "" && !["0", "false", "no", "off"].includes(normalized);
+}
+function detectShellKind(shell) {
+  const name = shell?.split("/").at(-1);
+  if (name === "zsh" || name === "bash" || name === "fish")
+    return name;
+  return;
+}
+function detectBackgroundSubagentsTarget(env = process.env) {
+  const shell = detectShellKind(env.SHELL);
+  if (shell === "zsh")
+    return join5(homedir3(), ".zshrc");
+  if (shell === "bash")
+    return join5(homedir3(), ".bashrc");
+  if (shell === "fish") {
+    const configHome = env.XDG_CONFIG_HOME || join5(homedir3(), ".config");
+    return join5(configHome, "fish", "conf.d", "opencode-background-subagents.fish");
+  }
+  return;
+}
+function getBackgroundSubagentsBlock(targetPath) {
+  const isFish = targetPath.endsWith(".fish");
+  const command = isFish ? `set -gx ${ENV_NAME} true` : `export ${ENV_NAME}=true`;
+  return `${START_MARKER}
+${command}
+${END_MARKER}`;
+}
+function manualBackgroundSubagentsInstructions(options) {
+  const shell = options?.shell ?? (options?.targetPath?.endsWith(".fish") ? "fish" : undefined) ?? detectShellKind(options?.targetPath);
+  const bashZshSnippet = `export ${ENV_NAME}=true`;
+  const fishSnippet = `set -gx ${ENV_NAME} true`;
+  if (shell === "fish") {
+    return `Start OpenCode with background subagents enabled:
+  env ${ENV_NAME}=true opencode
+
+Or add this to your fish startup file:
+  ${fishSnippet}`;
+  }
+  if (shell === "bash" || shell === "zsh") {
+    return `Start OpenCode with background subagents enabled:
+  ${ENV_NAME}=true opencode
+
+Or add this to your shell startup file:
+  ${bashZshSnippet}`;
+  }
+  return `Start OpenCode with background subagents enabled:
+  ${ENV_NAME}=true opencode
+
+Or add one of these to your shell startup file:
+  bash/zsh: ${bashZshSnippet}
+  fish: ${fishSnippet}`;
+}
+function expandHomePath(targetPath) {
+  if (targetPath === "~")
+    return homedir3();
+  if (targetPath.startsWith("~/"))
+    return join5(homedir3(), targetPath.slice(2));
+  return targetPath;
+}
+function upsertBackgroundSubagentsBlock(content, block) {
+  const start = content.indexOf(START_MARKER);
+  const end = content.indexOf(END_MARKER);
+  if (start !== -1 && end !== -1 && end > start) {
+    const afterEnd = end + END_MARKER.length;
+    return `${content.slice(0, start)}${block}${content.slice(afterEnd)}`;
+  }
+  const separator = content.length > 0 && !content.endsWith(`
+`) ? `
+
+` : "";
+  const prefix = content.length > 0 && content.endsWith(`
+`) ? `
+` : separator;
+  return `${content}${prefix}${block}
+`;
+}
+function writeBackgroundSubagentsBlock(targetPath) {
+  const block = getBackgroundSubagentsBlock(targetPath);
+  const content = existsSync5(targetPath) ? readFileSync4(targetPath, "utf8") : "";
+  const nextContent = upsertBackgroundSubagentsBlock(content, block);
+  mkdirSync4(dirname4(targetPath), { recursive: true });
+  writeFileSync2(targetPath, nextContent);
+}
 // src/cli/system.ts
 import { spawnSync } from "node:child_process";
 import { statSync as statSync4 } from "node:fs";
@@ -1517,6 +1657,59 @@ async function checkOpenCodeInstalled() {
   printSuccess(`OpenCode ${detectedVersion} detected${pathInfo}`);
   return { ok: true, version: version ?? undefined, path: path2 ?? undefined };
 }
+function shouldPromptForBackgroundSubagents(config) {
+  return Boolean(config.promptForStar && process.stdin.isTTY);
+}
+async function configureBackgroundSubagents(config) {
+  if (isBackgroundSubagentsEnabled(process.env.OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS)) {
+    printSuccess("OpenCode background subagents already enabled in environment");
+    return { enabledNow: true };
+  }
+  const target = config.backgroundSubagentsTarget !== undefined ? expandHomePath(config.backgroundSubagentsTarget) : detectBackgroundSubagentsTarget();
+  if (config.backgroundSubagents === "no") {
+    printInfo("OpenCode background subagents are not enabled.");
+    console.log(manualBackgroundSubagentsInstructions({ targetPath: target }));
+    return { enabledNow: false };
+  }
+  if (!target) {
+    printInfo("No safe shell startup file detected.");
+    console.log(manualBackgroundSubagentsInstructions());
+    return { enabledNow: false };
+  }
+  const block = getBackgroundSubagentsBlock(target);
+  if (config.dryRun) {
+    printInfo("Dry run mode - background subagents block that would be written:");
+    console.log(`Target: ${target}`);
+    console.log(`
+${block}
+`);
+    return { enabledNow: false, configuredTarget: target };
+  }
+  if (config.backgroundSubagents === "ask") {
+    if (!shouldPromptForBackgroundSubagents(config)) {
+      printInfo("Skipped background subagents shell configuration.");
+      console.log(manualBackgroundSubagentsInstructions({ targetPath: target }));
+      return { enabledNow: false };
+    }
+    const shouldWrite = await confirm(`Enable OpenCode background subagents in ${target}?`, true);
+    if (!shouldWrite) {
+      printInfo("Skipped background subagents shell configuration.");
+      console.log(manualBackgroundSubagentsInstructions({ targetPath: target }));
+      return { enabledNow: false };
+    }
+  }
+  try {
+    writeBackgroundSubagentsBlock(target);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    printError(`Could not write background subagents shell config: ${message}`);
+    printInfo("Add the setting manually instead:");
+    console.log(manualBackgroundSubagentsInstructions({ targetPath: target }));
+    return { enabledNow: false };
+  }
+  printSuccess(`Background subagents enabled ${SYMBOLS.arrow} ${DIM}${target}${RESET}`);
+  return { enabledNow: false, configuredTarget: target };
+}
 function handleStepResult(result, successMsg) {
   if (!result.success) {
     printError(`Failed: ${result.error}`);
@@ -1529,7 +1722,7 @@ async function runInstall(config) {
   const detected = detectCurrentConfig();
   const isUpdate = detected.isInstalled;
   printHeader(isUpdate);
-  let totalSteps = 6;
+  let totalSteps = 7;
   if (config.installCustomSkills)
     totalSteps += 1;
   totalSteps += 1;
@@ -1590,6 +1783,8 @@ async function runInstall(config) {
     if (!handleStepResult(lspResult, "LSP enabled"))
       return 1;
   }
+  printStep(step++, totalSteps, "Configuring OpenCode background subagents...");
+  const backgroundSubagents = await configureBackgroundSubagents(config);
   printStep(step++, totalSteps, "Writing oh-my-opencode-slim configuration...");
   if (config.dryRun) {
     const liteConfig = generateLiteConfig(config);
@@ -1599,7 +1794,7 @@ ${JSON.stringify(liteConfig, null, 2)}
 `);
   } else {
     const configPath2 = getExistingLiteConfigPath();
-    const configExists = existsSync5(configPath2);
+    const configExists = existsSync6(configPath2);
     if (configExists && !config.reset) {
       printInfo(`Configuration already exists at ${configPath2}. Use --reset to overwrite.`);
     } else {
@@ -1646,7 +1841,15 @@ ${JSON.stringify(liteConfig, null, 2)}
   console.log(`     ${BLUE}${configPath}${RESET}`);
   console.log();
   console.log("  4. Start OpenCode:");
-  console.log(`     ${BLUE}$ opencode${RESET}`);
+  if (backgroundSubagents.enabledNow) {
+    console.log(`     ${BLUE}$ opencode${RESET}`);
+  } else if (backgroundSubagents.configuredTarget) {
+    console.log(`     ${BLUE}$ source ${backgroundSubagents.configuredTarget}${RESET}`);
+    console.log(`     ${BLUE}$ opencode${RESET}`);
+    console.log(`     ${DIM}Or restart your terminal before running opencode.${RESET}`);
+  } else {
+    console.log(`     ${BLUE}$ OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode${RESET}`);
+  }
   console.log();
   console.log("  5. Verify the agents are responding:");
   console.log(`     ${BLUE}> ping all agents${RESET}`);
@@ -1668,7 +1871,9 @@ async function install(args) {
     preset: args.preset,
     promptForStar: args.tui,
     dryRun: args.dryRun,
-    reset: args.reset ?? false
+    reset: args.reset ?? false,
+    backgroundSubagents: args.backgroundSubagents ?? "no",
+    backgroundSubagentsTarget: args.backgroundSubagentsTarget
   };
   return runInstall(config);
 }
@@ -1700,6 +1905,15 @@ function parseArgs(args) {
         process.exit(1);
       }
       result.preset = preset;
+    } else if (arg.startsWith("--background-subagents=")) {
+      const mode = arg.split("=")[1];
+      if (!["ask", "yes", "no"].includes(mode)) {
+        console.error("Unsupported --background-subagents value: use ask, yes, or no");
+        process.exit(1);
+      }
+      result.backgroundSubagents = mode;
+    } else if (arg.startsWith("--background-subagents-target=")) {
+      result.backgroundSubagentsTarget = arg.split("=")[1];
     } else if (arg === "--dry-run") {
       result.dryRun = true;
     } else if (arg === "--reset") {
@@ -1709,6 +1923,7 @@ function parseArgs(args) {
       process.exit(0);
     }
   }
+  result.backgroundSubagents ??= result.tui && process.stdin.isTTY ? "ask" : "no";
   return result;
 }
 function printHelp() {
@@ -1722,6 +1937,11 @@ Usage:
 Options:
   --skills=yes|no        Install bundled skills (default: yes)
   --preset=<name>        Active generated config preset (default: openai)
+  --background-subagents=ask|yes|no
+                         Persist required OpenCode background subagent env
+                         (default: ask in interactive TTY, otherwise no)
+  --background-subagents-target=<path>
+                         Shell startup file to update
   --no-tui               Non-interactive mode
   --dry-run              Simulate install without writing files
   --reset                Force overwrite of existing configuration
@@ -1739,6 +1959,7 @@ For the full config reference, see docs/configuration.md.
 Examples:
   bunx oh-my-opencode-slim install
   bunx oh-my-opencode-slim install --no-tui --skills=yes
+  bunx oh-my-opencode-slim install --background-subagents=yes
   bunx oh-my-opencode-slim install --preset=opencode-go
   bunx oh-my-opencode-slim install --reset
   bunx oh-my-opencode-slim doctor
@@ -1764,7 +1985,12 @@ async function main() {
     process.exit(1);
   }
 }
-main().catch((err) => {
-  console.error("Fatal error:", err);
-  process.exit(1);
-});
+if (__require.main == __require.module) {
+  main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+  });
+}
+export {
+  parseArgs
+};