@sema-agent/core 7.17.1 → 7.17.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 7.17.3 — 2026-09-13
+
+### Narrowing — "not on the read-only allowlist" is not "reads no path": the read boundary judges every segment (#758; test [7138]; @server @cli @test)
+- **Before.** The read boundary judged the path operands of a shell segment only when that segment's PROGRAM was on the read-only allowlist. Any other program's operands were not judged at all — not for containment, not against the sensitive-path deny table — so an out-of-root read and a deny-row read both ran with ZERO asks under `shellGate` absent AND `"classify"`, while the same read spelled `cat` was one mandated ask. Measured on the real load path (Runner prepare → NodeExecutionEnv → the gate): `strings <outside>`, `nl <outside>`, `od -c <outside>`, `rev`, `file`, and `sort ~/.ssh/id_rsa` — asks=0, command executed, both doctrines. A name table was doing double duty as a claim about behaviour, and the set it silenced is the one set a name table cannot enumerate.
+- **After (one rule, three sites).** A segment whose program is not a listed reader is judged WHOLE and VERB-BLIND: every token from the program onward is offered to the boundary as a path candidate, under a head with no per-verb behaviour of its own. That is the form the containment face already used for LAUNCHER segments (`env cat <outside>`), promoted to the general rule — so the launcher special case disappears into it rather than being joined by a second one. Three sites carried the old assumption and all three now read the same way: the boundary walk of `classifyCompoundReadonlyDetailed` (which alone can answer for an in-root DENY row — the containment face deliberately drops the deny judge), `classifyOutOfRootReadGate` (which alone answers for a command the compound face refuses WHOLE), and the refused-command whitelist `refusedCommandExempt`, whose `!allow.has(head)` disjunct read an unlisted head as "a program that reads no path" and exempted it. Verb-blind is load-bearing in the safe direction: a per-verb table can silence a whole segment, skip a slot or move the base, and a program the deployment never declared must borrow none of that.
+- **Behaviour, for consumers — the RANGE, not a footnote.** Under BOTH doctrines a shell command whose program is not on the reader table now asks ONCE, mandated, when any of its words resolves outside the roots or onto the deny table, or is a word the walk could not read at all (an expansion, a subshell/glob/brace character, a `~` with no declared home). Every word, not only the path-shaped ones: a deny row names bare filenames (`.npmrc`, `.env`) and an expansion names what the text does not contain. A stored allow rule is disclosed as shadowed and does not clear it. **Under the default doctrine every one of these ran with ZERO asks before**, so on a headless deployment — no approver wired — the new card is a REFUSAL, not a prompt: `node -e "console.log(1)"`, `python3 -c "print(1)"`, `npm run "$SCRIPT"`, `npm install /opt/pkg`, `git -C /outside status`, `curl -o <outside> …`, `rm -rf /etc`, `touch <outside>`. The floor is unchanged and pinned: `npm test`, `timeout 300 npm test`, `env FOO=1 npm test`, `git status`, `npm run build`, `node scripts/build.mjs`, `python3 -m pytest tests/`, `docker ps`, `make`, `sort data.txt`, `curl https://…` keep their zero-ask verdict. **Stated over-fire** (the price of not carrying per-program option tables, which this file refuses to start doing): a token that is a WRITE target rather than a read gates too; a quoted literal that spells an out-of-root path gates even where the program only prints it (`printf '/etc/hosts'`); a program run by absolute path from outside the roots gates on its own path (`sudo /bin/cat <in-root>`, unchanged); an unfollowable base move now gates in its operand-less form as well (`pushd <anywhere>`); a refused-whole command carrying a line continuation, an escaped shell operator (`\>`), or a `#` alongside a quote character is a command the refused-command whitelist's positional splitter does not read the way bash does, and gets no exemption (one predicate, `whitelistReadsTheSameWords`, and one open design item behind all three — the exemption is a second hand-written parser beside the compound lexer, #753); and a non-canonical spelling of an in-root path (a symlinked `/var` → `/private/var` prefix) reads as out-of-root for an unlisted program exactly as it already did for a listed one. @server @cli: expect one more mandated-ask source on both tiers, and on a headless lane expect refusals where commands used to run — a probe that pinned zero asks for an unlisted program naming an absolute path outside the workspace, or carrying a `-e`/`-c` program body, reds. @test: the class criterion is a synthetic name (`zzunlisted`), not a tool list — a verification that enumerates names repeats the defect.
+- **Known residual, NOT closed here (a different class, pre-existing, and it is not keyed on the allowlist).** An option's ATTACHED payload is offered as a path candidate only when it is path-shaped, so a bare filename attached to a short or long option escapes the boundary walk for EVERY head, listed or not: `grep -f.npmrc`, `grep --file=.npmrc` and `awk -f.npmrc` are as silent as `base64 -i.npmrc`, while their separated (`-f .npmrc`) and path-shaped (`-i./.npmrc`) spellings mandate. Measured on this tree; filed rather than folded in, because the fix moves every head's candidate set and belongs with its own pins.
+- **Also.** `CompoundReadonlyVerdict.outOfRootRead` is now carried by a NAME-refused compound too (`rm -rf /etc`); the grant-offer reading is unchanged and remains the containment SENTENCE's, never the member's — a name-refused verdict's sentence is the name refusal, so no "allow reading from …" option is offered for it. The governed-agent example canonicalizes its temp workspace at the one minting point (a demo handing an unresolved workspace to an engine that canonicalizes its roots made every absolute operand read as out-of-root).
+- Pins: `test/backlog758-unlisted-reader-boundary.test.ts` (the real load path, two doctrines × out-of-root and in-root deny row × mandated-ask and zero-ask controls, on a synthetic unlisted name with real tools as corroboration; the over-fire floor at the seat face; the launcher promises unmoved; the third site's exempt/may-read sets with and without a wired deny judge; the `bash_readonly` face untouched; both mutation directions measured in the header), `test/backlog696-read-boundary-any-doctrine.test.ts` (appended unlisted-program rows on both seats), `test/backlog502-out-of-root-read-mandate.test.ts` / `test/rb412-bash-readonly-path-boundary.test.ts` / `test/rb474-glob-verdict-undecided.test.ts` (five cells re-pinned, each stating whether the old answer was a correct silence or the defect).
+
+## 7.17.2 — 2026-09-13
+
+### Fix — the directories the prompt advertises as writable feed the write gate's exemption through the request (#749; cli B-102; server S-261; @server @cli)
+- **Before.** Two seats judged one fact. The root fence's advertised-writable-directory seat (#691) admits the memory engine's write home — that admission is exactly what licenses the `# Memory` instruction's "write to it directly with the Write tool". The deployment's write gate (`createFsWriteGatePolicy`) knew nothing about it: the seat is minted inside prepare and its class is not exported, so under the manual-mode default (`defaultWrite: "ask"`, i.e. the `default` / `auto` / `acceptEdits` tiers) every write the prompt had just invited raised an approval card — an entry plus its index, two cards for one remembered fact. The only workaround open to a deployment was to copy the memory home into `exemptDirs`, making it a SECOND author of a list the fence already owns.
+- **After (one rule).** The seat is the single source and it travels on the call. `ToolCallRequest.advertisedWritableRoots` (optional, additive, read-only) carries the seat's admitted CANONICAL roots — the memory write home, the deployment's scratchpad — stamped by the Runner beside the live-cwd stamp at every adjudication seat and read live off the seat's own getter. `createFsWriteGatePolicy` checks it ahead of `exemptDirs` / `acceptDirs`: same verdict (allow, never asked), same containment comparison, same fold. The advertised roots are compared **frozen** — the seat admits only canonical spellings and `resolveKey`'s root fence compares its admitted roots exactly as they stand, so this gate must too. Re-resolving them per call would follow whatever the name points at AT ADJUDICATION TIME: replacing an admitted memory home with a symlink to the workspace (no race needed — any moment between two calls) would move the exemption domain onto the whole workspace and turn every ordinary source write from `ask` into `allow`. The CONFIGURED domains keep their per-call resolution, because they are deployment-authored text (a relative spelling, a path that did not exist at wiring time) rather than admitted keys. Nothing else changes — a sensitive-path `deny` composed alongside still outranks it, an unresolvable target still fails closed to `ask`, and an ABSENT or EMPTY list is NO exemption (never a wildcard). `FsWriteGatePolicyOptions` gains no option: the seat belongs to the request, not to the construction.
+- **The stamp is a frozen copy.** One helper mints the field at every station (`advertisedWritableRootsSeat`, beside the field's own declaration — the `callFaceSeat` shape), and it hands out `Object.freeze([...seat.roots])`. The seat's getter returns its own admission ledger and `combinePolicies` walks every layer with ONE request object, so a layer handed the live array could append to the very domain the gate exempts — for that call and every later one. `readonly` is a compile-time word; the freeze is the runtime one. (A layer REPLACING the whole field on the shared request is the pre-existing shape `cwd`, `budget` and `face` already live with; that belongs to the fold, not to this seat.)
+- **Stamp seats (five).** `prepare-ask-lane.ts` (the live gate), `prepare-park-ask.ts` (the parked call's projection re-adjudication), and `run-leg.ts` ×3 (the resume belts: the approver-edit recheck, the deny-narrowing lane, the persisted-rule lane). The last two are tightening-only lanes that never read the field; they are stamped so the field's own sentence — the Runner stamps it on every policy adjudication of the run — is true and cannot drift. `Prepared` carries the seat so the resume belts adjudicate against the same list the live gate used.
+- **For consumers.** @server: **zero changes to take this** — a run whose prompt advertises a memory home stops asking about writes into it, on your existing gate wiring. Your `exemptDirs: [scratchpadDir]` stays legal and correct; it is now redundant for any directory the seat already admits, and `isExempt` is untouched (it is still consulted after the domain checks). Do NOT add the memory home to `exemptDirs` — that is the second-writer shape this closes. @cli: the counter-control for B-102 is that an interactive `default`-tier run that stores a memory entry no longer raises a card for it; a probe that pinned that card reds.
+- Pins: `test/backlog749-advertised-roots-feed-write-gate.test.ts` (the gate unit: inside/outside/absent/empty/symlink-escape/unresolvable, an admitted root REPLACED by a symlink after admission not moving the domain, and the sensitive-path deny still outranking; the Runner end-to-end on a real memory wiring: the memory write lands with zero asks while an ordinary in-root write still asks exactly once, with the stamp positively observed on the adjudicated request; the structural invariant that every Runner line stamping `cwd` also stamps the seat, five stations, all through the one helper; the helper's frozen copy, and a greedy policy layer composed ahead of the gate failing to widen it).
+
+### Fix — a here-document or here-string is a reader's stdin, not a file: the read-evidence scan counts operands (#751; test [7111]; @cli @server)
+- **Before.** The read-evidence scan behind the shell read boundary (the rule that a command the grammar refused whole is mandated only when it may read) counted a listed path reader by NAME: `cat <<'EOF' > out.txt` — the everyday heredoc write — and `wc -l <<< "x"` raised a mandated ask under the default doctrine while `tr … <<< hello` did not (`tr` reads no path).
+- **After (one rule, a whitelist).** A refused command is exempt from the mandate only when every part of it is a shape the scan fully understands and none of them reads a file outside the walk's reach — everything else, including any token the scan does not understand, is read evidence. Exempt shapes, per segment: a program that reads no path (`echo`, `tee out.txt <<EOF`, `python3 - <<'EOF'`, an unlisted program); `cat` / `wc` with a payload-free flag cluster whose input is a here-document, a here-string or a literal in-root stdin file (`cat <<'EOF' > out.txt`, `wc -l <<< "x"`, `cat < secret`); a directory change (after which every relative stdin literal in the command is unjudged). A substitution body (`$(…)`, backticks, `<(…)`) is judged on its own — green under the compound walk (`echo $(cat src/a)`, `VAR=$(cat src/a)`) or exempt under the whitelist (`echo $(date)`) — and a here-document body is text. Mandated: a stdin source outside the root, deny-listed, expanded anywhere in its spelling or relative after a `cd`/`pushd` (`cat < /etc/passwd`, `cat < .${K}rc`, `pushd /etc; cat < hosts`); any listed reader other than `cat`/`wc` fed by a here-string (`sed -e'r/etc/passwd' <<< x`, `grep -f x <<< y`); an option that may carry a file (`cat -`, `sed -fsecret`); a reader inside a substitution that reads outside the root (`echo x$(cat /etc/hosts)`); a re-entry (`bash -c "$CMD"`, `eval`); an unterminated here-document. A shell re-entry program (`sh -c …`, `bash script.sh`, `eval …`, `source x`, `. x`), bare or behind a launcher, runs its argument as commands the walk never sees: refused whole and mandated on both seats (the 7.17.0–7.17.1 walk read it as an unlisted program and the boundary seat vouched it). `refusedCommandMayRead(command, allow, boundary)` is the complement of `refusedCommandExempt`. **Residual, disclosed (#753):** the exemption is a hand-written parser beside the compound walk's lexer; five adversarial rounds closed twenty-one corners (heredoc delimiters and bodies, quoting, substitutions, launchers, moved bases, option payloads); the class is open by construction until the whitelist runs over the compound lexer itself.
+- Pins: `test/backlog696-read-boundary-any-doctrine.test.ts` (eight non-objection heredoc / here-string / in-root stdin forms; six mandated stdin forms).
+
 ## 7.17.1 — 2026-09-13
 
 ### Narrowing — the shell read boundary never vouches a read it did not judge (#737; test [7074] G12 / G14; @server @cli @test)

package/dist/core/fs-write-gate-policy.js

@@ -31,6 +31,10 @@ export function createFsWriteGatePolicy(opts) {
             if (!canon.ok) {
                 return ask(`write to "${path}" requires approval: its real target could not be resolved (${canon.message})${advisory}`);
             }
+            for (const root of req.advertisedWritableRoots ?? []) {
+                if (isWithin(root, canon.key))
+                    return { action: "allow" };
+            }
             for (const dirs of [exemptDirs, acceptDirs]) {
                 if (!dirs)
                     continue;

package/dist/core/runner/contracts.d.ts

@@ -291,6 +291,8 @@ export interface Prepared {
     /** The per-task logical cwd ref when a real shell is mounted (else undefined). The Runner
      *  reads `cwdRef.current` after each tool to detect a `cd` move and emit `workspace_changed`. */
     cwdRef?: CwdRef;
+    /** The run's advertised-writable-directory seat (present with hands): `roots` is what the prompt advertised as writable and the fence admitted. Read live wherever a policy is adjudicated off a resumed leg, so the write gate's exemption domain is that same list. */
+    advertisedWritableDirs?: Pick<import("./advertised-writable-dirs.js").AdvertisedWritableDirs, "roots">;
     /** The ACTIVE EnterWorktree session ref (mounted with the worktree tools; undefined without
      *  real write hands). runtask's settle write reads `current` for the workspace-state entry. */
     worktreeSessionRef?: {

package/dist/core/runner/prepare-ask-lane.d.ts

@@ -18,6 +18,7 @@
  * the orchestrator grows no branch.
  */
 import type { AgentTool } from "../../internal/harness.js";
+import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 import type { AutoModeDenialTracker } from "../auto-mode.js";
 import { type Hooks } from "../hooks.js";
 import { type OnAsk, type ToolCallRequest, type ToolPolicy } from "../tool-policy.js";
@@ -44,6 +45,8 @@ export interface PrepareAskLaneInput {
     /** borrowed-readonly — the hand's live tracked cwd, or undefined (hands-less). Read per call at RUN time (`current`),
      *  never captured: the fs hand tools resolve their relative paths against this very ref. Not written here. */
     handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the run's advertised-writable-directory seat, or undefined (hands-less / nothing advertised). `roots` is read at RUN time, never captured: it is the fence's own admitted list and the write gate's exemption domain must be that same list. Not written here. */
+    advertisedWritableDirs: Pick<AdvertisedWritableDirs, "roots"> | undefined;
     /** borrowed-readonly — the shared mount roster; read at RUN time by the approval-preview projection (alias-aware
      *  lookup over whatever the roster holds when the ask is minted). Never mutated here. */
     tools: readonly AgentTool[];

package/dist/core/runner/prepare-ask-lane.js

@@ -1,6 +1,6 @@
 import { primaryActivityArg } from "../arg-summary.js";
 import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
-import { isLiveApproverSeat, resolveAsk } from "../tool-policy.js";
+import { advertisedWritableRootsSeat, isLiveApproverSeat, resolveAsk } from "../tool-policy.js";
 import { composeCallSignal, raceAbort } from "./abort-race.js";
 import { gateAskCarry, lateAskSettlementObserver } from "./denial-limit-arms.js";
 import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
@@ -55,14 +55,14 @@ function resolveApprovalPreview(tools, toolName, args) {
     }
 }
 export function prepareAskLane(input) {
-    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash } = input;
+    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash } = input;
     if (!gateMachineryActive)
         return { askLane: undefined };
     const composedCallSignal = (callSignal) => composeCallSignal(abortController.signal, callSignal);
     const adjudicate = effectivePolicy
         ? (req, callSignal) => {
             const signal = composedCallSignal(callSignal);
-            return raceAbort(Promise.resolve(effectivePolicy.check({ ...req, budget: budgetSnapshot, ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}) }, signal)), signal, () => ({
+            return raceAbort(Promise.resolve(effectivePolicy.check({ ...req, budget: budgetSnapshot, ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}), ...advertisedWritableRootsSeat(advertisedWritableDirs) }, signal)), signal, () => ({
                 action: "deny",
                 message: "policy check aborted (task timed out or cancelled)",
             }));

package/dist/core/runner/prepare-park-ask.d.ts

@@ -27,6 +27,7 @@ import { type OnAsk, type ToolCallRequest, type ToolPolicy } from "../tool-polic
 import { type ToolResultStore } from "../tool-result-store.js";
 import type { RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskSpec } from "../types.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 import { type ContentAskBinding } from "./content-ask-bindings.js";
 import type { AskLane, ParkAsk, Prepared, SuspendSaga } from "./contracts.js";
 import type { createRuleOffersOf } from "./permission-rule-lanes.js";
@@ -92,6 +93,8 @@ export interface PrepareParkAskInput {
     /** borrowed-readonly — the hand's live tracked cwd, or undefined; `current` is read at park time for the re-adjudication.
      *  Not written here. */
     handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the SAME seat the live gate stamps from ({@link import("./prepare-ask-lane.js").PrepareAskLaneInput.advertisedWritableDirs}): a parked call's projection re-adjudication asks one question about one call, so it must ask it against the same admitted list. Read at park time, not written here. */
+    advertisedWritableDirs: Pick<AdvertisedWritableDirs, "roots"> | undefined;
     /** borrowed-readonly — the run's offload store, or undefined (a volatile store holding results refuses the park). */
     offloadStore: ToolResultStore | undefined;
     /** borrowed-readonly — the per-task owned env, or undefined (a non-remote per-task env refuses the park). Never destroyed. */

package/dist/core/runner/prepare-park-ask.js

@@ -7,7 +7,7 @@ import { BINDING_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtF
 import { pauseOf } from "../pause-registry.js";
 import { askCarryRowMembers } from "../hooks.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { isLiveApproverSeat, carriesBidiControls, describeThrown, refuseOutOfContractDecision, tryCloneArgs } from "../tool-policy.js";
+import { advertisedWritableRootsSeat, isLiveApproverSeat, carriesBidiControls, describeThrown, refuseOutOfContractDecision, tryCloneArgs } from "../tool-policy.js";
 import { InMemoryToolResultStore, ScopedToolResultStore, isVolatileOffloadStore } from "../tool-result-store.js";
 import { raceAbort, raceSettlementAgainstSignal } from "./abort-race.js";
 import { checkpointScopeOf } from "./checkpoint-scope.js";
@@ -22,7 +22,7 @@ class ParkRefusal extends Error {
     }
 }
 export function prepareParkAsk(input) {
-    const { askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef } = input;
+    const { askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, advertisedWritableDirs, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef } = input;
     if (askLane === undefined || saga === undefined)
         return { parkAsk: undefined };
     const { composedCallSignal, approvalPreviewOf } = askLane;
@@ -160,6 +160,7 @@ export function prepareParkAsk(input) {
                         budget: budgetSnapshot,
                         ...callFaceSeat(req.face),
                         ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}),
+                        ...advertisedWritableRootsSeat(advertisedWritableDirs),
                     }, cutSignal)), cutSignal);
                     if (reprojectedRaced.tag === "aborted")
                         return undefined;

package/dist/core/runner/prepare-task.js

@@ -690,16 +690,16 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 return undefined;
             });
         }
-        const { askLane } = prepareAskLane({ gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash });
+        const { askLane } = prepareAskLane({ gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash });
         const { saga } = prepareSuspendSaga({ gateMachineryActive, abortController, harness, checkpointStore, deps, sessionId, hostTaskId, taskScope, liveSpendRef, resume, nestedStats, internals, activeTools, outputRef, readFileStateForCheckpoint, faceCheckpointSection, reminderMark, handsCwdRef, worktreeSessionRef, inheritedParentConstraints, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, autoModeIntent, inheritedAdmittedOrgScopes, ownOrgVerdictRef, orgGovernedProvenance, announcedListingsRef, gitStatusRef, hookIdentity, placementRootResolved, externalContentTargetActive, remoteEnvFailures, memoryEngineSession, suspendLoopRef, ownedEnv, incompleteSuspendAdapter });
         const { suspendForResource, suspendForPlatformLimit, suspendForReview } = prepareBoundaryParks({ saga, spec, checkpointStore, abortController, harness, session, sessions, sessionId, deps, priorLedger, maxSlices, maxSuspends, resourceTotal, priorSuspendCount, suspendChainBase, humanReviewRef, liveSpendRef, now, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, pausedRef, remoteEnvFailures, resourceSuspendEligible, durableSuspendInfraReady, incompleteSuspendAdapter });
-        const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef });
+        const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, advertisedWritableDirs, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef });
         prepareGateStations({ askLane, parkAsk, tools, toolRosterDeltas: rosterSeat, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedTools, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash });
         const { microCompact, charsPerToken } = prepareContextLane({ model, deps, sessionId, runId, hostTaskId, offloadStore, microCompactKnob, harness, batchHaltRef, gitStatusRef, requestLossyRef, trimPressureRef });
         const preparedHolder = {};
         const { cacheBreakDetector, cacheFingerprint, promptOverheadTokens, readTaskFile, normalizeAttachmentPath, isDedupStubResult, recentlyReadFiles, onCompactionApplied, detectExternalChanges, listBackgroundTasks, centerCompactionCandidate, effectiveReadFaceObserved, effectiveReadDenyObserved } = prepareTurnWiring({ deps, systemPromptSeat, harnessTools, fpRef, model, epochArtifactDigestForSnapshot, promptProfile, fableMitigations, systemBlocks, thinking, spec, sessionId, turnSnapshotRef, promptManifest, charsPerToken, handsEnabled, executionEnv, attachmentRootCanonical, additionalRootsCanonical, additionalReadRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, readFileStateForCheckpoint, denyNarrowingPolicy, abortController, hostTaskId, taskScope, buildAssembleInputs, centerAdoptionRef, harnessRef, epochDeclaredSections, carrierReadFace, readDenyAdditionsNormalized, preparedHolder });
         await onceLedger.settle(session, announcedListingsRef);
