release: v3.1.0

- Add column-based splittable calculation (getColumnCount, getColumnWidth)
- New decision tree: splittable → split, k=1 eviction → close+spawn, else → replace
- Add 'replace' action type using tmux respawn-pane (preserves layout)
- Replace oldest pane in-place instead of closing all panes when unsplittable
- Prevents scenario where all agent panes get closed leaving only 1

.github/workflows/ci.yml

@@ -4,13 +4,32 @@ on:
   push:
     branches: [master, dev]
   pull_request:
-    branches: [dev]
+    branches: [master, dev]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
+  # Block PRs targeting master branch
+  block-master-pr:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Check PR target branch
+        run: |
+          if [ "${{ github.base_ref }}" = "master" ]; then
+            echo "::error::PRs to master branch are not allowed. Please target the 'dev' branch instead."
+            echo ""
+            echo "PULL REQUESTS TO MASTER ARE BLOCKED"
+            echo ""
+            echo "All PRs must target the 'dev' branch."
+            echo "Please close this PR and create a new one targeting 'dev'."
+            exit 1
+          else
+            echo "PR targets '${{ github.base_ref }}' branch - OK"
+          fi
+
   test:
     runs-on: ubuntu-latest
     steps:

AGENTS.md

@@ -1,12 +1,24 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2026-01-25T13:10:00+09:00
-**Commit:** 043b1a33
+**Generated:** 2026-01-26T14:50:00+09:00
+**Commit:** 9d66b807
 **Branch:** dev
 
+---
+
+## **IMPORTANT: PULL REQUEST TARGET BRANCH**
+
+> **ALL PULL REQUESTS MUST TARGET THE `dev` BRANCH.**
+>
+> **DO NOT CREATE PULL REQUESTS TARGETING `master` BRANCH.**
+>
+> PRs to `master` will be automatically rejected by CI.
+
+---
+
 ## OVERVIEW
 
-OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3 Flash, Grok Code, GLM-4.7). 31 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, full Claude Code compatibility. "oh-my-zsh" for OpenCode.
+OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3 Flash, Grok Code). 32 lifecycle hooks, 20+ tools (LSP, AST-Grep, delegation), 10 specialized agents, full Claude Code compatibility. "oh-my-zsh" for OpenCode.
 
 ## STRUCTURE
 
@@ -14,14 +26,14 @@ OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemi
 oh-my-opencode/
 ├── src/
 │   ├── agents/        # 10 AI agents - see src/agents/AGENTS.md
-│   ├── hooks/         # 31 lifecycle hooks - see src/hooks/AGENTS.md
+│   ├── hooks/         # 32 lifecycle hooks - see src/hooks/AGENTS.md
 │   ├── tools/         # 20+ tools - see src/tools/AGENTS.md
 │   ├── features/      # Background agents, Claude Code compat - see src/features/AGENTS.md
-│   ├── shared/        # 50 cross-cutting utilities - see src/shared/AGENTS.md
+│   ├── shared/        # 55 cross-cutting utilities - see src/shared/AGENTS.md
 │   ├── cli/           # CLI installer, doctor - see src/cli/AGENTS.md
 │   ├── mcp/           # Built-in MCPs - see src/mcp/AGENTS.md
 │   ├── config/        # Zod schema, TypeScript types
-│   └── index.ts       # Main plugin entry (601 lines)
+│   └── index.ts       # Main plugin entry (672 lines)
 ├── script/            # build-schema.ts, build-binaries.ts
 ├── packages/          # 7 platform-specific binaries
 └── dist/              # Build output (ESM + .d.ts)
@@ -38,8 +50,8 @@ oh-my-opencode/
 | Add skill | `src/features/builtin-skills/` | Create dir with SKILL.md |
 | Add command | `src/features/builtin-commands/` | Add template + register in commands.ts |
 | Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` |
-| Background agents | `src/features/background-agent/` | manager.ts (1335 lines) |
-| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (773 lines) |
+| Background agents | `src/features/background-agent/` | manager.ts (1377 lines) |
+| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (752 lines) |
 
 ## TDD (Test-Driven Development)
 
@@ -51,8 +63,8 @@ oh-my-opencode/
 **Rules:**
 - NEVER write implementation before test
 - NEVER delete failing tests - fix the code
-- Test file: `*.test.ts` alongside source
-- BDD comments: `#given`, `#when`, `#then`
+- Test file: `*.test.ts` alongside source (100 test files)
+- BDD comments: `//#given`, `//#when`, `//#then`
 
 ## CONVENTIONS
 
@@ -61,7 +73,7 @@ oh-my-opencode/
 - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
 - **Exports**: Barrel pattern via index.ts
 - **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories
-- **Testing**: BDD comments, 95 test files
+- **Testing**: BDD comments, 100 test files
 - **Temperature**: 0.1 for code agents, max 0.3
 
 ## ANTI-PATTERNS
@@ -100,7 +112,7 @@ oh-my-opencode/
 bun run typecheck      # Type check
 bun run build          # ESM + declarations + schema
 bun run rebuild        # Clean + Build
-bun test               # 95 test files
+bun test               # 100 test files
 ```
 
 ## DEPLOYMENT
@@ -114,16 +126,14 @@ bun test               # 95 test files
 
 | File | Lines | Description |
 |------|-------|-------------|
-| `src/features/background-agent/manager.ts` | 1335 | Task lifecycle, concurrency |
-| `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions |
+| `src/features/builtin-skills/skills.ts` | 1729 | Skill definitions |
+| `src/features/background-agent/manager.ts` | 1377 | Task lifecycle, concurrency |
 | `src/agents/prometheus-prompt.ts` | 1196 | Planning agent |
-| `src/tools/delegate-task/tools.ts` | 1039 | Category-based delegation |
-| `src/hooks/atlas/index.ts` | 773 | Orchestrator hook |
+| `src/tools/delegate-task/tools.ts` | 1070 | Category-based delegation |
+| `src/hooks/atlas/index.ts` | 752 | Orchestrator hook |
 | `src/cli/config-manager.ts` | 664 | JSONC config parsing |
+| `src/index.ts` | 672 | Main plugin entry |
 | `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactor command template |
-| `src/index.ts` | 601 | Main plugin entry |
-| `src/tools/lsp/client.ts` | 596 | LSP JSON-RPC client |
-| `src/agents/atlas.ts` | 572 | Atlas orchestrator agent |
 
 ## MCP ARCHITECTURE
 

assets/oh-my-opencode.schema.json

@@ -38,6 +38,7 @@
         "type": "string",
         "enum": [
           "playwright",
+          "agent-browser",
           "frontend-ui-ux",
           "git-master"
         ]
@@ -70,12 +71,14 @@
           "interactive-bash-session",
           "thinking-block-validator",
           "ralph-loop",
+          "category-skill-reminder",
           "compaction-context-injector",
           "claude-code-hooks",
           "auto-slash-command",
           "edit-error-recovery",
           "delegate-task-retry",
           "prometheus-md-only",
+          "sisyphus-junior-notepad",
           "start-work",
           "atlas"
         ]
@@ -2171,6 +2174,55 @@
           "type": "boolean"
         }
       }
+    },
+    "browser_automation_engine": {
+      "type": "object",
+      "properties": {
+        "provider": {
+          "default": "playwright",
+          "type": "string",
+          "enum": [
+            "playwright",
+            "agent-browser"
+          ]
+        }
+      }
+    },
+    "tmux": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "layout": {
+          "default": "main-vertical",
+          "type": "string",
+          "enum": [
+            "main-horizontal",
+            "main-vertical",
+            "tiled",
+            "even-horizontal",
+            "even-vertical"
+          ]
+        },
+        "main_pane_size": {
+          "default": 60,
+          "type": "number",
+          "minimum": 20,
+          "maximum": 80
+        },
+        "main_pane_min_width": {
+          "default": 120,
+          "type": "number",
+          "minimum": 40
+        },
+        "agent_pane_min_width": {
+          "default": 40,
+          "type": "number",
+          "minimum": 20
+        }
+      }
     }
   }
 }

bun.lock

@@ -27,13 +27,13 @@
         "typescript": "^5.7.3",
       },
       "optionalDependencies": {
-        "oh-my-opencode-darwin-arm64": "3.0.0",
-        "oh-my-opencode-darwin-x64": "3.0.0",
-        "oh-my-opencode-linux-arm64": "3.0.0",
-        "oh-my-opencode-linux-arm64-musl": "3.0.0",
-        "oh-my-opencode-linux-x64": "3.0.0",
-        "oh-my-opencode-linux-x64-musl": "3.0.0",
-        "oh-my-opencode-windows-x64": "3.0.0",
+        "oh-my-opencode-darwin-arm64": "3.0.1",
+        "oh-my-opencode-darwin-x64": "3.0.1",
+        "oh-my-opencode-linux-arm64": "3.0.1",
+        "oh-my-opencode-linux-arm64-musl": "3.0.1",
+        "oh-my-opencode-linux-x64": "3.0.1",
+        "oh-my-opencode-linux-x64-musl": "3.0.1",
+        "oh-my-opencode-windows-x64": "3.0.1",
       },
     },
   },
@@ -225,19 +225,19 @@
 
     "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
 
-    "oh-my-opencode-darwin-arm64": ["oh-my-opencode-darwin-arm64@3.0.0", "", { "os": "darwin", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-zelvb7qz5GsS+Dhyz9rACZrkUMtWbAZGijiHSQqmRcjlN/sRPNhXtsL55VheDjlPM3VP+t3+psv+se0WA/aw5w=="],
+    "oh-my-opencode-darwin-arm64": ["oh-my-opencode-darwin-arm64@3.0.1", "", { "os": "darwin", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-LRcLVi6DsmGh3ICFeN4yVJ0KinvCM5jotd2z7tZQ74n0sziHO7grjK1CmJaPV9eCv0clatoK5xfFCeEJ3FvXYg=="],
 
-    "oh-my-opencode-darwin-x64": ["oh-my-opencode-darwin-x64@3.0.0", "", { "os": "darwin", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-dRMD1U5zIrb6BsiKQJZtAFtuD8clAQquZyU2LajMoFTHBNhcBDIgsaBBwvMBIq7dTe8rnFq91ExiFA8OfdrzBA=="],
+    "oh-my-opencode-darwin-x64": ["oh-my-opencode-darwin-x64@3.0.1", "", { "os": "darwin", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-ZaC0ZBe5M2f2aMncNsAMu9IZ3MjSPfNVcfUTCgJkp03db8lLPsajgjeG3556Er72hxignDPsEbrLkJBNlsDbAA=="],
 
-    "oh-my-opencode-linux-arm64": ["oh-my-opencode-linux-arm64@3.0.0", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-Wx6Cx2Nu2T69mfZa3FQ3gk0OFONvMh48rMVYK0Cp8VX5W4Zb/GZgTUFmZlYsApyxqP+7J9m18skd46qPOhzuEQ=="],
+    "oh-my-opencode-linux-arm64": ["oh-my-opencode-linux-arm64@3.0.1", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-pcOvV6Y2GSwKr0exDndeB2BtFt297XhJFQgrq1cbeEJawoRONDRp7LNSpjwILSQpQ7YkkYnO2bIczBmxI5llNA=="],
 
-    "oh-my-opencode-linux-arm64-musl": ["oh-my-opencode-linux-arm64-musl@3.0.0", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-mfOlptgLoXLVuhFRcXgZU7BYGuL1axZOMOOjONgncNzOp/BQYU5B9BRFihBUXdDsWGmeMiLowrYGBhVpSv3NlA=="],
+    "oh-my-opencode-linux-arm64-musl": ["oh-my-opencode-linux-arm64-musl@3.0.1", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-7kXKaVbgFnOMSaw+j4JbZNs7O7mkvCekcfWPwh/9I/0WD21/n4PbAGl01ePhRoQh+u9MC6t8FH046hEjL2sk1g=="],
 
-    "oh-my-opencode-linux-x64": ["oh-my-opencode-linux-x64@3.0.0", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-vVjshfaz0UC9NrGD9FfjlYK5NvckIW0sZaE/wRv/LKjrukHFH1jJpJa5KKXxBWLsEJjt6ooJRguXXxtfNXpAWw=="],
+    "oh-my-opencode-linux-x64": ["oh-my-opencode-linux-x64@3.0.1", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-1BOV1EnKa5BErhZmWiddnbriHwm1KFrPr+0BUCDdFX/d/hrMAJTo1733zaEnvKuXzvrdHSp/VznXheeUI1VjkA=="],
 
-    "oh-my-opencode-linux-x64-musl": ["oh-my-opencode-linux-x64-musl@3.0.0", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-N6cNJ7+Dj0a5dWqPf6OKfB39o8HWw5HQ3hB4omgYqc6Gzo6nChA4KIiVefEC3+tIL98x4XvMeD7OU+UYgwxHnQ=="],
+    "oh-my-opencode-linux-x64-musl": ["oh-my-opencode-linux-x64-musl@3.0.1", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-ASyTVatvU1nNJ0mk9o+A/GjybT5vOdgU172ystzCsnQ+12Mnv68GgaeMu/UFJgJNaZmKdhyUAP9XhnOKvEDBGQ=="],
 
-    "oh-my-opencode-windows-x64": ["oh-my-opencode-windows-x64@3.0.0", "", { "os": "win32", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode.exe" } }, "sha512-TaC0hiHpnsS42GWTVUKoTwCb+QzNLBlQtTkIQ0PjlkDYFjlEC2LuR2FFcscik055PRRIGishyB9A1n/8XAgcvA=="],
+    "oh-my-opencode-windows-x64": ["oh-my-opencode-windows-x64@3.0.1", "", { "os": "win32", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode.exe" } }, "sha512-QIuA564mVpwzCprhhAoyd8TSw0Rt2VM6M9y7H0fOoC/UjXuU+d7wIuUNuqUUMVaUnMedkctTZop0X0i2Q+Bvhg=="],
 
     "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
 

docs/configurations.md

@@ -159,7 +159,7 @@ Available agents: `oracle`, `librarian`, `explore`, `multimodal-looker`
 
 Oh My OpenCode includes built-in skills that provide additional capabilities:
 
-- **playwright**: Browser automation with Playwright MCP. Use for web scraping, testing, screenshots, and browser interactions.
+- **playwright** (default) / **agent-browser**: Browser automation for web scraping, testing, screenshots, and browser interactions. See [Browser Automation](#browser-automation) for switching between providers.
 - **git-master**: Git expert for atomic commits, rebase/squash, and history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with `delegate_task(category='quick', load_skills=['git-master'], ...)` to save context.
 
 Disable built-in skills via `disabled_skills` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
@@ -170,7 +170,54 @@ Disable built-in skills via `disabled_skills` in `~/.config/opencode/oh-my-openc
 }
 ```
 
-Available built-in skills: `playwright`, `git-master`
+Available built-in skills: `playwright`, `agent-browser`, `git-master`
+
+## Browser Automation
+
+Choose between two browser automation providers:
+
+| Provider | Interface | Features | Installation |
+|----------|-----------|----------|--------------|
+| **playwright** (default) | MCP tools | Playwright MCP server with structured tool calls | Auto-installed via npx |
+| **agent-browser** | Bash CLI | Vercel's CLI with session management, parallel browsers | Requires `bun add -g agent-browser` |
+
+**Switch providers** via `browser_automation_engine` in `oh-my-opencode.json`:
+
+```json
+{
+  "browser_automation_engine": {
+    "provider": "agent-browser"
+  }
+}
+```
+
+### Playwright (Default)
+
+Uses the official Playwright MCP server (`@playwright/mcp`). Browser automation happens through structured MCP tool calls.
+
+### agent-browser
+
+Uses [Vercel's agent-browser CLI](https://github.com/vercel-labs/agent-browser). Key advantages:
+- **Session management**: Run multiple isolated browser instances with `--session` flag
+- **Persistent profiles**: Keep browser state across restarts with `--profile`
+- **Snapshot-based workflow**: Get element refs via `snapshot -i`, interact with `@e1`, `@e2`, etc.
+- **CLI-first**: All commands via Bash - great for scripting
+
+**Installation required**:
+```bash
+bun add -g agent-browser
+agent-browser install  # Download Chromium
+```
+
+**Example workflow**:
+```bash
+agent-browser open https://example.com
+agent-browser snapshot -i  # Get interactive elements with refs
+agent-browser fill @e1 "user@example.com"
+agent-browser click @e2
+agent-browser screenshot result.png
+agent-browser close
+```
 
 ## Git Master
 

docs/features.md

@@ -78,11 +78,15 @@ Skills provide specialized workflows with embedded MCP servers and detailed inst
 | **frontend-ui-ux** | UI/UX tasks, styling | Designer-turned-developer persona. Crafts stunning UI/UX even without design mockups. Emphasizes bold aesthetic direction, distinctive typography, cohesive color palettes. |
 | **git-master** | commit, rebase, squash, blame | MUST USE for ANY git operations. Atomic commits with automatic splitting, rebase/squash workflows, history search (blame, bisect, log -S). |
 
-### Skill: playwright
+### Skill: Browser Automation (playwright / agent-browser)
 
 **Trigger**: Any browser-related request
 
-Provides browser automation via Playwright MCP server:
+Oh-My-OpenCode provides two browser automation providers, configurable via `browser_automation_engine.provider`:
+
+#### Option 1: Playwright MCP (Default)
+
+The default provider uses Playwright MCP server:
 
 ```yaml
 mcp:
@@ -91,18 +95,41 @@ mcp:
     args: ["@playwright/mcp@latest"]
 ```
 
-**Capabilities**:
+**Usage**:
+```
+/playwright Navigate to example.com and take a screenshot
+```
+
+#### Option 2: Agent Browser CLI (Vercel)
+
+Alternative provider using [Vercel's agent-browser CLI](https://github.com/vercel-labs/agent-browser):
+
+```json
+{
+  "browser_automation_engine": {
+    "provider": "agent-browser"
+  }
+}
+```
+
+**Requires installation**:
+```bash
+bun add -g agent-browser
+```
+
+**Usage**:
+```
+Use agent-browser to navigate to example.com and extract the main heading
+```
+
+#### Capabilities (Both Providers)
+
 - Navigate and interact with web pages
 - Take screenshots and PDFs
 - Fill forms and click elements
 - Wait for network requests
 - Scrape content
 
-**Usage**:
-```
-/playwright Navigate to example.com and take a screenshot
-```
-
 ### Skill: frontend-ui-ux
 
 **Trigger**: UI design tasks, visual changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -73,13 +73,13 @@
     "typescript": "^5.7.3"
   },
   "optionalDependencies": {
-    "oh-my-opencode-darwin-arm64": "3.0.1",
-    "oh-my-opencode-darwin-x64": "3.0.1",
-    "oh-my-opencode-linux-arm64": "3.0.1",
-    "oh-my-opencode-linux-arm64-musl": "3.0.1",
-    "oh-my-opencode-linux-x64": "3.0.1",
-    "oh-my-opencode-linux-x64-musl": "3.0.1",
-    "oh-my-opencode-windows-x64": "3.0.1"
+    "oh-my-opencode-darwin-arm64": "3.1.0",
+    "oh-my-opencode-darwin-x64": "3.1.0",
+    "oh-my-opencode-linux-arm64": "3.1.0",
+    "oh-my-opencode-linux-arm64-musl": "3.1.0",
+    "oh-my-opencode-linux-x64": "3.1.0",
+    "oh-my-opencode-linux-x64-musl": "3.1.0",
+    "oh-my-opencode-windows-x64": "3.1.0"
   },
   "trustedDependencies": [
     "@ast-grep/cli",

packages/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-darwin-arm64",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Platform-specific binary for oh-my-opencode (darwin-arm64)",
   "license": "MIT",
   "repository": {

packages/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-darwin-x64",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Platform-specific binary for oh-my-opencode (darwin-x64)",
   "license": "MIT",
   "repository": {

packages/linux-arm64-musl/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-arm64-musl",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-arm64-musl)",
   "license": "MIT",
   "repository": {

packages/linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-arm64",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-arm64)",
   "license": "MIT",
   "repository": {

packages/linux-x64-musl/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-x64-musl",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-x64-musl)",
   "license": "MIT",
   "repository": {

packages/linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-x64",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-x64)",
   "license": "MIT",
   "repository": {

packages/windows-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-windows-x64",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Platform-specific binary for oh-my-opencode (windows-x64)",
   "license": "MIT",
   "repository": {

src/agents/AGENTS.md

@@ -1,31 +1,28 @@
 # AGENTS KNOWLEDGE BASE
 
 ## OVERVIEW
-
 10 AI agents for multi-model orchestration. Sisyphus (primary), Atlas (orchestrator), oracle, librarian, explore, multimodal-looker, Prometheus, Metis, Momus, Sisyphus-Junior.
 
 ## STRUCTURE
-
 ```
 agents/
-├── atlas.ts                    # Master Orchestrator (572 lines)
-├── sisyphus.ts                 # Main prompt (450 lines)
-├── sisyphus-junior.ts          # Delegated task executor (135 lines)
-├── dynamic-agent-prompt-builder.ts  # Dynamic prompt generation (359 lines)
+├── atlas.ts                    # Master Orchestrator (holds todo list)
+├── sisyphus.ts                 # Main prompt (SF Bay Area engineer identity)
+├── sisyphus-junior.ts          # Delegated task executor (category-spawned)
 ├── oracle.ts                   # Strategic advisor (GPT-5.2)
-├── librarian.ts                # Multi-repo research (326 lines)
-├── explore.ts                  # Fast grep (Grok Code)
+├── librarian.ts                # Multi-repo research (GitHub CLI, Context7)
+├── explore.ts                  # Fast contextual grep (Grok Code)
 ├── multimodal-looker.ts        # Media analyzer (Gemini 3 Flash)
-├── prometheus-prompt.ts        # Planning (1196 lines)
-├── metis.ts                    # Plan consultant (315 lines)
-├── momus.ts                    # Plan reviewer (444 lines)
+├── prometheus-prompt.ts        # Planning (Interview/Consultant mode, 1196 lines)
+├── metis.ts                    # Pre-planning analysis (Gap detection)
+├── momus.ts                    # Plan reviewer (Ruthless fault-finding)
+├── dynamic-agent-prompt-builder.ts  # Dynamic prompt generation
 ├── types.ts                    # AgentModelConfig, AgentPromptMetadata
 ├── utils.ts                    # createBuiltinAgents(), resolveModelWithFallback()
 └── index.ts                    # builtinAgents export
 ```
 
 ## AGENT MODELS
-
 | Agent | Model | Temp | Purpose |
 |-------|-------|------|---------|
 | Sisyphus | anthropic/claude-opus-4-5 | 0.1 | Primary orchestrator |
@@ -40,14 +37,12 @@ agents/
 | Sisyphus-Junior | anthropic/claude-sonnet-4-5 | 0.1 | Category-spawned executor |
 
 ## HOW TO ADD
-
-1. Create `src/agents/my-agent.ts` exporting factory + metadata
-2. Add to `agentSources` in `src/agents/utils.ts`
-3. Update `AgentNameSchema` in `src/config/schema.ts`
-4. Register in `src/index.ts` initialization
+1. Create `src/agents/my-agent.ts` exporting factory + metadata.
+2. Add to `agentSources` in `src/agents/utils.ts`.
+3. Update `AgentNameSchema` in `src/config/schema.ts`.
+4. Register in `src/index.ts` initialization.
 
 ## TOOL RESTRICTIONS
-
 | Agent | Denied Tools |
 |-------|-------------|
 | oracle | write, edit, task, delegate_task |
@@ -57,14 +52,13 @@ agents/
 | Sisyphus-Junior | task, delegate_task |
 
 ## PATTERNS
-
-- **Factory**: `createXXXAgent(model?: string): AgentConfig`
-- **Metadata**: `XXX_PROMPT_METADATA` with category, cost, triggers
-- **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`
-- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas
+- **Factory**: `createXXXAgent(model: string): AgentConfig`
+- **Metadata**: `XXX_PROMPT_METADATA` with category, cost, triggers.
+- **Tool restrictions**: `createAgentToolRestrictions(tools)` or `createAgentToolAllowlist(tools)`.
+- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus, Atlas.
 
 ## ANTI-PATTERNS
-
-- **Trust reports**: NEVER trust "I'm done" - verify outputs
-- **High temp**: Don't use >0.3 for code agents
-- **Sequential calls**: Use `delegate_task` with `run_in_background`
+- **Trust reports**: NEVER trust "I'm done" - verify outputs.
+- **High temp**: Don't use >0.3 for code agents.
+- **Sequential calls**: Use `delegate_task` with `run_in_background` for exploration.
+- **Prometheus writing code**: Planner only - never implements.

src/agents/sisyphus-junior.ts

@@ -20,32 +20,6 @@ ALLOWED: call_omo_agent - You CAN spawn explore/librarian agents for research.
 You work ALONE for implementation. No delegation of implementation tasks.
 </Critical_Constraints>
 
