switchroom 0.14.12 → 0.14.13

package/telegram-plugin/permission-rule.ts

@@ -1,108 +1,187 @@
 /**
- * Resolve a Claude Code permission allow-rule from a permission_request
- * payload — the value we'd add to `tools.allow` in switchroom.yaml so
+ * Resolve Claude Code permission allow-rules from a permission_request
+ * payload — the value(s) we'd add to `tools.allow` in switchroom.yaml so
  * future invocations of the same operation never pop another approval
  * dialog.
  *
- * Used by the Telegram permission popup's "🔁 Always allow" button
- * (issue follow-up to #186). Per-skill granularity for `Skill` so
- * tapping "Always" on a `Skill (mail)` prompt only whitelists `mail`,
- * not all skills. Other tools fall back to the bare tool name —
- * promoting `Bash` from per-call confirm to always-allow is a more
- * meaningful blast-radius decision and shouldn't be hidden behind a
- * one-tap button on an arbitrary command, but the bare-name behaviour
- * is consistent with how the existing `tools.allow: [Bash]` works.
+ * Used by the Telegram permission card's "🔁 Always…" button. The button
+ * no longer commits a single fixed-breadth rule: it opens a scope choice
+ * so the operator decides whether "always" means *this exact thing* (e.g.
+ * this one file, this one MCP action) or *the whole category* (any file,
+ * every tool on the server). The scope of the grant — especially for
+ * "always" — must be legible before the operator taps it (vision pillar
+ * #2: you hold the leash).
  *
- * Returns:
- *   - `{ rule, label }` when we can compute a rule for the agent's yaml
- *   - `null` when the tool is something we don't know how to allow at
- *     a meaningful granularity (caller should disable the Always button
- *     to avoid writing a useless or dangerously-broad rule)
+ * `resolveScopedAllowChoices` returns up to two options:
+ *   - `specific` — the narrow grant (this file / this command / this
+ *     MCP action). Omitted when the tool has no meaningful sub-scope.
+ *   - `broad` — the category grant (any file / any command / every tool
+ *     on the server). Always present when choices resolve at all; the
+ *     gateway flags it with a ⚠️ and places it last.
  *
- * The `label` is what we surface to the operator in the confirmation
- * — "🔁 Always allow Skill(mail) for clerk". The rule is what lands in
- * yaml: matches Claude Code's settings.json permission-rule grammar
- * (`Tool` or `Tool(arg)` for granular).
+ * Returns `null` when the tool is something we can't allow at a
+ * meaningful granularity — the caller hides the Always button rather
+ * than write a useless or dangerously-broad rule.
+ *
+ * The rule strings match Claude Code's settings.json permission-rule
+ * grammar (`Tool`, `Tool(arg)`, `mcp__server__tool`, `mcp__server__*`).
  */
 
 import { basename } from "node:path";
 