-        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(permissionRuleLane !== undefined ? { persistedRuleLane: permissionRuleLane } : {}), ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, workCutRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolRoster, toolRosterDeltas: rosterSeat, structuredProjector, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(advertisedWritableDirs !== undefined ? { advertisedWritableDirs } : {}), ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(permissionRuleLane !== undefined ? { persistedRuleLane: permissionRuleLane } : {}), ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, workCutRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolRoster, toolRosterDeltas: rosterSeat, structuredProjector, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         rollback.commit();
         const prepared = buildPrepared();
         preparedHolder.current = prepared;

package/dist/core/runner/run-leg.js

@@ -10,7 +10,7 @@ import { applyPersistedTightening, disclosedRuleSet } from "../persisted-rule-ar
 import { computeCostMicroUsd } from "../pricing.js";
 import { mintSystemReminder } from "../reminder-mint.js";
 import { hasDestroy } from "../remote-env.js";
-import { refuseOutOfContractDecision } from "../tool-policy.js";
+import { advertisedWritableRootsSeat, refuseOutOfContractDecision } from "../tool-policy.js";
 import { callFaceSeat, judgeParkedToolIdentity, rosterEntryNamed, toolCallFaceOf } from "../tool-roster.js";
 import { deliverEngineNotice } from "../types.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY, sanitizeUntrustedText } from "../untrusted-text.js";
