@sema-agent/core 7.3.0 → 7.4.0

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

@@ -19,6 +19,26 @@ export type StreamFn = LlmStreamFn;
  *   while tool-result message artifacts are emitted later in assistant source order.
  */
 export type ToolExecutionMode = "sequential" | "parallel";
+/**
+ * The verdict a tool's INPUT PRE-VALIDATION returns (see {@link AgentTool.validateInput}). `ok: true`
+ * (or an `undefined` return) lets the call proceed to the gate; `ok: false` refuses it BEFORE any
+ * permission question is asked — `message` is the model-facing text (the same text the tool's own
+ * execution would have produced for the same input, so the refusal reads identically either way) and
+ * `code` an optional machine-readable reason that rides the error result's structured details.
+ */
+export type ToolInputVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    code?: string;
+};
+/** The context an input pre-validation hook receives: the call's identity and its abort signal, and
+ *  nothing else — a validator reads state, it does not act on the run. */
+export interface ToolInputValidationContext {
+    toolCallId: string;
+    signal?: AbortSignal;
+}
 /**
  * Controls how many queued user messages are injected when the agent loop reaches a queue drain point.
  *
@@ -527,6 +547,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * signal re-check, which has always minted its abort result with no details.
      */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /**
+     * Fault seat for a THROWING {@link AgentTool.validateInput}: the loop reads the throw as "no
+     * verdict" (the call proceeds to the gate as if the tool had no validator) and reports the fault
+     * here so a host can disclose it. Must not throw; a throwing sink is swallowed.
+     */
+    onToolInputValidationFault?: (info: {
+        toolName: string;
+        toolCallId: string;
+        error: unknown;
+    }) => void;
     /**
      * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.
      *
@@ -684,6 +714,18 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      *  (boundInputHash binds args, never the preview). NEVER adjudication input. Mechanism-neutral:
      *  any tool may declare one (run_workflow projects its script meta). */
     approvalPreview?: (args: unknown) => unknown;
