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

[yanyihan-xiaomi]

Overview

Experimental branch exploring "mode is immutable within a session" interaction model. Will not be merged to main — for trying out and discussion.

Key Changes

1. Sticky Mode

After the first message in a session, the mode is locked:

• Build / Plan form a group — can freely switch between them (Tab cycles within group)
• Compose and other modes are isolated — cannot switch once entered
• /new creates a fresh session and restores free selection

Contextual toasts:

• Build/Plan user tries to switch to compose → "In this session, you can only switch between build, plan"
• Compose user presses Tab → "Cannot switch mode mid-session after entering compose mode"

2. Permission Replaces Hidden

• Removed hidden: true from all compose skills
• Configured via agent permission: defaults deny compose:*, compose agent explicitly allows
• Skill.available() no longer filters by hidden — relies entirely on permission system
• Compose skills naturally appear in compose agent's system prompt skill listing

3. Plan Tools Scoped to Build/Plan

• Defaults deny plan_enter/plan_exit, build and plan explicitly allow both (symmetric)
• No registry.ts changes needed — llm.ts:resolveTools() already uses Permission.disabled() to strip denied tools
• Compose and future agents get a clean tool list automatically
• Differs from pre-feat(tool): make plan_enter/plan_exit always visible across modes #1207 (asymmetric per-agent, caused cache issues) — here both build/plan see both tools

4. Removed composeSkillsBlock() Injection

• No more hardcoded <available_skills> XML block injection
• compose.txt cleaned: removed {{compose_skills}} placeholder
• Subagent guidance updated to "distill instructions" model

Design Tradeoffs

Decision	Rationale
set() vs userSwitch() separation	Only guard user actions, don't block system behavior (session restore, plan tools)
Reactive !!lastUserMessage()	No manual lock/unlock — /new and /session work correctly by nature
move() skips blocked agents	Tab cycles within group, doesn't stop at first blocked entry
Self-switch always allowed	current === target → no-op, no false toast
Permission defaults deny + specific allow	Future agents auto-inherit deny, no per-agent config needed
Plan tools: symmetric in build/plan	No tool list mutation on build↔plan switch, stable prefix cache

⚠️ Breaking Changes

1. Custom modes affected: User-defined agents not in FREE_SWITCH_GROUP are treated as isolated (sticky). Would need group configuration support.
2. hidden: true no longer effective: Skills relying on hidden must migrate to permission config
3. Subagents can no longer receive <available_skills> blocks: Must distill instructions directly into prompts
4. Plan tools hidden from compose: Compose agent no longer sees plan_enter/plan_exit (denied via permission)

Try It

git checkout exp/sticky-agent-mode
bun install
bun dev

Test:

• Build mode → send message → Tab only switches to Plan
• Build mode → /agents → try compose → toast: "only switch between build, plan"
• Compose mode → send message → Tab shows toast
• /new → free switching restored
• /session into history → auto-locked

Stability Note

Theoretically more stable due to constrained behavior — the model's system prompt (skills + tools) is fixed for the entire session (no prefix cache invalidation from mode switches). However, this is a breaking change that affects custom mode workflows and is not planned to be merged.

Tests

• bun test test/agent/agent.test.ts — 48/48 pass (includes new plan tool permission tests)
• bun test test/session/prompt-skill-mention.test.ts — 8/8 pass
• bun test test/permission — 141/141 pass

Related Files

• Report: docs/compose/reports/sticky-agent-mode.md
• TUI core: packages/opencode/src/cli/cmd/tui/context/local.tsx
• Permission: packages/opencode/src/agent/agent.ts
• Compose cleanup: packages/opencode/src/session/prompt.ts, compose.txt

[yanyihan-xiaomi]

Superseded by #1725 — same implementation, clean commit history, ready for discussion.