@sema-agent/core 5.29.0 → 5.31.0

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

@@ -57,7 +57,7 @@ import { foldAdmissionFreeze } from "../memory-admission.js";
 import { prepareMemory } from "./prepare-memory.js";
 import { defaultPromptProvider, buildEnvironmentContext, buildGitSnapshot, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
 import { assemblePrompt } from "../../prompt-assembly/assemble.js";
-import { auditToolCollisions, projectToolManifest } from "../../prompt-assembly/tool-catalog.js";
+import { auditToolCollisions, getToolContract, projectToolManifest } from "../../prompt-assembly/tool-catalog.js";
 import { resolveEpochAgainstBundled } from "../../prompt-assembly/epoch.js";
 import { artifactDeclarations } from "../../prompt-assembly/artifact.js";
 import { buildTurnPromptSnapshot } from "../../prompt-assembly/turn-snapshot.js";
@@ -74,7 +74,7 @@ import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.j
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
 import { createMonitorTool } from "../../tools/monitor.js";
 import { createWorktreeTools } from "../../tools/worktree.js";
-import { applyCompactionToReadFileState, bashReversibilityProbe, createHandsToolkit, isReadDedupStubResult, seedReadFileStateFromContext, seedReadFileStateFromTranscript, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
+import { applyCompactionToReadFileState, assertReadFaceValue, bashReversibilityProbe, compileReadDeny, createHandsToolkit, isReadDedupStubResult, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
 import { decodeTextBytes } from "../../tools/fs/encoding.js";
 import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTool, classifyQuestionOutcome, isLiveQuestionFace, validateAskQuestions, } from "../ask-question.js";
 import { createSchedulerTools } from "../../tools/scheduler-tools.js";
@@ -85,7 +85,7 @@ import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-
 import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
 import { resolveKey } from "../../tools/fs/safety.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
-import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
+import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { countElicitOptIns, deriveAskEffective, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam } from "../wiring-manifest.js";
 import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
@@ -342,6 +342,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             throw e;
         }
     }
+    assertReadFaceValue(spec.readFace, "TaskSpec.readFace");
+    assertReadFaceValue(deps.readFace, "readFace (deployment seat)");
     if (spec.resumeAtMode !== undefined) {
         if (spec.resumeAt === undefined) {
             const e = new Error(`resumeAtMode "${spec.resumeAtMode}" requires resumeAt (there is no branch target to position against)`);
@@ -917,7 +919,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 internals.onWorkspaceResolved({
                     cwd: taskRootPath,
                     isolated: internals.isolation === "worktree",
-                    remote: workspaceEnv !== undefined && isRemoteExecutionEnv(workspaceEnv),
+                    remote: workspaceEnv !== undefined &&
+                        (isRemoteExecutionEnv(workspaceEnv) || workspaceEnv.hostLocalPaths === false),
                 });
             }
             catch {
@@ -1081,6 +1084,17 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const memoryAdmittedOrgScopesRef = { current: [] };
         const ownOrgVerdictRef = { current: undefined };
         const orgAdmissionCheckpointState = () => inheritedAdmittedOrgScopes !== undefined || ownOrgVerdictRef.current !== undefined || orgGovernedProvenance;
+        const faceCheckpointSection = () => {
+            if (resolvedReadFace === undefined) {
+                const seed = resume?.seed.readFace;
+                return seed !== undefined ? { face: seed.face, ...(seed.denyEntries !== undefined ? { denyEntries: seed.denyEntries.map((e) => ({ ...e })) } : {}) } : undefined;
+            }
+            if (resolvedReadFace === "open" || readDenyAdditionsNormalized.length > 0) {
+                return { face: resolvedReadFace, ...(readDenyAdditionsNormalized.length > 0 ? { denyEntries: readDenyAdditionsNormalized.map((e) => ({ ...e })) } : {}) };
+            }
+            return undefined;
+        };
+        const faceCheckpointState = () => faceCheckpointSection() !== undefined;
         const f012CheckpointState = () => (inheritedParentConstraints?.length ?? 0) > 0 ||
             seedInheritedGate?.constraintChain !== undefined ||
             internals?.delegationProvenance !== undefined;
@@ -1151,6 +1165,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         };
         let agentForkDenial;
         let observersActive = false;
+        let resolvedReadFace;
+        let readDenyAdditionsNormalized = [];
+        const fullShellReachable = handsEnabled &&
+            !(executionEnv instanceof StubExecutionEnv) &&
+            spec.handsReadOnly !== true &&
+            !(toolFaceSnapshot.exclude?.includes("Bash") ?? false);
         let autoModeDecider;
         const enrichSpecToolCtx = (ctx) => ({
             ...ctx,
@@ -1161,6 +1181,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...(frozenOnAsk !== undefined ? { onAsk: frozenOnAsk } : {}),
             ...(frozenOnQuestion !== undefined ? { onQuestion: frozenOnQuestion } : {}),
             ...(spec.handsReadOnly === true ? { handsReadOnly: true } : {}),
+            ...(resolvedReadFace === "roots" ? { readFace: "roots" } : {}),
+            ...(readDenyAdditionsNormalized.length > 0 ? { readDenyPatterns: Object.freeze(readDenyAdditionsNormalized.map((e) => ({ ...e }))) } : {}),
             ...(spec.interactiveTools === false ? { interactiveTools: false } : {}),
             oneShot: spec.oneShot,
             clientContext: spec.clientContext,
@@ -1366,6 +1388,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 workflowDepth: internals?.workflowDepth,
                 parentCwd: taskRootPath,
                 parentThinking: () => harnessRef.current?.getThinkingLevel() ?? thinking,
+                parentReadFace: () => resolvedReadFace,
+                parentReadDenyPatterns: () => (readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized : undefined),
+                onNotice: deps.onNotice,
+                parentCheckpointStoreDisabled: spec.checkpointStore === null,
+                parentCenterArtifactDigest: () => centerAdoption?.artifact.artifactDigest,
+                parentCenterSourceRevision: () => centerAdoption?.sourceRevision,
                 ...(forwardEvent ? { forwardEvent } : {}),
                 inheritedGateForChildren,
             }));
