@sema-agent/core 7.33.7 → 7.34.0

package/dist/engine/harness/types.d.ts

@@ -397,16 +397,15 @@ export interface FileSystem {
     listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     /** Return the canonical path for an existing path, resolving symlinks where supported. */
     canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /**
-     * VENDORED EDIT (design/72 §2.1, additive/backward-compatible): read a symlink's raw target (one
-     * hop, NOT followed). Optional — an env that omits it falls back to best-effort canonicalization
-     * for a DANGLING leaf symlink (a symlink whose target doesn't exist yet, which `canonicalPath`'s
-     * `realpath` can't resolve). Needed so a sensitive-path guard / containment check sees the real
-     * target of `write_file innocent.txt` where `innocent.txt -> .git/hooks/payload`.
-     */
+    /** OPTIONAL: a symlink's raw target, one hop, not followed — so a path guard sees where `innocent.txt -> .git/hooks/payload`
+     *  writes although the target does not exist yet (`canonicalPath`'s `realpath` cannot resolve a DANGLING leaf link).
+     *  Omitted ⇒ such a leaf is canonicalized best-effort. */
     readLink?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     /** OPTIONAL: the LEAF symlink chain of `path` ({@link SymlinkChain}). Omitted, or `ok: false` ⇒ the path judges read the spelling and the canonical terminal only (the reach they had before this seat); a remote adapter answers in one `readlink` round trip and a caller never emulates it through {@link readLink}; bounded (64 hops, a cycle ends it), a network hop kept unprobed. */
     canonicalChain?(path: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
+    /** OPTIONAL: the identity of the object `path` names, links followed (`<device>:<inode>` on POSIX, exact): equal answers name one object, where
+     *  a firmlink or bind mount keeps its own {@link canonicalPath}. Home-anchored deny rows are placed by it; omitted ⇒ by spelling only. */
+    fileIdentity?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     /** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
     exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     /** Create a directory. Defaults: `recursive: true`, no abort signal. */

package/dist/engine/llm/types.d.ts

@@ -144,10 +144,8 @@ export interface StreamOptions {
      * (see BrainTimeoutConfig.firstTokenTimeoutMs, design/17 O5).
      */
     stallTimeouts?: StallTimeouts;
-    /**
-     * Maximum retry attempts for providers/SDKs that support client-side retries.
-     * For example, OpenAI and Anthropic SDK clients default to 2.
-     */
+    /** Per-call cap on the brain's transient retry budget: this call retries at most this many times, never more than
+     *  the brain is configured for. */
     maxRetries?: number;
     /**
      * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.

package/dist/engine/loop/types.d.ts

@@ -765,6 +765,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * keyed by the folded-away spelling must stay inert rather than land on the other tool. Absent on non-MCP tools.
      */
     mcpRemoteName?: string;
+    /**
+     * The MCP server's own read-only declaration (`annotations.readOnlyHint === true` on its tools/list entry), set by
+     * the MCP materializer. It answers ONE question: whether the `plan` mode leaves the tool to run (the reference's
+     * `isReadOnly` for a server's tool). It is never the tool's effect — a server's self-claim does not lower the
+     * repeat-safety effect below its fail-closed `write` default (only the caller's `toolAxes` does). Absent on non-MCP tools.
+     */
+    mcpReadOnlyHint?: true;
     /**
      * design/120 P1.5 (CC `isConcurrencySafe(parsedInput)` parity): INPUT-level concurrency refinement
      * for a tool whose safety depends on its arguments — CC's only real consumer is

package/dist/index.d.ts

@@ -62,6 +62,12 @@ export { probeMcpServers, type McpProbeResult } from "./core/mcp-probe.js";
 export { MCP_FAILURE_KINDS, MCP_DELIVERY_VERDICTS, MCP_LIVENESS_STATES, classifyMcpFailure, type McpFailure, type McpFailureKind, type McpDelivered, type McpLivenessState, type McpServerLiveness } from "./core/mcp-failure.js";
 export { MCP_INJECTION_DROP_REASONS, MCP_INJECTION_DROP_TEXT, mcpInjectionDroppedNotice, type McpInjectionDropReason, type McpInjectionDropFacts } from "./core/mcp-injection-drop.js";
 export { askUnresolvableNotice, type AskUnresolvableFacts } 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, type MaterializedA2a, type A2aPeerStatus, type A2aRefreshResult, type A2aToolAxis } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf, type ProtocolNamespace, type ProtocolId } from "./core/protocol-table.js";
 export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions, } from "./core/session-policy-store.js";
@@ -104,7 +110,7 @@ export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, Ch
 export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } 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, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } 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, type DenyFace, type PathRuleDenyRow, type WriteDenyMatcher, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
 export { deploymentFaceClampNotice, resolveContainmentFace, type ContainmentFace, type ContainmentFaceInputs, type ContainmentFaceKind, type ContainmentFaceLayer, } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, type WriteProtectedEntry, type WriteProtectedRow, type WriteProtectedKind, type WriteProtectedHit, type WriteProtectionMatcher, type WriteProtectionVerdict, type WriteProtectionViewAbsence, type WriteProtectionJudgeContext, type WriteProtectionCompileOptions, type WriteProtectionCheck, WRITE_PROTECTION_TARGET_VIEWS, type WriteProtectionTargetView, type WriteProtectionMount, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
@@ -183,14 +189,18 @@ export { createAllowDenyPolicy, createApprovalPolicy,
  *  members that seat has no lane for (`"unavailable"`, a routing answer; `updatedInput`, an operator edit a
  *  policy verdict cannot get re-adjudicated). Exported so a host can NAME it instead of deriving it through
  *  `Parameters<typeof createApprovalPolicy>[0]["approve"]`. */
-type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
-export { type AskOrigin, ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, type RuleStoreUnreadable, isRuleStoreUnreadable, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate } from "./core/ask-origin.js";
+export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
+export { modePolicyOf, type ModePolicy, PERMISSION_MODE_FOLD_REASONS, type PermissionModeFoldReason, type PermissionModeReceipt, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
+export { readDenyClassifierRules, renderClassifierDenyRules, type DerivedDenyRule } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";
-export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, screenGateOutcome } from "./core/gate-outcome.js";
+export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, type ModeRelease, type ModeRefusal, screenGateOutcome } from "./core/gate-outcome.js";
 export { type AskCarry } from "./core/hooks.js";
 export { SWAPPABLE_DEP_SEATS, SWAP_SEAT_NOTICE, isSwappableDepSeat, screenSwappableDeps, type SwappableDepSeat, type SwappableDeps } from "./core/swappable-deps.js";
 export { parseAutoModeResponse, createAutoModeDecider, AUTO_MODE_UNAVAILABLE_CAUSES, isAutoModeUnavailableCause, classifierUnavailableDenyMessage, classifierParseFailureDenyMessage, AUTO_MODE_PARSE_FAILURES, isAutoModeParseFailure, type AutoModeParseFailure, type AutoModeUnavailableCause, AUTO_MODE_CLASSIFIER_FALLBACKS, isAutoModeClassifierFallback, AUTO_MODE_FALLBACK_CAUSES, isAutoModeFallbackCause, type AutoModeClassifierFallback, type AutoModeFallbackCause, type AutoModeClassifierRound, type AutoModeLadderRung, type AutoModeVerdict, type AutoModeDecider, type AutoModeDeciderOptions, type AutoModeClassified, type AutoModeClassifyFn, type AutoModeClassifyInput, createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence, unarmedWindow, type AutoModeDenialTracker, type AutoModeDenialLimitOptions, type DenialLimitCounts, type DenialLimitFallbackFace, type UnarmedDenialLimitFallback, type DenialLimitFallback, type DenialLimitVerdict, } from "./core/auto-mode.js";
+export type { ClassifierUnavailableSeat, ClassifierUnavailableInfo, ClassifierUnavailableDisposition, ClassifierUnavailableObserver } from "./core/classifier-unavailable-arm.js";
 export { AUTO_MODE_DENIAL_LIMIT_DEFAULTS, AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS, AUTO_MODE_CLASSIFIER_MAX_TOKENS } from "./core/auto-mode-defaults.js";
 export { classifierSeatModel, type ClassifierSeat } from "./core/runner/classifier-ladder.js";
 export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_MODE_DEFAULTS_SENTINEL, type AutoModeRules, type BuildAutoModePromptOptions, type AutoModeWindowOptions, } from "./core/auto-mode-prompt.js";
@@ -352,7 +362,7 @@ export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } f
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, ApproverPosture, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ReadRootGrantCandidate, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ReadRootGrantCandidate, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/index.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";
@@ -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";
@@ -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, 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/run-spec.d.ts