-<Work_Context>
-## Notepad Location (for recording learnings)
-NOTEPAD PATH: .sisyphus/notepads/{plan-name}/
-- learnings.md: Record patterns, conventions, successful approaches
-- issues.md: Record problems, blockers, gotchas encountered
-- decisions.md: Record architectural choices and rationales
-- problems.md: Record unresolved issues, technical debt
-
-You SHOULD append findings to notepad files after completing work.
-IMPORTANT: Always APPEND to notepad files - never overwrite or use Edit tool.
-
-## Plan Location (READ ONLY)
-PLAN PATH: .sisyphus/plans/{plan-name}.md
-
-CRITICAL RULE: NEVER MODIFY THE PLAN FILE
-
-The plan file (.sisyphus/plans/*.md) is SACRED and READ-ONLY.
-- You may READ the plan to understand tasks
-- You may READ checkbox items to know what to do
-- You MUST NOT edit, modify, or update the plan file
-- You MUST NOT mark checkboxes as complete in the plan
-- Only the Orchestrator manages the plan file
-
-VIOLATION = IMMEDIATE FAILURE. The Orchestrator tracks plan state.
-</Work_Context>
-
 <Todo_Discipline>
 TODO OBSESSION (NON-NEGOTIABLE):
 - 2+ steps → todowrite FIRST, atomic breakdown

src/agents/utils.test.ts

@@ -1,6 +1,7 @@
-import { describe, test, expect } from "bun:test"
+import { describe, test, expect, beforeEach } from "bun:test"
 import { createBuiltinAgents } from "./utils"
 import type { AgentConfig } from "@opencode-ai/sdk"
+import { clearSkillCache } from "../features/opencode-skill-loader/skill-content"
 
 const TEST_DEFAULT_MODEL = "anthropic/claude-opus-4-5"
 
@@ -109,6 +110,10 @@ describe("buildAgent with category and skills", () => {
   const { buildAgent } = require("./utils")
   const TEST_MODEL = "anthropic/claude-opus-4-5"
 
+  beforeEach(() => {
+    clearSkillCache()
+  })
+
   test("agent with category inherits category settings", () => {
     // #given - agent factory that sets category but no model
     const source = {
@@ -308,4 +313,42 @@ describe("buildAgent with category and skills", () => {
     // #then
     expect(agent.prompt).toBe("Base prompt")
   })
+
+  test("agent with agent-browser skill resolves when browserProvider is set", () => {
+    // #given
+    const source = {
+      "test-agent": () =>
+        ({
+          description: "Test agent",
+          skills: ["agent-browser"],
+          prompt: "Base prompt",
+        }) as AgentConfig,
+    }
+
+    // #when - browserProvider is "agent-browser"
+    const agent = buildAgent(source["test-agent"], TEST_MODEL, undefined, undefined, "agent-browser")
+
+    // #then - agent-browser skill content should be in prompt
+    expect(agent.prompt).toContain("agent-browser")
+    expect(agent.prompt).toContain("Base prompt")
+  })
+
+  test("agent with agent-browser skill NOT resolved when browserProvider not set", () => {
+    // #given
+    const source = {
+      "test-agent": () =>
+        ({
+          description: "Test agent",
+          skills: ["agent-browser"],
+          prompt: "Base prompt",
+        }) as AgentConfig,
+    }
+
+    // #when - no browserProvider (defaults to playwright)
+    const agent = buildAgent(source["test-agent"], TEST_MODEL)
+
+    // #then - agent-browser skill not found, only base prompt remains
+    expect(agent.prompt).toBe("Base prompt")
+    expect(agent.prompt).not.toContain("agent-browser open")
+  })
 })

src/agents/utils.ts

@@ -10,11 +10,12 @@ import { createMetisAgent } from "./metis"
 import { createAtlasAgent } from "./atlas"
 import { createMomusAgent } from "./momus"
 import type { AvailableAgent, AvailableCategory, AvailableSkill } from "./dynamic-agent-prompt-builder"
-import { deepMerge, fetchAvailableModels, resolveModelWithFallback, AGENT_MODEL_REQUIREMENTS, findCaseInsensitive, includesCaseInsensitive } from "../shared"
+import { deepMerge, fetchAvailableModels, resolveModelWithFallback, AGENT_MODEL_REQUIREMENTS, findCaseInsensitive, includesCaseInsensitive, readConnectedProvidersCache } from "../shared"
 import { DEFAULT_CATEGORIES, CATEGORY_DESCRIPTIONS } from "../tools/delegate-task/constants"
 import { resolveMultipleSkills } from "../features/opencode-skill-loader/skill-content"
 import { createBuiltinSkills } from "../features/builtin-skills"
 import type { LoadedSkill, SkillScope } from "../features/opencode-skill-loader/types"
+import type { BrowserAutomationProvider } from "../config/schema"
 
 type AgentSource = AgentFactory | AgentConfig
 
@@ -50,7 +51,8 @@ export function buildAgent(
   source: AgentSource,
   model: string,
   categories?: CategoriesConfig,
-  gitMasterConfig?: GitMasterConfig
+  gitMasterConfig?: GitMasterConfig,
+  browserProvider?: BrowserAutomationProvider
 ): AgentConfig {
   const base = isFactory(source) ? source(model) : source
   const categoryConfigs: Record<string, CategoryConfig> = categories
@@ -74,7 +76,7 @@ export function buildAgent(
   }
 
   if (agentWithCategory.skills?.length) {
-    const { resolved } = resolveMultipleSkills(agentWithCategory.skills, { gitMasterConfig })
+    const { resolved } = resolveMultipleSkills(agentWithCategory.skills, { gitMasterConfig, browserProvider })
     if (resolved.size > 0) {
       const skillContent = Array.from(resolved.values()).join("\n\n")
       base.prompt = skillContent + (base.prompt ? "\n\n" + base.prompt : "")
@@ -146,14 +148,17 @@ export async function createBuiltinAgents(
   categories?: CategoriesConfig,
   gitMasterConfig?: GitMasterConfig,
   discoveredSkills: LoadedSkill[] = [],
-  client?: any
+  client?: any,
+  browserProvider?: BrowserAutomationProvider
 ): Promise<Record<string, AgentConfig>> {
   if (!systemDefaultModel) {
     throw new Error("createBuiltinAgents requires systemDefaultModel")
   }
 
-  // Fetch available models at plugin init
-  const availableModels = client ? await fetchAvailableModels(client) : new Set<string>()
+  const connectedProviders = readConnectedProvidersCache()
+  const availableModels = client 
+    ? await fetchAvailableModels(client, { connectedProviders: connectedProviders ?? undefined }) 
+    : new Set<string>()
 
   const result: Record<string, AgentConfig> = {}
   const availableAgents: AvailableAgent[] = []
@@ -167,7 +172,7 @@ export async function createBuiltinAgents(
     description: categories?.[name]?.description ?? CATEGORY_DESCRIPTIONS[name] ?? "General tasks",
   }))
 
-  const builtinSkills = createBuiltinSkills()
+  const builtinSkills = createBuiltinSkills({ browserProvider })
   const builtinSkillNames = new Set(builtinSkills.map(s => s.name))
 
   const builtinAvailable: AvailableSkill[] = builtinSkills.map((skill) => ({
@@ -204,7 +209,7 @@ export async function createBuiltinAgents(
       systemDefaultModel,
     })
 
-    let config = buildAgent(source, model, mergedCategories, gitMasterConfig)
+    let config = buildAgent(source, model, mergedCategories, gitMasterConfig, browserProvider)
     
     // Apply variant from override or resolved fallback chain
     if (override?.variant) {

src/cli/AGENTS.md

@@ -8,7 +8,7 @@ CLI entry: `bunx oh-my-opencode`. Interactive installer, doctor diagnostics. Com
 
 ```
 cli/
-├── index.ts              # Commander.js entry
+├── index.ts              # Commander.js entry (4 commands)
 ├── install.ts            # Interactive TUI (520 lines)
 ├── config-manager.ts     # JSONC parsing (664 lines)
 ├── types.ts              # InstallArgs, InstallConfig
@@ -18,7 +18,7 @@ cli/
 │   ├── runner.ts         # Check orchestration
 │   ├── formatter.ts      # Colored output
 │   ├── constants.ts      # Check IDs, symbols
-│   ├── types.ts          # CheckResult, CheckDefinition
+│   ├── types.ts          # CheckResult, CheckDefinition (114 lines)
 │   └── checks/           # 14 checks, 21 files
 │       ├── version.ts    # OpenCode + plugin version
 │       ├── config.ts     # JSONC validity, Zod
@@ -38,36 +38,37 @@ cli/
 
 | Command | Purpose |
 |---------|---------|
-| `install` | Interactive setup |
-| `doctor` | 14 health checks |
-| `run` | Launch session |
-| `get-local-version` | Version check |
+| `install` | Interactive setup with provider selection |
+| `doctor` | 14 health checks for diagnostics |
+| `run` | Launch session with todo enforcement |
+| `get-local-version` | Version detection and update check |
 
-## DOCTOR CATEGORIES
+## DOCTOR CATEGORIES (14 Checks)
 
 | Category | Checks |
 |----------|--------|
 | installation | opencode, plugin |
-| configuration | config validity, Zod |
+| configuration | config validity, Zod, model-resolution |
 | authentication | anthropic, openai, google |
-| dependencies | ast-grep, comment-checker |
+| dependencies | ast-grep, comment-checker, gh-cli |
 | tools | LSP, MCP |
 | updates | version comparison |
 
 ## HOW TO ADD CHECK
 
 1. Create `src/cli/doctor/checks/my-check.ts`
-2. Export from `checks/index.ts`
-3. Add to `getAllCheckDefinitions()`
+2. Export `getXXXCheckDefinition()` factory returning `CheckDefinition`
+3. Add to `getAllCheckDefinitions()` in `checks/index.ts`
 
 ## TUI FRAMEWORK
 
-- **@clack/prompts**: `select()`, `spinner()`, `intro()`
-- **picocolors**: Terminal colors
-- **Symbols**: ✓ (pass), ✗ (fail), ⚠ (warn)
+- **@clack/prompts**: `select()`, `spinner()`, `intro()`, `outro()`
+- **picocolors**: Terminal colors for status and headers
+- **Symbols**: ✓ (pass), ✗ (fail), ⚠ (warn), ℹ (info)
 
 ## ANTI-PATTERNS
 
-- **Blocking in non-TTY**: Check `process.stdout.isTTY`
-- **Direct JSON.parse**: Use `parseJsonc()`
-- **Silent failures**: Return warn/fail in doctor
+- **Blocking in non-TTY**: Always check `process.stdout.isTTY`
+- **Direct JSON.parse**: Use `parseJsonc()` from shared utils
+- **Silent failures**: Return `warn` or `fail` in doctor instead of throwing
+- **Hardcoded paths**: Use `getOpenCodeConfigPaths()` from `config-manager.ts`

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

@@ -712,7 +712,7 @@ exports[`generateModelConfig fallback providers uses GitHub Copilot models when
       "model": "github-copilot/claude-sonnet-4.5",
     },
     "explore": {
-      "model": "opencode/gpt-5-nano",
+      "model": "github-copilot/gpt-5-mini",
     },
     "librarian": {
       "model": "github-copilot/claude-sonnet-4.5",
@@ -776,7 +776,7 @@ exports[`generateModelConfig fallback providers uses GitHub Copilot models with
       "model": "github-copilot/claude-sonnet-4.5",
     },
     "explore": {
-      "model": "opencode/gpt-5-nano",
+      "model": "github-copilot/gpt-5-mini",
     },
     "librarian": {
       "model": "github-copilot/claude-sonnet-4.5",
@@ -1022,7 +1022,7 @@ exports[`generateModelConfig mixed provider scenarios uses OpenAI + Copilot comb
       "model": "github-copilot/claude-sonnet-4.5",
     },
     "explore": {
-      "model": "opencode/gpt-5-nano",
+      "model": "github-copilot/gpt-5-mini",
     },
     "librarian": {
       "model": "github-copilot/claude-sonnet-4.5",

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

@@ -199,9 +199,11 @@ function buildDetailsArray(info: ModelResolutionInfo, available: AvailableModels
   details.push("═══ Available Models (from cache) ═══")
   details.push("")
   if (available.cacheExists) {
-    details.push(`  Providers: ${available.providers.length} (${available.providers.slice(0, 8).join(", ")}${available.providers.length > 8 ? "..." : ""})`)
+    details.push(`  Providers in cache: ${available.providers.length}`)
+    details.push(`  Sample: ${available.providers.slice(0, 6).join(", ")}${available.providers.length > 6 ? "..." : ""}`)
     details.push(`  Total models: ${available.modelCount}`)
     details.push(`  Cache: ~/.cache/opencode/models.json`)
+    details.push(`  ℹ Runtime: only connected providers used`)
     details.push(`  Refresh: opencode models --refresh`)
   } else {
     details.push("  ⚠ Cache not found. Run 'opencode' to populate.")

src/cli/model-fallback.test.ts

@@ -353,6 +353,17 @@ describe("generateModelConfig", () => {
       // #then explore should use gpt-5-nano (fallback)
       expect(result.agents?.explore?.model).toBe("opencode/gpt-5-nano")
     })
+
+    test("explore uses gpt-5-mini when only Copilot available", () => {
+      // #given only Copilot is available
+      const config = createConfig({ hasCopilot: true })
+
+      // #when generateModelConfig is called
+      const result = generateModelConfig(config)
+
+      // #then explore should use gpt-5-mini (Copilot fallback)
+      expect(result.agents?.explore?.model).toBe("github-copilot/gpt-5-mini")
+    })
   })
 
   describe("Sisyphus agent special cases", () => {

src/cli/model-fallback.ts

@@ -139,12 +139,14 @@ export function generateModelConfig(config: InstallConfig): GeneratedOmoConfig {
       continue
     }
 
-    // Special case: explore uses Claude haiku → OpenCode gpt-5-nano
+    // Special case: explore uses Claude haiku → GitHub Copilot gpt-5-mini → OpenCode gpt-5-nano
     if (role === "explore") {
       if (avail.native.claude) {
         agents[role] = { model: "anthropic/claude-haiku-4-5" }
       } else if (avail.opencodeZen) {
         agents[role] = { model: "opencode/claude-haiku-4-5" }
+      } else if (avail.copilot) {
+        agents[role] = { model: "github-copilot/gpt-5-mini" }
       } else {
         agents[role] = { model: "opencode/gpt-5-nano" }
       }

src/config/index.ts

@@ -9,6 +9,8 @@ export {
   SisyphusAgentConfigSchema,
   ExperimentalConfigSchema,
   RalphLoopConfigSchema,
+  TmuxConfigSchema,
+  TmuxLayoutSchema,
 } from "./schema"
 
 export type {
@@ -23,4 +25,6 @@ export type {
   ExperimentalConfig,
   DynamicContextPruningConfig,
   RalphLoopConfig,
+  TmuxConfig,
+  TmuxLayout,
 } from "./schema"

src/config/schema.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, test } from "bun:test"
-import { AgentOverrideConfigSchema, BuiltinCategoryNameSchema, CategoryConfigSchema, OhMyOpenCodeConfigSchema } from "./schema"
+import {
+  AgentOverrideConfigSchema,
+  BrowserAutomationConfigSchema,
+  BrowserAutomationProviderSchema,
+  BuiltinCategoryNameSchema,
+  CategoryConfigSchema,
+  OhMyOpenCodeConfigSchema,
+} from "./schema"
 
 describe("disabled_mcps schema", () => {
   test("should accept built-in MCP names", () => {
@@ -508,3 +515,94 @@ describe("Sisyphus-Junior agent override", () => {
     }
   })
 })
+
+describe("BrowserAutomationProviderSchema", () => {
+  test("accepts 'playwright' as valid provider", () => {
+    // #given
+    const input = "playwright"
+
+    // #when
+    const result = BrowserAutomationProviderSchema.safeParse(input)
+
+    // #then
+    expect(result.success).toBe(true)
+    expect(result.data).toBe("playwright")
+  })
+
+  test("accepts 'agent-browser' as valid provider", () => {
+    // #given
+    const input = "agent-browser"
+
+    // #when
+    const result = BrowserAutomationProviderSchema.safeParse(input)
+
+    // #then
+    expect(result.success).toBe(true)
+    expect(result.data).toBe("agent-browser")
+  })
+
+  test("rejects invalid provider", () => {
+    // #given
+    const input = "invalid-provider"
+
+    // #when
+    const result = BrowserAutomationProviderSchema.safeParse(input)
+
+    // #then
+    expect(result.success).toBe(false)
+  })
+})
+
+describe("BrowserAutomationConfigSchema", () => {
+  test("defaults provider to 'playwright' when not specified", () => {
+    // #given
+    const input = {}
+
+    // #when
+    const result = BrowserAutomationConfigSchema.parse(input)
+
+    // #then
+    expect(result.provider).toBe("playwright")
+  })
+
+  test("accepts agent-browser provider", () => {
+    // #given
+    const input = { provider: "agent-browser" }
+
+    // #when
+    const result = BrowserAutomationConfigSchema.parse(input)
+
+    // #then
+    expect(result.provider).toBe("agent-browser")
+  })
+})
+
+describe("OhMyOpenCodeConfigSchema - browser_automation_engine", () => {
+  test("accepts browser_automation_engine config", () => {
+    // #given
+    const input = {
+      browser_automation_engine: {
+        provider: "agent-browser",
+      },
+    }
+
+    // #when
+    const result = OhMyOpenCodeConfigSchema.safeParse(input)
+
+    // #then
+    expect(result.success).toBe(true)
+    expect(result.data?.browser_automation_engine?.provider).toBe("agent-browser")
+  })
+
+  test("accepts config without browser_automation_engine", () => {
+    // #given
+    const input = {}
+
+    // #when
+    const result = OhMyOpenCodeConfigSchema.safeParse(input)
+
+    // #then
+    expect(result.success).toBe(true)
+    expect(result.data?.browser_automation_engine).toBeUndefined()
+  })
+})

src/config/schema.ts

@@ -30,6 +30,7 @@ export const BuiltinAgentNameSchema = z.enum([
 
 export const BuiltinSkillNameSchema = z.enum([
   "playwright",
+  "agent-browser",
   "frontend-ui-ux",
   "git-master",
 ])
@@ -76,6 +77,7 @@ export const HookNameSchema = z.enum([
 
   "thinking-block-validator",
   "ralph-loop",
+  "category-skill-reminder",
 
   "compaction-context-injector",
   "claude-code-hooks",
@@ -83,6 +85,7 @@ export const HookNameSchema = z.enum([
   "edit-error-recovery",
   "delegate-task-retry",
   "prometheus-md-only",
+  "sisyphus-junior-notepad",
   "start-work",
   "atlas",
 ])
@@ -297,6 +300,32 @@ export const GitMasterConfigSchema = z.object({
   include_co_authored_by: z.boolean().default(true),
 })
 
+export const BrowserAutomationProviderSchema = z.enum(["playwright", "agent-browser"])
+
+export const BrowserAutomationConfigSchema = z.object({
+  /**
+   * Browser automation provider to use for the "playwright" skill.
+   * - "playwright": Uses Playwright MCP server (@playwright/mcp) - default
+   * - "agent-browser": Uses Vercel's agent-browser CLI (requires: bun add -g agent-browser)
+   */
+  provider: BrowserAutomationProviderSchema.default("playwright"),
+})
+
+export const TmuxLayoutSchema = z.enum([
+  'main-horizontal',  // main pane top, agent panes bottom stack
+  'main-vertical',    // main pane left, agent panes right stack (default)
+  'tiled',            // all panes same size grid
+  'even-horizontal',  // all panes horizontal row
+  'even-vertical',    // all panes vertical stack
+])
+
+export const TmuxConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  layout: TmuxLayoutSchema.default('main-vertical'),
+  main_pane_size: z.number().min(20).max(80).default(60),
+  main_pane_min_width: z.number().min(40).default(120),
+  agent_pane_min_width: z.number().min(20).default(40),
+})
 export const OhMyOpenCodeConfigSchema = z.object({
   $schema: z.string().optional(),
   disabled_mcps: z.array(AnyMcpNameSchema).optional(),
@@ -316,6 +345,8 @@ export const OhMyOpenCodeConfigSchema = z.object({
   background_task: BackgroundTaskConfigSchema.optional(),
   notification: NotificationConfigSchema.optional(),
   git_master: GitMasterConfigSchema.optional(),
+  browser_automation_engine: BrowserAutomationConfigSchema.optional(),
+  tmux: TmuxConfigSchema.optional(),
 })
 
 export type OhMyOpenCodeConfig = z.infer<typeof OhMyOpenCodeConfigSchema>
@@ -338,5 +369,9 @@ export type CategoryConfig = z.infer<typeof CategoryConfigSchema>
 export type CategoriesConfig = z.infer<typeof CategoriesConfigSchema>
 export type BuiltinCategoryName = z.infer<typeof BuiltinCategoryNameSchema>
 export type GitMasterConfig = z.infer<typeof GitMasterConfigSchema>
+export type BrowserAutomationProvider = z.infer<typeof BrowserAutomationProviderSchema>
+export type BrowserAutomationConfig = z.infer<typeof BrowserAutomationConfigSchema>
+export type TmuxConfig = z.infer<typeof TmuxConfigSchema>
+export type TmuxLayout = z.infer<typeof TmuxLayoutSchema>
 
 export { AnyMcpNameSchema, type AnyMcpName, McpNameSchema, type McpName } from "../mcp/types"

src/features/AGENTS.md

@@ -2,34 +2,31 @@
 
 ## OVERVIEW
 
-Core feature modules + Claude Code compatibility layer. Background agents, skill MCP, builtin skills/commands, 5 loaders.
+Core feature modules + Claude Code compatibility layer. Orchestrates background agents, skill MCPs, builtin skills/commands, and 16 feature modules.
 
 ## STRUCTURE
 
 ```
 features/
-├── background-agent/           # Task lifecycle (1335 lines)
+├── background-agent/           # Task lifecycle (1377 lines)
 │   ├── manager.ts              # Launch → poll → complete
-│   ├── concurrency.ts          # Per-provider limits
-│   └── types.ts                # BackgroundTask, LaunchInput
-├── skill-mcp-manager/          # MCP client lifecycle (520 lines)
-│   ├── manager.ts              # Lazy loading, cleanup
-│   └── types.ts                # SkillMcpConfig
-├── builtin-skills/             # Playwright, git-master, frontend-ui-ux
-│   └── skills.ts               # 1203 lines
-├── builtin-commands/           # ralph-loop, refactor, init-deep, start-work, remove-deadcode
-│   ├── commands.ts             # Command registry
-│   └── templates/              # Command templates (4 files)
+│   └── concurrency.ts          # Per-provider limits
+├── builtin-skills/             # Core skills (1729 lines)
+│   └── skills.ts               # agent-browser, dev-browser, frontend-ui-ux, git-master, typescript-programmer
+├── builtin-commands/           # ralph-loop, refactor, ulw-loop, init-deep, start-work, cancel-ralph
 ├── claude-code-agent-loader/   # ~/.claude/agents/*.md
 ├── claude-code-command-loader/ # ~/.claude/commands/*.md
-├── claude-code-mcp-loader/     # .mcp.json
+├── claude-code-mcp-loader/     # .mcp.json with ${VAR} expansion
 ├── claude-code-plugin-loader/  # installed_plugins.json
 ├── claude-code-session-state/  # Session persistence
 ├── opencode-skill-loader/      # Skills from 6 directories
 ├── context-injector/           # AGENTS.md/README.md injection
 ├── boulder-state/              # Todo state persistence
 ├── hook-message-injector/      # Message injection
-└── task-toast-manager/         # Background task notifications
+├── task-toast-manager/         # Background task notifications
+├── skill-mcp-manager/          # MCP client lifecycle (520 lines)
+├── tmux-subagent/              # Tmux session management
+└── ... (16 modules total)
 ```
 
 ## LOADER PRIORITY
@@ -44,8 +41,9 @@ features/
 
 - **Lifecycle**: `launch` → `poll` (2s) → `complete`
 - **Stability**: 3 consecutive polls = idle
-- **Concurrency**: Per-provider/model limits
+- **Concurrency**: Per-provider/model limits via `ConcurrencyManager`
 - **Cleanup**: 30m TTL, 3m stale timeout
+- **State**: Per-session Maps, cleaned on `session.deleted`
 
 ## SKILL MCP
 
@@ -58,3 +56,4 @@ features/
 - **Sequential delegation**: Use `delegate_task` parallel
 - **Trust self-reports**: ALWAYS verify
 - **Main thread blocks**: No heavy I/O in loader init
+- **Direct state mutation**: Use managers for boulder/session state

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

@@ -776,7 +776,7 @@ describe("BackgroundManager.notifyParentSession - dynamic message lookup", () =>
       parentModel: { providerID: "old", modelID: "old-model" },
     }
     const currentMessage: CurrentMessage = {
-      agent: "Sisyphus",
+      agent: "sisyphus",
       model: { providerID: "anthropic", modelID: "claude-opus-4-5" },
     }
 
@@ -784,7 +784,7 @@ describe("BackgroundManager.notifyParentSession - dynamic message lookup", () =>
     const promptBody = buildNotificationPromptBody(task, currentMessage)
 
     // #then - uses currentMessage values, not task.parentModel/parentAgent
-    expect(promptBody.agent).toBe("Sisyphus")
+    expect(promptBody.agent).toBe("sisyphus")
     expect(promptBody.model).toEqual({ providerID: "anthropic", modelID: "claude-opus-4-5" })
   })
 
@@ -827,11 +827,11 @@ describe("BackgroundManager.notifyParentSession - dynamic message lookup", () =>
       status: "completed",
       startedAt: new Date(),
       completedAt: new Date(),
-      parentAgent: "Sisyphus",
+      parentAgent: "sisyphus",
       parentModel: { providerID: "anthropic", modelID: "claude-opus" },
     }
     const currentMessage: CurrentMessage = {
-      agent: "Sisyphus",
+      agent: "sisyphus",
       model: { providerID: "anthropic" },
     }
 
@@ -839,7 +839,7 @@ describe("BackgroundManager.notifyParentSession - dynamic message lookup", () =>
     const promptBody = buildNotificationPromptBody(task, currentMessage)
 
     // #then - model not passed due to incomplete data
-    expect(promptBody.agent).toBe("Sisyphus")
+    expect(promptBody.agent).toBe("sisyphus")
     expect("model" in promptBody).toBe(false)
   })
 
@@ -856,7 +856,7 @@ describe("BackgroundManager.notifyParentSession - dynamic message lookup", () =>
       status: "completed",
       startedAt: new Date(),
       completedAt: new Date(),
-      parentAgent: "Sisyphus",
+      parentAgent: "sisyphus",
       parentModel: { providerID: "anthropic", modelID: "claude-opus" },
     }
 
@@ -864,7 +864,7 @@ describe("BackgroundManager.notifyParentSession - dynamic message lookup", () =>
     const promptBody = buildNotificationPromptBody(task, null)
 
     // #then - falls back to task.parentAgent, no model
-    expect(promptBody.agent).toBe("Sisyphus")
+    expect(promptBody.agent).toBe("sisyphus")
     expect("model" in promptBody).toBe(false)
   })
 })

src/features/background-agent/manager.ts

@@ -7,7 +7,8 @@ import type {
 } from "./types"
 import { log, getAgentToolRestrictions } from "../../shared"
 import { ConcurrencyManager } from "./concurrency"
-import type { BackgroundTaskConfig } from "../../config/schema"
+import type { BackgroundTaskConfig, TmuxConfig } from "../../config/schema"
+import { isInsideTmux } from "../../shared/tmux"
 
 import { subagentSessions } from "../claude-code-session-state"
 import { getTaskToastManager } from "../task-toast-manager"
@@ -54,6 +55,14 @@ interface QueueItem {
   input: LaunchInput
 }
 