@@ -1578,6 +1606,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const additionalRootsCanonical = [];
         const additionalReadRootsCanonical = [];
         let attachmentRootCanonical;
+        let readDenyMatcher;
         if (handsEnabled) {
             const rootRaw = taskRootPath;
             const canon = await executionEnv.canonicalPath(rootRaw);
@@ -1626,17 +1655,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
             const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
             readFileStateForCheckpoint = readFileState;
-            if (resume === undefined && spec.sessionId !== undefined) {
-                const prior = await session.buildContext().catch(() => undefined);
-                for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, additionalRootsCanonical);
-                    if (rk.ok)
-                        seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
-                }
-            }
             seedContextFiles = async (files) => {
                 for (const f of files) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, additionalRootsCanonical);
+                    const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
                     if (rk.ok)
                         seedReadFileStateFromContext(readFileState, rk.key, f.content);
                 }
@@ -1658,9 +1679,36 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(resume !== undefined ? { baselineUnknown: true } : {}),
                 };
             }
+            const seedReadFaceSection = resume?.seed.readFace;
+            const readDenyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seedReadFaceSection?.denyEntries ?? [])];
+            readDenyMatcher = compileReadDeny(readDenyAdditions, "readDenyPatterns");
+            {
+                const builtinCount = compileReadDeny([], "built-in").entries.length;
+                readDenyAdditionsNormalized = readDenyMatcher.entries.slice(builtinCount);
+            }
+            let liveReadFace = resolveReadFace({
+                specReadFace: spec.readFace,
+                depsReadFace: deps.readFace,
+                readOnlyMount: handsReadOnly,
+                orgGoverned: deps.permissionRuleOrg !== undefined,
+                fullShellReachable,
+            });
+            if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
+                liveReadFace = "roots";
+            resolvedReadFace = liveReadFace;
+            if (resume === undefined && spec.sessionId !== undefined) {
+                const prior = await session.buildContext().catch(() => undefined);
+                for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
+                    const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
+                    if (rk.ok)
+                        seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
+                }
+            }
             const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
                 ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
                 ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
+                ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
+                readFace: liveReadFace,
                 includeShell: handsIncludeShell,
                 readOnly: handsReadOnly,
                 ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
@@ -1714,6 +1762,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const shellReadBoundary = () => ({
                     roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
                     ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+                    denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
+                    ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
                 });
                 if (shellGate === "classify" && shellGatedBash)
                     reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
@@ -2164,6 +2214,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             policyEnabled: promptPolicyEnabled,
             hooksEnabled: promptHooksEnabled,
             isolationEnabled: isIsolated(executionEnv),