+    /**
+     * OPTIONAL input pre-validation, run by the loop AFTER schema validation and BEFORE the tool-call
+     * gate (permission hooks, policy, the human/classifier ask). A refusal is returned to the model as a
+     * typed error result and no question is ever asked for the call — the point of the seat: a call the
+     * tool would refuse on its own precondition (a file edit whose target was never read this session)
+     * must not cost the operator an approval card it can only ever fail on. Pure by contract: reads
+     * state (read-tracking, path grammar), never acts. A THROWING validator is read as "no verdict"
+     * (the call proceeds to the gate; the fault is disclosed through the loop's fault seat) — a broken
+     * validator must not refuse tools. The tool's own execution keeps validating the same precondition
+     * (the two reads are not one atomic step, and direct `execute` callers skip this seat).
+     */
+    validateInput?: (args: Static<TParameters>, ctx: ToolInputValidationContext) => Promise<ToolInputVerdict | undefined> | ToolInputVerdict | undefined;
     /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
     execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
     /**

package/dist/index.d.ts

@@ -119,13 +119,13 @@ export { createFsWriteGatePolicy, type FsWriteGatePolicyOptions } from "./core/f
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, type TaskNotificationPayload, type TaskNotificationStatus, type ExternalNotificationInput, type SystemInjection, type SystemInjectionPriority, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, type SemaProvenance, } from "./core/task-notification.js";
-export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, type SubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, type WiringManifest, type WiringFacts, type WiringLegKind, type AskSeamForm, type AskEffective, type QuestionChannelState, type SeamProvenance, type ParkLaneReason, type ManifestDurability, type StaticWiringDeps, type StaticWiringSpec, } from "./core/wiring-manifest.js";
+export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, type SubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, type AutoModeArmReason, type WiringManifest, type WiringFacts, type WiringLegKind, type AskSeamForm, type AskEffective, type QuestionChannelState, type SeamProvenance, type ParkLaneReason, type ManifestDurability, type StaticWiringDeps, type StaticWiringSpec, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, type ParkSelfCheckResult, type ParkProbeFinding, type ParkProbeFindingCode, } from "./core/park-selfcheck.js";
 export { type StoreDurability } from "./core/checkpoint-store.js";
 export { type StoreFidelity } from "./core/checkpoint-store.js";
 export { projectHumanInput, buildHumanInputEvent, type HumanInputSource, type HumanInputFrame, type HumanInputEvent, type HumanInputDelivery, } from "./core/human-input-projection.js";
 export { TaskRegistry, defaultTaskRegistry, createTaskOutputTool, createTaskStopTool, type SemaTaskType, type SemaTaskStatus, type SemaTaskHandle, type ParkedClaimTicket, type TaskAccess, type UnifiedTaskOutput, type TaskRetrievalStatus, type StopSource, type RegisterMonitorInput, type MonitorTimers, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccessWorkflowRun, DURABLE_AGENT_HANDLE_RE, } from "./core/task-registry.js";
-export { InMemoryMailboxStore, type MailboxStore, type MailboxMessage, type MailboxLease, MailboxStoreError, type MailboxStoreErrorCode, MAILBOX_TOMBSTONED_RECIPIENT_CODE, type MailboxAppendMessage, type MailboxPeerMeta, type MailboxPeerFromMode, type MailboxPeerRecordKind, MAILBOX_PEER_FROM_MODES, MAILBOX_PEER_RECORD_KINDS, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_CROSS_PROCESS_UNSAFE_CODE, readMailboxPeerMeta, mailboxCrossProcessMountVerdict, type MailboxCrossProcessVerdict, } from "./core/mailbox-store.js";
+export { InMemoryMailboxStore, type MailboxStore, type MailboxMessage, type MailboxLease, MailboxStoreError, type MailboxStoreErrorCode, MAILBOX_TOMBSTONED_RECIPIENT_CODE, type MailboxAppendMessage, type MailboxPeerMeta, type MailboxPeerFromMode, type MailboxPeerRecordKind, type MailboxPeerNoticeMeta, type MailboxPeerNoticeState, MAILBOX_PEER_NOTICE_STATES, MAILBOX_PEER_FROM_MODES, MAILBOX_PEER_RECORD_KINDS, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_CROSS_PROCESS_UNSAFE_CODE, readMailboxPeerMeta, mailboxCrossProcessMountVerdict, type MailboxCrossProcessVerdict, } from "./core/mailbox-store.js";
 export { FileMailboxStore, type FileMailboxStoreOptions } from "./stores/file/mailbox-store.js";
 export { createFileTaskListStore } from "./stores/file/task-list-store.js";
 export { createCcFileTaskListStore } from "./stores/cc/task-list-store.js";
@@ -145,7 +145,8 @@ export { createSchedulerTools, type SchedulerToolContext, SCHEDULE_WAKEUP_TOOL_N
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, type AutonomousLoopPromptOptions, } 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, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, type ApprovalSettledBy, APPROVAL_SETTLED_BY_VALUES, isApprovalSettledBy, type AskDenyResolution, ASK_DENY_RESOLUTION_VALUES, isAskDenyResolution, 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 { parseAutoModeResponse, createAutoModeDecider, type AutoModeVerdict, type AutoModeDecider, type AutoModeDeciderOptions, type AutoModeClassifyFn, type AutoModeClassifyInput, } from "./core/auto-mode.js";
+export { parseAutoModeResponse, createAutoModeDecider, type AutoModeVerdict, type AutoModeDecider, type AutoModeDeciderOptions, type AutoModeClassifyFn, type AutoModeClassifyInput, createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence, type AutoModeDenialTracker, type AutoModeDenialLimitOptions, type DenialLimitFallback, type DenialLimitVerdict, } from "./core/auto-mode.js";
+export { AUTO_MODE_DENIAL_LIMIT_DEFAULTS, AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS } from "./core/auto-mode-defaults.js";
 export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_MODE_DEFAULTS_SENTINEL, type AutoModeRules, type BuildAutoModePromptOptions, type AutoModeWindowOptions, } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./core/auto-mode-prompt-assets.js";
 export { AUTO_MODE_ARMING_RECIPE_VERSION, autoModeArmingRecipeOf, sanitizeAutoModeArmingRecipe, foldAutoModeArming, type AutoModeArmingRecipe, type AutoModeArmingFace, type AutoModeArmingFold, type AutoModeRebuildRefusal, } from "./core/auto-mode-arming.js";
@@ -258,8 +259,12 @@ export { PEER_REF_MIN, PEER_REF_MAX, PEER_REF_RE, mintPeerRef, formatPeerNameRef
 export { PEER_SESSION_RECORD_SCHEMA_VERSION, PEER_SESSION_RECORD_MAX_BYTES, SESSION_BOX_PREFIX, peerSessionBoxHandle, isPeerSessionId, PEER_SESSION_ID_GRAMMAR, parsePeerSessionAddress, readPeerSessionRecord, defaultPeerLivenessProbe, isPeerSessionProcessAlive, mintPeerSessionCandidates, resolvePeerSessions, createInMemoryPeerDirectory, vetPeerRegistryDirectory, judgePeerRecordFile, type PeerSessionRecord, type PeerSessionLiveness, type PeerSessionTempo, type PeerSessionRecordRefusal, type PeerSessionRecordRead, type PeerLivenessProbe, type PeerDirectory, type PeerDirectoryAccess, type PeerSessionCandidate, type PeerSessionResolution, type InMemoryPeerDirectory, type PeerRegistryDirectoryRefusal, type PeerRegistryDirectoryVerdict, } from "./agents/peer-directory.js";
 export { createListAgentsTool, LIST_AGENTS_TOOL_NAME, LIST_AGENTS_TOOL_ALIAS, LIST_AGENTS_MAX_RESULT_CHARS, type ListAgentsToolOptions, type ListAgentsRow } from "./agents/list-agents-tool.js";
 export { CROSS_SESSION_CLASSIFIER_RULE } from "./agents/cross-session-envelope.js";
-export { PEER_SESSION_ID_UNGRAMMATICAL_CODE, type PeerLaneMountVerdict } from "./agents/peer-session-drain.js";
-export { renderCrossSessionMessageFrame } from "./core/task-notification.js";
+export { PEER_SESSION_ID_UNGRAMMATICAL_CODE, type PeerLaneMountVerdict, type PeerInboundDisposition } from "./agents/peer-session-drain.js";
+export { renderCrossSessionMessageFrame, renderCrossSessionNoticeLine } from "./core/task-notification.js";
+export { PEER_HELD_QUEUE_CAP, PEER_IDLE_SUBSCRIPTION_TTL_MS, PEER_IDLE_SUBSCRIBER_TABLE_CAP, PEER_IDLE_OUTSTANDING_CAP, PEER_IDLE_PRIORS_KEPT, PEER_IDLE_FIRE_DEBOUNCE_MS, PEER_IDLE_HELD_BACKOFF_MS, PEER_IDLE_LABEL_MAX, CROSS_SESSION_DIALOG_EXPIRY_VALUES, CROSS_SESSION_DIALOG_EXPIRY_DEFAULT, resolveCrossSessionDialogExpiry, PEER_HELD_REVIEW_CAUSES, PEER_DELIVERY_RECEIPT_STATES, isPeerDeliveryReceiptState, PEER_DROP_REASONS, peerDeliveryReceiptLabel, describePeerDeliveryReceipt, peerRecipientSuffix, renderCrossSessionDeliveryNotice, describePeerDropReasons, renderCrossSessionDroppedNotice, PEER_IDLE_NOTICE_KINDS, isPeerIdleNoticeKind, PEER_IDLE_UNAVAILABLE_CAUSES, peerIdleNoticeLabel, peerIdleDetailOf, formatPeerNoticeClock, peerIdleNoticeSummary, renderCrossSessionIdleNotice, describePeerIdleSubscription, type CrossSessionDialogExpiry, type ResolvedCrossSessionDialogExpiry, type PeerDeliveryReceiptState, type PeerDropReason, type PeerIdleNoticeKind, type PeerIdleNoticeFields, } from "./agents/peer-notices.js";
+export { createPeerHeldQueue, peerHeldQueueFor, peerHeldQueueIfAny, peerHeldQueueKey, realPeerClock, type PeerInboundHoldCause, type PeerHeldEntry, type PeerHeldSettlement, type PeerHeldSettleReason, type PeerHeldSettleOutcome, type PeerClock, type PeerHeldQueueSink, type PeerHeldQueueConfig, type PeerHeldQueue, } from "./agents/peer-held-queue.js";
+export { createPeerIdleTarget, createPeerIdleRequester, peerIdleMachineFor, peerIdleMachineIfAny, peerIdleMachineKey, type PeerIdleSubscriber, type PeerIdleTargetNotice, type PeerIdleTargetSink, type PeerIdleSubscribeOutcome, type PeerIdleTarget, type PeerIdleOutstanding, type PeerIdleRequesterSink, type PeerIdleRequester, type PeerIdleMachine, } from "./agents/peer-idle.js";
+export { routePeerDeliveryReceipt, routePeerDroppedReceipt, routePeerIdleNotice, type PeerNoticeRoute } from "./agents/peer-notice-route.js";
 export { type PeerAdmissionStage } from "./agents/peer-admission.js";
 export { createAgentTranscriptTool, AGENT_TRANSCRIPT_TOOL_NAME, type AgentTranscriptToolOptions, } from "./agents/agent-transcript-tool.js";
 export { defineAgent } from "./agents/agent-definition.js";
@@ -277,13 +282,14 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, type CircuitBreakerOptions, type BreakerState, type BreakerSnapshot, type BreakerPhase, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, type DegradingBrainOptions, type DegradeReason, type DegradationInfo, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { WAITING_FIRST_TOKEN_AFTER_MS, WAITING_FIRST_TOKEN_EVERY_MS } from "./brain/stream-engine.js";
 export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, type RoutePairingStatus, } from "./brain/route-adjudicator.js";
 export type { RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, } from "./internal/llm.js";
 export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } from "./brain/route-conformance.js";
 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, 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, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, 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, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, 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

@@ -96,13 +96,13 @@ export { createFsWriteGatePolicy } from "./core/fs-write-gate-policy.js";
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, } from "./core/task-notification.js";
-export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, } from "./core/wiring-manifest.js";
+export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, } from "./core/park-selfcheck.js";
 export {} from "./core/checkpoint-store.js";
 export {} from "./core/checkpoint-store.js";
 export { projectHumanInput, buildHumanInputEvent, } from "./core/human-input-projection.js";
 export { TaskRegistry, defaultTaskRegistry, createTaskOutputTool, createTaskStopTool, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccessWorkflowRun, DURABLE_AGENT_HANDLE_RE, } from "./core/task-registry.js";
-export { InMemoryMailboxStore, MailboxStoreError, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MAILBOX_PEER_FROM_MODES, MAILBOX_PEER_RECORD_KINDS, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_CROSS_PROCESS_UNSAFE_CODE, readMailboxPeerMeta, mailboxCrossProcessMountVerdict, } from "./core/mailbox-store.js";
+export { InMemoryMailboxStore, MailboxStoreError, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MAILBOX_PEER_NOTICE_STATES, MAILBOX_PEER_FROM_MODES, MAILBOX_PEER_RECORD_KINDS, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_CROSS_PROCESS_UNSAFE_CODE, readMailboxPeerMeta, mailboxCrossProcessMountVerdict, } from "./core/mailbox-store.js";
 export { FileMailboxStore } from "./stores/file/mailbox-store.js";
 export { createFileTaskListStore } from "./stores/file/task-list-store.js";
 export { createCcFileTaskListStore } from "./stores/cc/task-list-store.js";
@@ -120,7 +120,8 @@ export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTIN
 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, APPROVAL_SETTLED_BY_VALUES, isApprovalSettledBy, ASK_DENY_RESOLUTION_VALUES, isAskDenyResolution, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
-export { parseAutoModeResponse, createAutoModeDecider, } from "./core/auto-mode.js";
+export { parseAutoModeResponse, createAutoModeDecider, createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence, } from "./core/auto-mode.js";
+export { AUTO_MODE_DENIAL_LIMIT_DEFAULTS, AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS } from "./core/auto-mode-defaults.js";
 export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_MODE_DEFAULTS_SENTINEL, } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./core/auto-mode-prompt-assets.js";
 export { AUTO_MODE_ARMING_RECIPE_VERSION, autoModeArmingRecipeOf, sanitizeAutoModeArmingRecipe, foldAutoModeArming, } from "./core/auto-mode-arming.js";
@@ -216,7 +217,11 @@ export { PEER_SESSION_RECORD_SCHEMA_VERSION, PEER_SESSION_RECORD_MAX_BYTES, SESS
 export { createListAgentsTool, LIST_AGENTS_TOOL_NAME, LIST_AGENTS_TOOL_ALIAS, LIST_AGENTS_MAX_RESULT_CHARS } from "./agents/list-agents-tool.js";
 export { CROSS_SESSION_CLASSIFIER_RULE } from "./agents/cross-session-envelope.js";
 export { PEER_SESSION_ID_UNGRAMMATICAL_CODE } from "./agents/peer-session-drain.js";
-export { renderCrossSessionMessageFrame } from "./core/task-notification.js";
+export { renderCrossSessionMessageFrame, renderCrossSessionNoticeLine } from "./core/task-notification.js";
+export { PEER_HELD_QUEUE_CAP, PEER_IDLE_SUBSCRIPTION_TTL_MS, PEER_IDLE_SUBSCRIBER_TABLE_CAP, PEER_IDLE_OUTSTANDING_CAP, PEER_IDLE_PRIORS_KEPT, PEER_IDLE_FIRE_DEBOUNCE_MS, PEER_IDLE_HELD_BACKOFF_MS, PEER_IDLE_LABEL_MAX, CROSS_SESSION_DIALOG_EXPIRY_VALUES, CROSS_SESSION_DIALOG_EXPIRY_DEFAULT, resolveCrossSessionDialogExpiry, PEER_HELD_REVIEW_CAUSES, PEER_DELIVERY_RECEIPT_STATES, isPeerDeliveryReceiptState, PEER_DROP_REASONS, peerDeliveryReceiptLabel, describePeerDeliveryReceipt, peerRecipientSuffix, renderCrossSessionDeliveryNotice, describePeerDropReasons, renderCrossSessionDroppedNotice, PEER_IDLE_NOTICE_KINDS, isPeerIdleNoticeKind, PEER_IDLE_UNAVAILABLE_CAUSES, peerIdleNoticeLabel, peerIdleDetailOf, formatPeerNoticeClock, peerIdleNoticeSummary, renderCrossSessionIdleNotice, describePeerIdleSubscription, } from "./agents/peer-notices.js";
+export { createPeerHeldQueue, peerHeldQueueFor, peerHeldQueueIfAny, peerHeldQueueKey, realPeerClock, } from "./agents/peer-held-queue.js";
+export { createPeerIdleTarget, createPeerIdleRequester, peerIdleMachineFor, peerIdleMachineIfAny, peerIdleMachineKey, } from "./agents/peer-idle.js";
+export { routePeerDeliveryReceipt, routePeerDroppedReceipt, routePeerIdleNotice } from "./agents/peer-notice-route.js";
 export {} from "./agents/peer-admission.js";
 export { createAgentTranscriptTool, AGENT_TRANSCRIPT_TOOL_NAME, } from "./agents/agent-transcript-tool.js";
 export { defineAgent } from "./agents/agent-definition.js";
@@ -234,6 +239,7 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { WAITING_FIRST_TOKEN_AFTER_MS, WAITING_FIRST_TOKEN_EVERY_MS } from "./brain/stream-engine.js";
 export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, } from "./brain/route-adjudicator.js";
 export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS } from "./brain/route-conformance.js";
 export {} from "./brain/timeout.js";

package/dist/internal/harness-types.d.ts

@@ -7,7 +7,7 @@
 export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/compaction/compaction.js";
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";
-export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, } from "../engine/loop/types.js";
+export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, ToolInputValidationContext, ToolInputVerdict, } from "../engine/loop/types.js";
 export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
 export type { ExecutionEnvExecOptions, ExecResult } from "../engine/harness/types.js";
 export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";

package/dist/orchestration/workflow.js

@@ -768,6 +768,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     };
     let journalTail = Promise.resolve();
     const JOURNAL_DRAIN_MAX_MS = 5_000;
+    const journalDurableResult = (result) => result.status !== "completed" && typeof result.errorMessage === "string" && result.errorMessage !== ""
+        ? { ...result, errorMessage: boundedRedactedSummary(result.errorMessage, MAX_TRANSCRIPT_CHARS) }
+        : result;
     const journalAppend = async (callKey, result, label) => {
         const dbg = typeof process !== "undefined" && process.env?.SEMA_DEBUG_WORKFLOW_JOURNAL === "1";
         if (!journalStore) {
@@ -775,9 +778,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 console.error(`[sema:wf-journal] runId=${runId} callKey=${callKey} SKIP (no journalStore on this run)`);
             return;
         }
+        const stored = journalDurableResult(result);
         let serialized;
         try {
-            serialized = JSON.stringify(result);
+            serialized = JSON.stringify(stored);
         }
         catch {
             serialized = undefined;
@@ -788,7 +792,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 run.journalSkips = (run.journalSkips ?? 0) + 1;
             emitRunLog(`resume-journal: agent #${callKeyOrdinal(callKey)}${label !== undefined ? ` "${label.slice(0, 80)}"` : ""} result is ${bytes} bytes, ` +
                 `over the ${MAX_JOURNAL_RESULT_BYTES}-byte per-entry cap — NOT cached. A resume from this run re-runs this agent and everything after it live.`);
-            const tombstone = journalStore.append(runId, scope, { callKey, result: journalOversizeTombstone(result, bytes) });
+            const tombstone = journalStore.append(runId, scope, { callKey, result: journalOversizeTombstone(stored, bytes) });
             journalTail = journalTail.then(() => tombstone).catch(() => undefined);
             try {
                 await tombstone;
@@ -801,7 +805,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             return;
         }
-        const p = journalStore.append(runId, scope, { callKey, result });
+        const p = journalStore.append(runId, scope, { callKey, result: stored });
         journalTail = journalTail.then(() => p).catch(() => undefined);
         try {
             await p;

package/dist/tools/fs/fs-write.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import type { BeforeWriteHook, TrackFileEditHook } from "../../core/types.js";
+import type { BeforeWriteHook, FileEditedHook, TrackFileEditHook } from "../../core/types.js";
 import { type ReadFileState } from "./safety.js";
 import { type CwdRef } from "./fs-shared.js";
 /**
@@ -12,8 +12,8 @@ import { type CwdRef } from "./fs-shared.js";
  * prefix comparison there (零开销直通). Absent hook ⇒ byte-identical behavior.
  */
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook } from "../../core/types.js";
-export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook): AgentTool;
-export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook): AgentTool;
+export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;
+export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;
 /**
  * design v1.163 — NotebookEdit: replace/insert/delete a single cell in a .ipynb. CC-parity tool over the SAME hand-band
  * safety skeleton as Edit/Write (resolveKey containment → requireRead read-before-edit → checkStale content-hash
@@ -21,4 +21,4 @@ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileSt
  * .ipynb as the RB-227 cell projection but records read state (hash/totalLines) in the RAW notebook-text
  * coordinate — that raw-coordinate read record is what this tool's freshness check depends on.
  */
