@dieulc/workflow 0.9.1 → 0.10.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dieulc/workflow",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "private": false,
   "keywords": ["pi-package", "workflow", "plan-mode", "review-mode", "questionnaire", "rewind"],
   "description": "Plan↔Build mode with an independent Review Mode reviewer, questionnaire, subagent explore, todos and shadow-checkpoint rewind for Pi.",
   "license": "MIT",
   "scripts": {
-    "test": "node --test utils.todo.test.ts permissions.test.ts roles.test.ts profiles.test.ts thinking-levels.test.ts workflow-status.test.ts picker.test.ts questionnaire-layout.test.ts questionnaire-view.test.ts model-default.test.ts review.test.ts review-ui.test.ts extension.test.ts commit-policy.test.ts edit-policy.test.ts tab-policy.test.ts tab-editor.test.ts",
+    "test": "node --test utils.todo.test.ts permissions.test.ts shell-text.test.ts roles.test.ts profiles.test.ts provider-retarget.test.ts thinking-levels.test.ts workflow-status.test.ts picker.test.ts questionnaire-layout.test.ts questionnaire-view.test.ts model-default.test.ts review.test.ts review-handoff.test.ts review-ui.test.ts extension.test.ts commit-policy.test.ts edit-policy.test.ts tab-policy.test.ts tab-editor.test.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "check:policy": "node --experimental-transform-types scripts/verify-write-policy.mjs",
     "prepublishOnly": "node ../../../scripts/verify-packages.mjs --pack-only --packages workflow"
@@ -41,8 +41,12 @@
     "questionnaire-view.ts",
     "model-default.ts",
     "permissions.ts",
+    "shell-text.ts",
     "review.ts",
     "review-providers.ts",
+    "review-recovery.ts",
+    "review-handoff.ts",
+    "provider-retarget.ts",
     "review-tools.ts",
     "review-runtime.ts",
     "review-ui.ts",
@@ -64,10 +68,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.84.4",
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-agent-core": "1.5.0",
+    "@earendil-works/pi-ai": "1.5.0",
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0",
     "typebox": "1.3.7",
     "@types/node": "^20.19.43",
     "typescript": "5.5.4"

package/permissions.ts

@@ -15,6 +15,17 @@
  * stays loadable in plain Node tests, exactly like `utils.ts`.
  */
 
+import {
+  atCommandPosition,
+  scanShell,
+  splitSegments,
+  tokenizeWords,
+  wordsText,
+  type ShellRedirect,
+  type ShellWord,
+} from "./shell-text.ts";
+import type { ArgumentCompletion } from "./utils.ts";
+
 export type CommandClass = "read-only" | "verify" | "full";
 
 export type WorkflowRole = "planner" | "reviewer" | "explorer" | "builder";
@@ -371,8 +382,10 @@ const BLOCKED_SCRIPT_SUFFIX_RE = /[:._-](fix|write)([:._-]|$)/i;
 // ── Dangerous syntax / patterns ──────────────────────────────────────
 
 /**
- * Hard denylist. Applied to the whole raw command (quote-insensitive, like the
- * original implementation) before any allowlist classification.
+ * Hard denylist, matched in COMMAND POSITION against a segment's argv (see
+ * `destructiveHit`): a keyword inside an argument of a read-only command is
+ * data, not a command. Every binary that executes its arguments is class
+ * `full`, so the anywhere-pass still covers `env rm`, `bash -c`, `xargs`.
  *
  * The git entries are deliberately narrowed so the read-only forms the
  * allowlist exposes are actually reachable: `git tag -l` / `--list`,
@@ -573,21 +586,37 @@ export function stripHarmlessRedirects(command: unknown): string {
  * Why a command's syntax cannot be classified (`null` = the syntax is fine).
  * Mirrors the order the gate has always used, so a refusal can name the first
  * failing construct instead of only saying "blocked".
+ *
+ * Two views, because the shell treats the two classes of construct
+ * differently (`shell-text.ts`):
+ *  - OPERATORS (`&`, `>`, `>>`, `<<`, `<(`/`>(`) are operators only OUTSIDE
+ *    quotes, so they are read from the `structural` view. `rg 'a > b' f`
+ *    writes nothing and `rg '<<' f` reads nothing.
+ *  - EXPANSIONS (`$(…)`, backticks, `${…}`) happen OUTSIDE single quotes but
+ *    DO happen inside double quotes, so they are read from the `expandable`
+ *    view. `rg '$(id)' f` is a literal search; `rg "$(id)" f` executes.
+ *
+ * The harmless-redirect exemptions (`2>&1`, `1>&2`, `> /dev/null`) are
+ * applied to the structural view BEFORE the tests, exactly as before: they
+ * are real redirects, they just write nothing the user can see.
  */
 export function forbiddenSyntaxReason(command: unknown): string | null {
   const raw = typeof command === "string" ? command : "";
+  if (!raw) return null;
+  const scan = scanShell(raw);
   // `2>&1` / `1>&2` are fd duplications, not file writes; `/dev/null` targets
-  // are a bit bucket, not a file.
-  const scrubbed = stripHarmlessRedirects(raw);
-  if (scrubbed.replace(/&&/g, " ").includes("&"))
+  // are a bit bucket, not a file. Masked (quoted) text is already non-
+  // structural, so a quoted `2>&1` needs no exemption.
+  const structural = stripHarmlessRedirects(scan.structural);
+  if (structural.replace(/&&/g, " ").includes("&"))
     return "a background `&` (only `&&` chains are allowed)";
-  if (raw.includes("$(")) return "command substitution `$(...)`";
-  if (raw.includes("`")) return "backtick command substitution";
-  if (raw.includes("${")) return "parameter expansion `${...}`";
-  if (raw.includes("<(") || raw.includes(">("))
+  if (scan.expandable.includes("$(")) return "command substitution `$(...)`";
+  if (scan.expandable.includes("`")) return "backtick command substitution";
+  if (scan.expandable.includes("${")) return "parameter expansion `${...}`";
+  if (structural.includes("<(") || structural.includes(">("))
     return "process substitution `<(...)` / `>(...)`";
-  if (raw.includes("<<")) return "a heredoc `<<`";
-  if (/(^|[^<&])>(?!>|&)/.test(scrubbed))
+  if (structural.includes("<<")) return "a heredoc `<<`";
+  if (/(^|[^<&])>(?!>|&)/.test(structural))
     return "a file redirect (`>` / `>>`); only `/dev/null` and `2>&1` are allowed";
   return null;
 }
@@ -605,67 +634,40 @@ export function hasForbiddenSyntax(command: string): boolean {
 /**
  * Split a compound command on top-level `|`, `;`, `&&`, `||` and newlines.
  * Quote-aware: `grep -E 'a|b' f` stays one segment.
+ *
+ * Delegates to `shell-text.ts` so the policy layer has ONE definition of a
+ * segment boundary. `splitSegments` reproduces this function's original
+ * behaviour exactly (including its escape-before-quote ordering); only the
+ * implementation moved.
  */
 export function splitCommandSegments(command: string): string[] {
-  const segments: string[] = [];
-  let current = "";
-  let quote: '"' | "'" | undefined;
-  let escaped = false;
-  const push = (): void => {
-    const s = current.trim();
-    if (s) segments.push(s);
-    current = "";
-  };
-  for (let i = 0; i < command.length; i++) {
-    const ch = command[i];
-    if (escaped) {
-      current += ch;
-      escaped = false;
-      continue;
-    }
-    if (ch === "\\") {
-      current += ch;
-      escaped = true;
-      continue;
-    }
-    if (quote) {
-      current += ch;
-      if (ch === quote) quote = undefined;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      quote = ch;
-      current += ch;
-      continue;
-    }
-    if (ch === "\n" || ch === ";") {
-      push();
-      continue;
-    }
-    if (ch === "|") {
-      push();
-      if (command[i + 1] === "|") i++;
-      continue;
-    }
-    if (ch === "&" && command[i + 1] === "&") {
-      push();
-      i++;
-      continue;
-    }
-    current += ch;
-  }
-  push();
-  return segments;
+  return splitSegments(command);
 }
 
 // ── Classification ───────────────────────────────────────────────────
 
 /** Classify one already-split segment. Unknown input → `full` (fail closed). */
 export function commandClassOf(segment: string): CommandClass {
+  return classifyWords(tokenizeWords(segment).words, segment);
+}
+
+/**
+ * Classify a segment whose argv words are already tokenised.
+ *
+ * The dispatch reads `words[0]` — the command name AFTER quote removal and
+ * with redirects excluded, so `2>/dev/null ls` classifies as `ls` instead of
+ * as an unknown binary. The branch helpers keep taking the segment text: they
+ * inspect flags and script names, and rewriting all of them would mix this
+ * change with an unrelated refactor. `commandClassOf(string)` stays the
+ * public entry point (D6).
+ */
+function classifyWords(
+  words: readonly ShellWord[],
+  segment: string,
+): CommandClass {
   const s = String(segment ?? "").trim();
   if (!s) return "full";
-  const first = firstWord(s);
-
+  const first = normalizeBinary(words[0]?.value ?? "") || firstWord(s);
   if (!first) return "full";
   if (INTERPRETER_EXECUTABLES.has(first)) return "full";
 
@@ -1041,29 +1043,230 @@ function classifyCargo(s: string): CommandClass {
 // ── Public gate ──────────────────────────────────────────────────────
 
 /**
- * The first destructive pattern (or writing flag) that matches, with the exact
- * text that matched so a refusal can name it (`rm`, `npm install`, `--fix`).
+ * The two ways a segment can be denied outright (see `destructiveHit`).
  */
-function destructiveMatch(
-  command: string,
-): { kind: "destructive-pattern" | "blocked-flag"; label: string } | undefined {
-  const hit = DESTRUCTIVE_PATTERNS.find((p) => p.test(command));
-  if (hit) {
-    const matched = command.match(hit)?.[0]?.trim() ?? "destructive keyword";
-    return { kind: "destructive-pattern", label: `\`${matched}\`` };
+type DestructiveKind = "destructive-pattern" | "blocked-flag";
+
+/** One segment as the destructive denylist needs to see it. */
+interface DestructiveInput {
+  words: readonly ShellWord[];
+  commandClass: CommandClass;
+}
+
+/**
+ * Position/class-aware destructive match.
+ *
+ * The denylist is defence-in-depth: a command that can EXECUTE its
+ * arguments is already class `full` and `full` is refused for every
+ * restricted role, so the keyword layer only has to catch what the
+ * classifier could have got wrong. Matching it against raw text — the old
+ * behaviour — made the canonical exploration queries impossible:
+ * `rg -n "rm -rf" src` was refused because the PATTERN contained a keyword.
+ *
+ * The rule (`shell-text.ts` gives the argv words):
+ *  1. A pattern counts when it matches at the START of a segment's argv —
+ *     the command position. `rm -rf x`, `npm install`, `git commit` hit;
+ *     `rg -n rm -rf src` does not.
+ *  2. It also counts ANYWHERE in a segment already classified `full`: that
+ *     segment is refused regardless, and the more specific label makes the
+ *     refusal explain itself (`env rm -rf /`, `bash -c "rm -rf /"`).
+ *  3. Patterns are checked across every segment BEFORE any flag, preserving
+ *     the original precedence (`npm install` reports a pattern, not a flag).
+ *
+ * Flags are matched against word VALUES, not raw text, because quote removal
+ * makes `find . "-delete"` a real flag.
+ */
+function destructiveHit(
+  segments: readonly DestructiveInput[],
+): { kind: DestructiveKind; label: string; index: number } | undefined {
+  // 1. Patterns in command position.
+  for (let i = 0; i < segments.length; i++) {
+    const text = wordsText(segments[i].words);
+    if (!text) continue;
+    for (const pattern of DESTRUCTIVE_PATTERNS) {
+      const m = pattern.exec(text);
+      if (m && atCommandPosition(text, m.index)) {
+        return {
+          kind: "destructive-pattern",
+          label: `\`${m[0].trim()}\``,
+          index: i,
+        };
+      }
+    }
+  }
+  // 2. Patterns anywhere in a segment that is already unrestricted.
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (seg.commandClass !== "full") continue;
+    const text = wordsText(seg.words);
+    if (!text) continue;
+    for (const pattern of DESTRUCTIVE_PATTERNS) {
+      const m = pattern.exec(text);
+      if (m) {
+        return {
+          kind: "destructive-pattern",
+          label: `\`${m[0].trim()}\``,
+          index: i,
+        };
+      }
+    }
+  }
+  // 3. A write flag on an otherwise-safe command (`eslint --fix`).
+  for (let i = 0; i < segments.length; i++) {
+    const m = DENIED_FLAG_RE.exec(wordsText(segments[i].words));
+    if (m) {
+      return {
+        kind: "blocked-flag",
+        label: `the flag \`${m[2] ?? m[0].trim()}\``,
+        index: i,
+      };
+    }
   }
-  const flag = command.match(DENIED_FLAG_RE);
-  if (flag)
-    return {
-      kind: "blocked-flag",
-      label: `the flag \`${flag[2] ?? flag[0].trim()}\``,
-    };
   return undefined;
 }
 
+/** Classify a command's segments the way the destructive denylist needs. */
+function destructiveInputsOf(command: unknown): DestructiveInput[] {
+  const scan = scanShell(command);
+  return scan.segments.map((seg) => ({
+    words: seg.words,
+    commandClass: commandClassOf(seg.raw),
+  }));
+}
+
 /** True when a segment is denied outright (destructive syntax or writing flags). */
 export function isDestructiveCommand(command: string): boolean {
-  return destructiveMatch(command) !== undefined;
+  return destructiveHit(destructiveInputsOf(command)) !== undefined;
+}
+
+// ── One analysis, two gates ──────────────────────────────────────────
+
+/** One segment, with both the role verdict and the write verdict. */
+export interface SegmentAnalysis {
+  /** Trimmed segment text (what `splitCommandSegments` returns). */
+  raw: string;
+  /** ARGV words after quote removal; operators and redirects excluded. */
+  words: ShellWord[];
+  /** Redirections of this segment (not argv). */
+  redirects: ShellRedirect[];
+  /** The command name, normalized (`git`, `npm`, `ls`). */
+  command: string;
+  /** Highest capability this segment needs. */
+  commandClass: CommandClass;
+  /** The write flag found on this segment, e.g. `--fix`. */
+  writeFlag?: string;
+  /** The git subcommand when this is a commit-policy operation. */
+  gitCommit: CommitPolicyHit | null;
+  /** The destructive pattern/flag that names this segment, when it is one. */
+  destructive?: { kind: DestructiveKind; label: string };
+  /** True when this segment may modify the filesystem. */
+  mutating: boolean;
+  /** Human cause, present when `mutating`. */
+  writeReason?: string;
+}
+
+/** The single analysis both gates consume (see `analyzeCommand`). */
+export interface CommandAnalysis {
+  raw: string;
+  /** The shell construct that cannot be classified, when there is one. */
+  forbiddenSyntax?: string;
+  segments: SegmentAnalysis[];
+  /** The first destructive hit across all segments, for the refusal message. */
+  destructive?: { kind: DestructiveKind; label: string };
+  /** True when ANY segment may modify the filesystem. */
+  mutating: boolean;
+  writeReason?: string;
+  writeSegment?: string;
+}
+
+/**
+ * Analyse a command ONCE for both gates.
+ *
+ * This is the single pipeline the role gate (`explainCommandRefusal`) and the
+ * write gate (`commandMayWrite` in edit-policy.ts) share, so their answers can
+ * no longer disagree about the same text.
+ *
+ * Per segment the write verdict follows the order the write policy has always
+ * documented (`edit-policy.ts`, "commandMayWrite"):
+ *   1. forbidden shell syntax → may write (a redirect is a write whatever else
+ *      runs; checked first so `git commit -m x > log` is still a write)
+ *   2. `git add|commit|push` → NOT a file write: the commit policy owns them
+ *   3. an unrestricted command class (`full`) → may write. Fail-closed default:
+ *      anything not provably read-only (interpreters, unknown binaries) may
+ *      write.
+ *   4. a write flag on a verify-class command (`eslint --fix`) → may write
+ *   5. otherwise → read-only (`ls`, `rg`, `git status`, `npm test`,
+ *      `tsc --noEmit`, and harmless redirects to `/dev/null` / `2>&1`).
+ *
+ * Classification runs on `stripHarmlessRedirects(segment)`, exactly as before:
+ * the `/dev/null` and `2>&1` exemptions are load-bearing (they keep
+ * `2>/dev/null ls` and `npm test 2> /dev/null | tail -5` read-only).
+ *
+ * Total and never throws: non-strings analyse as empty.
+ */
+export function analyzeCommand(command: unknown): CommandAnalysis {
+  const raw = typeof command === "string" ? command : "";
+  const trimmed = raw.trim();
+  if (!trimmed) return { raw, segments: [], mutating: false };
+
+  const scan = scanShell(trimmed);
+  const forbiddenSyntax = forbiddenSyntaxReason(trimmed) ?? undefined;
+  const segments: SegmentAnalysis[] = [];
+  let mutating = false;
+  let writeReason: string | undefined;
+  let writeSegment: string | undefined;
+
+  for (const seg of scan.segments) {
+    const scrubbed = stripHarmlessRedirects(seg.raw).trim();
+    const gitCommit = scrubbed ? gitCommitPolicyHit(scrubbed) : null;
+    const commandClass = commandClassOf(scrubbed || seg.raw);
+    const flag = DENIED_FLAG_RE.exec(wordsText(seg.words));
+    const segment: SegmentAnalysis = {
+      raw: seg.raw,
+      words: seg.words,
+      redirects: seg.redirects,
+      command: normalizeBinary(seg.words[0]?.value ?? ""),
+      commandClass,
+      gitCommit,
+      mutating: false,
+    };
+    if (flag) segment.writeFlag = flag[2] ?? flag[0].trim();
+
+    const syntax = forbiddenSyntaxReason(seg.raw);
+    if (syntax) {
+      segment.mutating = true;
+      segment.writeReason = syntax;
+    } else if (!scrubbed) {
+      // Nothing but harmless redirections: writes no file.
+    } else if (gitCommit) {
+      // The commit policy governs git add/commit/push; not a file write.
+    } else if (commandClass === "full") {
+      segment.mutating = true;
+      segment.writeReason = "runs a command that may modify files";
+    } else if (flag) {
+      segment.mutating = true;
+      segment.writeReason = `uses the write flag ${flag[2] ?? flag[0].trim()}`;
+    }
+
+    if (!mutating && segment.mutating) {
+      mutating = true;
+      writeReason = segment.writeReason;
+      writeSegment = seg.raw;
+    }
+    segments.push(segment);
+  }
+
+  const hit = destructiveHit(segments);
+  if (hit) {
+    segments[hit.index].destructive = { kind: hit.kind, label: hit.label };
+  }
+
+  const analysis: CommandAnalysis = { raw, segments, mutating };
+  if (forbiddenSyntax) analysis.forbiddenSyntax = forbiddenSyntax;
+  if (hit) analysis.destructive = { kind: hit.kind, label: hit.label };
+  if (writeReason) analysis.writeReason = writeReason;
+  if (writeSegment) analysis.writeSegment = writeSegment;
+  return analysis;
 }
 
 function classAllows(policyClass: CommandClass, needed: CommandClass): boolean {
@@ -1092,6 +1295,9 @@ export interface CommandRefusal {
  * The single source of truth for the gate: `null` means allowed. Keeping the
  * decision and the explanation in one function stops a refusal message from
  * describing a policy the gate no longer enforces.
+ *
+ * Reads ONE `analyzeCommand` result, so this gate and the write policy cannot
+ * disagree about quoting, redirects or command position.
  */
 export function explainCommandRefusal(
   role: WorkflowRole,
@@ -1105,36 +1311,40 @@ export function explainCommandRefusal(
       : { kind: "empty", detail: "the command is empty" };
   if (policy.commandClass === "full") return null;
 
-  const syntax = forbiddenSyntaxReason(raw);
-  if (syntax)
+  const analysis = analyzeCommand(raw);
+
+  if (analysis.forbiddenSyntax)
     return {
       kind: "forbidden-syntax",
-      detail: `forbidden shell syntax: ${syntax}`,
-      suggestion: syntax.includes("redirect")
+      detail: `forbidden shell syntax: ${analysis.forbiddenSyntax}`,
+      suggestion: analysis.forbiddenSyntax.includes("redirect")
         ? "drop the redirect — `cmd` already captures stdout and `cmd 2>&1` also captures stderr; only `2>/dev/null` and `2>&1` are exempt"
         : "use an allowlisted read-only/verify command, or /build for full shell access",
     };
 
-  const destructive = destructiveMatch(raw);
-  if (destructive)
+  if (analysis.destructive) {
+    const { kind, label } = analysis.destructive;
     return {
-      kind: destructive.kind,
-      detail: `${destructive.label} matched the raw command text (quoting does not exempt it)`,
+      kind,
+      detail:
+        kind === "blocked-flag"
+          ? `${label} can rewrite files`
+          : `${label} matched the destructive denylist`,
       suggestion:
         "remove or rename the argument, or use /build for unrestricted access",
     };
+  }
 
-  const segments = splitCommandSegments(raw);
-  if (segments.length === 0)
+  if (analysis.segments.length === 0)
     return { kind: "empty", detail: "no command segments found" };
-  for (const segment of segments) {
-    const needed = commandClassOf(segment);
-    if (classAllows(policy.commandClass, needed)) continue;
-    const head = firstWord(segment) || segment.slice(0, 40);
+  for (const segment of analysis.segments) {
+    if (classAllows(policy.commandClass, segment.commandClass)) continue;
+    const needed = segment.commandClass;
+    const head = segment.command || segment.raw.slice(0, 40);
     return {
       kind: "segment-class",
       detail: `\`${head}\` needs ${needed === "full" ? "unrestricted" : needed} access, above the ${policy.commandClass} limit`,
-      segment,
+      segment: segment.raw,
       suggestion: `${policy.role} may run ${policy.description}; see README "Permissions" for allowlisted alternatives, or use /build`,
     };
   }
@@ -1158,3 +1368,93 @@ export function describeRolePolicy(role: WorkflowRole): string {
   const policy = policyForRole(role);
   return `${policy.role} may run ${policy.description}`;
 }
+
+// ── Diagnostics: "/permissions explain" ─────────────────────────────
+
+/**
+ * Explain a command's verdict under every policy, for `/permissions explain`.
+ *
+ * Pure and side-effect free: it reads the same `analyzeCommand` result and
+ * the same `explainCommandRefusal` the gates use, so the answer cannot
+ * describe a policy the gate no longer enforces. Returns lines ready for
+ * `ctx.ui.notify`; the first line is always the command (or the usage).
+ */
+export function describeCommandPolicy(command: unknown): string[] {
+  const raw = typeof command === "string" ? command.trim() : "";
+  if (!raw) {
+    return [
+      "Usage: /permissions explain <command>",
+      "  Shows each segment's command class, the Plan/Review/Explorer verdict,",
+      "  and whether the write policy would treat it as a write.",
+      "  Example: /permissions explain rg -n 'a > b' docs",
+    ];
+  }
+
+  const analysis = analyzeCommand(raw);
+  const lines: string[] = [`Command: ${raw}`];
+  for (const reason of [
+    analysis.forbiddenSyntax
+      ? `forbidden shell syntax: ${analysis.forbiddenSyntax}`
+      : undefined,
+    analysis.destructive
+      ? `destructive denylist: ${analysis.destructive.label}`
+      : undefined,
+  ]) {
+    if (reason) lines.push(`  ✖ ${reason}`);
+  }
+
+  lines.push(`Segments (${analysis.segments.length}):`);
+  analysis.segments.forEach((seg, index) => {
+    const flags = [seg.commandClass, seg.mutating ? "write" : "no write"];
+    if (seg.writeFlag) flags.push(`flag ${seg.writeFlag}`);
+    if (seg.gitCommit) flags.push(`git ${seg.gitCommit} (commit policy)`);
+    lines.push(`  ${index + 1}. ${seg.raw}`, `     ${flags.join(" · ")}`);
+  });
+
+  lines.push("Role verdicts:");
+  for (const role of ["planner", "reviewer", "explorer"] as const) {
+    const refusal = explainCommandRefusal(role, raw);
+    lines.push(
+      refusal
+        ? `  ${role.padEnd(9)} ✖ ${refusal.kind} — ${refusal.detail}`
+        : `  ${role.padEnd(9)} ✔ allowed`,
+    );
+  }
+
+  lines.push(
+    analysis.mutating
+      ? `Default write policy: write — ${analysis.writeReason ?? "may modify files"}`
+      : "Default write policy: read-only — no prompt",
+  );
+  return lines;
+}
+
+/**
+ * Argument completions for `/permissions`.
+ *
+ * Follows the pi-tui full-argument contract used by the other policy
+ * commands: the first token completes the subcommand and the returned value
+ * replaces the whole typed argument. The command text itself is free-form, so
+ * nothing is offered past the subcommand.
+ *
+ * The exact-match rule is `suppressExactArgumentMatch` (utils.ts) inlined: a
+ * `utils.ts` import would add a runtime cycle (utils imports this module for
+ * `isSafeCommand`). Same behaviour — typing the whole word closes the list, so
+ * the first Enter submits.
+ */
+export function permissionsArgumentCompletions(
+  argumentPrefix: string,
+): ArgumentCompletion[] | null {
+  const raw = String(argumentPrefix ?? "");
+  if (/\s/.test(raw.trim())) return null;
+  const lower = raw.trim().toLowerCase();
+  if (!"explain".startsWith(lower)) return null;
+  if (lower === "explain") return null;
+  return [
+    {
+      value: "explain ",
+      label: "explain",
+      description: "show why a command would be allowed or refused",
+    },
+  ];
+}