+export interface SubagentSessionCreatedEvent {
+  sessionID: string
+  parentID: string
+  title: string
+}
+
+export type OnSubagentSessionCreated = (event: SubagentSessionCreatedEvent) => Promise<void>
+
 export class BackgroundManager {
   private static cleanupManagers = new Set<BackgroundManager>()
   private static cleanupRegistered = false
@@ -68,12 +77,20 @@ export class BackgroundManager {
   private concurrencyManager: ConcurrencyManager
   private shutdownTriggered = false
   private config?: BackgroundTaskConfig
-
+  private tmuxEnabled: boolean
+  private onSubagentSessionCreated?: OnSubagentSessionCreated
 
   private queuesByKey: Map<string, QueueItem[]> = new Map()
   private processingKeys: Set<string> = new Set()
 
-  constructor(ctx: PluginInput, config?: BackgroundTaskConfig) {
+  constructor(
+    ctx: PluginInput,
+    config?: BackgroundTaskConfig,
+    options?: {
+      tmuxConfig?: TmuxConfig
+      onSubagentSessionCreated?: OnSubagentSessionCreated
+    }
+  ) {
     this.tasks = new Map()
     this.notifications = new Map()
     this.pendingByParent = new Map()
@@ -81,6 +98,8 @@ export class BackgroundManager {
     this.directory = ctx.directory
     this.concurrencyManager = new ConcurrencyManager(config)
     this.config = config
+    this.tmuxEnabled = options?.tmuxConfig?.enabled ?? false
+    this.onSubagentSessionCreated = options?.onSubagentSessionCreated
     this.registerProcessCleanup()
   }
 
@@ -222,6 +241,29 @@ export class BackgroundManager {
     const sessionID = createResult.data.id
     subagentSessions.add(sessionID)
 
+    log("[background-agent] tmux callback check", {
+      hasCallback: !!this.onSubagentSessionCreated,
+      tmuxEnabled: this.tmuxEnabled,
+      isInsideTmux: isInsideTmux(),
+      sessionID,
+      parentID: input.parentSessionID,
+    })
+
+    if (this.onSubagentSessionCreated && this.tmuxEnabled && isInsideTmux()) {
+      log("[background-agent] Invoking tmux callback NOW", { sessionID })
+      await this.onSubagentSessionCreated({
+        sessionID,
+        parentID: input.parentSessionID,
+        title: input.description,
+      }).catch((err) => {
+        log("[background-agent] Failed to spawn tmux pane:", err)
+      })
+      log("[background-agent] tmux callback completed, waiting 200ms")
+      await new Promise(r => setTimeout(r, 200))
+    } else {
+      log("[background-agent] SKIP tmux callback - conditions not met")
+    }
+
     // Update task to running state
     task.status = "running"
     task.startedAt = new Date()

src/features/builtin-commands/templates/start-work.ts

@@ -25,7 +25,7 @@ export const START_WORK_TEMPLATE = `You are starting a Sisyphus work session.
    }
    \`\`\`
 
-5. **Read the plan file** and start executing tasks according to Orchestrator Sisyphus workflow
+5. **Read the plan file** and start executing tasks according to atlas workflow
 
 ## OUTPUT FORMAT
 
@@ -69,4 +69,4 @@ Reading plan and beginning execution...
 - The session_id is injected by the hook - use it directly
 - Always update boulder.json BEFORE starting work
 - Read the FULL plan file before delegating any tasks
-- Follow Orchestrator Sisyphus delegation protocols (7-section format)`
+- Follow atlas delegation protocols (7-section format)`

src/features/builtin-skills/agent-browser/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: agent-browser
+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
+---
+
+# Browser Automation with agent-browser
+
+## Quick start
+
+```bash
+agent-browser open <url>        # Navigate to page
+agent-browser snapshot -i       # Get interactive elements with refs
+agent-browser click @e1         # Click element by ref
+agent-browser fill @e2 "text"   # Fill input by ref
+agent-browser close             # Close browser
+```
+
+## Core workflow
+
+1. Navigate: `agent-browser open <url>`
+2. Snapshot: `agent-browser snapshot -i` (returns elements with refs like `@e1`, `@e2`)
+3. Interact using refs from the snapshot
+4. Re-snapshot after navigation or significant DOM changes
+
+## Commands
+
+### Navigation
+```bash
+agent-browser open <url>      # Navigate to URL
+agent-browser back            # Go back
+agent-browser forward         # Go forward
+agent-browser reload          # Reload page
+agent-browser close           # Close browser
+```
+
+### Snapshot (page analysis)
+```bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (recommended)
+agent-browser snapshot -c         # Compact output
+agent-browser snapshot -d 3       # Limit depth to 3
+agent-browser snapshot -s "#main" # Scope to CSS selector
+```
+
+### Interactions (use @refs from snapshot)
+```bash
+agent-browser click @e1           # Click
+agent-browser dblclick @e1        # Double-click
+agent-browser focus @e1           # Focus element
+agent-browser fill @e2 "text"     # Clear and type
+agent-browser type @e2 "text"     # Type without clearing
+agent-browser press Enter         # Press key
+agent-browser press Control+a     # Key combination
+agent-browser keydown Shift       # Hold key down
+agent-browser keyup Shift         # Release key
+agent-browser hover @e1           # Hover
+agent-browser check @e1           # Check checkbox
+agent-browser uncheck @e1         # Uncheck checkbox
+agent-browser select @e1 "value"  # Select dropdown
+agent-browser scroll down 500     # Scroll page
+agent-browser scrollintoview @e1  # Scroll element into view
+agent-browser drag @e1 @e2        # Drag and drop
+agent-browser upload @e1 file.pdf # Upload files
+```
+
+### Get information
+```bash
+agent-browser get text @e1        # Get element text
+agent-browser get html @e1        # Get innerHTML
+agent-browser get value @e1       # Get input value
+agent-browser get attr @e1 href   # Get attribute
+agent-browser get title           # Get page title
+agent-browser get url             # Get current URL
+agent-browser get count ".item"   # Count matching elements
+agent-browser get box @e1         # Get bounding box
+```
+
+### Check state
+```bash
+agent-browser is visible @e1      # Check if visible
+agent-browser is enabled @e1      # Check if enabled
+agent-browser is checked @e1      # Check if checked
+```
+
+### Screenshots & PDF
+```bash
+agent-browser screenshot          # Screenshot to stdout
+agent-browser screenshot path.png # Save to file
+agent-browser screenshot --full   # Full page
+agent-browser pdf output.pdf      # Save as PDF
+```
+
+### Video recording
+```bash
+agent-browser record start ./demo.webm    # Start recording (uses current URL + state)
+agent-browser click @e1                   # Perform actions
+agent-browser record stop                 # Stop and save video
+agent-browser record restart ./take2.webm # Stop current + start new recording
+```
+Recording creates a fresh context but preserves cookies/storage from your session.
+
+### Wait
+```bash
+agent-browser wait @e1                     # Wait for element
+agent-browser wait 2000                    # Wait milliseconds
+agent-browser wait --text "Success"        # Wait for text
+agent-browser wait --url "**/dashboard"    # Wait for URL pattern
+agent-browser wait --load networkidle      # Wait for network idle
+agent-browser wait --fn "window.ready"     # Wait for JS condition
+```
+
+### Mouse control
+```bash
+agent-browser mouse move 100 200      # Move mouse
+agent-browser mouse down left         # Press button
+agent-browser mouse up left           # Release button
+agent-browser mouse wheel 100         # Scroll wheel
+```
+
+### Semantic locators (alternative to refs)
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find first ".item" click
+agent-browser find nth 2 "a" text
+```
+
+### Browser settings
+```bash
+agent-browser set viewport 1920 1080      # Set viewport size
+agent-browser set device "iPhone 14"      # Emulate device
+agent-browser set geo 37.7749 -122.4194   # Set geolocation
+agent-browser set offline on              # Toggle offline mode
+agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers
+agent-browser set credentials user pass   # HTTP basic auth
+agent-browser set media dark              # Emulate color scheme
+```
+
+### Cookies & Storage
+```bash
+agent-browser cookies                     # Get all cookies
+agent-browser cookies set name value      # Set cookie
+agent-browser cookies clear               # Clear cookies
+agent-browser storage local               # Get all localStorage
+agent-browser storage local key           # Get specific key
+agent-browser storage local set k v       # Set value
+agent-browser storage local clear         # Clear all
+agent-browser storage session             # Get all sessionStorage
+agent-browser storage session key         # Get specific key
+agent-browser storage session set k v     # Set value
+agent-browser storage session clear       # Clear all
+```
+
+### Network
+```bash
+agent-browser network route <url>              # Intercept requests
+agent-browser network route <url> --abort      # Block requests
+agent-browser network route <url> --body '{}'  # Mock response
+agent-browser network unroute [url]            # Remove routes
+agent-browser network requests                 # View tracked requests
+agent-browser network requests --filter api    # Filter requests
+```
+
+### Tabs & Windows
+```bash
+agent-browser tab                 # List tabs
+agent-browser tab new [url]       # New tab
+agent-browser tab 2               # Switch to tab
+agent-browser tab close           # Close tab
+agent-browser window new          # New window
+```
+
+### Frames
+```bash
+agent-browser frame "#iframe"     # Switch to iframe
+agent-browser frame main          # Back to main frame
+```
+
+### Dialogs
+```bash
+agent-browser dialog accept [text]  # Accept dialog
+agent-browser dialog dismiss        # Dismiss dialog
+```
+
+### JavaScript
+```bash
+agent-browser eval "document.title"   # Run JavaScript
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--session <name>` | Isolated browser session (`AGENT_BROWSER_SESSION` env) |
+| `--profile <path>` | Persistent browser profile (`AGENT_BROWSER_PROFILE` env) |
+| `--headers <json>` | HTTP headers scoped to URL's origin |
+| `--executable-path <path>` | Custom browser binary (`AGENT_BROWSER_EXECUTABLE_PATH` env) |
+| `--args <args>` | Browser launch args (`AGENT_BROWSER_ARGS` env) |
+| `--user-agent <ua>` | Custom User-Agent (`AGENT_BROWSER_USER_AGENT` env) |
+| `--proxy <url>` | Proxy server (`AGENT_BROWSER_PROXY` env) |
+| `--proxy-bypass <hosts>` | Hosts to bypass proxy (`AGENT_BROWSER_PROXY_BYPASS` env) |
+| `-p, --provider <name>` | Cloud browser provider (`AGENT_BROWSER_PROVIDER` env) |
+| `--json` | Machine-readable JSON output |
+| `--headed` | Show browser window (not headless) |
+| `--cdp <port\|wss://url>` | Connect via Chrome DevTools Protocol |
+| `--debug` | Debug output |
+
+## Example: Form submission
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+```
+
+## Example: Authentication with saved state
+
+```bash
+# Login once
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "username"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Later sessions: load saved state
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+### Header-based Auth (Skip login flows)
+```bash
+# Headers scoped to api.example.com only
+agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'
+# Navigate to another domain - headers NOT sent (safe)
+agent-browser open other-site.com
+# Global headers (all domains)
+agent-browser set headers '{"X-Custom-Header": "value"}'
+```
+
+## Sessions & Persistent Profiles
+
+### Sessions (parallel browsers)
+```bash
+agent-browser --session test1 open site-a.com
+agent-browser --session test2 open site-b.com
+agent-browser session list
+```
+
+### Persistent Profiles
+Persists cookies, localStorage, IndexedDB, service workers, cache, login sessions across browser restarts.
+```bash
+agent-browser --profile ~/.myapp-profile open myapp.com
+# Or via env var
+AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com
+```
+- Use different profile paths for different projects
+- Login once → restart browser → still logged in
+- Stores: cookies, localStorage, IndexedDB, service workers, browser cache
+
+## JSON output (for parsing)
+
+Add `--json` for machine-readable output:
+```bash
+agent-browser snapshot -i --json
+agent-browser get text @e1 --json
+```
+
+## Debugging
+
+```bash
+agent-browser open example.com --headed              # Show browser window
+agent-browser console                                # View console messages
+agent-browser errors                                 # View page errors
+agent-browser record start ./debug.webm              # Record from current page
+agent-browser record stop                            # Save recording
+agent-browser connect 9222                           # Local CDP port
+agent-browser --cdp "wss://browser-service.com/cdp?token=..." snapshot  # Remote via WebSocket
+agent-browser console --clear                        # Clear console
+agent-browser errors --clear                         # Clear errors
+agent-browser highlight @e1                          # Highlight element
+agent-browser trace start                            # Start recording trace
+agent-browser trace stop trace.zip                   # Stop and save trace
+```
+
+---
+
+## Installation
+
+### Step 1: Install agent-browser CLI
+
+```bash
+bun add -g agent-browser
+```
+
+### Step 2: Install Playwright browsers
+
+**IMPORTANT**: `agent-browser install` may fail on some platforms (e.g., darwin-arm64) with "No binary found" error. In that case, install Playwright browsers directly:
+
+```bash
+# Create a temp project and install playwright
+cd /tmp && bun init -y && bun add playwright
+
+# Install Chromium browser
+bun playwright install chromium
+```
+
+This downloads Chrome for Testing to `~/Library/Caches/ms-playwright/`.
+
+### Verify installation
+
+```bash
+agent-browser open https://example.com --headed
+```
+
+If the browser opens successfully, installation is complete.
+
+### Troubleshooting
+
+| Error | Solution |
+|-------|----------|
+| `No binary found for darwin-arm64` | Run `bun playwright install chromium` in a project with playwright dependency |
+| `Executable doesn't exist at .../chromium-XXXX` | Re-run `bun playwright install chromium` |
+| Browser doesn't open | Ensure `--headed` flag is used for visible browser |
+
+---
+Run `agent-browser --help` for all commands. Repo: https://github.com/vercel-labs/agent-browser

src/features/builtin-skills/dev-browser/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: dev-browser
+description: Browser automation with persistent page state. Use when users ask to navigate websites, fill forms, take screenshots, extract web data, test web apps, or automate browser workflows. Trigger phrases include "go to [url]", "click on", "fill out the form", "take a screenshot", "scrape", "automate", "test the website", "log into", or any browser interaction request.
+---
+
+# Dev Browser Skill
+
+Browser automation that maintains page state across script executions. Write small, focused scripts to accomplish tasks incrementally. Once you've proven out part of a workflow and there is repeated work to be done, you can write a script to do the repeated work in a single execution.
+
+## Choosing Your Approach
+
+- **Local/source-available sites**: Read the source code first to write selectors directly
+- **Unknown page layouts**: Use `getAISnapshot()` to discover elements and `selectSnapshotRef()` to interact with them
+- **Visual feedback**: Take screenshots to see what the user sees
+
+## Setup
+
+> **Installation**: See [references/installation.md](references/installation.md) for detailed setup instructions including Windows support.
+
+Two modes available. Ask the user if unclear which to use.
+
+### Standalone Mode (Default)
+
+Launches a new Chromium browser for fresh automation sessions.
+
+```bash
+./skills/dev-browser/server.sh &
+```
+
+Add `--headless` flag if user requests it. **Wait for the `Ready` message before running scripts.**
+
+### Extension Mode
+
+Connects to user's existing Chrome browser. Use this when:
+
+- The user is already logged into sites and wants you to do things behind an authed experience that isn't local dev.
+- The user asks you to use the extension
+
+**Important**: The core flow is still the same. You create named pages inside of their browser.
+
+**Start the relay server:**
+
+```bash
+cd skills/dev-browser && npm i && npm run start-extension &
+```
+
+Wait for `Waiting for extension to connect...` followed by `Extension connected` in the console. To know that a client has connected and the browser is ready to be controlled.
+**Workflow:**
+
+1. Scripts call `client.page("name")` just like the normal mode to create new pages / connect to existing ones.
+2. Automation runs on the user's actual browser session
+
+If the extension hasn't connected yet, tell the user to launch and activate it. Download link: https://github.com/SawyerHood/dev-browser/releases
+
+## Writing Scripts
+
+> **Run all scripts from `skills/dev-browser/` directory.** The `@/` import alias requires this directory's config.
+
+Execute scripts inline using heredocs:
+
+```bash
+cd skills/dev-browser && npx tsx <<'EOF'
+import { connect, waitForPageLoad } from "@/client.js";
+
+const client = await connect();
+// Create page with custom viewport size (optional)
+const page = await client.page("example", { viewport: { width: 1920, height: 1080 } });
+
+await page.goto("https://example.com");
+await waitForPageLoad(page);
+
+console.log({ title: await page.title(), url: page.url() });
+await client.disconnect();
+EOF
+```
+
+**Write to `tmp/` files only when** the script needs reuse, is complex, or user explicitly requests it.
+
+### Key Principles
+
+1. **Small scripts**: Each script does ONE thing (navigate, click, fill, check)
+2. **Evaluate state**: Log/return state at the end to decide next steps
+3. **Descriptive page names**: Use `"checkout"`, `"login"`, not `"main"`
+4. **Disconnect to exit**: `await client.disconnect()` - pages persist on server
+5. **Plain JS in evaluate**: `page.evaluate()` runs in browser - no TypeScript syntax
+
+## Workflow Loop
+
+Follow this pattern for complex tasks:
+
+1. **Write a script** to perform one action
+2. **Run it** and observe the output
+3. **Evaluate** - did it work? What's the current state?
+4. **Decide** - is the task complete or do we need another script?
+5. **Repeat** until task is done
+
+### No TypeScript in Browser Context
+
+Code passed to `page.evaluate()` runs in the browser, which doesn't understand TypeScript:
+
+```typescript
+// ✅ Correct: plain JavaScript
+const text = await page.evaluate(() => {
+  return document.body.innerText;
+});
+
+// ❌ Wrong: TypeScript syntax will fail at runtime
+const text = await page.evaluate(() => {
+  const el: HTMLElement = document.body; // Type annotation breaks in browser!
+  return el.innerText;
+});
+```
+
+## Scraping Data
+
+For scraping large datasets, intercept and replay network requests rather than scrolling the DOM. See [references/scraping.md](references/scraping.md) for the complete guide covering request capture, schema discovery, and paginated API replay.
+
+## Client API
+
+```typescript
+const client = await connect();
+
+// Get or create named page (viewport only applies to new pages)
+const page = await client.page("name");
+const pageWithSize = await client.page("name", { viewport: { width: 1920, height: 1080 } });
+
+const pages = await client.list(); // List all page names
+await client.close("name"); // Close a page
+await client.disconnect(); // Disconnect (pages persist)
+
+// ARIA Snapshot methods
+const snapshot = await client.getAISnapshot("name"); // Get accessibility tree
+const element = await client.selectSnapshotRef("name", "e5"); // Get element by ref
+```
+
+The `page` object is a standard Playwright Page.
+
+## Waiting
+
+```typescript
+import { waitForPageLoad } from "@/client.js";
+
+await waitForPageLoad(page); // After navigation
+await page.waitForSelector(".results"); // For specific elements
+await page.waitForURL("**/success"); // For specific URL
+```
+
+## Inspecting Page State
+
+### Screenshots
+
+```typescript
+await page.screenshot({ path: "tmp/screenshot.png" });
+await page.screenshot({ path: "tmp/full.png", fullPage: true });
+```
+
+### ARIA Snapshot (Element Discovery)
+
+Use `getAISnapshot()` to discover page elements. Returns YAML-formatted accessibility tree:
+
+```yaml
+- banner:
+  - link "Hacker News" [ref=e1]
+  - navigation:
+    - link "new" [ref=e2]
+- main:
+  - list:
+    - listitem:
+      - link "Article Title" [ref=e8]
+      - link "328 comments" [ref=e9]
+- contentinfo:
+  - textbox [ref=e10]
+    - /placeholder: "Search"
+```
+
+**Interpreting refs:**
+
+- `[ref=eN]` - Element reference for interaction (visible, clickable elements only)
+- `[checked]`, `[disabled]`, `[expanded]` - Element states
+- `[level=N]` - Heading level
+- `/url:`, `/placeholder:` - Element properties
+
+**Interacting with refs:**
+
+```typescript
+const snapshot = await client.getAISnapshot("hackernews");
+console.log(snapshot); // Find the ref you need
+
+const element = await client.selectSnapshotRef("hackernews", "e2");
+await element.click();
+```
+
+## Error Recovery
+
+Page state persists after failures. Debug with:
+
+```bash
+cd skills/dev-browser && npx tsx <<'EOF'
+import { connect } from "@/client.js";
+
+const client = await connect();
+const page = await client.page("hackernews");
+
+await page.screenshot({ path: "tmp/debug.png" });
+console.log({
+  url: page.url(),
+  title: await page.title(),
+  bodyText: await page.textContent("body").then((t) => t?.slice(0, 200)),
+});
+
+await client.disconnect();
+EOF
+```

src/features/builtin-skills/dev-browser/references/installation.md

@@ -0,0 +1,193 @@
+# Dev Browser Installation Guide
+
+This guide covers installation for all platforms: macOS, Linux, and Windows.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) v18 or later with npm
+- Git (for cloning the skill)
+
+## Installation
+
+### Step 1: Clone the Skill
+
+```bash
+# Clone dev-browser to a temporary location
+git clone https://github.com/sawyerhood/dev-browser /tmp/dev-browser-skill
+
+# Copy to skills directory (adjust path as needed)
+# For oh-my-opencode: already bundled
+# For manual installation:
+mkdir -p ~/.config/opencode/skills
+cp -r /tmp/dev-browser-skill/skills/dev-browser ~/.config/opencode/skills/dev-browser
+
+# Cleanup
+rm -rf /tmp/dev-browser-skill
+```
+
+**Windows (PowerShell):**
+```powershell
+# Clone dev-browser to temp location
+git clone https://github.com/sawyerhood/dev-browser $env:TEMP\dev-browser-skill
+
+# Copy to skills directory
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"
+Copy-Item -Recurse "$env:TEMP\dev-browser-skill\skills\dev-browser" "$env:USERPROFILE\.config\opencode\skills\dev-browser"
+
+# Cleanup
+Remove-Item -Recurse -Force "$env:TEMP\dev-browser-skill"
+```
+
+### Step 2: Install Dependencies
+
+```bash
+cd ~/.config/opencode/skills/dev-browser
+npm install
+```
+
+**Windows (PowerShell):**
+```powershell
+cd "$env:USERPROFILE\.config\opencode\skills\dev-browser"
+npm install
+```
+
+### Step 3: Start the Server
+
+#### Standalone Mode (New Browser Instance)
+
+**macOS/Linux:**
+```bash
+cd ~/.config/opencode/skills/dev-browser
+./server.sh &
+# Or for headless:
+./server.sh --headless &
+```
+
+**Windows (PowerShell):**
+```powershell
+cd "$env:USERPROFILE\.config\opencode\skills\dev-browser"
+Start-Process -NoNewWindow -FilePath "node" -ArgumentList "server.js"
+# Or for headless:
+Start-Process -NoNewWindow -FilePath "node" -ArgumentList "server.js", "--headless"
+```
+
+**Windows (CMD):**
+```cmd
+cd %USERPROFILE%\.config\opencode\skills\dev-browser
+start /B node server.js
+```
+
+Wait for the `Ready` message before running scripts.
+
+#### Extension Mode (Use Existing Chrome)
+
+**macOS/Linux:**
+```bash
+cd ~/.config/opencode/skills/dev-browser
+npm run start-extension &
+```
+
+**Windows (PowerShell):**
+```powershell
+cd "$env:USERPROFILE\.config\opencode\skills\dev-browser"
+Start-Process -NoNewWindow -FilePath "npm" -ArgumentList "run", "start-extension"
+```
+
+Wait for `Extension connected` message.
+
+## Chrome Extension Setup (Optional)
+
+The Chrome extension allows controlling your existing Chrome browser with all your logged-in sessions.
+
+### Installation
+
+1. Download `extension.zip` from [latest release](https://github.com/sawyerhood/dev-browser/releases/latest)
+2. Extract to a permanent location:
+   - **macOS/Linux:** `~/.dev-browser-extension`
+   - **Windows:** `%USERPROFILE%\.dev-browser-extension`
+3. Open Chrome → `chrome://extensions`
+4. Enable "Developer mode" (toggle in top right)
+5. Click "Load unpacked" → select the extracted folder
+
+### Usage
+
+1. Click the Dev Browser extension icon in Chrome toolbar
+2. Toggle to "Active"
+3. Start the extension relay server (see above)
+4. Use dev-browser scripts - they'll control your existing Chrome
+
+## Troubleshooting
+
+### Server Won't Start
+
+**Check Node.js version:**
+```bash
+node --version  # Should be v18+
+```
+
+**Check port availability:**
+```bash
+# macOS/Linux
+lsof -i :3000
+
+# Windows
+netstat -ano | findstr :3000
+```
+
+### Playwright Installation Issues
+
+If Chromium fails to install:
+```bash
+npx playwright install chromium
+```
+
+### Windows-Specific Issues
+
+**Execution Policy:**
+If PowerShell scripts are blocked:
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+**Path Issues:**
+Use forward slashes or escaped backslashes in paths:
+```powershell
+# Good
+cd "$env:USERPROFILE/.config/opencode/skills/dev-browser"
+# Also good
+cd "$env:USERPROFILE\.config\opencode\skills\dev-browser"
+```
+
+### Extension Not Connecting
+
+1. Ensure extension is "Active" (click icon to toggle)
+2. Check relay server is running (`npm run start-extension`)
+3. Look for `Extension connected` message in console
+4. Try reloading the extension in `chrome://extensions`
+
+## Permissions
+
+To skip permission prompts in Claude Code, add to `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": ["Skill(dev-browser:dev-browser)", "Bash(npx tsx:*)"]
+  }
+}
+```
+
+## Updating
+
+```bash
+cd ~/.config/opencode/skills/dev-browser
+git pull
+npm install
+```
+
+**Windows:**
+```powershell
+cd "$env:USERPROFILE\.config\opencode\skills\dev-browser"
+git pull
+npm install
+```

src/features/builtin-skills/dev-browser/references/scraping.md

@@ -0,0 +1,155 @@
+# Data Scraping Guide
+
+For large datasets (followers, posts, search results), **intercept and replay network requests** rather than scrolling and parsing the DOM. This is faster, more reliable, and handles pagination automatically.
+
+## Why Not Scroll?
+
+Scrolling is slow, unreliable, and wastes time. APIs return structured data with pagination built in. Always prefer API replay.
+
+## Start Small, Then Scale
+
+**Don't try to automate everything at once.** Work incrementally:
+
+1. **Capture one request** - verify you're intercepting the right endpoint
+2. **Inspect one response** - understand the schema before writing extraction code
+3. **Extract a few items** - make sure your parsing logic works
+4. **Then scale up** - add pagination loop only after the basics work
+
+This prevents wasting time debugging a complex script when the issue is a simple path like `data.user.timeline` vs `data.user.result.timeline`.
+
+## Step-by-Step Workflow
+
+### 1. Capture Request Details
+
+First, intercept a request to understand URL structure and required headers:
+
+```typescript
+import { connect, waitForPageLoad } from "@/client.js";
+import * as fs from "node:fs";
+
+const client = await connect();
+const page = await client.page("site");
+
+let capturedRequest = null;
+page.on("request", (request) => {
+  const url = request.url();
+  // Look for API endpoints (adjust pattern for your target site)
+  if (url.includes("/api/") || url.includes("/graphql/")) {
+    capturedRequest = {
+      url: url,
+      headers: request.headers(),
+      method: request.method(),
+    };
+    fs.writeFileSync("tmp/request-details.json", JSON.stringify(capturedRequest, null, 2));
+    console.log("Captured request:", url.substring(0, 80) + "...");
+  }
+});
+
+await page.goto("https://example.com/profile");
+await waitForPageLoad(page);
+await page.waitForTimeout(3000);
+
+await client.disconnect();
+```
+
+### 2. Capture Response to Understand Schema
+
+Save a raw response to inspect the data structure:
+
+```typescript
+page.on("response", async (response) => {
+  const url = response.url();
+  if (url.includes("UserTweets") || url.includes("/api/data")) {
+    const json = await response.json();
+    fs.writeFileSync("tmp/api-response.json", JSON.stringify(json, null, 2));
+    console.log("Captured response");
+  }
+});
+```
+
+Then analyze the structure to find:
+
+- Where the data array lives (e.g., `data.user.result.timeline.instructions[].entries`)
+- Where pagination cursors are (e.g., `cursor-bottom` entries)
+- What fields you need to extract
+
+### 3. Replay API with Pagination
+
+Once you understand the schema, replay requests directly:
+
+```typescript
+import { connect } from "@/client.js";
+import * as fs from "node:fs";
+
+const client = await connect();
+const page = await client.page("site");
+
+const results = new Map(); // Use Map for deduplication
+const headers = JSON.parse(fs.readFileSync("tmp/request-details.json", "utf8")).headers;
+const baseUrl = "https://example.com/api/data";
+
+let cursor = null;
+let hasMore = true;
+
+while (hasMore) {
+  // Build URL with pagination cursor
+  const params = { count: 20 };
+  if (cursor) params.cursor = cursor;
+  const url = `${baseUrl}?params=${encodeURIComponent(JSON.stringify(params))}`;
+
+  // Execute fetch in browser context (has auth cookies/headers)
+  const response = await page.evaluate(
+    async ({ url, headers }) => {
+      const res = await fetch(url, { headers });
+      return res.json();
+    },
+    { url, headers }
+  );
+
+  // Extract data and cursor (adjust paths for your API)
+  const entries = response?.data?.entries || [];
+  for (const entry of entries) {
+    if (entry.type === "cursor-bottom") {
+      cursor = entry.value;
+    } else if (entry.id && !results.has(entry.id)) {
+      results.set(entry.id, {
+        id: entry.id,
+        text: entry.content,
+        timestamp: entry.created_at,
+      });
+    }
+  }
+
+  console.log(`Fetched page, total: ${results.size}`);
+
+  // Check stop conditions
+  if (!cursor || entries.length === 0) hasMore = false;
+
+  // Rate limiting - be respectful
+  await new Promise((r) => setTimeout(r, 500));
+}
+
+// Export results
+const data = Array.from(results.values());
+fs.writeFileSync("tmp/results.json", JSON.stringify(data, null, 2));
+console.log(`Saved ${data.length} items`);
+
+await client.disconnect();
+```
+
+## Key Patterns
+
+| Pattern                 | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `page.on('request')`    | Capture outgoing request URL + headers                 |
+| `page.on('response')`   | Capture response data to understand schema             |
+| `page.evaluate(fetch)`  | Replay requests in browser context (inherits auth)     |
+| `Map` for deduplication | APIs often return overlapping data across pages        |
+| Cursor-based pagination | Look for `cursor`, `next_token`, `offset` in responses |
+
+## Tips
+
+- **Extension mode**: `page.context().cookies()` doesn't work - capture auth headers from intercepted requests instead
+- **Rate limiting**: Add 500ms+ delays between requests to avoid blocks
+- **Stop conditions**: Check for empty results, missing cursor, or reaching a date/ID threshold
+- **GraphQL APIs**: URL params often include `variables` and `features` JSON objects - capture and reuse them

src/features/builtin-skills/index.ts

@@ -1,2 +1,2 @@
 export * from "./types"
-export { createBuiltinSkills } from "./skills"
+export { createBuiltinSkills, type CreateBuiltinSkillsOptions } from "./skills"

src/features/builtin-skills/skills.test.ts

@@ -0,0 +1,89 @@
+import { describe, test, expect } from "bun:test"
+import { createBuiltinSkills } from "./skills"
+
+describe("createBuiltinSkills", () => {
+	test("returns playwright skill by default", () => {
+		// #given - no options (default)
+
+		// #when
+		const skills = createBuiltinSkills()
+
+		// #then
+		const browserSkill = skills.find((s) => s.name === "playwright")
+		expect(browserSkill).toBeDefined()
+		expect(browserSkill!.description).toContain("browser")
+		expect(browserSkill!.mcpConfig).toHaveProperty("playwright")
+	})
+
+	test("returns playwright skill when browserProvider is 'playwright'", () => {
+		// #given
+		const options = { browserProvider: "playwright" as const }
+
+		// #when
+		const skills = createBuiltinSkills(options)
+
+		// #then
+		const playwrightSkill = skills.find((s) => s.name === "playwright")
+		const agentBrowserSkill = skills.find((s) => s.name === "agent-browser")
+		expect(playwrightSkill).toBeDefined()
+		expect(agentBrowserSkill).toBeUndefined()
+	})
+
+	test("returns agent-browser skill when browserProvider is 'agent-browser'", () => {
+		// #given
+		const options = { browserProvider: "agent-browser" as const }
+
+		// #when
+		const skills = createBuiltinSkills(options)
+
+		// #then
+		const agentBrowserSkill = skills.find((s) => s.name === "agent-browser")
+		const playwrightSkill = skills.find((s) => s.name === "playwright")
+		expect(agentBrowserSkill).toBeDefined()
+		expect(agentBrowserSkill!.description).toContain("browser")
+		expect(agentBrowserSkill!.allowedTools).toContain("Bash(agent-browser:*)")
+		expect(agentBrowserSkill!.template).toContain("agent-browser")
+		expect(playwrightSkill).toBeUndefined()
+	})
+
+	test("agent-browser skill template is inlined (not loaded from file)", () => {
+		// #given
+		const options = { browserProvider: "agent-browser" as const }
+
+		// #when
+		const skills = createBuiltinSkills(options)
+		const agentBrowserSkill = skills.find((s) => s.name === "agent-browser")
+
+		// #then - template should contain substantial content (inlined, not fallback)
+		expect(agentBrowserSkill!.template).toContain("## Quick start")
+		expect(agentBrowserSkill!.template).toContain("## Commands")
+		expect(agentBrowserSkill!.template).toContain("agent-browser open")
+		expect(agentBrowserSkill!.template).toContain("agent-browser snapshot")
+	})
+
+	test("always includes frontend-ui-ux and git-master skills", () => {
+		// #given - both provider options
+
+		// #when
+		const defaultSkills = createBuiltinSkills()
+		const agentBrowserSkills = createBuiltinSkills({ browserProvider: "agent-browser" })
+
+		// #then
+		for (const skills of [defaultSkills, agentBrowserSkills]) {
+			expect(skills.find((s) => s.name === "frontend-ui-ux")).toBeDefined()
+			expect(skills.find((s) => s.name === "git-master")).toBeDefined()
+		}
+	})
+
+	test("returns exactly 4 skills regardless of provider", () => {
+		// #given
+
+		// #when
+		const defaultSkills = createBuiltinSkills()
+		const agentBrowserSkills = createBuiltinSkills({ browserProvider: "agent-browser" })
+
+		// #then
+		expect(defaultSkills).toHaveLength(4)
+		expect(agentBrowserSkills).toHaveLength(4)
+	})
+})

src/features/builtin-skills/skills.ts

@@ -1,4 +1,5 @@
 import type { BuiltinSkill } from "./types"
+import type { BrowserAutomationProvider } from "../../config/schema"
 
 const playwrightSkill: BuiltinSkill = {
   name: "playwright",
@@ -14,6 +15,303 @@ This skill provides browser automation capabilities via the Playwright MCP serve
   },
 }
 
+const agentBrowserSkill: BuiltinSkill = {
+  name: "agent-browser",
+  description: "MUST USE for any browser-related tasks. Browser automation via agent-browser CLI - verification, browsing, information gathering, web scraping, testing, screenshots, and all browser interactions.",
+  template: `# Browser Automation with agent-browser
+
+## Quick start
+
+\`\`\`bash
+agent-browser open <url>        # Navigate to page
+agent-browser snapshot -i       # Get interactive elements with refs
+agent-browser click @e1         # Click element by ref
+agent-browser fill @e2 "text"   # Fill input by ref
+agent-browser close             # Close browser
+\`\`\`
+
+## Core workflow
+
+1. Navigate: \`agent-browser open <url>\`
+2. Snapshot: \`agent-browser snapshot -i\` (returns elements with refs like \`@e1\`, \`@e2\`)
+3. Interact using refs from the snapshot
+4. Re-snapshot after navigation or significant DOM changes
+
+## Commands
+
+### Navigation
+\`\`\`bash
+agent-browser open <url>      # Navigate to URL
+agent-browser back            # Go back
+agent-browser forward         # Go forward
+agent-browser reload          # Reload page
+agent-browser close           # Close browser
+\`\`\`
+
+### Snapshot (page analysis)
+\`\`\`bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (recommended)
+agent-browser snapshot -c         # Compact output
+agent-browser snapshot -d 3       # Limit depth to 3
+agent-browser snapshot -s "#main" # Scope to CSS selector
+\`\`\`
+
+### Interactions (use @refs from snapshot)
+\`\`\`bash
+agent-browser click @e1           # Click
+agent-browser dblclick @e1        # Double-click
+agent-browser focus @e1           # Focus element
+agent-browser fill @e2 "text"     # Clear and type
+agent-browser type @e2 "text"     # Type without clearing
+agent-browser press Enter         # Press key
+agent-browser press Control+a     # Key combination
+agent-browser keydown Shift       # Hold key down
+agent-browser keyup Shift         # Release key
+agent-browser hover @e1           # Hover
+agent-browser check @e1           # Check checkbox
+agent-browser uncheck @e1         # Uncheck checkbox
+agent-browser select @e1 "value"  # Select dropdown
+agent-browser scroll down 500     # Scroll page
+agent-browser scrollintoview @e1  # Scroll element into view
+agent-browser drag @e1 @e2        # Drag and drop
+agent-browser upload @e1 file.pdf # Upload files
+\`\`\`
+
+### Get information
+\`\`\`bash
+agent-browser get text @e1        # Get element text
+agent-browser get html @e1        # Get innerHTML
+agent-browser get value @e1       # Get input value
+agent-browser get attr @e1 href   # Get attribute
+agent-browser get title           # Get page title
+agent-browser get url             # Get current URL
+agent-browser get count ".item"   # Count matching elements
+agent-browser get box @e1         # Get bounding box
+\`\`\`
+
+### Check state
+\`\`\`bash
+agent-browser is visible @e1      # Check if visible
+agent-browser is enabled @e1      # Check if enabled
+agent-browser is checked @e1      # Check if checked
+\`\`\`
+
+### Screenshots & PDF
+\`\`\`bash
+agent-browser screenshot          # Screenshot to stdout
+agent-browser screenshot path.png # Save to file
+agent-browser screenshot --full   # Full page
+agent-browser pdf output.pdf      # Save as PDF
+\`\`\`
+
+### Video recording
+\`\`\`bash
+agent-browser record start ./demo.webm    # Start recording (uses current URL + state)
+agent-browser click @e1                   # Perform actions
+agent-browser record stop                 # Stop and save video
+agent-browser record restart ./take2.webm # Stop current + start new recording
+\`\`\`
+Recording creates a fresh context but preserves cookies/storage from your session.
+
+### Wait
+\`\`\`bash
+agent-browser wait @e1                     # Wait for element
+agent-browser wait 2000                    # Wait milliseconds
+agent-browser wait --text "Success"        # Wait for text
+agent-browser wait --url "**/dashboard"    # Wait for URL pattern
+agent-browser wait --load networkidle      # Wait for network idle
+agent-browser wait --fn "window.ready"     # Wait for JS condition
+\`\`\`
+
+### Mouse control
+\`\`\`bash
+agent-browser mouse move 100 200      # Move mouse
+agent-browser mouse down left         # Press button
+agent-browser mouse up left           # Release button
+agent-browser mouse wheel 100         # Scroll wheel
+\`\`\`
+
+### Semantic locators (alternative to refs)
+\`\`\`bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find first ".item" click
+agent-browser find nth 2 "a" text
+\`\`\`
+
+### Browser settings
+\`\`\`bash
+agent-browser set viewport 1920 1080      # Set viewport size
+agent-browser set device "iPhone 14"      # Emulate device
+agent-browser set geo 37.7749 -122.4194   # Set geolocation
+agent-browser set offline on              # Toggle offline mode
+agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers
+agent-browser set credentials user pass   # HTTP basic auth
+agent-browser set media dark              # Emulate color scheme
+\`\`\`
+
+### Cookies & Storage
+\`\`\`bash
+agent-browser cookies                     # Get all cookies
+agent-browser cookies set name value      # Set cookie
+agent-browser cookies clear               # Clear cookies
+agent-browser storage local               # Get all localStorage
+agent-browser storage local key           # Get specific key
+agent-browser storage local set k v       # Set value
+agent-browser storage local clear         # Clear all
+agent-browser storage session             # Get all sessionStorage
+agent-browser storage session key         # Get specific key
+agent-browser storage session set k v     # Set value
+agent-browser storage session clear       # Clear all
+\`\`\`
+
+### Network
+\`\`\`bash
+agent-browser network route <url>              # Intercept requests
+agent-browser network route <url> --abort      # Block requests
+agent-browser network route <url> --body '{}'  # Mock response
+agent-browser network unroute [url]            # Remove routes
+agent-browser network requests                 # View tracked requests
+agent-browser network requests --filter api    # Filter requests
+\`\`\`
+
+### Tabs & Windows
+\`\`\`bash
+agent-browser tab                 # List tabs
+agent-browser tab new [url]       # New tab
+agent-browser tab 2               # Switch to tab
+agent-browser tab close           # Close tab
+agent-browser window new          # New window
+\`\`\`
+
+### Frames
+\`\`\`bash
+agent-browser frame "#iframe"     # Switch to iframe
+agent-browser frame main          # Back to main frame
+\`\`\`
+
+### Dialogs
+\`\`\`bash
+agent-browser dialog accept [text]  # Accept dialog
+agent-browser dialog dismiss        # Dismiss dialog
+\`\`\`
+
+### JavaScript
+\`\`\`bash
+agent-browser eval "document.title"   # Run JavaScript
+\`\`\`
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| \`--session <name>\` | Isolated browser session (\`AGENT_BROWSER_SESSION\` env) |
+| \`--profile <path>\` | Persistent browser profile (\`AGENT_BROWSER_PROFILE\` env) |
+| \`--headers <json>\` | HTTP headers scoped to URL's origin |
+| \`--executable-path <path>\` | Custom browser binary (\`AGENT_BROWSER_EXECUTABLE_PATH\` env) |
+| \`--args <args>\` | Browser launch args (\`AGENT_BROWSER_ARGS\` env) |
+| \`--user-agent <ua>\` | Custom User-Agent (\`AGENT_BROWSER_USER_AGENT\` env) |
+| \`--proxy <url>\` | Proxy server (\`AGENT_BROWSER_PROXY\` env) |
+| \`--proxy-bypass <hosts>\` | Hosts to bypass proxy (\`AGENT_BROWSER_PROXY_BYPASS\` env) |
+| \`-p, --provider <name>\` | Cloud browser provider (\`AGENT_BROWSER_PROVIDER\` env) |
+| \`--json\` | Machine-readable JSON output |
+| \`--headed\` | Show browser window (not headless) |
+| \`--cdp <port\\|wss://url>\` | Connect via Chrome DevTools Protocol |
+| \`--debug\` | Debug output |
+
+## Example: Form submission
+
+\`\`\`bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+\`\`\`
+
+## Example: Authentication with saved state
+
+\`\`\`bash
+# Login once
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "username"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Later sessions: load saved state
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+\`\`\`
+
+### Header-based Auth (Skip login flows)
+\`\`\`bash
+# Headers scoped to api.example.com only
+agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'
+# Navigate to another domain - headers NOT sent (safe)
+agent-browser open other-site.com
+# Global headers (all domains)
+agent-browser set headers '{"X-Custom-Header": "value"}'
+\`\`\`
+
+## Sessions & Persistent Profiles
+
+### Sessions (parallel browsers)
+\`\`\`bash
+agent-browser --session test1 open site-a.com
+agent-browser --session test2 open site-b.com
+agent-browser session list
+\`\`\`
+
+### Persistent Profiles
+Persists cookies, localStorage, IndexedDB, service workers, cache, login sessions across browser restarts.
+\`\`\`bash
+agent-browser --profile ~/.myapp-profile open myapp.com
+# Or via env var
+AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com
+\`\`\`
+- Use different profile paths for different projects
+- Login once → restart browser → still logged in
+- Stores: cookies, localStorage, IndexedDB, service workers, browser cache
+
+## JSON output (for parsing)
+
+Add \`--json\` for machine-readable output:
+\`\`\`bash
+agent-browser snapshot -i --json
+agent-browser get text @e1 --json
+\`\`\`
+
+## Debugging
+
+\`\`\`bash
+agent-browser open example.com --headed              # Show browser window
+agent-browser console                                # View console messages
+agent-browser errors                                 # View page errors
+agent-browser record start ./debug.webm              # Record from current page
+agent-browser record stop                            # Save recording
+agent-browser connect 9222                           # Local CDP port
+agent-browser --cdp "wss://browser-service.com/cdp?token=..." snapshot  # Remote via WebSocket
+agent-browser console --clear                        # Clear console
+agent-browser errors --clear                         # Clear errors
+agent-browser highlight @e1                          # Highlight element
+agent-browser trace start                            # Start recording trace
+agent-browser trace stop trace.zip                   # Stop and save trace
+\`\`\`
+
+---
+Install: \`bun add -g agent-browser && agent-browser install\`. Run \`agent-browser --help\` for all commands. Repo: https://github.com/vercel-labs/agent-browser`,
+  allowedTools: ["Bash(agent-browser:*)"],
+}
+
 const frontendUiUxSkill: BuiltinSkill = {
   name: "frontend-ui-ux",
   description: "Designer-turned-developer who crafts stunning UI/UX even without design mockups",
@@ -1198,6 +1496,234 @@ POTENTIAL ACTIONS:
 - Bisect without proper good/bad boundaries -> Wasted time`,
 }
 
-export function createBuiltinSkills(): BuiltinSkill[] {
-  return [playwrightSkill, frontendUiUxSkill, gitMasterSkill]
+const devBrowserSkill: BuiltinSkill = {
+  name: "dev-browser",
+  description:
+    "Browser automation with persistent page state. Use when users ask to navigate websites, fill forms, take screenshots, extract web data, test web apps, or automate browser workflows. Trigger phrases include 'go to [url]', 'click on', 'fill out the form', 'take a screenshot', 'scrape', 'automate', 'test the website', 'log into', or any browser interaction request.",
+  template: `# Dev Browser Skill
+
+Browser automation that maintains page state across script executions. Write small, focused scripts to accomplish tasks incrementally. Once you've proven out part of a workflow and there is repeated work to be done, you can write a script to do the repeated work in a single execution.
+
+## Choosing Your Approach
+
+- **Local/source-available sites**: Read the source code first to write selectors directly
+- **Unknown page layouts**: Use \`getAISnapshot()\` to discover elements and \`selectSnapshotRef()\` to interact with them
+- **Visual feedback**: Take screenshots to see what the user sees
+
+## Setup
+
+**IMPORTANT**: Before using this skill, ensure the server is running. See [references/installation.md](references/installation.md) for platform-specific setup instructions (macOS, Linux, Windows).
+
+Two modes available. Ask the user if unclear which to use.
+
+### Standalone Mode (Default)
+
+Launches a new Chromium browser for fresh automation sessions.
+
+**macOS/Linux:**
+\`\`\`bash
+./skills/dev-browser/server.sh &
+\`\`\`
+
+**Windows (PowerShell):**
+\`\`\`powershell
+Start-Process -NoNewWindow -FilePath "node" -ArgumentList "skills/dev-browser/server.js"
+\`\`\`
+
+Add \`--headless\` flag if user requests it. **Wait for the \`Ready\` message before running scripts.**
+
+### Extension Mode
+
+Connects to user's existing Chrome browser. Use this when:
+
+- The user is already logged into sites and wants you to do things behind an authed experience that isn't local dev.
+- The user asks you to use the extension
+
+**Important**: The core flow is still the same. You create named pages inside of their browser.
+
+**Start the relay server:**
+
+**macOS/Linux:**
+\`\`\`bash
+cd skills/dev-browser && npm i && npm run start-extension &
+\`\`\`
+
+**Windows (PowerShell):**
+\`\`\`powershell
+cd skills/dev-browser; npm i; Start-Process -NoNewWindow -FilePath "npm" -ArgumentList "run", "start-extension"
+\`\`\`
+
+Wait for \`Waiting for extension to connect...\` followed by \`Extension connected\` in the console.
+
+If the extension hasn't connected yet, tell the user to launch and activate it. Download link: https://github.com/SawyerHood/dev-browser/releases
+
+## Writing Scripts
+
+> **Run all scripts from \`skills/dev-browser/\` directory.** The \`@/\` import alias requires this directory's config.
+
+Execute scripts inline using heredocs:
+
+**macOS/Linux:**
+\`\`\`bash
+cd skills/dev-browser && npx tsx <<'EOF'
+import { connect, waitForPageLoad } from "@/client.js";
+
+const client = await connect();
+const page = await client.page("example", { viewport: { width: 1920, height: 1080 } });
+
+await page.goto("https://example.com");
+await waitForPageLoad(page);
+
+console.log({ title: await page.title(), url: page.url() });
+await client.disconnect();
+EOF
+\`\`\`
+
+**Windows (PowerShell):**
+\`\`\`powershell
+cd skills/dev-browser
+@"
+import { connect, waitForPageLoad } from "@/client.js";
+
+const client = await connect();
+const page = await client.page("example", { viewport: { width: 1920, height: 1080 } });
+
+await page.goto("https://example.com");
+await waitForPageLoad(page);
+
+console.log({ title: await page.title(), url: page.url() });
+await client.disconnect();
+"@ | npx tsx --input-type=module
+\`\`\`
+
+### Key Principles
+
+1. **Small scripts**: Each script does ONE thing (navigate, click, fill, check)
+2. **Evaluate state**: Log/return state at the end to decide next steps
+3. **Descriptive page names**: Use \`"checkout"\`, \`"login"\`, not \`"main"\`
+4. **Disconnect to exit**: \`await client.disconnect()\` - pages persist on server
+5. **Plain JS in evaluate**: \`page.evaluate()\` runs in browser - no TypeScript syntax
+
+## Workflow Loop
+
+1. **Write a script** to perform one action
+2. **Run it** and observe the output
+3. **Evaluate** - did it work? What's the current state?
+4. **Decide** - is the task complete or do we need another script?
+5. **Repeat** until task is done
+
+### No TypeScript in Browser Context
+
+Code passed to \`page.evaluate()\` runs in the browser, which doesn't understand TypeScript:
+
+\`\`\`typescript
+// Correct: plain JavaScript
+const text = await page.evaluate(() => {
+  return document.body.innerText;
+});
+
+// Wrong: TypeScript syntax will fail at runtime
+const text = await page.evaluate(() => {
+  const el: HTMLElement = document.body; // Type annotation breaks in browser!
+  return el.innerText;
+});
+\`\`\`
+
+## Scraping Data
+
+For scraping large datasets, intercept and replay network requests rather than scrolling the DOM. See [references/scraping.md](references/scraping.md) for the complete guide.
+
+## Client API
+
+\`\`\`typescript
+const client = await connect();
+
+// Get or create named page
+const page = await client.page("name");
+const pageWithSize = await client.page("name", { viewport: { width: 1920, height: 1080 } });
+
+const pages = await client.list(); // List all page names
+await client.close("name"); // Close a page
+await client.disconnect(); // Disconnect (pages persist)
+
+// ARIA Snapshot methods
+const snapshot = await client.getAISnapshot("name"); // Get accessibility tree
+const element = await client.selectSnapshotRef("name", "e5"); // Get element by ref
+\`\`\`
+
+## Waiting
+
+\`\`\`typescript
+import { waitForPageLoad } from "@/client.js";
+
+await waitForPageLoad(page); // After navigation
+await page.waitForSelector(".results"); // For specific elements
+await page.waitForURL("**/success"); // For specific URL
+\`\`\`
+
+## Screenshots
+
+\`\`\`typescript
+await page.screenshot({ path: "tmp/screenshot.png" });
+await page.screenshot({ path: "tmp/full.png", fullPage: true });
+\`\`\`
+
+## ARIA Snapshot (Element Discovery)
+
+Use \`getAISnapshot()\` to discover page elements. Returns YAML-formatted accessibility tree:
+
+\`\`\`yaml
+- banner:
+  - link "Hacker News" [ref=e1]
+  - navigation:
+    - link "new" [ref=e2]
+- main:
+  - list:
+    - listitem:
+      - link "Article Title" [ref=e8]
+\`\`\`
+
+**Interacting with refs:**
+
+\`\`\`typescript
+const snapshot = await client.getAISnapshot("hackernews");
+console.log(snapshot); // Find the ref you need
+
+const element = await client.selectSnapshotRef("hackernews", "e2");
+await element.click();
+\`\`\`
+
+## Error Recovery
+
+Page state persists after failures. Debug with:
+
+\`\`\`bash
+cd skills/dev-browser && npx tsx <<'EOF'
+import { connect } from "@/client.js";
+
+const client = await connect();
+const page = await client.page("hackernews");
+
+await page.screenshot({ path: "tmp/debug.png" });
+console.log({
+  url: page.url(),
+  title: await page.title(),
+  bodyText: await page.textContent("body").then((t) => t?.slice(0, 200)),
+});
+
+await client.disconnect();
+EOF
+\`\`\``,
+}
+
+export interface CreateBuiltinSkillsOptions {
+  browserProvider?: BrowserAutomationProvider
+}
+
+export function createBuiltinSkills(options: CreateBuiltinSkillsOptions = {}): BuiltinSkill[] {
+  const { browserProvider = "playwright" } = options
+
+  const browserSkill = browserProvider === "agent-browser" ? agentBrowserSkill : playwrightSkill
+
+  return [browserSkill, frontendUiUxSkill, gitMasterSkill, devBrowserSkill]
 }

src/features/claude-code-session-state/state.test.ts

@@ -37,7 +37,7 @@ describe("claude-code-session-state", () => {
       setSessionAgent(sessionID, "Prometheus (Planner)")
 
       // #when - try to overwrite
-      setSessionAgent(sessionID, "Sisyphus")
+      setSessionAgent(sessionID, "sisyphus")
 
       // #then - first agent preserved
       expect(getSessionAgent(sessionID)).toBe("Prometheus (Planner)")
@@ -58,10 +58,10 @@ describe("claude-code-session-state", () => {
       setSessionAgent(sessionID, "Prometheus (Planner)")
 
       // #when - force update
-      updateSessionAgent(sessionID, "Sisyphus")
+      updateSessionAgent(sessionID, "sisyphus")
 
       // #then
-      expect(getSessionAgent(sessionID)).toBe("Sisyphus")
+      expect(getSessionAgent(sessionID)).toBe("sisyphus")
     })
   })
 
@@ -129,7 +129,7 @@ describe("claude-code-session-state", () => {
       // #given - user switches to custom agent "MyCustomAgent"
       const sessionID = "test-session-custom"
       const customAgent = "MyCustomAgent"
-      const defaultAgent = "Sisyphus"
+      const defaultAgent = "sisyphus"
 
       // User switches to custom agent (via UI)
       setSessionAgent(sessionID, customAgent)

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

@@ -21,7 +21,7 @@ describe("createContextInjectorMessagesTransformHook", () => {
       sessionID,
       role,
       time: { created: Date.now() },
-      agent: "Sisyphus",
+      agent: "sisyphus",
       model: { providerID: "test", modelID: "test" },
       path: { cwd: "/", root: "/" },
     },

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

@@ -265,3 +265,66 @@ describe("resolveMultipleSkillsAsync", () => {
 		expect(result.notFound).toEqual([])
 	})
 })
+
+describe("resolveSkillContent with browserProvider", () => {
+	it("should resolve agent-browser skill when browserProvider is 'agent-browser'", () => {
+		// #given: browserProvider set to agent-browser
+		const options = { browserProvider: "agent-browser" as const }
+
+		// #when: resolving content for 'agent-browser'
+		const result = resolveSkillContent("agent-browser", options)
+
+		// #then: returns agent-browser template
+		expect(result).not.toBeNull()
+		expect(result).toContain("agent-browser")
+	})
+
+	it("should return null for agent-browser when browserProvider is default", () => {
+		// #given: no browserProvider (defaults to playwright)
+
+		// #when: resolving content for 'agent-browser'
+		const result = resolveSkillContent("agent-browser")
+
+		// #then: returns null because agent-browser is not in default builtin skills
+		expect(result).toBeNull()
+	})
+
+	it("should return null for playwright when browserProvider is agent-browser", () => {
+		// #given: browserProvider set to agent-browser
+		const options = { browserProvider: "agent-browser" as const }
+
+		// #when: resolving content for 'playwright'
+		const result = resolveSkillContent("playwright", options)
+
+		// #then: returns null because playwright is replaced by agent-browser
+		expect(result).toBeNull()
+	})
+})
+
+describe("resolveMultipleSkills with browserProvider", () => {
+	it("should resolve agent-browser when browserProvider is set", () => {
+		// #given: agent-browser and git-master requested with browserProvider
+		const skillNames = ["agent-browser", "git-master"]
+		const options = { browserProvider: "agent-browser" as const }
+
+		// #when: resolving multiple skills
+		const result = resolveMultipleSkills(skillNames, options)
+
+		// #then: both resolved
+		expect(result.resolved.has("agent-browser")).toBe(true)
+		expect(result.resolved.has("git-master")).toBe(true)
+		expect(result.notFound).toHaveLength(0)
+	})
+
+	it("should not resolve agent-browser without browserProvider option", () => {
+		// #given: agent-browser requested without browserProvider
+		const skillNames = ["agent-browser"]
+
+		// #when: resolving multiple skills
+		const result = resolveMultipleSkills(skillNames)
+
+		// #then: agent-browser not found
+		expect(result.resolved.has("agent-browser")).toBe(false)
+		expect(result.notFound).toContain("agent-browser")
+	})
+})

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

@@ -3,24 +3,27 @@ import { discoverSkills } from "./loader"
 import type { LoadedSkill } from "./types"
 import { parseFrontmatter } from "../../shared/frontmatter"
 import { readFileSync } from "node:fs"
-import type { GitMasterConfig } from "../../config/schema"
+import type { GitMasterConfig, BrowserAutomationProvider } from "../../config/schema"
 
 export interface SkillResolutionOptions {
 	gitMasterConfig?: GitMasterConfig
+	browserProvider?: BrowserAutomationProvider
 }
 
-let cachedSkills: LoadedSkill[] | null = null
+const cachedSkillsByProvider = new Map<string, LoadedSkill[]>()
 
 function clearSkillCache(): void {
-	cachedSkills = null
+	cachedSkillsByProvider.clear()
 }
 
-async function getAllSkills(): Promise<LoadedSkill[]> {
-	if (cachedSkills) return cachedSkills
+async function getAllSkills(options?: SkillResolutionOptions): Promise<LoadedSkill[]> {
+	const cacheKey = options?.browserProvider ?? "playwright"
+	const cached = cachedSkillsByProvider.get(cacheKey)
+	if (cached) return cached
 
 	const [discoveredSkills, builtinSkillDefs] = await Promise.all([
 		discoverSkills({ includeClaudeCodePaths: true }),
-		Promise.resolve(createBuiltinSkills()),
+		Promise.resolve(createBuiltinSkills({ browserProvider: options?.browserProvider })),
 	])
 
 	const builtinSkillsAsLoaded: LoadedSkill[] = builtinSkillDefs.map((skill) => ({
@@ -44,8 +47,9 @@ async function getAllSkills(): Promise<LoadedSkill[]> {
 	const discoveredNames = new Set(discoveredSkills.map((s) => s.name))
 	const uniqueBuiltins = builtinSkillsAsLoaded.filter((s) => !discoveredNames.has(s.name))
 
-	cachedSkills = [...discoveredSkills, ...uniqueBuiltins]
-	return cachedSkills
+	const allSkills = [...discoveredSkills, ...uniqueBuiltins]
+	cachedSkillsByProvider.set(cacheKey, allSkills)
+	return allSkills
 }
 
 async function extractSkillTemplate(skill: LoadedSkill): Promise<string> {
@@ -118,7 +122,7 @@ export function injectGitMasterConfig(template: string, config?: GitMasterConfig
 }
 
 export function resolveSkillContent(skillName: string, options?: SkillResolutionOptions): string | null {
-	const skills = createBuiltinSkills()
+	const skills = createBuiltinSkills({ browserProvider: options?.browserProvider })
 	const skill = skills.find((s) => s.name === skillName)
 	if (!skill) return null
 
@@ -133,7 +137,7 @@ export function resolveMultipleSkills(skillNames: string[], options?: SkillResol
 	resolved: Map<string, string>
 	notFound: string[]
 } {
-	const skills = createBuiltinSkills()
+	const skills = createBuiltinSkills({ browserProvider: options?.browserProvider })
 	const skillMap = new Map(skills.map((s) => [s.name, s.template]))
 
 	const resolved = new Map<string, string>()
@@ -159,7 +163,7 @@ export async function resolveSkillContentAsync(
 	skillName: string,
 	options?: SkillResolutionOptions
 ): Promise<string | null> {
-	const allSkills = await getAllSkills()
+	const allSkills = await getAllSkills(options)
 	const skill = allSkills.find((s) => s.name === skillName)
 	if (!skill) return null
 
@@ -179,7 +183,7 @@ export async function resolveMultipleSkillsAsync(
 	resolved: Map<string, string>
 	notFound: string[]
 }> {
-	const allSkills = await getAllSkills()
+	const allSkills = await getAllSkills(options)
 	const skillMap = new Map<string, LoadedSkill>()
 	for (const skill of allSkills) {
 		skillMap.set(skill.name, skill)

src/features/tmux-subagent/action-executor.ts

@@ -0,0 +1,97 @@
+import type { TmuxConfig } from "../../config/schema"
+import type { PaneAction, WindowState } from "./types"
+import { spawnTmuxPane, closeTmuxPane, enforceMainPaneWidth, replaceTmuxPane } from "../../shared/tmux"
+import { log } from "../../shared"
+
+export interface ActionResult {
+  success: boolean
+  paneId?: string
+  error?: string
+}
+
+export interface ExecuteActionsResult {
+  success: boolean
+  spawnedPaneId?: string
+  results: Array<{ action: PaneAction; result: ActionResult }>
+}
+
+export interface ExecuteContext {
+  config: TmuxConfig
+  serverUrl: string
+  windowState: WindowState
+}
+
+async function enforceMainPane(windowState: WindowState): Promise<void> {
+  if (!windowState.mainPane) return
+  await enforceMainPaneWidth(windowState.mainPane.paneId, windowState.windowWidth)
+}
+
+export async function executeAction(
+  action: PaneAction,
+  ctx: ExecuteContext
+): Promise<ActionResult> {
+  if (action.type === "close") {
+    const success = await closeTmuxPane(action.paneId)
+    if (success) {
+      await enforceMainPane(ctx.windowState)
+    }
+    return { success }
+  }
+
+  if (action.type === "replace") {
+    const result = await replaceTmuxPane(
+      action.paneId,
+      action.newSessionId,
+      action.description,
+      ctx.config,
+      ctx.serverUrl
+    )
+    return {
+      success: result.success,
+      paneId: result.paneId,
+    }
+  }
+
+  const result = await spawnTmuxPane(
+    action.sessionId,
+    action.description,
+    ctx.config,
+    ctx.serverUrl,
+    action.targetPaneId,
+    action.splitDirection
+  )
+
+  if (result.success) {
+    await enforceMainPane(ctx.windowState)
+  }
+
+  return {
+    success: result.success,
+    paneId: result.paneId,
+  }
+}
+
+export async function executeActions(
+  actions: PaneAction[],
+  ctx: ExecuteContext
+): Promise<ExecuteActionsResult> {
+  const results: Array<{ action: PaneAction; result: ActionResult }> = []
+  let spawnedPaneId: string | undefined
+
+  for (const action of actions) {
+    log("[action-executor] executing", { type: action.type })
+    const result = await executeAction(action, ctx)
+    results.push({ action, result })
+
+    if (!result.success) {
+      log("[action-executor] action failed", { type: action.type, error: result.error })
+      return { success: false, results }
+    }
+
+    if ((action.type === "spawn" || action.type === "replace") && result.paneId) {
+      spawnedPaneId = result.paneId
+    }
+  }
+
+  return { success: true, spawnedPaneId, results }
+}

src/features/tmux-subagent/decision-engine.test.ts

@@ -0,0 +1,354 @@
+import { describe, it, expect } from "bun:test"
+import { 
+  decideSpawnActions, 
+  calculateCapacity, 
+  canSplitPane, 
+  canSplitPaneAnyDirection,
+  getBestSplitDirection,
+  type SessionMapping 
+} from "./decision-engine"
+import type { WindowState, CapacityConfig, TmuxPaneInfo } from "./types"
+import { MIN_PANE_WIDTH, MIN_PANE_HEIGHT } from "./types"
+
+const MIN_SPLIT_WIDTH = 2 * MIN_PANE_WIDTH + 1
+const MIN_SPLIT_HEIGHT = 2 * MIN_PANE_HEIGHT + 1
+
+describe("canSplitPane", () => {
+  const createPane = (width: number, height: number): TmuxPaneInfo => ({
+    paneId: "%1",
+    width,
+    height,
+    left: 100,
+    top: 0,
+    title: "test",
+    isActive: false,
+  })
+
+  it("returns true for horizontal split when width >= 2*MIN+1", () => {
+    //#given - pane with exactly minimum splittable width (107)
+    const pane = createPane(MIN_SPLIT_WIDTH, 20)
+
+    //#when
+    const result = canSplitPane(pane, "-h")
+
+    //#then
+    expect(result).toBe(true)
+  })
+
+  it("returns false for horizontal split when width < 2*MIN+1", () => {
+    //#given - pane just below minimum splittable width
+    const pane = createPane(MIN_SPLIT_WIDTH - 1, 20)
+
+    //#when
+    const result = canSplitPane(pane, "-h")
+
+    //#then
+    expect(result).toBe(false)
+  })
+
+  it("returns true for vertical split when height >= 2*MIN+1", () => {
+    //#given - pane with exactly minimum splittable height (23)
+    const pane = createPane(50, MIN_SPLIT_HEIGHT)
+
+    //#when
+    const result = canSplitPane(pane, "-v")
+
+    //#then
+    expect(result).toBe(true)
+  })
+
+  it("returns false for vertical split when height < 2*MIN+1", () => {
+    //#given - pane just below minimum splittable height
+    const pane = createPane(50, MIN_SPLIT_HEIGHT - 1)
+
+    //#when
+    const result = canSplitPane(pane, "-v")
+
+    //#then
+    expect(result).toBe(false)
+  })
+})
+
+describe("canSplitPaneAnyDirection", () => {
+  const createPane = (width: number, height: number): TmuxPaneInfo => ({
+    paneId: "%1",
+    width,
+    height,
+    left: 100,
+    top: 0,
+    title: "test",
+    isActive: false,
+  })
+
+  it("returns true when can split horizontally but not vertically", () => {
+    //#given
+    const pane = createPane(MIN_SPLIT_WIDTH, MIN_SPLIT_HEIGHT - 1)
+
+    //#when
+    const result = canSplitPaneAnyDirection(pane)
+
+    //#then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when can split vertically but not horizontally", () => {
+    //#given
+    const pane = createPane(MIN_SPLIT_WIDTH - 1, MIN_SPLIT_HEIGHT)
+
+    //#when
+    const result = canSplitPaneAnyDirection(pane)
+
+    //#then
+    expect(result).toBe(true)
+  })
+
+  it("returns false when cannot split in any direction", () => {
+    //#given - pane too small in both dimensions
+    const pane = createPane(MIN_SPLIT_WIDTH - 1, MIN_SPLIT_HEIGHT - 1)
+
+    //#when
+    const result = canSplitPaneAnyDirection(pane)
+
+    //#then
+    expect(result).toBe(false)
+  })
+})
+
+describe("getBestSplitDirection", () => {
+  const createPane = (width: number, height: number): TmuxPaneInfo => ({
+    paneId: "%1",
+    width,
+    height,
+    left: 100,
+    top: 0,
+    title: "test",
+    isActive: false,
+  })
+
+  it("returns -h when only horizontal split possible", () => {
+    //#given
+    const pane = createPane(MIN_SPLIT_WIDTH, MIN_SPLIT_HEIGHT - 1)
+
+    //#when
+    const result = getBestSplitDirection(pane)
+
+    //#then
+    expect(result).toBe("-h")
+  })
+
+  it("returns -v when only vertical split possible", () => {
+    //#given
+    const pane = createPane(MIN_SPLIT_WIDTH - 1, MIN_SPLIT_HEIGHT)
+
+    //#when
+    const result = getBestSplitDirection(pane)
+
+    //#then
+    expect(result).toBe("-v")
+  })
+
+  it("returns null when no split possible", () => {
+    //#given
+    const pane = createPane(MIN_SPLIT_WIDTH - 1, MIN_SPLIT_HEIGHT - 1)
+
+    //#when
+    const result = getBestSplitDirection(pane)
+
+    //#then
+    expect(result).toBe(null)
+  })
+
+  it("returns -h when width >= height and both splits possible", () => {
+    //#given - wider than tall
+    const pane = createPane(MIN_SPLIT_WIDTH + 10, MIN_SPLIT_HEIGHT)
+
+    //#when
+    const result = getBestSplitDirection(pane)
+
+    //#then
+    expect(result).toBe("-h")
+  })
+
+  it("returns -v when height > width and both splits possible", () => {
+    //#given - taller than wide (height needs to be > width for -v)
+    const pane = createPane(MIN_SPLIT_WIDTH, MIN_SPLIT_WIDTH + 10)
+
+    //#when
+    const result = getBestSplitDirection(pane)
+
+    //#then
+    expect(result).toBe("-v")
+  })
+})
+
+describe("decideSpawnActions", () => {
+  const defaultConfig: CapacityConfig = {
+    mainPaneMinWidth: 120,
+    agentPaneWidth: 40,
+  }
+
+  const createWindowState = (
+    windowWidth: number,
+    windowHeight: number,
+    agentPanes: Array<{ paneId: string; width: number; height: number; left: number; top: number }> = []
+  ): WindowState => ({
+    windowWidth,
+    windowHeight,
+    mainPane: { paneId: "%0", width: Math.floor(windowWidth / 2), height: windowHeight, left: 0, top: 0, title: "main", isActive: true },
+    agentPanes: agentPanes.map((p, i) => ({
+      ...p,
+      title: `agent-${i}`,
+      isActive: false,
+    })),
+  })
+
+  describe("minimum size enforcement", () => {
+    it("returns canSpawn=false when window too small", () => {
+      //#given - window smaller than minimum pane size
+      const state = createWindowState(50, 5)
+
+      //#when
+      const result = decideSpawnActions(state, "ses1", "test", defaultConfig, [])
+
+      //#then
+      expect(result.canSpawn).toBe(false)
+      expect(result.reason).toContain("too small")
+    })
+
+    it("returns canSpawn=true when main pane can be split", () => {
+      //#given - main pane width >= 2*MIN_PANE_WIDTH+1 = 107
+      const state = createWindowState(220, 44)
+
+      //#when
+      const result = decideSpawnActions(state, "ses1", "test", defaultConfig, [])
+
+      //#then
+      expect(result.canSpawn).toBe(true)
+      expect(result.actions.length).toBe(1)
+      expect(result.actions[0].type).toBe("spawn")
+    })
+
+    it("closes oldest pane when existing panes are too small to split", () => {
+      //#given - existing pane is below minimum splittable size
+      const state = createWindowState(220, 30, [
+        { paneId: "%1", width: 50, height: 15, left: 110, top: 0 },
+      ])
+      const mappings: SessionMapping[] = [
+        { sessionId: "old-ses", paneId: "%1", createdAt: new Date("2024-01-01") },
+      ]
+
+      //#when
+      const result = decideSpawnActions(state, "ses1", "test", defaultConfig, mappings)
+
+      //#then
+      expect(result.canSpawn).toBe(true)
+      expect(result.actions.length).toBe(2)
+      expect(result.actions[0].type).toBe("close")
+      expect(result.actions[1].type).toBe("spawn")
+    })
+
+    it("can spawn when existing pane is large enough to split", () => {
+      //#given - existing pane is above minimum splittable size
+      const state = createWindowState(320, 50, [
+        { paneId: "%1", width: MIN_SPLIT_WIDTH + 10, height: MIN_SPLIT_HEIGHT + 10, left: 160, top: 0 },
+      ])
+
+      //#when
+      const result = decideSpawnActions(state, "ses1", "test", defaultConfig, [])
+
+      //#then
+      expect(result.canSpawn).toBe(true)
+      expect(result.actions.length).toBe(1)
+      expect(result.actions[0].type).toBe("spawn")
+    })
+  })
+
+  describe("basic spawn decisions", () => {
+    it("returns canSpawn=true when capacity allows new pane", () => {
+      //#given - 220x44 window, mainPane width=110 >= MIN_SPLIT_WIDTH(107)
+      const state = createWindowState(220, 44)
+
+      //#when
+      const result = decideSpawnActions(state, "ses1", "test", defaultConfig, [])
+
+      //#then
+      expect(result.canSpawn).toBe(true)
+      expect(result.actions.length).toBe(1)
+      expect(result.actions[0].type).toBe("spawn")
+    })
+
+    it("spawns with splitDirection", () => {
+      //#given
+      const state = createWindowState(212, 44, [
+        { paneId: "%1", width: MIN_SPLIT_WIDTH, height: MIN_SPLIT_HEIGHT, left: 106, top: 0 },
+      ])
+
+      //#when
+      const result = decideSpawnActions(state, "ses1", "test", defaultConfig, [])
+
+      //#then
+      expect(result.canSpawn).toBe(true)
+      expect(result.actions[0].type).toBe("spawn")
+      if (result.actions[0].type === "spawn") {
+        expect(result.actions[0].sessionId).toBe("ses1")
+        expect(result.actions[0].splitDirection).toBeDefined()
+      }
+    })
+
+    it("returns canSpawn=false when no main pane", () => {
+      //#given
+      const state: WindowState = { windowWidth: 212, windowHeight: 44, mainPane: null, agentPanes: [] }
+
+      //#when
+      const result = decideSpawnActions(state, "ses1", "test", defaultConfig, [])
+
+      //#then
+      expect(result.canSpawn).toBe(false)
+      expect(result.reason).toBe("no main pane found")
+    })
+  })
+})
+
+describe("calculateCapacity", () => {
+  it("calculates 2D grid capacity (cols x rows)", () => {
+    //#given - 212x44 window (user's actual screen)
+    //#when
+    const capacity = calculateCapacity(212, 44)
+
+    //#then - availableWidth=106, cols=(106+1)/(52+1)=2, rows=(44+1)/(11+1)=3 (accounting for dividers)
+    expect(capacity.cols).toBe(2)
+    expect(capacity.rows).toBe(3)
+    expect(capacity.total).toBe(6)
+  })
+
+  it("returns 0 cols when agent area too narrow", () => {
+    //#given - window too narrow for even 1 agent pane
+    //#when
+    const capacity = calculateCapacity(100, 44)
+
+    //#then - availableWidth=50, cols=50/53=0
+    expect(capacity.cols).toBe(0)
+    expect(capacity.total).toBe(0)
+  })
+
+  it("returns 0 rows when window too short", () => {
+    //#given - window too short
+    //#when
+    const capacity = calculateCapacity(212, 10)
+
+    //#then - rows=10/11=0
+    expect(capacity.rows).toBe(0)
+    expect(capacity.total).toBe(0)
+  })
+
+  it("scales with larger screens but caps at MAX_GRID_SIZE=4", () => {
+    //#given - larger 4K-like screen (400x100)
+    //#when
+    const capacity = calculateCapacity(400, 100)
+
+    //#then - cols capped at 4, rows capped at 4 (MAX_GRID_SIZE)
+    expect(capacity.cols).toBe(3)
+    expect(capacity.rows).toBe(4)
+    expect(capacity.total).toBe(12)
+  })
+})

src/features/tmux-subagent/decision-engine.ts

@@ -0,0 +1,386 @@
+import type { WindowState, PaneAction, SpawnDecision, CapacityConfig, TmuxPaneInfo, SplitDirection } from "./types"
+import { MIN_PANE_WIDTH, MIN_PANE_HEIGHT } from "./types"
+
+export interface SessionMapping {
+  sessionId: string
+  paneId: string
+  createdAt: Date
+}
+
+export interface GridCapacity {
+  cols: number
+  rows: number
+  total: number
+}
+
+export interface GridSlot {
+  row: number
+  col: number
+}
+
+export interface GridPlan {
+  cols: number
+  rows: number
+  slotWidth: number
+  slotHeight: number
+}
+
+export interface SpawnTarget {
+  targetPaneId: string
+  splitDirection: SplitDirection
+}
+
+const MAIN_PANE_RATIO = 0.5
+const MAX_COLS = 2
+const MAX_ROWS = 3
+const MAX_GRID_SIZE = 4
+const DIVIDER_SIZE = 1
+const MIN_SPLIT_WIDTH = 2 * MIN_PANE_WIDTH + DIVIDER_SIZE
+const MIN_SPLIT_HEIGHT = 2 * MIN_PANE_HEIGHT + DIVIDER_SIZE
+
+export function getColumnCount(paneCount: number): number {
+  if (paneCount <= 0) return 1
+  return Math.min(MAX_COLS, Math.max(1, Math.ceil(paneCount / MAX_ROWS)))
+}
+
+export function getColumnWidth(agentAreaWidth: number, paneCount: number): number {
+  const cols = getColumnCount(paneCount)
+  const dividersWidth = (cols - 1) * DIVIDER_SIZE
+  return Math.floor((agentAreaWidth - dividersWidth) / cols)
+}
+
+export function isSplittableAtCount(agentAreaWidth: number, paneCount: number): boolean {
+  const columnWidth = getColumnWidth(agentAreaWidth, paneCount)
+  return columnWidth >= MIN_SPLIT_WIDTH
+}
+
+export function findMinimalEvictions(agentAreaWidth: number, currentCount: number): number | null {
+  for (let k = 1; k <= currentCount; k++) {
+    if (isSplittableAtCount(agentAreaWidth, currentCount - k)) {
+      return k
+    }
+  }
+  return null
+}
+
+export function canSplitPane(pane: TmuxPaneInfo, direction: SplitDirection): boolean {
+  if (direction === "-h") {
+    return pane.width >= MIN_SPLIT_WIDTH
+  }
+  return pane.height >= MIN_SPLIT_HEIGHT
+}
+
+export function canSplitPaneAnyDirection(pane: TmuxPaneInfo): boolean {
+  return pane.width >= MIN_SPLIT_WIDTH || pane.height >= MIN_SPLIT_HEIGHT
+}
+
+export function getBestSplitDirection(pane: TmuxPaneInfo): SplitDirection | null {
+  const canH = pane.width >= MIN_SPLIT_WIDTH
+  const canV = pane.height >= MIN_SPLIT_HEIGHT
+  
+  if (!canH && !canV) return null
+  if (canH && !canV) return "-h"
+  if (!canH && canV) return "-v"
+  return pane.width >= pane.height ? "-h" : "-v"
+}
+
+export function calculateCapacity(
+  windowWidth: number,
+  windowHeight: number
+): GridCapacity {
+  const availableWidth = Math.floor(windowWidth * (1 - MAIN_PANE_RATIO))
+  const cols = Math.min(MAX_GRID_SIZE, Math.max(0, Math.floor((availableWidth + DIVIDER_SIZE) / (MIN_PANE_WIDTH + DIVIDER_SIZE))))
+  const rows = Math.min(MAX_GRID_SIZE, Math.max(0, Math.floor((windowHeight + DIVIDER_SIZE) / (MIN_PANE_HEIGHT + DIVIDER_SIZE))))
+  const total = cols * rows
+  return { cols, rows, total }
+}
+
+export function computeGridPlan(
+  windowWidth: number,
+  windowHeight: number,
+  paneCount: number
+): GridPlan {
+  const capacity = calculateCapacity(windowWidth, windowHeight)
+  const { cols: maxCols, rows: maxRows } = capacity
+  
+  if (maxCols === 0 || maxRows === 0 || paneCount === 0) {
+    return { cols: 1, rows: 1, slotWidth: 0, slotHeight: 0 }
+  }
+
+  let bestCols = 1
+  let bestRows = 1
+  let bestArea = Infinity
+
+  for (let rows = 1; rows <= maxRows; rows++) {
+    for (let cols = 1; cols <= maxCols; cols++) {
+      if (cols * rows >= paneCount) {
+        const area = cols * rows
+        if (area < bestArea || (area === bestArea && rows < bestRows)) {
+          bestCols = cols
+          bestRows = rows
+          bestArea = area
+        }
+      }
+    }
+  }
+
+  const availableWidth = Math.floor(windowWidth * (1 - MAIN_PANE_RATIO))
+  const slotWidth = Math.floor(availableWidth / bestCols)
+  const slotHeight = Math.floor(windowHeight / bestRows)
+
+  return { cols: bestCols, rows: bestRows, slotWidth, slotHeight }
+}
+
+export function mapPaneToSlot(
+  pane: TmuxPaneInfo,
+  plan: GridPlan,
+  mainPaneWidth: number
+): GridSlot {
+  const rightAreaX = mainPaneWidth
+  const relativeX = Math.max(0, pane.left - rightAreaX)
+  const relativeY = pane.top
+
+  const col = plan.slotWidth > 0 
+    ? Math.min(plan.cols - 1, Math.floor(relativeX / plan.slotWidth))
+    : 0
+  const row = plan.slotHeight > 0
+    ? Math.min(plan.rows - 1, Math.floor(relativeY / plan.slotHeight))
+    : 0
+
+  return { row, col }
+}
+
+function buildOccupancy(
+  agentPanes: TmuxPaneInfo[],
+  plan: GridPlan,
+  mainPaneWidth: number
+): Map<string, TmuxPaneInfo> {
+  const occupancy = new Map<string, TmuxPaneInfo>()
+  for (const pane of agentPanes) {
+    const slot = mapPaneToSlot(pane, plan, mainPaneWidth)
+    const key = `${slot.row}:${slot.col}`
+    occupancy.set(key, pane)
+  }
+  return occupancy
+}
+
+function findFirstEmptySlot(
+  occupancy: Map<string, TmuxPaneInfo>,
+  plan: GridPlan
+): GridSlot {
+  for (let row = 0; row < plan.rows; row++) {
+    for (let col = 0; col < plan.cols; col++) {
+      const key = `${row}:${col}`
+      if (!occupancy.has(key)) {
+        return { row, col }
+      }
+    }
+  }
+  return { row: plan.rows - 1, col: plan.cols - 1 }
+}
+
+function findSplittableTarget(
+  state: WindowState,
+  preferredDirection?: SplitDirection
+): SpawnTarget | null {
+  if (!state.mainPane) return null
+
+  const existingCount = state.agentPanes.length
+
+  if (existingCount === 0) {
+    const virtualMainPane: TmuxPaneInfo = {
+      ...state.mainPane,
+      width: state.windowWidth,
+    }
+    if (canSplitPane(virtualMainPane, "-h")) {
+      return { targetPaneId: state.mainPane.paneId, splitDirection: "-h" }
+    }
+    return null
+  }
+
+  const plan = computeGridPlan(state.windowWidth, state.windowHeight, existingCount + 1)
+  const mainPaneWidth = Math.floor(state.windowWidth * MAIN_PANE_RATIO)
+  const occupancy = buildOccupancy(state.agentPanes, plan, mainPaneWidth)
+  const targetSlot = findFirstEmptySlot(occupancy, plan)
+
+  const leftKey = `${targetSlot.row}:${targetSlot.col - 1}`
+  const leftPane = occupancy.get(leftKey)
+  if (leftPane && canSplitPane(leftPane, "-h")) {
+    return { targetPaneId: leftPane.paneId, splitDirection: "-h" }
+  }
+
+  const aboveKey = `${targetSlot.row - 1}:${targetSlot.col}`
+  const abovePane = occupancy.get(aboveKey)
+  if (abovePane && canSplitPane(abovePane, "-v")) {
+    return { targetPaneId: abovePane.paneId, splitDirection: "-v" }
+  }
+
+  const splittablePanes = state.agentPanes
+    .map(p => ({ pane: p, direction: getBestSplitDirection(p) }))
+    .filter(({ direction }) => direction !== null)
+    .sort((a, b) => (b.pane.width * b.pane.height) - (a.pane.width * a.pane.height))
+
+  if (splittablePanes.length > 0) {
+    const best = splittablePanes[0]
+    return { targetPaneId: best.pane.paneId, splitDirection: best.direction! }
+  }
+
+  return null
+}
+
+export function findSpawnTarget(state: WindowState): SpawnTarget | null {
+  return findSplittableTarget(state)
+}
+
+function findOldestSession(mappings: SessionMapping[]): SessionMapping | null {
+  if (mappings.length === 0) return null
+  return mappings.reduce((oldest, current) =>
+    current.createdAt < oldest.createdAt ? current : oldest
+  )
+}
+
+function findOldestAgentPane(
+  agentPanes: TmuxPaneInfo[],
+  sessionMappings: SessionMapping[]
+): TmuxPaneInfo | null {
+  if (agentPanes.length === 0) return null
+  
+  const paneIdToAge = new Map<string, Date>()
+  for (const mapping of sessionMappings) {
+    paneIdToAge.set(mapping.paneId, mapping.createdAt)
+  }
+  
+  const panesWithAge = agentPanes
+    .map(p => ({ pane: p, age: paneIdToAge.get(p.paneId) }))
+    .filter(({ age }) => age !== undefined)
+    .sort((a, b) => a.age!.getTime() - b.age!.getTime())
+  
+  if (panesWithAge.length > 0) {
+    return panesWithAge[0].pane
+  }
+  
+  return agentPanes.reduce((oldest, p) => {
+    if (p.top < oldest.top || (p.top === oldest.top && p.left < oldest.left)) {
+      return p
+    }
+    return oldest
+  })
+}
+
+export function decideSpawnActions(
+  state: WindowState,
+  sessionId: string,
+  description: string,
+  _config: CapacityConfig,
+  sessionMappings: SessionMapping[]
+): SpawnDecision {
+  if (!state.mainPane) {
+    return { canSpawn: false, actions: [], reason: "no main pane found" }
+  }
+
+  const agentAreaWidth = Math.floor(state.windowWidth * (1 - MAIN_PANE_RATIO))
+  const currentCount = state.agentPanes.length
+
+  if (agentAreaWidth < MIN_PANE_WIDTH) {
+    return {
+      canSpawn: false,
+      actions: [],
+      reason: `window too small for agent panes: ${state.windowWidth}x${state.windowHeight}`,
+    }
+  }
+
+  const oldestPane = findOldestAgentPane(state.agentPanes, sessionMappings)
+  const oldestMapping = oldestPane 
+    ? sessionMappings.find(m => m.paneId === oldestPane.paneId)
+    : null
+
+  if (currentCount === 0) {
+    const virtualMainPane: TmuxPaneInfo = { ...state.mainPane, width: state.windowWidth }
+    if (canSplitPane(virtualMainPane, "-h")) {
+      return {
+        canSpawn: true,
+        actions: [{
+          type: "spawn",
+          sessionId,
+          description,
+          targetPaneId: state.mainPane.paneId,
+          splitDirection: "-h"
+        }]
+      }
+    }
+    return { canSpawn: false, actions: [], reason: "mainPane too small to split" }
+  }
+
+  if (isSplittableAtCount(agentAreaWidth, currentCount)) {
+    const spawnTarget = findSplittableTarget(state)
+    if (spawnTarget) {
+      return {
+        canSpawn: true,
+        actions: [{
+          type: "spawn",
+          sessionId,
+          description,
+          targetPaneId: spawnTarget.targetPaneId,
+          splitDirection: spawnTarget.splitDirection
+        }]
+      }
+    }
+  }
+
+  const minEvictions = findMinimalEvictions(agentAreaWidth, currentCount)
+
+  if (minEvictions === 1 && oldestPane) {
+    return {
+      canSpawn: true,
+      actions: [
+        {
+          type: "close",
+          paneId: oldestPane.paneId,
+          sessionId: oldestMapping?.sessionId || ""
+        },
+        {
+          type: "spawn",
+          sessionId,
+          description,
+          targetPaneId: state.mainPane.paneId,
+          splitDirection: "-h"
+        }
+      ],
+      reason: "closed 1 pane to make room for split"
+    }
+  }
+
+  if (oldestPane) {
+    return {
+      canSpawn: true,
+      actions: [{
+        type: "replace",
+        paneId: oldestPane.paneId,
+        oldSessionId: oldestMapping?.sessionId || "",
+        newSessionId: sessionId,
+        description
+      }],
+      reason: "replaced oldest pane (no split possible)"
+    }
+  }
+
+  return {
+    canSpawn: false,
+    actions: [],
+    reason: "no pane available to replace"
+  }
+}
+
+export function decideCloseAction(
+  state: WindowState,
+  sessionId: string,
+  sessionMappings: SessionMapping[]
+): PaneAction | null {
+  const mapping = sessionMappings.find((m) => m.sessionId === sessionId)
+  if (!mapping) return null
+
+  const paneExists = state.agentPanes.some((p) => p.paneId === mapping.paneId)
+  if (!paneExists) return null
+
+  return { type: "close", paneId: mapping.paneId, sessionId }
+}

src/features/tmux-subagent/index.ts

@@ -0,0 +1,5 @@
+export * from "./manager"
+export * from "./types"
+export * from "./pane-state-querier"
+export * from "./decision-engine"
+export * from "./action-executor"

src/features/tmux-subagent/manager.test.ts

@@ -0,0 +1,690 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test'
+import type { TmuxConfig } from '../../config/schema'
+import type { WindowState, PaneAction } from './types'
+import type { ActionResult, ExecuteContext } from './action-executor'
+
+type ExecuteActionsResult = {
+  success: boolean
+  spawnedPaneId?: string
+  results: Array<{ action: PaneAction; result: ActionResult }>
+}
+
+const mockQueryWindowState = mock<(paneId: string) => Promise<WindowState | null>>(
+  async () => ({
+    windowWidth: 212,
+    windowHeight: 44,
+    mainPane: { paneId: '%0', width: 106, height: 44, left: 0, top: 0, title: 'main', isActive: true },
+    agentPanes: [],
+  })
+)
+const mockPaneExists = mock<(paneId: string) => Promise<boolean>>(async () => true)
+const mockExecuteActions = mock<(
+  actions: PaneAction[],
+  ctx: ExecuteContext
+) => Promise<ExecuteActionsResult>>(async () => ({
+  success: true,
+  spawnedPaneId: '%mock',
+  results: [],
+}))
+const mockExecuteAction = mock<(
+  action: PaneAction,
+  ctx: ExecuteContext
+) => Promise<ActionResult>>(async () => ({ success: true }))
+const mockIsInsideTmux = mock<() => boolean>(() => true)
+const mockGetCurrentPaneId = mock<() => string | undefined>(() => '%0')
+
+mock.module('./pane-state-querier', () => ({
+  queryWindowState: mockQueryWindowState,
+  paneExists: mockPaneExists,
+  getRightmostAgentPane: (state: WindowState) =>
+    state.agentPanes.length > 0
+      ? state.agentPanes.reduce((r, p) => (p.left > r.left ? p : r))
+      : null,
+  getOldestAgentPane: (state: WindowState) =>
+    state.agentPanes.length > 0
+      ? state.agentPanes.reduce((o, p) => (p.left < o.left ? p : o))
+      : null,
+}))
+
+mock.module('./action-executor', () => ({
+  executeActions: mockExecuteActions,
+  executeAction: mockExecuteAction,
+}))
+
+mock.module('../../shared/tmux', () => ({
+  isInsideTmux: mockIsInsideTmux,
+  getCurrentPaneId: mockGetCurrentPaneId,
+  POLL_INTERVAL_BACKGROUND_MS: 2000,
+  SESSION_TIMEOUT_MS: 600000,
+  SESSION_MISSING_GRACE_MS: 6000,
+  SESSION_READY_POLL_INTERVAL_MS: 100,
+  SESSION_READY_TIMEOUT_MS: 500,
+}))
+
+const trackedSessions = new Set<string>()
+
+function createMockContext(overrides?: {
+  sessionStatusResult?: { data?: Record<string, { type: string }> }
+}) {
+  return {
+    serverUrl: new URL('http://localhost:4096'),
+    client: {
+      session: {
+        status: mock(async () => {
+          if (overrides?.sessionStatusResult) {
+            return overrides.sessionStatusResult
+          }
+          const data: Record<string, { type: string }> = {}
+          for (const sessionId of trackedSessions) {
+            data[sessionId] = { type: 'running' }
+          }
+          return { data }
+        }),
+      },
+    },
+  } as any
+}
+
+function createSessionCreatedEvent(
+  id: string,
+  parentID: string | undefined,
+  title: string
+) {
+  return {
+    type: 'session.created',
+    properties: {
+      info: { id, parentID, title },
+    },
+  }
+}
+
+function createWindowState(overrides?: Partial<WindowState>): WindowState {
+  return {
+    windowWidth: 220,
+    windowHeight: 44,
+    mainPane: { paneId: '%0', width: 110, height: 44, left: 0, top: 0, title: 'main', isActive: true },
+    agentPanes: [],
+    ...overrides,
+  }
+}
+
+describe('TmuxSessionManager', () => {
+  beforeEach(() => {
+    mockQueryWindowState.mockClear()
+    mockPaneExists.mockClear()
+    mockExecuteActions.mockClear()
+    mockExecuteAction.mockClear()
+    mockIsInsideTmux.mockClear()
+    mockGetCurrentPaneId.mockClear()
+    trackedSessions.clear()
+
+    mockQueryWindowState.mockImplementation(async () => createWindowState())
+    mockExecuteActions.mockImplementation(async (actions) => {
+      for (const action of actions) {
+        if (action.type === 'spawn') {
+          trackedSessions.add(action.sessionId)
+        }
+      }
+      return {
+        success: true,
+        spawnedPaneId: '%mock',
+        results: [],
+      }
+    })
+  })
+
+  describe('constructor', () => {
+    test('enabled when config.enabled=true and isInsideTmux=true', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+
+      //#when
+      const manager = new TmuxSessionManager(ctx, config)
+
+      //#then
+      expect(manager).toBeDefined()
+    })
+
+    test('disabled when config.enabled=true but isInsideTmux=false', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(false)
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+
+      //#when
+      const manager = new TmuxSessionManager(ctx, config)
+
+      //#then
+      expect(manager).toBeDefined()
+    })
+
+    test('disabled when config.enabled=false', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: false,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+
+      //#when
+      const manager = new TmuxSessionManager(ctx, config)
+
+      //#then
+      expect(manager).toBeDefined()
+    })
+  })
+
+  describe('onSessionCreated', () => {
+    test('first agent spawns from source pane via decision engine', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+      mockQueryWindowState.mockImplementation(async () => createWindowState())
+
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+      const event = createSessionCreatedEvent(
+        'ses_child',
+        'ses_parent',
+        'Background: Test Task'
+      )
+
+      //#when
+      await manager.onSessionCreated(event)
+
+      //#then
+      expect(mockQueryWindowState).toHaveBeenCalledTimes(1)
+      expect(mockExecuteActions).toHaveBeenCalledTimes(1)
+
+      const call = mockExecuteActions.mock.calls[0]
+      expect(call).toBeDefined()
+      const actionsArg = call![0]
+      expect(actionsArg).toHaveLength(1)
+      expect(actionsArg[0].type).toBe('spawn')
+      if (actionsArg[0].type === 'spawn') {
+        expect(actionsArg[0].sessionId).toBe('ses_child')
+        expect(actionsArg[0].description).toBe('Background: Test Task')
+        expect(actionsArg[0].targetPaneId).toBe('%0')
+        expect(actionsArg[0].splitDirection).toBe('-h')
+      }
+    })
+
+    test('second agent spawns with correct split direction', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+
+      let callCount = 0
+      mockQueryWindowState.mockImplementation(async () => {
+        callCount++
+        if (callCount === 1) {
+          return createWindowState()
+        }
+        return createWindowState({
+          agentPanes: [
+            {
+              paneId: '%1',
+              width: 40,
+              height: 44,
+              left: 100,
+              top: 0,
+              title: 'omo-subagent-Task 1',
+              isActive: false,
+            },
+          ],
+        })
+      })
+
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+
+      //#when - first agent
+      await manager.onSessionCreated(
+        createSessionCreatedEvent('ses_1', 'ses_parent', 'Task 1')
+      )
+      mockExecuteActions.mockClear()
+
+      //#when - second agent
+      await manager.onSessionCreated(
+        createSessionCreatedEvent('ses_2', 'ses_parent', 'Task 2')
+      )
+
+      //#then
+      expect(mockExecuteActions).toHaveBeenCalledTimes(1)
+      const call = mockExecuteActions.mock.calls[0]
+      expect(call).toBeDefined()
+      const actionsArg = call![0]
+      expect(actionsArg).toHaveLength(1)
+      expect(actionsArg[0].type).toBe('spawn')
+    })
+
+    test('does NOT spawn pane when session has no parentID', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+      const event = createSessionCreatedEvent('ses_root', undefined, 'Root Session')
+
+      //#when
+      await manager.onSessionCreated(event)
+
+      //#then
+      expect(mockExecuteActions).toHaveBeenCalledTimes(0)
+    })
+
+    test('does NOT spawn pane when disabled', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: false,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+      const event = createSessionCreatedEvent(
+        'ses_child',
+        'ses_parent',
+        'Background: Test Task'
+      )
+
+      //#when
+      await manager.onSessionCreated(event)
+
+      //#then
+      expect(mockExecuteActions).toHaveBeenCalledTimes(0)
+    })
+
+    test('does NOT spawn pane for non session.created event type', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+      const event = {
+        type: 'session.deleted',
+        properties: {
+          info: { id: 'ses_child', parentID: 'ses_parent', title: 'Task' },
+        },
+      }
+
+      //#when
+      await manager.onSessionCreated(event)
+
+      //#then
+      expect(mockExecuteActions).toHaveBeenCalledTimes(0)
+    })
+
+    test('replaces oldest agent when unsplittable (small window)', async () => {
+      //#given - small window where split is not possible
+      mockIsInsideTmux.mockReturnValue(true)
+      mockQueryWindowState.mockImplementation(async () =>
+        createWindowState({
+          windowWidth: 160,
+          windowHeight: 11,
+          agentPanes: [
+            {
+              paneId: '%1',
+              width: 40,
+              height: 11,
+              left: 80,
+              top: 0,
+              title: 'omo-subagent-Task 1',
+              isActive: false,
+            },
+          ],
+        })
+      )
+
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 120,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+
+      //#when
+      await manager.onSessionCreated(
+        createSessionCreatedEvent('ses_new', 'ses_parent', 'New Task')
+      )
+
+      //#then - with small window, replace action is used instead of close+spawn
+      expect(mockExecuteActions).toHaveBeenCalledTimes(1)
+      const call = mockExecuteActions.mock.calls[0]
+      expect(call).toBeDefined()
+      const actionsArg = call![0]
+      expect(actionsArg).toHaveLength(1)
+      expect(actionsArg[0].type).toBe('replace')
+    })
+  })
+
+  describe('onSessionDeleted', () => {
+    test('closes pane when tracked session is deleted', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+
+      let stateCallCount = 0
+      mockQueryWindowState.mockImplementation(async () => {
+        stateCallCount++
+        if (stateCallCount === 1) {
+          return createWindowState()
+        }
+        return createWindowState({
+          agentPanes: [
+            {
+              paneId: '%mock',
+              width: 40,
+              height: 44,
+              left: 100,
+              top: 0,
+              title: 'omo-subagent-Task',
+              isActive: false,
+            },
+          ],
+        })
+      })
+
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+
+      await manager.onSessionCreated(
+        createSessionCreatedEvent(
+          'ses_child',
+          'ses_parent',
+          'Background: Test Task'
+        )
+      )
+      mockExecuteAction.mockClear()
+
+      //#when
+      await manager.onSessionDeleted({ sessionID: 'ses_child' })
+
+      //#then
+      expect(mockExecuteAction).toHaveBeenCalledTimes(1)
+      const call = mockExecuteAction.mock.calls[0]
+      expect(call).toBeDefined()
+      expect(call![0]).toEqual({
+        type: 'close',
+        paneId: '%mock',
+        sessionId: 'ses_child',
+      })
+    })
+
+    test('does nothing when untracked session is deleted', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+
+      //#when
+      await manager.onSessionDeleted({ sessionID: 'ses_unknown' })
+
+      //#then
+      expect(mockExecuteAction).toHaveBeenCalledTimes(0)
+    })
+  })
+
+  describe('cleanup', () => {
+    test('closes all tracked panes', async () => {
+      //#given
+      mockIsInsideTmux.mockReturnValue(true)
+
+      let callCount = 0
+      mockExecuteActions.mockImplementation(async () => {
+        callCount++
+        return {
+          success: true,
+          spawnedPaneId: `%${callCount}`,
+          results: [],
+        }
+      })
+
+      const { TmuxSessionManager } = await import('./manager')
+      const ctx = createMockContext()
+      const config: TmuxConfig = {
+        enabled: true,
+        layout: 'main-vertical',
+        main_pane_size: 60,
+        main_pane_min_width: 80,
+        agent_pane_min_width: 40,
+      }
+      const manager = new TmuxSessionManager(ctx, config)
+
+      await manager.onSessionCreated(
+        createSessionCreatedEvent('ses_1', 'ses_parent', 'Task 1')
+      )
+      await manager.onSessionCreated(
+        createSessionCreatedEvent('ses_2', 'ses_parent', 'Task 2')
+      )
+
+      mockExecuteAction.mockClear()
+
+      //#when
+      await manager.cleanup()
+
+      //#then
+      expect(mockExecuteAction).toHaveBeenCalledTimes(2)
+    })
+  })
+})
+
+describe('DecisionEngine', () => {
+  describe('calculateCapacity', () => {
+    test('calculates correct 2D grid capacity', async () => {
+      //#given
+      const { calculateCapacity } = await import('./decision-engine')
+
+      //#when
+      const result = calculateCapacity(212, 44)
+
+      //#then - availableWidth=106, cols=(106+1)/(52+1)=2, rows=(44+1)/(11+1)=3 (accounting for dividers)
+      expect(result.cols).toBe(2)
+      expect(result.rows).toBe(3)
+      expect(result.total).toBe(6)
+    })
+
+    test('returns 0 cols when agent area too narrow', async () => {
+      //#given
+      const { calculateCapacity } = await import('./decision-engine')
+
+      //#when
+      const result = calculateCapacity(100, 44)
+
+      //#then - availableWidth=50, cols=50/53=0
+      expect(result.cols).toBe(0)
+      expect(result.total).toBe(0)
+    })
+  })
+
+  describe('decideSpawnActions', () => {
+    test('returns spawn action with splitDirection when under capacity', async () => {
+      //#given
+      const { decideSpawnActions } = await import('./decision-engine')
+      const state: WindowState = {
+        windowWidth: 212,
+        windowHeight: 44,
+        mainPane: {
+          paneId: '%0',
+          width: 106,
+          height: 44,
+          left: 0,
+          top: 0,
+          title: 'main',
+          isActive: true,
+        },
+        agentPanes: [],
+      }
+
+      //#when
+      const decision = decideSpawnActions(
+        state,
+        'ses_1',
+        'Test Task',
+        { mainPaneMinWidth: 120, agentPaneWidth: 40 },
+        []
+      )
+
+      //#then
+      expect(decision.canSpawn).toBe(true)
+      expect(decision.actions).toHaveLength(1)
+      expect(decision.actions[0].type).toBe('spawn')
+      if (decision.actions[0].type === 'spawn') {
+        expect(decision.actions[0].sessionId).toBe('ses_1')
+        expect(decision.actions[0].description).toBe('Test Task')
+        expect(decision.actions[0].targetPaneId).toBe('%0')
+        expect(decision.actions[0].splitDirection).toBe('-h')
+      }
+    })
+
+    test('returns replace when split not possible', async () => {
+      //#given - small window where split is never possible
+      const { decideSpawnActions } = await import('./decision-engine')
+      const state: WindowState = {
+        windowWidth: 160,
+        windowHeight: 11,
+        mainPane: {
+          paneId: '%0',
+          width: 80,
+          height: 11,
+          left: 0,
+          top: 0,
+          title: 'main',
+          isActive: true,
+        },
+        agentPanes: [
+          {
+            paneId: '%1',
+            width: 80,
+            height: 11,
+            left: 80,
+            top: 0,
+            title: 'omo-subagent-Old',
+            isActive: false,
+          },
+        ],
+      }
+      const sessionMappings = [
+        { sessionId: 'ses_old', paneId: '%1', createdAt: new Date('2024-01-01') },
+      ]
+
+      //#when
+      const decision = decideSpawnActions(
+        state,
+        'ses_new',
+        'New Task',
+        { mainPaneMinWidth: 120, agentPaneWidth: 40 },
+        sessionMappings
+      )
+
+      //#then - agent area (80) < MIN_SPLIT_WIDTH (105), so replace is used
+      expect(decision.canSpawn).toBe(true)
+      expect(decision.actions).toHaveLength(1)
+      expect(decision.actions[0].type).toBe('replace')
+    })
+
+    test('returns canSpawn=false when window too small', async () => {
+      //#given
+      const { decideSpawnActions } = await import('./decision-engine')
+      const state: WindowState = {
+        windowWidth: 60,
+        windowHeight: 5,
+        mainPane: {
+          paneId: '%0',
+          width: 30,
+          height: 5,
+          left: 0,
+          top: 0,
+          title: 'main',
+          isActive: true,
+        },
+        agentPanes: [],
+      }
+
+      //#when
+      const decision = decideSpawnActions(
+        state,
+        'ses_1',
+        'Test Task',
+        { mainPaneMinWidth: 120, agentPaneWidth: 40 },
+        []
+      )
+
+      //#then
+      expect(decision.canSpawn).toBe(false)
+      expect(decision.reason).toContain('too small')
+    })
+  })
+})

src/features/tmux-subagent/manager.ts

@@ -0,0 +1,396 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import type { TmuxConfig } from "../../config/schema"
+import type { TrackedSession, CapacityConfig } from "./types"
+import {
+  isInsideTmux,
+  getCurrentPaneId,
+  POLL_INTERVAL_BACKGROUND_MS,
+  SESSION_MISSING_GRACE_MS,
+  SESSION_READY_POLL_INTERVAL_MS,
+  SESSION_READY_TIMEOUT_MS,
+} from "../../shared/tmux"
+import { log } from "../../shared"
+import { queryWindowState } from "./pane-state-querier"
+import { decideSpawnActions, decideCloseAction, type SessionMapping } from "./decision-engine"
+import { executeActions, executeAction } from "./action-executor"
+
+type OpencodeClient = PluginInput["client"]
+
+interface SessionCreatedEvent {
+  type: string
+  properties?: { info?: { id?: string; parentID?: string; title?: string } }
+}
+
+const SESSION_TIMEOUT_MS = 10 * 60 * 1000
+
+/**
+ * State-first Tmux Session Manager
+ * 
+ * Architecture:
+ * 1. QUERY: Get actual tmux pane state (source of truth)
+ * 2. DECIDE: Pure function determines actions based on state
+ * 3. EXECUTE: Execute actions with verification
+ * 4. UPDATE: Update internal cache only after tmux confirms success
+ * 
+ * The internal `sessions` Map is just a cache for sessionId<->paneId mapping.
+ * The REAL source of truth is always queried from tmux.
+ */
+export class TmuxSessionManager {
+  private client: OpencodeClient
+  private tmuxConfig: TmuxConfig
+  private serverUrl: string
+  private sourcePaneId: string | undefined
+  private sessions = new Map<string, TrackedSession>()
+  private pendingSessions = new Set<string>()
+  private pollInterval?: ReturnType<typeof setInterval>
+
+  constructor(ctx: PluginInput, tmuxConfig: TmuxConfig) {
+    this.client = ctx.client
+    this.tmuxConfig = tmuxConfig
+    const defaultPort = process.env.OPENCODE_PORT ?? "4096"
+    this.serverUrl = ctx.serverUrl?.toString() ?? `http://localhost:${defaultPort}`
+    this.sourcePaneId = getCurrentPaneId()
+
+    log("[tmux-session-manager] initialized", {
+      configEnabled: this.tmuxConfig.enabled,
+      tmuxConfig: this.tmuxConfig,
+      serverUrl: this.serverUrl,
+      sourcePaneId: this.sourcePaneId,
+    })
+  }
+
+  private isEnabled(): boolean {
+    return this.tmuxConfig.enabled && isInsideTmux()
+  }
+
+  private getCapacityConfig(): CapacityConfig {
+    return {
+      mainPaneMinWidth: this.tmuxConfig.main_pane_min_width,
+      agentPaneWidth: this.tmuxConfig.agent_pane_min_width,
+    }
+  }
+
+  private getSessionMappings(): SessionMapping[] {
+    return Array.from(this.sessions.values()).map((s) => ({
+      sessionId: s.sessionId,
+      paneId: s.paneId,
+      createdAt: s.createdAt,
+    }))
+  }
+
+  private async waitForSessionReady(sessionId: string): Promise<boolean> {
+    const startTime = Date.now()
+    
+    while (Date.now() - startTime < SESSION_READY_TIMEOUT_MS) {
+      try {
+        const statusResult = await this.client.session.status({ path: undefined })
+        const allStatuses = (statusResult.data ?? {}) as Record<string, { type: string }>
+        
+        if (allStatuses[sessionId]) {
+          log("[tmux-session-manager] session ready", {
+            sessionId,
+            status: allStatuses[sessionId].type,
+            waitedMs: Date.now() - startTime,
+          })
+          return true
+        }
+      } catch (err) {
+        log("[tmux-session-manager] session status check error", { error: String(err) })
+      }
+      
+      await new Promise((resolve) => setTimeout(resolve, SESSION_READY_POLL_INTERVAL_MS))
+    }
+    
+    log("[tmux-session-manager] session ready timeout", {
+      sessionId,
+      timeoutMs: SESSION_READY_TIMEOUT_MS,
+    })
+    return false
+  }
+
+  async onSessionCreated(event: SessionCreatedEvent): Promise<void> {
+    const enabled = this.isEnabled()
+    log("[tmux-session-manager] onSessionCreated called", {
+      enabled,
+      tmuxConfigEnabled: this.tmuxConfig.enabled,
+      isInsideTmux: isInsideTmux(),
+      eventType: event.type,
+      infoId: event.properties?.info?.id,
+      infoParentID: event.properties?.info?.parentID,
+    })
+
+    if (!enabled) return
+    if (event.type !== "session.created") return
+
+    const info = event.properties?.info
+    if (!info?.id || !info?.parentID) return
+
+    const sessionId = info.id
+    const title = info.title ?? "Subagent"
+
+    if (this.sessions.has(sessionId) || this.pendingSessions.has(sessionId)) {
+      log("[tmux-session-manager] session already tracked or pending", { sessionId })
+      return
+    }
+
+    if (!this.sourcePaneId) {
+      log("[tmux-session-manager] no source pane id")
+      return
+    }
+
+    this.pendingSessions.add(sessionId)
+
+    try {
+      const state = await queryWindowState(this.sourcePaneId)
+      if (!state) {
+        log("[tmux-session-manager] failed to query window state")
+        return
+      }
+
+      log("[tmux-session-manager] window state queried", {
+        windowWidth: state.windowWidth,
+        mainPane: state.mainPane?.paneId,
+        agentPaneCount: state.agentPanes.length,
+        agentPanes: state.agentPanes.map((p) => p.paneId),
+      })
+
+      const decision = decideSpawnActions(
+        state,
+        sessionId,
+        title,
+        this.getCapacityConfig(),
+        this.getSessionMappings()
+      )
+
+      log("[tmux-session-manager] spawn decision", {
+        canSpawn: decision.canSpawn,
+        reason: decision.reason,
+        actionCount: decision.actions.length,
+        actions: decision.actions.map((a) => {
+          if (a.type === "close") return { type: "close", paneId: a.paneId }
+          if (a.type === "replace") return { type: "replace", paneId: a.paneId, newSessionId: a.newSessionId }
+          return { type: "spawn", sessionId: a.sessionId }
+        }),
+      })
+
+      if (!decision.canSpawn) {
+        log("[tmux-session-manager] cannot spawn", { reason: decision.reason })
+        return
+      }
+
+      const result = await executeActions(
+        decision.actions,
+        { config: this.tmuxConfig, serverUrl: this.serverUrl, windowState: state }
+      )
+
+      for (const { action, result: actionResult } of result.results) {
+        if (action.type === "close" && actionResult.success) {
+          this.sessions.delete(action.sessionId)
+          log("[tmux-session-manager] removed closed session from cache", {
+            sessionId: action.sessionId,
+          })
+        }
+        if (action.type === "replace" && actionResult.success) {
+          this.sessions.delete(action.oldSessionId)
+          log("[tmux-session-manager] removed replaced session from cache", {
+            oldSessionId: action.oldSessionId,
+            newSessionId: action.newSessionId,
+          })
+        }
+      }
+
+      if (result.success && result.spawnedPaneId) {
+        const sessionReady = await this.waitForSessionReady(sessionId)
+        
+        if (!sessionReady) {
+          log("[tmux-session-manager] session not ready after timeout, tracking anyway", {
+            sessionId,
+            paneId: result.spawnedPaneId,
+          })
+        }
+        
+        const now = Date.now()
+        this.sessions.set(sessionId, {
+          sessionId,
+          paneId: result.spawnedPaneId,
+          description: title,
+          createdAt: new Date(now),
+          lastSeenAt: new Date(now),
+        })
+        log("[tmux-session-manager] pane spawned and tracked", {
+          sessionId,
+          paneId: result.spawnedPaneId,
+          sessionReady,
+        })
+        this.startPolling()
+      } else {
+        log("[tmux-session-manager] spawn failed", {
+          success: result.success,
+          results: result.results.map((r) => ({
+            type: r.action.type,
+            success: r.result.success,
+            error: r.result.error,
+          })),
+        })
+      }
+    } finally {
+      this.pendingSessions.delete(sessionId)
+    }
+  }
+
+  async onSessionDeleted(event: { sessionID: string }): Promise<void> {
+    if (!this.isEnabled()) return
+    if (!this.sourcePaneId) return
+
+    const tracked = this.sessions.get(event.sessionID)
+    if (!tracked) return
+
+    log("[tmux-session-manager] onSessionDeleted", { sessionId: event.sessionID })
+
+    const state = await queryWindowState(this.sourcePaneId)
+    if (!state) {
+      this.sessions.delete(event.sessionID)
+      return
+    }
+
+    const closeAction = decideCloseAction(state, event.sessionID, this.getSessionMappings())
+    if (closeAction) {
+      await executeAction(closeAction, { config: this.tmuxConfig, serverUrl: this.serverUrl, windowState: state })
+    }
+
+    this.sessions.delete(event.sessionID)
+
+    if (this.sessions.size === 0) {
+      this.stopPolling()
+    }
+  }
+
+  private startPolling(): void {
+    if (this.pollInterval) return
+
+    this.pollInterval = setInterval(
+      () => this.pollSessions(),
+      POLL_INTERVAL_BACKGROUND_MS,
+    )
+    log("[tmux-session-manager] polling started")
+  }
+
+  private stopPolling(): void {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval)
+      this.pollInterval = undefined
+      log("[tmux-session-manager] polling stopped")
+    }
+  }
+
+  private async pollSessions(): Promise<void> {
+    if (this.sessions.size === 0) {
+      this.stopPolling()
+      return
+    }
+
+    try {
+      const statusResult = await this.client.session.status({ path: undefined })
+      const allStatuses = (statusResult.data ?? {}) as Record<string, { type: string }>
+
+      log("[tmux-session-manager] pollSessions", {
+        trackedSessions: Array.from(this.sessions.keys()),
+        allStatusKeys: Object.keys(allStatuses),
+      })
+
+      const now = Date.now()
+      const sessionsToClose: string[] = []
+
+      for (const [sessionId, tracked] of this.sessions.entries()) {
+        const status = allStatuses[sessionId]
+        const isIdle = status?.type === "idle"
+
+        if (status) {
+          tracked.lastSeenAt = new Date(now)
+        }
+
+        const missingSince = !status ? now - tracked.lastSeenAt.getTime() : 0
+        const missingTooLong = missingSince >= SESSION_MISSING_GRACE_MS
+        const isTimedOut = now - tracked.createdAt.getTime() > SESSION_TIMEOUT_MS
+
+        log("[tmux-session-manager] session check", {
+          sessionId,
+          statusType: status?.type,
+          isIdle,
+          missingSince,
+          missingTooLong,
+          isTimedOut,
+          shouldClose: isIdle || missingTooLong || isTimedOut,
+        })
+
+        if (isIdle || missingTooLong || isTimedOut) {
+          sessionsToClose.push(sessionId)
+        }
+      }
+
+      for (const sessionId of sessionsToClose) {
+        log("[tmux-session-manager] closing session due to poll", { sessionId })
+        await this.closeSessionById(sessionId)
+      }
+    } catch (err) {
+      log("[tmux-session-manager] poll error", { error: String(err) })
+    }
+  }
+
+  private async closeSessionById(sessionId: string): Promise<void> {
+    const tracked = this.sessions.get(sessionId)
+    if (!tracked) return
+
+    log("[tmux-session-manager] closing session pane", {
+      sessionId,
+      paneId: tracked.paneId,
+    })
+
+    const state = this.sourcePaneId ? await queryWindowState(this.sourcePaneId) : null
+    if (state) {
+      await executeAction(
+        { type: "close", paneId: tracked.paneId, sessionId },
+        { config: this.tmuxConfig, serverUrl: this.serverUrl, windowState: state }
+      )
+    }
+
+    this.sessions.delete(sessionId)
+
+    if (this.sessions.size === 0) {
+      this.stopPolling()
+    }
+  }
+
+  createEventHandler(): (input: { event: { type: string; properties?: unknown } }) => Promise<void> {
+    return async (input) => {
+      await this.onSessionCreated(input.event as SessionCreatedEvent)
+    }
+  }
+
+  async cleanup(): Promise<void> {
+    this.stopPolling()
+
+    if (this.sessions.size > 0) {
+      log("[tmux-session-manager] closing all panes", { count: this.sessions.size })
+      const state = this.sourcePaneId ? await queryWindowState(this.sourcePaneId) : null
+      
+      if (state) {
+        const closePromises = Array.from(this.sessions.values()).map((s) =>
+          executeAction(
+            { type: "close", paneId: s.paneId, sessionId: s.sessionId },
+            { config: this.tmuxConfig, serverUrl: this.serverUrl, windowState: state }
+          ).catch((err) =>
+            log("[tmux-session-manager] cleanup error for pane", {
+              paneId: s.paneId,
+              error: String(err),
+            }),
+          ),
+        )
+        await Promise.all(closePromises)
+      }
+      this.sessions.clear()
+    }
+
+    log("[tmux-session-manager] cleanup complete")
+  }
+}

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

@@ -0,0 +1,73 @@
+import { spawn } from "bun"
+import type { WindowState, TmuxPaneInfo } from "./types"
+import { getTmuxPath } from "../../tools/interactive-bash/utils"
+import { log } from "../../shared"
+
+export async function queryWindowState(sourcePaneId: string): Promise<WindowState | null> {
+  const tmux = await getTmuxPath()
+  if (!tmux) return null
+
+  const proc = spawn(
+    [
+      tmux,
+      "list-panes",
+      "-t",
+      sourcePaneId,
+      "-F",
+      "#{pane_id},#{pane_width},#{pane_height},#{pane_left},#{pane_top},#{pane_title},#{pane_active},#{window_width},#{window_height}",
+    ],
+    { stdout: "pipe", stderr: "pipe" }
+  )
+
+  const exitCode = await proc.exited
+  const stdout = await new Response(proc.stdout).text()
+
+  if (exitCode !== 0) {
+    log("[pane-state-querier] list-panes failed", { exitCode })
+    return null
+  }
+
+  const lines = stdout.trim().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 [paneId, widthStr, heightStr, leftStr, topStr, title, activeStr, windowWidthStr, windowHeightStr] = line.split(",")
+    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 })
+    }
+  }
+
+  panes.sort((a, b) => a.left - b.left || a.top - b.top)
+
+  const mainPane = panes.find((p) => p.paneId === sourcePaneId)
+  if (!mainPane) {
+    log("[pane-state-querier] CRITICAL: sourcePaneId not found in panes", {
+      sourcePaneId,
+      availablePanes: panes.map((p) => p.paneId),
+    })
+    return null
+  }
+
+  const agentPanes = panes.filter((p) => p.paneId !== mainPane.paneId)
+
+  log("[pane-state-querier] window state", {
+    windowWidth,
+    windowHeight,
+    mainPane: mainPane.paneId,
+    agentPaneCount: agentPanes.length,
+  })
+
+  return { windowWidth, windowHeight, mainPane, agentPanes }
+}