-export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook): AgentTool;
+export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;

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

@@ -5,16 +5,35 @@ import { sha256, resolveKey, violationText, violationDetails, requireRead, check
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
 async function envFinalWrite(env, key, content, signal, opts) {
+    const fireEdited = () => {
+        if (opts?.edited?.hook === undefined)
+            return;
+        try {
+            const ack = opts.edited.hook({ tool: opts.edited.tool, path: opts.edited.path, key });
+            if (ack !== null && (typeof ack === "object" || typeof ack === "function") && typeof ack.then === "function") {
+                void ack.then(undefined, () => undefined);
+            }
+        }
+        catch {
+        }
+    };
     let r;
     try {
         r = await writeThroughEnv(env, key, content, signal, opts);
     }
     catch (err) {
         await discardTrackedEdit(opts?.track, "verify");
+        fireEdited();
         throw err;
     }
-    if (!r.ok)
-        await discardTrackedEdit(opts?.track, NOTHING_WAS_WRITTEN.has(r.error.code) ? "proven" : "verify");
+    if (!r.ok) {
+        const proven = NOTHING_WAS_WRITTEN.has(r.error.code);
+        await discardTrackedEdit(opts?.track, proven ? "proven" : "verify");
+        if (!proven)
+            fireEdited();
+        return r;
+    }
+    fireEdited();
     return r;
 }
 const NOTHING_WAS_WRITTEN = new Set(["already_exists", "precondition_failed"]);
@@ -66,7 +85,7 @@ async function gateToolWrite(hook, tool, path, key, content) {
         return `Error (${tool}): write rejected by the write gate (${res.code}): ${clipHookText(res.reason)}`;
     return undefined;
 }
-export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit) {
+export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
     return defineTool({
         name: "Edit",
         contract: { contractId: "core.edit@1", implementationRevision: "1" },
@@ -83,6 +102,35 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             replace_all: Type.Optional(Type.Boolean({ description: "Replace all occurrences of old_string (default false)" })),
         }),
         effect: "write",
+        validateInput: async (args, ctx) => {
+            const a = args;
+            if (Array.isArray(a.edits) && a.edits.length > 0)
+                return { ok: true };
+            if (typeof a.old_string !== "string" || typeof a.new_string !== "string")
+                return { ok: true };
+            const path = fileArgPath(args);
+            if (path === undefined)
+                return { ok: true };
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            if (!r.ok)
+                return { ok: true };
+            if (a.old_string === a.new_string)
+                return { ok: true };
+            const exists = await env.exists(r.key, ctx.signal);
+            if (!exists.ok || !exists.value)
+                return { ok: true };
+            const editInfo = await env.fileInfo(r.key, ctx.signal);
+            if (editInfo.ok && editInfo.value.size > MAX_EDIT_BYTES)
+                return { ok: true };
+            if (a.old_string === "")
+                return { ok: true };
+            if (ipynbRedirect("Edit", path))
+                return { ok: true };
+            const notRead = requireRead(state, r.key);
+            if (notRead === undefined)
+                return { ok: true };
+            return { ok: false, code: notRead.code, message: await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT) };
+        },
         execute: async (args, ctx) => {
             const a = args;
             const batch = Array.isArray(a.edits) && a.edits.length > 0;
@@ -122,7 +170,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                     const tracked = await trackToolEdit(trackEdit, "Edit", path, r.key, ctx.signal);
                     if (tracked.refusal !== undefined)
                         return errorResult(tracked.refusal);
-                    const write = await envFinalWrite(env, r.key, created, ctx.signal, { exclusive: true, track: tracked });
+                    const write = await envFinalWrite(env, r.key, created, ctx.signal, { exclusive: true, track: tracked, edited: { hook: onEdited, tool: "Edit", path } });
                     if (!write.ok) {
                         if (write.error.code === "already_exists") {
                             return errorResult(`Error (Edit): cannot create "${path}": file already exists (created concurrently since the existence check). Read the file first, then edit it normally (or Write after the Read to overwrite it).`);
@@ -176,7 +224,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 if (trackedOverwrite.refusal !== undefined)
                     return errorResult(trackedOverwrite.refusal);
                 const encodedOverwrite = encodeTextForFile(newContent, preDec.encoding, preDec.endings);
-                const write = await envFinalWrite(env, r.key, encodedOverwrite, ctx.signal, { track: trackedOverwrite });
+                const write = await envFinalWrite(env, r.key, encodedOverwrite, ctx.signal, { track: trackedOverwrite, edited: { hook: onEdited, tool: "Edit", path } });
                 if (!write.ok)
                     return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
                 const persistedOverwrite = persistedTextOf(encodedOverwrite);
@@ -253,7 +301,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             if (trackedEdit.refusal !== undefined)
                 return errorResult(trackedEdit.refusal);
             const encodedEdit = encodeTextForFile(working, decoded.encoding, decoded.endings);
-            const write = await envFinalWrite(env, r.key, encodedEdit, ctx.signal, { track: trackedEdit });
+            const write = await envFinalWrite(env, r.key, encodedEdit, ctx.signal, { track: trackedEdit, edited: { hook: onEdited, tool: "Edit", path } });
             if (!write.ok)
                 return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
             const persistedEdit = persistedTextOf(encodedEdit);
@@ -276,7 +324,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
         },
     });
 }