-export interface AlwaysAllowRule {
-  /** The exact string to add to `tools.allow` in switchroom.yaml. */
+/** One scope option offered behind the "🔁 Always…" button. */
+export interface ScopeOption {
+  /** Exact string to add to `tools.allow` in switchroom.yaml. */
   readonly rule: string;
-  /** Human-readable label for the confirmation message. */
-  readonly label: string;
+  /** Short button label, e.g. "This file" / "Any file" / "All Perplexity". */
+  readonly buttonLabel: string;
+  /** True for the broadest option — gateway rides a ⚠️ on it and shows it last. */
+  readonly broad: boolean;
+}
+
+export interface ScopedAllowChoices {
+  /** Narrow grant (this file / this command / this action). May be absent. */
+  readonly specific?: ScopeOption;
+  /** Broadest grant (any file / any command / every server tool). */
+  readonly broad: ScopeOption;
 }
 
+const FILE_TOOLS = new Set([
+  "Edit",
+  "Write",
+  "MultiEdit",
+  "NotebookEdit",
+  "Read",
+]);
+
+// Tools with no meaningful sub-scope — only a broad, whole-tool grant.
+const BROAD_ONLY_TOOLS = new Set([
+  "Glob",
+  "Grep",
+  "WebFetch",
+  "WebSearch",
+  "Task",
+  "Agent",
+  "TodoWrite",
+  "ExitPlanMode",
+]);
+
 /**
- * @param toolName    Claude Code's tool_name from the permission_request
+ * @param toolName     Claude Code's tool_name from the permission_request
  * @param inputPreview JSON string with the tool's input. May be undefined
  *                     or non-JSON; the function is conservative.
  */
-export function resolveAlwaysAllowRule(
+export function resolveScopedAllowChoices(
   toolName: string,
   inputPreview: string | undefined,
-): AlwaysAllowRule | null {
+): ScopedAllowChoices | null {
   if (!toolName) return null;
   const input = parseInput(inputPreview);
 
-  switch (toolName) {
-    case "Skill": {
-      // Per-skill granularity: `Skill(mail)`. Mirror permission-title's
-      // defensive field-fallback so the rule resolves whenever the
-      // popup managed to render the skill name in brackets.
-      if (!input) return null;
-      const skill =
-        readString(input, "skill") ??
-        readString(input, "skill_name") ??
-        readString(input, "skillName") ??
-        readString(input, "name") ??
-        skillBasenameFromPath(input);
-      if (!skill) return null;
-      // Claude Code's permission-rule grammar quotes the arg with
-      // parentheses, no inner quoting needed for typical skill names
-      // (alphanumeric + dash/underscore/dot). Refuse rules with
-      // characters that could break the parser or expand to unintended
-      // matches.
-      if (!/^[A-Za-z0-9._\-+]+$/.test(skill)) return null;
+  // ── Skill: per-skill is the narrow grant; all skills is the broad one.
+  if (toolName === "Skill") {
+    const skill = input ? resolveSkillName(input) : null;
+    if (!skill) return null; // can't name it → don't offer an always rule
+    if (!/^[A-Za-z0-9._\-+]+$/.test(skill)) return null;
+    return {
+      specific: { rule: `Skill(${skill})`, buttonLabel: "This skill", broad: false },
+      broad: { rule: "Skill", buttonLabel: "Any skill", broad: true },
+    };
+  }
+
+  // ── File tools: this exact path vs any file.
+  if (FILE_TOOLS.has(toolName)) {
+    const path = filePathFrom(input);
+    const broad: ScopeOption = { rule: toolName, buttonLabel: "Any file", broad: true };
+    if (path) {
       return {
-        rule: `Skill(${skill})`,
-        label: `Skill(${skill})`,
+        specific: { rule: `${toolName}(${path})`, buttonLabel: "This file", broad: false },
+        broad,
       };
     }
-    case "Bash":
-    case "Read":
-    case "Write":
-    case "Edit":
-    case "MultiEdit":
-    case "NotebookEdit":
-    case "Glob":
-    case "Grep":
-    case "WebFetch":
-    case "WebSearch":
-    case "Task":
-    case "Agent":
-    case "TodoWrite":
-    case "ExitPlanMode": {
-      // Bare tool name — same shape as `tools.allow: [Bash]`. We
-      // don't pattern-match the args here: that's the operator's job
-      // when they want fine control. The Telegram button is for the
-      // common "I trust this skill / this tool category" case, not
-      // for synthesizing precise Bash glob rules.
-      return { rule: toolName, label: toolName };
-    }
-    default: {
-      // MCP tools (mcp__server__tool) come through with their full
-      // namespaced name. Pre-approve the exact tool — same pattern
-      // the scaffold already uses for SWITCHROOM_TELEGRAM_MCP_TOOLS.
-      if (/^mcp__[A-Za-z0-9_\-]+(__[A-Za-z0-9_\-]+)?$/.test(toolName)) {
-        return { rule: toolName, label: toolName };
-      }
-      // Unknown tool — refuse rather than write a rule we can't
-      // explain. Leaves the operator to add it via the CLI.
-      return null;
+    return { broad };
+  }
+
+  // ── Bash: this command family (`npm:*`) vs any command.
+  if (toolName === "Bash") {
+    const broad: ScopeOption = { rule: "Bash", buttonLabel: "Any command", broad: true };
+    const cmd = input ? readString(input, "command") : null;
+    const tok = cmd ? bashFirstToken(cmd) : null;
+    if (tok) {
+      return {
+        specific: { rule: `Bash(${tok}:*)`, buttonLabel: `${tok} commands`, broad: false },
+        broad,
+      };
     }
+    return { broad };
+  }
+
+  if (BROAD_ONLY_TOOLS.has(toolName)) {
+    return { broad: { rule: toolName, buttonLabel: "Always allow", broad: true } };
+  }
+
+  // ── MCP tools: `mcp__<server>__<tool>`. This exact action vs every
+  // tool on the server (`mcp__<server>__*`).
+  const mcp = /^mcp__([A-Za-z0-9_-]+)__([A-Za-z0-9_-]+)$/.exec(toolName);
+  if (mcp) {
+    const server = mcp[1]!;
+    return {
+      specific: { rule: toolName, buttonLabel: "This action", broad: false },
+      broad: { rule: `mcp__${server}__*`, buttonLabel: `All ${prettyMcpServer(server)}`, broad: true },
+    };
+  }
+  // Server-only namespace (`mcp__hindsight`) — broad grant only.
+  if (/^mcp__[A-Za-z0-9_-]+$/.test(toolName)) {
+    return { broad: { rule: toolName, buttonLabel: "Always allow", broad: true } };
   }
+
+  // Unknown tool — refuse rather than write a rule we can't explain.
+  return null;
+}
+
+/**
+ * Prettify an MCP server slug for display: `perplexity` → `Perplexity`,
+ * `google-workspace` → `Google Workspace`. Exported so the card title
+ * layer (permission-title.ts) renders the same server name as the
+ * scope button.
+ */
+export function prettyMcpServer(server: string): string {
+  return server
+    .split(/[-_]/)
+    .filter((w) => w.length > 0)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+function resolveSkillName(input: Record<string, unknown>): string | null {
+  return (
+    readString(input, "skill") ??
+    readString(input, "skill_name") ??
+    readString(input, "skillName") ??
+    readString(input, "name") ??
+    skillBasenameFromPath(input)
+  );
+}
+
+function filePathFrom(input: Record<string, unknown> | null): string | null {
+  if (!input) return null;
+  return readString(input, "file_path") ?? readString(input, "notebook_path");
+}
+
+/**
+ * First token of a Bash command, used to synthesize a `Bash(<tok>:*)`
+ * prefix rule. Returns null for anything that isn't a clean command
+ * word (paths, shell metacharacters, traversal) — better to fall back
+ * to the explicit "any command" grant than emit a rule that doesn't
+ * match what the operator saw.
+ */
+function bashFirstToken(command: string): string | null {
+  const m = /^\s*([^\s|&;<>()`$]+)/.exec(command);
+  if (!m) return null;
+  const tok = m[1]!;
+  if (tok.includes("..")) return null;
+  // Allow a leading path (e.g. /usr/bin/ls) but keep it a single safe word.
+  return /^[A-Za-z0-9._\-\/]+$/.test(tok) ? tok : null;
 }
 
 function parseInput(raw: string | undefined): Record<string, unknown> | null {
@@ -134,18 +213,8 @@ function skillBasenameFromPath(input: Record<string, unknown>): string | null {
 
 /**
  * Verify that a grant actually landed in the resolved `tools.allow` list.
- *
- * Called by the `perm:always:*` handler after `switchroom agent grant`
- * returns to guard against silently-failed or misdirected yaml writes.
- * Extracted as a pure helper so it can be unit-tested without a full
- * Grammy + switchroomExec harness.
- *
- * @param resolvedAllow  The `tools.allow` array from `resolveAgentConfig`
- *                       for the target agent (pass `[]` when absent/undefined).
- * @param ruleRule       The rule string produced by `resolveAlwaysAllowRule`
- *                       (e.g. `"Skill(garmin)"`, `"Bash"`, `"mcp__x__y"`).
- * @returns `true` when the rule is present (grant confirmed), `false` when
- *          absent (grant failed / config location drifted).
+ * Called by the always-allow handler after the persistence round-trip to
+ * guard against silently-failed or misdirected yaml writes.
  */
 export function isRulePersisted(
   resolvedAllow: readonly string[],
@@ -155,27 +224,22 @@ export function isRulePersisted(
 }
 
 /**
- * Inverse of `resolveAlwaysAllowRule` — does a stored allow-rule cover a
- * fresh `permission_request`? Used by the bridge's session-scoped
- * always-allow cache (issue #1138) to short-circuit prompts when the
- * operator has already tapped "🔁 Always allow" for an equivalent tool
- * call earlier in the same session.
+ * Inverse of the rule resolver — does a stored allow-rule cover a fresh
+ * `permission_request`? Used by the bridge's session-scoped always-allow
+ * cache (#1138) to short-circuit prompts when the operator has already
+ * tapped an equivalent grant earlier in the same session.
  *
- * Matching rules (mirrors what `resolveAlwaysAllowRule` produces):
+ * Matching rules (mirror what `resolveScopedAllowChoices` produces):
  *
- *   - Bare tool name (`Edit`, `Bash`, `Write`, …) ⇒ matches any
- *     invocation of that tool. This is consistent with how
- *     `tools.allow: [Edit]` works in `.claude/settings.json` — there's
- *     no arg matching at this layer.
- *   - `Skill(<name>)` ⇒ matches only `Skill` invocations whose resolved
- *     skill name (via the same field-fallback chain as the resolver)
- *     equals `<name>`.
- *   - `mcp__<server>__<tool>` ⇒ matches the exact namespaced MCP tool
- *     name.
+ *   - Bare tool name (`Edit`, `Bash`, …) ⇒ any invocation of that tool.
+ *   - `Edit(<path>)` / `Read(<path>)` / … ⇒ that tool, that exact file.
+ *   - `Bash(<tok>:*)` ⇒ Bash whose first command token equals `<tok>`.
+ *   - `Skill(<name>)` ⇒ Skill whose resolved name equals `<name>`.
+ *   - `mcp__<server>__<tool>` ⇒ that exact namespaced MCP tool.
+ *   - `mcp__<server>__*` ⇒ any tool on that MCP server.
  *
  * Returns `false` for any malformed rule rather than throwing — the
- * caller (bridge) is on the hot permission path and should fall through
- * to the gateway prompt on bad input.
+ * caller (bridge) is on the hot permission path.
  */
 export function matchesAllowRule(
   rule: string,
@@ -184,23 +248,37 @@ export function matchesAllowRule(
 ): boolean {
   if (!rule || !toolName) return false;
 
-  // Skill(name) — extract the parenthesized argument and compare against
-  // the resolved skill identifier from the request.
-  const skillMatch = /^Skill\(([^)]+)\)$/.exec(rule);
-  if (skillMatch) {
-    if (toolName !== "Skill") return false;
-    const ruleSkill = skillMatch[1];
+  // MCP wildcard: `mcp__server__*` covers every tool on that server.
+  if (rule.endsWith("__*") && rule.startsWith("mcp__")) {
+    const prefix = rule.slice(0, -1); // drop the trailing "*" → "mcp__server__"
+    return toolName.startsWith(prefix);
+  }
+
+  // `Tool(arg)` — scoped grants for Skill / file tools / Bash.
+  const scoped = /^([A-Za-z]+)\((.+)\)$/.exec(rule);
+  if (scoped) {
+    const ruleTool = scoped[1]!;
+    const arg = scoped[2]!;
+    if (ruleTool !== toolName) return false;
     const input = parseInput(inputPreview);
-    if (!input) return false;
-    const reqSkill =
-      readString(input, "skill") ??
-      readString(input, "skill_name") ??
-      readString(input, "skillName") ??
-      readString(input, "name") ??
-      skillBasenameFromPath(input);
-    return reqSkill === ruleSkill;
+
+    if (ruleTool === "Skill") {
+      if (!input) return false;
+      return resolveSkillName(input) === arg;
+    }
+    if (ruleTool === "Bash") {
+      const cmd = input ? readString(input, "command") : null;
+      if (!cmd) return false;
+      const m = /^([^:]+):\*$/.exec(arg); // "<tok>:*"
+      if (!m) return false;
+      return bashFirstToken(cmd) === m[1];
+    }
+    if (FILE_TOOLS.has(ruleTool)) {
+      return filePathFrom(input) === arg;
+    }
+    return false;
   }
 
-  // Bare tool name or namespaced MCP tool — exact string compare.
+  // Bare tool name or exact namespaced MCP tool — exact string compare.
   return rule === toolName;
 }