@sema-agent/core 7.5.2 → 7.6.1

package/dist/core/hooks.d.ts

@@ -1,8 +1,12 @@
 import type { ActorAssertion, DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
 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,
@@ -385,30 +389,7 @@ export declare function runHookSeat<T>(seat: HookSeatName, bound: HookSeatBound,
  * expiry, including the ones where the bound was never reached.)
  */
 export declare function hookSeatExpiredError(seat: HookSeatName, timeoutMs: number, cause: "timeout" | "aborted", consequence: string): Error;
-/**
- * Where a {@link Hooks.permissionDenied} deny came from — our gate-source enum standing in for CC's
- * `decision_reason_type` ('classifier'|'asyncAgent'|'mode'|'rule'), named after OUR adjudicate-chain
- * sources (design/134 R5):
- *  - `"policy"` — the ToolPolicy denied directly, or a policy-raised `ask` resolved to deny
- *    (headless auto-deny / approver said no / approval aborted).
- *  - `"hook"` — a PreToolUse hook `ask` (folded allow→ask) resolved to deny, OR the engine's fail-closed
- *    interception of a hook that THREW (RB-442). (A hook's own `deny` short-circuit is EXCLUDED from the
- *    event — a decision the hook made; the crash interception is a decision the ENGINE made. The
- *    exclusion is ours on that merit; see {@link Hooks.permissionDenied} for why it must NOT be read
- *    as a parity claim about this seat's trigger surface.)
- *  - `"safety"` — the gate's deterministic egress/irreversibility tighten (design/70 / design/77 §4)
- *    raised the `ask` that resolved to deny, from an explicit per-tool mark.
- *  - `"shellGate"` — same tighten-deny, but the tool's irreversibility tier was installed by the COARSE
- *    `TaskSpec.shellGate` doctrine (design/80 D-E), not an explicit per-tool mark.
- *  - `"planMode"` — the design/108 plan-mode write-deny short-circuit (a read-only fidelity gate).
- *  - `"org"` (design/182 §7) — the ORG layer: an organization deny rule, or the fail-closed tighten an
- *    org-governed deployment applies while it cannot adjudicate against a snapshot (that tighten's ask
- *    then resolving to deny). Its own word rather than `"policy"` because the authority is the ORG's
- *    published snapshot, not this deployment's `ToolPolicy` — an operator reading "policy" on a call
- *    their own policy allowed would be looking in the wrong place.
- */
-export type PermissionDeniedSource = "policy" | "hook" | "safety" | "shellGate" | "planMode" | "classifier" | "org";
-/** The payload a {@link Hooks.permissionDenied} callback observes (CC-exact fields + `source`). */
+/** The payload a {@link Hooks.permissionDenied} callback observes (CC-exact fields + the gate outcome). */
 export interface PermissionDeniedPayload {
     /** #281 件A — the run/leg identity envelope. Present on every ENGINE emission (the gate's single
      *  deny exit, the hook-crash intercept, the plan-mode and compliance denies); absent only when a
@@ -421,33 +402,20 @@ export interface PermissionDeniedPayload {
     toolCallId: string;
     /** Human/model-readable deny reason (CC `reason`) — the RAW decision text, NOT `<system-reminder>`-wrapped. */
     reason: string;
-    /** Which gate source produced the deny (our `decision_reason_type` analog). */
-    source: PermissionDeniedSource;
-    /** The ask resolver's own deny-arm classification, carried BESIDE `source` (two different
-     *  questions: `source` names which LAYER raised the gate; this names HOW the ask resolution
-     *  refused — a person's no vs a timeout vs headless vs an approver contract violation …). Present
-     *  only on a deny that came through an ask resolution AND whose word passed the closed-vocabulary
-     *  screen; a policy's direct deny, a hook deny, and the crash/plan-mode/compliance emissions carry
-     *  none. See {@link import("./tool-policy.js").AskDenyResolution}. */
-    resolution?: import("./tool-policy.js").AskDenyResolution;
-    /** #548 — the deny is the classifier denial-limit fallback's AUTO-DENY (core's own window elapsed;
-     *  see {@link import("./tool-policy.js").ResolvedAsk.autoDenied}). Carried verbatim from the resolver;
-     *  absent on every other deny. */
-    autoDenied?: true;
+    /**
+     * The gate outcome this deny is — the SAME object the call's `tool_end` frame carries as `gate` and
+     * the engine's per-call sideband records (one mint, three faces). `disposition.deniedBy` says which
+     * LAYER refused (our `decision_reason_type` analog for the refusing half); when the refusal came through
+     * an ask resolution, `settlement` says how the wait ended and `origin` who asked. Nothing is read out of
+     * an absence: a direct policy / hook / plan-mode / compliance deny carries no settlement because it
+     * settled none.
+     */
+    gate: GateOutcome;
     /** {@link HookSeatSignal} — this invocation's own abort signal. On an OBSERVATION seat the deny has
      *  already happened and nothing this callback does can change it, so the signal says exactly one
      *  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
@@ -927,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`). */
@@ -943,46 +902,14 @@ export interface ToolGateResult {
     /** Model-readable block reason (already `<system-reminder>`-wrapped). */
     reason?: string;
     /**
-     * What ended the approval this call was waiting on, when this gate pass settled one (the ask
-     * resolution's own {@link import("./tool-policy.js").ApprovalSettledBy}, carried out verbatim — this
-     * layer classifies nothing). Present on BOTH terminal exits, the block and the allow: an approved
-     * call is a settled approval too, and a caller that saw the source only on refusals would read its
-     * absence on an execution as "nobody approved this". Absent on everything that settled no approval —
-     * a straight policy deny, a hook deny, a posture verdict where nobody was asked, every ordinary
-     * allow. The caller records it on its own per-call sideband so it reaches that call's `tool_end`
-     * frame: the machine-readable half of the disclosure `reason` makes in words, on a channel no tool
-     * and no post-tool hook can write.
-     */
-    settledBy?: import("./tool-policy.js").ApprovalSettledBy;
-    /**
-     * The ask resolver's deny-arm classification (see {@link import("./tool-policy.js").AskDenyResolution}),
-     * present only on a BLOCK whose deny came through an ask resolution and passed the closed-vocabulary
-     * screen at the deny exit (a self-declared word on a policy's own deny is dropped there, never
-     * forwarded). Rides beside {@link settledBy} to the caller's per-call sideband and the call's
-     * `tool_end` frame — the machine-readable "why was this refused" a consumer classifies on.
-     */
-    resolution?: import("./tool-policy.js").AskDenyResolution;
-    /**
-     * `true` ⇔ this BLOCK is the classifier denial-limit fallback's own auto-deny: the ask's window
-     * (`AskRequest.denialLimitFallback.autoDenyAfterMs`) elapsed with nobody answering and the resolver
-     * refused it itself — the same fact the `permissionDenied` observer payload's `autoDenied` carries,
-     * read from the same two places (this gate's own resolution, or the module-private attestation an
-     * inherited arm bound to THIS call). Rides to the call's `tool_end` frame so a consumer can tell
-     * "the classifier fallback's own 120 s window auto-denied" from "the approval factory's own window
-     * (`approvalTimeoutMs`) elapsed" — both settle as `settledBy:"timeout"` / `resolution:"window_expired"`,
-     * and the factory's deadline NEVER carries this. A durable park's expiry settles on the decide lane
-     * with no `resolution` word, so it is told apart by that absence, not by this bit.
-     * Absent everywhere else (a person's no, a policy deny, an executing call).
+     * The record of this pass ({@link GateOutcome}): its final disposition, the ask it settled (if any) and
+     * that ask's origin. Present on BOTH terminal exits, the block and the allow — an approved call is a
+     * settled approval too, and a caller that saw the record only on refusals would read its absence on an
+     * execution as "nobody approved this". Absent only on the durable-suspend exit, where the pass decided
+     * nothing yet. The caller records it on its own per-call sideband so it reaches that call's `tool_end`
+     * frame, and the deny observer receives the same object: one mint, three faces.
      */
-    autoDenied?: true;
-    /**
-     * design/252 G-7 — WHOSE settlement that was: the identifier the approval channel reported, carried
-     * out verbatim beside {@link settledBy}. This layer authenticates nothing and compares nothing; the
-     * value was screened for shape at the seam that received it (`screenApproverAttribution`) and is a
-     * transcription from there on. Present only where the caller settled something AND reported an
-     * identity — absent everywhere else, and absence never means "nobody": it means nobody said.
-     */
-    approver?: string;
+    gate?: GateOutcome;
     /** Rewritten args to execute with (re-validated by the loop); omitted when nothing rewrote. */
     updatedInput?: unknown;
     /**
@@ -1140,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
@@ -1703,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