@@ -29,6 +29,7 @@ import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { TaskResult, TaskSpec } from "../core/types.js";
 import { type ToolPolicy } from "../core/tool-policy.js";
 import type { TaskOutcome } from "../core/task-outcome.js";
+import type { EngineNotice } from "../core/engine-notice.js";
 import { type OracleBaseline, type OracleGateResult, type OracleVerdict, type SpecContract } from "../core/spec-contract.js";
 export interface RunSpecOptions {
     /** Workcopy root — the containment root for frozenPaths, oracle cwd, and `spec.path` resolution. */
@@ -36,6 +37,9 @@ export interface RunSpecOptions {
     /** Per-run base spec (model/tools/toolPolicy/hooks/limits/…). `objective` is owned by runSpec (the
      *  spec framing); `toolPolicy` and `hooks` are COMPOSED with runSpec's, never replaced. */
     taskSpec: Omit<TaskSpec, "objective">;
+    /** Receives the oracle gates' once-per-process `config.secret_env_scrubbed` notice (`runOracle`'s `onNotice`);
+     *  absent ⇒ the console line. */
+    onNotice?: (notice: EngineNotice) => void;
 }
 export interface RunSpecOracleReport {
     /** Terminal adjudication (the authoritative bit — the stop gate only advises mid-run). */

package/dist/orchestration/run-spec.js

@@ -80,7 +80,8 @@ export async function runSpec(runner, contract, opts) {
     const startedAt = Date.now();
     const frozenResolved = resolveFrozenPaths(rootDir, contract.frozenPaths);
     const snapshot = snapshotFrozenPaths(frozenResolved);
-    const preflight = await runOracle(contract.oracle, rootDir, { signal: opts.taskSpec.signal });
+    const noticeSeat = opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {};
+    const preflight = await runOracle(contract.oracle, rootDir, { signal: opts.taskSpec.signal, ...noticeSeat });
     const baseline = captureBaseline(preflight);
     let oracleHadRedRun = preflight.verdict === "red";
     let oracleRuns = 1;
@@ -137,7 +138,7 @@ export async function runSpec(runner, contract, opts) {
             guardRestores += restoreFrozenPaths(snapshot, rootDir);
             if (!gateAbandoned) {
                 const gateSignal = ctx.signal !== undefined && opts.taskSpec.signal !== undefined ? AbortSignal.any([ctx.signal, opts.taskSpec.signal]) : (ctx.signal ?? opts.taskSpec.signal);
-                const report = await runOracle(contract.oracle, rootDir, { baseline, ...(gateSignal !== undefined ? { signal: gateSignal } : {}) });
+                const report = await runOracle(contract.oracle, rootDir, { baseline, ...(gateSignal !== undefined ? { signal: gateSignal } : {}), ...noticeSeat });
                 if (ctx.signal?.aborted === true)
                     return undefined;
                 oracleRuns++;
@@ -175,7 +176,7 @@ export async function runSpec(runner, contract, opts) {
         hooks,
     });
     guardRestores += restoreFrozenPaths(snapshot, rootDir);
-    const final = await runOracle(contract.oracle, rootDir, { baseline });
+    const final = await runOracle(contract.oracle, rootDir, { baseline, ...noticeSeat });
     oracleRuns++;
     if (final.verdict === "red") {
         oracleHadRedRun = true;

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/fs-atomic.js

@@ -4,6 +4,7 @@ import { hrtime } from "node:process";
 import { basename, dirname, join, resolve as resolvePath } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { execFileSync } from "node:child_process";
+import { scrubSecretEnv } from "../../core/secret-env.js";
 import { physicalPathOf, physicalPathOfExisting } from "../../core/physical-path.js";
 import { thrownText } from "../../core/thrown-value.js";
 const SAFE_COMPONENT = /^[A-Za-z0-9_.-]+$/;
@@ -637,7 +638,7 @@ function probeStartTimesOnce(pid) {
             encoding: "utf8",
             timeout: START_TIME_PROBE_TIMEOUT_MS,
             stdio: ["ignore", "pipe", "ignore"],
-            env: { ...process.env, LC_ALL: "C", LANG: "C" },
+            env: { ...scrubSecretEnv(process.env), LC_ALL: "C", LANG: "C" },
         });
     }
     catch (err) {

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,49 @@
+/**
+ * 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 it. */
+export declare function composeReadChecks(stations: ReadonlyArray<{
+    readonly check: ShellReadCheck;
+    readonly tools: ReadonlySet<string>;
+}>): ShellReadCheck | undefined;