exp: plan tools permission-gated + differentiated switch-blocked toast

yanyihan-xiaomi · yanyihan-xiaomi · commit a7ddbb0bf658 · 2026-07-14T20:40:42.000+08:00
- plan_enter/plan_exit: deny in compose agent permission (agent.ts)
- registry.ts reads permission to filter, no hardcoded agent names
- switchBlockedToast: shows subset message (build/plan) or locked message (compose)
- i18n: add tui.agent.locked.subset in all locales
diff --git a/docs/compose/reports/sticky-agent-mode.md b/docs/compose/reports/sticky-agent-mode.md
@@ -4,7 +4,7 @@ status: experimental
 specs: []
 plans: []
 branch: exp/sticky-agent-mode
-commits: e418785e..fe72d4e2
+commits: e418785e..6760950e
 ---
 
 # Sticky Agent Mode — Final Report
@@ -13,7 +13,11 @@ commits: e418785e..fe72d4e2
 
 An experimental mode-locking system where agent selection is permanent for the duration of a session. Once a session has content (any user message), the user cannot switch to a different mode group. Build and Plan form a single free-switch group; all other agents (Compose, etc.) are isolated — once you're in Compose, you stay in Compose until `/new`.
 
-Alongside this, compose skills are migrated from `hidden: true` to permission-based scoping. The compose agent's permission allows `compose:*` skills; all other agents deny them. This eliminates the hardcoded `composeSkillsBlock()` injection — compose skills appear in the normal system prompt skill listing when the compose agent is active.
+Three supporting changes enable a clean per-mode experience:
+
+1. **Permission-based skill scoping** — compose skills use `deny`/`allow` permissions instead of `hidden: true`
+2. **Plan tools scoped to build/plan** — `plan_enter`/`plan_exit` denied by default, allowed only for build/plan (keeping compose's tool list clean)
+3. **Removed `composeSkillsBlock()` injection** — compose skills appear naturally in the system prompt via `available(agent)`
 
 ## Architecture
 
@@ -23,10 +27,11 @@ Alongside this, compose skills are migrated from `hidden: true` to permission-ba
 
 - `agentStore.sessionHasMessages` — reactive boolean derived from `!!lastUserMessage()`
 - `FREE_SWITCH_GROUP = ["build", "plan"]` — agents that can freely switch between each other
-- `canSwitchTo(target)` — returns true if: no messages yet, OR both current and target are in the same group
+- `canSwitchTo(target)` — returns true if: no messages yet, OR target is self, OR both current and target are in the same group
 - `set(name)` — unguarded, for system/programmatic use (session restore, plan tools, CLI)
-- `userSwitch(name)` — guarded, for user actions (dialog, voice). Shows toast when blocked
+- `userSwitch(name)` — guarded, for user actions (dialog, voice). Shows contextual toast when blocked
 - `move(direction)` — cycles through agents, skipping blocked ones. Toast only when no valid target exists
+- `switchBlockedToast()` — shows subset message (build/plan group) or locked message (compose isolated)
 
 **File:** `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx`
 
@@ -49,9 +54,16 @@ Single reactive effect — no manual lock/unlock. Naturally handles `/new` (empt
 
 - `Skill.available()` no longer filters `!sk.hidden` — relies entirely on permission
 
-**File:** `packages/opencode/src/skill/compose/.bundle/*/SKILL.md`
+### Plan Tools Scoping
+
+**File:** `packages/opencode/src/agent/agent.ts`
+
+- `defaults` includes `plan_enter: "deny"`, `plan_exit: "deny"`
+- Build agent: `plan_enter: "allow"`, `plan_exit: "allow"`
+- Plan agent: `plan_enter: "allow"`, `plan_exit: "allow"`
+- Both agents see BOTH tools (symmetric, no list mutation on build↔plan switch)
 
-- All 14 compose skills: `hidden: true` removed from frontmatter
+**No registry.ts changes needed** — `llm.ts:resolveTools()` already uses `Permission.disabled()` to strip denied tools before sending them to the model. The permission rules in agent.ts are sufficient.
 
 ### Compose Prompt Cleanup
 
@@ -63,7 +75,7 @@ Single reactive effect — no manual lock/unlock. Naturally handles `/new` (empt
 **File:** `packages/opencode/src/session/prompt/compose.txt`
 
 - "Compose Skills Visibility" section simplified: skills are in the normal listing
-- Subagent guidance: "distill instructions" instead of "pass skill lists"
+- Subagent guidance: "distill instructions into prompts"
 
 ### Design Decisions
 
@@ -73,34 +85,42 @@ Single reactive effect — no manual lock/unlock. Naturally handles `/new` (empt
 
 **`move()` skips blocked agents:** Tab cycles within the allowed group instead of stopping at the first blocked agent. Toast only shows when the entire group has been exhausted (e.g., compose mode with no other compose-group agents).
 
-**Permission in defaults (deny) + compose override (allow):** Future agents automatically inherit the `compose:*` deny. Only the compose agent explicitly opts in. This is more future-proof than denying on each non-compose agent individually.
+**Self-switch always allowed:** `canSwitchTo` returns true when `current === target`. Prevents false toast on no-op switches (e.g., compose user selecting compose in `/agents` dialog).
+
+**Contextual toast messages:** Two variants — "只能在 build, plan 之间切换" when in the group but target is outside, "进入 compose 模式后无法切换" when isolated with no valid targets.
+
+**Plan tools: symmetric allow in build/plan, deny in defaults:** Future agents automatically inherit the deny. Build and plan both see both tools (no list mutation within the group). This is NOT a revert of #1207 — #1207 made plan tools visible to ALL agents; this scopes them to the build/plan group only, possible because sticky mode prevents cross-group switching.
 
-**Subagent distillation model:** Compose skills instruct the orchestrator to distill guidance into concrete subagent prompts, rather than passing `<available_skills>` blocks. Subagents are leaf workers — they don't need orchestration skills.
+**Permission in defaults (deny) + specific agent override (allow):** Used for both skills (`compose:*`) and tools (`plan_enter`/`plan_exit`). Future agents automatically inherit all deny rules. Only the relevant agent explicitly opts in.
 
 ## Usage
 
 This is an experimental branch (`exp/sticky-agent-mode`). Behavior:
 
 - **New session:** Mode selector works normally (Tab cycles all agents)
 - **After first message:** Mode is locked to the current group
-  - Build/Plan: can Tab between them freely
+  - Build/Plan: Tab cycles between them. Toast: "只能在 build, plan 之间切换" if trying `/agents` to compose
   - Compose: Tab shows toast — "进入 compose 模式后无法在运行中切换模式"
 - **`/new`:** Creates empty session → mode unlocked again
 - **`/session`:** Enters existing session → mode locked to that session's agent
+- **Self-switch:** Always allowed (no-op, no toast)
 
 ## Verification
 
 - `bun typecheck` — clean (0 errors)
 - `bun test test/session/prompt-skill-mention.test.ts` — 8/8 pass
 - `bun test test/permission` — 141/141 pass
-- Manual TUI testing: Tab cycling, `/session`, `/new`, toast messages
+- Manual TUI testing: Tab cycling, `/session`, `/new`, `/agents` dialog, toast messages
 
 ## Journey Log
 
 > Brief notes on what informed the final design.
 
 - [dead end] `lock()` boolean — persisted after `/new`, broke mode switching on new sessions
 - [dead end] Guard in `set()` with `{ force: true }` bypass — fragile, missed system call sites
+- [dead end] Hardcoded plan tool filter in registry.ts — unnecessary, `llm.ts:resolveTools` already uses `Permission.disabled()` generically
 - [pivot] Switched to reactive `!!lastUserMessage()` derivation — handles all session transitions naturally
 - [pivot] Separated `set()` (system) from `userSwitch()` (user) — eliminated the whitelist problem entirely
-- [lesson] `move()` must skip blocked agents, not stop at the first one — otherwise Tab breaks within the allowed group
+- [pivot] Plan tools: defaults deny + build/plan allow (symmetric) — differs from pre-#1207 (asymmetric) but stays stable within the group
+- [lesson] `move()` must skip blocked agents, not stop at the first one
+- [lesson] Self-switch (`current === target`) must always pass — otherwise no-op triggers false toast
diff --git a/packages/opencode/src/agent/agent.ts b/packages/opencode/src/agent/agent.ts
@@ -109,6 +109,8 @@ export const layer = Layer.effect(
             "*": "allow",
             "compose:*": "deny",
           },
+          plan_enter: "deny",
+          plan_exit: "deny",
           external_directory: {
             "*": "ask",
             ...Object.fromEntries(whitelistedDirs.map((dir) => [dir, "allow"])),
@@ -135,6 +137,8 @@ export const layer = Layer.effect(
               defaults,
               Permission.fromConfig({
                 question: "allow",
+                plan_enter: "allow",
+                plan_exit: "allow",
               }),
               user,
             ),
@@ -173,6 +177,8 @@ export const layer = Layer.effect(
               defaults,
               Permission.fromConfig({
                 question: "allow",
+                plan_enter: "allow",
+                plan_exit: "allow",
                 external_directory: {
                   [path.join(Global.Path.data, "plans", "*")]: "allow",
                 },
diff --git a/packages/opencode/src/cli/cmd/tui/context/local.tsx b/packages/opencode/src/cli/cmd/tui/context/local.tsx
@@ -56,10 +56,27 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
         if (!agentStore.sessionHasMessages) return true
         const current = agentStore.current
         if (!current) return true
+        if (current === target) return true
         const currentInGroup = FREE_SWITCH_GROUP.includes(current)
         const targetInGroup = FREE_SWITCH_GROUP.includes(target)
         return currentInGroup && targetInGroup
       }
+      const switchBlockedToast = () => {
+        const current = agentStore.current ?? ""
+        if (FREE_SWITCH_GROUP.includes(current)) {
+          toast.show({
+            variant: "warning",
+            message: t("tui.agent.locked.subset", { agents: FREE_SWITCH_GROUP.join(", ") }),
+            duration: 3000,
+          })
+        } else {
+          toast.show({
+            variant: "warning",
+            message: t("tui.agent.locked", { mode: current }),
+            duration: 3000,
+          })
+        }
+      }
       const { theme } = useTheme()
       const colors = createMemo(() => [
         theme.secondary,
@@ -88,11 +105,7 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
         },
         userSwitch(name: string) {
           if (!canSwitchTo(name)) {
-            toast.show({
-              variant: "warning",
-              message: t("tui.agent.locked", { mode: agentStore.current ?? "" }),
-              duration: 3000,
-            })
+            switchBlockedToast()
             return
           }
           this.set(name)
@@ -113,11 +126,7 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
                 return
               }
             }
-            toast.show({
-              variant: "warning",
-              message: t("tui.agent.locked", { mode: agentStore.current ?? "" }),
-              duration: 3000,
-            })
+            switchBlockedToast()
           })
         },
         setSessionHasMessages(value: boolean) {
diff --git a/packages/opencode/src/cli/cmd/tui/i18n/en.ts b/packages/opencode/src/cli/cmd/tui/i18n/en.ts
@@ -276,6 +276,7 @@ export const dict: Record<string, string> = {
   "tui.command.variant.list.title": "Switch model variant",
   "tui.command.agent.cycle.reverse.title": "Agent cycle reverse",
   "tui.agent.locked": "Cannot switch mode mid-session after entering {{mode}} mode",
+  "tui.agent.locked.subset": "In this session, you can only switch between {{agents}}",
   "tui.command.provider.login.title": "Login",
   "tui.command.provider.connect.title": "Connect provider",
   "tui.command.provider.logout.title": "Logout",
diff --git a/packages/opencode/src/cli/cmd/tui/i18n/es.ts b/packages/opencode/src/cli/cmd/tui/i18n/es.ts
@@ -352,6 +352,7 @@ export const dict = {
   "tui.command.variant.list.title": "Cambiar variante de modelo",
   "tui.command.agent.cycle.reverse.title": "Ciclo de agentes (inverso)",
   "tui.agent.locked": "No se puede cambiar de modo después de entrar en modo {{mode}}",
+  "tui.agent.locked.subset": "En esta sesión, solo puede cambiar entre {{agents}}",
   "tui.command.provider.login.title": "Iniciar sesión",
   "tui.command.provider.connect.title": "Conectar proveedor",
   "tui.command.provider.logout.title": "Cerrar sesión",
diff --git a/packages/opencode/src/cli/cmd/tui/i18n/fr.ts b/packages/opencode/src/cli/cmd/tui/i18n/fr.ts
@@ -340,6 +340,7 @@ export const dict = {
   "tui.command.variant.list.title": "Changer de variante de modèle",
   "tui.command.agent.cycle.reverse.title": "Cycle d'agents (inverse)",
   "tui.agent.locked": "Impossible de changer de mode après être entré en mode {{mode}}",
+  "tui.agent.locked.subset": "Dans cette session, vous pouvez uniquement basculer entre {{agents}}",
   "tui.command.provider.login.title": "Connexion",
   "tui.command.provider.connect.title": "Connecter un fournisseur",
   "tui.command.provider.logout.title": "Déconnexion",
diff --git a/packages/opencode/src/cli/cmd/tui/i18n/ja.ts b/packages/opencode/src/cli/cmd/tui/i18n/ja.ts
@@ -285,6 +285,7 @@ export const dict = {
   "tui.command.variant.list.title": "モデルバリアントを切り替え",
   "tui.command.agent.cycle.reverse.title": "エージェントを逆循環",
   "tui.agent.locked": "{{mode}} モードに入った後はモードを切り替えできません",
+  "tui.agent.locked.subset": "このセッションでは {{agents}} の間でのみ切り替え可能です",
   "tui.command.provider.login.title": "ログイン",
   "tui.command.provider.connect.title": "プロバイダに接続",
   "tui.command.provider.logout.title": "ログアウト",
diff --git a/packages/opencode/src/cli/cmd/tui/i18n/ru.ts b/packages/opencode/src/cli/cmd/tui/i18n/ru.ts
@@ -355,6 +355,7 @@ export const dict = {
   "tui.command.variant.list.title": "Сменить вариант модели",
   "tui.command.agent.cycle.reverse.title": "Цикл агентов (в обратном порядке)",
   "tui.agent.locked": "Невозможно сменить режим после входа в {{mode}}",
+  "tui.agent.locked.subset": "В этой сессии можно переключаться только между {{agents}}",
   "tui.command.provider.login.title": "Войти",
   "tui.command.provider.connect.title": "Подключить провайдера",
   "tui.command.provider.logout.title": "Выйти",
diff --git a/packages/opencode/src/cli/cmd/tui/i18n/zh.ts b/packages/opencode/src/cli/cmd/tui/i18n/zh.ts
@@ -261,6 +261,7 @@ export const dict = {
   "tui.command.variant.list.title": "切换模型变体",
   "tui.command.agent.cycle.reverse.title": "反向循环切换智能体",
   "tui.agent.locked": "进入 {{mode}} 模式后无法在运行中切换模式",
+  "tui.agent.locked.subset": "已开始的会话中，只能在 {{agents}} 之间切换",
   "tui.command.provider.login.title": "登录",
   "tui.command.provider.connect.title": "连接服务商",
   "tui.command.provider.logout.title": "登出",
diff --git a/packages/opencode/src/cli/cmd/tui/i18n/zht.ts b/packages/opencode/src/cli/cmd/tui/i18n/zht.ts
@@ -261,6 +261,7 @@ export const dict = {
   "tui.command.variant.list.title": "切換模型變體",
   "tui.command.agent.cycle.reverse.title": "反向循環切換智慧代理",
   "tui.agent.locked": "進入 {{mode}} 模式後無法在運行中切換模式",
+  "tui.agent.locked.subset": "已開始的會話中，只能在 {{agents}} 之間切換",
   "tui.command.provider.login.title": "登入",
   "tui.command.provider.connect.title": "連線供應商",
   "tui.command.provider.logout.title": "登出",
diff --git a/packages/opencode/test/agent/agent.test.ts b/packages/opencode/test/agent/agent.test.ts
@@ -132,23 +132,37 @@ test("build agent unaffected — no hardPermission", async () => {
   })
 })
 
-test("plan_enter and plan_exit are allowed (not hidden) for all primary agents", async () => {
+test("plan_enter and plan_exit are allowed for build and plan agents", async () => {
   await using tmp = await tmpdir()
   await Instance.provide({
     directory: tmp.path,
     fn: async () => {
       const agents = await load(tmp.path, (svc) => svc.list())
-      const primaryAgents = agents.filter((a) => a.mode === "primary")
-      expect(primaryAgents.length).toBeGreaterThanOrEqual(3)
-      for (const agent of primaryAgents) {
-        const disabled = Permission.disabled(["plan_enter", "plan_exit"], agent.permission)
+      for (const name of ["build", "plan"]) {
+        const agent = agents.find((a) => a.name === name)
+        expect(agent).toBeDefined()
+        const disabled = Permission.disabled(["plan_enter", "plan_exit"], agent!.permission)
         expect(disabled.has("plan_enter")).toBe(false)
         expect(disabled.has("plan_exit")).toBe(false)
       }
     },
   })
 })
 
+test("plan_enter and plan_exit are denied for compose agent", async () => {
+  await using tmp = await tmpdir()
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      const compose = await load(tmp.path, (svc) => svc.get("compose"))
+      expect(compose).toBeDefined()
+      const disabled = Permission.disabled(["plan_enter", "plan_exit"], compose!.permission)
+      expect(disabled.has("plan_enter")).toBe(true)
+      expect(disabled.has("plan_exit")).toBe(true)
+    },
+  })
+})
+
 test("explore agent denies edit and write", async () => {
   await using tmp = await tmpdir()
   await Instance.provide({