-export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit) {
+export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
     return defineTool({
         name: "Write",
         contract: { contractId: "core.write@1", implementationRevision: "1" },
@@ -290,6 +338,23 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             content: Type.String({ description: "The content to write to the file" }),
         }),
         effect: "write",
+        validateInput: async (args, ctx) => {
+            const path = fileArgPath(args);
+            if (path === undefined)
+                return { ok: true };
+            if (ipynbRedirect("Write", path))
+                return { ok: true };
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            if (!r.ok)
+                return { ok: true };
+            const exists = await env.exists(r.key, ctx.signal);
+            if (!exists.ok || !exists.value)
+                return { ok: true };
+            const notRead = requireRead(state, r.key);
+            if (notRead === undefined)
+                return { ok: true };
+            return { ok: false, code: notRead.code, message: await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT) };
+        },
         execute: async (args, ctx) => {
             const { content } = args;
             const path = fileArgPath(args);
@@ -327,7 +392,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 if (trackedWrite.refusal !== undefined)
                     return errorResult(trackedWrite.refusal);
                 const encodedWrite = encodeTextForFile(content, decodedPrev.encoding, "preserve");
-                const write = await envFinalWrite(env, r.key, encodedWrite, ctx.signal, { track: trackedWrite });
+                const write = await envFinalWrite(env, r.key, encodedWrite, ctx.signal, { track: trackedWrite, edited: { hook: onEdited, tool: "Write", path } });
                 if (!write.ok)
                     return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
                 const persistedWrite = persistedTextOf(encodedWrite);
@@ -343,7 +408,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             const trackedCreate = await trackToolEdit(trackEdit, "Write", path, r.key, ctx.signal);
             if (trackedCreate.refusal !== undefined)
                 return errorResult(trackedCreate.refusal);
-            const write = await envFinalWrite(env, r.key, content, ctx.signal, { track: trackedCreate });
+            const write = await envFinalWrite(env, r.key, content, ctx.signal, { track: trackedCreate, edited: { hook: onEdited, tool: "Write", path } });
             if (!write.ok)
                 return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
             const totalLines = countLines(content);
@@ -356,7 +421,10 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
         },
     });
 }
