@sema-agent/core 7.33.8 → 7.35.0

package/dist/index.js

@@ -29,7 +29,7 @@ export { StdioLspTransport } from "./engine/lsp/stdio-lsp-transport.js";
 export { encodeFrame, createFrameDecoder } from "./engine/lsp/frame-decoder.js";
 export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, MODEL_ROLES, } from "./core/roles.js";
 export { selectModel, selectModelOrThrow } from "./core/select-model.js";
-export { BrainError, classifyHttp } from "./brain/errors.js";
+export { BrainError, classifyHttp, isProviderEchoShape, PROVIDER_ECHO_SHAPE } from "./brain/errors.js";
 export { looksDegenerate, inspectDegenerate, trimDegenerateTail } from "./brain/repetition.js";
 export { computeCostMicroUsd, isModelPriced, modelCostToPricing, } from "./core/pricing.js";
 export { cacheFamilyOf, promptTokensOf, uncachedInputTokensOf } from "./core/runner/usage-accounting.js";
@@ -48,6 +48,12 @@ export { probeMcpServers } from "./core/mcp-probe.js";
 export { MCP_FAILURE_KINDS, MCP_DELIVERY_VERDICTS, MCP_LIVENESS_STATES, classifyMcpFailure } from "./core/mcp-failure.js";
 export { MCP_INJECTION_DROP_REASONS, MCP_INJECTION_DROP_TEXT, mcpInjectionDroppedNotice } from "./core/mcp-injection-drop.js";
 export { askUnresolvableNotice } from "./core/ask-unresolvable-notice.js";
+export { ASK_UNRESOLVABLE_CAUSES } from "./core/ask-unresolvable-notice.js";
+export { DURABLE_MANDATE_SOURCES } from "./core/tool-policy.js";
+export { TERMINAL_CAUSE_IS_REPLAYABLE } from "./core/terminal-cause.js";
+export { RESERVED_AGENT_NAMES } from "./agents/subagent.js";
+export { WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS } from "./orchestration/workflow-size-guideline.js";
+export { ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./core/untrusted-text.js";
 export { materializeA2aTools, A2aRpcError } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf } from "./core/protocol-table.js";
 export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, } from "./core/session-policy-store.js";
@@ -58,7 +64,7 @@ export { LOCKED_KEY_REGISTRY, resolveLockedKeys } from "./core/locked-config.js"
 export { BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, complianceCallDenial, resolveComplianceDenies, } from "./core/compliance.js";
 export { admitMemoryScopes, foldAdmissionFreeze, } from "./core/memory-admission.js";
 export { assertRetentionCapability, RETENTION_CASCADE_DOMAINS, RETENTION_CASCADE_EXEMPT, } from "./core/retention.js";
-export { GOVERNANCE_CODES, governanceRetryClass } from "./core/governance-codes.js";
+export { GOVERNANCE_CODES, governanceRetryClass, TOOL_DECLARATION_CODES } from "./core/governance-codes.js";
 export { NOTICE_AUDIENCE, noticeAudienceOf, ENGINE_NOTICE_CODES } from "./core/governance-codes.js";
 export { TtlSessionStore } from "./core/session-store.js";
 export { reconcileInterruptedSession, findOrphanToolCalls, } from "./core/session-reconcile.js";
@@ -82,7 +88,7 @@ export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
-export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, } from "./tools/fs/index.js";
+export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, READ_DENY_HOME_WORD, readDenyPatternRun, readDenyHomesOf, compileWriteDeny, DENY_FACES, } from "./tools/fs/index.js";
 export { deploymentFaceClampNotice, resolveContainmentFace, } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, WRITE_PROTECTION_TARGET_VIEWS, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } from "./core/tool-result-store.js";
@@ -111,7 +117,7 @@ export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, RESUPPLIED_FRAME_PREAMBLE, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, NOTIFICATION_INJECTION_OUTCOMES, isNotificationInjectionOutcome, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, HANDBACK_STATES, COMPACTION_KINDS, handbackStateOf, terminalFrameFacets, } from "./core/task-notification.js";
 export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, TOOL_PATH_ABSENCES, TOOL_WIRE_NAME_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_CARD_ID_MAX_CHARS, TOOL_KEY_MAX_CHARS, TOOL_KEYS_MAX, RENDER_HINT_MAX_CHARS, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_LIST, pathTargetSlotOnly, } from "./core/tool-face.js";
 export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, pathConfinableWriteToolNames, skillScopeWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
-export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
+export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, rosterToolName, ruleNamesOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
 export {} from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf } from "./core/effective-path-target.js";
 export { pathFamilyOf, isAbsoluteForFamily, pathIdentityOf, win32NamespaceScreen, WIN32_NAMESPACE_REFUSALS } from "./tools/fs/safety.js";