src/features/tmux-subagent/types.ts

@@ -0,0 +1,45 @@
+export interface TrackedSession {
+  sessionId: string
+  paneId: string
+  description: string
+  createdAt: Date
+  lastSeenAt: Date
+}
+
+export const MIN_PANE_WIDTH = 52
+export const MIN_PANE_HEIGHT = 11
+
+export interface TmuxPaneInfo {
+  paneId: string
+  width: number
+  height: number
+  left: number
+  top: number
+  title: string
+  isActive: boolean
+}
+
+export interface WindowState {
+  windowWidth: number
+  windowHeight: number
+  mainPane: TmuxPaneInfo | null
+  agentPanes: TmuxPaneInfo[]
+}
+
+export type SplitDirection = "-h" | "-v"
+
+export type PaneAction =
+  | { type: "close"; paneId: string; sessionId: string }
+  | { type: "spawn"; sessionId: string; description: string; targetPaneId: string; splitDirection: SplitDirection }
+  | { type: "replace"; paneId: string; oldSessionId: string; newSessionId: string; description: string }
+
+export interface SpawnDecision {
+  canSpawn: boolean
+  actions: PaneAction[]
+  reason?: string
+}
+
+export interface CapacityConfig {
+  mainPaneMinWidth: number
+  agentPaneWidth: number
+}