-export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit) {
+const notebookNotIpynbMessage = (notebookPath) => `Error (NotebookEdit): "${notebookPath}" is not a .ipynb file; use Edit for other file types.`;
+const NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE = `Error (NotebookEdit): Cell type is required when using edit_mode=insert.`;
+const NOTEBOOK_CELL_ID_REQUIRED_MESSAGE = `Error (NotebookEdit): cell_id is required for replace/delete.`;
+export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
     return defineTool({
         name: "NotebookEdit",
         contract: { contractId: "core.notebook_edit@1", implementationRevision: "1" },
@@ -382,18 +450,35 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
             })),
         }),
         effect: "write",
+        validateInput: async (args, ctx) => {
+            const a = args;
+            const mode = a.edit_mode ?? "replace";
+            if (!a.notebook_path.toLowerCase().endsWith(".ipynb"))
+                return { ok: false, code: "invalid", message: notebookNotIpynbMessage(a.notebook_path) };
+            if (mode === "insert" && !a.cell_type)
+                return { ok: false, code: "invalid", message: NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE };
+            if (mode !== "insert" && !a.cell_id)
+                return { ok: false, code: "invalid", message: NOTEBOOK_CELL_ID_REQUIRED_MESSAGE };
+            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots);
+            if (!r.ok)
+                return { ok: true };
+            const notRead = requireRead(state, r.key);
+            if (notRead === undefined)
+                return { ok: true };
+            return { ok: false, code: notRead.code, message: await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT) };
+        },
         execute: async (args, ctx) => {
             const a = args;
             const { notebook_path, cell_id, new_source } = a;
             let cellType = a.cell_type;
             const mode = a.edit_mode ?? "replace";
             if (!notebook_path.toLowerCase().endsWith(".ipynb")) {
-                return errorResult(`Error (NotebookEdit): "${notebook_path}" is not a .ipynb file; use Edit for other file types.`);
+                return errorResult(notebookNotIpynbMessage(notebook_path));
             }
             if (mode === "insert" && !cellType)
-                return errorResult(`Error (NotebookEdit): Cell type is required when using edit_mode=insert.`);
+                return errorResult(NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE);
             if (mode !== "insert" && !cell_id)
-                return errorResult(`Error (NotebookEdit): cell_id is required for replace/delete.`);
+                return errorResult(NOTEBOOK_CELL_ID_REQUIRED_MESSAGE);
             const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
                 return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));
