@gotgenes/pi-permission-system 39.0.4 → 39.1.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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)
 
 

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.4",
+  "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/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/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;