src/hooks/AGENTS.md

@@ -1,16 +1,14 @@
 # HOOKS KNOWLEDGE BASE
 
 ## OVERVIEW
-
-31 lifecycle hooks intercepting/modifying agent behavior. Events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, onSummarize.
+32 lifecycle hooks intercepting/modifying agent behavior. Events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, onSummarize.
 
 ## STRUCTURE
-
 ```
 hooks/
-├── atlas/                      # Main orchestration (773 lines)
-├── anthropic-context-window-limit-recovery/  # Auto-summarize
-├── todo-continuation-enforcer.ts # Force TODO completion (489 lines)
+├── atlas/                      # Main orchestration (752 lines)
+├── anthropic-context-window-limit-recovery/ # Auto-summarize
+├── todo-continuation-enforcer.ts # Force TODO completion (16k lines)
 ├── ralph-loop/                 # Self-referential dev loop
 ├── claude-code-hooks/          # settings.json compat layer - see AGENTS.md
 ├── comment-checker/            # Prevents AI slop
@@ -35,45 +33,54 @@ hooks/
 ├── non-interactive-env/        # Non-TTY environment handling
 ├── start-work/                 # Sisyphus work session starter
 ├── task-resume-info/           # Resume info for cancelled tasks
-├── question-label-truncator/   # Auto-truncates question labels >30 chars
+├── question-label-truncator/   # Auto-truncates question labels
+├── category-skill-reminder/    # Reminds of category skills
+├── empty-task-response-detector.ts # Detects empty responses
+├── sisyphus-junior-notepad/    # Sisyphus Junior notepad
 └── index.ts                    # Hook aggregation + registration
 ```
 
 ## HOOK EVENTS
-
 | Event | Timing | Can Block | Use Case |
 |-------|--------|-----------|----------|
-| PreToolUse | Before tool | Yes | Validate/modify inputs |
-| PostToolUse | After tool | No | Append warnings, truncate |
-| UserPromptSubmit | On prompt | Yes | Keyword detection |
-| Stop | Session idle | No | Auto-continue |
-| onSummarize | Compaction | No | Preserve state |
+| UserPromptSubmit | `chat.message` | Yes | Keyword detection, slash commands |
+| PreToolUse | `tool.execute.before` | Yes | Validate/modify inputs, inject context |
+| PostToolUse | `tool.execute.after` | No | Truncate output, error recovery |
+| Stop | `event` (session.stop) | No | Auto-continue, notifications |
+| onSummarize | Compaction | No | Preserve state, inject summary context |
 
 ## EXECUTION ORDER
-
-**chat.message**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork → ralphLoop
-
-**tool.execute.before**: claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → rulesInjector
-
-**tool.execute.after**: editErrorRecovery → delegateTaskRetry → commentChecker → toolOutputTruncator → claudeCodeHooks
+- **UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork
+- **PreToolUse**: questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → atlasHook
+- **PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo
 
 ## HOW TO ADD
-
 1. Create `src/hooks/name/` with `index.ts` exporting `createMyHook(ctx)`
 2. Add hook name to `HookNameSchema` in `src/config/schema.ts`
-3. Register in `src/index.ts`:
-   ```typescript
-   const myHook = isHookEnabled("my-hook") ? createMyHook(ctx) : null
-   ```
+3. Register in `src/index.ts` and add to relevant lifecycle methods
 
-## PATTERNS
+## HOOK PATTERNS
 
-- **Session-scoped state**: `Map<sessionID, Set<string>>`
-- **Conditional execution**: Check `input.tool` before processing
-- **Output modification**: `output.output += "\n${REMINDER}"`
+**Simple Single-Event**:
+```typescript
+export function createToolOutputTruncatorHook(ctx) {
+  return { "tool.execute.after": async (input, output) => { ... } }
+}
+```
+
+**Multi-Event with State**:
+```typescript
+export function createThinkModeHook() {
+  const state = new Map<string, ThinkModeState>()
+  return {
+    "chat.params": async (output, sessionID) => { ... },
+    "event": async ({ event }) => { /* cleanup */ }
+  }
+}
+```
 
 ## ANTI-PATTERNS
-
 - **Blocking non-critical**: Use PostToolUse warnings instead
-- **Heavy computation**: Keep PreToolUse light
-- **Redundant injection**: Track injected files
+- **Heavy computation**: Keep PreToolUse light to avoid latency
+- **Redundant injection**: Track injected files to avoid context bloat
+- **Direct state mutation**: Use `output.output +=` instead of replacing

src/hooks/atlas/index.test.ts