+            readFaceOpen: resolvedReadFace === "open",
             orchestrationEnabled: selfOrchestrationActive,
             orchestrationDeferred: selfOrchestrationActive && (toolFaceSnapshot.defer?.includes("Workflow") ?? false),
             promptProfile,
@@ -2216,6 +2267,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             if (additionalRootsCanonical.length > 0) {
                 envFacts.additionalDirectories = [...additionalRootsCanonical];
             }
+            if (resolvedReadFace !== undefined)
+                envFacts.readFace = resolvedReadFace;
             if (additionalReadRootsCanonical.length > 0) {
                 envFacts.additionalReadDirectories = [...additionalReadRootsCanonical];
             }
@@ -2309,6 +2362,16 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 if (excluded.has(tools[i].name))
                     tools.splice(i, 1);
         }
+        if (handsEnabled) {
+            const fullShellOnRoster = tools.some((t) => t.name === "Bash" && getToolContract(t, "core").contractId === FULL_SHELL_CONTRACT_ID);
+            if (fullShellOnRoster !== fullShellReachable) {
+                const e = new Error(`internal invariant: fullShellReachable=${String(fullShellReachable)} but the post-exclusion roster ` +
+                    `${fullShellOnRoster ? "carries" : "does not carry"} the full shell (${FULL_SHELL_CONTRACT_ID}). ` +
+                    `A new roster-affecting mechanism was added without updating the predicate.`);
+                e.code = "internal.full_shell_reachable_mismatch";
+                throw e;
+            }
+        }
         if (promptProfile === "classic") {
             for (let i = 0; i < tools.length; i++) {
                 const t = tools[i];
@@ -3300,6 +3363,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             const suggestions = suggestRulesForCommand(command);
             return suggestions.length > 0 ? { ruleSuggestions: suggestions } : {};
         };
+        const frozenClassifierExcluded = (d) => d.decisionReason === "hook" || d.matchedAskRule !== undefined;
         const recheckApprovedEdit = async (pol, onAskOf, creq, edit, csignal, ancestorDecider) => {
             let editArgs = edit;
             for (let round = 0;; round++) {
@@ -3326,7 +3390,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 }
                 if (re.updatedInput !== undefined)
                     editArgs = re.updatedInput;
-                if (ancestorDecider !== undefined) {
+                if (ancestorDecider !== undefined && !frozenClassifierExcluded(re)) {
                     const verdict = await ancestorDecider
                         .decide({ req: { ...creq, args: editArgs }, ...(re.message !== undefined ? { askMessage: re.message } : {}) }, csignal ?? abortController.signal)
                         .catch(() => ({ kind: "unavailable", cause: "error" }));
@@ -3405,7 +3469,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                     `ask cannot be reconstructed in a delegated child; denied fail-closed (tighten-only)`,
                             };
                         }
-                        if (pc.autoMode !== undefined) {
+                        if (pc.autoMode !== undefined && !frozenClassifierExcluded(first)) {
                             const verdict = await pc.autoMode.decider
                                 .decide({ req: creq, ...(first.message !== undefined ? { askMessage: first.message } : {}) }, csignal ?? abortController.signal)
                                 .catch(() => ({ kind: "unavailable", cause: "error" }));
@@ -3492,7 +3556,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             };
                         }
                         const presentedArgs = decision.updatedInput !== undefined ? decision.updatedInput : creq.args;
-                        if (pc.autoMode !== undefined) {
+                        if (pc.autoMode !== undefined && !frozenClassifierExcluded(decision)) {
                             const verdict = await pc.autoMode.decider
                                 .decide({ req: { ...creq, args: presentedArgs }, ...(decision.message !== undefined ? { askMessage: decision.message } : {}) }, csignal ?? abortController.signal)
                                 .catch(() => ({ kind: "unavailable", cause: "error" }));
@@ -3902,6 +3966,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 nestedStats: { ...nestedStats },
                 consolidationNotes: undefined,
                 readFileState: readFileStateForCheckpoint ? [...readFileStateForCheckpoint.entries()] : undefined,
+                readFace: faceCheckpointSection(),
                 repairBundle: repairBundleForCheckpoint(parkedSpendMicroUsd),
                 workspaceHandle,
                 handsCwd: handsCwdRef?.current,
@@ -4121,7 +4186,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const mintedAt = Date.now();
                 const cp = {
                     token,
-                    version: f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : resourceLedgerOut.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
+                    version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : resourceLedgerOut.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
                     scope,
                     sessionId,
                     leafId,
@@ -4203,7 +4268,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     const mintedAt = Date.now();
                     const cp = {
                         token,
-                        version: f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : reviewLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                        version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : reviewLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                         scope,
                         sessionId,
                         leafId,
@@ -4455,11 +4520,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const scope = durableApproval?.scope || checkpointScopeOf({ principal: spec.principal });
                         const ttlMs = sanitizedTtlMs(durableApproval?.ttlMs);
                         const checkpointState = serializeCheckpointState(remoteHandle, inFlightSpendMicroUsd());
+                        if (realApproval !== undefined && checkpointState.readFace !== undefined) {
+                            checkpointState.readFace = { ...checkpointState.readFace, realApproval: true };
+                        }
                         const approvalLedger = debitLedger(priorLedger, liveSpendRef.get?.() ?? { costMicroUsd: 0, tokens: 0, turns: 0, walltimeMs: 0 }, resourceTotal, { countSlice: false });
                         const mintedAt = Date.now();
                         cp = {
                             token,
-                            version: realApproval !== undefined ? REAL_APPROVAL_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                            version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : realApproval !== undefined ? REAL_APPROVAL_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                             scope,
                             sessionId,
                             leafId,
@@ -4809,21 +4877,42 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         promptManifest.lowering = turnSnapshot.lowering;
         const promptOverheadTokens = Math.ceil((systemPrompt.length +
             harnessTools.reduce((a, t) => a + t.name.length + (t.description?.length ?? 0) + JSON.stringify(t.parameters ?? {}).length, 0)) / charsPerToken);
+        const announceAttachmentSkip = (path, reason) => {
+            deps.onError?.(new Error(`working-file attachment skipped — ${path}: ${reason}`), {
+                phase: "degraded",
+                sessionId,
+                classification: "attachment-read",
+            });
+        };
         const readTaskFile = handsEnabled
             ? async (path) => {
                 try {
+                    let key = path;
                     if (attachmentRootCanonical !== undefined) {
-                        const rk = await resolveKey(executionEnv, attachmentRootCanonical, path, undefined, undefined, additionalRootsCanonical);
-                        if (!rk.ok)
+                        const rk = await resolveKey(executionEnv, attachmentRootCanonical, path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, readDenyMatcher, resolvedReadFace);
+                        if (!rk.ok) {
+                            announceAttachmentSkip(path, rk.violation.message);
+                            if (rk.violation.code === "read_path_denied" && rk.violation.pattern !== undefined) {
+                                return { withheld: { pattern: rk.violation.pattern } };
+                            }
                             return null;
+                        }
+                        key = rk.key;
                     }
-                    const r = await executionEnv.readBinaryFile(path);
-                    if (!r.ok)
+                    const r = await executionEnv.readBinaryFile(key);
+                    if (!r.ok) {
+                        announceAttachmentSkip(path, r.error.message);
                         return null;
+                    }
                     const d = decodeTextBytes(r.value);
-                    return d.malformed ? null : d.text;
+                    if (d.malformed) {
+                        announceAttachmentSkip(path, "malformed text encoding (truncated UTF-16 body)");
+                        return null;
+                    }
+                    return d.text;
                 }
-                catch {
+                catch (err) {
+                    announceAttachmentSkip(path, err instanceof Error ? err.message : String(err));
                     return null;
                 }
             }
@@ -4833,7 +4922,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 if (attachmentRootCanonical === undefined)
                     return path;
                 try {
-                    const rk = await resolveKey(executionEnv, attachmentRootCanonical, path, undefined, handsCwdRef?.current, additionalRootsCanonical);
+                    const rk = await resolveKey(executionEnv, attachmentRootCanonical, path, undefined, handsCwdRef?.current, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
                     return rk.ok ? rk.key : path;
                 }
                 catch {

package/dist/core/runner/runtask.js

@@ -1,6 +1,7 @@
+import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
-import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
+import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
 import { engineVersion } from "../version.js";
 import { CONFIG_CATALOG_VERSION, declarationReasons, resolveEffectiveConfig } from "../../config/catalog.js";
 import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
@@ -3718,11 +3719,36 @@ export class Runner {
             (preCasGateBit.origin === "org_rule" ||
                 preCasGateBit.origin === "org_unavailable" ||
                 preCasGateBit.origin === "policy");
-        if (checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION ? !preCasBitWellFormed : preCasGateBit !== undefined) {
+        const faceSaysGoverned = (cp.state.readFace?.realApproval) === true;
+        const preCasBitViolation = checkpointVersionOf(cp) === REAL_APPROVAL_CHECKPOINT_VERSION
+            ? !preCasBitWellFormed
+            : checkpointVersionOf(cp) < REAL_APPROVAL_CHECKPOINT_VERSION
+                ? preCasGateBit !== undefined
+                : faceSaysGoverned
+                    ? !preCasBitWellFormed
+                    : preCasGateBit !== undefined && !preCasBitWellFormed;
+        if (preCasBitViolation) {
             throw new CheckpointError("checkpoint.invalid_outcome", checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION
-                ? `a v${checkpointVersionOf(cp)} checkpoint must carry a well-formed non-budgetable realApproval gate bit (origin org_rule/org_unavailable/policy) on an irreversible_ask gate — this row does not; refusing to resume a damaged real-approval row (corruption / downgrade guard), the checkpoint stays pending`
+                ? `a v${checkpointVersionOf(cp)} checkpoint's realApproval gate bit must be well-formed (origin org_rule/org_unavailable/policy)${checkpointVersionOf(cp) === REAL_APPROVAL_CHECKPOINT_VERSION ? " and present on an irreversible_ask gate" : ""} — this row's is not; refusing to resume a damaged real-approval row (corruption / downgrade guard), the checkpoint stays pending`
                 : `a v${checkpointVersionOf(cp)} checkpoint carries a realApproval gate bit no release of that version ever minted — refusing to honor a fabricated origin (corruption / forgery guard), the checkpoint stays pending`, { reason: checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION ? "real_approval_damaged" : "real_approval_forged" });
         }
+        {
+            const faceSectionRaw = cp.state.readFace;
+            const faceCandidate = faceSectionRaw !== undefined && typeof faceSectionRaw === "object" && faceSectionRaw !== null
+                ? faceSectionRaw
+                : undefined;
+            const faceWellFormed = faceCandidate !== undefined &&
+                (faceCandidate.face === "open" || faceCandidate.face === "roots") &&
+                (faceCandidate.realApproval === undefined || faceCandidate.realApproval === true) &&
+                (faceCandidate.denyEntries === undefined ||
+                    (Array.isArray(faceCandidate.denyEntries) &&
+                        faceCandidate.denyEntries.every((e) => persistedReadDenyEntryProblem(e) === null)));
+            if (checkpointVersionOf(cp) >= FACE_CHECKPOINT_VERSION ? !faceWellFormed : faceSectionRaw !== undefined) {
+                throw new CheckpointError("checkpoint.invalid_outcome", checkpointVersionOf(cp) >= FACE_CHECKPOINT_VERSION
+                    ? `a v${checkpointVersionOf(cp)} checkpoint must carry a well-formed read-face section (state.readFace) — this row's is missing or malformed; refusing to resume a damaged read-face row (corruption / downgrade guard), the checkpoint stays pending`
+                    : `a v${checkpointVersionOf(cp)} checkpoint carries a read-face section no release of that version ever minted — refusing to honor a fabricated read-face state (corruption / forgery guard), the checkpoint stays pending`, { reason: checkpointVersionOf(cp) >= FACE_CHECKPOINT_VERSION ? "read_face_damaged" : "read_face_forged" });
+            }
+        }
         if ((preCasGateBit?.origin === "org_rule" || preCasGateBit?.origin === "org_unavailable") &&
             this.deps.permissionRuleOrg === undefined) {
             throw new CheckpointError("checkpoint.unsupported_version", `this checkpoint's approval was minted under organization governance (${preCasGateBit.origin}) and this worker has no org adjudication wiring (permissionRuleOrg) — a governed approval may only be redeemed where governance can be enforced; the checkpoint stays pending, resume it on an org-wired worker`, { reason: "governed_unwired" });

package/dist/core/runner/session-rule-policy.d.ts

@@ -53,8 +53,9 @@ export declare function isWithin(root: string, p: string): boolean;
  *  - `toolDeny` → deny the listed tools.
  *  - `toolAllow` (if set) → deny any tool NOT listed (a narrowing allowlist).
  *  - `commandAllow`/`commandDeny` → delegate to {@link createCoarseCommandNamePolicy} (argv[0] names; only
- *    speaks about shell tools). allowlist mode denies the un-listed/un-parseable; blocklist mode asks on the
- *    un-parseable circumvention surface (the gate decides).
+ *    speaks about shell tools) with `defaultAction:"deny"` in BOTH modes — so this policy structurally
+ *    emits no ask. Allowlist mode denies the un-listed and the un-parseable; blocklist mode denies the
+ *    listed and the un-parseable (a parseable command absent from the deny list stays allowed).
  *  - `allowDirs` (if set) → a WRITE tool must land inside one of the dirs (resolved via `canonicalizeTarget`,
  *    so a symlink can't carry across a write out); a write-capable tool that cannot be path-confined (e.g. `bash`)
  *    is DENIED while `allowDirs` is set (fail-closed, mirrors active-skill-scope MAJOR-2).

package/dist/core/runner/tool-output-projection.js

@@ -62,7 +62,7 @@ const CC_DETAIL_TYPES = new Set([
     "agent", "task", "task-list", "task-output", "workflow-run",
     "web-fetch", "web-search", "todo", "cron-create", "cron-delete", "cron-list", "image",
     "task-stop", "tool-search", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
-    "monitor-start", "path_not_in_root", "readonly_out_of_root", "bash_invalid_timeout",
+    "monitor-start", "path_not_in_root", "read_path_denied", "readonly_out_of_root", "bash_invalid_timeout",
     "report-findings", "schedule-wakeup", "send-message", "agent-transcript", "a2a", "document",
 ]);
 export const structuredFrom = (result) => {

package/dist/core/sensitive-path-policy.js

@@ -1,4 +1,5 @@
 import { canonicalizeTarget, writeTargetPath } from "../tools/fs/safety.js";
+import { compileSegmentPattern, matchSegmentPatterns } from "../tools/fs/read-deny.js";
 const DEFAULT_GUARDED_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
 export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".env",
@@ -25,33 +26,21 @@ export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".bash_history",
     ".zsh_history",
 ];
-function segmentGlobToRegExp(segment) {
-    const escaped = segment.replace(/[.+^${}()|[\]\\?]/g, "\\$&").replace(/\*/g, "[^/]*");
-    return new RegExp(`^${escaped}$`, CASE_INSENSITIVE_FS ? "i" : "");
-}
 const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
 function compilePatterns(patterns) {
     const out = [];
     for (const raw of patterns) {
-        const segments = raw.split("/").filter(Boolean).map(segmentGlobToRegExp);
-        if (segments.length === 0) {
+        const compiled = compileSegmentPattern(raw, CASE_INSENSITIVE_FS ? "unicode" : "none");
+        if (compiled === null) {
             throw new Error(`createSensitivePathPolicy: pattern ${JSON.stringify(raw)} contains no path segments and would guard nothing. ` +
                 `Patterns are "/"-separated runs of path SEGMENTS (e.g. ".ssh", ".git/hooks", "*.pem"); remove the entry or spell the segments.`);
         }
-        out.push({ raw, segments });
+        out.push(compiled);
     }
     return out;
 }
 function matchSensitive(canonicalKey, compiled) {
-    const segs = canonicalKey.split(/[\\/]/).filter(Boolean);
-    for (const pat of compiled) {
-        const n = pat.segments.length;
-        for (let i = 0; i + n <= segs.length; i++) {
-            if (pat.segments.every((re, j) => re.test(segs[i + j])))
-                return pat.raw;
-        }
-    }
-    return null;
+    return matchSegmentPatterns(canonicalKey, compiled);
 }
 export function createSensitivePathPolicy(opts) {
     const compiled = compilePatterns(opts.patterns);

package/dist/core/store-contracts/tool-result-store-contract.d.ts

@@ -19,4 +19,7 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
  * host-side read face, and an optional parameter one store honors while another drops it silently is
  * exactly the divergence the two legs above exist to prevent.
  */
-export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner, onOptionalMember?: (report: {
+    member: "deleteBySession";
+    status: "verified" | "absent";
+}) => void): Promise<void>;

package/dist/core/store-contracts/tool-result-store-contract.js

@@ -1,6 +1,6 @@
 import { strict as assert } from "node:assert";
 import { beginContract } from "./contract-harness.js";
-export async function toolResultStoreContract(make, runAssertion) {
+export async function toolResultStoreContract(make, runAssertion, onOptionalMember) {
     const { run, settle } = beginContract(runAssertion);
     run("put/get full + sliced; write-once no-op; unknown → undefined", async () => {
         const store = make();
@@ -55,5 +55,30 @@ export async function toolResultStoreContract(make, runAssertion) {
         assert.equal((await store.get(unowned)).content, "bytes from a write site that stated no owner");
         assert.equal(await ownerOf("tr_never~written"), undefined);
     });
+    run("#196 deleteBySession (optional): four-state semantics when present; absence is REPORTED, not silently green", async () => {
+        const probe = make();
+        if (probe.deleteBySession === undefined) {
+            onOptionalMember?.({ member: "deleteBySession", status: "absent" });
+            return;
+        }
+        assert.equal(typeof probe.deleteBySession, "function", `deleteBySession is present but not callable (got ${typeof probe.deleteBySession}) — a garbage member is a DEFECT, not an optional-member absence`);
+        const store = make();
+        const del = (sessionId) => Promise.resolve(store.deleteBySession(sessionId));
+        await store.put("tr_sweep~a", "A-bytes", { sessionId: "sess-X", taskId: "t1" });
+        await store.put("tr_sweep~b", "B-bytes", { sessionId: "sess-X" });
+        await store.put("tr_sweep~other", "OTHER-bytes", { sessionId: "sess-Y" });
+        await store.put("tr_sweep~unowned", "UNOWNED-bytes");
+        const first = await del("sess-X");
+        assert.equal(first.deleted, 2, "both rows recorded for the session are deleted (taskId presence does not split the key)");
+        assert.equal(await store.get("tr_sweep~a"), undefined, "a swept row is gone");
+        assert.equal(await store.get("tr_sweep~b"), undefined);
+        assert.equal((await store.get("tr_sweep~other")).content, "OTHER-bytes", "another session's row survives the sweep");
+        assert.equal(first.unattributable >= 1, true, "an unowned row is counted unattributable");
+        assert.equal((await store.get("tr_sweep~unowned")).content, "UNOWNED-bytes", "an unowned row is never deleted by a session sweep");
+        const second = await del("sess-X");
+        assert.equal(second.deleted, 0, "a repeated sweep deletes nothing");
+        assert.equal((await store.get("tr_sweep~other")).content, "OTHER-bytes");
+        onOptionalMember?.({ member: "deleteBySession", status: "verified" });
+    });
     await settle();
 }

package/dist/core/tighten-task-spec.js

@@ -25,6 +25,24 @@ export function tightenTaskSpec(base, overrides) {
             merged[field] = [...new Set([...(b ?? []), ...(o ?? [])])];
         }
     }
+    if (base.readFace === "roots" && overrides.readFace === "open") {
+        throw new TaskSpecTightenError('tightenTaskSpec: cannot loosen readFace from "roots" to "open" (override may only tighten)');
+    }
+    if (base.readFace !== undefined || overrides.readFace !== undefined) {
+        merged.readFace = base.readFace === "roots" || overrides.readFace === "roots" ? "roots" : (overrides.readFace ?? base.readFace);
+    }
+    if (base.readDenyPatterns !== undefined || overrides.readDenyPatterns !== undefined) {
+        const seen = new Set();
+        const union = [];
+        for (const e of [...(base.readDenyPatterns ?? []), ...(overrides.readDenyPatterns ?? [])]) {
+            const key = typeof e === "string" ? `i:${e}` : `${e.caseSensitive === true ? "s" : "i"}:${e.pattern}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            union.push(e);
+        }
+        merged.readDenyPatterns = union;
+    }
     if (base.handsReadOnly === true && overrides.handsReadOnly === false) {
         throw new TaskSpecTightenError("tightenTaskSpec: cannot loosen handsReadOnly from true to false (override may only tighten)");
     }

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

@@ -175,6 +175,19 @@ export type PermissionResult = {
      *  consumer (approval card, wire frame) can tell the person their rule is alive, just outranked.
      *  Absent ⇒ no rule matched, or the ask was cleared normally. */
     persistedRuleShadowed?: string;
+    /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
+     *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
+     *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
+     *  per-call instruction — CC draws the same line: only a matched ask rule diverts the auto-mode
+     *  lane, a mode-default ask stays classifier-eligible). Consumer: the gate's auto-mode classifier
+     *  step refuses to resolve an ask carrying it — a person's standing "ask me each time" is not
+     *  classifier hesitation, so a classifier verdict must not be the thing that clears it. A policy
+     *  self-declaring the member only ever OPTS ITS OWN ask OUT of classifier auto-resolution
+     *  (tightening — the false-claim direction is safe, unlike the engine-stamped `"hook"` word whose
+     *  risk was laundering provenance AWAY). {@link combinePolicies} carries it onto the surviving ask
+     *  when ANY folded-away concurrent ask bore it (monotone, tighten-only); it is consumed inside the
+     *  gate and deliberately NOT copied onto the park/approval-card request. */
+    matchedAskRule?: string;
 } | {
     action: "deny";
     updatedInput?: unknown;
@@ -723,7 +736,13 @@ export interface AskRequest {
      *  (codex adversarial round, confirmed). NOT the same fact as {@link fromSubagent} either: that is
      *  the design/153 attribution discriminator (`parentTaskId` presence), which a directly-started
      *  workflow's children lack even though refusals must still speak the child posture to them.
-     *  `readonly`, trusted (internals never ride a TaskSpec), sync-path-only like its siblings. */
+     *  `readonly`, trusted (internals never ride a TaskSpec), sync-path-only like its siblings.
+     *
+     *  Key division, at a glance (the two child-ish keys serve DIFFERENT faces — neither implies the other):
+     *  - `fromSubagent` — ATTRIBUTION: "a nameable parent task issued this" (`parentTaskId` presence);
+     *    drives display/identity surfaces.
+     *  - `isDelegatedChild` — REFUSAL POSTURE: "no user turn ever lands in this run's transcript";
+     *    drives which deny text the model is told (stop-and-wait vs adapt-or-report), forks included. */
     readonly isDelegatedChild?: true;
     /** RB-203 (codex review, confirmed P1) — carried from the originating {@link PermissionResult}'s ask
      *  variant of the same name: `true` ⇒ {@link resolveAsk} must not let a blanket `onAsk: "allow"`

package/dist/core/tool-policy.js

@@ -317,6 +317,7 @@ export function combinePolicies(...policies) {
             let current = req;
             let rewrite;
             let settled;
+            let ruleAskText;
             for (const p of policies) {
                 const d = refuseOutOfContractDecision(await p.check(current, signal));
                 if (d.action === "deny") {
@@ -334,10 +335,14 @@ export function combinePolicies(...policies) {
                 if (d.action === "ask" && (asked === undefined || (d.requiresRealApproval === true && asked.requiresRealApproval !== true))) {
                     asked = d;
                 }
+                if (d.action === "ask" && d.matchedAskRule !== undefined && ruleAskText === undefined) {
+                    ruleAskText = d.matchedAskRule;
+                }
             }
             if (asked) {
                 const merged = rewrite?.updatedInput;
-                return merged !== undefined ? { ...asked, updatedInput: merged } : asked;
+                const withMark = ruleAskText !== undefined && asked.matchedAskRule === undefined ? { ...asked, matchedAskRule: ruleAskText } : asked;
+                return merged !== undefined ? { ...withMark, updatedInput: merged } : withMark;
             }
             const allowed = rewrite ?? ALLOW;
             return settled !== undefined ? { ...allowed, settledBy: settled } : allowed;
@@ -891,9 +896,31 @@ export async function resolveAsk(req, onAsk, signal) {
         };
     }
     if (typeof ok === "object" && ok !== null) {
-        const supplied = ok.settledBy;
-        const allowed = ok.allow;
-        const suppliedEdit = ok.updatedInput;
+        let supplied;
+        let allowed;
+        let suppliedEdit;
+        try {
+            supplied = ok.settledBy;
+            allowed = ok.allow;
+            suppliedEdit = ok.updatedInput;
+        }
+        catch (err) {
+            return {
+                action: "deny",
+                message: `the approver's outcome for "${req.toolName}" could not be read (${describeThrown(err)}) — denied fail-closed`,
+                decisionReason: "mode",
+                settledBy: "aborted",
+            };
+        }
+        if (typeof allowed !== "boolean") {
+            return {
+                action: "deny",
+                message: `the approver for "${req.toolName}" returned an object whose allow is not a boolean ` +
+                    `(got ${allowed === null ? "null" : typeof allowed}) — a verdict is exactly true or false; denied fail-closed`,
+                decisionReason: "mode",
+                settledBy: "aborted",
+            };
+        }
         if (supplied !== undefined && supplied !== "human" && supplied !== "timeout") {
             return {
                 action: "deny",