@sema-agent/core 7.3.1 → 7.4.0

package/dist/core/types.d.ts

@@ -733,6 +733,32 @@ export interface ToolExecuteContext {
      * the tool runs outside a Runner task.
      */
     parentCwd?: string;
+    /**
+     * The RUNNING task's file-history LINEAGE (Runner-filled, read-only, never a model/tool argument;
+     * present iff a `RunnerDeps.fileHistoryStore` is live for the run): the history scope this run
+     * records its first-touch edits into and the TREE those records' keys are minted against — the
+     * canonical root spelling plus the env's filesystem identity (`fs`: a remote workspace's handle,
+     * `"host"` for the control-plane host's filesystem, else a per-env-instance token).
+     *
+     * WHICH children are threaded it, exactly: the Agent tool's FRESH spawn legs (sync / steer /
+     * background / fork) pass it VERBATIM into the child's trusted internals
+     * (`RunInternals.fileHistoryLineage`), which is how a same-process delegation tree keeps ONE
+     * history: a child on the SAME tree (both coordinates equal) records into the lineage's scope (the
+     * root session's), so the root session's `rewindFilesTo` reaches the child's edits; a child on a
+     * different tree (worktree isolation, an explicit `cwd`, a fresh per-task sandbox) starts its own
+     * lineage, because root-relative keys re-joined against a different tree would name files that run
+     * never edited. Three delegated legs deliberately carry NO lineage and keep their own scope: the
+     * Agent tool's REVIVE arm (a revival's lineage would be the REVIVER's tree, which says nothing
+     * about the revived row's), and the workflow / team orchestration spawn legs (`run_workflow`,
+     * `runTeamDiscussion` — they build their children's internals without this seat). Edits made by
+     * those children are therefore NOT reachable from the root session's rewind, and a restore request
+     * on one of them is not refused either — it converges that child's own scope.
+     */
+    fileHistoryLineage?: {
+        scope: string;
+        root: string;
+        fs: string;
+    };
     /**
      * design/319 (A ticket) — the RUNNING task's reminder provenance mark, Runner-filled, read-only,
      * NEVER a model/tool argument. The Agent tool's FORK route threads it into the forked child's
@@ -1299,6 +1325,35 @@ export type TrackEditResult = {
     refusal: string;
 };
 export type TrackFileEditHook = (req: TrackEditRequest) => Promise<TrackEditResult>;
+/**
+ * The hands band's MUTATION-EDITED observation seat — the counterpart of {@link TrackEditRequest},
+ * fired at the other end of the same lane. Called once per Write/Edit/NotebookEdit call whose FINAL
+ * env write did not PROVABLY write nothing, at the single point every mutation lane funnels through,
+ * under the same three-valued law as the first-touch record's own retraction:
+ *  - a call the argument checks, the read-before-edit gate, the write gate or the first-touch
+ *    history seat refused never fires it (nothing was written);
+ *  - a call whose write FAILED with a code whose contract says nothing was written never fires it;
+ *  - a call whose write failed AMBIGUOUSLY (a non-atomic env that truncated and then errored) or
+ *    THREW fires it — exactly the arm where the retraction KEEPS the first-touch record because the
+ *    file may really have changed. The two seats agree on purpose: a file whose baseline was kept
+ *    for a possible modification must also be listed as possibly modified;
+ *  - a `Bash` command that changed a file never fires it: bash does not run through this band's
+ *    write lanes at all, which is the whole reason this seat is not a tool-name table.
+ * PURE OBSERVATION: it returns nothing and it cannot refuse. A FAULT in it is contained in both
+ * shapes an observer can fail in — a synchronous throw, and (the return type is `void`, but an
+ * `async` function still type-checks there) a rejected promise, which is sunk rather than left
+ * unhandled. Neither is awaited: an observer must never turn a landed write into a failed tool
+ * answer, nor delay one.
+ */
+export interface FileEditedNotice {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument — the SAME coordinate the delegated-child projection's
+     *  `SubagentEditedFile.path` carries, so the two seats can be read side by side. */
+    path: string;
+    /** The resolved canonical containment key the bytes actually landed on. */
+    key: string;
+}
+export type FileEditedHook = (notice: FileEditedNotice) => void;
 /**
  * design/141 件2 — the SAFE deployment-configurable subset of the hands toolkit ({@link RunnerDeps.hands}).
  * Only fields whose injection is purely additive for a deployment are here; Runner-internal orchestration
@@ -2130,6 +2185,15 @@ export interface TaskSpec {
      * target with no history boundary fails loud (`rewind_snapshot.unresolvable`). Requires
      * `RunnerDeps.fileHistoryStore`. The session leaf is untouched — the next turn continues the
      * CURRENT conversation, only the files moved.
+     *
+     * A same-process child THE AGENT TOOL SPAWNED FRESH (the legs that are handed a lineage — see
+     * `ToolExecuteContext.fileHistoryLineage` for the exact set, and for the legs that are not) which
+     * shares its root session's tree records its edits into the ROOT session's history, so a rewind
+     * that should cover those edits is the root session's action; a restore request on such a child run
+     * is refused loud (`rewind.child_scope_unsupported`) rather than converging a scope that holds none
+     * of its edits. A delegated child that was handed NO lineage — a revival, a workflow/team member —
+     * keeps its own scope: its edits are outside this target's reach, and its own restore request is an
+     * ordinary one.
      */
     rewindFilesTo?: string;
     /**
@@ -3532,7 +3596,7 @@ export interface TaskResult {
      * ignores the field is unchanged. A rewind that could NOT be delivered as asked is NOT a note — it is a
      * terminal failure (`rewind_snapshot.unresolvable` / `rewind.store_unconfigured` /
      * `rewind.restore_failed` / `rewind.invalid_spec` / `rewind.rewind_files_retired` /
-     * `rewind.conflicting_targets`).
+     * `rewind.conflicting_targets` / `rewind.child_scope_unsupported`).
      *
      * - `conversation_only` — {@link TaskSpec.resumeAt} branched the transcript WITHOUT
      *   {@link TaskSpec.restoreFiles}, so the working tree was deliberately left where it was (CC's
@@ -3555,6 +3619,56 @@ export interface TaskResult {
         /** Human-readable statement of what did NOT happen and why — safe to show a user verbatim. */
         message: string;
     }>;