@@ -373,7 +373,7 @@ describe("atlas hook", () => {
       const ORCHESTRATOR_SESSION = "orchestrator-write-test"
 
        beforeEach(() => {
-         setupMessageStorage(ORCHESTRATOR_SESSION, "Atlas")
+         setupMessageStorage(ORCHESTRATOR_SESSION, "atlas")
        })
 
       afterEach(() => {
@@ -444,7 +444,7 @@ describe("atlas hook", () => {
       test("should NOT append reminder when non-orchestrator writes outside .sisyphus/", async () => {
         // #given
         const nonOrchestratorSession = "non-orchestrator-session"
-        setupMessageStorage(nonOrchestratorSession, "Sisyphus-Junior")
+        setupMessageStorage(nonOrchestratorSession, "sisyphus-junior")
         
         const hook = createAtlasHook(createMockPluginInput())
         const originalOutput = "File written successfully"
@@ -601,7 +601,7 @@ describe("atlas hook", () => {
          getMainSessionID: () => MAIN_SESSION_ID,
          subagentSessions: new Set<string>(),
        }))
-       setupMessageStorage(MAIN_SESSION_ID, "Atlas")
+       setupMessageStorage(MAIN_SESSION_ID, "atlas")
      })
 
     afterEach(() => {
@@ -845,7 +845,7 @@ describe("atlas hook", () => {
 
        // #given - last agent is NOT Atlas
        cleanupMessageStorage(MAIN_SESSION_ID)
-       setupMessageStorage(MAIN_SESSION_ID, "Sisyphus")
+       setupMessageStorage(MAIN_SESSION_ID, "sisyphus")
 
        const mockInput = createMockPluginInput()
        const hook = createAtlasHook(mockInput)

src/hooks/atlas/index.ts

@@ -11,6 +11,7 @@ import { getMainSessionID, subagentSessions } from "../../features/claude-code-s
 import { findNearestMessageWithFields, MESSAGE_STORAGE } from "../../features/hook-message-injector"
 import { log } from "../../shared/logger"
 import { createSystemDirective, SYSTEM_DIRECTIVE_PREFIX, SystemDirectiveTypes } from "../../shared/system-directive"
+import { isCallerOrchestrator, getMessageDir } from "../../shared/session-utils"
 import type { BackgroundManager } from "../../features/background-agent"
 
 export const HOOK_NAME = "atlas"
@@ -380,28 +381,6 @@ interface ToolExecuteAfterOutput {
   metadata: Record<string, unknown>
 }
 
-function getMessageDir(sessionID: string): string | null {
-  if (!existsSync(MESSAGE_STORAGE)) return null
-
-  const directPath = join(MESSAGE_STORAGE, sessionID)
-  if (existsSync(directPath)) return directPath
-
-  for (const dir of readdirSync(MESSAGE_STORAGE)) {
-    const sessionPath = join(MESSAGE_STORAGE, dir, sessionID)
-    if (existsSync(sessionPath)) return sessionPath
-  }
-
-  return null
-}
-
-function isCallerOrchestrator(sessionID?: string): boolean {
-   if (!sessionID) return false
-   const messageDir = getMessageDir(sessionID)
-   if (!messageDir) return false
-   const nearest = findNearestMessageWithFields(messageDir)
-   return nearest?.agent?.toLowerCase() === "atlas"
- }
-
 interface SessionState {
   lastEventWasAbortError?: boolean
   lastContinuationInjectedAt?: number
@@ -672,7 +651,7 @@ export function createAtlasHook(
       if (input.tool === "delegate_task") {
         const prompt = output.args.prompt as string | undefined
         if (prompt && !prompt.includes(SYSTEM_DIRECTIVE_PREFIX)) {
-          output.args.prompt = prompt + `\n<system-reminder>${SINGLE_TASK_DIRECTIVE}</system-reminder>`
+          output.args.prompt = `<system-reminder>${SINGLE_TASK_DIRECTIVE}</system-reminder>\n` + prompt
           log(`[${HOOK_NAME}] Injected single-task directive to delegate_task`, {
             sessionID: input.sessionID,
           })

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

@@ -6,6 +6,7 @@ import { log } from "../../shared/logger"
 import { getConfigLoadErrors, clearConfigLoadErrors } from "../../shared/config-errors"
 import { runBunInstall } from "../../cli/config-manager"
 import { isModelCacheAvailable } from "../../shared/model-availability"
+import { hasConnectedProvidersCache, updateConnectedProvidersCache } from "../../shared/connected-providers-cache"
 import type { AutoUpdateCheckerOptions } from "./types"
 
 const SISYPHUS_SPINNER = ["·", "•", "●", "○", "◌", "◦", " "]
@@ -77,6 +78,7 @@ export function createAutoUpdateCheckerHook(ctx: PluginInput, options: AutoUpdat
 
         await showConfigErrorsIfAny(ctx)
         await showModelCacheWarningIfNeeded(ctx)
+        await updateAndShowConnectedProvidersCacheStatus(ctx)
 
         if (localDevVersion) {
           if (showStartupToast) {
@@ -186,6 +188,29 @@ async function showModelCacheWarningIfNeeded(ctx: PluginInput): Promise<void> {
   log("[auto-update-checker] Model cache warning shown")
 }
 
+async function updateAndShowConnectedProvidersCacheStatus(ctx: PluginInput): Promise<void> {
+  const hadCache = hasConnectedProvidersCache()
+
+  updateConnectedProvidersCache(ctx.client).catch(() => {})
+
+  if (!hadCache) {
+    await ctx.client.tui
+      .showToast({
+        body: {
+          title: "Connected Providers Cache",
+          message: "Building provider cache for first time. Restart OpenCode for full model filtering.",
+          variant: "info" as const,
+          duration: 8000,
+        },
+      })
+      .catch(() => {})
+
+    log("[auto-update-checker] Connected providers cache toast shown (first run)")
+  } else {
+    log("[auto-update-checker] Connected providers cache exists, updating in background")
+  }
+}
+
 async function showConfigErrorsIfAny(ctx: PluginInput): Promise<void> {
   const errors = getConfigLoadErrors()
   if (errors.length === 0) return

src/hooks/category-skill-reminder/index.test.ts

@@ -0,0 +1,346 @@
+import { describe, expect, test, beforeEach, afterEach, spyOn } from "bun:test"
+import { createCategorySkillReminderHook } from "./index"
+import { updateSessionAgent, clearSessionAgent, _resetForTesting } from "../../features/claude-code-session-state"
+import * as sharedModule from "../../shared"
+
+describe("category-skill-reminder hook", () => {
+  let logCalls: Array<{ msg: string; data?: unknown }>
+  let logSpy: ReturnType<typeof spyOn>
+
+  beforeEach(() => {
+    _resetForTesting()
+    logCalls = []
+    logSpy = spyOn(sharedModule, "log").mockImplementation((msg: string, data?: unknown) => {
+      logCalls.push({ msg, data })
+    })
+  })
+
+  afterEach(() => {
+    logSpy?.mockRestore()
+  })
+
+  function createMockPluginInput() {
+    return {
+      client: {
+        tui: {
+          showToast: async () => {},
+        },
+      },
+    } as any
+  }
+
+  describe("target agent detection", () => {
+    test("should inject reminder for sisyphus agent after 3 tool calls", async () => {
+      // #given - sisyphus agent session with multiple tool calls
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "sisyphus-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "file content", metadata: {} }
+
+      // #when - 3 edit tool calls are made
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output)
+
+      // #then - reminder should be injected
+      expect(output.output).toContain("[Category+Skill Reminder]")
+      expect(output.output).toContain("delegate_task")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should inject reminder for atlas agent", async () => {
+      // #given - atlas agent session
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "atlas-session"
+      updateSessionAgent(sessionID, "Atlas")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - 3 tool calls are made
+      await hook["tool.execute.after"]({ tool: "bash", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "bash", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "bash", sessionID, callID: "3" }, output)
+
+      // #then - reminder should be injected
+      expect(output.output).toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should inject reminder for sisyphus-junior agent", async () => {
+      // #given - sisyphus-junior agent session
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "junior-session"
+      updateSessionAgent(sessionID, "sisyphus-junior")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - 3 tool calls are made
+      await hook["tool.execute.after"]({ tool: "write", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "write", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "write", sessionID, callID: "3" }, output)
+
+      // #then - reminder should be injected
+      expect(output.output).toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should NOT inject reminder for non-target agents", async () => {
+      // #given - librarian agent session (not a target)
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "librarian-session"
+      updateSessionAgent(sessionID, "librarian")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - 3 tool calls are made
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output)
+
+      // #then - reminder should NOT be injected
+      expect(output.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should detect agent from input.agent when session state is empty", async () => {
+      // #given - no session state, agent provided in input
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "input-agent-session"
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - 3 tool calls with agent in input
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "1", agent: "Sisyphus" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2", agent: "Sisyphus" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3", agent: "Sisyphus" }, output)
+
+      // #then - reminder should be injected
+      expect(output.output).toContain("[Category+Skill Reminder]")
+    })
+  })
+
+  describe("delegation tool tracking", () => {
+    test("should NOT inject reminder if delegate_task is used", async () => {
+      // #given - sisyphus agent that uses delegate_task
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "delegation-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - delegate_task is used, then more tool calls
+      await hook["tool.execute.after"]({ tool: "delegate_task", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "4" }, output)
+
+      // #then - reminder should NOT be injected (delegation was used)
+      expect(output.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should NOT inject reminder if call_omo_agent is used", async () => {
+      // #given - sisyphus agent that uses call_omo_agent
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "omo-agent-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - call_omo_agent is used first
+      await hook["tool.execute.after"]({ tool: "call_omo_agent", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "4" }, output)
+
+      // #then - reminder should NOT be injected
+      expect(output.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should NOT inject reminder if task tool is used", async () => {
+      // #given - sisyphus agent that uses task tool
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "task-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - task tool is used
+      await hook["tool.execute.after"]({ tool: "task", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "4" }, output)
+
+      // #then - reminder should NOT be injected
+      expect(output.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+  })
+
+  describe("tool call counting", () => {
+    test("should NOT inject reminder before 3 tool calls", async () => {
+      // #given - sisyphus agent with only 2 tool calls
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "few-calls-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - only 2 tool calls are made
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output)
+
+      // #then - reminder should NOT be injected yet
+      expect(output.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should only inject reminder once per session", async () => {
+      // #given - sisyphus agent session
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "once-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output1 = { title: "", output: "result1", metadata: {} }
+      const output2 = { title: "", output: "result2", metadata: {} }
+
+      // #when - 6 tool calls are made (should trigger at 3, not again at 6)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "1" }, output1)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output1)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output1)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "4" }, output2)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "5" }, output2)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "6" }, output2)
+
+      // #then - reminder should be in output1 but not output2
+      expect(output1.output).toContain("[Category+Skill Reminder]")
+      expect(output2.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should only count delegatable work tools", async () => {
+      // #given - sisyphus agent with mixed tool calls
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "mixed-tools-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - non-delegatable tools are called (should not count)
+      await hook["tool.execute.after"]({ tool: "lsp_goto_definition", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "lsp_find_references", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "lsp_symbols", sessionID, callID: "3" }, output)
+
+      // #then - reminder should NOT be injected (LSP tools don't count)
+      expect(output.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+  })
+
+  describe("event handling", () => {
+    test("should reset state on session.deleted event", async () => {
+      // #given - sisyphus agent with reminder already shown
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "delete-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output1 = { title: "", output: "result1", metadata: {} }
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "1" }, output1)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output1)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output1)
+      expect(output1.output).toContain("[Category+Skill Reminder]")
+
+      // #when - session is deleted and new session starts
+      await hook.event({ event: { type: "session.deleted", properties: { info: { id: sessionID } } } })
+
+      const output2 = { title: "", output: "result2", metadata: {} }
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "4" }, output2)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "5" }, output2)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "6" }, output2)
+
+      // #then - reminder should be shown again (state was reset)
+      expect(output2.output).toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should reset state on session.compacted event", async () => {
+      // #given - sisyphus agent with reminder already shown
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "compact-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output1 = { title: "", output: "result1", metadata: {} }
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "1" }, output1)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output1)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output1)
+      expect(output1.output).toContain("[Category+Skill Reminder]")
+
+      // #when - session is compacted
+      await hook.event({ event: { type: "session.compacted", properties: { sessionID } } })
+
+      const output2 = { title: "", output: "result2", metadata: {} }
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "4" }, output2)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "5" }, output2)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "6" }, output2)
+
+      // #then - reminder should be shown again (state was reset)
+      expect(output2.output).toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+  })
+
+  describe("case insensitivity", () => {
+    test("should handle tool names case-insensitively", async () => {
+      // #given - sisyphus agent with mixed case tool names
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "case-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - tool calls with different cases
+      await hook["tool.execute.after"]({ tool: "EDIT", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "Edit", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output)
+
+      // #then - reminder should be injected (all counted)
+      expect(output.output).toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+
+    test("should handle delegation tool names case-insensitively", async () => {
+      // #given - sisyphus agent using DELEGATE_TASK in uppercase
+      const hook = createCategorySkillReminderHook(createMockPluginInput())
+      const sessionID = "case-delegate-session"
+      updateSessionAgent(sessionID, "Sisyphus")
+
+      const output = { title: "", output: "result", metadata: {} }
+
+      // #when - DELEGATE_TASK in uppercase is used
+      await hook["tool.execute.after"]({ tool: "DELEGATE_TASK", sessionID, callID: "1" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "2" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "3" }, output)
+      await hook["tool.execute.after"]({ tool: "edit", sessionID, callID: "4" }, output)
+
+      // #then - reminder should NOT be injected (delegation was detected)
+      expect(output.output).not.toContain("[Category+Skill Reminder]")
+
+      clearSessionAgent(sessionID)
+    })
+  })
+})

src/hooks/category-skill-reminder/index.ts

@@ -0,0 +1,165 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import { getSessionAgent } from "../../features/claude-code-session-state"
+import { log } from "../../shared"
+
+/**
+ * Target agents that should receive category+skill reminders.
+ * These are orchestrator agents that delegate work to specialized agents.
+ */
+const TARGET_AGENTS = new Set([
+  "sisyphus",
+  "sisyphus-junior",
+  "atlas",
+])
+
+/**
+ * Tools that indicate the agent is doing work that could potentially be delegated.
+ * When these tools are used, we remind the agent about the category+skill system.
+ */
+const DELEGATABLE_WORK_TOOLS = new Set([
+  "edit",
+  "write",
+  "bash",
+  "read",
+  "grep",
+  "glob",
+])
+
+/**
+ * Tools that indicate the agent is already using delegation properly.
+ */
+const DELEGATION_TOOLS = new Set([
+  "delegate_task",
+  "call_omo_agent",
+  "task",
+])
+
+const REMINDER_MESSAGE = `
+[Category+Skill Reminder]
+
+You are an orchestrator agent. Consider whether this work should be delegated:
+
+**DELEGATE when:**
+- UI/Frontend work → category: "visual-engineering", skills: ["frontend-ui-ux"]
+- Complex logic/architecture → category: "ultrabrain"
+- Quick/trivial tasks → category: "quick"
+- Git operations → skills: ["git-master"]
+- Browser automation → skills: ["playwright"] or ["agent-browser"]
+
+**DO IT YOURSELF when:**
+- Gathering context/exploring codebase
+- Simple edits that are part of a larger task you're coordinating
+- Tasks requiring your full context understanding
+
+Example delegation:
+\`\`\`
+delegate_task(
+  category="visual-engineering",
+  load_skills=["frontend-ui-ux"],
+  description="Implement responsive navbar with animations",
+  run_in_background=true
+)
+\`\`\`
+`
+
+interface ToolExecuteInput {
+  tool: string
+  sessionID: string
+  callID: string
+  agent?: string
+}
+
+interface ToolExecuteOutput {
+  title: string
+  output: string
+  metadata: unknown
+}
+
+interface SessionState {
+  delegationUsed: boolean
+  reminderShown: boolean
+  toolCallCount: number
+}
+
+export function createCategorySkillReminderHook(_ctx: PluginInput) {
+  const sessionStates = new Map<string, SessionState>()
+
+  function getOrCreateState(sessionID: string): SessionState {
+    if (!sessionStates.has(sessionID)) {
+      sessionStates.set(sessionID, {
+        delegationUsed: false,
+        reminderShown: false,
+        toolCallCount: 0,
+      })
+    }
+    return sessionStates.get(sessionID)!
+  }
+
+  function isTargetAgent(sessionID: string, inputAgent?: string): boolean {
+    const agent = getSessionAgent(sessionID) ?? inputAgent
+    if (!agent) return false
+    const agentLower = agent.toLowerCase()
+    return TARGET_AGENTS.has(agentLower) || 
+           agentLower.includes("sisyphus") || 
+           agentLower.includes("atlas")
+  }
+
+  const toolExecuteAfter = async (
+    input: ToolExecuteInput,
+    output: ToolExecuteOutput,
+  ) => {
+    const { tool, sessionID } = input
+    const toolLower = tool.toLowerCase()
+
+    if (!isTargetAgent(sessionID, input.agent)) {
+      return
+    }
+
+    const state = getOrCreateState(sessionID)
+
+    if (DELEGATION_TOOLS.has(toolLower)) {
+      state.delegationUsed = true
+      log("[category-skill-reminder] Delegation tool used", { sessionID, tool })
+      return
+    }
+
+    if (!DELEGATABLE_WORK_TOOLS.has(toolLower)) {
+      return
+    }
+
+    state.toolCallCount++
+
+    if (state.toolCallCount >= 3 && !state.delegationUsed && !state.reminderShown) {
+      output.output += REMINDER_MESSAGE
+      state.reminderShown = true
+      log("[category-skill-reminder] Reminder injected", { 
+        sessionID, 
+        toolCallCount: state.toolCallCount 
+      })
+    }
+  }
+
+  const eventHandler = async ({ event }: { event: { type: string; properties?: unknown } }) => {
+    const props = event.properties as Record<string, unknown> | undefined
+
+    if (event.type === "session.deleted") {
+      const sessionInfo = props?.info as { id?: string } | undefined
+      if (sessionInfo?.id) {
+        sessionStates.delete(sessionInfo.id)
+      }
+    }
+
+    if (event.type === "session.compacted") {
+      const sessionID = (props?.sessionID ??
+        (props?.info as { id?: string } | undefined)?.id) as string | undefined
+      if (sessionID) {
+        sessionStates.delete(sessionID)
+      }
+    }
+  }
+
+  return {
+    "tool.execute.after": toolExecuteAfter,
+    event: eventHandler,
+  }
+}

src/hooks/claude-code-hooks/AGENTS.md

@@ -1,51 +1,48 @@
 # CLAUDE CODE HOOKS COMPATIBILITY
 
 ## OVERVIEW
-
-Full Claude Code settings.json hook compatibility. 5 lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact.
+Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands defined in Claude Code configuration.
 
 ## STRUCTURE
-
 ```
 claude-code-hooks/
 ├── index.ts              # Main factory (401 lines)
 ├── config.ts             # Loads ~/.claude/settings.json
-├── config-loader.ts      # Extended config
+├── config-loader.ts      # Extended config (disabledHooks)
 ├── pre-tool-use.ts       # PreToolUse executor
 ├── post-tool-use.ts      # PostToolUse executor
 ├── user-prompt-submit.ts # UserPromptSubmit executor
-├── stop.ts               # Stop hook executor
+├── stop.ts               # Stop hook executor (with active state tracking)
 ├── pre-compact.ts        # PreCompact executor
 ├── transcript.ts         # Tool use recording
-├── tool-input-cache.ts   # Pre→post caching
-├── types.ts              # Hook types
-└── todo.ts               # Todo JSON fix
+├── tool-input-cache.ts   # Pre→post input caching
+└── types.ts              # Hook & IO type definitions
 ```
 
 ## HOOK LIFECYCLE
-
-| Event | When | Can Block | Context |
-|-------|------|-----------|---------|
-| PreToolUse | Before tool | Yes | sessionId, toolName, toolInput |
-| PostToolUse | After tool | Warn | + toolOutput, transcriptPath |
-| UserPromptSubmit | On message | Yes | sessionId, prompt, parts |
-| Stop | Session idle | inject | sessionId, parentSessionId |
-| PreCompact | Before summarize | No | sessionId |
+| Event | Timing | Can Block | Context Provided |
+|-------|--------|-----------|------------------|
+| PreToolUse | Before tool exec | Yes | sessionId, toolName, toolInput, cwd |
+| PostToolUse | After tool exec | Warn | + toolOutput, transcriptPath |
+| UserPromptSubmit | On message send | Yes | sessionId, prompt, parts, cwd |
+| Stop | Session idle/end | Inject | sessionId, parentSessionId, cwd |
+| PreCompact | Before summarize | No | sessionId, cwd |
 
 ## CONFIG SOURCES
-
 Priority (highest first):
-1. `.claude/settings.json` (project)
-2. `~/.claude/settings.json` (user)
+1. `.claude/settings.json` (Project-local)
+2. `~/.claude/settings.json` (Global user)
 
 ## HOOK EXECUTION
-
-1. Hooks loaded from settings.json
-2. Matchers filter by tool name
-3. Commands via subprocess with `$SESSION_ID`, `$TOOL_NAME`
-4. Exit codes: 0=pass, 1=warn, 2=block
+- **Matchers**: Hooks filter by tool name or event type via regex/glob.
+- **Commands**: Executed via subprocess with env vars (`$SESSION_ID`, `$TOOL_NAME`).
+- **Exit Codes**:
+  - `0`: Pass (Success)
+  - `1`: Warn (Continue with system message)
+  - `2`: Block (Abort operation/prompt)
 
 ## ANTI-PATTERNS
-
-- **Heavy PreToolUse**: Runs before EVERY tool call
-- **Blocking non-critical**: Use PostToolUse warnings
+- **Heavy PreToolUse**: Runs before EVERY tool; keep logic light to avoid latency.
+- **Blocking non-critical**: Prefer PostToolUse warnings for non-fatal issues.
+- **Direct state mutation**: Use `updatedInput` in PreToolUse instead of side effects.
+- **Ignoring Exit Codes**: Ensure scripts return `2` to properly block sensitive tools.

src/hooks/compaction-context-injector/index.ts

@@ -33,7 +33,13 @@ When summarizing this session, you MUST include the following sections in your s
 - Pending items from the original request
 - Follow-up tasks identified during the work
 
-## 5. MUST NOT Do (Critical Constraints)
+## 5. Active Working Context (For Seamless Continuation)
+- **Files**: Paths of files currently being edited or frequently referenced
+- **Code in Progress**: Key code snippets, function signatures, or data structures under active development
+- **External References**: Documentation URLs, library APIs, or external resources being consulted
+- **State & Variables**: Important variable names, configuration values, or runtime state relevant to ongoing work
+
+## 6. MUST NOT Do (Critical Constraints)
 - Things that were explicitly forbidden
 - Approaches that failed and should not be retried
 - User's explicit restrictions or preferences

src/hooks/index.ts

@@ -22,10 +22,12 @@ export { createNonInteractiveEnvHook } from "./non-interactive-env";
 export { createInteractiveBashSessionHook } from "./interactive-bash-session";
 
 export { createThinkingBlockValidatorHook } from "./thinking-block-validator";
+export { createCategorySkillReminderHook } from "./category-skill-reminder";
 export { createRalphLoopHook, type RalphLoopHook } from "./ralph-loop";
 export { createAutoSlashCommandHook } from "./auto-slash-command";
 export { createEditErrorRecoveryHook } from "./edit-error-recovery";
 export { createPrometheusMdOnlyHook } from "./prometheus-md-only";
+export { createSisyphusJuniorNotepadHook } from "./sisyphus-junior-notepad";
 export { createTaskResumeInfoHook } from "./task-resume-info";
 export { createStartWorkHook } from "./start-work";
 export { createAtlasHook } from "./atlas";

src/hooks/keyword-detector/index.test.ts

@@ -419,7 +419,7 @@ describe("keyword-detector agent-specific ultrawork messages", () => {
     }
 
     // #when - ultrawork keyword detected with Sisyphus agent
-    await hook["chat.message"]({ sessionID, agent: "Sisyphus" }, output)
+    await hook["chat.message"]({ sessionID, agent: "sisyphus" }, output)
 
     // #then - should use normal ultrawork message with agent utilization instructions
     const textPart = output.parts.find(p => p.type === "text")
@@ -471,7 +471,7 @@ describe("keyword-detector agent-specific ultrawork messages", () => {
       message: {} as Record<string, unknown>,
       parts: [{ type: "text", text: "ultrawork implement" }],
     }
-    await hook["chat.message"]({ sessionID: sisyphusSessionID, agent: "Sisyphus" }, sisyphusOutput)
+    await hook["chat.message"]({ sessionID: sisyphusSessionID, agent: "sisyphus" }, sisyphusOutput)
 
     // #then - each session should have the correct message type
     const prometheusTextPart = prometheusOutput.parts.find(p => p.type === "text")
@@ -492,7 +492,7 @@ describe("keyword-detector agent-specific ultrawork messages", () => {
     const sessionID = "same-session-agent-switch"
 
     // Simulate: session state was updated to sisyphus (by index.ts updateSessionAgent)
-    updateSessionAgent(sessionID, "Sisyphus")
+    updateSessionAgent(sessionID, "sisyphus")
 
     const output = {
       message: {} as Record<string, unknown>,

src/hooks/prometheus-md-only/index.test.ts

@@ -277,7 +277,7 @@ describe("prometheus-md-only", () => {
 
   describe("with non-Prometheus agent in message storage", () => {
     beforeEach(() => {
-      setupMessageStorage(TEST_SESSION_ID, "Sisyphus")
+      setupMessageStorage(TEST_SESSION_ID, "sisyphus")
     })
 
     test("should not affect non-Prometheus agents", async () => {

src/hooks/prometheus-md-only/index.ts

@@ -89,10 +89,10 @@ export function createPrometheusMdOnlyHook(ctx: PluginInput) {
       const toolName = input.tool
 
       // Inject read-only warning for task tools called by Prometheus
-      if (TASK_TOOLS.includes(toolName)) {
-        const prompt = output.args.prompt as string | undefined
-        if (prompt && !prompt.includes(SYSTEM_DIRECTIVE_PREFIX)) {
-          output.args.prompt = prompt + PLANNING_CONSULT_WARNING
+       if (TASK_TOOLS.includes(toolName)) {
+         const prompt = output.args.prompt as string | undefined
+         if (prompt && !prompt.includes(SYSTEM_DIRECTIVE_PREFIX)) {
+           output.args.prompt = PLANNING_CONSULT_WARNING + prompt
           log(`[${HOOK_NAME}] Injected read-only planning warning to ${toolName}`, {
             sessionID: input.sessionID,
             tool: toolName,

src/hooks/sisyphus-junior-notepad/constants.ts

@@ -0,0 +1,29 @@
+export const HOOK_NAME = "sisyphus-junior-notepad"
+
+export const NOTEPAD_DIRECTIVE = `
+<Work_Context>
+## Notepad Location (for recording learnings)
+NOTEPAD PATH: .sisyphus/notepads/{plan-name}/
+- learnings.md: Record patterns, conventions, successful approaches
+- issues.md: Record problems, blockers, gotchas encountered
+- decisions.md: Record architectural choices and rationales
+- problems.md: Record unresolved issues, technical debt
+
+You SHOULD append findings to notepad files after completing work.
+IMPORTANT: Always APPEND to notepad files - never overwrite or use Edit tool.
+
+## Plan Location (READ ONLY)
+PLAN PATH: .sisyphus/plans/{plan-name}.md
+
+CRITICAL RULE: NEVER MODIFY THE PLAN FILE
+
+The plan file (.sisyphus/plans/*.md) is SACRED and READ-ONLY.
+- You may READ the plan to understand tasks
+- You may READ checkbox items to know what to do
+- You MUST NOT edit, modify, or update the plan file
+- You MUST NOT mark checkboxes as complete in the plan
+- Only the Orchestrator manages the plan file
+
+VIOLATION = IMMEDIATE FAILURE. The Orchestrator tracks plan state.
+</Work_Context>
+`

src/hooks/sisyphus-junior-notepad/index.ts

@@ -0,0 +1,45 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import { isCallerOrchestrator } from "../../shared/session-utils"
+import { SYSTEM_DIRECTIVE_PREFIX } from "../../shared/system-directive"
+import { log } from "../../shared/logger"
+import { HOOK_NAME, NOTEPAD_DIRECTIVE } from "./constants"
+
+export * from "./constants"
+
+export function createSisyphusJuniorNotepadHook(ctx: PluginInput) {
+  return {
+    "tool.execute.before": async (
+      input: { tool: string; sessionID: string; callID: string },
+      output: { args: Record<string, unknown>; message?: string }
+    ): Promise<void> => {
+      // 1. Check if tool is delegate_task
+      if (input.tool !== "delegate_task") {
+        return
+      }
+
+      // 2. Check if caller is Atlas (orchestrator)
+      if (!isCallerOrchestrator(input.sessionID)) {
+        return
+      }
+
+      // 3. Get prompt from output.args
+      const prompt = output.args.prompt as string | undefined
+      if (!prompt) {
+        return
+      }
+
+      // 4. Check for double injection
+      if (prompt.includes(SYSTEM_DIRECTIVE_PREFIX)) {
+        return
+      }
+
+      // 5. Prepend directive
+      output.args.prompt = NOTEPAD_DIRECTIVE + prompt
+
+      // 6. Log injection
+      log(`[${HOOK_NAME}] Injected notepad directive to delegate_task`, {
+        sessionID: input.sessionID,
+      })
+    },
+  }
+}

src/hooks/todo-continuation-enforcer.test.ts

@@ -835,8 +835,8 @@ describe("todo-continuation-enforcer", () => {
 
     // OpenCode returns assistant messages with flat modelID/providerID, not nested model object
     const mockMessagesWithAssistant = [
-      { info: { id: "msg-1", role: "user", agent: "Sisyphus", model: { providerID: "openai", modelID: "gpt-5.2" } } },
-      { info: { id: "msg-2", role: "assistant", agent: "Sisyphus", modelID: "gpt-5.2", providerID: "openai" } },
+      { info: { id: "msg-1", role: "user", agent: "sisyphus", model: { providerID: "openai", modelID: "gpt-5.2" } } },
+      { info: { id: "msg-2", role: "assistant", agent: "sisyphus", modelID: "gpt-5.2", providerID: "openai" } },
     ]
 
     const mockInput = {
@@ -886,8 +886,8 @@ describe("todo-continuation-enforcer", () => {
     setMainSession(sessionID)
 
     const mockMessagesWithCompaction = [
-      { info: { id: "msg-1", role: "user", agent: "Sisyphus", model: { providerID: "anthropic", modelID: "claude-sonnet-4-5" } } },
-      { info: { id: "msg-2", role: "assistant", agent: "Sisyphus", modelID: "claude-sonnet-4-5", providerID: "anthropic" } },
+      { info: { id: "msg-1", role: "user", agent: "sisyphus", model: { providerID: "anthropic", modelID: "claude-sonnet-4-5" } } },
+      { info: { id: "msg-2", role: "assistant", agent: "sisyphus", modelID: "claude-sonnet-4-5", providerID: "anthropic" } },
       { info: { id: "msg-3", role: "assistant", agent: "compaction", modelID: "claude-sonnet-4-5", providerID: "anthropic" } },
     ]
 
@@ -923,7 +923,7 @@ describe("todo-continuation-enforcer", () => {
 
     // #then - continuation uses Sisyphus (skipped compaction agent)
     expect(promptCalls.length).toBe(1)
-    expect(promptCalls[0].agent).toBe("Sisyphus")
+    expect(promptCalls[0].agent).toBe("sisyphus")
   })
 
   test("should skip injection when only compaction agent messages exist", async () => {

src/index.ts

@@ -23,6 +23,7 @@ import {
   createInteractiveBashSessionHook,
 
   createThinkingBlockValidatorHook,
+  createCategorySkillReminderHook,
   createRalphLoopHook,
   createAutoSlashCommandHook,
   createEditErrorRecoveryHook,
@@ -31,6 +32,7 @@ import {
   createStartWorkHook,
   createAtlasHook,
   createPrometheusMdOnlyHook,
+  createSisyphusJuniorNotepadHook,
   createQuestionLabelTruncatorHook,
 } from "./hooks";
 import {
@@ -73,6 +75,7 @@ import {
 import { BackgroundManager } from "./features/background-agent";
 import { SkillMcpManager } from "./features/skill-mcp-manager";
 import { initTaskToastManager } from "./features/task-toast-manager";
+import { TmuxSessionManager } from "./features/tmux-subagent";
 import { type HookName } from "./config";
 import { log, detectExternalNotificationPlugin, getNotificationConflictWarning, resetMessageCursor, includesCaseInsensitive } from "./shared";
 import { loadPluginConfig } from "./plugin-config";
@@ -87,6 +90,14 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
   const pluginConfig = loadPluginConfig(ctx.directory, ctx);
   const disabledHooks = new Set(pluginConfig.disabled_hooks ?? []);
   const firstMessageVariantGate = createFirstMessageVariantGate();
+
+  const tmuxConfig = {
+    enabled: pluginConfig.tmux?.enabled ?? false,
+    layout: pluginConfig.tmux?.layout ?? 'main-vertical',
+    main_pane_size: pluginConfig.tmux?.main_pane_size ?? 60,
+    main_pane_min_width: pluginConfig.tmux?.main_pane_min_width ?? 120,
+    agent_pane_min_width: pluginConfig.tmux?.agent_pane_min_width ?? 40,
+  } as const;
   const isHookEnabled = (hookName: HookName) => !disabledHooks.has(hookName);
 
   const modelCacheState = createModelCacheState();
@@ -181,6 +192,10 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
     ? createThinkingBlockValidatorHook()
     : null;
 
+  const categorySkillReminder = isHookEnabled("category-skill-reminder")
+    ? createCategorySkillReminderHook(ctx)
+    : null;
+
   const ralphLoop = isHookEnabled("ralph-loop")
     ? createRalphLoopHook(ctx, {
         config: pluginConfig.ralph_loop,
@@ -204,11 +219,37 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
     ? createPrometheusMdOnlyHook(ctx)
     : null;
 
+  const sisyphusJuniorNotepad = isHookEnabled("sisyphus-junior-notepad")
+    ? createSisyphusJuniorNotepadHook(ctx)
+    : null;
+
   const questionLabelTruncator = createQuestionLabelTruncatorHook();
 
   const taskResumeInfo = createTaskResumeInfoHook();
 
-  const backgroundManager = new BackgroundManager(ctx, pluginConfig.background_task);
+  const tmuxSessionManager = new TmuxSessionManager(ctx, tmuxConfig);
+
+  const backgroundManager = new BackgroundManager(ctx, pluginConfig.background_task, {
+    tmuxConfig,
+    onSubagentSessionCreated: async (event) => {
+      log("[index] onSubagentSessionCreated callback received", {
+        sessionID: event.sessionID,
+        parentID: event.parentID,
+        title: event.title,
+      });
+      await tmuxSessionManager.onSessionCreated({
+        type: "session.created",
+        properties: {
+          info: {
+            id: event.sessionID,
+            parentID: event.parentID,
+            title: event.title,
+          },
+        },
+      });
+      log("[index] onSubagentSessionCreated callback completed");
+    },
+  });
 
   const atlasHook = isHookEnabled("atlas")
     ? createAtlasHook(ctx, { directory: ctx.directory, backgroundManager })
@@ -238,6 +279,7 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
     "multimodal-looker"
   );
   const lookAt = isMultimodalLookerEnabled ? createLookAt(ctx) : null;
+  const browserProvider = pluginConfig.browser_automation_engine?.provider ?? "playwright";
   const delegateTask = createDelegateTask({
     manager: backgroundManager,
     client: ctx.client,
@@ -245,10 +287,28 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
     userCategories: pluginConfig.categories,
     gitMasterConfig: pluginConfig.git_master,
     sisyphusJuniorModel: pluginConfig.agents?.["sisyphus-junior"]?.model,
+    browserProvider,
+    onSyncSessionCreated: async (event) => {
+      log("[index] onSyncSessionCreated callback", {
+        sessionID: event.sessionID,
+        parentID: event.parentID,
+        title: event.title,
+      });
+      await tmuxSessionManager.onSessionCreated({
+        type: "session.created",
+        properties: {
+          info: {
+            id: event.sessionID,
+            parentID: event.parentID,
+            title: event.title,
+          },
+        },
+      });
+    },
   });
   const disabledSkills = new Set(pluginConfig.disabled_skills ?? []);
   const systemMcpNames = getSystemMcpServerNames();
-  const builtinSkills = createBuiltinSkills().filter((skill) => {
+  const builtinSkills = createBuiltinSkills({ browserProvider }).filter((skill) => {
     if (disabledSkills.has(skill.name as never)) return false;
     if (skill.mcpConfig) {
       for (const mcpName of Object.keys(skill.mcpConfig)) {
@@ -418,6 +478,7 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
       await thinkMode?.event(input);
       await anthropicContextWindowLimitRecovery?.event(input);
       await agentUsageReminder?.event(input);
+      await categorySkillReminder?.event(input);
       await interactiveBashSession?.event(input);
       await ralphLoop?.event(input);
       await atlasHook?.handler(input);
@@ -425,29 +486,36 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
       const { event } = input;
       const props = event.properties as Record<string, unknown> | undefined;
 
-      if (event.type === "session.created") {
-        const sessionInfo = props?.info as
-          | { id?: string; title?: string; parentID?: string }
-          | undefined;
-        if (!sessionInfo?.parentID) {
-          setMainSession(sessionInfo?.id);
-        }
-        firstMessageVariantGate.markSessionCreated(sessionInfo);
-      }
+       if (event.type === "session.created") {
+         const sessionInfo = props?.info as
+           | { id?: string; title?: string; parentID?: string }
+           | undefined;
+         log("[event] session.created", { sessionInfo, props });
+         if (!sessionInfo?.parentID) {
+           setMainSession(sessionInfo?.id);
+         }
+         firstMessageVariantGate.markSessionCreated(sessionInfo);
+         await tmuxSessionManager.onSessionCreated(
+           event as { type: string; properties?: { info?: { id?: string; parentID?: string; title?: string } } }
+         );
+       }
 
-      if (event.type === "session.deleted") {
-        const sessionInfo = props?.info as { id?: string } | undefined;
-        if (sessionInfo?.id === getMainSessionID()) {
-          setMainSession(undefined);
-        }
-        if (sessionInfo?.id) {
-          clearSessionAgent(sessionInfo.id);
-          resetMessageCursor(sessionInfo.id);
-          firstMessageVariantGate.clear(sessionInfo.id);
-          await skillMcpManager.disconnectSession(sessionInfo.id);
-          await lspManager.cleanupTempDirectoryClients();
-        }
-      }
+       if (event.type === "session.deleted") {
+         const sessionInfo = props?.info as { id?: string } | undefined;
+         if (sessionInfo?.id === getMainSessionID()) {
+           setMainSession(undefined);
+         }
+         if (sessionInfo?.id) {
+           clearSessionAgent(sessionInfo.id);
+           resetMessageCursor(sessionInfo.id);
+           firstMessageVariantGate.clear(sessionInfo.id);
+           await skillMcpManager.disconnectSession(sessionInfo.id);
+           await lspManager.cleanupTempDirectoryClients();
+           await tmuxSessionManager.onSessionDeleted({
+             sessionID: sessionInfo.id,
+           });
+         }
+       }
 
       if (event.type === "message.updated") {
         const info = props?.info as Record<string, unknown> | undefined;
@@ -495,6 +563,7 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
       await directoryReadmeInjector?.["tool.execute.before"]?.(input, output);
       await rulesInjector?.["tool.execute.before"]?.(input, output);
       await prometheusMdOnly?.["tool.execute.before"]?.(input, output);
+      await sisyphusJuniorNotepad?.["tool.execute.before"]?.(input, output);
       await atlasHook?.["tool.execute.before"]?.(input, output);
 
       if (input.tool === "task") {
@@ -574,6 +643,7 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
       await rulesInjector?.["tool.execute.after"](input, output);
       await emptyTaskResponseDetector?.["tool.execute.after"](input, output);
       await agentUsageReminder?.["tool.execute.after"](input, output);
+      await categorySkillReminder?.["tool.execute.after"](input, output);
       await interactiveBashSession?.["tool.execute.after"](input, output);
 await editErrorRecovery?.["tool.execute.after"](input, output);
         await delegateTaskRetry?.["tool.execute.after"](input, output);

src/mcp/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## OVERVIEW
 
-3 remote MCP servers: web search, documentation, code search. HTTP/SSE transport.
+3 remote MCP servers: web search, documentation, code search. HTTP/SSE transport. Part of three-tier MCP system.
 
 ## STRUCTURE
 
@@ -20,10 +20,16 @@ mcp/
 
 | Name | URL | Purpose | Auth |
 |------|-----|---------|------|
-| websearch | mcp.exa.ai | Real-time web search | EXA_API_KEY |
-| context7 | mcp.context7.com | Library docs | None |
+| websearch | mcp.exa.ai/mcp?tools=web_search_exa | Real-time web search | EXA_API_KEY |
+| context7 | mcp.context7.com/mcp | Library docs | None |
 | grep_app | mcp.grep.app | GitHub code search | None |
 
+## THREE-TIER MCP SYSTEM
+
+1. **Built-in** (this directory): websearch, context7, grep_app
+2. **Claude Code compat**: `.mcp.json` with `${VAR}` expansion
+3. **Skill-embedded**: YAML frontmatter in skills (handled by skill-mcp-manager)
+
 ## CONFIG PATTERN
 
 ```typescript
@@ -54,5 +60,5 @@ const mcps = createBuiltinMcps(["websearch"])  // Disable specific
 ## NOTES
 
 - **Remote only**: HTTP/SSE, no stdio
-- **Disable**: User can set `disabled_mcps: ["name"]`
+- **Disable**: User can set `disabled_mcps: ["name"]` in config
 - **Exa**: Requires `EXA_API_KEY` env var

src/plugin-handlers/config-handler.ts

@@ -165,6 +165,7 @@ export function createConfigHandler(deps: ConfigHandlerDeps) {
       ...discoveredUserSkills,
     ];
 
+    const browserProvider = pluginConfig.browser_automation_engine?.provider ?? "playwright";
     const builtinAgents = await createBuiltinAgents(
       migratedDisabledAgents,
       pluginConfig.agents,
@@ -173,7 +174,8 @@ export function createConfigHandler(deps: ConfigHandlerDeps) {
       pluginConfig.categories,
       pluginConfig.git_master,
       allDiscoveredSkills,
-      ctx.client
+      ctx.client,
+      browserProvider
     );
 
     // Claude Code agents: Do NOT apply permission migration

src/shared/AGENTS.md

@@ -1,81 +1,78 @@
 # SHARED UTILITIES KNOWLEDGE BASE
 
 ## OVERVIEW
-
-34 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution, agent display names.
+55 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution.
 
 ## STRUCTURE
-
 ```
 shared/
-├── logger.ts              # File-based logging
-├── permission-compat.ts   # Agent tool restrictions
-├── dynamic-truncator.ts   # Token-aware truncation
-├── frontmatter.ts         # YAML frontmatter
-├── jsonc-parser.ts        # JSON with Comments
-├── data-path.ts           # XDG-compliant storage
-├── opencode-config-dir.ts # ~/.config/opencode
-├── claude-config-dir.ts   # ~/.claude
-├── migration.ts           # Legacy config migration
-├── opencode-version.ts    # Version comparison
-├── external-plugin-detector.ts # OAuth spoofing detection
-├── model-requirements.ts  # Agent/Category requirements
-├── model-availability.ts  # Models fetch + fuzzy match
-├── model-resolver.ts      # 3-step resolution
-├── model-sanitizer.ts     # Model ID normalization
-├── shell-env.ts           # Cross-platform shell
-├── agent-display-names.ts # Agent display name mapping
-├── agent-tool-restrictions.ts # Tool restriction helpers
-├── agent-variant.ts       # Agent variant detection
-├── command-executor.ts    # Subprocess execution
-├── config-errors.ts       # Config error types
-├── deep-merge.ts          # Deep object merge
-├── file-reference-resolver.ts # File path resolution
-├── file-utils.ts          # File utilities
-├── hook-disabled.ts       # Hook enable/disable check
-├── pattern-matcher.ts     # Glob pattern matching
-├── session-cursor.ts      # Session cursor tracking
-├── snake-case.ts          # String case conversion
-├── system-directive.ts    # System prompt helpers
-├── tool-name.ts           # Tool name constants
-├── zip-extractor.ts       # ZIP file extraction
-├── index.ts               # Barrel export
-└── *.test.ts              # Colocated tests
+├── tmux/                  # Tmux TUI integration (types, utils, constants)
+├── logger.ts              # File-based logging (/tmp/oh-my-opencode.log)
+├── dynamic-truncator.ts   # Token-aware context window management (194 lines)
+├── model-resolver.ts      # 3-step resolution (Override → Fallback → Default)
+├── model-requirements.ts  # Agent/category model fallback chains (132 lines)
+├── model-availability.ts  # Provider model fetching & fuzzy matching (154 lines)
+├── jsonc-parser.ts        # JSONC parsing with comment support
+├── frontmatter.ts         # YAML frontmatter extraction (JSON_SCHEMA only)
+├── data-path.ts           # XDG-compliant storage resolution
+├── opencode-config-dir.ts # ~/.config/opencode resolution (143 lines)
+├── claude-config-dir.ts   # ~/.claude resolution
+├── migration.ts           # Legacy config migration logic (231 lines)
+├── opencode-version.ts    # Semantic version comparison
+├── permission-compat.ts   # Agent tool restriction enforcement
+├── system-directive.ts    # Unified system message prefix & types
+├── session-utils.ts       # Session cursor, orchestrator detection
+├── shell-env.ts           # Cross-platform shell environment
+├── agent-variant.ts       # Agent variant from config
+├── zip-extractor.ts       # Binary/Resource ZIP extraction
+├── deep-merge.ts          # Recursive object merging (proto-pollution safe, MAX_DEPTH=50)
+├── case-insensitive.ts    # Case-insensitive object lookups
+├── session-cursor.ts      # Session message cursor tracking
+├── command-executor.ts    # Shell command execution (225 lines)
+└── index.ts               # Barrel export for all utilities
 ```
 
-## WHEN TO USE
+## MOST IMPORTED
+| Utility | Users | Purpose |
+|---------|-------|---------|
+| logger.ts | 16+ | Background task visibility |
+| system-directive.ts | 8+ | Message filtering |
+| opencode-config-dir.ts | 8+ | Path resolution |
+| permission-compat.ts | 6+ | Tool restrictions |
 
+## WHEN TO USE
 | Task | Utility |
 |------|---------|
-| Debug logging | `log(message, data)` |
-| Limit context | `dynamicTruncate(ctx, sessionId, output)` |
-| Parse frontmatter | `parseFrontmatter(content)` |
-| Load JSONC | `parseJsonc(text)` or `readJsoncFile(path)` |
-| Restrict tools | `createAgentToolAllowlist(tools)` |
-| Resolve paths | `getOpenCodeConfigDir()` |
-| Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` |
-| Resolve model | `resolveModelWithFallback()` |
-| Agent display name | `getAgentDisplayName(agentName)` |
+| Path Resolution | `getOpenCodeConfigDir()`, `getDataPath()` |
+| Token Truncation | `dynamicTruncate(ctx, sessionId, output)` |
+| Config Parsing | `readJsoncFile<T>(path)`, `parseJsonc(text)` |
+| Model Resolution | `resolveModelWithFallback(client, reqs, override)` |
+| Version Gating | `isOpenCodeVersionAtLeast(version)` |
+| YAML Metadata | `parseFrontmatter(content)` |
+| Tool Security | `createAgentToolAllowlist(tools)` |
+| System Messages | `createSystemDirective(type)`, `isSystemDirective(msg)` |
+| Deep Merge | `deepMerge(target, source)` |
 
-## PATTERNS
+## KEY PATTERNS
 
+**3-Step Resolution** (Override → Fallback → Default):
 ```typescript
-// Token-aware truncation
-const { result } = await dynamicTruncate(ctx, sessionID, buffer)
+const model = resolveModelWithFallback({
+  userModel: config.agents.sisyphus.model,
+  fallbackChain: AGENT_MODEL_REQUIREMENTS.sisyphus.fallbackChain,
+  availableModels: fetchedModels,
+})
+```
 
-// JSONC config
-const settings = readJsoncFile<Settings>(configPath)
-
-// Version-gated
-if (isOpenCodeVersionAtLeast("1.1.0")) { /* ... */ }
-
-// Model resolution
-const model = await resolveModelWithFallback(client, requirements, override)
+**System Directive Filtering**:
+```typescript
+if (isSystemDirective(message)) return  // Skip system-generated
+const directive = createSystemDirective("TODO CONTINUATION")
 ```
 
 ## ANTI-PATTERNS
-
-- **Raw JSON.parse**: Use `jsonc-parser.ts`
-- **Hardcoded paths**: Use `*-config-dir.ts`
-- **console.log**: Use `logger.ts` for background
-- **Unbounded output**: Use `dynamic-truncator.ts`
+- **Raw JSON.parse**: Use `jsonc-parser.ts` for comment support
+- **Hardcoded Paths**: Use `*-config-dir.ts` or `data-path.ts`
+- **console.log**: Use `logger.ts` for background task visibility
+- **Unbounded Output**: Use `dynamic-truncator.ts` to prevent overflow
+- **Manual Version Check**: Use `opencode-version.ts` for semver safety

src/shared/agent-variant.test.ts

@@ -18,12 +18,12 @@ describe("resolveAgentVariant", () => {
     // #given
     const config = {
       agents: {
-        Sisyphus: { variant: "low" },
+        sisyphus: { variant: "low" },
       },
     } as OhMyOpenCodeConfig
 
     // #when
-    const variant = resolveAgentVariant(config, "Sisyphus")
+    const variant = resolveAgentVariant(config, "sisyphus")
 
     // #then
     expect(variant).toBe("low")
@@ -33,7 +33,7 @@ describe("resolveAgentVariant", () => {
     // #given
     const config = {
       agents: {
-        Sisyphus: { category: "ultrabrain" },
+        sisyphus: { category: "ultrabrain" },
       },
       categories: {
         ultrabrain: { model: "openai/gpt-5.2", variant: "xhigh" },
@@ -41,7 +41,7 @@ describe("resolveAgentVariant", () => {
     } as OhMyOpenCodeConfig
 
     // #when
-    const variant = resolveAgentVariant(config, "Sisyphus")
+    const variant = resolveAgentVariant(config, "sisyphus")
 
     // #then
     expect(variant).toBe("xhigh")
@@ -53,13 +53,13 @@ describe("applyAgentVariant", () => {
     // #given
     const config = {
       agents: {
-        Sisyphus: { variant: "low" },
+        sisyphus: { variant: "low" },
       },
     } as OhMyOpenCodeConfig
     const message: { variant?: string } = {}
 
     // #when
-    applyAgentVariant(config, "Sisyphus", message)
+    applyAgentVariant(config, "sisyphus", message)
 
     // #then
     expect(message.variant).toBe("low")
@@ -69,13 +69,13 @@ describe("applyAgentVariant", () => {
     // #given
     const config = {
       agents: {
-        Sisyphus: { variant: "low" },
+        sisyphus: { variant: "low" },
       },
     } as OhMyOpenCodeConfig
     const message = { variant: "max" }
 
     // #when
-    applyAgentVariant(config, "Sisyphus", message)
+    applyAgentVariant(config, "sisyphus", message)
 
     // #then
     expect(message.variant).toBe("max")

src/shared/connected-providers-cache.ts

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs"
+import { join } from "path"
+import { log } from "./logger"
+import { getOmoOpenCodeCacheDir } from "./data-path"
+
+const CONNECTED_PROVIDERS_CACHE_FILE = "connected-providers.json"
+const PROVIDER_MODELS_CACHE_FILE = "provider-models.json"
+
+interface ConnectedProvidersCache {
+	connected: string[]
+	updatedAt: string
+}
+
+interface ProviderModelsCache {
+	models: Record<string, string[]>
+	connected: string[]
+	updatedAt: string
+}
+
+function getCacheFilePath(filename: string): string {
+	return join(getOmoOpenCodeCacheDir(), filename)
+}
+
+function ensureCacheDir(): void {
+	const cacheDir = getOmoOpenCodeCacheDir()
+	if (!existsSync(cacheDir)) {
+		mkdirSync(cacheDir, { recursive: true })
+	}
+}
+
+/**
+ * Read the connected providers cache.
+ * Returns the list of connected provider IDs, or null if cache doesn't exist.
+ */
+export function readConnectedProvidersCache(): string[] | null {
+	const cacheFile = getCacheFilePath(CONNECTED_PROVIDERS_CACHE_FILE)
+
+	if (!existsSync(cacheFile)) {
+		log("[connected-providers-cache] Cache file not found", { cacheFile })
+		return null
+	}
+
+	try {
+		const content = readFileSync(cacheFile, "utf-8")
+		const data = JSON.parse(content) as ConnectedProvidersCache
+		log("[connected-providers-cache] Read cache", { count: data.connected.length, updatedAt: data.updatedAt })
+		return data.connected
+	} catch (err) {
+		log("[connected-providers-cache] Error reading cache", { error: String(err) })
+		return null
+	}
+}
+
+/**
+ * Check if connected providers cache exists.
+ */
+export function hasConnectedProvidersCache(): boolean {
+	const cacheFile = getCacheFilePath(CONNECTED_PROVIDERS_CACHE_FILE)
+	return existsSync(cacheFile)
+}
+
+/**
+ * Write the connected providers cache.
+ */
+function writeConnectedProvidersCache(connected: string[]): void {
+	ensureCacheDir()
+	const cacheFile = getCacheFilePath(CONNECTED_PROVIDERS_CACHE_FILE)
+
+	const data: ConnectedProvidersCache = {
+		connected,
+		updatedAt: new Date().toISOString(),
+	}
+
+	try {
+		writeFileSync(cacheFile, JSON.stringify(data, null, 2))
+		log("[connected-providers-cache] Cache written", { count: connected.length })
+	} catch (err) {
+		log("[connected-providers-cache] Error writing cache", { error: String(err) })
+	}
+}
+
+/**
+ * Read the provider-models cache.
+ * Returns the cache data, or null if cache doesn't exist.
+ */
+export function readProviderModelsCache(): ProviderModelsCache | null {
+	const cacheFile = getCacheFilePath(PROVIDER_MODELS_CACHE_FILE)
+
+	if (!existsSync(cacheFile)) {
+		log("[connected-providers-cache] Provider-models cache file not found", { cacheFile })
+		return null
+	}
+
+	try {
+		const content = readFileSync(cacheFile, "utf-8")
+		const data = JSON.parse(content) as ProviderModelsCache
+		log("[connected-providers-cache] Read provider-models cache", { 
+			providerCount: Object.keys(data.models).length, 
+			updatedAt: data.updatedAt 
+		})
+		return data
+	} catch (err) {
+		log("[connected-providers-cache] Error reading provider-models cache", { error: String(err) })
+		return null
+	}
+}
+
+/**
+ * Check if provider-models cache exists.
+ */
+export function hasProviderModelsCache(): boolean {
+	const cacheFile = getCacheFilePath(PROVIDER_MODELS_CACHE_FILE)
+	return existsSync(cacheFile)
+}
+
+/**
+ * Write the provider-models cache.
+ */
+export function writeProviderModelsCache(data: { models: Record<string, string[]>; connected: string[] }): void {
+	ensureCacheDir()
+	const cacheFile = getCacheFilePath(PROVIDER_MODELS_CACHE_FILE)
+
+	const cacheData: ProviderModelsCache = {
+		...data,
+		updatedAt: new Date().toISOString(),
+	}
+
+	try {
+		writeFileSync(cacheFile, JSON.stringify(cacheData, null, 2))
+		log("[connected-providers-cache] Provider-models cache written", { 
+			providerCount: Object.keys(data.models).length 
+		})
+	} catch (err) {
+		log("[connected-providers-cache] Error writing provider-models cache", { error: String(err) })
+	}
+}
+
+/**
+ * Update the connected providers cache by fetching from the client.
+ * Also updates the provider-models cache with model lists per provider.
+ */
+export async function updateConnectedProvidersCache(client: {
+	provider?: {
+		list?: () => Promise<{ data?: { connected?: string[] } }>
+	}
+	model?: {
+		list?: () => Promise<{ data?: Array<{ id: string; provider: string }> }>
+	}
+}): Promise<void> {
+	if (!client?.provider?.list) {
+		log("[connected-providers-cache] client.provider.list not available")
+		return
+	}
+
+	try {
+		const result = await client.provider.list()
+		const connected = result.data?.connected ?? []
+		log("[connected-providers-cache] Fetched connected providers", { count: connected.length, providers: connected })
+
+		writeConnectedProvidersCache(connected)
+
+		// Also update provider-models cache if model.list is available
+		if (client.model?.list) {
+			try {
+				const modelsResult = await client.model.list()
+				const models = modelsResult.data ?? []
+
+				const modelsByProvider: Record<string, string[]> = {}
+				for (const model of models) {
+					if (!modelsByProvider[model.provider]) {
+						modelsByProvider[model.provider] = []
+					}
+					modelsByProvider[model.provider].push(model.id)
+				}
+
+				writeProviderModelsCache({
+					models: modelsByProvider,
+					connected,
+				})
+
+				log("[connected-providers-cache] Provider-models cache updated", {
+					providerCount: Object.keys(modelsByProvider).length,
+					totalModels: models.length,
+				})
+			} catch (modelErr) {
+				log("[connected-providers-cache] Error fetching models", { error: String(modelErr) })
+			}
+		}
+	} catch (err) {
+		log("[connected-providers-cache] Error updating cache", { error: String(err) })
+	}
+}

src/shared/data-path.ts

@@ -20,3 +20,28 @@ export function getDataDir(): string {
 export function getOpenCodeStorageDir(): string {
   return path.join(getDataDir(), "opencode", "storage")
 }
+
+/**
+ * Returns the user-level cache directory.
+ * Matches OpenCode's behavior via xdg-basedir:
+ * - All platforms: XDG_CACHE_HOME or ~/.cache
+ */
+export function getCacheDir(): string {
+  return process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache")
+}
+
+/**
+ * Returns the oh-my-opencode cache directory.
+ * All platforms: ~/.cache/oh-my-opencode
+ */
+export function getOmoOpenCodeCacheDir(): string {
+  return path.join(getCacheDir(), "oh-my-opencode")
+}
+
+/**
+ * Returns the OpenCode cache directory (for reading OpenCode's cache).
+ * All platforms: ~/.cache/opencode
+ */
+export function getOpenCodeCacheDir(): string {
+  return path.join(getCacheDir(), "opencode")
+}

src/shared/index.ts

@@ -28,4 +28,7 @@ export * from "./agent-tool-restrictions"
 export * from "./model-requirements"
 export * from "./model-resolver"
 export * from "./model-availability"
+export * from "./connected-providers-cache"
 export * from "./case-insensitive"
+export * from "./session-utils"
+export * from "./tmux"

src/shared/model-availability.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from "bun:test"
 import { mkdtempSync, writeFileSync, rmSync } from "fs"
 import { tmpdir } from "os"
 import { join } from "path"
-import { fetchAvailableModels, fuzzyMatchModel, __resetModelCache } from "./model-availability"
+import { fetchAvailableModels, fuzzyMatchModel, getConnectedProviders, __resetModelCache } from "./model-availability"
 
 describe("fetchAvailableModels", () => {
   let tempDir: string
@@ -30,14 +30,16 @@ describe("fetchAvailableModels", () => {
     writeFileSync(join(cacheDir, "models.json"), JSON.stringify(data))
   }
 
-  it("#given cache file with models #when fetchAvailableModels called #then returns Set of model IDs", async () => {
+  it("#given cache file with models #when fetchAvailableModels called with connectedProviders #then returns Set of model IDs", async () => {
     writeModelsCache({
       openai: { id: "openai", models: { "gpt-5.2": { id: "gpt-5.2" } } },
       anthropic: { id: "anthropic", models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
       google: { id: "google", models: { "gemini-3-pro": { id: "gemini-3-pro" } } },
     })
 
-    const result = await fetchAvailableModels()
+    const result = await fetchAvailableModels(undefined, {
+      connectedProviders: ["openai", "anthropic", "google"]
+    })
 
     expect(result).toBeInstanceOf(Set)
     expect(result.size).toBe(3)
@@ -46,36 +48,47 @@ describe("fetchAvailableModels", () => {
     expect(result.has("google/gemini-3-pro")).toBe(true)
   })
 
-  it("#given cache file not found #when fetchAvailableModels called #then returns empty Set", async () => {
+  it("#given connectedProviders unknown #when fetchAvailableModels called without options #then returns empty Set", async () => {
+    writeModelsCache({
+      openai: { id: "openai", models: { "gpt-5.2": { id: "gpt-5.2" } } },
+    })
+
     const result = await fetchAvailableModels()
 
     expect(result).toBeInstanceOf(Set)
     expect(result.size).toBe(0)
   })
 
-  it("#given cache read twice #when second call made #then uses cached result", async () => {
+  it("#given cache file not found #when fetchAvailableModels called with connectedProviders #then returns empty Set", async () => {
+    const result = await fetchAvailableModels(undefined, { connectedProviders: ["openai"] })
+
+    expect(result).toBeInstanceOf(Set)
+    expect(result.size).toBe(0)
+  })
+
+  it("#given cache read twice #when second call made with same providers #then reads fresh each time", async () => {
     writeModelsCache({
       openai: { id: "openai", models: { "gpt-5.2": { id: "gpt-5.2" } } },
       anthropic: { id: "anthropic", models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
     })
 
-    const result1 = await fetchAvailableModels()
-    const result2 = await fetchAvailableModels()
+    const result1 = await fetchAvailableModels(undefined, { connectedProviders: ["openai"] })
+    const result2 = await fetchAvailableModels(undefined, { connectedProviders: ["openai"] })
 
-    expect(result1).toEqual(result2)
+    expect(result1.size).toBe(result2.size)
     expect(result1.has("openai/gpt-5.2")).toBe(true)
   })
 
-  it("#given empty providers in cache #when fetchAvailableModels called #then returns empty Set", async () => {
+  it("#given empty providers in cache #when fetchAvailableModels called with connectedProviders #then returns empty Set", async () => {
     writeModelsCache({})
 
-    const result = await fetchAvailableModels()
+    const result = await fetchAvailableModels(undefined, { connectedProviders: ["openai"] })
 
     expect(result).toBeInstanceOf(Set)
     expect(result.size).toBe(0)
   })
 
-  it("#given cache file with various providers #when fetchAvailableModels called #then extracts all IDs correctly", async () => {
+  it("#given cache file with various providers #when fetchAvailableModels called with all providers #then extracts all IDs correctly", async () => {
     writeModelsCache({
       openai: { id: "openai", models: { "gpt-5.2-codex": { id: "gpt-5.2-codex" } } },
       anthropic: { id: "anthropic", models: { "claude-sonnet-4-5": { id: "claude-sonnet-4-5" } } },
@@ -83,7 +96,9 @@ describe("fetchAvailableModels", () => {
       opencode: { id: "opencode", models: { "gpt-5-nano": { id: "gpt-5-nano" } } },
     })
 
-    const result = await fetchAvailableModels()
+    const result = await fetchAvailableModels(undefined, {
+      connectedProviders: ["openai", "anthropic", "google", "opencode"]
+    })
 
     expect(result.size).toBe(4)
     expect(result.has("openai/gpt-5.2-codex")).toBe(true)
@@ -239,3 +254,359 @@ describe("fuzzyMatchModel", () => {
 		expect(result).toBeNull()
 	})
 })
+
+describe("getConnectedProviders", () => {
+	//#given SDK client with connected providers
+	//#when provider.list returns data
+	//#then returns connected array
+	it("should return connected providers from SDK", async () => {
+		const mockClient = {
+			provider: {
+				list: async () => ({
+					data: { connected: ["anthropic", "opencode", "google"] }
+				})
+			}
+		}
+
+		const result = await getConnectedProviders(mockClient)
+
+		expect(result).toEqual(["anthropic", "opencode", "google"])
+	})
+
+	//#given SDK client
+	//#when provider.list throws error
+	//#then returns empty array
+	it("should return empty array on SDK error", async () => {
+		const mockClient = {
+			provider: {
+				list: async () => { throw new Error("Network error") }
+			}
+		}
+
+		const result = await getConnectedProviders(mockClient)
+
+		expect(result).toEqual([])
+	})
+
+	//#given SDK client with empty connected array
+	//#when provider.list returns empty
+	//#then returns empty array
+	it("should return empty array when no providers connected", async () => {
+		const mockClient = {
+			provider: {
+				list: async () => ({ data: { connected: [] } })
+			}
+		}
+
+		const result = await getConnectedProviders(mockClient)
+
+		expect(result).toEqual([])
+	})
+
+	//#given SDK client without provider.list method
+	//#when getConnectedProviders called
+	//#then returns empty array
+	it("should return empty array when client.provider.list not available", async () => {
+		const mockClient = {}
+
+		const result = await getConnectedProviders(mockClient)
+
+		expect(result).toEqual([])
+	})
+
+	//#given null client
+	//#when getConnectedProviders called
+	//#then returns empty array
+	it("should return empty array for null client", async () => {
+		const result = await getConnectedProviders(null)
+
+		expect(result).toEqual([])
+	})
+
+	//#given SDK client with missing data.connected
+	//#when provider.list returns without connected field
+	//#then returns empty array
+	it("should return empty array when data.connected is undefined", async () => {
+		const mockClient = {
+			provider: {
+				list: async () => ({ data: {} })
+			}
+		}
+
+		const result = await getConnectedProviders(mockClient)
+
+		expect(result).toEqual([])
+	})
+})
+
+describe("fetchAvailableModels with connected providers filtering", () => {
+	let tempDir: string
+	let originalXdgCache: string | undefined
+
+	beforeEach(() => {
+		__resetModelCache()
+		tempDir = mkdtempSync(join(tmpdir(), "opencode-test-"))
+		originalXdgCache = process.env.XDG_CACHE_HOME
+		process.env.XDG_CACHE_HOME = tempDir
+	})
+
+	afterEach(() => {
+		if (originalXdgCache !== undefined) {
+			process.env.XDG_CACHE_HOME = originalXdgCache
+		} else {
+			delete process.env.XDG_CACHE_HOME
+		}
+		rmSync(tempDir, { recursive: true, force: true })
+	})
+
+	function writeModelsCache(data: Record<string, any>) {
+		const cacheDir = join(tempDir, "opencode")
+		require("fs").mkdirSync(cacheDir, { recursive: true })
+		writeFileSync(join(cacheDir, "models.json"), JSON.stringify(data))
+	}
+
+	//#given cache with multiple providers
+	//#when connectedProviders specifies one provider
+	//#then only returns models from that provider
+	it("should filter models by connected providers", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+			anthropic: { models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
+			google: { models: { "gemini-3-pro": { id: "gemini-3-pro" } } },
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: ["anthropic"]
+		})
+
+		expect(result.size).toBe(1)
+		expect(result.has("anthropic/claude-opus-4-5")).toBe(true)
+		expect(result.has("openai/gpt-5.2")).toBe(false)
+		expect(result.has("google/gemini-3-pro")).toBe(false)
+	})
+
+	//#given cache with multiple providers
+	//#when connectedProviders specifies multiple providers
+	//#then returns models from all specified providers
+	it("should filter models by multiple connected providers", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+			anthropic: { models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
+			google: { models: { "gemini-3-pro": { id: "gemini-3-pro" } } },
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: ["anthropic", "google"]
+		})
+
+		expect(result.size).toBe(2)
+		expect(result.has("anthropic/claude-opus-4-5")).toBe(true)
+		expect(result.has("google/gemini-3-pro")).toBe(true)
+		expect(result.has("openai/gpt-5.2")).toBe(false)
+	})
+
+	//#given cache with models
+	//#when connectedProviders is empty array
+	//#then returns empty set
+	it("should return empty set when connectedProviders is empty", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+			anthropic: { models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: []
+		})
+
+		expect(result.size).toBe(0)
+	})
+
+	//#given cache with models
+	//#when connectedProviders is undefined (no options)
+	//#then returns empty set (triggers fallback in resolver)
+	it("should return empty set when connectedProviders not specified", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+			anthropic: { models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
+		})
+
+		const result = await fetchAvailableModels()
+
+		expect(result.size).toBe(0)
+	})
+
+	//#given cache with models
+	//#when connectedProviders contains provider not in cache
+	//#then returns empty set for that provider
+	it("should handle provider not in cache gracefully", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: ["azure"]
+		})
+
+		expect(result.size).toBe(0)
+	})
+
+	//#given cache with models and mixed connected providers
+	//#when some providers exist in cache and some don't
+	//#then returns models only from matching providers
+	it("should return models from providers that exist in both cache and connected list", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+			anthropic: { models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: ["anthropic", "azure", "unknown"]
+		})
+
+		expect(result.size).toBe(1)
+		expect(result.has("anthropic/claude-opus-4-5")).toBe(true)
+	})
+
+	//#given filtered fetch
+	//#when called twice with different filters
+	//#then does NOT use cache (dynamic per-session)
+	it("should not cache filtered results", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+			anthropic: { models: { "claude-opus-4-5": { id: "claude-opus-4-5" } } },
+		})
+
+		// First call with anthropic
+		const result1 = await fetchAvailableModels(undefined, {
+			connectedProviders: ["anthropic"]
+		})
+		expect(result1.size).toBe(1)
+
+		// Second call with openai - should work, not cached
+		const result2 = await fetchAvailableModels(undefined, {
+			connectedProviders: ["openai"]
+		})
+		expect(result2.size).toBe(1)
+		expect(result2.has("openai/gpt-5.2")).toBe(true)
+	})
+
+	//#given connectedProviders unknown
+	//#when called twice without connectedProviders
+	//#then always returns empty set (triggers fallback)
+	it("should return empty set when connectedProviders unknown", async () => {
+		writeModelsCache({
+			openai: { models: { "gpt-5.2": { id: "gpt-5.2" } } },
+		})
+
+		const result1 = await fetchAvailableModels()
+		const result2 = await fetchAvailableModels()
+
+		expect(result1.size).toBe(0)
+		expect(result2.size).toBe(0)
+	})
+})
+
+describe("fetchAvailableModels with provider-models cache (whitelist-filtered)", () => {
+	let tempDir: string
+	let originalXdgCache: string | undefined
+
+	beforeEach(() => {
+		__resetModelCache()
+		tempDir = mkdtempSync(join(tmpdir(), "opencode-test-"))
+		originalXdgCache = process.env.XDG_CACHE_HOME
+		process.env.XDG_CACHE_HOME = tempDir
+	})
+
+	afterEach(() => {
+		if (originalXdgCache !== undefined) {
+			process.env.XDG_CACHE_HOME = originalXdgCache
+		} else {
+			delete process.env.XDG_CACHE_HOME
+		}
+		rmSync(tempDir, { recursive: true, force: true })
+	})
+
+	function writeProviderModelsCache(data: { models: Record<string, string[]>; connected: string[] }) {
+		const cacheDir = join(tempDir, "oh-my-opencode")
+		require("fs").mkdirSync(cacheDir, { recursive: true })
+		writeFileSync(join(cacheDir, "provider-models.json"), JSON.stringify({
+			...data,
+			updatedAt: new Date().toISOString()
+		}))
+	}
+
+	function writeModelsCache(data: Record<string, any>) {
+		const cacheDir = join(tempDir, "opencode")
+		require("fs").mkdirSync(cacheDir, { recursive: true })
+		writeFileSync(join(cacheDir, "models.json"), JSON.stringify(data))
+	}
+
+	//#given provider-models cache exists (whitelist-filtered)
+	//#when fetchAvailableModels called
+	//#then uses provider-models cache instead of models.json
+	it("should prefer provider-models cache over models.json", async () => {
+		writeProviderModelsCache({
+			models: {
+				opencode: ["big-pickle", "gpt-5-nano"],
+				anthropic: ["claude-opus-4-5"]
+			},
+			connected: ["opencode", "anthropic"]
+		})
+		writeModelsCache({
+			opencode: { models: { "big-pickle": {}, "gpt-5-nano": {}, "gpt-5.2": {} } },
+			anthropic: { models: { "claude-opus-4-5": {}, "claude-sonnet-4-5": {} } }
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: ["opencode", "anthropic"]
+		})
+
+		expect(result.size).toBe(3)
+		expect(result.has("opencode/big-pickle")).toBe(true)
+		expect(result.has("opencode/gpt-5-nano")).toBe(true)
+		expect(result.has("anthropic/claude-opus-4-5")).toBe(true)
+		expect(result.has("opencode/gpt-5.2")).toBe(false)
+		expect(result.has("anthropic/claude-sonnet-4-5")).toBe(false)
+	})
+
+	//#given only models.json exists (no provider-models cache)
+	//#when fetchAvailableModels called
+	//#then falls back to models.json (no whitelist filtering)
+	it("should fallback to models.json when provider-models cache not found", async () => {
+		writeModelsCache({
+			opencode: { models: { "big-pickle": {}, "gpt-5-nano": {}, "gpt-5.2": {} } },
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: ["opencode"]
+		})
+
+		expect(result.size).toBe(3)
+		expect(result.has("opencode/big-pickle")).toBe(true)
+		expect(result.has("opencode/gpt-5-nano")).toBe(true)
+		expect(result.has("opencode/gpt-5.2")).toBe(true)
+	})
+
+	//#given provider-models cache with whitelist
+	//#when connectedProviders filters to subset
+	//#then only returns models from connected providers
+	it("should filter by connectedProviders even with provider-models cache", async () => {
+		writeProviderModelsCache({
+			models: {
+				opencode: ["big-pickle"],
+				anthropic: ["claude-opus-4-5"],
+				google: ["gemini-3-pro"]
+			},
+			connected: ["opencode", "anthropic", "google"]
+		})
+
+		const result = await fetchAvailableModels(undefined, {
+			connectedProviders: ["opencode"]
+		})
+
+		expect(result.size).toBe(1)
+		expect(result.has("opencode/big-pickle")).toBe(true)
+		expect(result.has("anthropic/claude-opus-4-5")).toBe(false)
+		expect(result.has("google/gemini-3-pro")).toBe(false)
+	})
+})

src/shared/model-availability.ts

@@ -1,12 +1,8 @@
-/**
- * Fuzzy matching utility for model names
- * Supports substring matching with provider filtering and priority-based selection
- */
-
 import { existsSync, readFileSync } from "fs"
-import { homedir } from "os"
 import { join } from "path"
 import { log } from "./logger"
+import { getOpenCodeCacheDir } from "./data-path"
+import { readProviderModelsCache, hasProviderModelsCache } from "./connected-providers-cache"
 
 /**
  * Fuzzy match a target model name against available models
@@ -91,29 +87,69 @@ export function fuzzyMatchModel(
 	return result
 }
 
-let cachedModels: Set<string> | null = null
-
-function getOpenCodeCacheDir(): string {
-	const xdgCache = process.env.XDG_CACHE_HOME
-	if (xdgCache) return join(xdgCache, "opencode")
-	return join(homedir(), ".cache", "opencode")
-}
-
-export async function fetchAvailableModels(_client?: any): Promise<Set<string>> {
-	log("[fetchAvailableModels] CALLED")
-	
-	if (cachedModels !== null) {
-		log("[fetchAvailableModels] returning cached models", { count: cachedModels.size, models: Array.from(cachedModels).slice(0, 20) })
-		return cachedModels
+export async function getConnectedProviders(client: any): Promise<string[]> {
+	if (!client?.provider?.list) {
+		log("[getConnectedProviders] client.provider.list not available")
+		return []
 	}
 
+	try {
+		const result = await client.provider.list()
+		const connected = result.data?.connected ?? []
+		log("[getConnectedProviders] connected providers", { count: connected.length, providers: connected })
+		return connected
+	} catch (err) {
+		log("[getConnectedProviders] SDK error", { error: String(err) })
+		return []
+	}
+}
+
+export async function fetchAvailableModels(
+	_client?: any,
+	options?: { connectedProviders?: string[] | null }
+): Promise<Set<string>> {
+	const connectedProvidersUnknown = options?.connectedProviders === null || options?.connectedProviders === undefined
+
+	log("[fetchAvailableModels] CALLED", { 
+		connectedProvidersUnknown,
+		connectedProviders: options?.connectedProviders 
+	})
+
+	if (connectedProvidersUnknown) {
+		log("[fetchAvailableModels] connected providers unknown, returning empty set for fallback resolution")
+		return new Set<string>()
+	}
+
+	const connectedProviders = options!.connectedProviders!
+	const connectedSet = new Set(connectedProviders)
 	const modelSet = new Set<string>()
+
+	const providerModelsCache = readProviderModelsCache()
+	if (providerModelsCache) {
+		log("[fetchAvailableModels] using provider-models cache (whitelist-filtered)")
+		
+		for (const [providerId, modelIds] of Object.entries(providerModelsCache.models)) {
+			if (!connectedSet.has(providerId)) {
+				continue
+			}
+			for (const modelId of modelIds) {
+				modelSet.add(`${providerId}/${modelId}`)
+			}
+		}
+
+		log("[fetchAvailableModels] parsed from provider-models cache", {
+			count: modelSet.size,
+			connectedProviders: connectedProviders.slice(0, 5)
+		})
+
+		return modelSet
+	}
+
+	log("[fetchAvailableModels] provider-models cache not found, falling back to models.json")
 	const cacheFile = join(getOpenCodeCacheDir(), "models.json")
 
-	log("[fetchAvailableModels] reading cache file", { cacheFile })
-
 	if (!existsSync(cacheFile)) {
-		log("[fetchAvailableModels] cache file not found, returning empty set")
+		log("[fetchAvailableModels] models.json cache file not found, returning empty set")
 		return modelSet
 	}
 
@@ -122,9 +158,13 @@ export async function fetchAvailableModels(_client?: any): Promise<Set<string>>
 		const data = JSON.parse(content) as Record<string, { id?: string; models?: Record<string, { id?: string }> }>
 
 		const providerIds = Object.keys(data)
-		log("[fetchAvailableModels] providers found", { count: providerIds.length, providers: providerIds.slice(0, 10) })
+		log("[fetchAvailableModels] providers found in models.json", { count: providerIds.length, providers: providerIds.slice(0, 10) })
 
 		for (const providerId of providerIds) {
+			if (!connectedSet.has(providerId)) {
+				continue
+			}
+
 			const provider = data[providerId]
 			const models = provider?.models
 			if (!models || typeof models !== "object") continue
@@ -134,9 +174,11 @@ export async function fetchAvailableModels(_client?: any): Promise<Set<string>>
 			}
 		}
 
-		log("[fetchAvailableModels] parsed models", { count: modelSet.size, models: Array.from(modelSet).slice(0, 20) })
+		log("[fetchAvailableModels] parsed models from models.json (NO whitelist filtering)", {
+			count: modelSet.size,
+			connectedProviders: connectedProviders.slice(0, 5)
+		})
 
-		cachedModels = modelSet
 		return modelSet
 	} catch (err) {
 		log("[fetchAvailableModels] error", { error: String(err) })
@@ -144,11 +186,12 @@ export async function fetchAvailableModels(_client?: any): Promise<Set<string>>
 	}
 }
 
-export function __resetModelCache(): void {
-	cachedModels = null
-}
+export function __resetModelCache(): void {}
 
 export function isModelCacheAvailable(): boolean {
+	if (hasProviderModelsCache()) {
+		return true
+	}
 	const cacheFile = join(getOpenCodeCacheDir(), "models.json")
 	return existsSync(cacheFile)
 }

src/shared/model-requirements.test.ts

@@ -59,14 +59,23 @@ describe("AGENT_MODEL_REQUIREMENTS", () => {
     const explore = AGENT_MODEL_REQUIREMENTS["explore"]
 
     // #when - accessing explore requirement
-    // #then - fallbackChain exists with claude-haiku-4-5 as first entry
+    // #then - fallbackChain exists with claude-haiku-4-5 as first entry, gpt-5-mini as second, gpt-5-nano as third
     expect(explore).toBeDefined()
     expect(explore.fallbackChain).toBeArray()
-    expect(explore.fallbackChain.length).toBeGreaterThan(0)
+    expect(explore.fallbackChain).toHaveLength(3)
 
     const primary = explore.fallbackChain[0]
     expect(primary.providers).toContain("anthropic")
+    expect(primary.providers).toContain("opencode")
     expect(primary.model).toBe("claude-haiku-4-5")
+
+    const secondary = explore.fallbackChain[1]
+    expect(secondary.providers).toContain("github-copilot")
+    expect(secondary.model).toBe("gpt-5-mini")
+
+    const tertiary = explore.fallbackChain[2]
+    expect(tertiary.providers).toContain("opencode")
+    expect(tertiary.model).toBe("gpt-5-nano")
   })
 
   test("multimodal-looker has valid fallbackChain with gemini-3-flash as primary", () => {

src/shared/model-requirements.ts

@@ -35,6 +35,7 @@ export const AGENT_MODEL_REQUIREMENTS: Record<string, ModelRequirement> = {
   explore: {
     fallbackChain: [
       { providers: ["anthropic", "opencode"], model: "claude-haiku-4-5" },
+      { providers: ["github-copilot"], model: "gpt-5-mini" },
       { providers: ["opencode"], model: "gpt-5-nano" },
     ],
   },

src/shared/model-resolver.ts

@@ -1,6 +1,7 @@
 import { log } from "./logger"
 import { fuzzyMatchModel } from "./model-availability"
 import type { FallbackEntry } from "./model-requirements"
+import { readConnectedProvidersCache } from "./connected-providers-cache"
 
 export type ModelResolutionInput = {
 	userModel?: string
@@ -53,12 +54,28 @@ export function resolveModelWithFallback(
 
 	// Step 2: Provider fallback chain (with availability check)
 	if (fallbackChain && fallbackChain.length > 0) {
-		// If availableModels is empty (no cache), use first fallback entry directly without availability check
 		if (availableModels.size === 0) {
+			const connectedProviders = readConnectedProvidersCache()
+			const connectedSet = connectedProviders ? new Set(connectedProviders) : null
+
+			for (const entry of fallbackChain) {
+				for (const provider of entry.providers) {
+					if (connectedSet === null || connectedSet.has(provider)) {
+						const model = `${provider}/${entry.model}`
+						log("Model resolved via fallback chain (no model cache, using connected provider)", { 
+							provider, 
+							model: entry.model, 
+							variant: entry.variant,
+							hasConnectedCache: connectedSet !== null
+						})
+						return { model, source: "provider-fallback", variant: entry.variant }
+					}
+				}
+			}
 			const firstEntry = fallbackChain[0]
 			const firstProvider = firstEntry.providers[0]
 			const model = `${firstProvider}/${firstEntry.model}`
-			log("Model resolved via fallback chain (no cache, using first entry)", { provider: firstProvider, model: firstEntry.model, variant: firstEntry.variant })
+			log("Model resolved via fallback chain (no cache at all, using first entry)", { provider: firstProvider, model: firstEntry.model, variant: firstEntry.variant })
 			return { model, source: "provider-fallback", variant: firstEntry.variant }
 		}
 
@@ -72,7 +89,6 @@ export function resolveModelWithFallback(
 				}
 			}
 		}
-		// No match found in fallback chain - fall through to system default
 		log("No available model found in fallback chain, falling through to system default")
 	}
 

src/shared/session-utils.ts

@@ -0,0 +1,27 @@
+import * as path from "node:path"
+import * as os from "node:os"
+import { existsSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import { findNearestMessageWithFields, MESSAGE_STORAGE } from "../features/hook-message-injector"
+
+export function getMessageDir(sessionID: string): string | null {
+  if (!existsSync(MESSAGE_STORAGE)) return null
+
+  const directPath = join(MESSAGE_STORAGE, sessionID)
+  if (existsSync(directPath)) return directPath
+
+  for (const dir of readdirSync(MESSAGE_STORAGE)) {
+    const sessionPath = join(MESSAGE_STORAGE, dir, sessionID)
+    if (existsSync(sessionPath)) return sessionPath
+  }
+
+  return null
+}
+
+export function isCallerOrchestrator(sessionID?: string): boolean {
+  if (!sessionID) return false
+  const messageDir = getMessageDir(sessionID)
+  if (!messageDir) return false
+  const nearest = findNearestMessageWithFields(messageDir)
+  return nearest?.agent?.toLowerCase() === "atlas"
+}

src/shared/tmux/constants.ts

@@ -0,0 +1,12 @@
+// Polling interval for background session status checks
+export const POLL_INTERVAL_BACKGROUND_MS = 2000
+
+// Maximum idle time before session considered stale
+export const SESSION_TIMEOUT_MS = 10 * 60 * 1000  // 10 minutes
+
+// Grace period for missing session before cleanup
+export const SESSION_MISSING_GRACE_MS = 6000  // 6 seconds
+
+// Session readiness polling config
+export const SESSION_READY_POLL_INTERVAL_MS = 500
+export const SESSION_READY_TIMEOUT_MS = 10_000  // 10 seconds max wait

src/shared/tmux/index.ts

@@ -0,0 +1,3 @@
+export * from "./types"
+export * from "./constants"
+export * from "./tmux-utils"

src/shared/tmux/tmux-utils.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from "bun:test"
+import {
+  isInsideTmux,
+  isServerRunning,
+  resetServerCheck,
+  spawnTmuxPane,
+  closeTmuxPane,
+  applyLayout,
+} from "./tmux-utils"
+
+describe("isInsideTmux", () => {
+  test("returns true when TMUX env is set", () => {
+    // #given
+    const originalTmux = process.env.TMUX
+    process.env.TMUX = "/tmp/tmux-1000/default"
+
+    // #when
+    const result = isInsideTmux()
+
+    // #then
+    expect(result).toBe(true)
+
+    // cleanup
+    process.env.TMUX = originalTmux
+  })
+
+  test("returns false when TMUX env is not set", () => {
+    // #given
+    const originalTmux = process.env.TMUX
+    delete process.env.TMUX
+
+    // #when
+    const result = isInsideTmux()
+
+    // #then
+    expect(result).toBe(false)
+
+    // cleanup
+    process.env.TMUX = originalTmux
+  })
+
+  test("returns false when TMUX env is empty string", () => {
+    // #given
+    const originalTmux = process.env.TMUX
+    process.env.TMUX = ""
+
+    // #when
+    const result = isInsideTmux()
+
+    // #then
+    expect(result).toBe(false)
+
+    // cleanup
+    process.env.TMUX = originalTmux
+  })
+})
+
+describe("isServerRunning", () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    resetServerCheck()
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  test("returns true when server responds OK", async () => {
+    // #given
+    globalThis.fetch = mock(async () => ({ ok: true })) as any
+
+    // #when
+    const result = await isServerRunning("http://localhost:4096")
+
+    // #then
+    expect(result).toBe(true)
+  })
+
+  test("returns false when server not reachable", async () => {
+    // #given
+    globalThis.fetch = mock(async () => {
+      throw new Error("ECONNREFUSED")
+    }) as any
+
+    // #when
+    const result = await isServerRunning("http://localhost:4096")
+
+    // #then
+    expect(result).toBe(false)
+  })
+
+  test("returns false when fetch returns not ok", async () => {
+    // #given
+    globalThis.fetch = mock(async () => ({ ok: false })) as any
+
+    // #when
+    const result = await isServerRunning("http://localhost:4096")
+
+    // #then
+    expect(result).toBe(false)
+  })
+
+  test("caches successful result", async () => {
+    // #given
+    const fetchMock = mock(async () => ({ ok: true })) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    await isServerRunning("http://localhost:4096")
+
+    // #then - should only call fetch once due to caching
+    expect(fetchMock.mock.calls.length).toBe(1)
+  })
+
+  test("does not cache failed result", async () => {
+    // #given
+    const fetchMock = mock(async () => {
+      throw new Error("ECONNREFUSED")
+    }) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    await isServerRunning("http://localhost:4096")
+
+    // #then - should call fetch 4 times (2 attempts per call, 2 calls)
+    expect(fetchMock.mock.calls.length).toBe(4)
+  })
+
+  test("uses different cache for different URLs", async () => {
+    // #given
+    const fetchMock = mock(async () => ({ ok: true })) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    await isServerRunning("http://localhost:5000")
+
+    // #then - should call fetch twice for different URLs
+    expect(fetchMock.mock.calls.length).toBe(2)
+  })
+})
+
+describe("resetServerCheck", () => {
+  test("clears cache without throwing", () => {
+    // #given, #when, #then
+    expect(() => resetServerCheck()).not.toThrow()
+  })
+
+  test("allows re-checking after reset", async () => {
+    // #given
+    const originalFetch = globalThis.fetch
+    const fetchMock = mock(async () => ({ ok: true })) as any
+    globalThis.fetch = fetchMock
+
+    // #when
+    await isServerRunning("http://localhost:4096")
+    resetServerCheck()
+    await isServerRunning("http://localhost:4096")
+
+    // #then - should call fetch twice after reset
+    expect(fetchMock.mock.calls.length).toBe(2)
+
+    // cleanup
+    globalThis.fetch = originalFetch
+  })
+})
+
+describe("tmux pane functions", () => {
+  test("spawnTmuxPane is exported as function", async () => {
+    // #given, #when
+    const result = typeof spawnTmuxPane
+
+    // #then
+    expect(result).toBe("function")
+  })
+
+  test("closeTmuxPane is exported as function", async () => {
+    // #given, #when
+    const result = typeof closeTmuxPane
+
+    // #then
+    expect(result).toBe("function")
+  })
+
+  test("applyLayout is exported as function", async () => {
+    // #given, #when
+    const result = typeof applyLayout
+
+    // #then
+    expect(result).toBe("function")
+  })
+})

src/shared/tmux/tmux-utils.ts

@@ -0,0 +1,266 @@
+import { spawn } from "bun"
+import type { TmuxConfig, TmuxLayout } from "../../config/schema"
+import type { SpawnPaneResult } from "./types"
+import { getTmuxPath } from "../../tools/interactive-bash/utils"
+
+let serverAvailable: boolean | null = null
+let serverCheckUrl: string | null = null
+
+export function isInsideTmux(): boolean {
+  return !!process.env.TMUX
+}
+
+export async function isServerRunning(serverUrl: string): Promise<boolean> {
+  if (serverCheckUrl === serverUrl && serverAvailable === true) {
+    return true
+  }
+
+  const healthUrl = new URL("/health", serverUrl).toString()
+  const timeoutMs = 3000
+  const maxAttempts = 2
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), timeoutMs)
+
+    try {
+      const response = await fetch(healthUrl, { signal: controller.signal }).catch(
+        () => null
+      )
+      clearTimeout(timeout)
+
+      if (response?.ok) {
+        serverCheckUrl = serverUrl
+        serverAvailable = true
+        return true
+      }
+    } finally {
+      clearTimeout(timeout)
+    }
+
+    if (attempt < maxAttempts) {
+      await new Promise((r) => setTimeout(r, 250))
+    }
+  }
+
+  return false
+}
+
+export function resetServerCheck(): void {
+  serverAvailable = null
+  serverCheckUrl = null
+}
+
+export type SplitDirection = "-h" | "-v"
+
+export function getCurrentPaneId(): string | undefined {
+  return process.env.TMUX_PANE
+}
+
+export interface PaneDimensions {
+  paneWidth: number
+  windowWidth: number
+}
+
+export async function getPaneDimensions(paneId: string): Promise<PaneDimensions | null> {
+  const tmux = await getTmuxPath()
+  if (!tmux) return null
+
+  const proc = spawn([tmux, "display", "-p", "-t", paneId, "#{pane_width},#{window_width}"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const exitCode = await proc.exited
+  const stdout = await new Response(proc.stdout).text()
+
+  if (exitCode !== 0) return null
+
+  const [paneWidth, windowWidth] = stdout.trim().split(",").map(Number)
+  if (isNaN(paneWidth) || isNaN(windowWidth)) return null
+
+  return { paneWidth, windowWidth }
+}
+
+export async function spawnTmuxPane(
+  sessionId: string,
+  description: string,
+  config: TmuxConfig,
+  serverUrl: string,
+  targetPaneId?: string,
+  splitDirection: SplitDirection = "-h"
+): Promise<SpawnPaneResult> {
+  const { log } = await import("../logger")
+  
+  log("[spawnTmuxPane] called", { sessionId, description, serverUrl, configEnabled: config.enabled, targetPaneId, splitDirection })
+  
+  if (!config.enabled) {
+    log("[spawnTmuxPane] SKIP: config.enabled is false")
+    return { success: false }
+  }
+  if (!isInsideTmux()) {
+    log("[spawnTmuxPane] SKIP: not inside tmux", { TMUX: process.env.TMUX })
+    return { success: false }
+  }
+  
+  const serverRunning = await isServerRunning(serverUrl)
+  if (!serverRunning) {
+    log("[spawnTmuxPane] SKIP: server not running", { serverUrl })
+    return { success: false }
+  }
+
+  const tmux = await getTmuxPath()
+  if (!tmux) {
+    log("[spawnTmuxPane] SKIP: tmux not found")
+    return { success: false }
+  }
+  
+  log("[spawnTmuxPane] all checks passed, spawning...")
+
+  const opencodeCmd = `opencode attach ${serverUrl} --session ${sessionId}`
+
+  const args = [
+    "split-window",
+    splitDirection,
+    "-d",
+    "-P",
+    "-F",
+    "#{pane_id}",
+    ...(targetPaneId ? ["-t", targetPaneId] : []),
+    opencodeCmd,
+  ]
+
+  const proc = spawn([tmux, ...args], { stdout: "pipe", stderr: "pipe" })
+  const exitCode = await proc.exited
+  const stdout = await new Response(proc.stdout).text()
+  const paneId = stdout.trim()
+
+  if (exitCode !== 0 || !paneId) {
+    return { success: false }
+  }
+
+  const title = `omo-subagent-${description.slice(0, 20)}`
+  spawn([tmux, "select-pane", "-t", paneId, "-T", title], {
+    stdout: "ignore",
+    stderr: "ignore",
+  })
+
+  return { success: true, paneId }
+}
+
+export async function closeTmuxPane(paneId: string): Promise<boolean> {
+  const { log } = await import("../logger")
+  
+  if (!isInsideTmux()) {
+    log("[closeTmuxPane] SKIP: not inside tmux")
+    return false
+  }
+
+  const tmux = await getTmuxPath()
+  if (!tmux) {
+    log("[closeTmuxPane] SKIP: tmux not found")
+    return false
+  }
+
+  log("[closeTmuxPane] killing pane", { paneId })
+  
+  const proc = spawn([tmux, "kill-pane", "-t", paneId], {
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const exitCode = await proc.exited
+  const stderr = await new Response(proc.stderr).text()
+
+  if (exitCode !== 0) {
+    log("[closeTmuxPane] FAILED", { paneId, exitCode, stderr: stderr.trim() })
+  } else {
+    log("[closeTmuxPane] SUCCESS", { paneId })
+  }
+
+  return exitCode === 0
+}
+
+export async function replaceTmuxPane(
+  paneId: string,
+  sessionId: string,
+  description: string,
+  config: TmuxConfig,
+  serverUrl: string
+): Promise<SpawnPaneResult> {
+  const { log } = await import("../logger")
+  
+  log("[replaceTmuxPane] called", { paneId, sessionId, description })
+  
+  if (!config.enabled) {
+    return { success: false }
+  }
+  if (!isInsideTmux()) {
+    return { success: false }
+  }
+
+  const tmux = await getTmuxPath()
+  if (!tmux) {
+    return { success: false }
+  }
+
+  const opencodeCmd = `opencode attach ${serverUrl} --session ${sessionId}`
+
+  const proc = spawn([tmux, "respawn-pane", "-k", "-t", paneId, opencodeCmd], {
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const exitCode = await proc.exited
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text()
+    log("[replaceTmuxPane] FAILED", { paneId, exitCode, stderr: stderr.trim() })
+    return { success: false }
+  }
+
+  const title = `omo-subagent-${description.slice(0, 20)}`
+  spawn([tmux, "select-pane", "-t", paneId, "-T", title], {
+    stdout: "ignore",
+    stderr: "ignore",
+  })
+
+  log("[replaceTmuxPane] SUCCESS", { paneId, sessionId })
+  return { success: true, paneId }
+}
+
+export async function applyLayout(
+  tmux: string,
+  layout: TmuxLayout,
+  mainPaneSize: number
+): Promise<void> {
+  const layoutProc = spawn([tmux, "select-layout", layout], { stdout: "ignore", stderr: "ignore" })
+  await layoutProc.exited
+
+  if (layout.startsWith("main-")) {
+    const dimension =
+      layout === "main-horizontal" ? "main-pane-height" : "main-pane-width"
+    const sizeProc = spawn([tmux, "set-window-option", dimension, `${mainPaneSize}%`], {
+      stdout: "ignore",
+      stderr: "ignore",
+    })
+    await sizeProc.exited
+  }
+}
+
+export async function enforceMainPaneWidth(
+  mainPaneId: string,
+  windowWidth: number
+): Promise<void> {
+  const { log } = await import("../logger")
+  const tmux = await getTmuxPath()
+  if (!tmux) return
+
+  const DIVIDER_WIDTH = 1
+  const mainWidth = Math.floor((windowWidth - DIVIDER_WIDTH) / 2)
+  
+  const proc = spawn([tmux, "resize-pane", "-t", mainPaneId, "-x", String(mainWidth)], {
+    stdout: "ignore",
+    stderr: "ignore",
+  })
+  await proc.exited
+  
+  log("[enforceMainPaneWidth] main pane resized", { mainPaneId, mainWidth, windowWidth })
+}

src/shared/tmux/types.ts

@@ -0,0 +1,4 @@
+export interface SpawnPaneResult {
+  success: boolean
+  paneId?: string  // e.g., "%42"
+}

src/tools/AGENTS.md

@@ -10,14 +10,14 @@
 tools/
 ├── [tool-name]/
 │   ├── index.ts      # Barrel export
-│   ├── tools.ts      # ToolDefinition
+│   ├── tools.ts      # ToolDefinition or factory
 │   ├── types.ts      # Zod schemas
 │   └── constants.ts  # Fixed values
-├── lsp/              # 6 tools: definition, references, symbols, diagnostics, rename
+├── lsp/              # 6 tools: definition, references, symbols, diagnostics, rename (client.ts 596 lines)
 ├── ast-grep/         # 2 tools: search, replace (25 languages)
-├── delegate-task/    # Category-based routing (1039 lines)
+├── delegate-task/    # Category-based routing (1070 lines)
 ├── session-manager/  # 4 tools: list, read, search, info
-├── grep/             # Custom grep with timeout
+├── grep/             # Custom grep with timeout (60s, 10MB)
 ├── glob/             # 60s timeout, 100 file limit
 ├── interactive-bash/ # Tmux session management
 ├── look-at/          # Multimodal PDF/image
@@ -25,37 +25,51 @@ tools/
 ├── skill-mcp/        # Skill MCP operations
 ├── slashcommand/     # Slash command dispatch
 ├── call-omo-agent/   # Direct agent invocation
-└── background-task/  # background_output, background_cancel (513 lines)
+└── background-task/  # background_output, background_cancel
 ```
 
 ## TOOL CATEGORIES
 
-| Category | Tools | Purpose |
+| Category | Tools | Pattern |
 |----------|-------|---------|
-| LSP | lsp_goto_definition, lsp_find_references, lsp_symbols, lsp_diagnostics, lsp_prepare_rename, lsp_rename | Semantic code intelligence |
-| Search | ast_grep_search, ast_grep_replace, grep, glob | Pattern discovery |
-| Session | session_list, session_read, session_search, session_info | History navigation |
-| Agent | delegate_task, call_omo_agent, background_output, background_cancel | Task orchestration |
-| System | interactive_bash, look_at | CLI, multimodal |
-| Skill | skill, skill_mcp, slashcommand | Skill execution |
+| LSP | lsp_goto_definition, lsp_find_references, lsp_symbols, lsp_diagnostics, lsp_prepare_rename, lsp_rename | Direct |
+| Search | ast_grep_search, ast_grep_replace, grep, glob | Direct |
+| Session | session_list, session_read, session_search, session_info | Direct |
+| Agent | delegate_task, call_omo_agent | Factory |
+| Background | background_output, background_cancel | Factory |
+| System | interactive_bash, look_at | Mixed |
+| Skill | skill, skill_mcp, slashcommand | Factory |
 
 ## HOW TO ADD
 
 1. Create `src/tools/[name]/` with standard files
 2. Use `tool()` from `@opencode-ai/plugin/tool`
 3. Export from `src/tools/index.ts`
-4. Add to `builtinTools` object
+4. Static tools → `builtinTools`, Factory → separate export
 
-## LSP SPECIFICS
+## TOOL PATTERNS
 
-- **Client**: `client.ts` manages stdio, JSON-RPC (596 lines)
-- **Singleton**: `LSPServerManager` with ref counting
-- **Capabilities**: definition, references, symbols, diagnostics, rename
+**Direct ToolDefinition**:
+```typescript
+export const grep: ToolDefinition = tool({
+  description: "...",
+  args: { pattern: tool.schema.string() },
+  execute: async (args) => result,
+})
+```
 
-## AST-GREP SPECIFICS
+**Factory Function** (context-dependent):
+```typescript
+export function createDelegateTask(ctx, manager): ToolDefinition {
+  return tool({ execute: async (args) => { /* uses ctx */ } })
+}
+```
 
-- **Engine**: `@ast-grep/napi` for 25+ languages
-- **Patterns**: `$VAR` (single), `$$$` (multiple)
+## NAMING
+
+- **Tool names**: snake_case (`lsp_goto_definition`)
+- **Functions**: camelCase (`createDelegateTask`)
+- **Directories**: kebab-case (`delegate-task/`)
 
 ## ANTI-PATTERNS
 

src/tools/delegate-task/tools.test.ts

@@ -3,14 +3,15 @@ import { DEFAULT_CATEGORIES, CATEGORY_PROMPT_APPENDS, CATEGORY_DESCRIPTIONS } fr
 import { resolveCategoryConfig } from "./tools"
 import type { CategoryConfig } from "../../config/schema"
 import { __resetModelCache } from "../../shared/model-availability"
+import { clearSkillCache } from "../../features/opencode-skill-loader/skill-content"
 
 // Test constants - systemDefaultModel is required by resolveCategoryConfig
 const SYSTEM_DEFAULT_MODEL = "anthropic/claude-sonnet-4-5"
 
 describe("sisyphus-task", () => {
-  // Reset model cache before each test to prevent cross-test pollution
   beforeEach(() => {
     __resetModelCache()
+    clearSkillCache()
   })
 
   describe("DEFAULT_CATEGORIES", () => {
@@ -100,7 +101,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -315,7 +316,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
 
@@ -377,7 +378,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
 
@@ -435,7 +436,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
 
@@ -484,7 +485,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -524,7 +525,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -573,7 +574,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -639,7 +640,7 @@ describe("sisyphus-task", () => {
     const toolContext = {
       sessionID: "parent-session",
       messageID: "parent-message",
-      agent: "Sisyphus",
+      agent: "sisyphus",
       abort: new AbortController().signal,
     }
     
@@ -694,7 +695,7 @@ describe("sisyphus-task", () => {
     const toolContext = {
       sessionID: "parent-session",
       messageID: "parent-message",
-      agent: "Sisyphus",
+      agent: "sisyphus",
       abort: new AbortController().signal,
     }
     
@@ -749,7 +750,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -809,7 +810,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -862,7 +863,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -917,7 +918,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent",
         messageID: "msg",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal
       }
 
@@ -982,7 +983,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -1040,7 +1041,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -1101,7 +1102,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -1166,7 +1167,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -1231,7 +1232,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -1301,7 +1302,7 @@ describe("sisyphus-task", () => {
       const toolContext = {
         sessionID: "parent-session",
         messageID: "parent-message",
-        agent: "Sisyphus",
+        agent: "sisyphus",
         abort: new AbortController().signal,
       }
       
@@ -1324,6 +1325,112 @@ describe("sisyphus-task", () => {
     }, { timeout: 20000 })
   })
 
+  describe("browserProvider propagation", () => {
+    test("should resolve agent-browser skill when browserProvider is passed", async () => {
+      // #given - delegate_task configured with browserProvider: "agent-browser"
+      const { createDelegateTask } = require("./tools")
+      let promptBody: any
+
+      const mockManager = { launch: async () => ({}) }
+      const mockClient = {
+        app: { agents: async () => ({ data: [] }) },
+        config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
+        session: {
+          get: async () => ({ data: { directory: "/project" } }),
+          create: async () => ({ data: { id: "ses_browser_provider" } }),
+          prompt: async (input: any) => {
+            promptBody = input.body
+            return { data: {} }
+          },
+          messages: async () => ({
+            data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
+          }),
+          status: async () => ({ data: {} }),
+        },
+      }
+
+      // Pass browserProvider to createDelegateTask
+      const tool = createDelegateTask({
+        manager: mockManager,
+        client: mockClient,
+        browserProvider: "agent-browser",
+      })
+
+      const toolContext = {
+        sessionID: "parent-session",
+        messageID: "parent-message",
+        agent: "sisyphus",
+        abort: new AbortController().signal,
+      }
+
+      // #when - request agent-browser skill
+      await tool.execute(
+        {
+          description: "Test browserProvider propagation",
+          prompt: "Do something",
+          category: "ultrabrain",
+          run_in_background: false,
+          load_skills: ["agent-browser"],
+        },
+        toolContext
+      )
+
+      // #then - agent-browser skill should be resolved (not in notFound)
+      expect(promptBody).toBeDefined()
+      expect(promptBody.system).toBeDefined()
+      expect(promptBody.system).toContain("agent-browser")
+    }, { timeout: 20000 })
+
+    test("should NOT resolve agent-browser skill when browserProvider is not set", async () => {
+      // #given - delegate_task without browserProvider (defaults to playwright)
+      const { createDelegateTask } = require("./tools")
+
+      const mockManager = { launch: async () => ({}) }
+      const mockClient = {
+        app: { agents: async () => ({ data: [] }) },
+        config: { get: async () => ({ data: { model: SYSTEM_DEFAULT_MODEL } }) },
+        session: {
+          get: async () => ({ data: { directory: "/project" } }),
+          create: async () => ({ data: { id: "ses_no_browser_provider" } }),
+          prompt: async () => ({ data: {} }),
+          messages: async () => ({
+            data: [{ info: { role: "assistant" }, parts: [{ type: "text", text: "Done" }] }]
+          }),
+          status: async () => ({ data: {} }),
+        },
+      }
+
+      // No browserProvider passed
+      const tool = createDelegateTask({
+        manager: mockManager,
+        client: mockClient,
+      })
+
+      const toolContext = {
+        sessionID: "parent-session",
+        messageID: "parent-message",
+        agent: "sisyphus",
+        abort: new AbortController().signal,
+      }
+
+      // #when - request agent-browser skill without browserProvider
+      const result = await tool.execute(
+        {
+          description: "Test missing browserProvider",
+          prompt: "Do something",
+          category: "ultrabrain",
+          run_in_background: false,
+          load_skills: ["agent-browser"],
+        },
+        toolContext
+      )
+
+      // #then - should return skill not found error
+      expect(result).toContain("Skills not found")
+      expect(result).toContain("agent-browser")
+    })
+  })
+
   describe("buildSystemContent", () => {
     test("returns undefined when no skills and no category promptAppend", () => {
       // #given

src/tools/delegate-task/tools.ts

@@ -3,7 +3,7 @@ import { existsSync, readdirSync } from "node:fs"
 import { join } from "node:path"
 import type { BackgroundManager } from "../../features/background-agent"
 import type { DelegateTaskArgs } from "./types"
-import type { CategoryConfig, CategoriesConfig, GitMasterConfig } from "../../config/schema"
+import type { CategoryConfig, CategoriesConfig, GitMasterConfig, BrowserAutomationProvider } from "../../config/schema"
 import { DEFAULT_CATEGORIES, CATEGORY_PROMPT_APPENDS, CATEGORY_DESCRIPTIONS } from "./constants"
 import { findNearestMessageWithFields, findFirstMessageWithAgent, MESSAGE_STORAGE } from "../../features/hook-message-injector"
 import { resolveMultipleSkillsAsync } from "../../features/opencode-skill-loader/skill-content"
@@ -13,6 +13,7 @@ import type { ModelFallbackInfo } from "../../features/task-toast-manager/types"
 import { subagentSessions, getSessionAgent } from "../../features/claude-code-session-state"
 import { log, getAgentToolRestrictions, resolveModel, getOpenCodeConfigPaths, findByNameCaseInsensitive, equalsIgnoreCase } from "../../shared"
 import { fetchAvailableModels } from "../../shared/model-availability"
+import { readConnectedProvidersCache } from "../../shared/connected-providers-cache"
 import { resolveModelWithFallback } from "../../shared/model-resolver"
 import { CATEGORY_MODEL_REQUIREMENTS } from "../../shared/model-requirements"
 
@@ -150,6 +151,12 @@ export function resolveCategoryConfig(
   return { config, promptAppend, model }
 }
 
+export interface SyncSessionCreatedEvent {
+  sessionID: string
+  parentID: string
+  title: string
+}
+
 export interface DelegateTaskToolOptions {
   manager: BackgroundManager
   client: OpencodeClient
@@ -157,6 +164,8 @@ export interface DelegateTaskToolOptions {
   userCategories?: CategoriesConfig
   gitMasterConfig?: GitMasterConfig
   sisyphusJuniorModel?: string
+  browserProvider?: BrowserAutomationProvider
+  onSyncSessionCreated?: (event: SyncSessionCreatedEvent) => Promise<void>
 }
 
 export interface BuildSystemContentInput {
@@ -179,7 +188,7 @@ export function buildSystemContent(input: BuildSystemContentInput): string | und
 }
 
 export function createDelegateTask(options: DelegateTaskToolOptions): ToolDefinition {
-  const { manager, client, directory, userCategories, gitMasterConfig, sisyphusJuniorModel } = options
+  const { manager, client, directory, userCategories, gitMasterConfig, sisyphusJuniorModel, browserProvider, onSyncSessionCreated } = options
 
   const allCategories = { ...DEFAULT_CATEGORIES, ...userCategories }
   const categoryNames = Object.keys(allCategories)
@@ -239,7 +248,7 @@ Prompts MUST be in English.`
 
       let skillContent: string | undefined
       if (args.load_skills.length > 0) {
-        const { resolved, notFound } = await resolveMultipleSkillsAsync(args.load_skills, { gitMasterConfig })
+        const { resolved, notFound } = await resolveMultipleSkillsAsync(args.load_skills, { gitMasterConfig, browserProvider })
         if (notFound.length > 0) {
           const allSkills = await discoverSkills({ includeClaudeCodePaths: true })
           const available = allSkills.map(s => s.name).join(", ")
@@ -499,7 +508,10 @@ To continue this session: session_id="${args.session_id}"`
            )
          }
 
-         const availableModels = await fetchAvailableModels(client)
+          const connectedProviders = readConnectedProvidersCache()
+          const availableModels = await fetchAvailableModels(client, {
+            connectedProviders: connectedProviders ?? undefined
+          })
 
          const resolved = resolveCategoryConfig(args.category, {
            userCategories,
@@ -844,6 +856,19 @@ To continue this session: session_id="${task.sessionID}"`
         const sessionID = createResult.data.id
         syncSessionID = sessionID
         subagentSessions.add(sessionID)
+
+        if (onSyncSessionCreated) {
+          log("[delegate_task] Invoking onSyncSessionCreated callback", { sessionID, parentID: ctx.sessionID })
+          await onSyncSessionCreated({
+            sessionID,
+            parentID: ctx.sessionID,
+            title: args.description,
+          }).catch((err) => {
+            log("[delegate_task] onSyncSessionCreated callback failed", { error: String(err) })
+          })
+          await new Promise(r => setTimeout(r, 200))
+        }
+
         taskId = `sync_${sessionID.slice(0, 8)}`
         const startTime = new Date()
 

src/tools/skill/tools.test.ts

@@ -57,6 +57,45 @@ const mockContext = {
   abort: new AbortController().signal,
 }
 
+describe("skill tool - synchronous description", () => {
+  it("includes available_skills immediately when skills are pre-provided", () => {
+    // #given
+    const loadedSkills = [createMockSkill("test-skill")]
+
+    // #when
+    const tool = createSkillTool({ skills: loadedSkills })
+
+    // #then
+    expect(tool.description).toContain("<available_skills>")
+    expect(tool.description).toContain("test-skill")
+  })
+
+  it("includes all pre-provided skills in available_skills immediately", () => {
+    // #given
+    const loadedSkills = [
+      createMockSkill("playwright"),
+      createMockSkill("frontend-ui-ux"),
+      createMockSkill("git-master"),
+    ]
+
+    // #when
+    const tool = createSkillTool({ skills: loadedSkills })
+
+    // #then
+    expect(tool.description).toContain("playwright")
+    expect(tool.description).toContain("frontend-ui-ux")
+    expect(tool.description).toContain("git-master")
+  })
+
+  it("shows no-skills message immediately when empty skills are pre-provided", () => {
+    // #given / #when
+    const tool = createSkillTool({ skills: [] })
+
+    // #then
+    expect(tool.description).toContain("No skills are currently available")
+  })
+})
+
 describe("skill tool - agent restriction", () => {
   it("allows skill without agent restriction to any agent", async () => {
     // #given

src/tools/skill/tools.ts

@@ -147,7 +147,14 @@ export function createSkillTool(options: SkillLoadOptions = {}): ToolDefinition
     return cachedDescription
   }
 
-  getDescription()
+  if (options.skills) {
+    const skillInfos = options.skills.map(loadedSkillToInfo)
+    cachedDescription = skillInfos.length === 0
+      ? TOOL_DESCRIPTION_NO_SKILLS
+      : TOOL_DESCRIPTION_PREFIX + formatSkillsXml(skillInfos)
+  } else {
+    getDescription()
+  }
 
   return tool({
     get description() {

src/tools/slashcommand/tools.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "bun:test"
+import { createSlashcommandTool } from "./tools"
+import type { CommandInfo } from "./types"
+import type { LoadedSkill } from "../../features/opencode-skill-loader"
+
+function createMockCommand(name: string, description = ""): CommandInfo {
+  return {
+    name,
+    metadata: {
+      name,
+      description: description || `Test command ${name}`,
+    },
+    scope: "builtin",
+  }
+}
+
+function createMockSkill(name: string, description = ""): LoadedSkill {
+  return {
+    name,
+    path: `/test/skills/${name}/SKILL.md`,
+    resolvedPath: `/test/skills/${name}`,
+    definition: {
+      name,
+      description: description || `Test skill ${name}`,
+      template: "Test template",
+    },
+    scope: "opencode-project",
+  }
+}
+
+describe("slashcommand tool - synchronous description", () => {
+  it("includes available_skills immediately when commands and skills are pre-provided", () => {
+    // #given
+    const commands = [createMockCommand("commit", "Create a git commit")]
+    const skills = [createMockSkill("playwright", "Browser automation via Playwright MCP")]
+
+    // #when
+    const tool = createSlashcommandTool({ commands, skills })
+
+    // #then
+    expect(tool.description).toContain("<available_skills>")
+    expect(tool.description).toContain("commit")
+    expect(tool.description).toContain("playwright")
+  })
+
+  it("includes all pre-provided commands and skills in description immediately", () => {
+    // #given
+    const commands = [
+      createMockCommand("commit", "Git commit"),
+      createMockCommand("plan", "Create plan"),
+    ]
+    const skills = [
+      createMockSkill("playwright", "Browser automation"),
+      createMockSkill("frontend-ui-ux", "Frontend design"),
+      createMockSkill("git-master", "Git operations"),
+    ]
+
+    // #when
+    const tool = createSlashcommandTool({ commands, skills })
+
+    // #then
+    expect(tool.description).toContain("commit")
+    expect(tool.description).toContain("plan")
+    expect(tool.description).toContain("playwright")
+    expect(tool.description).toContain("frontend-ui-ux")
+    expect(tool.description).toContain("git-master")
+  })
+
+  it("shows prefix-only description when both commands and skills are empty", () => {
+    // #given / #when
+    const tool = createSlashcommandTool({ commands: [], skills: [] })
+
+    // #then - even with no items, description should be built synchronously (not just prefix)
+    expect(tool.description).toContain("Load a skill")
+  })
+})

src/tools/slashcommand/tools.ts

@@ -210,8 +210,12 @@ export function createSlashcommandTool(options: SlashcommandToolOptions = {}): T
     return cachedDescription
   }
 
-  // Pre-warm the cache immediately
-  buildDescription()
+  if (options.commands !== undefined && options.skills !== undefined) {
+    const allItems = [...options.commands, ...options.skills.map(skillToCommandInfo)]
+    cachedDescription = buildDescriptionFromItems(allItems)
+  } else {
+    buildDescription()
+  }
 
   return tool({
     get description() {