@sema-agent/core 7.6.0 → 7.6.1

package/dist/core/hands-band.d.ts

@@ -0,0 +1,134 @@
+/**
+ * design/138 S2-C — the hands band's write-time CONTENT hook (single source; `src/tools/fs` re-exports
+ * these so its import surface is unchanged — moved here by design/141 件2 because `RunnerDeps.hands`
+ * carries the deployment-composable half of the hook). Called before EVERY `env.writeFile` in
+ * Write/Edit/NotebookEdit with the resolved containment key and the exact final text; `{ ok:false }`
+ * fails the tool with a structured error and NOTHING is written. A THROWING hook fails CLOSED.
+ */
+export interface BeforeWriteRequest {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument (for the error-message coordinate the model knows). */
+    path: string;
+    /** The resolved canonical containment key — what the hook should judge. */
+    key: string;
+    /** The FINAL full text about to be written (Edit/NotebookEdit: after application). */
+    content: string;
+}
+export type BeforeWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export type BeforeWriteHook = (req: BeforeWriteRequest) => BeforeWriteResult | undefined | Promise<BeforeWriteResult | undefined>;
+/**
+ * design/381 — the hands band's FIRST-TOUCH HISTORY hook, called before EVERY file mutation in
+ * Write/Edit/NotebookEdit (after the `beforeWrite` content gate passed, immediately before the
+ * final env write) with the resolved canonical containment key. The Runner wires it to
+ * `FileHistoryStore.trackEdit` (backup-before-first-edit, the CC FileHistory trigger-point set
+ * minus the bash simulation arm sema does not have — DV-7); later calls for an already-tracked
+ * path are cheap store no-ops. `{ok:false}` carries the REFUSAL TEXT the tool must answer instead
+ * of writing (DV-14 default: no durable first-touch state ⇒ the edit is refused, typed and loud —
+ * any proceed-unprotected policy is resolved INSIDE the hook by the Runner, never by the band).
+ * A THROWING hook fails CLOSED (same posture as the write gate). Absent hook ⇒ byte-identical
+ * behavior (no history store wired).
+ */
+export interface TrackEditRequest {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument (for the error-message coordinate the model knows). */
+    path: string;
+    /** The resolved canonical containment key — the identity the history record is keyed on. */
+    key: string;
+    /** The tool call's abort signal, threaded into the store's env read. */
+    signal?: AbortSignal;
+}
+export type TrackEditResult = {
+    ok: true;
+    /**
+     * #491 — the compensating handle for the ordering the topology cannot avoid: the pre-image
+     * capture runs BEFORE the write, so a write that then FAILS (lost create race, ENOSPC,
+     * EACCES, read-only mount) would leave a first-touch record for an edit that never happened —
+     * and an `existed-not` record makes an untouched path a rewind DELETE target, removing bytes
+     * whoever writes them next (the user, a peer process) owns. Present ONLY when THIS call minted
+     * the record (an already-tracked path belongs to the edit that first touched it and must never
+     * be discarded); the band calls it on the write-failure arm of every mutation lane. `proof`
+     * says which retraction rule applies: `"proven"` = the write's own error code guarantees
+     * nothing was written, `"verify"` = ambiguous, so the history seat must re-read the path and
+     * retract only if it still matches what the first touch recorded. It never throws and never
+     * blocks the failure it accompanies — the original write error is the answer.
+     */
+    annul?: (proof: "proven" | "verify") => Promise<void>;
+} | {
+    ok: false;
+    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
+ * state (taskRegistry/detachHub/execClamp/cwdRef/mount coordination) is deliberately NOT configurable.
+ */
+export interface HandsBandOptions {
+    /** Override the `bash_readonly` command allowlist (read-only band). Default: the built-in read-only set. */
+    bashReadonlyAllow?: readonly string[];
+    /** Co-Authored-By trailer for the bash git protocol. Default NONE ([c209] BREAKING: attribution is a
+     *  deployment identity asset — the branded scenario sets `"Name <email>"`); `false` ≡ unset. */
+    commitCoAuthor?: string | false;
+    /** Read-tool image downsampler: inject your own, or `false` to force-disable (deterministic no-sharp).
+     *  Omitted ⇒ auto-detect sharp. Same contract as the MCP-side {@link import("./mcp.js").ImageDownsampler}. */
+    readImageDownsampler?: ((input: Buffer, mimeType: string) => Promise<import("./mcp.js").DownsampledImage | undefined>) | false;
+    /** Deployment write gate — COMPOSED with (never replacing) the engine's MemoryEngine write-scan gate:
+     *  this hook judges first (a rejection short-circuits), the engine gate then still runs in full. */
+    beforeWrite?: BeforeWriteHook;
+    /** RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity): on a foreground Bash command's OWN timeout, an eligible
+     *  command (see `canAutoBackground` — no `git` anywhere in the command, not a `sleep`-first-word wait) is
+     *  adopted as a background task instead of being killed — CC's own posture ("received no response for
+     *  Nms" would otherwise force a wasteful blind re-run of a non-idempotent long command). Default `false`
+     *  (byte-compat): this is a deployment-level opt-in, deliberately NOT inferred from background-task
+     *  plumbing (`detachHub`/`taskRegistry`) merely being present, since the Runner wires those unconditionally
+     *  for every task — tying eligibility to their mere presence would silently flip the timeout outcome for
+     *  every existing caller with no explicit signal at all. */
+    autoBackgroundOnTimeout?: boolean;
+    /** Append the per-read content-safety reminder after a successful text read (the ~50-token
+     *  `<system-reminder>` the Read tool adds to a text body — the plain-text and notebook read paths;
+     *  PDF text extraction has its own result builder and has never carried the reminder, so this switch
+     *  does not govern it). Default TRUE, and an omitted field keeps
+     *  that default: a BYOM engine cannot assume its serving model carries that mitigation internally, and
+     *  the reminder only works because it sits next to the bytes it is about — not in a system prompt
+     *  hundreds of turns back.
+     *
+     *  Pass `false` to state that THIS deployment's serving model does carry it, and stop paying the
+     *  reminder's tokens on every text read for advice the model already applies. Absent and `false` are
+     *  deliberately different decisions: absent means "unknown, so assume not". */
+    readCyberReminder?: boolean;
+}

package/dist/core/hands-band.js

@@ -0,0 +1 @@
+export {};

package/dist/core/hooks.d.ts

@@ -2,8 +2,11 @@ import type { ActorAssertion, DocumentContent, ImageContent, TextContent } from
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
 import type { DecisionReason, PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
 import type { GateOutcome } from "./gate-outcome.js";
+export { normalizeOrgGateVerdict, normalizePersistedRuleHit, persistedRuleMandateOf } from "./gate-lanes.js";
+export { cloneObserverInput } from "./runner/gate-exit.js";
 import { type AskClass } from "./ask-class.js";
-import { type AutoModeDenialTracker } from "./auto-mode.js";
+import type { AutoModeDenialTracker } from "./auto-mode.js";
+export { formatHookFeedback } from "./reminder-mint.js";
 import type { WiringLegKind } from "./wiring-manifest.js";
 /**
  * In-process hook seam (design/37) — a provider-agnostic interception layer modeled on CC's hooks,
@@ -413,15 +416,6 @@ export interface PermissionDeniedPayload {
      *  thing: stop reading, nobody is waiting for your answer any more. */
     signal?: AbortSignal;
 }
-/**
- * 1.256 复审 MED-1 — observe-only payload isolation for {@link Hooks.permissionDenied}: clone the tool
- * args before they ride the observer payload, so a hook mutating `payload.input` can never pollute the
- * LIVE args object (later events / audit records share it). Same posture as the postToolUseFailure
- * details clone (prepare-task): `structuredClone` first; a non-structured-cloneable graph
- * (functions/handles) falls back to a SHALLOW plain object/array copy (top-level mutation isolated);
- * a non-object primitive passes through as-is (immutable anyway).
- */
-export declare function cloneObserverInput(input: unknown): unknown;
 /** Context for {@link Hooks.stopFailure} — aligned with the TaskResult error face (observe-only). */
 export interface StopFailureContext {
     /** #281 件A — the run/leg identity envelope (always present on the engine's emission; the seat is
@@ -901,15 +895,6 @@ export interface UserPromptSubmitResult {
     /** Injected ahead of the user's prompt (wrapped as a `<system-reminder>`). */
     additionalContext?: string;
 }
-/** Wrap model-facing hook/gate feedback in a `<system-reminder>` so it reads as guidance, not data.
- *  NOTE (council design/74 #6): this does NOT escape a literal `</system-reminder>` in `text` — callers MUST
- *  pass trusted, first-party strings (every current caller does: fixed gate/limit messages). If a future
- *  caller needs to relay UNTRUSTED content (tool output, user data), it must sanitize the close tag first
- *  (or use the `delimitUntrusted` fence), or a crafted payload could break out of the reminder framing.
- *  design/319 (A ticket): `mark` is the session's reminder provenance mark — run-scoped callers thread it
- *  so the open tag carries the value the system-prompt declaration names (rendered by the mint home; the
- *  body is byte-untouched). Absent ⇒ the historic bare open tag (a caller outside a run). */
-export declare function formatHookFeedback(text: string, mark?: string): string;
 /** The outcome of the two-phase tool gate, mapped onto the harness `tool_call` hook return shape. */
 export interface ToolGateResult {
     /** Block execution (the loop emits an error tool result with `reason`). */
@@ -1082,53 +1067,6 @@ export interface PersistedRuleCoverage {
 }
 /** Every shape a lane may answer with. A bare string stays valid and unchanged. */
 export type PersistedRuleAnswer = string | PersistedRuleHit | PersistedRuleCoverage | PersistedRuleUnreadable | undefined;
-/**
- * design/252 review r3 — read a foreign {@link OrgGateVerdict} the way the personal-rule answer is read:
- * OWN DATA properties only, never the prototype chain, never an accessor.
- *
- * Unlike the personal-rule normalizer below, this one accepts ANY non-array object as the carrier —
- * not only a plain record. The two seams tighten in opposite directions when a shape is refused: the
- * personal lane is a LOOSENING seam, so refusing a class instance degrades toward asking; this answer
- * carries the org's DENY, and folding a structurally valid `{status:"available", verdict:{behavior:
- * "deny"}}` class instance into `unavailable` would LOOSEN it — from a deny nobody can approve into a
- * real-approval ask a person can clear. A class instance's fields are its own data properties, so the
- * own-data read below already gives the full pollution guarantee (inherited members never authorize);
- * the prototype test added nothing here but the downgrade.
- *
- * The two seams are the same class of trust boundary and were not being read the same way. What that
- * cost here is worse than on the personal lane, because this answer is GOVERNANCE:
- *  · an inherited `revision` (a polluted `Object.prototype`) stamped a fabricated snapshot version onto
- *    a human's approval request — a WRONG record, which is worse than an absent one;
- *  · an inherited `verdict` invented an org rule, and with it an org ask or deny the lane never gave;
- *  · an answer that is not a record at all read as "available, nothing to say", i.e. the governance
- *    fail-open the availability contract exists to prevent.
- * Anything this function cannot read as a well-formed answer becomes `unavailable` — the fail-CLOSED
- * word, never the empty one.
- */
-export declare function normalizeOrgGateVerdict(answer: unknown, unreadable: string): OrgGateVerdict;
-/**
- * Normalize the accepted {@link ToolGateInput.persistedRules} answers into one reading.
- *
- * `{}` = a clean negative (no rule admits this call). `{ unreadable: true }` = the lane could not read
- * its source. `{ hit }` = a match, whose `rules` is the non-empty coverage set (design/375). An answer
- * outside every accepted shape — a number, `null`, an object with neither `rules` nor `unreadable`, an
- * EMPTY `rules` array, the retired pre-375 `{ rule, dots? }` single-rule object — is read as a clean
- * negative rather than a match: this is a LOOSENING seam, so an answer nobody can name degrades toward
- * asking, never toward an allow built on it. All-or-nothing across the set's TEXTS for the same
- * reason: a set with one unreadable member is a different (smaller) claim than the lane made, and a
- * decision must not stand on a claim nobody made — one bad member drops the whole answer to the clean
- * negative. Per-member DOTS stay individually optional (identity lost ⇒ `"not_reported"`, exactly the
- * single-rule contract).
- *
- * The hit's dots are COPIED, not aliased. The array travels onto an ask that may sit in front of a
- * person for a long time; a lane that retains and mutates its own array would otherwise change what the
- * approver is looking at, and what an audit later reads, after the evidence was stamped.
- */
-export declare function normalizePersistedRuleHit(hit: PersistedRuleAnswer): {
-    hit?: PersistedRuleHit;
-    unreadable?: true;
-    coverage?: readonly import("./permission-rule-model.js").SegmentCoverage[];
-};
 /** Inputs to the two-phase tool gate. `adjudicate`/`resolveAsk` are pre-bound to the task abort
  *  signal; when the caller also supplies {@link ToolGateInput.callSignal}, the Runner's closures
  *  additionally bind their waits to that per-call signal (`AbortSignal.any` of the two), so a turn
@@ -1645,41 +1583,6 @@ export declare function createPreToolUseConstraintPolicy(preToolUse: NonNullable
  *  walltime and no cancel, the race never fires. So the same seat bound rides here too, and the two
  *  installations of one callback are now bounded the same way for the same reason. */
 timeoutMs?: number): ToolPolicy;
-/**
- * The mandate provenance of one call, judged from the SAME mark inputs the gate is driven with —
- * the single source for "could a persisted allow rule clear this ask?". Allow rules silence the
- * classifier's questions, never a mandated one, and this predicate is the mandated-family half of
- * that boundary (the real-approval/governance half rides the decision's own `requiresRealApproval`
- * bit, which the org layer stamps):
- *  · `probeMandated` — this CALL's own reversibility probe declared its demotion STRUCTURAL
- *    (`"probe_mandate"`), judged FIRST because it is the only per-call member here: the three below
- *    are properties of the TOOL and are true of every call on the seat, so a mandate that is true of
- *    this one call must not be shadowed by the tier that happens to carry it (#502: the built-in
- *    shell probe raises it for a listed reader naming a path outside the session's roots — a boundary
- *    the deployment declared, which is exactly what the classify tier alone cannot say);
- *  · `egress` — the tool's own external-write mark, judged next: it is the tool's declaration even
- *    when the coarse doctrine also installed a shell tier on the same seat;
- *  · `shellGated` + tier `"always"` — the operator's per-call confirmation doctrine
- *    (`"operator_always"`); the classify doctrine installs `"maybe"`, and THOSE asks stay the rule
- *    lane's home turf (`undefined`) — that is the don't-ask-again main case, and the per-call member
- *    above is deliberately the ONLY thing that carves a mandate out of it;
- *  · a tool's OWN `"always"`/`"maybe"` irreversibility tier without the doctrine (`"tool_marks"`).
- *
- * Two consumers, one derivation: the gate's silencing arm (a matching rule is disclosed as shadowed
- * instead of clearing the ask) and the runner's suggestion factory (a mandated ask offers no
- * "stop asking me this" option — a rule minted from it would never clear it). A drift between the
- * two would let a card offer a rule the lane then refuses to honor. The per-call member reaches both
- * the same way every other per-call fact does: the gate stamps it on the surviving ask, the
- * synchronous sites read it off the decision they spread, and the park leg threads its own parameter.
- */
-export declare function persistedRuleMandateOf(marks: {
-    egress?: boolean;
-    shellGated?: boolean;
-    irreversibility?: "never" | "maybe" | "always";
-    /** #502: the surviving ask's engine-stamped `probeMandated` — see
-     *  {@link import("./types.js").ReversibilityVerdict.mandated}. */
-    probeMandated?: boolean;
-}): "operator_always" | "tool_marks" | "probe_mandate" | undefined;
 /**
  * The park closure's ONE structural seat — what the gate hands the durable park beyond the twelve
  * positional seats. Every member is optional and read by name, so a new thing the park must know
@@ -1709,4 +1612,20 @@ export declare function askCarryRowMembers(carry: AskCarry | undefined): {
     denialLimitFallback?: import("./auto-mode.js").DenialLimitFallback;
     origin?: import("./ask-origin.js").AskOrigin;
 };
+/**
+ * The design/37 **two-phase tool gate** — the single chokepoint that makes the load-bearing invariant
+ * structural ("a hook's `allow` cannot bypass the policy's `deny`/`ask`"):
+ *
+ *  1. **collect** — run the PreToolUse hook, threading any `updatedInput` rewrite into `currentInput`
+ *     and collecting `additionalContext`. A hook `deny` short-circuits to a block immediately; a hook
+ *     `ask` is remembered (it does not short-circuit — a later policy `deny` outranks it).
+ *  2. **adjudicate** — run the tool policy on the FINAL `currentInput` (never the model's stale args),
+ *     fold it with any remembered hook-ask via `deny > ask > allow`, and resolve a surviving `ask`
+ *     through `onAsk`. The policy ALWAYS runs regardless of the hook's verdict. A policy `allow` may
+ *     itself carry an `updatedInput` rewrite (redact/clamp), applied last over any hook rewrite.
+ *
+ * Because both phases run in this one linear function, the ordering — and the "policy is final"
+ * invariant — is enforced by the call stack, not by registration convention. Returns the gate result
+ * for the harness `tool_call` hook plus the PreToolUse context to attach to the tool result.
+ */
 export declare function runToolGate(input: ToolGateInput): Promise<ToolGateResult>;