+    /**
+     * The files THIS RUN's hands actually mutated, with how many times each — the same
+     * `{path, edits}` shape the delegated-child projection publishes as
+     * {@link import("../agents/subagent-steps.js").SubagentEditedFile}, so a host can read the two
+     * seats side by side. A run is one host-side user message, which is the granularity a
+     * "restore the code this message changed" affordance needs; the per-model-turn beat
+     * (`turn_end`) deliberately has no such seat.
+     *
+     * **Source**: the hands band's own mutation lane. One entry is bumped when a `Write`/`Edit`/
+     * `NotebookEdit` call's FINAL env write returns success — not when a tool call starts, not from a
+     * tool-name table over the event stream. The consequences are the contract:
+     *  - a refused, gated or FAILED write is not counted (a write whose bytes never landed is not an
+     *    edit — the same lane point that retracts its first-touch history record);
+     *  - a `Bash` command that changed a file is not counted: it does not go through those lanes.
+     *    This matches the reference implementation's own trigger set;
+     *  - one tool CALL counts once, so a batch `Edit` (multiple `edits[]` against one file in one
+     *    call) is one edit here, exactly as the child projection counts it.
+     *
+     * **`path` form**: the model-supplied path argument, verbatim — the same coordinate
+     * `SubagentEditedFile.path` uses, deliberately not the canonical containment key, so both seats
+     * spell a file the way the transcript does. IDENTITY, however, is the canonical FILE, not the
+     * spelling: a relative argument resolves against the run's LIVE cwd, so one spelling can name two
+     * different files across a `cd` (two entries, each showing that spelling) and two spellings can
+     * name one file (ONE entry, showing the first spelling that reached it). Insertion order = order
+     * of first edit.
+     *
+     * **Three-valued on the failure edge, upper bound never lower**: a write failure is three-valued.
+     * A failure whose error code's contract states nothing was written is a proven no-op and is NOT
+     * counted. An AMBIGUOUS failure or a thrown write IS counted: an `ExecutionEnv` whose write is not
+     * atomic can truncate a file and then report an error, that file may really have changed, and the
+     * first-touch history record for it is kept for exactly that reason — so this list names it too,
+     * and a `rewindFilesTo` will restore it. (The reference env replaces whole files by stage+rename —
+     * fully old or fully new — so this edge belongs to its in-place fallback arms and to third-party
+     * envs.) A host therefore reads this list as "files that may differ from before this run", never
+     * as "writes the model saw succeed"; the tool answers carry that.
+     *
+     * **In-presence condition**: present iff this run's hands landed ≥1 such write — zero edits means
+     * the key is ABSENT, never an empty array. It does NOT depend on whether a
+     * `RunnerDeps.fileHistoryStore` is wired: this is an observation of what this run did, not a
+     * durable history, and a deployment with no history store still gets it (what a store adds is the
+     * ability to REWIND, not the ability to say what changed). It covers this run's OWN band only — a
+     * delegated child's writes ride the child's own result and the delegation projection, not this
+     * key.
+     *
+     * **Bound**: at most 1000 distinct files. Past that, already-listed files keep counting and new
+     * ones are not added — a result seat cannot be unbounded, and a single user message reaching a
+     * thousand distinct files is already outside what this observation is for. A consumer that must
+     * know whether it is reading a saturated list can compare the length against that ceiling.
+     */
+    editedFiles?: import("../agents/subagent-steps.js").SubagentEditedFile[];
     /**
      * Present (`true`) exactly when the run's FINAL turn was halted by a person's BARE rejection of a
      * tool call — the parent-thread control-flow boundary: the rejected call's same-message siblings
@@ -5954,6 +6068,20 @@ export interface EngineNotice {
      *    (whoever answered the card is the one entitled to hear the answer ran nothing); a host may
      *    forward it on its own wire.
      *
+     *  - `"classifier.denial_limit"` (#548, CC 2.1.250 `FO`/"too many classifier denials in headless
+     *    mode") — the auto-mode classifier's DENIAL LIMIT was reached (3 consecutive blocks, or 20 in the
+     *    run; `RunnerDeps.autoMode.denialLimit`) and the fallback ask it turns into had NO approver to go
+     *    to: none wired, a blanket `onAsk:"allow"` (refused for a real-approval ask), or an approver that
+     *    reported unavailable with no durable park to take it. The run was STOPPED — `TaskResult.status`
+     *    `"failed"`, `errorCode` the same code, `errorMessage` the limit sentence — rather than kept
+     *    spending on a model the classifier denies without end; the triggering call's own result is the
+     *    deny that stood. Once per run (the first headless fallback owns the terminal);
+     *    `detail: { sessionId, runId, toolName, toolCallId, consecutive, total, limit }` — `limit` is
+     *    `"consecutive"` | `"total"`, the bound that tripped. Audience `"user"` (the person whose run
+     *    ended is the one entitled to hear why, and to review the transcript the sentence points at).
+     *    With an approver wired the same bound mints NO notice — the fallback ask reaches the person
+     *    instead (`AskRequest.denialLimitFallback`).
+     *
      *  - `"steering.parked_input_blocked"` (design/373 §4.3) — a PARKED steer entry was withheld when
      *    a resume redelivered it (any resume kind that drains parked steers — wake included) by the
      *    deployment's `userPromptSubmit` screen (block verdict, or a fail-closed non-answer/crash):
@@ -6125,23 +6253,61 @@ export interface EngineNotice {
      *    disposition table with the error dispositions. The loser MUST NOT retry into the winner's
      *    account. A consumer diffing its own table against the catalog must not add a row for it.
      *
+     *  - `"config.peer_admission_out_of_range"` (#551) — a `RunnerDeps.peerAdmission` field the
+     *    resolver could not use: outside its legal range, or not a finite number at all (a string off
+     *    an untyped host's wiring, `NaN`, `Infinity`). THAT FIELD falls back to its own default (never
+     *    a clamp to the nearest edge, never a whole-config reject) and every other field is unaffected.
+     *    One notice PER FIELD — two bad fields in one config are two notices — deduped per SINK on
+     *    `(field, given)` rather than per call (the resolver runs on every SendMessage and every drain
+     *    round; the fact is about the wiring, not about the call). Per SINK, not per process: two
+     *    Runners in one process each own an `onNotice`, and a process-global ledger would deliver the
+     *    fact to whichever resolved first and leave the other silently without its own disclosure. The
+     *    unwired arm (no `onNotice`: the shared `console.warn` throat) latches per process instead —
+     *    the console IS one process-wide channel. `detail: { field, given, default,
+     *    range: [lo, hi], reason }`, where `reason` is `"out_of_range" | "not_a_finite_number"`.
+     *    Audience `"operator"` (a configuration fact; the fix is the deployment's).
      *  - `"config.peer_lane_unmounted"` (design/385 §1.2⑥) — `RunnerDeps.peerDirectory` is wired but
      *    the cross-session lane could not mount on this leg: no `mailboxStore`, or one that does not
      *    declare `crossProcessSafe: true` (several terminals would share one session box on luck). The
      *    seat is inert for the run (no ListAgents, peer addresses refuse with the same reason). Once per
      *    prepared leg; `detail: { reason, code, mailboxWired, sessionId, runId }`. Audience `"operator"`
      *    (a wiring fact; the fix is the deployment's).
-     *  - `"peer.inbound_disposition"` (design/385 §1.2④ / §4.6) — a message parked in THIS session's
-     *    own box was settled at the drain WITHOUT reaching the model. `detail.disposition` is the arm:
-     *    `"refused"` (this session's `crossSessionInbound` setting, or a record whose typed fields
-     *    cannot be rendered canonically), `"admission_refused"` (the drain-stage admission re-check:
-     *    duplicate / hop loop / runaway — `cause` names it), `"notice_unrouted"` (a notice-kind record
-     *    — idle/delivery notice — met a build with no notice face: settled without delivery, never
-     *    ridden through the peer-message envelope), or `"held"` (mode parity held it; the
-     *    held-message review face is not mounted in this build, so the message STAYS PARKED and the
-     *    drain stops at it — disclosed once per seq per leg). `detail: { disposition, cause, seq, box,
+     *  - `"peer.inbound_disposition"` (design/385 §1.2④ / §4.6 / §4.4) — a message parked in THIS
+     *    session's own box was settled at the drain WITHOUT reaching the model. `detail.disposition` is
+     *    the arm (closed set `PeerInboundDisposition`): `"refused"` (this session's `crossSessionInbound`
+     *    setting, or a record whose typed fields cannot be rendered canonically), `"admission_refused"`
+     *    (the drain-stage admission re-check: duplicate / hop loop / runaway — `cause` names it),
+     *    `"notice_unrouted"` (a notice-kind record the notice face cannot render — no typed `notice`, or
+     *    a state that does not fit its kind — settled without delivery, never ridden through the
+     *    peer-message envelope), `"notice_user_only"` (a delivery receipt / idle notice whose sender this
+     *    session's parity would HOLD: surfaced here for the user, not read by the model — CC's
+     *    `modelVisible:false` arm; `cause` carries the rendered notice text), or `"held"` — the parity
+     *    judgment held it: the message ENTERED this session's process-level held queue and was acked
+     *    from the box (later messages are not blocked behind it), where it is re-judged at every
+     *    boundary, released or refused with a receipt, and expires WITH a receipt under `dialogExpiry`
+     *    (see `peer.held_settled`); `cause` is a `PeerInboundHoldCause` — the parity causes, or the
+     *    drain gate's TRANSIENT `rate_limited` (that one does NOT enter the queue: the message stays in
+     *    the box and the drain stops at its seq until the bucket refills). Disclosed once per seq per leg,
+     *    and again when a re-judgment moves a held entry's cause. `detail: { disposition, cause, seq, box,
      *    fromSession?, sessionId, runId }`. Audience `"user"`: the session's user is the one who did
      *    not receive it.
+     *  - `"peer.held_settled"` (design/385 §4.4, slice 4) — a message left THIS session's held queue.
+     *    `detail.settlement` names how: `"delivered"` (a re-judgment or an approval released it into
+     *    this session's model context), `"refused"` (the setting moved to refuse, or an approval met a
+     *    refusing policy), `"expired"` (the `dialogExpiry` deadline, an eviction when the 100-entry queue
+     *    was full, a cancelled review, or a graceful shutdown), `"denied"` (the review face), `"dropped"`
+     *    (the injection lane refused the released frame). `detail.reason` is the trigger
+     *    (`deadline | evicted | shutdown | rejudge | approved | denied | cancelled | inject_failed`); the
+     *    sender was sent the matching receipt whenever the record carried a reply address.
+     *    `detail: { settlement, reason, seq, box, fromSession?, heldCount, sessionId, runId }`. Audience
+     *    `"user"`: it is this session's user who held (or was holding) the message.
+     *  - `"peer.idle_subscription"` (design/385 §5.2, slice 4) — a peer session asked to be told when
+     *    THIS session next goes idle (`SendMessage … notify_when_idle`). `detail.outcome`: `"recorded"`
+     *    / `"refreshed"` (a same-requester re-ask; the subscription is one-shot and expires unfired after
+     *    12 h), `"full"` (the 32-entry table is full) or `"refused"` (this session's `crossSessionInbound`
+     *    is `refuse`) — the last two answered the requester with an `unavailable` notice. `detail:
+     *    { outcome, fromSession, live, seq, box, sessionId, runId }`. Audience `"user"`: the person whose
+     *    session is being watched is the one entitled to know (CC announces it in the session UI).
      *
      *  - `"delegation.transcript_integrity"` (subagent transcript persistence) — a durable agent row
      *    with a BOUND transcript sessionId met a session store that attests `not_found` for it: the
@@ -6891,6 +7057,25 @@ export interface RunnerDeps {
             consecutiveFailures: number;
             lastCause: string;
         }) => void;
+        /**
+         * The classifier DENIAL LIMIT (CC 2.1.250 `FO`/`AKe`): a run whose classifier keeps blocking falls
+         * back to a PERSON instead of being denied without end. Per run: a `block` first increments the
+         * consecutive and total counts and then judges `consecutive >= maxConsecutive || total >= maxTotal`
+         * — the block that reaches a bound is itself the one that becomes an `ask` (the 3rd consecutive
+         * block asks). That ask carries `requiresRealApproval: true` (no automatic lane may clear it — not
+         * a sandbox admission, not an inherited resolver, not a blanket `onAsk:"allow"`) plus the additive
+         * `denialLimitFallback` member with the counts and its own auto-deny window; an unanswered ask
+         * auto-denies after `autoDenyAfterMs` (default 120s; `0` = no window). A classifier allow, or a
+         * person's allow of the fallback ask, zeroes the consecutive count; reaching the total bound
+         * zeroes everything. With no approver wired at all (headless), the fallback has nowhere to go and
+         * the run STOPS with `TaskResult.errorCode = "classifier.denial_limit"` (a notice of the same
+         * code is minted).
+         *
+         * Every member optional (defaults 3 / 20 / 120_000). A present member with a bad value is refused
+         * loudly at prepare — never clamped, never silently read as the default.
+         * See {@link import("./auto-mode.js").AutoModeDenialLimitOptions}.
+         */
+        denialLimit?: import("./auto-mode.js").AutoModeDenialLimitOptions;
         /**
          * #503 — OPT IN to recording this arming's serializable criteria (an
          * {@link import("./auto-mode-arming.js").AutoModeArmingRecipe}) on the constraint-chain entries a
@@ -7051,6 +7236,18 @@ export interface RunnerDeps {
      * everywhere (mode parity, the CC default). Inert without {@link peerDirectory}.
      */
     crossSessionInbound?: import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers | (() => import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers);
