@gotgenes/pi-permission-system 39.0.3 → 39.1.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [39.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.4...pi-permission-system-v39.1.0) (2026-10-05)
+
+
+### Features
+
+* **pi-permission-system:** time, timeout, nice, stdbuf, and setsid resolve by the command they run ([8cf8fb0](https://github.com/gotgenes/pi-packages/commit/8cf8fb0e62681f49059f093bd1a1ff4d7fa78ece)), closes [#963](https://github.com/gotgenes/pi-packages/issues/963)
+* **pi-permission-system:** time -p and timeout -v keep the execution-modifier exemption ([#963](https://github.com/gotgenes/pi-packages/issues/963)) ([98157a3](https://github.com/gotgenes/pi-packages/commit/98157a3f1a9033172618a40738ad671a0f5d8604))
+
+### Documentation
+
+* **pi-permission-system:** measure the execution-modifier exemption ([#963](https://github.com/gotgenes/pi-packages/issues/963)) ([157f07a](https://github.com/gotgenes/pi-packages/commit/157f07a69c1f7f8103482ae7d8b6c15116970579))
+* **pi-permission-system:** document the execution-modifier exemption and mark Phase 15's #963 step complete ([03017b3](https://github.com/gotgenes/pi-packages/commit/03017b3422b412fc94afc8fe77d6126889bb4903))
+* **pi-permission-system:** measure the literal-word rule on execution modifiers ([#963](https://github.com/gotgenes/pi-packages/issues/963)) ([1c61a2a](https://github.com/gotgenes/pi-packages/commit/1c61a2a3b4707dc873b927ca84bed4c1a611b97a))
+* **pi-permission-system:** document the literal-word and -- rules for execution modifiers ([#963](https://github.com/gotgenes/pi-packages/issues/963)) ([17270c3](https://github.com/gotgenes/pi-packages/commit/17270c36b40debbddcc04fe3752a760dae62bb94))
+* **pi-permission-system:** note that a modifier's environment assignment may be computed ([#963](https://github.com/gotgenes/pi-packages/issues/963)) ([1ed420e](https://github.com/gotgenes/pi-packages/commit/1ed420e0095e37e76660583db42c6d5c11993103))
+
+## [39.0.4](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.3...pi-permission-system-v39.0.4) (2026-10-05)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** show a broken config file's error once, not twice, at session start ([67ddf4f](https://github.com/gotgenes/pi-packages/commit/67ddf4f637bd6f4e15246093dc3d1c459552c7f2)), closes [#953](https://github.com/gotgenes/pi-packages/issues/953)
+* **pi-permission-system:** report a policy file that fails closed mid-session ([100a0d3](https://github.com/gotgenes/pi-packages/commit/100a0d3e1b49c92454163b270df52df7cc78ca1f)), closes [#953](https://github.com/gotgenes/pi-packages/issues/953)
+
 ## [39.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.2...pi-permission-system-v39.0.3) (2026-10-03)
 
 

package/dist/public.d.ts

@@ -29,12 +29,16 @@ type BashCommandContext = "command_substitution" | "process_substitution" | "sub
  * core, so it is read-only for any argument feed and the floor's reason (an
  * unknown direction behind the wrapper) does not hold.
  *
+ * `"execution-modifier"` — every wrapper layer (`time`, `timeout`, `nice`,
+ * `stdbuf`, `setsid`) changes only how the visible inner command runs, so the
+ * unit is decided by that command's own rule whatever it does (#963).
+ *
  * A named reason rather than a boolean, so the review log states *why* a
  * wrapper was let through, and so a later source (a chain verdict, a user
  * declaration) is an added member rather than a second flag. ADR 0013 §11
- * keeps v1 at the audited core alone.
+ * keeps both reasons package-audited; user declarations do not lift the floor.
  */
-type FloorExemption = "core-reader";
+type FloorExemption = "core-reader" | "execution-modifier";
 interface PermissionCheckResult {
     toolName: string;
     state: PermissionState;
@@ -56,12 +60,12 @@ interface PermissionCheckResult {
      * The command the winning bash unit actually runs, when it is a wrapper whose
      * inner command differs from the unit text (#713). Display-only: the gate
      * decides on `command`, and on `executedUnit`'s rules only when
-     * {@link floorExemption} says the inner command is a proven pure reader.
+     * {@link floorExemption} says the wrapper's floor has no reason to hold.
      */
     executedUnit?: string;
     /**
      * Set when the winning bash unit is a wrapper the floor no longer covers,
-     * naming why (#803). Recorded in the review log so an allow the floor would
+     * naming why (#803, #963). Recorded in the review log so an allow the floor would
      * once have prompted for is auditable to the reason that let it through.
      */
     floorExemption?: FloorExemption;

package/docs/configuration.md

@@ -532,7 +532,7 @@ The bash gate fails closed: when in doubt it blocks or prompts, never silently a
 - An indirection wrapper — `sudo`, `env`, `xargs`, `time`, `nohup`, `timeout`, `nice`, `parallel`, `rust-parallel`, `rush`, `doas`, `setsid`, `stdbuf`, `watch`, `flock`, or `find`/`fd` carrying a per-result exec flag (`find` with `-exec`/`-execdir`/`-ok`/`-okdir`, `fd` with `-x`/`--exec`/`-X`/`--exec-batch`) — runs a following command that a rule on the wrapper text would otherwise never gate, so its decision is floored the same way (the synthetic `<indirection-bash-wrapper>` pattern in the review log).
   So `sudo aws s3 rm s3://bucket` prompts rather than riding an `aws *: allow`, while a bare `find . -name '*.py'` search (no exec flag) is unaffected.
   An `allow` is clamped to `ask`, and an explicit `deny` still denies.
-  The one exception is a wrapper running a [pure-reader command](#wrapper-transparency), whose direction is provable however unknown its argument feed is.
+  The [two exceptions](#wrapper-transparency) are a wrapper running a pure-reader command, whose direction is provable however unknown its argument feed is, and a wrapper that only modifies how a command runs (`time`, `timeout`, `nice`, `stdbuf`, `setsid`), which is decided exactly as the command it runs.
 
 Every synthetic `ask` above — the two parse sentinels and both wrapper floors — is auto-approved under `yoloMode: true`, which is an explicit full-permissive opt-in rather than a rule that could ride through.
 An explicit `deny` still denies under yolo, and with yolo off the floors are unaffected.
@@ -1018,7 +1018,12 @@ Two more shapes withdraw the claim:
 #### Wrapper transparency
 
 The [indirection-wrapper floor](#fail-closed-behavior) exists because a wrapper hides the command that should be gated.
-For one class the hiding is immaterial: a pure-reader command is read-only for **any** arguments, so `xargs grep -l foo` is provably a read even though what `xargs` feeds it is unknowable.
+Two kinds of wrapper unit have no reason to be floored: one running a [pure reader](#a-wrapper-running-a-pure-reader), and one that only [modifies how a command runs](#a-wrapper-that-only-modifies-execution).
+Each resolves by the inner command's own `bash` rules, and the review log records which reason applied as `floorExemption`.
+
+##### A wrapper running a pure reader
+
+For this class the hiding is immaterial: a pure-reader command is read-only for **any** arguments, so `xargs grep -l foo` is provably a read even though what `xargs` feeds it is unknowable.
 The floor guards unknowability of *scope*, and scope stays the path surfaces' job — for a wrapped command exactly as for a bare one.
 
 Such a unit is therefore **not** floored.
@@ -1034,7 +1039,7 @@ All four of these must hold, and each is a way the floor's reason could still ap
 4. The enclosing statement provably writes no file through a redirect.
    A destination the parse cannot resolve — `> $OUT`, `> $(mktemp)` — counts against the exemption rather than for it.
 
-So `xargs grep -l foo`, `xargs wc -l`, `xargs sed -n 1p`, and `find . -name '*.ts' -exec cat {} +` stop prompting under a matching `bash` allow, while `xargs rm`, `xargs sed -i`, `time pnpm test`, and `find . -exec sh -c '…' \;` still prompt.
+So `xargs grep -l foo`, `xargs wc -l`, `xargs sed -n 1p`, and `find . -name '*.ts' -exec cat {} +` stop prompting under a matching `bash` allow, while `xargs rm`, `xargs sed -i`, and `find . -exec sh -c '…' \;` still prompt.
 
 Three things this does **not** change:
 
@@ -1046,10 +1051,35 @@ Three things this does **not** change:
   The exemption decides the `bash` surface only, and every path token the command projects still goes through `path` and `external_directory` with the direction its command proved.
   Clause 4 is what keeps that from being a weaker promise than it sounds: a redirect destination the parse cannot resolve (`> $OUT`, `> $(mktemp)`) is not projected onto those surfaces either, so the wrapper keeps its floor rather than relying on a gate that would not see the write.
 
+##### A wrapper that only modifies execution
+
+`time`, `timeout`, `nice`, `stdbuf`, and `setsid` change only *how* the same visible command runs: its timing, kill deadline, scheduling, buffering, or session.
+Every operand is on the command line, and the wrapper adds no privilege, environment, or argument feed, so the floor's reason does not hold whatever the inner command does.
+Such a unit resolves exactly as the command it runs, and the review log records `floorExemption: "execution-modifier"`.
+
+All four of these must hold, and each keeps the decision about the command that really runs:
+
+1. **Every** wrapper layer is one of the five.
+   `time sudo rm -rf x` and `sudo time pnpm test` stay floored, as do `nohup` (it may write `nohup.out`) and `flock` (it creates its lock file).
+2. Every option on each layer is one that wrapper is known to take, spelled in full, and every option, value, and operand is written literally (an environment assignment, which the shell does not split, may be computed).
+   A word the shell rewrites (`timeout $D …`, `timeout {5,sudo} …`) may become several, one of them a wrapper, so it keeps the floor.
+   So `timeout --sig KILL 5 …` (an abbreviation) and `nice -5 …` stay floored, and so do `time`'s file-writing `-o`, `--output`, and `-a`.
+   The admitted options are `time -p`/`-l`/`-h`/`-f`; `timeout -s`/`-k`/`-f`/`-p`/`-v` and their long forms; `nice -n`/`--adjustment`; and `stdbuf -i`/`-o`/`-e` and their long forms.
+3. The command it runs is not itself a wrapper or an inline shell, so `timeout 5 bash -c '…'` stays floored.
+4. The command it runs is named literally.
+   `time ( … )` and `time { …; }` stay floored: the parser reads the group as `time`'s arguments, so the commands inside are not yet gated on their own rules.
+
+So under `bash: {"*": "allow", "git push *": "deny"}`, `time pnpm run lint >/tmp/lint.txt 2>&1` is allowed and `timeout 60 git push --force` is denied, exactly as without the wrapper.
+No redirect refusal applies here: the redirect destination goes through `path` and `external_directory` as it does for the bare command, and a destination the parse cannot resolve (`> $OUT`) is unprojected for both forms alike.
+When a unit qualifies for both exemptions (`time grep foo`), the review log records `core-reader`.
+
+##### Declarations and privilege
+
+Neither exemption is extended by configuration.
 A user `commandEffects` declaration participates in effect classification but does **not** lift the floor.
 The core's argument-independence is audited here; a claim about a wrapped command is not, and a wrong claim behind a wrapper fails open.
 
-`sudo` and `doas` are ordinary wrappers to this rule.
+`sudo` and `doas` are ordinary wrappers to the pure-reader rule, and never execution modifiers.
 The path surfaces gate `sudo cat /etc/shadow` exactly as they gate `cat /etc/shadow`, so nothing about the *file set* changes — what `sudo` adds is that the operating system would have refused, which this extension has never modelled.
 If you run a permissive `bash` policy and want privilege elevation to prompt regardless, say so directly:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "39.0.3",
+  "version": "39.1.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/bash/command-enumeration.ts

@@ -8,8 +8,8 @@ import {
   type CommandWord,
   classifyWrapperWords,
   executedUnitOf,
+  floorExemptionOf,
   inlineShellPayloadIndex,
-  isTransparentWrapper,
   type WrapperKind,
 } from "./wrapper-analysis";
 
@@ -468,9 +468,7 @@ function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
     spellings: homeSpelling === undefined ? undefined : [homeSpelling],
     wrapperKind: classifyWrapperWords(words),
     executedUnit: executedUnitOf(text, words) ?? undefined,
-    floorExemption: isTransparentWrapper(words, redirectedScope(node, scope))
-      ? "core-reader"
-      : undefined,
+    floorExemption: floorExemptionOf(words, redirectedScope(node, scope)),
   });
 }
 

package/src/access-intent/bash/wrapper-analysis.ts

@@ -9,6 +9,7 @@
  * classifiers over the same vocabulary would drift.
  */
 
+import type { FloorExemption } from "#src/types";
 import { proveCommandEffect } from "./command-effects";
 import type { ArgWord } from "./node-text";
 
@@ -143,9 +144,12 @@ export function executedUnitOf(
 }
 
 /**
- * True when a wrapper unit's floor has no reason left to hold: the command it
- * runs is in the pure-reader core, so its *direction* is provable however
- * unknown its argument feed is (ADR 0013 §11, #803).
+ * Why a wrapper unit's floor has no reason left to hold, or `undefined` when it
+ * still does.
+ *
+ * `"core-reader"`: the command it runs is in the pure-reader core, so its
+ * *direction* is provable however unknown its argument feed is (ADR 0013 §11,
+ * #803).
  *
  * The floor exists because a wrapper hides the command that should be gated,
  * and the unknowability it guards is unknowability of scope — which stays the
@@ -153,7 +157,7 @@ export function executedUnitOf(
  * alike. Argument-independence is the core's admission bar, so there are no
  * arguments that make `grep` write a file.
  *
- * Four things must hold, and each is a way the reason could still hold:
+ * Four things must hold for it, and each is a way the reason could still hold:
  *
  * 1. The unit is an indirection wrapper — an ordinary command has no floor.
  * 2. Unwrapping reached the inner command without passing through an opaque
@@ -165,21 +169,128 @@ export function executedUnitOf(
  *    not transparent.
  * 4. The unit writes no file through a redirect, which the caller reads off
  *    the parse tree and this module never sees.
+ *
+ * `"execution-modifier"`: every wrapper layer only changes *how* the visible
+ * inner command runs, so the unit resolves by that command's own rule whatever
+ * it does (see {@link onlyModifiesExecution}). The first two conditions above
+ * hold for it too; the core-reader reason is preferred when both apply.
  */
-export function isTransparentWrapper(
+export function floorExemptionOf(
   words: readonly CommandWord[],
   statement: { readonly writesViaRedirect: boolean },
-): boolean {
-  if (statement.writesViaRedirect) return false;
-  if (classifyWrapperWords(words) !== "indirection") return false;
+): FloorExemption | undefined {
+  if (classifyWrapperWords(words) !== "indirection") return undefined;
 
   // Only the peeled words matter here, so the walk is handed no source span to
   // cut from — the text slice is `executedUnitOf`'s product, not this one's.
   const unwrapped = unwrapIndirection(words, "");
-  if (unwrapped.kind === "opaque" || unwrapped.layers === 0) return false;
+  if (unwrapped.kind === "opaque" || unwrapped.peeled.length === 0) {
+    return undefined;
+  }
 
   const head = unwrapped.words.at(0)?.text ?? "";
-  return proveCommandEffect(head, unwrapped.words.slice(1)).effect === "read";
+  const provesRead =
+    proveCommandEffect(head, unwrapped.words.slice(1)).effect === "read";
+  if (provesRead && !statement.writesViaRedirect) return "core-reader";
+  return onlyModifiesExecution(unwrapped.peeled, unwrapped.words)
+    ? "execution-modifier"
+    : undefined;
+}
+
+/**
+ * True when every peeled layer only changes *how* the inner command runs, and
+ * that command is a literal name the gate can resolve by its own rule.
+ *
+ * The floor's reason (a wrapper hides the command that should be gated) is
+ * false for an execution modifier whatever the inner command does: every
+ * operand is on the command line, and the wrapper adds no privilege,
+ * environment, or argument feed. So the unit inherits the inner verdict rather
+ * than being classified a read, which is why no redirect refusal applies —
+ * the destination is gated by the path surfaces exactly as for the bare
+ * command.
+ *
+ * Each condition is a way the inherited verdict could name the wrong command:
+ *
+ * 1. Every layer is a modifier. The peel looks through `sudo` and `env` too,
+ *    so `time sudo rm` would otherwise inherit `rm`'s verdict.
+ * 2. Every option in every layer is on that modifier's allowlist. The real
+ *    tools accept abbreviations (`timeout --sig KILL 5 rm`) the inner-command
+ *    search does not know, and one of them misplaces where the command starts.
+ *    Each option, value, and operand must also be literal: the shell splits
+ *    `timeout $D pnpm` or expands `timeout {5,sudo} rm` into extra words before
+ *    the modifier runs, and one of those may be a wrapper or the real command.
+ * 3. The peel ended at an ordinary command, not a wrapper it could not see
+ *    past.
+ * 4. The inner head is a literal command name. The grammar has no `time`
+ *    keyword, so `time { …; }` and `time ( … )` reach here with shell syntax
+ *    where the command name should be.
+ */
+function onlyModifiesExecution(
+  peeled: readonly (readonly CommandWord[])[],
+  inner: readonly CommandWord[],
+): boolean {
+  return (
+    peeled.every(isAdmittedModifierLayer) &&
+    classifyWrapperWords(inner) === undefined &&
+    isLiteralCommandName(inner.at(0)?.text ?? "")
+  );
+}
+
+/**
+ * True when a peeled layer is an execution modifier whose every word before
+ * the inner command is one it admits.
+ *
+ * Walks the words with the same value-taking table {@link innerCommandIndex}
+ * skips by, so an admitted option's value can never be taken for the command.
+ */
+function isAdmittedModifierLayer(layer: readonly CommandWord[]): boolean {
+  const name = wrapperName(layer);
+  const flags =
+    name === undefined ? undefined : EXECUTION_MODIFIER_FLAGS.get(name);
+  if (name === undefined || flags === undefined) return false;
+
+  const valueTaking = admittedValueTaking(name);
+  for (let index = 1; index < layer.length; index++) {
+    const word = layer[index].text;
+    if (isEnvironmentAssignment(word)) continue;
+    // A word the shell rewrites (`$D`, `{5,sudo}`, `*`) may become several, one
+    // of them a wrapper or the real command, so only a literal word is admitted.
+    if (layer[index].computed) return false;
+    if (word === "--") continue;
+    if (!word.startsWith("-")) continue;
+    if (flags.has(word)) continue;
+    if (valueTaking.has(word)) {
+      index++;
+      if (layer[index]?.computed) return false;
+      continue;
+    }
+    if (!hasAttachedValue(word, valueTaking)) return false;
+  }
+  return true;
+}
+
+/** A modifier's value-taking options, less any that write a file. */
+function admittedValueTaking(name: string): ReadonlySet<string> {
+  const valueTaking = VALUE_TAKING_FLAGS.get(name) ?? EMPTY_FLAGS;
+  const writing = WRITING_OPTIONS.get(name) ?? EMPTY_FLAGS;
+  return new Set([...valueTaking].filter((flag) => !writing.has(flag)));
+}
+
+/** `--long=value`, or a short option with its value attached (`-sKILL`). */
+function hasAttachedValue(
+  word: string,
+  valueTaking: ReadonlySet<string>,
+): boolean {
+  if (word.startsWith("--")) {
+    const equals = word.indexOf("=");
+    return equals !== -1 && valueTaking.has(word.slice(0, equals));
+  }
+  return word.length > 2 && valueTaking.has(word.slice(0, 2));
+}
+
+/** A command name spelled literally: no quoting, expansion, or shell syntax. */
+function isLiteralCommandName(text: string): boolean {
+  return LITERAL_COMMAND_NAME.test(text) && !RESERVED_WORDS.has(text);
 }
 
 // ── Unwrapping ───────────────────────────────────────────────────────────────
@@ -200,8 +311,11 @@ type UnwrapResult =
       readonly kind: "peeled";
       readonly text: string;
       readonly words: readonly CommandWord[];
-      /** How many indirection layers came off; `0` means none did. */
-      readonly layers: number;
+      /**
+       * Each peeled layer's words before its inner command: the wrapper name,
+       * its options, and any leading operand. Empty when none came off.
+       */
+      readonly peeled: readonly (readonly CommandWord[])[];
     };
 
 /**
@@ -210,7 +324,7 @@ type UnwrapResult =
  *
  * Stopping early is not an error: the words peeled so far are returned, and
  * each caller decides what an incomplete peel is worth — `executedUnitOf`
- * shows it, {@link isTransparentWrapper} declines it because the head word it
+ * shows it, {@link floorExemptionOf} declines it because the head word it
  * would judge is the wrapper's own.
  *
  * `unitText` is the span the peeled `text` is cut from; a caller that wants
@@ -222,7 +336,7 @@ function unwrapIndirection(
 ): UnwrapResult {
   let text = unitText;
   let current = words;
-  let layers = 0;
+  const peeled: (readonly CommandWord[])[] = [];
 
   for (let depth = 0; depth < MAX_UNWRAP_DEPTH; depth++) {
     const kind = classifyWrapperWords(current);
@@ -238,11 +352,11 @@ function unwrapIndirection(
     if (start === -1 || start >= current.length) break;
     const end = execTerminatorIndex(current, start);
     text = sliceWords(text, current, start, end).trimEnd();
+    peeled.push(current.slice(0, start));
     current = rebase(current, start, end);
-    layers++;
   }
 
-  return { kind: "peeled", text, words: current, layers };
+  return { kind: "peeled", text, words: current, peeled };
 }
 
 /** How many wrapper layers to unwrap before giving up. */
@@ -304,7 +418,11 @@ function innerCommandIndex(words: readonly CommandWord[]): number {
 
   while (index < words.length) {
     const word = words[index].text;
-    if (word === "--") return index + 1;
+    if (word === "--") {
+      // The end of options, not of operands: `timeout -- 5 cmd` still takes
+      // its duration before the command.
+      return operandPending ? index + 2 : index + 1;
+    }
     if (isEnvironmentAssignment(word)) {
       index++;
       continue;
@@ -435,6 +553,78 @@ const VALUE_TAKING_FLAGS = new Map<string, ReadonlySet<string>>([
 
 const EMPTY_FLAGS: ReadonlySet<string> = new Set<string>();
 
+/**
+ * Wrappers that change only *how* the same visible command runs — timing, kill
+ * deadline, scheduling, buffering, session — each with the flags (options
+ * taking no value) it admits. Value-taking options are admitted from
+ * {@link VALUE_TAKING_FLAGS}, less {@link WRITING_OPTIONS}, so the two tables
+ * cannot disagree about where the inner command starts. Any other option
+ * refuses the exemption.
+ */
+const EXECUTION_MODIFIER_FLAGS = new Map<string, ReadonlySet<string>>([
+  // BSD `man 1 time`: `time [-al] [-h | -p] [-o file]`; `-p` is also the bash
+  // keyword's only option. `-a` appends to the `-o` file, so it is not listed.
+  ["time", new Set(["-p", "-l", "-h"])],
+  // GNU coreutils `timeout --help`.
+  [
+    "timeout",
+    new Set([
+      "-f",
+      "--foreground",
+      "-p",
+      "--preserve-status",
+      "-v",
+      "--verbose",
+    ]),
+  ],
+  // `nice` and `stdbuf` take only value options; util-linux `setsid`'s flags
+  // are unverified on this host, so none is admitted.
+  ["nice", EMPTY_FLAGS],
+  ["stdbuf", EMPTY_FLAGS],
+  ["setsid", EMPTY_FLAGS],
+]);
+
+/**
+ * Each modifier's value-taking options that write a file, never admitted.
+ * Per wrapper: `time -o` names an output file, while `stdbuf -o` sets a mode.
+ */
+const WRITING_OPTIONS = new Map<string, ReadonlySet<string>>([
+  ["time", new Set(["-o", "--output"])],
+]);
+
+/**
+ * A command name with no quoting, expansion, glob, or grouping character, and
+ * not an option: a name led by `-` is one {@link executedUnitOf} declines to
+ * name, so it could never be resolved.
+ */
+const LITERAL_COMMAND_NAME = /^[A-Za-z0-9_./+@%,:][A-Za-z0-9_./+@%,:-]*$/;
+
+/** Bash reserved words, which open syntax rather than name a command. */
+const RESERVED_WORDS: ReadonlySet<string> = new Set([
+  "!",
+  "{",
+  "}",
+  "[[",
+  "]]",
+  "case",
+  "coproc",
+  "do",
+  "done",
+  "elif",
+  "else",
+  "esac",
+  "fi",
+  "for",
+  "function",
+  "if",
+  "in",
+  "select",
+  "then",
+  "time",
+  "until",
+  "while",
+]);
+
 /**
  * Wrappers whose first bare word is an operand (a duration, a lock file) rather
  * than the start of the inner command.

package/src/config/config-store.ts

@@ -101,7 +101,7 @@ export class ConfigStore
    *
    * This store answers; `ConfigIssueReporter` decides whether the operator has
    * heard it yet (#933). Not to be confused with
-   * `PermissionResolver.getConfigIssues(agentName?)`, which answers for the
+   * `PermissionResolver.getPolicyIssues(agentName?)`, which answers for the
    * *policy* files rather than the extension config.
    */
   getConfigIssues(): readonly string[] {

package/src/config/policy-issue-reporter.ts

@@ -0,0 +1,55 @@
+/**
+ * policy-issue-reporter.ts — Tell the operator what composing their policy
+ * revealed, once per notice, for as long as it holds.
+ *
+ * The policy side answers only what it alone knows: the fail-closed notice for
+ * a rejected non-global scope (its `allow` rules are clamped to `ask`) and the
+ * port notice for relocated MCP tool keys. A config file's own schema errors
+ * are `ConfigIssueReporter`'s; both reporters reading them showed the operator
+ * each one twice (#953).
+ *
+ * Policy is re-read from file mtimes whenever it is consulted, so a file broken
+ * mid-session is clamped mid-session. Reporting only at `session_start` left
+ * that clamp unexplained; this is driven there and on every
+ * `before_agent_start`, so the operator hears about it on the next turn.
+ *
+ * The notices are agent-scoped, so the agent name is an argument rather than
+ * something this reads for itself: `AgentPrepHandler` resolves it from the
+ * `<active_agent>` prompt tag — the only name a pi-subagents child has — after
+ * turn prep runs, and hands it here.
+ *
+ * The latch is `ConfigIssueReporter`'s: per notice, delivered as one joined
+ * message per report, and *replaced* each report rather than added to — so a
+ * file fixed and broken again, or an agent switched away from and back into
+ * with a broken scope, is announced again.
+ */
+
+import type { ConfigIssueWarner } from "./config-issue-reporter";
+
+/** The policy seam this reads (ISP): the notices composing an agent's policy produced. */
+export interface PolicyIssueSource {
+  getPolicyIssues(agentName?: string): readonly string[];
+}
+
+/** The seam the session-start and agent-prep handlers drive. */
+export interface PolicyIssueReporting {
+  report(agentName: string | undefined): void;
+}
+
+export class PolicyIssueReporter implements PolicyIssueReporting {
+  private reported: ReadonlySet<string> = new Set();
+
+  constructor(
+    private readonly source: PolicyIssueSource,
+    private readonly log: ConfigIssueWarner,
+  ) {}
+
+  report(agentName: string | undefined): void {
+    const current = this.source.getPolicyIssues(agentName);
+    const unreported = current.filter((issue) => !this.reported.has(issue));
+    if (unreported.length > 0) {
+      this.log.warn(unreported.join("\n"));
+    }
+    this.reported = new Set(current);
+  }
+}

package/src/config/policy-loader.ts

@@ -81,8 +81,8 @@ export interface ResolvedPolicyPaths {
 
 /**
  * Abstraction over file I/O for loading permission policy from disk.
- * Implementations handle caching, path resolution, and config-issue
- * accumulation.  `PermissionManager` depends on this interface so that
+ * Implementations handle caching, path resolution, and marking a rejected
+ * scope `invalid`.  `PermissionManager` depends on this interface so that
  * merge + evaluation logic can be tested with an in-memory stub.
  */
 export interface PolicyLoader {
@@ -93,8 +93,6 @@ export interface PolicyLoader {
   getConfiguredMcpServerNames(): readonly string[];
   /** Combined mtime stamp for cache invalidation. */
   getCacheStamp(agentName?: string): string;
-  /** Accumulated config-parse issues across all loads. */
-  getConfigIssues(): string[];
   /** Resolved paths for the /permission-system show command. */
   getResolvedPolicyPaths(): ResolvedPolicyPaths;
 }
@@ -172,7 +170,6 @@ export class FilePolicyLoader implements PolicyLoader {
   private configuredMcpServerNamesCache: FileCacheEntry<
     readonly string[]
   > | null = null;
-  private accumulatedConfigIssues: string[] = [];
 
   constructor(options: PolicyLoaderOptions = {}) {
     this.globalConfigPath =
@@ -194,21 +191,11 @@ export class FilePolicyLoader implements PolicyLoader {
       : null;
   }
 
-  // ── Config issue accumulation ────────────────────────────────────────
-
-  private accumulateConfigIssues(issues: string[]): void {
-    for (const issue of issues) {
-      if (!this.accumulatedConfigIssues.includes(issue)) {
-        this.accumulatedConfigIssues.push(issue);
-      }
-    }
-  }
-
-  getConfigIssues(): string[] {
-    return [...this.accumulatedConfigIssues];
-  }
-
   // ── Scope loaders ────────────────────────────────────────────────────
+  //
+  // A config file's schema errors are not kept here: `ConfigStore` loads the
+  // same files through the same `loadUnifiedConfig` and reports them, so this
+  // loader reads them only to decide whether a scope fails closed (#953).
 
   loadGlobalConfig(): ScopeConfig {
     const stamp = getFileStamp(this.globalConfigPath);
@@ -216,8 +203,7 @@ export class FilePolicyLoader implements PolicyLoader {
       return this.globalConfigCache.value;
     }
 
-    const { config, issues } = loadUnifiedConfig(this.globalConfigPath);
-    this.accumulateConfigIssues(issues);
+    const { config } = loadUnifiedConfig(this.globalConfigPath);
 
     const value: ScopeConfig = {
       permission: config.permission,
@@ -238,7 +224,6 @@ export class FilePolicyLoader implements PolicyLoader {
     }
 
     const { config, issues } = loadUnifiedConfig(this.projectGlobalConfigPath);
-    this.accumulateConfigIssues(issues);
 
     // A present-but-rejected file yields issues (parse error or schema
     // rejection); an absent file yields none. Fail closed on the former.

package/src/handlers/before-agent-start.ts

@@ -4,6 +4,7 @@ import type {
   NormalizedBuildSystemPromptOptions,
 } from "@earendil-works/pi-coding-agent";
 import type { SubagentDetector } from "#src/authority/subagent-detection";
+import type { PolicyIssueReporting } from "#src/config/policy-issue-reporter";
 import {
   visibleSkillPromptEntries,
   withoutDeniedSkills,
@@ -78,6 +79,10 @@ export function shouldExposeTool(
  * - `logger` — records each change to the effective tool surface
  * - `detector` — tells a subagent child from a root, which decides whether a
  *   custom prompt gets this node's tool surface
+ * - `policyIssues` — reports what composing policy revealed for the agent the
+ *   prompt names; driven here rather than in turn prep because the
+ *   `<active_agent>` tag, the only name a pi-subagents child has, is read here
+ *   (#953)
  *
  * The active set is recomputed from the session's pre-filter tool surface
  * every turn, so relaxing a rule restores the tool it had withheld (#873).
@@ -90,6 +95,7 @@ export class AgentPrepHandler {
     private readonly toolRegistry: ToolRegistry,
     private readonly logger: DebugLogger,
     private readonly detector: SubagentDetector,
+    private readonly policyIssues: PolicyIssueReporting,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -105,6 +111,9 @@ export class AgentPrepHandler {
         ? event.systemPrompt
         : event.systemPrompt.join("\n");
     const agentName = this.session.resolveAgentName(ctx, systemPrompt);
+    // Policy is re-read by mtime, so this turn may compose a clamp the file
+    // just caused; say so for the agent this turn runs as.
+    this.policyIssues.report(agentName ?? undefined);
     const registered = readRegisteredTools(this.toolRegistry.getAll());
     const surface = this.session.resolveExposedTools(
       this.observeToolSurface(registered),

package/src/handlers/gates/bash-command.ts

@@ -183,7 +183,8 @@ function floorUnparsedUnit(
  * is clamped up to a synthetic `ask` naming the kind that caused it — unless
  * the enumerator established that the floor has no reason left to hold, in
  * which case the unit is resolved by the rules of the command it runs (ADR 0013
- * §11, #803).
+ * §11): its inner command is a proven pure reader (#803), or every wrapper
+ * layer only modifies how that command runs (#963).
  *
  * Only an `allow` reaches here, which is what makes the exemption unable to
  * weaken anything: an explicit `deny` or `ask` on the wrapper is decided before

package/src/handlers/lifecycle.ts

@@ -1,10 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AskDialogRelease } from "#src/authority/ask-dialog-queue";
 import type { ConfigIssueReporting } from "#src/config/config-issue-reporter";
+import type { PolicyIssueReporting } from "#src/config/policy-issue-reporter";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "#src/config/status";
 import type { DecisionSummaryWriter } from "#src/logging/decision-audit";
 import type { SessionLogger } from "#src/logging/session-logger";
-import type { PermissionResolver } from "#src/policy/permission-resolver";
 import type { ServiceLifecycle } from "#src/service/service-lifecycle";
 import type { PermissionSession } from "#src/session/permission-session";
 
@@ -41,7 +41,9 @@ export const UNTRUSTED_PROJECT_MESSAGE =
  *
  * Constructor deps:
  * - `session` — encapsulates all mutable session state and lifecycle operations
- * - `resolver` — owns permission-query surface: `getConfigIssues`
+ * - `policyIssues` — reports what composing policy revealed (a fail-closed clamp,
+ *   a port notice) for the agent the session names, latched per notice; driven
+ *   here and on every turn, so a clamp caused mid-session is explained (#953)
  * - `serviceLifecycle` — owns the process-global service publication;
  *   `activate` publishes (skipped for registered subagent children) and emits
  *   the ready event; `teardown` unsubscribes all session listeners and unpublishes
@@ -56,7 +58,7 @@ export const UNTRUSTED_PROJECT_MESSAGE =
 export class SessionLifecycleHandler {
   constructor(
     private readonly session: PermissionSession,
-    private readonly resolver: PermissionResolver,
+    private readonly policyIssues: PolicyIssueReporting,
     private readonly serviceLifecycle: ServiceLifecycle,
     private readonly logger: SessionLogger,
     private readonly audit: DecisionSummaryWriter,
@@ -84,10 +86,7 @@ export class SessionLifecycleHandler {
     }
 
     const agentName = this.session.resolveAgentName(ctx);
-    const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
-    for (const issue of policyIssues) {
-      this.logger.warn(issue);
-    }
+    this.policyIssues.report(agentName ?? undefined);
 
     if (event.reason === "reload") {
       this.logger.debug("lifecycle.reload", {

package/src/index.ts

@@ -41,6 +41,7 @@ import { ConfigStore } from "#src/config/config-store";
 import { resolveDialogKeys } from "#src/config/dialog-keys";
 import { isYoloModeEnabled } from "#src/config/extension-config";
 import { computeExtensionPaths } from "#src/config/extension-paths";
+import { PolicyIssueReporter } from "#src/config/policy-issue-reporter";
 import { GateRunner } from "#src/handlers/gates/runner";
 import { SkillInputGatePipeline } from "#src/handlers/gates/skill-input-gate-pipeline";
 import { ToolCallGatePipeline } from "#src/handlers/gates/tool-call-gate-pipeline";
@@ -322,9 +323,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // was recorded as delivered and never shown (#933). Driven at session_start
   // and on every turn; the latch keeps an unchanged issue quiet.
   const configIssueReporter = new ConfigIssueReporter(configStore, logger);
+  // What composing policy revealed (a fail-closed clamp, a port notice) is
+  // agent-scoped, so each driver hands over the agent name it resolved (#953).
+  const policyIssueReporter = new PolicyIssueReporter(resolver, logger);
   const lifecycle = new SessionLifecycleHandler(
     session,
-    resolver,
+    policyIssueReporter,
     serviceLifecycle,
     logger,
     audit,
@@ -346,6 +350,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     toolRegistry,
     logger,
     subagentDetection,
+    policyIssueReporter,
   );
 
   const gateRunner = new GateRunner(

package/src/policy/permission-manager.ts

@@ -62,12 +62,12 @@ type ResolvedPermissions = {
   /**
    * Non-global scopes whose config file failed to load or validate. When
    * non-empty the composed ruleset has been floored allow→ask (#646); the
-   * names also drive the fail-closed notice in {@link getConfigIssues}.
+   * names also drive the fail-closed notice in {@link getPolicyIssues}.
    */
   failClosedScopes: RuleOrigin[];
   /**
    * Top-level permission keys naming Pi MCP tools, relocated onto the `mcp`
-   * surface; they drive the port notice in {@link getConfigIssues}.
+   * surface; they drive the port notice in {@link getPolicyIssues}.
    */
   legacyMcpToolKeys: string[];
 };
@@ -92,7 +92,7 @@ export interface ScopedPermissionManager {
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   isToolFullyDenied(toolName: string, agentName?: string): boolean;
-  getConfigIssues(agentName?: string): string[];
+  getPolicyIssues(agentName?: string): string[];
 }
 
 export interface PermissionManagerOptions extends PolicyLoaderOptions {
@@ -158,11 +158,20 @@ export class PermissionManager implements ScopedPermissionManager {
     this.resolvedPermissionsCache.clear();
   }
 
-  getConfigIssues(agentName?: string): string[] {
-    // Trigger a load/resolve to ensure issues are collected.
+  /**
+   * What composing `agentName`'s policy revealed: the fail-closed notice for
+   * a rejected non-global scope and the port notice for relocated MCP tool
+   * keys. Recomputed on every resolve, so a notice disappears once its cause is
+   * fixed.
+   *
+   * A config file's own schema errors are not here: `ConfigStore` loads the
+   * same files through the same `loadUnifiedConfig` and owns reporting them,
+   * so listing them here too showed the operator each one twice (#953).
+   */
+  getPolicyIssues(agentName?: string): string[] {
     const { failClosedScopes, legacyMcpToolKeys } =
       this.resolvePermissions(agentName);
-    const issues = [...this.loader.getConfigIssues()];
+    const issues: string[] = [];
     if (failClosedScopes.length > 0) {
       issues.push(
         `Invalid ${failClosedScopes.join(", ")} configuration detected — ` +

package/src/policy/permission-resolver.ts

@@ -4,6 +4,7 @@ import type {
   ResolvedAccessIntent,
 } from "#src/access-intent/access-intent";
 import { surfaceFamilyMembers } from "#src/access-intent/path-surfaces";
+import type { PolicyIssueSource } from "#src/config/policy-issue-reporter";
 import type { SkillPermissionChecker } from "#src/exposure/skill-prompt-sanitizer";
 import type { SessionRules } from "#src/session/session-rules";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
@@ -64,7 +65,7 @@ function toResolvedIntent(
  * - `sessionRules` — narrowed to `getRuleset` (ISP: the resolver only reads, never records)
  */
 export class PermissionResolver
-  implements ScopedPermissionResolver, SkillPermissionChecker
+  implements ScopedPermissionResolver, SkillPermissionChecker, PolicyIssueSource
 {
   constructor(
     private readonly permissionManager: ScopedPermissionManager,
@@ -139,7 +140,7 @@ export class PermissionResolver
     return this.permissionManager.isToolFullyDenied(toolName, agentName);
   }
 
-  getConfigIssues(agentName?: string): string[] {
-    return this.permissionManager.getConfigIssues(agentName);
+  getPolicyIssues(agentName?: string): string[] {
+    return this.permissionManager.getPolicyIssues(agentName);
   }
 }

package/src/types.ts

@@ -48,12 +48,16 @@ export type BashCommandContext =
  * core, so it is read-only for any argument feed and the floor's reason (an
  * unknown direction behind the wrapper) does not hold.
  *
+ * `"execution-modifier"` — every wrapper layer (`time`, `timeout`, `nice`,
+ * `stdbuf`, `setsid`) changes only how the visible inner command runs, so the
+ * unit is decided by that command's own rule whatever it does (#963).
+ *
  * A named reason rather than a boolean, so the review log states *why* a
  * wrapper was let through, and so a later source (a chain verdict, a user
  * declaration) is an added member rather than a second flag. ADR 0013 §11
- * keeps v1 at the audited core alone.
+ * keeps both reasons package-audited; user declarations do not lift the floor.
  */
-export type FloorExemption = "core-reader";
+export type FloorExemption = "core-reader" | "execution-modifier";
 
 export interface PermissionCheckResult {
   toolName: string;
@@ -76,12 +80,12 @@ export interface PermissionCheckResult {
    * The command the winning bash unit actually runs, when it is a wrapper whose
    * inner command differs from the unit text (#713). Display-only: the gate
    * decides on `command`, and on `executedUnit`'s rules only when
-   * {@link floorExemption} says the inner command is a proven pure reader.
+   * {@link floorExemption} says the wrapper's floor has no reason to hold.
    */
   executedUnit?: string;
   /**
    * Set when the winning bash unit is a wrapper the floor no longer covers,
-   * naming why (#803). Recorded in the review log so an allow the floor would
+   * naming why (#803, #963). Recorded in the review log so an allow the floor would
    * once have prompted for is auditable to the reason that let it through.
    */
   floorExemption?: FloorExemption;