@sema-agent/core 7.33.7 → 7.34.0

package/dist/core/permission-rule-model.js

@@ -6,6 +6,7 @@ import { inlineUntrusted } from "./untrusted-text.js";
 import { pathTargetOf } from "./tool-registry.js";
 import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
 import { readShellCommand } from "./shell-lexer.js";
+import { readOnlyLineObjection, readOnlyShellVerdict } from "./read-only-shell.js";
 export const RULE_BEHAVIORS = ["deny", "ask", "allow"];
 const RULE_BEHAVIOR_SET = new Set(RULE_BEHAVIORS);
 export function isRuleBehavior(v) {
@@ -450,6 +451,29 @@ export function pathRuleReachOf(rule, target, bases) {
     const segments = target.split("/").filter((sg) => sg !== "");
     return globSegmentsReach(globs, segments) ? REACHED : NOT_REACHED;
 }
+export function pathRuleHeadOf(rule, bases) {
+    const family = pathFamilyOf(bases);
+    const tree = bases.root ?? bases.cwd;
+    let head;
+    if (rule.match === "subpath") {
+        if (carriesDotSegment(rule.command, family))
+            return undefined;
+        const dir = pathIdentityOf(rule.command, family, tree);
+        return dir.ok && isIdentityDir(dir.identity, family) ? dir.identity : undefined;
+    }
+    else if (rule.match === "path") {
+        const r = resolvePathPattern(rule.command, bases, rule.behavior);
+        if ("missingBase" in r)
+            return undefined;
+        const parts = r.resolved.split("/");
+        const wild = parts.findIndex((part) => part.includes("*"));
+        head = (wild === -1 ? parts : parts.slice(0, wild)).join("/");
+    }
+    else
+        return undefined;
+    const id = pathIdentityOf(head === "" ? "/" : head, family, tree);
+    return id.ok ? id.identity : undefined;
+}
 function hasUnescapedStar(s) {
     for (let i = 0; i < s.length; i++) {
         if (s[i] !== "*")
@@ -765,15 +789,22 @@ export function findAdmittingRule(rules, call) {
         return lone !== undefined ? [lone] : undefined;
     }
     const covering = [];
+    const lineObjection = readOnlyLineObjection(call.command, call.execCwd ?? call.cwd);
     for (const [i, segment] of shape.segments.entries()) {
         const dir = cdDirs[i];
         const first = firstEligibleAdmittingRule(rules, segment, call) ?? (dir !== undefined ? firstEligibleDirectoryRule(rules, dir, call) : undefined);
-        if (first === undefined)
+        if (first === undefined) {
+            if (readsOnlyAsSegment(segment, lineObjection))
+                continue;
             return undefined;
+        }
         if (!covering.includes(first))
             covering.push(first);
     }
-    return covering;
+    return covering.length > 0 ? covering : undefined;
+}
+function readsOnlyAsSegment(segment, lineObjection) {
+    return lineObjection === undefined && !movesShellCursor(segment) && readOnlyShellVerdict(segment).readOnly;
 }
 function firstEligibleDirectoryRule(rules, directory, call) {
     for (const rule of rules) {
@@ -855,11 +886,13 @@ export function segmentCoverageOf(command, rules, call) {
         return undefined;
     const proposed = rules.proposed ?? [];
     const cdDirs = resolveCdSegmentDirectories(shape.segments, call.execCwd ?? call.cwd);
+    const lineObjection = readOnlyLineObjection(folded, call.execCwd ?? call.cwd);
     return shape.segments.map((segment, i) => {
         const dir = cdDirs[i];
         return {
             segment: segment.trim(),
-            covered: firstEligibleAdmittingRule(rules.persisted, segment, call) !== undefined ||
+            covered: readsOnlyAsSegment(segment, lineObjection) ||
+                firstEligibleAdmittingRule(rules.persisted, segment, call) !== undefined ||
                 (dir !== undefined && firstEligibleDirectoryRule(rules.persisted, dir, call) !== undefined) ||
                 proposed.some((p) => p.rule.tool === "Read"
                     ? dir !== undefined &&

package/dist/core/permission-rule-provider.d.ts

@@ -72,12 +72,16 @@ export interface EffectivePermissionRules {
     org: OrgRuleResolution;
     /** The durable partition's revision — the optimistic-concurrency anchor for its writes. */
     rev: number;
-    /** Present iff the DURABLE partition could not be read: `rules`/`removed` are then empty and `rev` is 0,
-     *  while the org partition's resolution beside it still stands (a flaky personal store must not become
-     *  an org governance outage). A consumer that needs the durable rows treats this as a read failure —
-     *  {@link effectiveOrThrow} is that reading; the gate's personal lane reads it as "unreadable"
-     *  (zero rules + a disclosure, fail toward asking). */
+    /** Present iff a PERSONAL partition could not be read — the durable one (its user / project rows; `removed` is then
+     *  empty and `rev` 0) or the session one: the failed partition's rows are absent from `rules`, while the rows of the
+     *  partition that WAS read stand, and so does the org resolution beside them (a flaky personal store must not become an
+     *  org governance outage). The line names the failure (both lines, `; `-joined, when both failed). A consumer that needs
+     *  the durable rows treats this as a read failure — {@link effectiveOrThrow} is that reading; the gate's personal lane
+     *  and the leg's path-row read skip the failed partition's rows, disclosed, and judge by the rest. */
     unreadable?: string;
+    /** Beside {@link unreadable}: the sources whose partition could not be read (`user` and `project` — the durable
+     *  partition; `session`), in that order — the rows `rules` does not carry. */
+    unreadableSources?: readonly Exclude<RuleSource, "org">[];
     /** Disclosure lines from the personal partitions (a session partition that could not be read, rows it
      *  served that are not canonical session rows of this session). The org partition's lines ride
      *  `org.disclosures`. */
@@ -85,12 +89,11 @@ export interface EffectivePermissionRules {
 }
 /**
  * The host-visible store, already anchored to one owner. One read verb, which never throws: each
- * partition reports its own failure in the view — the DURABLE partition's read failure as `unreadable`
- * (zero rows; the caller maps it to "unreadable": a loud disclosure, fail toward asking, exactly as the
- * old `list()` throw did), the SESSION partition's read failure as `unreadable` too (it may hold a
- * deny/ask row of this session, and zero rows would erase it — served-but-non-canonical rows stay a
- * `disclosures` line), the ORG partition's as its `status`. The org verdict stands while a personal
- * partition is down, and the personal rows stand while an org source is down.
+ * partition reports its own failure in the view — a PERSONAL partition's read failure (the durable one's, the
+ * session one's) as `unreadable` / `unreadableSources`, with that partition's rows absent and the other's present
+ * (served-but-non-canonical session rows stay a `disclosures` line), the ORG partition's as its `status`. The unit
+ * that fails is the partition: the org verdict stands while a personal partition is down, each personal partition's
+ * rows stand while the other is down, and the personal rows stand while an org source is down.
  */
 export interface PermissionRuleStore {
     effective(query?: {
@@ -119,6 +122,14 @@ export interface PermissionRuleStoreProvider {
         session: boolean;
     }>;
 }
+/**
+ * The store one task reads its person's rules from. The unauthenticated floor is enforced HERE, not merely asked of the
+ * provider: an absent principal resolves to zero personal rules, and a provider that forgot it would hand one person's
+ * standing approvals to an anonymous task. The ONE exception is an explicitly declared LOCAL-OWNER deployment, where "no
+ * principal" is the typed absence of identity — the machine owner's own bucket (a provider with no such face resolves
+ * the anonymous store; {@link createPermissionRuleLanes} refuses that declaration loudly).
+ */
+export declare function ownerStoreOf(provider: PermissionRuleStoreProvider, principal: string | undefined, localOwnerDeclared: boolean): PermissionRuleStore;
 /** What {@link createPermissionRuleStoreProvider} composes. */
 export interface PermissionRuleStoreConfig {
     /** The durable CRDT partition (user + project sources). Absent ⇒ no personal rules exist on this

package/dist/core/permission-rule-provider.js

@@ -4,6 +4,10 @@ import { UNGOVERNED_ORG_RESOLUTION, compileOrgShadowPredicate, createOrgRulePart
 export function ruleSourceOf(scope) {
     return scope.kind === "global" ? "user" : scope.kind;
 }
+export function ownerStoreOf(provider, principal, localOwnerDeclared) {
+    const anonymous = principal === undefined || principal === "";
+    return anonymous && localOwnerDeclared && provider.forLocalOwner !== undefined ? provider.forLocalOwner() : provider.forPrincipal(anonymous ? undefined : principal);
+}
 function usableSessionId(sessionId) {
     return typeof sessionId === "string" && sessionId !== "" ? sessionId : undefined;
 }
@@ -61,16 +65,22 @@ class UnifiedPermissionRuleStore {
             this.readSessionRows(usableSessionId(query?.sessionId), disclosures),
         ]);
         const orgResolution = orgSettled;
-        if ("unreadable" in sessionRows) {
-            return { rules: [], removed: [], org: orgResolution, rev: 0, disclosures, unreadable: sessionRows.unreadable };
-        }
+        const unreadable = [];
+        const unreadableSources = [];
         if (!durableSettled.ok) {
-            return { rules: [], removed: [], org: orgResolution, rev: 0, disclosures, unreadable: errText(durableSettled.e) };
+            unreadable.push(errText(durableSettled.e));
+            unreadableSources.push("user", "project");
+        }
+        if ("unreadable" in sessionRows) {
+            unreadable.push(sessionRows.unreadable);
+            unreadableSources.push("session");
         }
-        const durableRead = durableSettled.v;
+        const failed = unreadable.length > 0 ? { unreadable: unreadable.join("; "), unreadableSources } : {};
+        const durableRead = durableSettled.ok ? durableSettled.v : EMPTY_DURABLE;
+        const sessionRead = "unreadable" in sessionRows ? [] : sessionRows;
         const shadowed = compileOrgShadowPredicate(orgResolution.rules);
         const rules = [];
-        for (const r of [...sessionRows, ...durableRead.rules]) {
+        for (const r of [...sessionRead, ...durableRead.rules]) {
             rules.push({ ...r, source: ruleSourceOf(r.scope), status: r.behavior === "allow" && shadowed(r) ? "shadowed-by-org" : "live" });
         }
         const removed = [];
@@ -83,7 +93,7 @@ class UnifiedPermissionRuleStore {
                 continue;
             removed.push({ behavior: t.behavior, rule: t.rule, scope: t.scope, source: ruleSourceOf(t.scope), status: "removed" });
         }
-        return { rules, removed, org: orgResolution, rev: durableRead.rev, disclosures };
+        return { rules, removed, org: orgResolution, rev: durableRead.rev, disclosures, ...failed };
     }
     async readSessionRows(sessionId, disclosures) {
         if (this.session === undefined || sessionId === undefined)

package/dist/core/permission-rules.d.ts

@@ -47,7 +47,8 @@
  */
 import type { NamedToolPolicy } from "./tool-policy.js";
 import { parsePermissionRule, type ParsedPermissionRule } from "./permission-rule-syntax.js";
-import { type PathRuleBases } from "./permission-rule-model.js";
+import { type ParsedRule, type PathRuleBases } from "./permission-rule-model.js";
+import type { DenyFace, PathRuleDenyRow } from "../tools/fs/read-deny.js";
 export { parsePermissionRule, type ParsedPermissionRule };
 /** [K-PLATFORM-SWEEP] MINOR#11: Bash's REAL non-primary arg names, accepted as generic param rules
  *  (`Bash(timeout:...)`). Exported SOLELY so a lockstep test can assert it against the live Bash tool
@@ -190,6 +191,27 @@ export interface RuleFaceView {
 export declare function catalogRuleFaceView(toolName: string): RuleFaceView | undefined;
 /** Exported for the lockstep guard only (the scalar vocabulary of a catalog tool) — not part of the rule DSL. */
 export declare const fileToolParamVocabulary: (canonicalTool: string) => ReadonlySet<string> | undefined;
+/**
+ * The path DENY rules that speak for a FACE rather than for one tool (the reference implementation's reading: a Read
+ * deny rule covers every built-in tool that reads a file and the shell's file commands; an Edit deny rule every tool
+ * that edits one; a Read deny also refuses writing the same path). Such a rule reaches any call whose declared path
+ * target is on one of its faces — the write tools, the read tools, the search roots — and it is exported to the
+ * engine's deny tables (`ToolPolicy.pathDenyRules`) so the shell's reads and writes and the
+ * traversals meet it too. A path rule on any other tool keeps its tool's name as its reach (`Write(<path>)` is judged on
+ * the Write tool, a stricter reading the reference does not make).
+ */
+export declare const PATH_DENY_RULE_FACES: Readonly<Record<string, readonly DenyFace[]>>;
+/**
+ * The deny-table row of ONE face-keyed path deny rule, resolved against `bases` — the row's reach IS the rule's (the same
+ * parsed rule, the same bases). Every source of such rows builds them here: a policy's compiled rules, and the person's
+ * persisted store rows. The caller holds the bases the pattern needs (`ruleBasesNeeded`): a row whose base is missing
+ * reads `unreadable`, which this row treats as a reach — a deny row that cannot be judged holds.
+ */
+export declare function pathRuleDenyRowOf(rule: {
+    readonly parsed: ParsedRule;
+    readonly ruleText: string;
+    readonly faces: readonly DenyFace[];
+}, bases: PathRuleBases): PathRuleDenyRow;
 /** Dry-run 校验/迁移报告:不 throw,返回全部 issues(含 `unsupported.*` 分类,
  *  供从 CC settings 迁移的部署逐条对照)。 */
 export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps" | "ruleFaces" | "pathBases">): PermissionRuleIssue[];

package/dist/core/permission-rules.js

@@ -1,8 +1,8 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { PATH_RULE_BASE_LABEL, isUsablePathBase, parseRuleText, pathRuleReachOf, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
-import { pathFamilyOf } from "../tools/fs/safety.js";
+import { PATH_RULE_BASE_LABEL, READ_RULE_TOOL, isUsablePathBase, parseRuleText, pathRuleHeadOf, pathRuleReachOf, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
+import { pathFamilyOf, pathIdentityOf, spellingOfIdentity } from "../tools/fs/safety.js";
 import { effectivePathTargetOf } from "./effective-path-target.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
 import { ruleDenialSentence } from "./rule-denial-sentence.js";
@@ -81,6 +81,27 @@ export const fileToolParamVocabulary = (canonicalTool) => {
     const face = catalogRuleFaceOf(canonicalTool);
     return face?.params === undefined || pathTargetOf(canonicalTool) === undefined ? undefined : new Set(face.params);
 };
+export const PATH_DENY_RULE_FACES = Object.freeze({ [READ_RULE_TOOL]: ["read", "write"], Edit: ["write"] });
+export function pathRuleDenyRowOf(rule, bases) {
+    const family = pathFamilyOf(bases);
+    const tree = bases.root ?? bases.cwd;
+    const head = pathRuleHeadOf(rule.parsed, bases);
+    return {
+        rule: rule.ruleText,
+        tool: rule.parsed.tool,
+        pattern: parsePermissionRule(rule.ruleText).ruleContent ?? "",
+        faces: rule.faces,
+        reaches: (absolutePath) => {
+            const id = pathIdentityOf(absolutePath, family, tree);
+            return id.ok && pathRuleReachOf(rule.parsed, id.identity, bases).reach !== "not_reached";
+        },
+        ...(head !== undefined ? { head: spellingOfIdentity(head, family) } : {}),
+    };
+}
+function callPathFaceOf(req) {
+    const target = protectivePathTargetOf(req);
+    return target === undefined ? undefined : target.access === "read" ? "read" : "write";
+}
 function countStars(s) {
     let n = 0;
     for (const c of s)
@@ -196,7 +217,8 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                 }
                 if (issues.length > 0 && issues[issues.length - 1].rule === text && issues[issues.length - 1].code === "unsupported.path_base")
                     continue;
-                entry.content[r.behavior].push({ parsed: parsedPath.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
+                const faces = r.behavior === "deny" ? PATH_DENY_RULE_FACES[toolName] : undefined;
+                entry.content[r.behavior].push({ parsed: parsedPath.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}), ...(faces !== undefined ? { faces } : {}) });
                 byTool.set(toolName, entry);
                 continue;
             }
@@ -317,6 +339,8 @@ export function createPermissionRulePolicy(rules, opts) {
     }
     const coveringHit = (lane, toolName) => lane.length === 0 ? undefined : lane.find((r) => namespacedRuleNameCovers(r.ruleName, toolName));
     const hasCovering = namespacedCovering.deny.length > 0 || namespacedCovering.ask.length > 0 || namespacedCovering.allow.length > 0;
+    const faceDenyRules = [...byTool.values()].flatMap((e) => e.content.deny.filter((r) => r.faces !== undefined));
+    const pathDenyRules = faceDenyRules.map((r) => pathRuleDenyRowOf({ parsed: r.parsed, ruleText: r.ruleText, faces: r.faces }, pathBases));
     const commandParam = catalogRuleFaceOf("Bash")?.primaryParams[0] ?? "command";
     const contentHit = (lane, req) => {
         if (lane.length === 0)
@@ -349,14 +373,15 @@ export function createPermissionRulePolicy(rules, opts) {
         }
         return unreadable;
     };
-    const unreadableAsk = (hit, req) => ({
+    const unreadableAsk = (hit, lane, req) => ({
         action: "ask",
         message: `tool "${req.toolName}" needs approval: the call could not be read against the permission rule ${hit.rule.ruleText} (${hit.unreadable}) — a person must decide`,
-        matchedAskRule: hit.rule.ruleText,
+        ruleUnreadable: lane,
         requiresRealApproval: true,
     });
     return {
         nameSets: [nameSets],
+        ...(pathDenyRules.length > 0 ? { pathDenyRules } : {}),
         check(req) {
             const entry = byTool.get(req.toolName);
             const covering = hasCovering && protocolOf(req.toolName) !== undefined;
@@ -368,7 +393,9 @@ export function createPermissionRulePolicy(rules, opts) {
                 if (coveringDeny)
                     return { action: "deny", message: ruleDenial(req, coveringDeny.ruleText, coveringDeny.source) };
             }
-            const contentDeny = entry !== undefined ? contentHit(entry.content.deny, req) : undefined;
+            const callFace = faceDenyRules.length > 0 ? callPathFaceOf(req) : undefined;
+            const denyLane = [...(entry?.content.deny.filter((r) => r.faces === undefined) ?? []), ...(callFace !== undefined ? faceDenyRules.filter((r) => r.faces.includes(callFace)) : [])];
+            const contentDeny = denyLane.length > 0 ? contentHit(denyLane, req) : undefined;
             if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
                 return { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
             }
@@ -379,7 +406,7 @@ export function createPermissionRulePolicy(rules, opts) {
                 }
             }
             if (contentDeny?.unreadable !== undefined)
-                return unreadableAsk({ rule: contentDeny.rule, unreadable: contentDeny.unreadable }, req);
+                return unreadableAsk({ rule: contentDeny.rule, unreadable: contentDeny.unreadable }, "content_deny", req);
             if (entry) {
                 if (entry.bare.ask) {
                     return { action: "ask", message: ruleAskMessage(entry.bare.ask.ruleText, entry.bare.ask.source), matchedAskRule: entry.bare.ask.ruleText };
@@ -394,7 +421,7 @@ export function createPermissionRulePolicy(rules, opts) {
                 const contentAsk = contentHit(entry.content.ask, req);
                 if (contentAsk !== undefined) {
                     if (contentAsk.unreadable !== undefined)
-                        return unreadableAsk({ rule: contentAsk.rule, unreadable: contentAsk.unreadable }, req);
+                        return unreadableAsk({ rule: contentAsk.rule, unreadable: contentAsk.unreadable }, "content_ask", req);
                     return { action: "ask", message: ruleAskMessage(contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
                 }
                 const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);

package/dist/core/persisted-rule-arms.d.ts

@@ -17,9 +17,10 @@ import type { PersistedRuleHit, PersistedRuleHitRule } from "./hooks.js";
  *  produces it; the arms below read it). */
 export interface PersistedRuleRead {
     readonly hit?: PersistedRuleHit;
+    /** The lane could not answer: with `reason`, the CALL could not be read against the person's deny/ask rows;
+     *  without, the store could not be read — its rows take no part in the decision (the record says so). */
     readonly unreadable?: true;
-    /** The lexer's reason when the CALL could not be read against the person's deny/ask rows (absent for
-     *  a store read failure) — the message says which it was; the decision is the same. */
+    /** The lexer's reason when the CALL could not be read against the person's deny/ask rows. */
     readonly reason?: string;
 }
 /** Display form of a rule set (design/375 §5.1): every rule text is a DISPLAY value on a human trust
@@ -45,14 +46,14 @@ export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[])
  *    ask, the marker is stamped if absent and the message names the rule — the standing question
  *    outranks a remembered yes across lanes, exactly as the DSL's own order says within one; a deny
  *    stays a deny.
- *  · UNREADABLE — the wired store could not be read (a read failure, a timeout), or the CALL could not be
- *    read against the person's standing deny/ask rows (`reason` carries the lexer's word: an expansion
- *    where a rule reads a word, an unterminated quote, a syntax error): the person's deny/ask rows
- *    cannot be enforced for this call, so it fails CLOSED the way an unreadable org snapshot does — an
- *    allow tightens to an ask carrying `requiresRealApproval` (no automatic lane clears it; the gate
+ *  · UNREADABLE CALL — the store was read, but the CALL could not be read against the person's standing
+ *    deny/ask rows (`reason` carries the lexer's word: an expansion where a rule reads a word, an
+ *    unterminated quote, a syntax error): whether a row forbids this call is unknown, so it fails CLOSED —
+ *    an allow tightens to an ask carrying `requiresRealApproval` (no automatic lane clears it; the gate
  *    derives the origin `rule_store_unavailable` from its own record of the read), an ask acquires the
- *    bit, a deny stays a deny. Reading an unreadable store as "no rule" would erase every deny the
- *    person wrote the moment their file is locked or corrupt.
+ *    bit, a deny stays a deny.
+ * A store that could not be READ (`unreadable` without a `reason`) contributes no row: the decision is returned
+ * untouched, as for no hit — the lane announces the skipped store, and the rows apply again once a read succeeds.
  * An allow hit (or no hit) returns the decision untouched: the allow arm is the station's.
  */
 export declare function applyPersistedTightening(decision: PermissionResult, read: PersistedRuleRead | undefined): {

package/dist/core/persisted-rule-arms.js

@@ -1,3 +1,4 @@
+import { decisionAskClassesOf } from "./ask-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 export function disclosedRuleSet(rules) {
     const shown = rules.slice(0, 5).map((r) => inlineUntrusted(r.rule, 200));
@@ -5,16 +6,18 @@ export function disclosedRuleSet(rules) {
     return rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
 }
 export function applyPersistedTightening(decision, read) {
-    if (read?.unreadable === true) {
+    if (read?.unreadable === true && read.reason !== undefined) {
         if (decision.action === "deny")
             return { decision };
-        const message = read.reason !== undefined
-            ? `this call could not be read against the person's standing deny/ask rules (${read.reason}) — whether one of them forbids it is unknown, so it needs a real approval`
-            : "the persisted permission-rule store could not be read for this call — the person's own deny/ask rules cannot be enforced, so this call needs a real approval until the store is readable";
+        const message = `this call could not be read against the person's standing deny/ask rules (${read.reason}) — whether one of them forbids it is unknown, so it needs a real approval`;
+        const unreadableCall = { ruleUnreadable: "persisted_call" };
+        const standingFence = decision.action === "ask" && decisionAskClassesOf({ ...decision, foldedAskClasses: undefined }).has("policy_rra")
+            ? { foldedAskClasses: [...(decision.foldedAskClasses ?? []), "policy_rra"] }
+            : {};
         return {
             decision: decision.action === "allow"
-                ? { action: "ask", message, decisionReason: "persisted_rule", requiresRealApproval: true, ...(decision.updatedInput !== undefined ? { updatedInput: decision.updatedInput } : {}) }
-                : { ...decision, requiresRealApproval: true, message: `${decision.message !== undefined ? `${decision.message} ` : ""}(${message})` },
+                ? { action: "ask", message, decisionReason: "persisted_rule", requiresRealApproval: true, ...unreadableCall, ...(decision.updatedInput !== undefined ? { updatedInput: decision.updatedInput } : {}) }
+                : { ...decision, requiresRealApproval: true, ...unreadableCall, ...standingFence, message: `${decision.message !== undefined ? `${decision.message} ` : ""}(${message})` },
             tightened: "unreadable",
         };
     }

package/dist/core/present-plan-tool.d.ts

@@ -13,7 +13,7 @@ export declare const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
  * making enter execute (set the flag) BEFORE the sibling edit is prepared+gated — closing the same-batch window.
  * Exit is via `present_plan` (→ plan_review → human approve-resume), not by this tool.
  */
-export declare function createEnterPlanModeTool(enterPlanMode: () => void): ToolSpec;
+export declare function createEnterPlanModeTool(enterPlanMode: () => Promise<void> | void): ToolSpec;
 /**
  * design/80 D-B — the first-party `present_plan` tool (CC `ExitPlanMode` parity). A THIN composition over the
  * general `ctx.requestReview()` primitive: the model calls it with a plan; the tool returns the plan as its

package/dist/core/present-plan-tool.js

@@ -3,7 +3,7 @@ import { delimitUntrusted } from "./untrusted-text.js";
 import { toolFace } from "./tool-catalog-entries.js";
 export const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
 export const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
-const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, write/edit/mutating tool calls are REJECTED while read-only tools (Read, Grep, Glob, etc.) still work. When your plan is ready, call ${PRESENT_PLAN_TOOL_NAME} with it — the run PAUSES for a human to approve it, then continues (read-only lifted) so you can execute.
+const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, every write/edit/mutating tool call ASKS the user first ("Cannot write to <path> while in plan mode."; where nobody can answer, it is refused) while read-only tools (Read, Grep, Glob, etc.) still work. When your plan is ready, call ${PRESENT_PLAN_TOOL_NAME} with it — the run PAUSES for a human to approve it, then continues (read-only lifted) so you can execute.
 
 Use this tool proactively when you're about to start a non-trivial implementation task. If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead — getting alignment on the plan itself is the point.
 
@@ -37,8 +37,8 @@ export function createEnterPlanModeTool(enterPlanMode) {
         parameters: Type.Object({}),
         executionMode: "sequential",
         execute: async () => {
-            enterPlanMode();
-            const message = "Entered plan mode (read-only). Write/edit/mutating tools are now rejected for the rest of this run; " +
+            await enterPlanMode();
+            const message = "Entered plan mode (read-only). Every write/edit/mutating tool call now asks the user first for the rest of this run; " +
                 `research with read-only tools, then call ${PRESENT_PLAN_TOOL_NAME} with your plan to get it approved before acting.`;
             return {
                 content: message,

package/dist/core/read-only-shell.d.ts

@@ -1,19 +1,3 @@
-/**
- * The READ-ONLY shell reader — "does this command line provably only READ?" — the allow-layer member
- * the tool gate consults for the shell tool after every tightening lane and after the person's own allow
- * rules, and before the classifier or a person is asked (`gate-lanes.ts`). Upstream (CC 2.1.250) has the
- * same station: its shell tool's `isReadOnly` runs the command through a parser, splits it into its
- * simple commands, and admits the whole line only when EVERY simple command is read-only by its tables;
- * this module is that reading over this engine's own lexer ({@link readShellCommand}, the tightening
- * reader's) and the transcribed tables (`read-only-shell-table.ts`).
- *
- * The reading itself is the contract on {@link readOnlyShellVerdict}.
- *
- * What the verdict is NOT: a security boundary of its own. The deny/ask lanes run before it and win; the
- * mandated asks (an operator's per-call shell confirmation, a tool's own egress/irreversibility marks, an
- * explicit ask rule, a hook's ask, governance) are never cleared by it — the gate's allow-layer predicate
- * decides where it may speak, exactly as it decides for a person's stored allow rule.
- */
 import { type ShellCommandShape } from "./shell-lexer.js";
 /** The reader's answer: read-only, or not — with the first reason the reading stopped on (a sentence a
  *  trace or a card can show; never adjudication input). */
@@ -23,6 +7,14 @@ export type ReadOnlyShellVerdict = {
     readonly readOnly: false;
     readonly reason: string;
 };
+/** The reference implementation's question for a compound that changes directory and runs git (2.1.280, `cd-git-compound`). */
+export declare const CD_GIT_COMPOUND_SENTENCE = "This command changes directory before running a version-control command, which can pick up untrusted hooks or repository configuration from the target directory. Approve only if you trust it.";
+/**
+ * Does this line change directory and run git — a `cd` beside a `git` — other than by ONE plain `cd <path>` that lands
+ * where the session stands (`cwd`)? The reference's no-op reading, lexical here: the path is `.` / `..`, starts `./` /
+ * `../` / `/`, carries no expansion, quote-removed text only, and resolves to `cwd` itself. No `cwd` ⇒ no no-op.
+ */
+export declare function changesDirectoryBeforeGit(shape: ShellCommandShape, cwd?: string): boolean;
 /**
  * Read `command` as the allow layer must: read-only, or the first reason it is not. A shape already read by
  * the caller may be handed in (the gate reads every shell command once).
@@ -36,7 +28,15 @@ export type ReadOnlyShellVerdict = {
  * admitted only under {@link READ_ONLY_GLOB_PROGRAMS}; else the structural reading (the bare-program set,
  * the exact forms, `echo`/`ls`/`cd`/`find`/`printf`/`history`/`arch`/`ifconfig`); else the flag-vetted
  * table with its per-row danger predicates, and the `uniq`/`jq` forms. A `cd` beside a `git` in one line
- * is never read-only (the git command's repository is then not the session's). Anything the reading does
- * not positively admit is NOT read-only — the answer is never a guess, and a `false` costs one question.
+ * is never read-only (the git command's repository is then not the session's) unless the `cd` lands where the session
+ * stands ({@link changesDirectoryBeforeGit}). Anything the reading does not positively admit is NOT read-only — the
+ * answer is never a guess, and a `false` costs one question.
+ */
+export declare function readOnlyShellVerdict(command: string, shape?: ShellCommandShape, cwd?: string): ReadOnlyShellVerdict;
+/**
+ * The reader's LINE-level objection to `command` — what makes no segment of it read-only in its place, whatever the
+ * segment reads on its own: the line's structure, or a `cd` beside a `git` ({@link changesDirectoryBeforeGit}). A caller
+ * that judges a compound's segments one by one ({@link readOnlyShellVerdict} over a segment's text) asks this of the
+ * line first.
  */
-export declare function readOnlyShellVerdict(command: string, shape?: ShellCommandShape): ReadOnlyShellVerdict;
+export declare function readOnlyLineObjection(command: string, cwd?: string): string | undefined;

package/dist/core/read-only-shell.js

@@ -1,6 +1,22 @@
+import { posix } from "node:path";
 import { readShellCommand } from "./shell-lexer.js";
 import { FIND_ACTION_PRIMARIES, FIND_NEWER_PRIMARY, FIND_VALUE_PRIMARIES, FLAG_VALUE_ACCEPTS, READ_ONLY_BARE_ONLY, READ_ONLY_BARE_PROGRAMS, READ_ONLY_COMMAND_TABLE, READ_ONLY_ENV_NAMES, READ_ONLY_EXACT_FORMS, READ_ONLY_GLOB_PROGRAMS, XARGS_READ_ONLY_TARGETS, dockerRetargetDanger, } from "./read-only-shell-table.js";
 const NOT = (reason) => ({ readOnly: false, reason });
+export const CD_GIT_COMPOUND_SENTENCE = "This command changes directory before running a version-control command, which can pick up untrusted hooks or repository configuration from the target directory. Approve only if you trust it.";
+export function changesDirectoryBeforeGit(shape, cwd) {
+    const programs = shape.segments.map((s) => peelBuiltinPrefix(s.argv.slice(leadingAssignmentCount(s.argv)).map((w) => w.text))[0] ?? "");
+    if (shape.segments.length < 2 || !programs.includes("cd") || !programs.includes("git"))
+        return false;
+    const cds = shape.segments.filter((_, i) => programs[i] === "cd");
+    const [cd] = cds;
+    if (cwd === undefined || cds.length !== 1 || cd === undefined || cd.redirections.length > 0 || cd.argv.length !== 2 || cd.argv[0].raw !== "cd")
+        return true;
+    const target = cd.argv[1];
+    if (target.expands !== false || !/^(?:\.\.?(?:\/|$)|\/)/.test(target.text) || /[$`*?[\\]/.test(target.raw))
+        return true;
+    const trim = (p) => p.replace(/\/+$/, "") || "/";
+    return trim(posix.resolve(cwd, target.text)) !== trim(cwd);
+}
 const READ_ONLY = { readOnly: true };
 const BARE_PROGRAMS = new Set(READ_ONLY_BARE_PROGRAMS.filter((p) => !p.includes(" ")));
 const BARE_MULTIWORD = READ_ONLY_BARE_PROGRAMS.filter((p) => p.includes(" ")).map((p) => p.split(" "));
@@ -23,15 +39,10 @@ const PRINTF_ESCAPE = new RegExp(`%[^%a-zA-Z]*${PRINTF_LENGTH}\\\\[0-7xX]`);
 const PRINTF_NUMERIC = new RegExp(`%[-+ 0#']*[0-9.*]*${PRINTF_LENGTH}[diouxXeEfFgGaAn]`);
 const JQ_DANGER_FLAG = /^['"]?-[a-zA-Z]*[fL]/;
 const JQ_DANGER_TEXT = /--from-file|--rawfile|--slurpfile|--run-tests|--library-path|\benv\b|\$ENV\b|\binclude\b|\bimport\b/;
-export function readOnlyShellVerdict(command, shape = readShellCommand(command)) {
-    if (shape.grouped)
-        return NOT("a subshell, group or control structure — not a flat list of simple commands");
-    if (shape.segments.length === 0)
-        return NOT("no command");
-    if (shape.backgrounded)
-        return NOT("a background `&` defers execution past the approval-time reading");
-    if (shape.strayRedirection)
-        return NOT("a redirection on a piece that runs no program — the shell still opens its target");
+export function readOnlyShellVerdict(command, shape = readShellCommand(command), cwd) {
+    const line = lineStructureObjection(shape);
+    if (line !== undefined)
+        return NOT(line);
     for (const seg of shape.segments) {
         if (seg.unreadable !== undefined)
             return NOT(seg.unreadable);
@@ -46,9 +57,8 @@ export function readOnlyShellVerdict(command, shape = readShellCommand(command))
                 return NOT("a shell-specific expansion spelling (`=cmd`, `~[…]`)");
         }
     }
-    const programs = shape.segments.map((s) => peelBuiltinPrefix(s.argv.slice(leadingAssignmentCount(s.argv)).map((w) => w.text))[0] ?? "");
-    if (shape.segments.length > 1 && programs.includes("cd") && programs.includes("git"))
-        return NOT("a compound that changes directory and runs git");
+    if (changesDirectoryBeforeGit(shape, cwd))
+        return NOT(CD_GIT_REASON);
     for (const seg of shape.segments) {
         const verdict = segmentVerdict(seg);
         if (!verdict.readOnly)
@@ -56,6 +66,22 @@ export function readOnlyShellVerdict(command, shape = readShellCommand(command))
     }
     return READ_ONLY;
 }
+const CD_GIT_REASON = "a compound that changes directory and runs git";
+function lineStructureObjection(shape) {
+    if (shape.grouped)
+        return "a subshell, group or control structure — not a flat list of simple commands";
+    if (shape.segments.length === 0)
+        return "no command";
+    if (shape.backgrounded)
+        return "a background `&` defers execution past the approval-time reading";
+    if (shape.strayRedirection)
+        return "a redirection on a piece that runs no program — the shell still opens its target";
+    return undefined;
+}
+export function readOnlyLineObjection(command, cwd) {
+    const shape = readShellCommand(command);
+    return lineStructureObjection(shape) ?? (changesDirectoryBeforeGit(shape, cwd) ? CD_GIT_REASON : undefined);
+}
 function expansionKind(w) {
     if (w.expands === false)
         return "none";

package/dist/core/retired-keys.d.ts

@@ -12,8 +12,14 @@ export declare function retiredKeyOf(bag: object, table: Readonly<Record<string,
     replacement: string;
 } | undefined;
 /**
- * The deps-bag door: a retired seat still wired by a deployment is refused BY NAME (`config.deps_retired_key`)
- * instead of vanishing silently — a seat that is silently dropped reads to the deployment as wired. `owner` is
- * the bag's type name for the sentence (`RunnerDeps`, `RunWorkflowToolDeps`).
+ * The retired-key door: a retired seat still wired by a deployment is refused BY NAME (`config.deps_retired_key`
+ * on a deps bag, `config.spec_retired_key` on a `TaskSpec`) instead of vanishing silently — a seat that is silently
+ * dropped reads to the caller as wired. `owner` is the bag's type name for the sentence (`RunnerDeps`,
+ * `RunWorkflowToolDeps`, `TaskSpec`).
  */
 export declare function assertNoRetiredKeys(bag: object, table: Readonly<Record<string, string>>, owner: string): void;
+/** The RETIRED `TaskSpec` keys, each with the sentence that names its replacement — the table the spec door reads
+ *  ({@link assertNoRetiredKeys} with owner `TaskSpec`). A caller still writing one of these is refused by name
+ *  (`config.spec_retired_key`), never read as absence: a mode a caller believes it declared must not silently run
+ *  as another. */
+export declare const RETIRED_TASK_SPEC_KEYS: Readonly<Record<string, string>>;

package/dist/core/retired-keys.js

@@ -10,6 +10,10 @@ export function assertNoRetiredKeys(bag, table, owner) {
     if (hit === undefined)
         return;
     const e = new Error(`${owner}.${hit.key} is retired and is not read by this engine — ${hit.replacement}. Refused rather than ignored: a seat that is silently dropped reads to the deployment as wired.`);
-    e.code = "config.deps_retired_key";
+    e.code = owner === "TaskSpec" ? "config.spec_retired_key" : "config.deps_retired_key";
     throw e;
 }
+export const RETIRED_TASK_SPEC_KEYS = Object.freeze({
+    autoModeRequested: 'the permission mode is one key now — write `permissionMode: "auto"`',
+    approverPosture: 'the permission mode is one key now — write `permissionMode: "bypassPermissions"` (the engine renders the posture from the effective mode)',
+});