@sema-agent/core 5.27.0 → 5.29.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 5.29.0 — 2026-08-13
+
+No API-BREAKING changes (exports grow only: `AskOutcome.reason`, `AskRequest.isDelegatedChild`).
+
+### Changed (behavior)
+
+- **A human deny speaks a posture and can carry the decider's words.** The sync approval seat
+  `AskOutcome` gains `reason?: string` on its object arm: attached to a deny, the text reaches the
+  model inside the untrusted fence, bounded to 2048 code points — the same containment and bound as
+  the durable leg's reviewer note (whose four relay sites were previously unbounded and now share
+  the cap). Refusal messages fork on the issuing run's position (`AskRequest.isDelegatedChild`,
+  forks included): a parent-thread run is told to STOP and wait for the user, a delegated child is
+  told to adapt or report; the machine-greppable head line is unchanged. On an allow the seat is
+  never read; a non-string reason on a deny is refused loudly; timeout denials carry the note under
+  a neutral bridge. NOTE: the posture is model-facing text — making a parent-thread denial abort the
+  in-flight batch is registered follow-up work.
+- **`worktreeDir` never names a non-host path.** A remote isolated agent's sandbox cwd is no longer
+  recorded (`ResolvedWorkspace` gains a required `remote` key; absence on the record now means
+  "shared tree OR remote sandbox"), and a workspace observation is authoritative replacement state —
+  a local→remote retry clears the stale host path.
+- **Session freshness is judged by conversation content, not branch entries.** A pre-minted
+  sessionId or a host-pre-seeded marker (naming the chat, recording a model pick before the first
+  turn) no longer stamps `legacy_migration` on a brand-new session's first epoch pin — and no longer
+  silently costs such a session its published center prompt (the adoption arm shared the same
+  refuted entry-count proxy; all three freshness sites now share one predicate).
+- **The ask-question tool teaches previews.** The tool description carries the Preview feature block
+  (CC markdown variant, verbatim), so the preview card form — the only question form whose answer
+  carries user notes — is reachable.
+- The resident execution-environment prompt line about denied calls no longer instructs a blanket
+  "adjust and continue" — it defers to the denial message's own guidance (prompt golden re-frozen).
+
+## 5.28.0 — 2026-08-12
+
+No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.
+
+### Narrowed (behavior, ruled)
+
+- **A hook-promoted ask's provenance is stamped, never read back.** Every consumption point keying
+  on `decisionReason === "hook"` now reads an engine-stamped value: the fold reconstructs the
+  promoted ask from an explicit member whitelist and stamps `"hook"` unconditionally, so a hook
+  self-declaring any other word (or extra members like `persistedRuleShadowed`) cannot change how
+  the persisted-rule lane, the rule-suggestion factory, or the inherited-frame reuse treat the ask.
+- **A `decisionReason` outside the closed set is refused at the consumption screen.** A
+  deployment-authored `ToolPolicy.check` returning an unrecognized word (or routing the field
+  through a getter/prototype) is denied fail-closed with the closed set named; plain decisions pass
+  by reference. The HOOK seam is exempt by design (the field is a documented non-input there — see
+  the stamp above).
+- **The served org snapshot meets the same validator as a fetched one.** A persisted last-known-good
+  snapshot carrying a rule the current validator refuses now fails closed during a provider outage
+  instead of serving partial policy.
+- **Legacy rule text the current validator refuses no longer stalls sync.** A shape-whole tombstone
+  whose TEXT is refused gets the new closed-set reason `invalid_rule_text` — disclosed, quarantined,
+  and no longer withholding the whole inbound-adds round (safe: tombstones match byte-identical
+  text only, and an add with that text is refused by the same predicate).
+- **Case-colliding scope directories are refused loudly on case-insensitive filesystems.** Two
+  scopes differing only by case no longer silently share one physical directory (macOS/Windows);
+  collision detection compares folded identity (dev:ino-keyed), with lazy real probing instead of
+  platform guessing.
+- **Spill provenance is session-only, and a failing spill degrades instead of poisoning.** The agent
+  spill write points stamp `{sessionId}` (matching the offload/budget/compaction form); a failed or
+  conflicting spill put defers to a sibling-proven ref or reports honestly — a legacy-shape row can
+  no longer make an agent result permanently unreadable (guarded put + generation guard + coherent
+  poll snapshot).
+
+### Added
+
+- `onNotice` structured notice seat (three families: `config.env_timeout_discarded`,
+  `config.materialize_env_discarded`, `tool_result.offload_put_failed` — this entry originally said
+  "first two families"; corrected 2026-08-12, the third family shipped in the same release) — absent
+  keeps the `console.warn` text verbatim; a present non-function seat is announced once and falls
+  back loudly instead of silencing both channels.
+- `tool_end.errorCode` now reads both discriminator spellings — `details.code` first (string), then
+  `details.errorKind` — so loop-thrown error frames are classifiable; `code` wins when both exist.
+- `ToolResultStore.deleteBySession?` (optional member; File + in-memory implementations, not on the
+  scoped wrapper, not in the published contract kit) — returns `{ deleted, unattributable }`;
+  selection keys on recorded provenance, unowned rows are counted and never deleted. A put refused
+  over an orphan sidecar un-publishes its own content (pre-call state restored), and a damaged
+  re-published survivor is counted unattributable.
+- Adopt-on-read ledger writes are serialized behind the existing cross-process txn mutex (lock-free
+  probe fast path; divergence acquires the mutex, reloads the ledger from disk, and re-verifies
+  lock ownership at recovery, side-effect and commit points) — cross-process lost-update closed.
+- `runTaskStream` refuses an out-of-shape `resume` synchronously (a resume without `outcome` used to
+  hang `stream.result()` forever).
+- `docs/INTEGRATION-CORE.md` — the core→embedder contract document (event-frame per-key obligations,
+  code-vocabulary pointers, TaskResult matrix, resume/decide shapes, store optional-member table);
+  maintained per L3 release.
+- Rule-suggestion admission honesty (#174 adjacency): the suggestion factory keys on the stamped
+  provenance.
+
+### Fixed
+
+- Control-character gate: five bench probe arms now genuinely reach their claimed product paths;
+  the published B2 index-truncation curve was corrected to `[0, 0, 0.005, 0.602]` (the old counting
+  masked a real N200 loss).
+- `TaskResult.retryAfterMs` and `tool_end.errorCode` JSDoc corrected to match code (two accepted
+  codes; the errorKind fallback).
+
 ## 5.27.0 — 2026-08-11
 
 No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.

package/dist/agents/cascade.d.ts

@@ -9,7 +9,7 @@ import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
  * APPLICABILITY: cascade only helps when the gate is **decidable** (a schema check, a verifier model, a
  * concrete assertion). Open-ended "completeness" tasks (find every bug, writing quality) have no oracle —
  * the gate keeps passing the first plausible cheap answer and escalation idles. Those want breadth /
- * adversarial debate (a `team`), not a depth ladder.
+ * falsification-style debate (a `team`), not a depth ladder.
  *
  * Cost note (design/27 §2): each rung is an independent COLD `runTask` — every escalation repays the
  * full input cost. Cascade wins when (a) the cheap rung usually passes and (b) the prompt isn't so large

package/dist/agents/observer.d.ts

@@ -36,11 +36,11 @@ export type ObserverDigestEvent = {
     type: "turn_ended";
     reason: string;
 };
-/** CC `S$r` — anti-injection: a forged envelope tag inside observed content is defused in place. */
+/** CC `S$r` — anti-injection: a caller-declared envelope tag inside observed content is defused in place. */
 export declare function escapeObserverTags(text: string): string;
 /**
  * CC `zZe` @8339092 — verbatim: `t.replace(new RegExp(`<(?=/?${e}(?:[>\\s/]|$))`, "gi"), "<\\")`.
- * Defuses a forged occurrence of ONE specific tag (opening AND closing) inside content — the second
+ * Defuses a caller-declared occurrence of ONE specific tag (opening AND closing) inside content — the second
  * escape layer CC applies to the DYNAMIC envelope tag (`<{slug}-activity>`) after joining, which the
  * static four-tag `escapeObserverTags` (Scg layer) cannot cover. Deviation from CC (hardening): the
  * tag is regex-escaped before entering the RegExp — CC interpolates raw, safe only because its slugs
@@ -281,7 +281,7 @@ export interface ObserverReportToolOptions {
  * `<${$Bt} from="${Yp(e)}">\n${zZe($Bt, t)}\n</${$Bt}>` with `$Bt = "agent-message"` @1344442.
  * Deviation from CC ($Bt=agent-message → observer-report, sovereign choice): we keep a dedicated
  * frame tag so the observed agent can tell an observer report from generic agent traffic. The
- * escape mechanics are CC-faithful: the frame tag itself is zZe-defused in the body (so a forged
+ * escape mechanics are CC-faithful: the frame tag itself is zZe-defused in the body (so a caller-declared
  * `</observer-report>` cannot break the frame) and the `from=` attribute value is Yp-escaped.
  * Additional hardening beyond CC: the body also rides through the four-event-tag Scg layer.
  *

package/dist/agents/peer-admission.d.ts

@@ -145,7 +145,7 @@ export declare function resetPeerAdmissionRegistryForTests(): void;
  * mounting is structurally single-sourced and survives any downstream projection of the payload).
  * Layered WITH the session-level `SUBAGENT_CONSENT_NOTICE` (prompts/default.ts), not replacing it:
  * that section governs COMMAND authority at session level; this block narrows AUTHORIZATION per
- * message. Placement per leg: OUTSIDE the `<teammate-message>` frame (a forged copy inside the
+ * message. Placement per leg: OUTSIDE the `<teammate-message>` frame (a caller-declared copy inside the
  * sender-controlled body arrives escaped, so position distinguishes the real block); the L3 resume
  * leg carries it in the TRUST-FRAME layer of the peer-resume prompt, never inside the data fence
  * (a load-bearing instruction inside a "this is DATA" fence would demote itself).

package/dist/agents/teacher.d.ts

@@ -13,7 +13,7 @@ import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
  * creative quality — because there is no oracle for *completeness*: the verifier can't know how many bugs
  * the code has or which one was missed, so a student that finds one obvious issue passes the rubric while
  * silently missing others, and the escalation machinery idles (verified in practice: 0 escalations, the
- * verifier becomes pure added cost). Such tasks are solved by **breadth + adversarial debate** (a `team`
+ * verifier becomes pure added cost). Such tasks are solved by **breadth + falsification-style debate** (a `team`
  * council), not by **depth escalation** — the two are orthogonal. See design/12 §六 for the full reasoning.
  */
 /** Default teacher (advisor) system prompt — returns ONLY structured JSON guidance. */

package/dist/agents/verify.d.ts

@@ -3,7 +3,7 @@ import type { Runner, ResumeTaskConfig } from "../core/runner/runtask.js";
 import type { CheckpointGate, CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
 import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js";
 /**
- * Verification gate (developer mode, design/28 §4). An **independent adversarial verifier** runs after
+ * Verification gate (developer mode, design/28 §4). An **independent falsification-style verifier** runs after
  * an implementation task and tries to BREAK it — read-only, evidence-required, returning a structured
  * verdict — then the gate loops fix→re-verify until PASS or a round cap.
  *
@@ -20,7 +20,7 @@ import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js"
  * SKILL.md` closest to the code it covers … and if that file does not exist, create it." So upstream's
  * position is "verification is project-specific; teach the user's repo to describe its own", not "here
  * is a verifier". This primitive is therefore a SUPERSET of what upstream ships in a different
- * direction than the old note implied: a spawned adversarial verifier with a fix loop, bundled. It is
+ * direction than the old note implied: a spawned falsification-style verifier with a fix loop, bundled. It is
  * orthogonal to and composable with the Stop hook (wire the verdict into a stop() hook to make it a
  * hard completion gate).
  *
@@ -31,7 +31,7 @@ import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js"
  * per task via {@link runWithVerification} (or {@link runDeveloperTask}).
  *
  * Boundary vs teacher mode: teacher's Tier-1 is a *lenient* rubric verifier that triggers escalation to
- * an advisor (stuck/wrong recovery); this is a *strict adversarial* completion gate with a fix loop.
+ * an advisor (stuck/wrong recovery); this is a *strict falsification-style* completion gate with a fix loop.
  * Orthogonal, composable, not merged.
  */
 export declare const VERIFICATION_PROMPT = "You are a verification specialist. Your job is NOT to confirm the implementation works \u2014 it is to try to BREAK it.\n\nYou have two documented failure patterns. First, verification avoidance: faced with a check, you find reasons not to run it \u2014 you read code, narrate what you would test, declare \"PASS,\" and move on. Second, being seduced by the first 80%: a polished result or a passing test suite makes you inclined to pass it, not noticing the edge that crashes, the state that vanishes, the bad input that is unhandled. The first 80% is the easy part. Your entire value is in finding the last 20%.\n\n## Hard boundary \u2014 do not modify the project\nYou are STRICTLY a verifier. Do NOT create, modify, or delete project files; do NOT install packages; do NOT run version-control write operations. Use only the read/probe/execute tools available to you. (If you need a scratch file, use a temp directory, and clean up.)\n\n## Evidence is mandatory\nReading code is NOT verification. Every check must actually run something \u2014 execute the code, hit the endpoint, run the build/tests \u2014 and record the command and its real output. A \"PASS\" with no command output is a skip, not a pass.\n\n## Strategy (adapt to what changed)\n- Build/lib changes: build it, run the full test suite, exercise the public API as a consumer would.\n- Backend/API: start it, call endpoints, check response *shapes* (not just status codes), test error paths.\n- CLI/script: run with representative AND edge inputs (empty, malformed, boundary); check stdout/stderr/exit codes.\n- Bug fix: reproduce the original bug first, verify the fix, then check for regressions and side effects.\n- Refactor (no behavior change): the existing suite must pass unchanged; diff the public surface; same inputs \u2192 same outputs.\nRun the project's own build/tests/linters as a baseline, then apply the type-specific checks. Test results are context, not proof \u2014 the implementer is an LLM too; its tests may be happy-path or circular.\n\n## Adversarial probes (pick the ones that fit)\nBoundary values (0, -1, empty, very long, unicode, max), idempotency (same mutating call twice), orphan operations (ids that don't exist), concurrency (parallel create-if-not-exists). Your verdict must include at least one adversarial probe you actually ran and its result \u2014 even if it was handled correctly.\n\n## Before you FAIL\nCheck you haven't missed why it's actually fine: defensive code elsewhere, intentional behavior documented in comments/specs, or an unfixable external-contract limitation (note that as an observation, not a FAIL). Don't wave away real issues, but don't FAIL on intentional behavior.\n\n## Verdict\nSubmit exactly one verdict via the provided output tool:\n- PASS \u2014 you ran real checks (including \u22651 adversarial probe) and it holds up. Put the commands + observed output in `evidence`.\n- FAIL \u2014 something is broken. Put each concrete problem (with how to reproduce) in `findings`.\n- PARTIAL \u2014 environmental limitation only (no test framework, a tool/server unavailable). Not for \"I'm unsure\": if you can run the check, decide PASS or FAIL. Note what you couldn't verify and why in `findings`.";
@@ -202,7 +202,7 @@ export interface VerificationResult extends TaskResult {
     verification: VerificationOutcome;
 }
 /**
- * Verify an already-**completed** implementation `result` behind the independent adversarial verifier,
+ * Verify an already-**completed** implementation `result` behind the independent falsification-style verifier,
  * looping fix→re-verify until PASS (or a round cap) — **without re-running the implementation**. This is the
  * L3 entry for the L2+L3 composition (design/54 §4): in a fan-out, a worker's module has already been
  * produced, so the orchestrator runs the mechanical L2 gate ({@link runExecGate}), computes the diff, then
@@ -219,7 +219,7 @@ export interface VerificationResult extends TaskResult {
  */
 export declare function verifyCompleted(runner: Runner, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig): Promise<VerificationResult>;
 /**
- * Run an implementation task, then gate it behind an independent adversarial verifier, looping
+ * Run an implementation task, then gate it behind an independent falsification-style verifier, looping
  * fix→re-verify until PASS (or a round cap). Returns the implementation result plus the
  * {@link VerificationOutcome}. The caller decides WHEN to use this (explicit opt-in) — it always
  * verifies once invoked. If the impl **suspends on a durable HITL gate**, it is surfaced as
@@ -232,7 +232,7 @@ export declare function runWithVerification(runner: Runner, implSpec: TaskSpec,
  * durable + HITL + verify integration (design/51 P1-b). The mirror of {@link runWithVerification} for the
  * resume path: `runWithVerification` surfaces a HITL suspend as failed-with-token; once the human
  * adjudicates, the caller calls this with the `token` + `outcome`, and it resumes the implementation and —
- * **if it COMPLETES** — runs the identical adversarial verifier + fix loop. If the resumed run suspends
+ * **if it COMPLETES** — runs the identical falsification-style verifier + fix loop. If the resumed run suspends
  * AGAIN (a later durable gate), it is surfaced as failed-with-token (`unverified`) for the caller to resume
  * once more. `objective` is the ORIGINAL task objective (the resume carries none of its own) — the verifier
  * needs it as context; pass the same objective the original `runWithVerification` ran with.

package/dist/bench/metrics.d.ts

@@ -458,7 +458,7 @@ export interface PairedBinaryComparison {
 /**
  * codex B2 — compare two arms' delivered truly-correct as PAIRED binary. Pairs runs by the COMPOSITE
  * `(taskId, seed)` key (codex MAJOR-A: a bare `seed` collides across tasks — the same repeat index
- * recurs per task — so cross-task input would overwrite pairs and poison the McNemar sample);
+ * recurs per task — so cross-task input would overwrite pairs and contaminate the McNemar sample);
  * only rows where BOTH arms delivered (not withheld, both scored) form a pair — a
  * withheld run has no delivered binary to pair (it is scored in the withhold/avoided-loss axis, not
  * here). `mde` is the pre-registered minimum detectable effect (default 0.20 absolute = a 20pp swing).

package/dist/brain/retry.d.ts

@@ -13,7 +13,7 @@
  * - `Retry-After` (delta-seconds or HTTP-date), on any retryable response.
  * - `anthropic-ratelimit-unified-reset` (an absolute epoch-seconds stamp of when the rate-limit window
  *   reopens), read only off a 429 — it is a rate-limit signal.
- * When both are present the larger wins. Both are clamped so a hostile/buggy value
+ * When both are present the larger wins. Both are clamped so a untrusted/buggy value
  * (`Retry-After: 2147483647`, a reset stamp years out) cannot pin the caller for hours.
  */
 /** Parse a `Retry-After` header (delta-seconds or HTTP-date) to ms; undefined if absent/unparseable. */

package/dist/core/arg-summary.d.ts

@@ -52,7 +52,7 @@ export interface SummarizableFinding {
 export declare function summarizeRedactions(findings: readonly SummarizableFinding[]): string;
 /** The optional collector every redaction entry point accepts. `preexistingMarkers` (ANG-11) counts
  *  marker-shaped literals ALREADY present in the input before any pass ran — a nonzero value means the
- *  text arrived pre-redacted or carries forged markers, either way "marker present" is not proof this
+ *  text arrived pre-redacted or carries caller-declared markers, either way "marker present" is not proof this
  *  pipeline ran. Caller-owned: pass `{ findings: [] }` and read it back after the call. */
 export interface RedactionReport {
     findings: RedactionFinding[];

package/dist/core/ask-class.d.ts

@@ -8,7 +8,7 @@
  * self-reported "this ask is sandbox-local" field would be the same trust hole as the
  * `decisionReason:"safety"` self-declaration this codebase already refuses. Instead, BUILT-IN policy
  * factories register their instances here (private WeakMap brand — nothing a deployment policy can
- * forge by shaping its return value), and everything unregistered reads as `unknown`.
+ * self-declare by shaping its return value), and everything unregistered reads as `unknown`.
  *
  * Classes and their dominance (STRICT — merge keeps the strongest; only an all-`sandbox_local` set
  * may auto-admit):
@@ -27,7 +27,7 @@ export type AskClass = "sandbox_local" | "external_authority" | "hook" | "mandat
 /**
  * Brand a built-in policy instance with its ask class (engine factories only — not exported from the
  * package). The `check` binding is LOCKED as a non-writable, non-configurable DATA property before the
- * policy is returned (codex adversarial round 4, HIGH): reading `policy.check` and INVOKING it must
+ * policy is returned (codex falsification-style round 4, HIGH): reading `policy.check` and INVOKING it must
  * name the same callable, atomically. A plain `===` re-read was TOCTOU-able by an accessor — a getter
  * could return the branded function to `policyAskClassOf` and a deployment ask to the gate's
  * invocation. Locking the property makes the callable un-swappable and un-redefinable, so the class

package/dist/core/ask-question.d.ts

@@ -234,7 +234,7 @@ export declare function askQuestionContinuationCard(questionId: string, continua
  * The ONE shape validator for a question batch, shared by the tool body and by the engine's routing lane
  * (which validates BEFORE it puts anything in front of a person — a malformed batch must be refused to
  * the model, not rendered). Returns the model-facing error text, or `undefined` when the batch is well
- * formed. Total: it never throws on hostile field shapes.
+ * formed. Total: it never throws on untrusted field shapes.
  */
 export declare function validateAskQuestions(questions: unknown): string | undefined;
 /** design/173 件3 — engine-side options for the mounted tool (prepare wires them; a deployment

package/dist/core/ask-question.js

@@ -184,7 +184,20 @@ export function createAskUserQuestionTool(onQuestion, source, opts) {
             "Usage notes:\n" +
             '- Users will always be able to select "Other" to provide custom text input\n' +
             "- Use multiSelect: true to allow multiple answers to be selected for a question\n" +
-            '- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label',
+            '- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label' +
+            "\n" +
+            "\n" +
+            "Preview feature:\n" +
+            "Use the optional `preview` field on options when presenting concrete artifacts that users need to visually compare:\n" +
+            "- ASCII mockups of UI layouts or components\n" +
+            "- Code snippets showing different implementations\n" +
+            "- Diagram variations\n" +
+            "- Configuration examples\n" +
+            "\n" +
+            "Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. " +
+            "When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on " +
+            "the left and preview on the right. Do not use previews for simple preference questions where labels and " +
+            "descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).",
         parameters: Type.Object({
             questions: Type.Array(Type.Object({
                 question: Type.String({

package/dist/core/background-shell.d.ts

@@ -6,16 +6,16 @@
  * 这是一个 **env 上的可选能力**(非一种独立 env 类型),所以不 `extends ExecutionEnv` —— 用交叉类型挂到具体实现上,并经
  * {@link hasBackgroundShell} 运行时检测(对齐 remote-env.ts 的 `hasDestroy`/`isRemoteExecutionEnv` 模式,零 vendor 接口改动)。
  *
- * 设计裁定(经 codex + workflow 5-lens 双轨对抗复审收敛,design/103 v2):
+ * 设计裁定(经 codex + workflow 5-lens 双轨证伪式复审收敛,design/103 v2):
  * - **不跨 durable suspend**:后台进程在每条退出路径被 dispose;Runner 必须在 suspendVM **之前** 调
  *   {@link BackgroundShellCapability.disposeBackgroundShells}(detached job 不在 suspendVM 的 in-flight 契约射程内)。
- * - **越权隔离**:`pollBackground`/`killBackground` 的 shellId MUST 被校验为本 env 自己 spawn 过的;非本 env 走 `not_found`。
+ * - **越界隔离**:`pollBackground`/`killBackground` 的 shellId MUST 被校验为本 env 自己 spawn 过的;非本 env 走 `not_found`。
  * - **按-id-可重读**:实现 MUST 保证按 shellId 跨多次独立调用可重复读取累积/增量输出(execStream 的 consume-once 不满足)。
  */
 import type { ExecutionEnv, ExecutionEnvExecOptions, Result } from "../internal/harness-types.js";
 /**
  * 一个 long-running / detached 进程的句柄。**env-local、非 durable、对调用方不透明** —— adapter 内部把它映射到真实进程/
- * provider job,**绝不**把可猜的 raw provider job id 暴露成 shellId(否则跨租户可枚举,design/103 §3.8 越权红线)。
+ * provider job,**绝不**把可猜的 raw provider job id 暴露成 shellId(否则跨租户可枚举,design/103 §3.8 越界红线)。
  */
 export type BackgroundShellId = string & {
     readonly __brand: "BackgroundShellId";
@@ -105,11 +105,11 @@ export interface BackgroundShellCapability {
     /**
      * 读一个后台进程**自上次 poll 以来的新增**输出 + 当前状态(cursor 语义)。退出后仍可读残余 + exitCode,直到被 dispose/reap。
      *
-     * 🔴 越权契约:`shellId` MUST 被校验为**本 env 自己 spawnBackground 返回过**的;非本 env 一律 `not_found`,绝不解析外部 job id。
+     * 🔴 越界契约:`shellId` MUST 被校验为**本 env 自己 spawnBackground 返回过**的;非本 env 一律 `not_found`,绝不解析外部 job id。
      * 🔴 重读契约:实现 MUST 保证「按 shellId 跨多次独立调用可重复读取累积/增量」(remote 的 execStream consume-once 不满足 —— 见 design/103 §5.2 两条路径)。
      */
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
-    /** 杀一个后台进程(幂等:杀已死的是 no-op,返回 ok)。`shellId` 同 {@link pollBackground} 的越权校验。 */
+    /** 杀一个后台进程(幂等:杀已死的是 no-op,返回 ok)。`shellId` 同 {@link pollBackground} 的越界校验。 */
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
     /**
      * 杀掉并清理**本 env 的所有**后台进程。Runner 在每条退出路径调:finish/abort/throw 在 run-loop tail finally,**suspend/

package/dist/core/checkpoint-store.d.ts

@@ -784,7 +784,7 @@ export interface CheckpointState {
         /** THIS task's OWN admitted org verdict at suspend (adversarial-review adoption, 2026-08-05):
          *  distinct from {@link admittedOrgScopes} (the incoming PARENT constraint). The resume leg
          *  applies it as the SESSION freeze on the final admitted projection — regardless of origin
-         *  (deployment-origin scopes bypass the chain freeze, never the session freeze) — so a session's
+         *  (deployment-origin scopes circumvent the chain freeze, never the session freeze) — so a session's
          *  verdict can only NARROW across suspend/resume: re-adjudication still runs every leg (a
          *  revoked grant refuses the resume), but a policy widened mid-session cannot widen THIS
          *  session's mount or the chain its children inherit. Present (possibly EMPTY — an adjudicated
@@ -797,7 +797,7 @@ export interface CheckpointState {
          *  suspend leg did not hold); a scope string = the explicit grant. Present iff
          *  {@link ownAdmittedOrgScopes} is (same adjudication record). */
         ownAdmittedOrgWriteScope?: string | null;
-        /** The MONOTONIC org-governance provenance bit (adversarial round 5): `true` when any leg of
+        /** The MONOTONIC org-governance provenance bit (falsification-style round 5): `true` when any leg of
          *  the suspended tree ran with an org-admission surface (or inherited the bit). A resume worker
          *  missing the surface still treats the leg as governed — org-shaped scopes respelled outside
          *  the v2 contract are refused, even when every admitted set en route was EMPTY. Absent on
@@ -901,7 +901,7 @@ export declare const RESOURCE_CHECKPOINT_VERSION = 2;
  * `boundInputHash`) whose enforcement lives ENTIRELY in the resuming worker's resume path. A pre-D-1 worker
  * (released 1.100.0: `MAX_SUPPORTED`=2, and its resume code has ZERO binding logic) would otherwise resume a
  * D-1-minted v1 checkpoint and execute the pending tool with NO decision-action verification — the exact
- * "approve vendor-A $5 → execute vendor-B $5000" bypass the binding exists to prevent (council BLOCKER #1).
+ * "approve vendor-A $5 → execute vendor-B $5000" circumvent the binding exists to prevent (council BLOCKER #1).
  * Stamping these at **v3 (> the old worker's MAX of 2)** forces a pre-D-1 worker to reject them PRE-CAS
  * (`unsupported_version`, stays `pending`, retried on a binding-enforcing worker) instead of silently voiding
  * the binding. A resource_limit suspend keeps stamping v2; a pre-binding (legacy 1.100.0) checkpoint is v1.
@@ -923,7 +923,7 @@ export declare const BINDING_CHECKPOINT_VERSION = 3;
  */
 export declare const TOKEN_CHECKPOINT_VERSION = 5;
 /**
- * Org-memory admission state (adversarial round 2, 2026-08-05 — the BINDING_CHECKPOINT_VERSION
+ * Org-memory admission state (falsification-style round 2, 2026-08-05 — the BINDING_CHECKPOINT_VERSION
  * precedent replayed a fourth time): the schema version a suspend stamps when its state carries
  * org-admission freeze fields (`inheritedGate.admittedOrgScopes` / `ownAdmittedOrgScopes` /
  * `ownAdmittedOrgWriteScope` — the adjudicated-empty record included). The enforcement — the
@@ -937,7 +937,7 @@ export declare const TOKEN_CHECKPOINT_VERSION = 5;
 export declare const ORG_ADMISSION_CHECKPOINT_VERSION = 6;
 /**
  * F-012 (2026-08-09 — the ORG_ADMISSION_CHECKPOINT_VERSION precedent replayed a fifth time, codex
- * adversarial finding): the schema version a suspend stamps when its state carries the F-012 durable
+ * falsification-style finding): the schema version a suspend stamps when its state carries the F-012 durable
  * enforcement fields — `inheritedGate.constraintChain`/`constraintDigest` (the frozen ancestor
  * projection chain the resume-edit re-adjudication executes) or `delegationProvenance` (the monotonic
  * provenance aggregate a resume re-seeds). Both enforcements live ENTIRELY in the resuming worker: a
@@ -1022,7 +1022,7 @@ export declare function debitLedger(prior: ResourceLedger | undefined, slice: {
  *  per-slice window / walltime). A resumed slice's effective `maxCostUsd` is `min(window, this)`. NB: `0` is a
  *  VALID, exhausted ceiling — NOT "unlimited" (only `undefined` is unlimited). Any spend then immediately trips
  *  `overBudget`, and the run loop fails an exhausted resume fast (runtask). Never falsy-test this value (a
- *  `if (remaining)` would skip a legitimate 0 ceiling and silently bypass the budget). */
+ *  `if (remaining)` would skip a legitimate 0 ceiling and silently circumvent the budget). */
 export declare function remainingBudgetMicroUsd(ledger: ResourceLedger | undefined): number | undefined;
 /** design/164 (the TOKEN sibling of {@link remainingBudgetMicroUsd}): tokens the NEXT slice may still
  *  spend = `totalTokens − spentTokens`, never negative. `undefined` when no token total is set (the run is
@@ -1270,7 +1270,7 @@ export interface Checkpoint {
      * `durableApproval` (an unattended safety suspend, a non-ask gate, or a legacy pre-1.389 checkpoint — the
      * consumer then falls back to the human-kind scope-only inference for legacy rows and injects NOTHING for
      * unattended parks, so a spawn that never opted in can never gain the opt-in through a resume). Engine-
-     * minted from the task's own spec — a worker/tool cannot forge it (`durableApproval` never rides tool args).
+     * minted from the task's own spec — a worker/tool cannot self-declare it (`durableApproval` never rides tool args).
      */
     durableApproval?: {
         scope: string;
@@ -1442,7 +1442,7 @@ export declare class CheckpointError extends Error {
      *  rather than evicting: an already-accepted operator instruction is never dropped to make room —
      *  the caller delivers or removes a parked steer first. Nothing is written on this path. */
      | "steering.queue_full"
-    /** design/171 §6.3 (adversarial review adoption): the append reused an `inputId` already parked on
+    /** design/171 §6.3 (falsification review adoption): the append reused an `inputId` already parked on
      *  this checkpoint, but with DIFFERENT content. Re-appending an IDENTICAL payload stays the
      *  idempotent no-op a retry needs; a differing one is refused, because swallowing it would lose the
      *  second operator's instruction — the exact silent loss the queue replaced. Retry with a fresh id.
@@ -1450,7 +1450,7 @@ export declare class CheckpointError extends Error {
      | "steering.duplicate_input_id"
     /** design/144 §3 (governance-gate purity, fail-closed pre-CAS): a `wake` outcome was supplied for a
      *  checkpoint that awaits a PENDING GATE DECISION (tool approval / dry-run review / plan review /
-     *  resource-limit continue). Wake is a pure un-park verb and must never bypass an approval — resume
+     *  resource-limit continue). Wake is a pure un-park verb and must never circumvent an approval — resume
      *  the checkpoint through its own decide entry instead (the error message names it). */
      | "wake.gate_pending"
     /** design/144 §3 (anti spin-wake): a `wake` outcome carried no `message` and the checkpoint has no
@@ -1498,7 +1498,7 @@ export declare class CheckpointError extends Error {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
         /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
          *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
-         *  damaged/forged and no worker ever will" — blanket-retriable and gate-shape heuristics were
+         *  damaged/caller-declared and no worker ever will" — blanket-retriable and gate-shape heuristics were
          *  both refuted downstream, so the throw site carries the fact it always knew). Closed set;
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
@@ -1563,7 +1563,7 @@ export declare class CheckpointError extends Error {
      *  rather than evicting: an already-accepted operator instruction is never dropped to make room —
      *  the caller delivers or removes a parked steer first. Nothing is written on this path. */
      | "steering.queue_full"
-    /** design/171 §6.3 (adversarial review adoption): the append reused an `inputId` already parked on
+    /** design/171 §6.3 (falsification review adoption): the append reused an `inputId` already parked on
      *  this checkpoint, but with DIFFERENT content. Re-appending an IDENTICAL payload stays the
      *  idempotent no-op a retry needs; a differing one is refused, because swallowing it would lose the
      *  second operator's instruction — the exact silent loss the queue replaced. Retry with a fresh id.
@@ -1571,7 +1571,7 @@ export declare class CheckpointError extends Error {
      | "steering.duplicate_input_id"
     /** design/144 §3 (governance-gate purity, fail-closed pre-CAS): a `wake` outcome was supplied for a
      *  checkpoint that awaits a PENDING GATE DECISION (tool approval / dry-run review / plan review /
-     *  resource-limit continue). Wake is a pure un-park verb and must never bypass an approval — resume
+     *  resource-limit continue). Wake is a pure un-park verb and must never circumvent an approval — resume
      *  the checkpoint through its own decide entry instead (the error message names it). */
      | "wake.gate_pending"
     /** design/144 §3 (anti spin-wake): a `wake` outcome carried no `message` and the checkpoint has no
@@ -1619,7 +1619,7 @@ export declare class CheckpointError extends Error {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
         /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
          *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
-         *  damaged/forged and no worker ever will" — blanket-retriable and gate-shape heuristics were
+         *  damaged/caller-declared and no worker ever will" — blanket-retriable and gate-shape heuristics were
          *  both refuted downstream, so the throw site carries the fact it always knew). Closed set;
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
@@ -1880,7 +1880,7 @@ export interface CheckpointStore {
      * REJECTED with a typed {@link CheckpointError} `steering.invalid_content` (mirroring runtask.ts's trusted-
      * steer reject) — a dirty steer NEVER enters {@link CheckpointState}, so the persisted state stays clean
      * regardless of `trusted`. (The untrusted RESUME-injection path ALSO sanitizes the text as untrusted data;
-     * this persist-time reject is the belt that keeps a forged close tag out of the durable record on BOTH
+     * this persist-time reject is the belt that keeps a caller-declared close tag out of the durable record on BOTH
      * paths.) Text over {@link MAX_PENDING_STEER_CHARS} is rejected with the same code (HRD-APV-4 — the
      * steer is re-delivered into the model context on every resume, so it is capped like every other
      * persisted model-facing field on this row; rejected rather than truncated because cutting an

package/dist/core/file-snapshot-store.d.ts

@@ -72,7 +72,7 @@ export interface FileSnapshotStore {
     /**
      * 2c session-sync ([277]): STORE a single content-addressed blob — the symmetric WRITE side of {@link getBlob},
      * for a two-phase PUSH (upload blobs, THEN import the manifest that references them). VERIFIES content-address
-     * integrity (`sha256(bytes) === hash`) so a corrupt/mismatched upload can never poison the store (a later
+     * integrity (`sha256(bytes) === hash`) so a corrupt/mismatched upload can never contaminate the store (a later
      * getBlob/restore would otherwise return wrong content); a mismatch → `read_failed`, nothing stored. IMMUTABLE +
      * content-addressed: a repeat putBlob for the same hash is a no-op (the bytes are identical by definition).
      * Returns a {@link FileSnapshotResult} (NOT void) so the integrity failure is encodable under the never-throw

package/dist/core/hooks.d.ts

@@ -8,7 +8,7 @@ import { type AskClass } from "./ask-class.js";
  *
  *  - {@link Hooks.preToolUse} runs before a tool executes. It may **rewrite** the args (an `allow` with
  *    `updatedInput`), **restrict** the call (`deny`/`ask`), and/or inject `additionalContext`. It is a
- *    pre-filter only: a hook's `allow` does NOT bypass the tool-policy gate — the policy still runs on
+ *    pre-filter only: a hook's `allow` does NOT circumvent the tool-policy gate — the policy still runs on
  *    the (possibly rewritten) args and has the final say (load-bearing invariant; see {@link runToolGate}).
  *  - {@link Hooks.postToolUse} runs after a tool executes. It may replace the result content
  *    (`updatedOutput`) and/or append `additionalContext`.
@@ -55,7 +55,7 @@ export interface Hooks {
      * JSON on the ordinary path, which clones whole; the residual is reachable only through values a
      * DEPLOYMENT put there (its own rewrite, or driving `runToolGate` directly), and the face and the
      * deployment are one trust principal — this seam helps a deployment keep its own declaration, it is not
-     * a boundary against an adversary.
+     * a boundary against an untrusted party.
      *
      * If a declared-observational face RETURNS SOMETHING ANYWAY, the return is REFUSED, not obeyed: the
      * call proceeds as if the hook had no opinion (`undefined`), and the deployment's `onError` face is
@@ -142,7 +142,7 @@ export interface Hooks {
      * plan-mode write-deny. Closes the observation blind spot where a blocked call fires NEITHER postToolUse
      * NOR postToolUseFailure (R3 scoping). Does NOT fire for:
      *  - a **durable suspend** (the ask path — CC surfaces that via a `can_use_tool` control_request);
-     *  - a **PreToolUse hook deny** (CC-exact: "PreToolUse hook denies bypass canUseTool and are not
+     *  - a **PreToolUse hook deny** (CC-exact: "PreToolUse hook denies circumvention canUseTool and are not
      *    covered here").
      * DOES fire for a **PreToolUse hook CRASH** (RB-442, `source:"hook"`): a throwing hook is intercepted by
      * the ENGINE, which then makes its OWN fail-closed deny decision. The R5 exclusion above covers the
@@ -417,6 +417,28 @@ export interface HookToolOutput {
 /**
  * A PreToolUse hook result: a {@link PermissionResult} (so a hook can `deny`/`ask`, or `allow` with an
  * `updatedInput` rewrite) plus optional `additionalContext` injected into the eventual tool result.
+ *
+ * **The provenance members are not hook-settable inputs** (#174). `decisionReason` is the ENGINE's account
+ * of which layer produced a verdict, and `persistedRuleShadowed` is the gate's own #144 disclosure that a
+ * stored rule matched without clearing the ask. The gate stamps both itself — a `decisionReason` on a hook
+ * result is DISCARDED (a hook ask always reads `"hook"` downstream), and a `persistedRuleShadowed` is
+ * dropped rather than rendered on an approval card as a rule no lane matched.
+ *
+ * Which of a hook's OTHER members reach the surviving decision depends on which fold arm ran, so read
+ * the arm, not a single list: an ask promoted from a policy `allow` is rebuilt from the hook's `message`,
+ * `requiresRealApproval` and `updatedInput`, while a hook ask folded BESIDE a policy ask contributes its
+ * message and its mandate to the policy's decision and leaves the policy's own rewrite in place (the
+ * hook's rewrite still reaches execution — through the gate's captured rewrite, not through the decision
+ * object). Both arms are at the `hookAsk` fold in {@link runToolGate}.
+ *
+ * `additionalContext` is on neither list and never was consumed as a decision member: it rides its own
+ * channel — collected into the gate's `preToolContext` as soon as the hook answers, whichever verdict it
+ * returned, and drained onto the tool result by the runner. DELIVERY is narrower than collection: the
+ * runner stashes the context only for a call that will EXECUTE, because a blocked or suspended call never
+ * reaches the result step that drains it and carries its own model-facing reason instead. The context
+ * formerly APPEARED on the promoted ask object as an undeclared property, because that fold spread the
+ * whole hook result; the concurrent arm never carried it, so the two arms disagreed on a member neither
+ * of them reads. Nothing in the engine reads it off a decision.
  */
 export type PreToolUseResult = PermissionResult & {
     additionalContext?: string;

package/dist/core/hooks.js

@@ -98,7 +98,7 @@ function preToolUseCrashReason(subject, err) {
 function screenPreToolUseResult(r) {
     if (r === undefined)
         return undefined;
-    return refuseOutOfContractDecision(r);
+    return refuseOutOfContractDecision(r, { reasonIsNonInput: true });
 }
 export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
     return brandPolicyAskClass({
@@ -125,6 +125,7 @@ export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
                     action: "ask",
                     message: decisionText(r) ?? `approval required for "${req.toolName}" (inherited PreToolUse hook)`,
                     decisionReason: "hook",
+                    ...(r.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                     ...(r.updatedInput !== undefined ? { updatedInput: r.updatedInput } : {}),
                 };
             }
@@ -220,13 +221,31 @@ export async function runToolGate(input) {
     if ((decision.action === "allow" || decision.action === "ask") && decision.updatedInput !== undefined) {
         policyRewrite = decision.updatedInput;
     }
-    else if (hookAsk?.action === "ask" && hookAsk.updatedInput !== undefined) {
+    else if (hookAsk?.updatedInput !== undefined) {
         policyRewrite = hookAsk.updatedInput;
     }
     if (decision.action === "allow" && hookAsk) {
-        decision = { ...hookAsk, decisionReason: hookAsk.decisionReason ?? "hook" };
+        decision = {
+            action: "ask",
+            ...(hookAsk.message !== undefined ? { message: hookAsk.message } : {}),
+            decisionReason: "hook",
+            ...(hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(hookAsk.updatedInput !== undefined ? { updatedInput: hookAsk.updatedInput } : {}),
+        };
         denySource = "hook";
     }
+    else if (decision.action === "ask" && hookAsk) {
+        const hookMessage = hookAsk.message;
+        const foldedMessage = hookMessage !== undefined && hookMessage !== decision.message
+            ? `${decision.message !== undefined ? `${decision.message} ` : ""}(a PreToolUse hook also asks: ${hookMessage})`
+            : decision.message;
+        decision = {
+            ...decision,
+            decisionReason: "hook",
+            ...(foldedMessage !== undefined ? { message: foldedMessage } : {}),
+            ...(hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+        };
+    }
     if (input.egress && decision.action === "allow") {
         decision = {
             action: "ask",

package/dist/core/human-input-projection.d.ts

@@ -18,8 +18,8 @@
  *
  * The label goes through the same two neutralizers as the external notification's `from="…"` header
  * (`inlineUntrusted` + `attrEscape` — one-line, capped, break-out-defused, quote-escaped), so a
- * hostile id can never close the `[from "…"]` frame, escape an enclosing `<system-reminder>`, or
- * smuggle a fake `(unverified)`-free identity. The projection runs BEFORE trust framing at every
+ * untrusted id can never close the `[from "…"]` frame, escape an enclosing `<system-reminder>`, or
+ * carry across a fake `(unverified)`-free identity. The projection runs BEFORE trust framing at every
  * call site, so the annotation always sits INSIDE the frame it attributes (a trusted frame's
  * reminder wrapper, an untrusted frame's fence) and can never be separated from its text.
  */

package/dist/core/memory-admission.d.ts

@@ -50,7 +50,7 @@ export interface MemoryAdmissionInput {
      *  request-origin scope outside it refuses the prepare; a deployment-origin scope outside it is
      *  dropped and disclosed; a write grant absent from it collapses to read-only. */
     priorOwnVerdict: OwnOrgAdmissionVerdict | undefined;
-    /** The monotonic governance-provenance bit (adversarial round 5): true when this leg's TREE is
+    /** The monotonic governance-provenance bit (falsification-style round 5): true when this leg's TREE is
      *  org-governed — the deployment surface is configured here, or ANY ancestor/prior leg recorded
      *  the bit (`InheritedGate.orgAdmissionGoverned`, persisted on checkpoints). Counts as governance
      *  evidence even when every admitted set en route is EMPTY: a governed parent's org-less child,
@@ -82,7 +82,7 @@ export interface MemoryAdmissionOutcome {
  * (an older-shape chain must never read as "unconstrained"); a top-level leg simply has no chain
  * constraint. The SESSION freeze (the leg's own suspend-time verdict) is a separate input to
  * {@link admitMemoryScopes} (`priorOwnVerdict`) — it must constrain the FINAL admitted projection
- * regardless of origin (deployment-origin scopes bypass the chain freeze, not the session freeze),
+ * regardless of origin (deployment-origin scopes circumvent the chain freeze, not the session freeze),
  * so it cannot ride this chain-side fold.
  */
 export declare function foldAdmissionFreeze(input: {