@@ -477,7 +562,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
             const trackedNb = await trackToolEdit(trackEdit, "NotebookEdit", notebook_path, r.key, ctx.signal);
             if (trackedNb.refusal !== undefined)
                 return errorResult(trackedNb.refusal);
-            const w = await envFinalWrite(env, r.key, encodeTextForFile(updated, decodedNb.encoding, decodedNb.endings), ctx.signal, { track: trackedNb });
+            const w = await envFinalWrite(env, r.key, encodeTextForFile(updated, decodedNb.encoding, decodedNb.endings), ctx.signal, { track: trackedNb, edited: { hook: onEdited, tool: "NotebookEdit", path: notebook_path } });
             if (!w.ok)
                 return errorResult(`Error (NotebookEdit): cannot write "${notebook_path}": ${w.error.message}`);
             state.set(r.key, { hash: sha256(updated), totalLines: countLines(updated), truncated: false, lastReadAt: Date.now() });

package/dist/tools/fs/index.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import { type BeforeWriteHook, type TrackFileEditHook } from "../../core/types.js";
+import { type BeforeWriteHook, type FileEditedHook, type TrackFileEditHook } from "../../core/types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type ReadFileState } from "./safety.js";
 import type { PdfModelCapabilities } from "./pdf.js";
@@ -120,6 +120,12 @@ export interface HandsToolkitOptions {
      *  env write, so the file's pre-edit state is durably recorded before it changes. The Runner
      *  wires it to `FileHistoryStore.trackEdit`; absent ⇒ byte-identical behavior (no history). */
     trackFileEdit?: TrackFileEditHook;
+    /** The mutation lane's LANDED observation seat — fired once per Write/Edit/NotebookEdit call whose
+     *  bytes reached disk (never for a refused/failed one, never for a Bash-authored change). Wired by
+     *  the Runner to the per-run accumulator behind `TaskResult.editedFiles`; absent ⇒ nothing observes.
+     *  Purely additive: it cannot refuse a write, and a fault in it is contained in both shapes (a
+     *  synchronous throw and a rejected promise), neither of them awaited. */
+    onFileEdited?: FileEditedHook;
     /** #181-F6 — see createBashTool's taskOpts field of the same name: whether the Monitor tool is on
      *  this run's roster (the Runner mounts Monitor, this band never does). `false` drops the gh
      *  rate-limit hint's Monitor clause; absent ⇒ historic full wording (byte-compat). */

package/dist/tools/fs/index.js

@@ -50,7 +50,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts),
     ];
     if (!readOnly) {
-        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit));
+        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited));
     }
     tools.push(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace), createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace), createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace));
     if (includeShell) {

package/dist/tools/fs/safety.d.ts

@@ -138,6 +138,18 @@ export declare function isAbsolutePathForm(p: string): boolean;
  * imports are `node:crypto` plus a type, so there is no layering wall between them.
  */
 export declare function isWinFormPath(p: string): boolean;
+/**
+ * Expand a LEADING `~` (bare, or followed by a separator of either family) against `home`; every other
+ * spelling is returned untouched — a `~` anywhere but the front is an ordinary filename character.
+ *
+ * Lives here for the same reason `isWinFormPath` does: it is a path-FAMILY decision (which characters
+ * end the first component), and the domain gate holds this module as the one home for those. Callers
+ * that need it: the sensitive-path guard's data-root resolution, and — spelled privately for now —
+ * `tool-policy.ts`'s `lexicalPath`. NOT a resolution of relative paths: a caller that also needs that
+ * says so with its own `resolve`, because the two consumers of this value disagree about which cwd a
+ * relative spelling belongs to and that disagreement is theirs to state, not this helper's to hide.
+ */
+export declare function expandHomeTilde(p: string, home: string): string;
 export declare function isBlockedDevicePath(key: string): boolean;
 /**
  * RB-153 — purely LEXICAL path normalization: collapse repeated separators, drop `.` segments, and
@@ -335,16 +347,25 @@ export declare function withinAnyRoot(rootsCanonical: readonly string[], p: stri
 /**
  * RB-371 ① — the escape-hatch tail for the `path_not_in_root` refusal: its three sibling hints
  * below each name a sanctioned next step; this refusal named none, leaving the model to oscillate
- * between "the boundary is hard" and discovering by trial that bash is not confined by it.
+ * between "the boundary is hard" and hunting for a way around it.
+ *
+ * The card names the SANCTIONED way out and nothing else: widening the declaration
+ * (`additionalDirectories` / read-only `additionalReadDirectories`, design/119), or the
+ * deployment-level `readFace: "open"` for reads.
  *
- * Ordering is deliberate (ruled 2026-08-12, fence = the deployment's declared containment
- * boundary): the SANCTIONED way out — widening the declaration (`additionalDirectories` /
- * read-only `additionalReadDirectories`, design/119) — leads; the Bash sentence stays as a FACT
- * (the shell genuinely is not confined by this fence — design/44 §5 — and omitting that would
- * just let the model discover it by trial), but it is a statement, not a recommendation, and it
- * comes last. Every shell call still passes the deployment's approval policy.
+ * A trailing sentence naming the shell as unconfined by this fence was REMOVED (it had been kept on
+ * the argument that a statement of fact is not a recommendation, and that omitting it would only let
+ * the model discover the same thing by trial). A live retest settled that argument the other way: a
+ * refused agent read the sentence as the next step, went to the shell, and rewrote through it the
+ * very file the fence had just protected. A refusal card is a PROMPT surface — naming, at the moment
+ * of denial, a second tool that does not enforce the boundary is a recipe whatever its grammar, and
+ * the model cannot be relied on to hear "fact, not advice". The underlying fact is unchanged and
+ * still documented where humans read it (design/44 §5: the shell is deliberately unconfined by this
+ * fence, and every shell call still passes the deployment's approval policy); it is simply no longer
+ * handed to the model inside a denial. What the card says now: this is denied, and here is the
+ * sanctioned way to be allowed.
  */
-export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s), ask for the directory to be added to the deployment's additionalDirectories \u2014 or additionalReadDirectories for read-only access; a deployment that wants reads open everywhere can declare readFace: \"open\" instead of listing directories. For completeness: the Bash tool is not confined by this fence, and every Bash call remains subject to the deployment's approval policy.)";
+export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s), ask for the directory to be added to the deployment's additionalDirectories \u2014 or additionalReadDirectories for read-only access; a deployment that wants reads open everywhere can declare readFace: \"open\" instead of listing directories.)";
 /** inv 1 (read-before-edit): a file must have been read this task before it can be edited/overwritten.
  *  Message is CC 2.1.198 live-verbatim (all-tools-live-probe 2026-07-08 §2.1/§3.1/§5.1 — one message for
  *  Edit/Write/NotebookEdit: "before writing to it", not the old sema "before editing").

package/dist/tools/fs/safety.js

@@ -53,6 +53,16 @@ const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[0-9¹²³]|LPT[0-9¹²³]|CONIN\$
 export function isWinFormPath(p) {
     return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\") || (!p.startsWith("/") && p.includes("\\"));
 }
+export function expandHomeTilde(p, home) {
+    if (p === "~")
+        return home;
+    if (!p.startsWith("~"))
+        return p;
+    const next = p[1];
+    if (next !== "/" && next !== "\\")
+        return p;
+    return home + "/" + p.slice(2);
+}
 function isWinReservedDeviceKey(key) {
     if (!isWinFormPath(key))
         return false;
@@ -493,7 +503,7 @@ export function violationDetails(v) {
 export function withinAnyRoot(rootsCanonical, p) {
     return rootsCanonical.some((r) => within(r, p));
 }
-export const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s), ask for the directory to be added to the deployment's additionalDirectories — or additionalReadDirectories for read-only access; a deployment that wants reads open everywhere can declare readFace: \"open\" instead of listing directories. For completeness: the Bash tool is not confined by this fence, and every Bash call remains subject to the deployment's approval policy.)";
+export const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s), ask for the directory to be added to the deployment's additionalDirectories — or additionalReadDirectories for read-only access; a deployment that wants reads open everywhere can declare readFace: \"open\" instead of listing directories.)";
 export function requireRead(state, key) {
     const entry = state.get(key);
     if (entry === undefined || entry.isPartialView) {

package/package.json

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