feat(permissions): fuzzy pattern matching for tool permissions

   Add fuzzy/glob pattern support to the permission system, allowing users
   to grant broad patterns (e.g. "mcp__playcanvas__*", "git.*", "/src/*")
   instead of only exact tool+args matches.

   Core changes:
   - `deriveFuzzyPattern()` — auto-derives glob from tool name structure
     (MCP: mcp__<server>__*, non-MCP: tool name itself)
   - `deriveFuzzyArgPattern()` — derives regex from args
     (bash: first-word prefix, file tools: directory prefix)
   - `describeFuzzyArgPattern()` — human-readable version for UI display
   - Three-tier save in TUI/Web: exact / fuzzy tool / fuzzy args
   - Session grants extended with glob matching (sessionGrantPatterns)
   - All three permission levels (Allow/Always Allow/Save) support fuzzy

   LLM supplement:
   - `prefetchLlmSuggestions()` — async fire-and-forget LLM call to derive
     smarter patterns (e.g. "git push.*" vs "git.*"), cached per session
   - Results appear as [AI] options on subsequent prompts for same tool

   Bug fixes:
   - TUI sub-menu Escape now cancels sub-mode instead of denying
   - Sub-menu arrow navigation debounced (120ms) to prevent double-jumps
   - Web UI sub-menu pattern consistent with TUI (expand-on-click)

   Files:
   - src/permissions/fuzzy.ts, fuzzy-llm.ts (new)
   - src/permissions/manager.ts (session grants + glob, persistRule override)
   - src/ui/conversation.ts (sub-menu state machine, LLM option rendering)
   - src/ui/tui-app.ts (three-tier save, session grant options)
   - src/ui/web/web-backend.ts (fuzzy in protocol, LLM prefetch)
   - src/ui/shared/types.ts (PermissionPrompt, ClientCommand, ServerEvent)
   - web/src/components/* (sub-menu UI, LLM suggestions)

Author: 王璨

openspec/changes/archive/2025-01-21-fuzzy-permission-matching/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-10

openspec/changes/archive/2025-01-21-fuzzy-permission-matching/design.md

@@ -0,0 +1,58 @@
+## Context
+
+`tool-name-glob` 和 `claude-code-permission-format` 已定义了 glob 规则存储和匹配能力。`permission-persist-ui` 定义了 "Always Allow (save)" 一键保存精确工具名。
+
+缺口：保存时只有精确名选项。用户想保存 `mcp__playcanvas__*` 只能手动编辑 settings.json。
+
+本变更在保存时自动推导模糊模式，与精确名并列为两个选项，用户一键选择，零编辑。
+
+## Goals / Non-Goals
+
+**Goals:**
+- "Always Allow (save)" 时同时展示精确和模糊两个选项
+- 模糊模式由系统自动推导，用户无需编辑
+- 对 MCP 工具推导 `mcp__<server>__*`；非 MCP 工具不展示模糊选项
+- TUI 和 Web 均支持
+
+**Non-Goals:**
+- 手动编辑模式（不需要）
+- 多层模糊（不需要 mid-level glob）
+- 正则表达式
+- 会话级授权变更
+
+## Decisions
+
+### Decision 1: 自动推导，不做手动编辑
+
+模糊模式完全由系统根据工具名结构推导。用户只需在精确/模糊之间二选一。
+
+**Rationale:** 90% 的模糊需求是「允许这个 MCP server 的所有工具」——`mcp__<server>__*`。不需要用户自己敲 `*`。
+
+### Decision 2: 推导规则
+
+- MCP 工具 (`mcp__<server>__<rest>`) → 模糊选项: `mcp__<server>__*`
+- 非 MCP 工具（无 `__` 分隔符）→ 不展示模糊选项
+- 未来可扩展：识别更多命名空间模式
+
+### Decision 3: TUI 交互
+
+按 `s` 后展开子选项：
+```
+[s] Always Allow (save)
+  [1] exact:  mcp__playcanvas__create_scene
+  [2] fuzzy:  mcp__playcanvas__*
+```
+按 `1` 保存精确，按 `2` 保存模糊。ESC 返回主选项。
+
+### Decision 4: Web 交互
+
+点击 "Save as Rule" 展开两个子按钮：
+- "Exact: mcp__playcanvas__create_scene"
+- "Fuzzy: mcp__playcanvas__*"
+
+点击即保存，无额外确认。
+
+## Risks / Trade-offs
+
+- **Risk:** 用户误选模糊选项，授权范围超出预期 → **Mitigation:** 模糊选项始终显示完整的 pattern 字符串，用户看清楚再选
+- **Risk:** 非 MCP 工具的模糊模式不够明显 → 当前不做，后续可加

openspec/changes/archive/2025-01-21-fuzzy-permission-matching/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+The permission tool's "Always Allow (save)" only saves exact tool name matches (e.g., `mcp__playcanvas__create_scene`). When a different tool from the same MCP server is invoked, the user must re-grant permission. Users want to save a fuzzy pattern like `mcp__playcanvas__*` directly from the permission prompt — without manual editing or opening settings.json.
+
+## What Changes
+
+- When user selects "Always Allow (save)", present **two options**: exact (`mcp__playcanvas__create_scene`) and fuzzy (`mcp__playcanvas__*`)
+- The fuzzy pattern is **auto-derived** from the tool name structure — no manual editing needed
+- For MCP tools (`mcp__<server>__<tool>`), the fuzzy pattern is `mcp__<server>__*`
+- For non-namespaced tools (e.g., `bash`, `read_file`), only the exact option is shown (no fuzzy)
+- TUI: pressing `s` shows exact/fuzzy sub-options; user picks one with a key
+- Web: "Save as Rule" expands to show two buttons: "Exact" and "Fuzzy (`mcp__<server>__*`)"
+
+## Capabilities
+
+### New Capabilities
+
+- `permission-fuzzy-save`: Auto-derived fuzzy pattern option in the "Always Allow (save)" flow. System derives the fuzzy pattern from the tool name and presents it alongside the exact option as a simple two-way choice.
+
+### Modified Capabilities
+
+- `permission-persist-ui`: "Always Allow (save)" now expands to a two-option choice (exact / fuzzy) instead of immediately saving the exact name. The persist payload carries the selected pattern.
+- `claude-code-permission-format`: `persistRule` now accepts an optional `toolNamePattern` override — when provided, it is written to settings instead of the prompt's exact tool name.
+
+## Impact
+
+- **TUI**: permission prompt key handler — `s` expands to sub-options
+- **Web**: `PermissionDialog` — "Save as Rule" expands to two buttons
+- **Shared types**: `PermissionPrompt` may carry an optional `fuzzyPattern: string` field
+- **Wire protocol**: `ClientCommand.permission` may need a `toolNamePattern` field
+- **PermissionManager**: `persistRule()` accepts optional pattern override

openspec/changes/archive/2025-01-21-fuzzy-permission-matching/specs/claude-code-permission-format/spec.md

@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: PersistRule writes allow/deny format
+When `persistRule()` writes a new permission rule to settings.json, it SHALL use the `allow` or `deny` array format rather than the `rules` object array. The tool name SHALL be written as-is (including any `*` wildcard). If `persistRule()` receives an optional `toolNamePattern` parameter, that pattern SHALL be used as the tool name in the persisted rule instead of the prompted tool name.
+
+#### Scenario: Persist allow rule to settings
+- **WHEN** user selects "Always Allow (save)" with exact for `mcp__lsp__textDocument_hover`
+- **THEN** settings.json `permissions.allow` SHALL contain `"mcp__lsp__textDocument_hover"` and `permissions.rules` SHALL be unchanged
+
+#### Scenario: Persist allow rule with fuzzy pattern
+- **WHEN** `persistRule()` is called with `{tool: "mcp__lsp__textDocument_hover", decision: "allow"}` and `toolNamePattern: "mcp__lsp__*"`
+- **THEN** settings.json `permissions.allow` SHALL contain `"mcp__lsp__*"` (NOT the original `mcp__lsp__textDocument_hover`)
+
+#### Scenario: Persist deny rule to settings
+- **WHEN** a deny rule with `{tool: "mcp__danger__*", decision: "deny"}` is persisted
+- **THEN** settings.json `permissions.deny` SHALL contain `"mcp__danger__*"`
+
+#### Scenario: Existing allow array is appended
+- **WHEN** settings.json already has `"allow": ["read_file"]` and a new allow rule for `bash` is persisted
+- **THEN** `"allow"` SHALL become `["read_file", "bash"]` (no duplicates)
+
+#### Scenario: Duplicate fuzzy pattern not appended
+- **WHEN** settings.json already has `"allow": ["mcp__lsp__*"]` and `persistRule()` is called with `toolNamePattern: "mcp__lsp__*"`
+- **THEN** `"allow"` SHALL remain `["mcp__lsp__*"]` (no duplicate entry)

openspec/changes/archive/2025-01-21-fuzzy-permission-matching/specs/permission-fuzzy-save/spec.md

@@ -0,0 +1,79 @@
+## ADDED Requirements
+
+### Requirement: Fuzzy pattern auto-derived for MCP tools
+When a permission prompt is shown for an MCP tool (name matching `mcp__<server>__<rest>`), the system SHALL auto-derive a fuzzy glob pattern `mcp__<server>__*` and present it alongside the exact tool name as a save option.
+
+#### Scenario: Fuzzy pattern derived for MCP tool
+- **WHEN** permission is prompted for `mcp__playcanvas__create_scene`
+- **THEN** the fuzzy save option SHALL display `mcp__playcanvas__*`
+
+#### Scenario: No fuzzy pattern for non-MCP tool
+- **WHEN** permission is prompted for `bash`
+- **THEN** no fuzzy save option SHALL be presented (only exact)
+
+#### Scenario: No fuzzy pattern for non-namespaced tool
+- **WHEN** permission is prompted for `read_file`
+- **THEN** no fuzzy save option SHALL be presented (only exact)
+
+### Requirement: TUI presents exact/fuzzy sub-options on save
+When the user presses `s` ("Always Allow (save)") in the TUI permission prompt and a fuzzy pattern can be derived, the TUI SHALL display sub-options: `[1] exact: <toolName>` and `[2] fuzzy: <fuzzyPattern>`. The TUI SHALL accept `1` to save the exact name, `2` to save the fuzzy pattern, and `Escape` to return to the main prompt.
+
+#### Scenario: TUI shows fuzzy sub-option
+- **WHEN** user presses `s` for `mcp__playcanvas__create_scene`
+- **THEN** the TUI SHALL display:
+  ```
+  [1] exact: mcp__playcanvas__create_scene
+  [2] fuzzy: mcp__playcanvas__*
+  ```
+
+#### Scenario: TUI saves exact on key 1
+- **WHEN** user presses `1` in the sub-option menu
+- **THEN** `persistRule` SHALL contain `{tool: "mcp__playcanvas__create_scene", decision: "allow"}`
+
+#### Scenario: TUI saves fuzzy on key 2
+- **WHEN** user presses `2` in the sub-option menu
+- **THEN** `persistRule` SHALL contain `{tool: "mcp__playcanvas__*", decision: "allow"}`
+
+#### Scenario: TUI Escape returns to main prompt
+- **WHEN** the sub-option menu is shown and user presses Escape
+- **THEN** the main permission prompt options SHALL be re-displayed
+
+#### Scenario: TUI skips sub-options when no fuzzy pattern
+- **WHEN** user presses `s` for `bash` (no fuzzy derivable)
+- **THEN** the exact name SHALL be saved immediately (no sub-option menu)
+
+### Requirement: Web presents exact/fuzzy sub-buttons on save
+When the user clicks "Save as Rule" in the Web permission dialog and a fuzzy pattern can be derived, the dialog SHALL display two buttons: "Exact: `<toolName>`" and "Fuzzy: `<fuzzyPattern>`". Clicking either button SHALL immediately send the persist command with the corresponding pattern.
+
+#### Scenario: Web shows fuzzy sub-button
+- **WHEN** user clicks "Save as Rule" for `mcp__playcanvas__create_scene`
+- **THEN** two buttons SHALL appear:
+  - "Exact: mcp__playcanvas__create_scene"
+  - "Fuzzy: mcp__playcanvas__*"
+
+#### Scenario: Web sends exact persist
+- **WHEN** user clicks "Exact: mcp__playcanvas__create_scene"
+- **THEN** a `ClientCommand` of type `permission` with `decision: "always_allow_save"` SHALL be sent (no `toolNamePattern`)
+
+#### Scenario: Web sends fuzzy persist
+- **WHEN** user clicks "Fuzzy: mcp__playcanvas__*"
+- **THEN** a `ClientCommand` of type `permission` with `decision: "always_allow_save"` and `toolNamePattern: "mcp__playcanvas__*"` SHALL be sent
+
+#### Scenario: Web skips sub-buttons when no fuzzy pattern
+- **WHEN** user clicks "Save as Rule" for `bash` (no fuzzy derivable)
+- **THEN** the exact name SHALL be saved immediately (no sub-buttons)
+
+### Requirement: Fuzzy pattern derivation function
+The system SHALL provide a `deriveFuzzyPattern(toolName: string): string | null` function. For tool names matching `mcp__<server>__<rest>`, it SHALL return `mcp__<server>__*`. For all other tool names, it SHALL return `null`.
+
+#### Scenario: Derive from MCP tool
+- **WHEN** `deriveFuzzyPattern("mcp__lsp__textDocument_hover")` is called
+- **THEN** it SHALL return `"mcp__lsp__*"`
+
+#### Scenario: Null for non-MCP tool
+- **WHEN** `deriveFuzzyPattern("bash")` is called
+- **THEN** it SHALL return `null`
+
+#### Scenario: Null for bare mcp prefix
+- **WHEN** `deriveFuzzyPattern("mcp__")` is called
+- **THEN** it SHALL return `null`

openspec/changes/archive/2025-01-21-fuzzy-permission-matching/specs/permission-persist-ui/spec.md

@@ -0,0 +1,53 @@
+## MODIFIED Requirements
+
+### Requirement: TUI permission dialog includes save option
+The TUI permission prompt SHALL present options: "Allow", "Always Allow", "Always Allow (save)", and "Deny". When the user selects "Always Allow (save)" and a fuzzy pattern can be derived from the tool name, the TUI SHALL display a sub-menu with exact and fuzzy options before saving. The "Input Idea" option SHALL be removed. The save option SHALL use key "s" with a distinct color.
+
+#### Scenario: TUI shows save option
+- **WHEN** the agent requests permission for tool `mcp__lsp__textDocument_definition`
+- **THEN** the TUI SHALL display options: `[Allow] [Always Allow] [Always Allow (save)] [Deny]`
+
+#### Scenario: Save option writes exact name to settings.json
+- **WHEN** user selects "Always Allow (save)" for `mcp__lsp__textDocument_definition` and chooses exact
+- **THEN** `PermissionPromptResult` SHALL have `decision: "allow"`, `rememberForSession: true`, and `persistRule: {tool: "mcp__lsp__textDocument_definition", decision: "allow"}`
+
+#### Scenario: Save option writes fuzzy pattern to settings.json
+- **WHEN** user selects "Always Allow (save)" for `mcp__lsp__textDocument_definition` and chooses fuzzy
+- **THEN** `PermissionPromptResult` SHALL have `decision: "allow"`, `rememberForSession: true`, and `persistRule: {tool: "mcp__lsp__*", decision: "allow"}`
+
+#### Scenario: Save option key binding
+- **WHEN** user presses "s" during permission prompt
+- **THEN** the "Always Allow (save)" SHALL be activated (showing sub-options if fuzzy is derivable)
+
+### Requirement: Web UI permission dialog includes save button
+The Web `PermissionDialog` component SHALL present a "Save as Rule" button alongside "Allow", "Always Allow", and "Deny". When clicked and a fuzzy pattern can be derived, the save area SHALL expand to show "Exact" and "Fuzzy" sub-buttons.
+
+#### Scenario: Web UI shows save button
+- **WHEN** a permission prompt is active in the Web UI
+- **THEN** four buttons SHALL be displayed: `[Allow] [Always Allow] [Save as Rule] [Deny]`
+
+#### Scenario: Web save button sends persist command (exact)
+- **WHEN** user clicks "Save as Rule" then "Exact" in Web UI
+- **THEN** a `ClientCommand` of type `permission` with `decision: "always_allow_save"` SHALL be sent to the backend
+
+#### Scenario: Web save button sends persist command (fuzzy)
+- **WHEN** user clicks "Save as Rule" then "Fuzzy: mcp__playcanvas__*" in Web UI
+- **THEN** a `ClientCommand` of type `permission` with `decision: "always_allow_save"` and `toolNamePattern: "mcp__playcanvas__*"` SHALL be sent to the backend
+
+### Requirement: Wire protocol supports always_allow_save
+The `ClientCommand.permission.decision` type SHALL include `"always_allow_save"` as a valid value. The `PermOption.value` type in shared types SHALL include `"always_allow_save"`. The `ClientCommand.permission` payload SHALL include an optional `toolNamePattern: string` field.
+
+#### Scenario: Backend receives always_allow_save
+- **WHEN** Web UI sends `{type: "permission", decision: "always_allow_save"}`
+- **THEN** the web backend SHALL resolve the permission with `decision: "allow"`, `rememberForSession: true`, and `persistRule: {tool: <current tool>, decision: "allow"}`
+
+#### Scenario: Backend receives always_allow_save with toolNamePattern
+- **WHEN** Web UI sends `{type: "permission", decision: "always_allow_save", toolNamePattern: "mcp__lsp__*"}`
+- **THEN** the web backend SHALL resolve the permission with `decision: "allow"`, `rememberForSession: true`, and `persistRule: {tool: "mcp__lsp__*", decision: "allow"}`
+
+### Requirement: Session grants remain exact match
+The "Always Allow" (session-level) option SHALL continue to use `sessionGrants` which stores exact tool names only. Session grants SHALL NOT support glob patterns.
+
+#### Scenario: Session grant is exact
+- **WHEN** user selects "Always Allow" for `mcp__lsp__textDocument_hover`
+- **THEN** only `mcp__lsp__textDocument_hover` is added to session grants; `mcp__lsp__textDocument_definition` is NOT automatically granted

openspec/changes/archive/2025-01-21-fuzzy-permission-matching/tasks.md

@@ -0,0 +1,36 @@
+## 1. Shared types & protocol
+
+- [x] 1.1 Add optional `toolNamePattern: string` field to `ClientCommand.permission` in shared types
+- [x] 1.2 Add optional `toolNamePattern` parameter to `persistRule` function signature
+- [x] 1.3 Update `PermissionPromptResult` to carry `toolNamePattern` when fuzzy is selected
+
+## 2. Fuzzy pattern derivation
+
+- [x] 2.1 Add `deriveFuzzyPattern(toolName: string): string | null` — for MCP tools (`mcp__<server>__<rest>`) returns `mcp__<server>__*`, otherwise `null`
+- [x] 2.2 Add `fuzzyPattern` to `PermissionPrompt` type so UI can display it
+
+## 3. PermissionManager persistRule changes
+
+- [x] 3.1 Update `persistRule()` to accept optional `toolNamePattern` override
+- [x] 3.2 When `toolNamePattern` provided, write it to `permissions.allow`/`permissions.deny` instead of prompt tool name
+- [x] 3.3 Skip appending if `toolNamePattern` already exists in the target array
+
+## 4. TUI permission prompt
+
+- [x] 4.1 When user presses `s` and `fuzzyPattern` exists, show sub-options: `[1] exact: <tool>` / `[2] fuzzy: <pattern>`
+- [x] 4.2 Key `1` saves exact name, key `2` saves fuzzy pattern, Escape returns to main prompt
+- [x] 4.3 When `fuzzyPattern` is null, `s` saves exact name immediately (no sub-menu)
+- [x] 4.4 Wire result into `PermissionPromptResult` with appropriate `toolNamePattern`
+
+## 5. Web permission dialog
+
+- [x] 5.1 When user clicks "Save as Rule" and `fuzzyPattern` exists, expand to show "Exact" and "Fuzzy" buttons
+- [x] 5.2 Click "Exact" → send persist without `toolNamePattern`
+- [x] 5.3 Click "Fuzzy" → send persist with `toolNamePattern`
+- [x] 5.4 When `fuzzyPattern` is null, "Save as Rule" saves exact name immediately (no expansion)
+
+## 6. Integration & cleanup
+
+- [x] 6.1 Ensure "Always Allow (save)" exact path works identically to before — no regression
+- [x] 6.2 Ensure session grants (`sessionGrants`) remain exact match only
+- [x] 6.3 End-to-end: prompt `mcp__playcanvas__create_scene` → save fuzzy `mcp__playcanvas__*` → next `mcp__playcanvas__delete_scene` call auto-allowed

openspec/changes/archive/2025-07-16-fix-mcp-double-underscore-separator/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-10

openspec/changes/archive/2025-07-16-fix-mcp-double-underscore-separator/design.md

@@ -0,0 +1,68 @@
+## Context
+
+The MCP tool naming convention uses `__` (double underscore) as the delimiter: `mcp__<server>__<tool>`. This pattern is already documented in existing specs (`tool-name-glob`, `permission-persist-ui`, `permission-project-persist`), but the implementation in `src/mcp/manager.ts` and `src/drivers/tool-registry.ts` uses single `_` instead.
+
+Single underscore is ambiguous: for a tool like `mcp_lsp_textDocument_hover`, it's impossible to determine where the server name ("lsp") ends and the tool name begins without external knowledge. With `__`, the boundary is explicit: `mcp__lsp__textDocument_hover`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Use `__` as the separator for MCP tool names and driver names, matching the spec convention
+- Update prefix extraction in `tool-registry.ts` to split on `__` for correct server grouping
+
+**Non-Goals:**
+- No migration tool for existing persisted permissions (low blast radius at this stage)
+- No change to the MCP wire protocol or MCP server configurations
+- No change to how tools are discovered or loaded — only the naming changes
+
+## Decisions
+
+### Decision 1: Separator format: `mcp__<server>__<tool>`
+
+Both boundaries use `__`: between `mcp` and `<server>`, and between `<server>` and `<tool>`.
+
+```typescript
+// Before (buggy):
+const toolName = `mcp_${serverName}_${def.name}`;
+// Result: mcp_lsp_textDocument_hover — ambiguous
+
+// After (correct):
+const toolName = `mcp__${serverName}__${def.name}`;
+// Result: mcp__lsp__textDocument_hover — unambiguous
+```
+
+The driver name also uses `__`:
+```typescript
+// Before:
+name: `mcp_${serverName}`  // "mcp_lsp"
+// After:
+name: `mcp__${serverName}` // "mcp__lsp"
+```
+
+### Decision 2: Prefix extraction
+
+The grouping logic in `tool-registry.ts` must split on `__`:
+
+```typescript
+// Before:
+const prefix = name.startsWith("mcp_")
+  ? name.split("_").slice(0, 2).join("_")
+  : "other";
+
+// After:
+const prefix = name.startsWith("mcp__")
+  ? name.split("__").slice(0, 2).join("__")
+  : "other";
+```
+
+For `mcp__lsp__textDocument_hover`, `split("__")` gives `["mcp", "lsp", "textDocument_hover"]`, and `slice(0,2).join("__")` gives `"mcp__lsp"` — the correct server group.
+
+### Decision 3: No migration tool
+
+Persisted permissions in `.dscode/settings.json` that use the old single-underscore format will silently stop matching because `matchesTool` does exact/glob comparison. Users will need to re-save their MCP tool permissions. Given the early stage of the project, this is acceptable — the alternative (writing a migration) adds complexity with minimal benefit.
+
+## Risks / Trade-offs
+
+- **[Risk]** Users with existing `permissions.allow` entries using `mcp_lsp_*` will have broken rules → **Mitigation**: Document in release notes. This is a developer tool in early development; blast radius is minimal.
+- **[Risk]** External code or scripts that depend on the old naming format → **Mitigation**: The naming is internal-only. No external API is affected.
+- **[Trade-off]** `__` is visually subtle but unambiguous → Chosen over alternatives like `:` (which could conflict with MCP URI schemes) or `/` (which looks like a path).