Merge pull request #1725 from XiaomiMiMo/feat/sticky-agent-mode

feat: sticky agent mode — mode locking + permission-based skill scoping

Author: yanyihan-xiaomi

docs/compose/reports/sticky-agent-mode.md

@@ -0,0 +1,119 @@
+---
+feature: sticky-agent-mode
+status: proposed
+specs: []
+plans: []
+branch: feat/sticky-agent-mode
+---
+
+# Sticky Agent Mode — Final Report
+
+## What Was Built
+
+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`.
+
+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
+
+### Sticky Mode (TUI)
+
+**File:** `packages/opencode/src/cli/cmd/tui/context/local.tsx`
+
+- `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 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 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`
+
+```ts
+createEffect(() => {
+  local.agent.setSessionHasMessages(!!lastUserMessage())
+})
+```
+
+Single reactive effect — no manual lock/unlock. Naturally handles `/new` (empty session = unlocked), `/session` (has messages = locked), and message submission.
+
+### Permission-Based Skill Scoping
+
+**File:** `packages/opencode/src/agent/agent.ts`
+
+- `defaults` includes `skill: { "*": "allow", "compose:*": "deny" }`
+- Compose agent overrides with `skill: { "compose:*": "allow" }`
+
+**File:** `packages/opencode/src/skill/index.ts`
+
+- `Skill.available()` no longer filters `!sk.hidden` — relies entirely on permission
+
+### 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)
+
+**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
+
+**File:** `packages/opencode/src/session/prompt.ts`
+
+- `composeSkillsBlock()` import and call removed
+- Only `{{compose_docs_dir}}` substitution remains in PROMPT_COMPOSE
+
+**File:** `packages/opencode/src/session/prompt/compose.txt`
+
+- "Compose Skills Visibility" section simplified: skills are in the normal listing
+- Subagent guidance: "distill instructions into prompts"
+
+### Design Decisions
+
+**`set()` vs `userSwitch()` separation:** The guard only applies to user-initiated actions (Tab, dialog, voice). System paths (session restore, plan_enter/plan_exit, CLI --agent) use `set()` directly and are never blocked. This avoids a fragile whitelist of "force" call sites.
+
+**Reactive `sessionHasMessages` from `lastUserMessage()`:** No manual lock/unlock state. The signal is derived from actual session content, so `/new`, `/session`, and submits all work correctly without explicit handling.
+
+**`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).
+
+**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.
+
+**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
+
+- **New session:** Mode selector works normally (Tab cycles all agents)
+- **After first message:** Mode is locked to the current group
+  - Build/Plan: Tab cycles between them. Toast when trying to reach Compose
+  - Compose: Tab shows toast — cannot switch mid-session
+- **`/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
+- `bun test test/session/prompt-skill-mention.test.ts` — 8/8 pass
+- `bun test test/permission` — 141/141 pass
+- `bun test test/agent/agent.test.ts` — 48/48 pass
+
+## Design Notes
+
+Key constraints that shaped the final approach:
+
+- Guard must separate system paths (`set()`) from user actions (`userSwitch()`) — putting the guard directly in `set()` requires a fragile whitelist for session restore, plan tools, and CLI
+- Sticky state must be **derived** (`!!lastUserMessage()`), not manually managed — a boolean `lock()` breaks on `/new` and `/session` transitions
+- `move()` must skip blocked agents rather than stopping — otherwise Tab appears broken when the next agent in order is blocked
+- Plan tools use the existing `Permission.disabled()` pipeline in `llm.ts:resolveTools()` — no registry changes needed

packages/opencode/src/agent/agent.ts

@@ -105,6 +105,12 @@ export const layer = Layer.effect(
         const defaults = Permission.fromConfig({
           "*": "allow",
           doom_loop: "ask",
+          skill: {
+            "*": "allow",
+            "compose:*": "deny",
+          },
+          plan_enter: "deny",
+          plan_exit: "deny",
           external_directory: {
             "*": "ask",
             ...Object.fromEntries(whitelistedDirs.map((dir) => [dir, "allow"])),
@@ -131,6 +137,8 @@ export const layer = Layer.effect(
               defaults,
               Permission.fromConfig({
                 question: "allow",
+                plan_enter: "allow",
+                plan_exit: "allow",
               }),
               user,
             ),
@@ -169,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",
                 },
@@ -206,6 +216,7 @@ export const layer = Layer.effect(
               defaults,
               Permission.fromConfig({
                 question: "allow",
+                skill: { "compose:*": "allow" },
               }),
               user,
             ),

packages/opencode/src/cli/cmd/tui/component/dialog-agent.tsx

@@ -23,7 +23,7 @@ export function DialogAgent() {
       current={local.agent.current()?.name}
       options={options()}
       onSelect={(option) => {
-        local.agent.set(option.value)
+        local.agent.userSwitch(option.value)
         dialog.clear()
       }}
     />

packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx

@@ -191,7 +191,7 @@ export function Prompt(props: PromptProps) {
 
   function voiceSwitchAgent(name: string) {
     const match = local.agent.list().find((x) => x.name.toLowerCase() === name.toLowerCase())
-    if (match) local.agent.set(match.name)
+    if (match) local.agent.userSwitch(match.name)
     else toast.show({ message: t("tui.voice.error.unknown_agent", { name: name }), variant: "error", duration: 3000 })
   }
 
@@ -507,6 +507,11 @@ export function Prompt(props: PromptProps) {
     ),
   )
 
+  // Derive sticky mode from whether session has messages
+  createEffect(() => {
+    local.agent.setSessionHasMessages(!!lastUserMessage())
+  })
+
   // Initialize agent/model/variant from last user message when session changes
   let syncedSessionID: string | undefined
   createEffect(() => {
@@ -515,7 +520,6 @@ export function Prompt(props: PromptProps) {
 
     if (sessionID !== syncedSessionID) {
       if (!sessionID || !msg) return
-
       syncedSessionID = sessionID
 
       // Only set agent if it's a primary agent (not a subagent)

packages/opencode/src/cli/cmd/tui/context/local.tsx

@@ -49,7 +49,34 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
       const visibleAgents = createMemo(() => sync.data.agent.filter((x) => !x.hidden))
       const [agentStore, setAgentStore] = createStore({
         current: undefined as string | undefined,
+        sessionHasMessages: false,
       })
+      const FREE_SWITCH_GROUP = ["build", "plan"]
+      const canSwitchTo = (target: string) => {
+        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,
@@ -76,16 +103,32 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
             })
           setAgentStore("current", name)
         },
+        userSwitch(name: string) {
+          if (!canSwitchTo(name)) {
+            switchBlockedToast()
+            return
+          }
+          this.set(name)
+        },
         move(direction: 1 | -1) {
-          batch(() => {
-            const current = this.current()
-            if (!current) return
-            let next = agents().findIndex((x) => x.name === current.name) + direction
-            if (next < 0) next = agents().length - 1
-            if (next >= agents().length) next = 0
-            const value = agents()[next]
-            setAgentStore("current", value.name)
-          })
+          const current = this.current()
+          if (!current) return
+          const list = agents()
+          const currentIdx = list.findIndex((x) => x.name === current.name)
+          for (let i = 1; i < list.length; i++) {
+            let idx = currentIdx + direction * i
+            idx = ((idx % list.length) + list.length) % list.length
+            const candidate = list[idx]
+            if (!candidate) continue
+            if (canSwitchTo(candidate.name)) {
+              setAgentStore("current", candidate.name)
+              return
+            }
+          }
+          switchBlockedToast()
+        },
+        setSessionHasMessages(value: boolean) {
+          setAgentStore("sessionHasMessages", value)
         },
         color(name: string) {
           const index = visibleAgents().findIndex((x) => x.name === name)

packages/opencode/src/cli/cmd/tui/i18n/en.ts

@@ -275,6 +275,8 @@ export const dict: Record<string, string> = {
   "tui.command.variant.cycle.title": "Variant cycle",
   "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",

packages/opencode/src/cli/cmd/tui/i18n/es.ts

@@ -351,6 +351,8 @@ export const dict = {
   "tui.command.variant.cycle.title": "Ciclo de variantes",
   "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",

packages/opencode/src/cli/cmd/tui/i18n/fr.ts

@@ -339,6 +339,8 @@ export const dict = {
   "tui.command.variant.cycle.title": "Cycle de variantes",
   "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",

packages/opencode/src/cli/cmd/tui/i18n/ja.ts

@@ -284,6 +284,8 @@ export const dict = {
   "tui.command.variant.cycle.title": "バリアントを循環",
   "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": "ログアウト",

packages/opencode/src/cli/cmd/tui/i18n/ru.ts

@@ -354,6 +354,8 @@ export const dict = {
   "tui.command.variant.cycle.title": "Цикл вариантов",
   "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": "Выйти",