+    /**
+     * design/385 §4.4 (slice 4) — this deployment's `dialogExpiry` (CC settings key, verbatim vocabulary
+     * `"60s" | "5m" | "10m" | "never"`, default `"5m"`): how long a HELD cross-session message whose cause
+     * a human review could resolve (mode-mismatch / no-mode-asserted / invalid attestation) waits in this
+     * session's held queue before it resolves to its safe no-action default — EXPIRED, dropped WITH a
+     * receipt to the sender, never silently. `"never"` disables the deadline. Read at every drain round
+     * (getter form for a host that re-reads its settings). A value outside the vocabulary is announced
+     * ONCE per leg through `onError` (`classification: "peer-dialog-expiry"`) and the default applies —
+     * a garbage setting never silently reads as a policy. Absent = the default. Inert without
+     * {@link peerDirectory}.
+     */
+    crossSessionDialogExpiry?: import("../agents/peer-notices.js").CrossSessionDialogExpiry | (() => import("../agents/peer-notices.js").CrossSessionDialogExpiry | undefined);
     /**
      * design/164 件五 — DEPLOYMENT-level usage governance: allowances that span TASKS, evaluated per
      * principal (or once for the whole deployment when a task declares none). A different axis from

package/dist/index.d.ts

@@ -125,7 +125,7 @@ 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";
@@ -284,7 +289,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, 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 { 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

@@ -102,7 +102,7 @@ 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";

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" },
@@ -151,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).`);
@@ -205,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);
@@ -282,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);
@@ -305,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" },
@@ -373,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);
@@ -389,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);
@@ -405,7 +424,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
 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) {
+export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
     return defineTool({
         name: "NotebookEdit",
         contract: { contractId: "core.notebook_edit@1", implementationRevision: "1" },
@@ -543,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) {