@@ -148,9 +154,12 @@ export { hasScheduler, isValidCronExpr, SchedulerError } from "./core/scheduler.
 export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
-export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export {} from "./core/read-root-grant-screen.js";
-export { ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, isRuleStoreUnreadable, PERSISTED_RULE_MANDATES, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { modePolicyOf, PERMISSION_MODE_FOLD_REASONS, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
+export { readDenyClassifierRules, renderClassifierDenyRules } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, isSettlementKind, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, screenGateOutcome } from "./core/gate-outcome.js";
 export {} from "./core/hooks.js";

package/dist/orchestration/workflow-governance.js

@@ -298,7 +298,7 @@ function pickWhitelist(scriptSpec) {
         if (!Array.isArray(readDenyPatternsRaw)) {
             throw new WorkflowScriptError('agent(spec): `readDenyPatterns` must be an array of deny entries (a "/"-separated segment run such as ".ssh", or { pattern, caseSensitive? })');
         }
-        const entries = mapUntrustedArray(readDenyPatternsRaw, "agent(spec): `readDenyPatterns`", MAX_SCRIPT_DENY_ENTRIES, "Every entry is judged against every path the child reads, for the child's whole run; the deployment's own entries, and whichever built-in tiers the deployment switched on (none by default), are in force on top of these.", pickReadDenyEntry);
+        const entries = mapUntrustedArray(readDenyPatternsRaw, "agent(spec): `readDenyPatterns`", MAX_SCRIPT_DENY_ENTRIES, "Every entry is judged against every path the child reads, for the child's whole run; the deployment's own entries, and whichever built-in tiers the deployment has on (by default the credentials and home agent-config tiers), are in force on top of these.", pickReadDenyEntry);
         try {
             compileReadDeny(entries, "agent(spec).readDenyPatterns");
         }

package/dist/orchestration/workflow-primitives.d.ts

@@ -52,7 +52,7 @@ parentReadFace?: () => TaskSpec["readFace"],
  *  stricter-wins into every spawned child on its own seat (the two seats never read each other). */
 parentWriteFace?: () => TaskSpec["writeFace"], 
 /** Twin of the above for the deny-set additions (the extra entries the host's own deployment/task
- *  layers stacked on; the built-in rows the DEPLOYMENT switched on — none by default — apply beside them). */
+ *  layers stacked on; the built-in rows the DEPLOYMENT's tier selection activates apply beside them). */
 parentReadDenyPatterns?: () => TaskSpec["readDenyPatterns"], 
 /** #345 ③ — the HOST task's write-hands clamp is ON (`spec.handsReadOnly === true`). Injected
  *  tighten-only into every spawned child, like the read-face clamp above; see the injection

package/dist/orchestration/workflow-size-guideline.js

@@ -1,10 +1,10 @@
 export const WORKFLOW_SIZE_GUIDELINES = ["unrestricted", "small", "medium", "large"];
 export const WORKFLOW_SIZE_GUIDELINE_DEFAULT = "medium";
-export const WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS = {
+export const WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS = Object.freeze({
     small: 5,
     medium: 15,
     large: 50,
-};
+});
 export function normalizeWorkflowSizeGuideline(value) {
     return WORKFLOW_SIZE_GUIDELINES.includes(value) ? value : undefined;
 }

package/dist/stores/file/index.d.ts

@@ -96,8 +96,8 @@ export interface FileStorageBackendOptions {
      * grows the seat later is wired here in the same constructor.
      *
      * The payload is the UNION shape ({@link FileStorageCorruptReadInfo}): `path` + `reason` always,
-     * with the session-policy face's `sessionId`/`principal` present only when the reading store keys by
-     * them. One sink for one failure grammar — a host does not register three.
+     * `sessionId` when the disclosure is about one session (the session store and the session-policy face),
+     * `principal` when the read was keyed by one. One sink for one failure grammar — a host does not register three.
      */
     onCorruptRead?: (info: FileStorageCorruptReadInfo) => void;
 }
@@ -110,7 +110,9 @@ export interface FileStorageBackendOptions {
  * that replay's count (`"replay"`) from a disclosure about a file or directory as a whole (`"file"`).
  */
 export type FileStorageCorruptReadInfo = CorruptReadInfo & {
-    /** Present only when the reading store keys by session (the session-policy face). */
+    /** Present when the disclosure is about ONE session: the session-policy face's rows, and the session store's
+     *  log of that session (its skipped records and tally, or the log skipped from a listing). Absent on a
+     *  disclosure about a directory as a whole or about a store not keyed by session. */
     sessionId?: string;
     /** Present only when the read was keyed by a principal. */
     principal?: string;

package/dist/stores/file/session-store.d.ts

@@ -14,8 +14,14 @@ export interface FileSessionRepoOptions {
      * Never fires on plain ENOENT / `not_found` — that is honest absence, and the torn TAIL stays silent
      * too (dying mid-write is the append log's documented crash-recovery shape, not corruption).
      * Swallow-guarded: a throwing sink cannot re-introduce the fault the fail-open avoids.
+     *
+     * `sessionId` rides every disclosure about ONE session — its log's skipped records and tally, and its log
+     * skipped from a listing — naming the session the repo was reading (on a listing, the id its file name
+     * spells); a disclosure about the sessions directory itself carries none.
      */
-    onCorruptRead?: (info: CorruptReadInfo) => void;
+    onCorruptRead?: (info: CorruptReadInfo & {
+        sessionId?: string;
+    }) => void;
 }
 export declare class FileSessionRepo implements SessionRepo {
     private readonly dir;
@@ -26,7 +32,7 @@ export declare class FileSessionRepo implements SessionRepo {
      *  check on the way out possible without pinning a storage the table itself only holds weakly. */
     private readonly joined;
     constructor(root: string, opts?: FileSessionRepoOptions);
-    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}. */
+    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}'s whole-file level; `sessionId` when the file is one session's log. */
     private disclose;
     private pathFor;
     /**

package/dist/stores/file/session-store.js

@@ -74,8 +74,8 @@ export class FileSessionRepo {
         ensureDir(this.tmpDir);
         this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
     }
-    disclose(path, reason) {
-        this.onCorruptRead?.({ kind: "file", path, reason });
+    disclose(path, reason, sessionId) {
+        this.onCorruptRead?.({ kind: "file", path, reason, ...(sessionId !== undefined ? { sessionId } : {}) });
     }
     pathFor(id) {
         return join(this.dir, `${sanitizePathComponent(id)}${SUFFIX}`);
@@ -89,7 +89,7 @@ export class FileSessionRepo {
         const lines = readJsonlRecords(path, (info) => {
             if (info.kind === "replay")
                 tally = info;
-            this.onCorruptRead?.(info);
+            this.onCorruptRead?.({ ...info, sessionId: id });
         }, SESSION_LINE_JUDGE);
         let meta;
         const entries = [];
@@ -174,7 +174,7 @@ export class FileSessionRepo {
             }
             catch (err) {
                 if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the listing`);
+                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the listing`, id);
                 }
             }
         }
@@ -203,7 +203,7 @@ export class FileSessionRepo {
             }
             catch (err) {
                 if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the placed listing`);
+                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the placed listing`, id);
                 }
                 continue;
             }

package/dist/tools/artifact/artifact-tool.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The `Artifact` tool: one tool, `action`-multiplexed, assembled from the host's capability declaration.
+ * The action enum, the parameter set and the description are all functions of `capabilities` — the
+ * implementation behind the seam is never inspected. Session state (the version tracked per URL and the
+ * local-path → URL binding that makes "same file path ⇒ same page" hold) lives in this factory's closure,
+ * fresh per run, never checkpointed.
+ */
+import { type PermissionMode } from "../../core/ask-origin.js";
+import { type EngineNotice } from "../../core/engine-notice.js";
 import { type ArtifactHost, type ArtifactHostCapabilities } from "../../core/artifact-host.js";
 import { type OnAsk } from "../../core/tool-policy.js";
 import type { ToolSpec } from "../../core/types.js";
@@ -42,6 +51,14 @@ export interface ArtifactToolOptions {
      *  = the run has no ask face, and a shared read is then REFUSED fail-closed (`artifact.refused`, content withheld) —
      *  never silently delivered. */
     onAsk?: OnAsk;
+    /** The run's effective permission mode, read at each shared-read consent (a steer moves it). The consent ask is
+     *  arbitrated as the gate's asks are (class `artifact_shared_read`): `bypassPermissions` RELEASES the read — delivered,
+     *  announced once per run through `onNotice`, and NOT remembered as an approval (a mode release is not a person's
+     *  nod; a later `default` leg asks) — `dontAsk` refuses it, every other mode asks the approver. Absent ⇒ no arbitration
+     *  (the approver decides, or the read is withheld with none). */
+    permissionMode?: () => PermissionMode;
+    /** The notice sink the release account rides (`permission.ask_released_by_mode`, once per run for this class). */
+    onNotice?: (notice: EngineNotice) => void;
 }
 /** Supporting files per publish (upstream cap); enforced in the schema AND in the body, for callers that bypass the schema. */
 export declare const MAX_FILES_PER_PUBLISH = 255;

package/dist/tools/artifact/artifact-tool.js

@@ -1,3 +1,5 @@
+import { arbitrateByMode, classifyAsk } from "../../core/ask-origin.js";
+import { deliverEngineNotice } from "../../core/engine-notice.js";
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { ARTIFACT_ACTION_CONCURRENCY_SAFE, ARTIFACT_COMMIT_THROW_OUTCOME, ARTIFACT_FAILURE_RESULT_CODE, ARTIFACT_HOST_ERROR_CODE, ARTIFACT_LIST_SCOPES, ARTIFACT_PLANE_CONTENT_ORIGIN, ARTIFACT_PUBLISH_CONTEXTS, } from "../../core/artifact-host.js";
@@ -128,7 +130,8 @@ function buildSchema(caps) {
 const invalid = (text) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", invalidArguments: true });
 const typed = (code, text, extra = {}) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", code: ARTIFACT_FAILURE_RESULT_CODE[code], ...extra });
 export function createArtifactTool(opts) {
-    const { host, capabilities: caps, runId, taskId, sessionId, agentName, readLocalFile, onAsk } = opts;
+    const { host, capabilities: caps, runId, taskId, sessionId, agentName, readLocalFile, onAsk, permissionMode, onNotice } = opts;
+    let releaseAnnounced = false;
     const versions = new Map();
     const bindings = new Map();
     const occurrences = new Map();
@@ -316,6 +319,18 @@ export function createArtifactTool(opts) {
     const sharedReadConsent = (url, ref, ctx) => {
         if (sharedReadApproved.has(url))
             return Promise.resolve({ ok: true });
+        if (permissionMode !== undefined) {
+            const verdict = arbitrateByMode(permissionMode(), classifyAsk({ action: "ask", requiresRealApproval: true, guard: "artifact_shared_read" }, { contentQuestion: false, markedUnresolvable: false, org: undefined, tightened: undefined, mandateMarks: {} }));
+            if (verdict.kind === "released") {
+                if (!releaseAnnounced && onNotice !== undefined) {
+                    releaseAnnounced = true;
+                    deliverEngineNotice(onNotice, { code: "permission.ask_released_by_mode", message: `the ${verdict.mode} permission mode released a shared-artifact read (${inlineUntrusted(url, 300)}) without asking anyone; further shared reads of this run under the mode are released the same way`, detail: { mode: verdict.mode, askClass: verdict.askClass, count: 1, firstToolCallId: ctx.toolCallId, ...(sessionId !== undefined ? { sessionId } : {}), runId } });
+                }
+                return Promise.resolve({ ok: true });
+            }
+            if (verdict.kind === "denied_by_mode")
+                return Promise.resolve({ ok: false, reason: `the ${verdict.mode} permission mode refuses to read another person's artifact without approval` });
+        }
         const pending = consentInFlight.get(url);
         if (pending !== undefined)
             return pending;

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

@@ -15,7 +15,7 @@ import { type LexedCommand, type LexedSegment, type LexedWord, type ShellLex, ty
  * hostname), and `file` (`-C -m` → compiles/writes a magic file) were REMOVED — each is read-only by NAME
  * but state-MUTATING with args, which an argv[0]-only filter cannot tell apart. Leaving them in defeated
  * both the `effect:read` truthfulness here and the classifier's irreversibility promise (a `date -s` would
- * auto-allow an irreversible clock jump under `shellGate:"classify"`).
+ * auto-allow an irreversible clock jump on the full shell face).
  *
  * Rows 3-4 are the CC-anchored expansion — the members of CC's safe-command
  * set (pretty223.js:420513-420565 `e6s`; identical in the 220 corpus; the 220→245 campaign diff records
@@ -223,7 +223,7 @@ export declare function splitShellCompoundSegments(source: string, options?: {
     reject: string;
 };
 /**
- * Compound read-only classification for the `bash` CLASSIFY face (shellGate:"classify").
+ * Compound read-only classification for the `bash` full-shell face (the shape tier).
  * Splits a command on the connector set `;` `&&` `||` `|` and passes every segment through
  * {@link coarseReadonlyCheck} (the single {@link parseLeadingCommandName} parser + bare-name allowlist).
  * All segments green ⇒ read-only. Returns a reason when rejected, else undefined.
@@ -304,8 +304,11 @@ export interface BashReadonlyRootBoundary {
      *  EVERY read face wires this one seat, the `bash_readonly` shell included, at BOTH of its judging
      *  moments — roots answer WHERE a command may read and the allowlist WHICH verb runs, neither answers
      *  WHICH FILES are off the table. What this seat is and is not is stated once, at
-     *  `shell.read_boundary.friction_floor`. */
-    denyMatch?: (resolvedPath: string) => string | null;
+     *  `shell.read_boundary.friction_floor`. `walked` — the path is a member a traversal enumerated, not a
+     *  spelling of the command ({@link import("./read-deny.js").ReadDenyMatcher.matchPath}). */
+    denyMatch?: (resolvedPath: string, opts?: {
+        readonly walked?: boolean;
+    }) => string | null;
     /** What the wired {@link denyMatch} judge would apply — the ACTIVE deny patterns. Read for ONE question:
      *  is there anything for a traversal to defeat? EMPTY ⇒ the judge refuses nothing, so a walk under it
      *  bypasses nothing and {@link CompoundReadonlyVerdict.recursiveReadPaths} is not minted. ABSENT ⇒ the
@@ -328,7 +331,7 @@ export interface BashReadonlyRootBoundary {
  */
 export interface CompoundReadonlyVerdict {
     /** Demotion reason (the same string {@link classifyCompoundReadonly} returns), or undefined: the
-     *  command's SHAPE is not one the classify doctrine auto-allows. WHERE the command reads is not this
+     *  command's SHAPE is not one the shape tier auto-allows. WHERE the command reads is not this
      *  verdict's business — that is the gate's shell read station (`shell-read-check.ts`). */
     reason?: string;
 }
@@ -350,6 +353,24 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  *  operand scan below, which is safe for an unknown command because a bare word can only ever name
  *  something under the working directory. */
 export declare const NO_PATH_OPERAND_COMMANDS: ReadonlySet<string>;
+/** The no-path-operand programs that EVALUATE a word (`test -v 'a[$(…)]'` runs the substitution in the subscript): a word
+ *  the shell or that evaluation rewrites is handed over as any program's is; only their settled words name nothing. */
+export declare const NO_PATH_OPERAND_EVALUATORS: ReadonlySet<string>;
+/** The builtins whose `NAME=value` arguments are assignments bash performs (and exports, for `export`), never paths. */
+export declare const DECLARATION_BUILTINS: ReadonlySet<string>;
+/** The shell BUILTINS that open no file, start no program and evaluate nothing: an external program's loader reads its
+ *  environment (`LD_PRELOAD` for `sleep`), `printf` reads `TZ` for `%(…)T` and assigns through `-v`, `test -v` and an
+ *  array subscript evaluate arithmetic (which runs a `$(…)` inside it). A declaration builtin counts only bare — no option
+ *  word (`-i` evaluates the value) — and every inert segment's words carry no `[` `]` `$` or backquote. */
+export declare const INERT_BUILTINS: ReadonlySet<string>;
+/** The indices of the SETTLED words a {@link MESSAGE_SLOTS} row reads as message text under the subcommand's grammar:
+ *  the value of `-m` (attached, or the next word) or of `--message` (`=`, or the next word; an unambiguous prefix of it
+ *  counts). A word the shell rewrites is never claimed, and neither is any word another option consumes — those words
+ *  stay the verb-blind walk's. */
+export declare function messageSlotWords(program: string, words: readonly {
+    readonly folded: string;
+    readonly expands: unknown;
+}[], programIndex: number): Set<number>;
 /** True for a token that can denote a filesystem location OUTSIDE the working directory. A bare word
  *  (`foo`, `a.txt`, a grep pattern, an awk program) cannot: with no separator and no `..` it always
  *  resolves under the cwd, which the caller's cwd governance already covers.
@@ -934,8 +955,8 @@ export declare const POLL_LOOP_MAX_BEATS = 120;
 export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
 /**
  * The BOUNDED READ-ONLY POLL LOOP arm of the classify face. The compound classifier above rejects any
- * control structure (`for` is not an allowlisted name), which makes `shellGate:"classify"` behave like
- * `"always"` for a monitoring consumer whose whole idiom is `for i in $(seq 1 8); do tail -n 5 x.log;
+ * control structure (`for` is not an allowlisted name), which makes the shape tier behave like
+ * the `"always"` floor for a monitoring consumer whose whole idiom is `for i in $(seq 1 8); do tail -n 5 x.log;
  * sleep 2; done`. This arm accepts EXACTLY that grammar and nothing else. Returns the rejection
  * reason, or undefined when the command matches the grammar (⇒ safe to treat as reversible).
  *

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

@@ -162,7 +162,95 @@ export function formatOutOfRootReadApprovalOption(directory) {
 export const NO_PATH_OPERAND_COMMANDS = new Set([
     "pwd", "echo", "printf", "whoami", "uname", "which", "tr", "basename", "dirname",
     "cal", "uptime", "id", "groups", "nproc", "locale", "free", "true", "false", "seq", "expr", "type", "sleep",
+    "test", "[",
 ]);
+export const NO_PATH_OPERAND_EVALUATORS = new Set(["test", "["]);
+export const DECLARATION_BUILTINS = new Set(["export", "declare", "typeset", "local", "readonly"]);
+export const INERT_BUILTINS = new Set(["echo", "true", "false", "pwd", ...DECLARATION_BUILTINS]);
+const MESSAGE_SLOTS = {
+    git: {
+        globalPlain: ["-p", "--paginate", "-P", "--no-pager", "--bare", "--no-replace-objects", "--literal-pathspecs", "--glob-pathspecs", "--noglob-pathspecs", "--icase-pathspecs", "--no-optional-locks"],
+        globalValue: ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env", "--super-prefix"],
+        subcommands: {
+            commit: { plain: "apsnvqeioz", optional: "Su", value: "mFCct", longValue: ["message", "file", "template", "pathspec-from-file", "author", "date", "cleanup", "fixup", "squash", "trailer", "reuse-message", "reedit-message"] },
+            tag: { plain: "asfdvle", optional: "n", value: "mFu", longValue: ["message", "file", "local-user", "cleanup", "trailer", "sort", "format", "contains", "no-contains", "points-at", "merged", "no-merged"] },
+            merge: { plain: "nqve", optional: "S", value: "mFsX", longValue: ["message", "file", "strategy", "strategy-option", "into-name", "cleanup"] },
+            stash: { plain: "pkuaqS", optional: "", value: "m", longValue: ["message", "pathspec-from-file"] },
+        },
+    },
+};
+export function messageSlotWords(program, words, programIndex) {
+    const out = new Set();
+    const row = MESSAGE_SLOTS[program];
+    if (row === undefined)
+        return out;
+    let j = programIndex + 1;
+    for (; j < words.length; j++) {
+        const w = words[j].folded;
+        if (!w.startsWith("-"))
+            break;
+        if (row.globalValue.includes(w))
+            j++;
+        else if (!row.globalPlain.includes(w) && !row.globalValue.some((o) => o.startsWith("--") && w.startsWith(`${o}=`)))
+            return out;
+    }
+    const sub = row.subcommands[words[j]?.folded ?? ""];
+    if (sub === undefined)
+        return out;
+    const settled = (k) => words[k] !== undefined && words[k].expands === false;
+    let pending;
+    for (let k = j + 1; k < words.length; k++) {
+        const w = words[k].folded;
+        if (pending !== undefined) {
+            if (pending === "message" && settled(k))
+                out.add(k);
+            pending = undefined;
+            continue;
+        }
+        if (w === "--")
+            break;
+        if (!settled(k)) {
+            pending = "other";
+            continue;
+        }
+        if (!w.startsWith("-") || w === "-")
+            continue;
+        if (w.startsWith("--")) {
+            const eq = w.indexOf("=");
+            const name = w.slice(2, eq < 0 ? undefined : eq);
+            const takers = sub.longValue.filter((n) => n.startsWith(name));
+            const message = name.length > 0 && takers.length > 0 && takers.every((n) => n === "message") || name === "message";
+            if (eq >= 0) {
+                if (message)
+                    out.add(k);
+                continue;
+            }
+            if (takers.length > 0)
+                pending = message ? "message" : "other";
+            continue;
+        }
+        const letters = w.slice(1);
+        for (let i = 0; i < letters.length; i++) {
+            const c = letters[i];
+            if (sub.plain.includes(c))
+                continue;
+            if (sub.optional.includes(c))
+                break;
+            if (sub.value.includes(c)) {
+                if (i < letters.length - 1) {
+                    if (c === "m")
+                        out.add(k);
+                }
+                else
+                    pending = c === "m" ? "message" : "other";
+                break;
+            }
+            pending = "other";
+            break;
+        }
+    }
+    return out;
+}
 const XARGS_TARGETS_ACCEPTED_UNJUDGED = NO_PATH_OPERAND_COMMANDS;
 export function isPathShapedToken(tok) {
     return tok.includes("/") || tok.startsWith("~") || tok === "." || tok === "..";

package/dist/tools/fs/containment-face.d.ts

@@ -18,8 +18,8 @@ export declare function containmentFaceSeatName(kind: ContainmentFaceKind, layer
  *  screen the seats on runs that never mount hands. The resolver itself also runs on every hands-less
  *  leg; this screen still fires first, so a garbage value refuses before any leg-shape branching. */
 export declare function assertContainmentFaceValue(v: unknown, kind: ContainmentFaceKind, layer: ContainmentFaceLayer): ContainmentFace | undefined;
-/** Inputs to {@link resolveContainmentFace} — all structural/declaration facts, never permission modes
- *  (a deliberate axis separation: this shape carries facts, not verdicts). */
+/** Inputs to {@link resolveContainmentFace} — structural/declaration facts; a permission mode enters only as
+ *  the face its table row states ({@link modeFace}), never as a mode word. */
 export interface ContainmentFaceInputs {
     /** Which face is being resolved. Selects the seat spellings and the mint codes; the ORDER below is
      *  one body, identical for both. */
@@ -41,8 +41,13 @@ export interface ContainmentFaceInputs {
      *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — every
      *  exclusion source is spec-time-frozen, so this is always computable). When false, the roots fence
      *  is the ONLY boundary this face has, so no IMPLICIT default may open it; an EXPLICIT "open" on
-     *  either seat still wins (row 4 of the order is a default, not a clamp). */
+     *  either seat or the mode's face still wins (row 4 of the order is a default, not a clamp). */
     fullShellReachable: boolean;
+    /** The face the leg's permission MODE states (`ModePolicy.writeFace`: `bypassPermissions` ⇒ "open"; absent ⇒
+     *  the mode states nothing). Row 3′: read after the explicit seats and before the defaults — a seat's word (the
+     *  deployment's ceiling, a task's tighten) outranks it, and neither the read-only mount nor org governance
+     *  consults it. */
+    modeFace?: ContainmentFace;
     /** Observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
      *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
      *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
@@ -63,6 +68,7 @@ export interface ContainmentFaceInputs {
  *  2. org-governed: the task seat's "open" refuses (task layer only tightens); deps "open" wins;
  *     otherwise ROOTS.
  *  3. explicit seat: spec ?? deps.
+ *  3′. the mode's face ({@link ContainmentFaceInputs.modeFace}).
  *  4. bash-less mount: ROOTS (the fence is the only boundary there — "the fence guards nothing bash
  *     reaches anyway" does not hold, so no implicit default may open it).
  *  5. default: ROOTS — the engine never opens implicitly.

package/dist/tools/fs/containment-face.js

@@ -67,6 +67,8 @@ export function resolveContainmentFace(i) {
         return spec;
     if (deps !== undefined)
         return deps;
+    if (i.modeFace !== undefined)
+        return i.modeFace;
     if (!i.fullShellReachable)
         return "roots";
     return "roots";

package/dist/tools/fs/file-read-check.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The READ station of the file tools (Read / Grep / Glob) — the read face's twin of the shell read station, one gate
+ * input shape ({@link ShellReadCheck}) so the gate, the approved-edit re-judge and the resumed leg's belt read both:
+ * before approval, where the call's declared path target lands is resolved exactly as the tool will resolve it
+ * (`resolveKey` over the same spelling, base, roots, deny table and containment face), and a target OUTSIDE the read
+ * roots is an ORDINARY question — a person answers it, a persisted `Read(//dir/**)` row or the auto-mode classifier
+ * may, a permission mode arbitrates it — with the directory whose grant clears it on the card. The deny table and
+ * every other refusal stay the tool's own: this station judges containment only, after the deny judgment.
+ *
+ * A call whose out-of-root read the gate put to a question is ADMITTED for that one target when the gate applies the
+ * verdict ({@link ShellReadVerdict.admit}): the tool reads it once ({@link FileReadStation.admitted}), on the canonical
+ * key the station judged — a target that resolves elsewhere by then is refused by the tool's own fence, and a verdict
+ * the gate never received (its wait elapsed, the judgment threw) admits nothing.
+ */
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { ContainmentFace } from "./containment-face.js";
+import { type ReadDenyMatcher } from "./read-deny.js";
+import type { ShellReadCheck } from "./shell-read-check.js";
+export interface FileReadStation {
+    readonly check: ShellReadCheck;
+    /** The station's membership: the tool names whose declared read target it judges. */
+    readonly tools: ReadonlySet<string>;
+    /** Did the gate put THIS call's read of `canonicalKey` outside the roots to a question it then let through? Consumed
+     *  on a match: the admission covers one read of one target. */
+    readonly admitted: (toolCallId: string | undefined, canonicalKey: string) => boolean;
+}
+export interface FileReadStationOptions {
+    readonly env: ExecutionEnv;
+    readonly rootCanonical: string;
+    /** The extra read roots, read per call (a grant widens the live set). */
+    readonly roots: () => readonly string[];
+    readonly readDeny?: ReadDenyMatcher;
+    readonly readFace?: ContainmentFace;
+    readonly homeDir?: string;
+    /** The file tools this leg mounts (their catalog path target is the one judged). */
+    readonly tools: ReadonlySet<string>;
+    /** A target no answer may admit (the store-isolation rule's judgment, `rootAdmittingArtifactStore`): it is left to
+     *  the tool's own refusal, no question is raised for it. */
+    readonly excluded?: (canonicalKey: string) => boolean;
+    /** A target the tools' own fence admits without the roots (the engine's background output file,
+     *  `backgroundOutputReadExemption`): no question is put for it. */
+    readonly exempt?: (canonicalKey: string) => boolean;
+}
+export declare function createFileReadStation(opts: FileReadStationOptions): FileReadStation;
+/** One gate input over the leg's read stations: each call is judged by the station whose membership holds the first of
+ *  its names any station holds (the spelling first). */
+export declare function composeReadChecks(stations: ReadonlyArray<{
+    readonly check: ShellReadCheck;
+    readonly tools: ReadonlySet<string>;
+}>): ShellReadCheck | undefined;

package/dist/tools/fs/file-read-check.js

@@ -0,0 +1,79 @@
+import { effectivePathSpellingOf } from "../../core/effective-path-target.js";
+import { firstNamed, pathTargetOf, ruleNamesOf } from "../../core/tool-registry.js";
+import { fitMiddle, READ_DENY_SENTENCE_PART_MAX } from "./read-deny.js";
+import { resolveKey, violationDetails } from "./safety.js";
+import { grantOfferFor, parentDirLexically } from "./shell-read-judge.js";
+const ADMISSION_MAX = 1024;
+const VOUCH = { disposition: "vouch", finding: "none" };
+export function createFileReadStation(opts) {
+    const admissions = new Map();
+    const remember = (toolCallId, key) => {
+        if (admissions.size >= ADMISSION_MAX) {
+            const oldest = admissions.keys().next().value;
+            if (oldest !== undefined)
+                admissions.delete(oldest);
+        }
+        admissions.set(toolCallId, key);
+    };
+    const check = {
+        judge(call, args, cwd, signal, callOpts) {
+            const member = ruleNamesOf(call).find((n) => opts.tools.has(n));
+            if (member === undefined)
+                return null;
+            const toolName = call.toolName;
+            const selection = effectivePathSpellingOf({ toolName, args }, pathTargetOf(member), { root: opts.rootCanonical, cwd });
+            if (selection === undefined || "refused" in selection || selection.spelled === undefined)
+                return null;
+            const spelled = selection.spelled;
+            return (async () => {
+                const extra = opts.roots();
+                const r = await resolveKey(opts.env, opts.rootCanonical, spelled, signal, selection.base, extra, undefined, opts.readDeny, opts.readFace);
+                if (r.ok || r.violation.code !== "path_not_in_root" || r.violation.target === undefined || opts.excluded?.(r.violation.target) === true || opts.exempt?.(r.violation.target) === true)
+                    return VOUCH;
+                const target = r.violation.target;
+                const toolCallId = callOpts.toolCallId;
+                const roots = [opts.rootCanonical, ...extra];
+                const details = violationDetails(r.violation);
+                const allowed = fitMiddle(roots.join(", "), READ_DENY_SENTENCE_PART_MAX);
+                if (callOpts.seat === "rejudge") {
+                    return { disposition: "refuse", finding: "outside_roots", sentence: `Error (${toolName}): the approved edit reads "${fitMiddle(target, READ_DENY_SENTENCE_PART_MAX)}", outside the directories allowed for this session (${allowed}) — re-submit it as a fresh call and answer its card.`, details };
+                }
+                const info = pathTargetOf(member)?.absent === "base" ? await opts.env.fileInfo(target, signal) : undefined;
+                const readsDirectory = info?.ok === true && info.value.kind === "directory";
+                const offer = grantOfferFor(readsDirectory ? target : parentDirLexically(target), target, { roots, ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}) });
+                return {
+                    disposition: "ordinary",
+                    finding: "outside_roots",
+                    sentence: `reads outside the allowed directories for this session: "${fitMiddle(target, READ_DENY_SENTENCE_PART_MAX)}" is not under ${allowed}`,
+                    details,
+                    ...(offer !== undefined ? { readRootCandidate: { dir: offer.dir, ...(offer.covers !== undefined ? { covers: offer.covers } : {}), clearsThisAsk: true } } : {}),
+                    ...(toolCallId !== undefined ? { admit: () => remember(toolCallId, target) } : {}),
+                };
+            })();
+        },
+        unanswered: () => VOUCH,
+    };
+    const admitted = (toolCallId, key) => {
+        if (toolCallId === undefined || admissions.get(toolCallId) !== key)
+            return false;
+        admissions.delete(toolCallId);
+        return true;
+    };
+    return { check, tools: opts.tools, admitted };
+}
+export function composeReadChecks(stations) {
+    if (stations.length === 0)
+        return undefined;
+    if (stations.length === 1)
+        return stations[0].check;
+    const byName = new Map();
+    for (const s of stations)
+        for (const n of s.tools)
+            if (!byName.has(n))
+                byName.set(n, s);
+    const stationOf = (call) => firstNamed(byName, ruleNamesOf(call))?.value;
+    return {
+        judge: (call, args, cwd, signal, callOpts) => stationOf(call)?.check.judge(call, args, cwd, signal, callOpts) ?? null,
+        unanswered: (call, cause) => (stationOf(call) ?? stations[0]).check.unanswered(call, cause),
+    };
+}