@@ -571,6 +571,7 @@ async function resolvePendingCall(runner, prepared, resume, emit, emitCommitted,
             toolCallId: pendingAction.toolCallId,
             budget: beltBudget,
             ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
+            ...advertisedWritableRootsSeat(prepared.advertisedWritableDirs),
             ...callFaceSeat(toolCallFaceOf(prepared.toolRosterDeltas.current, pendingAction.toolName)),
         }, prepared.abortController.signal));
         const beltUnsafe = rechecked.action === "deny" ||
@@ -632,6 +633,7 @@ async function resolvePendingCall(runner, prepared, resume, emit, emitCommitted,
             ...callFaceSeat(toolCallFaceOf(prepared.toolRosterDeltas.current, pendingAction.toolName)),
             budget: beltBudget,
             ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
+            ...advertisedWritableRootsSeat(prepared.advertisedWritableDirs),
         }, prepared.abortController.signal));
         if (narrowed.action === "deny") {
             const narrowedDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" is now denied by a session rule and was not executed${narrowed.message ? `: ${narrowed.message}` : ""}.`, prepared.reminderMark);
@@ -651,6 +653,7 @@ async function resolvePendingCall(runner, prepared, resume, emit, emitCommitted,
             ...callFaceSeat(toolCallFaceOf(prepared.toolRosterDeltas.current, pendingAction.toolName)),
             budget: beltBudget,
             ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
+            ...advertisedWritableRootsSeat(prepared.advertisedWritableDirs),
         }))
             .then((answer) => normalizePersistedRuleHit(answer)), unreadable, { signal: prepared.abortController.signal, timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
         const tightened = applyPersistedTightening({ action: "allow" }, read);

package/dist/core/tool-policy.d.ts

@@ -58,6 +58,30 @@ export interface ToolCallRequest {
      * window — at that declaration, not here.
      */
     cwd?: string;
+    /**
+     * The CANONICAL directories THIS RUN'S PROMPT ADVERTISES AS WRITABLE — the admitted list of the root
+     * fence's advertised-writable-directory seat (the memory engine's write home, the deployment's
+     * scratchpad), in admission order, deduplicated. Stamped by the Runner on every policy adjudication of
+     * the run, read live at adjudication time (a directory admitted by a later phase is on the list the
+     * next call carries).
+     *
+     * WHY IT EXISTS: the fence and the write gate were judging one fact twice. The prompt tells the model
+     * "write to it directly with the Write tool" and the fence opens the hole for exactly the directories
+     * this list names — but a deployment-authored write gate knew nothing of them, so every advertised
+     * write still asked (a memory entry plus its index = two questions the person was told would not be
+     * asked). Reading THIS field makes the gate's exemption domain the same list the fence admitted,
+     * instead of a second copy the deployment maintains by hand.
+     *
+     * A containment gate reads it EXACTLY as {@link import("./fs-write-gate-policy.js").FsWriteGatePolicyOptions.exemptDirs}:
+     * a covered write whose canonical target lands inside one of these directories is allowed and not
+     * asked. It grants nothing else — a DENY composed alongside (sensitive-path, an org rule) still
+     * outranks it under the deny > ask > allow fold, and an unresolvable target still fails closed.
+     *
+     * ABSENT outside a Runner, or when the run has no hands, or when nothing was advertised. Absence is NO
+     * exemption, never a wildcard (an empty list reads the same). Read-only — a policy cannot advertise a
+     * directory by writing one back.
+     */
+    advertisedWritableRoots?: readonly string[];
     /**
      * design/80 D-E-core: read-only per-run budget snapshot so a STATELESS policy can self-limit against
      * state that survives suspend/resume (a fresh in-memory counter would reset every leg — the supervisor
@@ -104,6 +128,23 @@ export interface ToolCallRequest {
 /** `read_only` (#619): the shell tool's command was PROVABLY read-only by the engine's transcribed upstream
  *  tables (`readOnlyShellVerdict`) and the allow layer let it run without a question — after every
  *  deny/ask lane and the person's own allow rules, never over a mandated ask. */
+/**
+ * Stamp {@link ToolCallRequest.advertisedWritableRoots} from the run's advertised-writable-directory seat
+ * — the ONE place the seat becomes a request field, so every adjudication station stamps it alike (the
+ * `callFaceSeat` shape).
+ *
+ * The list is COPIED AND FROZEN here, and that is load-bearing rather than tidy. The seat's `roots` getter
+ * hands back its own admission ledger, and {@link combinePolicies} walks every layer with ONE request
+ * object: a layer handed the live array could append to the very domain the write gate exempts, widening
+ * it for that call and for every later one. `readonly` is a compile-time word; this is the runtime one.
+ * (What a frozen array does not close is a layer REPLACING the whole field on the shared request — the
+ * pre-existing shape that `cwd`, `budget` and `face` live with; it belongs to the fold, not to this seat.)
+ */
+export declare function advertisedWritableRootsSeat(seat: {
+    readonly roots: readonly string[];
+} | undefined): {
+    advertisedWritableRoots?: readonly string[];
+};
 declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 export type DecisionReason = (typeof DECISION_REASONS)[number];
 /** Carry every engine attestation (settlement, classifier cause) from a decision onto a reconstruction of it — the

package/dist/core/tool-policy.js

@@ -10,6 +10,9 @@ import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./unt
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
 import { protocolOf } from "./protocol-table.js";
 import { isAbsoluteForFamily, isAbsolutePathForm, joinForFamily, normalizeAbsPathLexically, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
+export function advertisedWritableRootsSeat(seat) {
+    return seat === undefined ? {} : { advertisedWritableRoots: Object.freeze([...seat.roots]) };
+}
 const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -389,13 +389,15 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  *  has no filesystem and stays lexical, and a REMOTE env keeps the lexical behaviour (its
  *  `canonicalPath` is an RPC per candidate). */
 export declare function resolveOperandLexically(base: string | undefined, operand: string, homeDir: string | undefined): string | undefined;
-/** Whether a command the grammar gate REFUSED WHOLE carries evidence that it may READ: a listed reader or a shell
- *  re-entry program anywhere in it, a substitution where a program name stands (`$C /etc/passwd`), or a stdin
- *  redirection from a non-literal target (`cat < $F`). The out-of-root and base-mover readings over its literal path
- *  tokens are the containment gate's, asked separately. A refused command with none of these — a write through a
- *  redirection (`echo hi > out.txt`), a function definition — names no read for the boundary to mandate: the syntax
- *  refusal stays the classify seat's own plain ask. */
-export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>): boolean;
+/** Whether a command the grammar gate REFUSED WHOLE may READ a file the boundary never judged. The answer is the
+ *  complement of a WHITELIST: the command is exempt only when every part of it is a shape the scan fully understands
+ *  and none of those shapes reads a file outside the walk's reach — everything else is read evidence, so a token the
+ *  scan does not understand mandates rather than passes. Exempt shapes, per segment: a program that reads no path
+ *  (`echo`, `python3 -`, `tee out.txt`, an unlisted program); `cat` / `wc` with payload-free flags whose input is a
+ *  here-document, a here-string or a literal in-root stdin file; a directory change (which then makes every relative
+ *  stdin literal in the command unjudged). A substitution body (`$(…)`, backticks, `<(…)`) is judged on its own: green
+ *  under the compound walk, or exempt under this whitelist; a here-document body is text, not commands. */
+export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): boolean;
 /**
  * The home directory's VARIABLE spellings, SUBSTITUTED with the declared value before a read face segments the
  * command: `$HOME` / `${HOME}` at the START of a word (an empty quote pair before it included), unquoted or
@@ -491,13 +493,16 @@ export declare const COMMAND_LAUNCHERS_FOR_TEST: ReadonlySet<string>;
  * reason for a demotion has one predicate to read.
  *
  * What it judges and what it does not:
- *  · SEGMENTS whose PROGRAM is in `allow` — the deployment's own read-command table, the analogue of
- *    the reference implementation's path-restricted command list. The program is read after the two
- *    decorations the shell itself strips before choosing it (leading `NAME=value` assignments, a path
- *    prefix), so `/bin/cat` is judged as `cat`: recognizing readers by their literal spelling alone let
- *    a rule the persisted grammar admits (`Bash(/bin/cat:*)`) carry the exact read this gate exists for.
- *    Every other segment is skipped, so this face never invents a path judgement for a verb the
- *    deployment never declared readable.
+ *  · EVERY segment, under one of two readings. A segment whose PROGRAM is in `allow` — the deployment's
+ *    own read-command table, the analogue of the reference implementation's path-restricted command
+ *    list — is read with that verb's own slots (a pattern operand, a recursive form). The program is
+ *    read after the two decorations the shell itself strips before choosing it (leading `NAME=value`
+ *    assignments, a path prefix), so `/bin/cat` is judged as `cat`: recognizing readers by their literal
+ *    spelling alone let a rule the persisted grammar admits (`Bash(/bin/cat:*)`) carry the exact read
+ *    this gate exists for. Every OTHER segment is judged whole and verb-blind — its tokens are offered
+ *    as path candidates under a head with no per-verb behaviour — because a program not on the table is
+ *    not a program known to read nothing: skipping it made the gate silent for every reader the
+ *    deployment had not enumerated, which is the one thing a name table cannot enumerate.
  *  · `cd` is judged whether or not the deployment listed it, because the walk MODELS it (it threads the
  *    base across segments) and dropping it would place every later relative operand against a base bash
  *    has already left. A move the walk cannot model (`pushd`/`popd`) is not silently tolerated either —

package/dist/tools/fs/bash-readonly-classifier.js

@@ -260,37 +260,365 @@ function tokensMoveBase(toks, allow) {
     return unwrapped.kind === "refused" || (unwrapped.kind === "reader" && unwrapped.head === "cd");
 }
 const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi)?sh|eval|source|\.)$/;
-export function refusedCommandMayRead(command, allow) {
-    for (const m of command.matchAll(/(?<![<>&\d])<(?![<&])\s*(\S*)/g)) {
-        const target = (m[1] ?? "").replace(/^["']+|["']+$/g, "");
-        if (target === "" || /^[$`(~]/.test(target))
-            return true;
+export function refusedCommandMayRead(command, allow, boundary) {
+    return !refusedCommandExempt(command, allow, boundary, 0);
+}
+const STDIN_ONLY_READER_FLAGS = new Map([
+    ["cat", /^-[AbeEnstTuv]+$/],
+    ["wc", /^-[clmwL]+$/],
+]);
+const SUBSTITUTION_PLACEHOLDER = "\u0000subst";
+function withoutHeredocBodies(text) {
+    const lines = text.split("\n");
+    const out = [];
+    const expandedBodies = [];
+    let terminator;
+    let expanded = false;
+    let body = [];
+    for (const line of lines) {
+        if (terminator !== undefined) {
+            if (line.trim() === terminator) {
+                if (expanded)
+                    expandedBodies.push(body.join("\n"));
+                terminator = undefined;
+                body = [];
+            }
+            else
+                body.push(line);
+            continue;
+        }
+        out.push(line);
+        const header = heredocHeaderOf(line);
+        if (header === null)
+            return undefined;
+        if (header !== undefined) {
+            terminator = header.word;
+            expanded = !header.quoted;
+        }
+    }
+    return terminator === undefined ? { outer: out.join("\n"), expandedBodies } : undefined;
+}
+function heredocHeaderOf(line) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "\\" && !inSingle) {
+            i++;
+            continue;
+        }
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (inSingle || inDouble)
+            continue;
+        if (ch === "#")
+            return undefined;
+        if (ch === "<" && line[i + 1] === "<") {
+            if (line[i + 2] === "<") {
+                i += 2;
+                continue;
+            }
+            const m = /^<<-?\s*([^\s;|&<>()]+)/.exec(line.slice(i));
+            if (m === null)
+                return null;
+            const word = m[1];
+            if (/[$`]/.test(word))
+                return null;
+            const delimiter = word.replace(/\\(.)/g, "$1").replace(/["']/g, "");
+            if (delimiter === "")
+                return null;
+            return { word: delimiter, quoted: /["'\\]/.test(word) };
+        }
+    }
+    return undefined;
+}
+function splitSubstitutions(text, quotesAreLiteral = false) {
+    let outer = "";
+    const bodies = [];
+    let i = 0;
+    let inSingle = false;
+    let inDouble = false;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === "\\" && !inSingle) {
+            outer += text.slice(i, i + 2);
+            i += 2;
+            continue;
+        }
+        if (ch === "'" && !inDouble && !quotesAreLiteral) {
+            inSingle = !inSingle;
+            outer += ch;
+            i++;
+            continue;
+        }
+        if (ch === '"' && !inSingle && !quotesAreLiteral) {
+            inDouble = !inDouble;
+            outer += ch;
+            i++;
+            continue;
+        }
+        if (inSingle) {
+            outer += ch;
+            i++;
+            continue;
+        }
+        if (ch === "`") {
+            const close = text.indexOf("`", i + 1);
+            if (close < 0)
+                return undefined;
+            bodies.push(text.slice(i + 1, close));
+            outer += SUBSTITUTION_PLACEHOLDER;
+            i = close + 1;
+            continue;
+        }
+        if ((ch === "$" || ch === "<" || ch === ">") && text[i + 1] === "(") {
+            let depth = 0;
+            let j = i + 1;
+            let quoted;
+            for (; j < text.length; j++) {
+                const c = text[j];
+                if (quoted !== undefined) {
+                    if (c === "\\" && quoted === '"')
+                        j++;
+                    else if (c === quoted)
+                        quoted = undefined;
+                    continue;
+                }
+                if (c === "'" || c === '"') {
+                    quoted = c;
+                    continue;
+                }
+                if (c === "(")
+                    depth++;
+                else if (c === ")") {
+                    depth--;
+                    if (depth === 0)
+                        break;
+                }
+            }
+            if (j >= text.length)
+                return undefined;
+            bodies.push(text.slice(i + 2, j));
+            outer += SUBSTITUTION_PLACEHOLDER;
+            i = j + 1;
+            continue;
+        }
+        outer += ch;
+        i++;
+    }
+    if (inSingle)
+        return undefined;
+    return { outer, bodies };
+}
+function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside = false) {
+    if (depth > 4)
+        return false;
+    const stripped = withoutHeredocBodies(command);
+    if (stripped === undefined)
+        return false;
+    if (!whitelistReadsTheSameWords(command, stripped.outer))
+        return false;
+    const split = splitSubstitutions(stripped.outer);
+    if (split === undefined)
+        return false;
+    const bodies = [...split.bodies];
+    for (const expandedBody of stripped.expandedBodies) {
+        const inner = splitSubstitutions(expandedBody, true);
+        if (inner === undefined)
+            return false;
+        bodies.push(...inner.bodies);
     }
     const fold = (w) => w.replace(/\\(.)/g, "$1").replace(/["']/g, "");
     const programOf = (w) => {
-        const inner = fold(w).replace(/^[$`(]+|[)`]+$/g, "");
+        const inner = fold(w);
         return inner.includes("/") ? inner.slice(inner.lastIndexOf("/") + 1) : inner;
     };
-    for (const word of command.split(/[\s<>|;&()]+/)) {
-        const base = programOf(word);
-        if (base === "")
+    const segments = split.outer.split(/\n|;|&&|\|\||\||(?<![>&\d])&(?![>&])/).map((segment) => {
+        const toks = [];
+        for (const word of segment.trim().split(/\s+/)) {
+            let rest = word;
+            while (rest !== "") {
+                const m = /^(\d*(?:<<<|<<|<|>>|>)(?:&\d*)?|&>>?)(.*)$/.exec(rest);
+                if (m !== null) {
+                    toks.push(m[1].replace(/^\d+/, ""));
+                    rest = m[2];
+                    continue;
+                }
+                const at = rest.search(/\d*(?:<<<|<<|<|>>|>)|&>/);
+                if (at <= 0) {
+                    toks.push(rest);
+                    break;
+                }
+                toks.push(rest.slice(0, at));
+                rest = rest.slice(at);
+            }
+        }
+        const commentAt = toks.findIndex((t) => t.startsWith("#"));
+        return (commentAt >= 0 ? toks.slice(0, commentAt) : toks)
+            .map((t) => (/^[A-Za-z_][A-Za-z0-9_]*\(\)$/.test(t) ? "{" : t.replace(/^[({]+|[)}]+$/g, "")))
+            .filter((t) => t !== "");
+    });
+    const headIndex = (toks) => {
+        let i = 0;
+        while (i < toks.length) {
+            const w = fold(toks[i]);
+            if (ASSIGNMENT_WORD.test(w) || SHELL_CONTROL_PREFIXES.has(w) || SHELL_BLOCK_WORDS.has(w) || /^[{}]$/.test(w)) {
+                i++;
+                continue;
+            }
+            if (/^(?:<<<|<<|<|>>?|&>>?)$/.test(w)) {
+                i += 2;
+                continue;
+            }
+            if (/^(?:>>?|<)&\d*$/.test(w)) {
+                i++;
+                continue;
+            }
+            break;
+        }
+        return i;
+    };
+    const runProgramOf = (toks, i) => {
+        let head = programOf(toks[i] ?? "");
+        let guard = 0;
+        while (COMMAND_LAUNCHERS.has(head) && guard++ < 8) {
+            let j = i + 1;
+            while (j < toks.length && (ASSIGNMENT_WORD.test(fold(toks[j])) || /^\d+[smhd]?$/.test(fold(toks[j]))))
+                j++;
+            const next = toks[j];
+            if (next === undefined || fold(next).startsWith("-"))
+                return undefined;
+            i = j;
+            head = programOf(next);
+        }
+        return head;
+    };
+    const baseMoved = baseMovedOutside ||
+        segments.some((toks) => {
+            const i = headIndex(toks);
+            if (i >= toks.length)
+                return false;
+            const head = runProgramOf(toks, i);
+            return head === undefined || head === "cd" || UNMODELLED_BASE_MOVERS.has(head);
+        });
+    for (const body of bodies) {
+        const walked = classifyCompoundReadonlyDetailed(body, allow, boundary);
+        const fullyGreen = !baseMoved && walked.reason === undefined && walked.readDenied !== true && walked.outOfRootRead !== true && walked.refusedWhole !== true &&
+            (walked.undecidedPaths?.length ?? 0) === 0 && (walked.unresolvedOperands?.length ?? 0) === 0 && (walked.recursiveReadPaths?.length ?? 0) === 0;
+        if (fullyGreen)
             continue;
-        if ((allow.has(base) && !NO_PATH_OPERAND_COMMANDS.has(base)) || SHELL_REENTRY_PROGRAM_RE.test(base))
-            return true;
+        if (!refusedCommandExempt(body, allow, boundary, depth + 1, baseMoved))
+            return false;
     }
-    for (const segment of command.split(/\n|;|&&|\|\||\||(?<![>&\d])&(?![>&])/)) {
-        for (const raw of segment.trim().split(/\s+/)) {
-            const word = fold(raw);
-            if (word === "")
+    const stdinFileJudgedInside = (raw) => {
+        if (raw === undefined || raw === "" || raw.includes(SUBSTITUTION_PLACEHOLDER) || UNREADABLE_WHITELIST_WORD.test(raw))
+            return false;
+        if (boundary === undefined || baseMoved)
+            return false;
+        const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], fold(raw), boundary.homeDir);
+        if (resolved === undefined || boundary.denyMatch?.(resolved) != null)
+            return false;
+        return withinAnyRoot(boundary.roots, resolved);
+    };
+    const unlistedSegmentJudgedInside = (toks, from) => {
+        if (boundary === undefined)
+            return true;
+        let endOfOptions = false;
+        for (let j = from; j < toks.length; j++) {
+            const t = toks[j];
+            if (t === "<<<" || t === "<<" || t === "<") {
+                j++;
                 continue;
-            if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word) || SHELL_CONTROL_PREFIXES.has(word) || SHELL_BLOCK_WORDS.has(word) || word === "{" || word === "}" || COMMAND_LAUNCHERS.has(programOf(word)) || word.startsWith("-"))
+            }
+            if (/^(?:>>?|&>>?)$/.test(t)) {
+                j++;
                 continue;
-            if (/^[$`(]/.test(word))
-                return true;
-            break;
+            }
+            if (/^(?:>>?|<)&\d*$/.test(t))
+                continue;
+            const word = fold(t);
+            if (j > from && !endOfOptions && word === "--") {
+                endOfOptions = true;
+                continue;
+            }
+            if (j === from && !isPathShapedToken(word)) {
+                if (UNREADABLE_WHITELIST_WORD.test(word) || word.includes(SUBSTITUTION_PLACEHOLDER))
+                    return false;
+                continue;
+            }
+            const optionShaped = !endOfOptions && word.startsWith("-") && word !== "-";
+            const candidates = optionShaped ? [...attachedOptionPayloads(word), ...(isPathShapedToken(word) ? [word] : [])] : [word];
+            for (const candidate of candidates) {
+                if (!stdinFileJudgedInside(candidate))
+                    return false;
+            }
+        }
+        return true;
+    };
+    for (const toks of segments) {
+        for (let j = 0; j < toks.length; j++)
+            if (toks[j] === "<" && !stdinFileJudgedInside(toks[j + 1]))
+                return false;
+        let i = headIndex(toks);
+        if (i >= toks.length)
+            continue;
+        const headWord = fold(toks[i]);
+        if (headWord.includes(SUBSTITUTION_PLACEHOLDER) || /[$`]/.test(headWord))
+            return false;
+        let head = programOf(headWord);
+        if (COMMAND_LAUNCHERS.has(head)) {
+            const wrapped = runProgramOf(toks, i);
+            if (wrapped === undefined || /[$`]/.test(wrapped) || SHELL_REENTRY_PROGRAM_RE.test(wrapped))
+                return false;
+            const unwrapped = unwrapLauncher(toks.slice(i).map(fold), allow);
+            if (unwrapped.kind === "refused")
+                return false;
+            if (unwrapped.kind === "unlisted") {
+                if (!unlistedSegmentJudgedInside(toks, i))
+                    return false;
+                continue;
+            }
+            head = unwrapped.head;
+            i += unwrapped.index;
+        }
+        if (SHELL_REENTRY_PROGRAM_RE.test(head))
+            return false;
+        if (head === "cd" || UNMODELLED_BASE_MOVERS.has(head))
+            continue;
+        if (!allow.has(head)) {
+            if (!unlistedSegmentJudgedInside(toks, i))
+                return false;
+            continue;
+        }
+        if (NO_PATH_OPERAND_COMMANDS.has(head))
+            continue;
+        const flags = STDIN_ONLY_READER_FLAGS.get(head);
+        if (flags === undefined)
+            return false;
+        for (let j = i + 1; j < toks.length; j++) {
+            const t = toks[j];
+            if (t === "<<<" || t === "<<" || t === "<") {
+                j++;
+                continue;
+            }
+            if (/^(?:>>?|&>>?)$/.test(t)) {
+                j++;
+                continue;
+            }
+            if (/^(?:>>?|<)&\d*$/.test(t))
+                continue;
+            if (flags.test(fold(t)))
+                continue;
+            return false;
         }
     }
-    return false;
+    return true;
 }
 function unwrapLauncher(folded, allow) {
     for (let i = 1; i < folded.length; i++) {
@@ -302,7 +630,7 @@ function unwrapLauncher(folded, allow) {
         const head = t.includes("/") ? t.slice(t.lastIndexOf("/") + 1) : t;
         if (SHELL_CONTROL_PREFIXES.has(head) || SHELL_BLOCK_WORDS.has(head))
             return { kind: "refused", reason: `"${folded[0]}" is given shell control syntax ("${head}") where the program it runs would be ${NOT_AUTO_ALLOWED}` };
-        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head } : { kind: "unlisted" };
+        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head } : { kind: "unlisted", head };
     }
     return { kind: "unlisted" };
 }
@@ -911,10 +1239,15 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             continue;
         }
         nameRefusal ??= `command "${parsed.name}" is not in the read-only allowlist`;
+        if (SHELL_REENTRY_PROGRAM_RE.test(name))
+            return { reason: `command "${parsed.name}" runs its argument as shell text, which this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
         if (COMMAND_LAUNCHERS.has(name)) {
             const unwrapped = unwrapLauncher(folded.slice(from), allow);
             if (unwrapped.kind === "refused")
                 return { reason: unwrapped.reason, refusedWhole: true };
+            if (unwrapped.kind === "unlisted" && unwrapped.head !== undefined && SHELL_REENTRY_PROGRAM_RE.test(unwrapped.head)) {
+                return { reason: `"${written}" runs "${unwrapped.head}", which runs its argument as shell text this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
+            }
             if (unwrapped.kind === "unlisted")
                 unlistedSegments.add(si);
             else
@@ -955,8 +1288,13 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     const foldedSegments = [];
     let shapeRefusal = nameRefusal;
     for (let si = 0; si < segments.length; si++) {
-        if (unlistedSegments.has(si))
+        if (unlistedSegments.has(si)) {
+            const unlisted = tokenizeSegment(segments[si]);
+            if (unlisted.folded.length === 0)
+                continue;
+            foldedSegments.push({ folded: [LAUNCHER_SCAN_HEAD, ...unlisted.folded], raw: [LAUNCHER_SCAN_HEAD, ...unlisted.raw] });
             continue;
+        }
         const rehead = reheaded.get(si);
         const segmentTokens = rehead === undefined ? tokenizeSegment(segments[si]) : reheadSegment(tokenizeSegment(segments[si]), rehead.head, rehead.from);
         const toks = segmentTokens.folded;
@@ -1151,6 +1489,14 @@ export function classifySimpleCommandReadBoundary(command, boundary) {
 }
 const NOT_GATED = { gated: false, paths: [] };
 const ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const UNREADABLE_WHITELIST_WORD = /[$`()*?[\]{}~]/;
+function whitelistReadsTheSameWords(command, outsideHeredocBodies) {
+    if (/\\\r?\n/.test(command))
+        return false;
+    if (/\\[<>&|;()]/.test(outsideHeredocBodies))
+        return false;
+    return !(outsideHeredocBodies.includes("#") && /["']/.test(outsideHeredocBodies));
+}
 const UNMODELLED_BASE_MOVERS = new Set(["pushd", "popd"]);
 const COMMAND_LAUNCHERS = new Set([
     "env", "command", "builtin", "exec", "noglob", "xargs",
@@ -1188,14 +1534,12 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
             if (written === undefined)
                 continue;
             const name = programBasename(written);
-            if (!allow.has(name) && COMMAND_LAUNCHERS.has(name)) {
-                readers.push({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
-                continue;
-            }
             if (UNMODELLED_BASE_MOVERS.has(name))
                 baseMoved = true;
-            if (!allow.has(name) && name !== "cd")
+            if (!allow.has(name) && name !== "cd") {
+                readers.push({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
                 continue;
+            }
             readers.push(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });
         }
         if (readers.length === 0)

package/dist/tools/fs/fs-bash.js

@@ -86,7 +86,7 @@ function unjudgedRead(command, allowSet, resolved, verdict) {
         return true;
     if (verdict.refusedWhole !== true)
         return false;
-    if (refusedCommandMayRead(command, allowSet))
+    if (refusedCommandMayRead(command, allowSet, resolved))
         return true;
     return resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.17.1",
+  "version": "7.17.3",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",