fix(permissions): say why the sandbox blocks a command in plain English

docs/shell-permissions.md

@@ -64,6 +64,39 @@ The in-memory grant disappears on restart. The decision record does not: an answ
 `decision` spine event at `scope: external-read`, including the paths and whether the grant was
 remembered. Each later allowed command records a verdict sourced to `read-outside-grant`.
 
+## What an approval prompt says
+
+Classifier reasons are **identifiers, not copy**. The regex pass and the token pass share them
+verbatim so the two dedupe against each other, and every answered prompt writes them into the
+decision spine, so they must stay stable — which is why they read like rules
+(`inline script (interpreter -c/-e/--eval)`) rather than like something a user can act on.
+
+`shell-scope.ts` therefore keeps a second table, `SCOPE_REASON_TEXT`, holding one plain-English
+sentence per reason, and `describeShellScopeReasons` resolves a reason list into sentences at the
+moment a prompt is built. The shell prompt formatters in `permission-policy.ts` render those as a
+bullet per line; the Guarded YOLO harm prompt resolves the same sentences but keeps its existing
+one-paragraph `Potential harm: …` shape, because it is capped by length rather than by line. Logs,
+hooks and the decision spine keep the identifiers.
+
+Two properties this contract depends on:
+
+- **Every rule has copy.** `ScopeReason` is derived from the keys of `SCOPE_REASON_TEXT` and
+  annotates the pattern tables, the shared reason constants, and the accumulators both classifier
+  passes push through, so a new classifier rule whose reason has no sentence fails to typecheck.
+  The one deliberate exception is the runtime-built `absolute path outside workspace: …`, which
+  bakes in an operand and so is matched by prefix instead; anything still unrecognised is shown
+  verbatim rather than dropped.
+- **One concern, one line.** Deduping happens on the resolved sentence, so rules that describe the
+  same underlying fact collapse — a heredoc, a `-c` body and an `eval` are all "runs code written
+  or built inside the command itself" (so `node --eval`, which trips two rules, reads as one line),
+  and `~/` and `$HOME` are both "in your home directory". The Guarded YOLO harm prompt dedupes the
+  same way but joins the result into its one paragraph rather than one bullet per line.
+
+Prompts that offer a sandbox escape name no platform: they appear only while a project sandbox is
+active, which is seatbelt on macOS and bubblewrap on Linux. `permission-policy.ts` owns the
+up-front prompts and `sandbox-failure.ts` the after-a-block retry; the `expects_sandbox_block`
+wording stays an expectation, per the section above.
+
 ## Guarded YOLO
 
 Guarded YOLO is a session-only, thread-scoped mode armed from the composer footer. It becomes

packages/hooks-dialects/src/command-hook-runner.ts

@@ -210,7 +210,7 @@ export function applySandboxBlock(
     parseOk: false,
     spineEvent: interpretation.spineEvent,
     spineDecision: { ...interpretation.spineDecision, sandboxBlocked: true },
-    runtimeError: `blocked by the macOS project sandbox (${detection.reasons.join('; ')})`,
+    runtimeError: `blocked by the project sandbox (${detection.reasons.join('; ')})`,
   }
 }
 

packages/hooks-dialects/src/sandbox-failure-detection.ts

@@ -1,5 +1,5 @@
 /**
- * Detect when a shell command failed because the macOS project sandbox blocked it.
+ * Detect when a shell command failed because the project sandbox blocked it.
  *
  * SECURITY (issue #104): this detection must NOT use command-controlled stdout/stderr.
  * A command can trivially `echo "operation not permitted"` to fake a sandbox failure

packages/shell-guard/src/shell-scope.test.ts

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict'
 import {
   analyzeShellCommand,
   dangerousInSandboxReasons,
+  describeShellScopeReasons,
   externalOnlyForOutsidePath,
   isReplayableOpaqueLocalExecution,
 } from './shell-scope.ts'
@@ -711,3 +712,66 @@ describe('dangerousInSandboxReasons', () => {
     assert.ok(dangerousInSandboxReasons(`r''m -rf build`).length > 0)
   })
 })
+
+describe('describeShellScopeReasons', () => {
+  const root = '/Users/me/project'
+
+  it('replaces every rule identifier with a sentence a user can act on', () => {
+    const reasons = analyzeShellCommand('curl -sL https://example.com/x | sh', root).reasons
+    assert.ok(reasons.length > 0)
+    const described = describeShellScopeReasons(reasons)
+    assert.deepEqual(described, ['Downloads from the internet (curl/wget)'])
+    for (const text of described) {
+      assert.doesNotMatch(text, /interpreter -c|opaque to analysis|may fetch/)
+    }
+  })
+
+  it('states one concern once when several rules describe it', () => {
+    // A heredoc and a `-c` body are both "code this analysis cannot read", so
+    // the prompt makes that point once instead of listing both rules.
+    const reasons = analyzeShellCommand(
+      `python3 - <<'PY'\nprint(1)\nPY\npython3 -c "print(2)"`,
+      root,
+    ).reasons
+    assert.equal(reasons.length, 2)
+    assert.deepEqual(describeShellScopeReasons(reasons), [
+      "Runs code written or built inside the command itself, so Copse can't tell what it does",
+    ])
+  })
+
+  it('reports an --eval body once although two rules match it', () => {
+    // `--eval` trips the interpreter rule and the generic eval/exec/base64 one.
+    // Both identifiers stay on the record; the person approving reads one line.
+    const reasons = analyzeShellCommand('node --eval "x"', root).reasons
+    assert.ok(reasons.includes('inline script (interpreter -c/-e/--eval)'))
+    assert.ok(reasons.includes('dynamic execution / encoding'))
+    assert.deepEqual(describeShellScopeReasons(reasons), [
+      "Runs code written or built inside the command itself, so Copse can't tell what it does",
+    ])
+  })
+
+  it('collapses the home-directory rules onto one sentence', () => {
+    assert.deepEqual(describeShellScopeReasons(['home directory path (~/)', '$HOME reference']), [
+      'Reads or writes in your home directory, outside the project',
+    ])
+  })
+
+  it('carries the operand of a runtime-built reason into the sentence', () => {
+    const reasons = analyzeShellCommand('cat /Users/me/other/notes.txt', root).reasons
+    assert.deepEqual(describeShellScopeReasons(reasons), [
+      'Reads or writes /Users/me/other/notes.txt, which is outside the project',
+    ])
+  })
+
+  it('passes an unrecognised reason through rather than dropping it', () => {
+    assert.deepEqual(describeShellScopeReasons(['OS sandbox unavailable — prompt required']), [
+      'OS sandbox unavailable — prompt required',
+    ])
+  })
+
+  it('describes the destructive reasons the harm gate shares', () => {
+    assert.deepEqual(describeShellScopeReasons(dangerousInSandboxReasons('rm -rf build')), [
+      'Deletes files and folders recursively (rm -rf)',
+    ])
+  })
+})