@sema-agent/client-core 0.8.0 → 0.9.0

package/dist/hitl/hitlBridge.d.ts

@@ -0,0 +1,245 @@
+/**
+ * ⇄ B7 批搬迁(2026-07-27,设计稿 §3 B7):cli `src/seam/adapter/upstream/hitlBridge.ts`(491 行)
+ *    **整条进包**。这是 HITL 的心脏 —— suspended ↔ canUseTool 的编组层。
+ *
+ * 🔴 **D-1 两元组是安全不变量,原样搬,一个字节不改**(设计稿 §3 B7 原文):
+ *    `bindingOf()`(下方 §1 末)把人**看见的那一行** `PendingCheckpoint` 上的
+ *    `boundCallId` + `boundInputHash` **逐字回显**进 `approvals.decide(...)` —— 绝不本地重算
+ *    (重算出来的假不匹配会 fail-close 掉一个合法审批);409 `approval_binding_mismatch`
+ *    是**安全信号**,抛 `HitlSafetyError('binding_mismatch')`,**绝不自动重试**。
+ *    这两段代码在 `scripts/run-client-core-pure-test.mjs` 的 B7 段有**字节级**断言
+ *    (常量字面量比对 + 壳树在场时的双向比对),改一个字符就红。
+ *
+ * ── 搬迁差分(只有三处,全在类型/依赖面,零运行时语义变化)────────────────────────────────
+ *  1. `eventSeq` 从 `../types.js` → `../adapter/types.js`(B3 已搬入本包,同一份实现)。
+ *  2. CC 的 `PermissionDecision` / `PermissionDenyDecision` / `CanUseToolFn` 三个类型住在壳的
+ *     `src/types/permissions.ts` + `src/hooks/useCanUseTool.tsx`(它们拖 `ToolType` /
+ *     `ToolUseContext` / `AssistantMessage` 整张 CC 内部类型图,不属于 wire 词汇表)。
+ *     本包改用**结构切片 + 泛型**:`HitlPermissionDecisionLike`(本桥真正读的三个键)与
+ *     `HitlCanUseToolFn<D>`(CC 回调的形状,tool/context/message 三个位对本桥是不透明的)。
+ *     壳侧 shim 用自己的 `PermissionDecision` 实例化泛型 ⇒ 壳侧调用点类型一字节不变。
+ *     🔴 这是**类型面**的收窄,不是行为面:运行时只读 `.behavior` / `.message` / `.updatedInput`
+ *        三个键(原文就只读这三个)。
+ *  3. `backendDeny` 的返回形状(`decisionReason:{type:'asyncAgent',reason}`)是 CC 的
+ *     `PermissionDenyDecision` 逐字形,本包按字面量声明(壳侧 shim 断言可赋值)。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * src/seam/adapter/upstream/hitlBridge.ts — the UPSTREAM control bridge (tasks.json T23; NEW file, no CC-logic edit).
+ *
+ * This is the human-in-the-loop (HITL) heart of the seam: the place where CC's synchronous `canUseTool`
+ * callback (useCanUseTool.tsx:27 — the spine the contract must reproduce) meets the `@sema-ai/sdk`
+ * suspended → decide → resume loop (contract/04 §2/§4/§6, contract/08 IH-4/IH-5/IH-10). CC's loop calls
+ * `canUseTool(tool, input, …)` before any guarded tool runs and BLOCKS on the returned `PermissionDecision`;
+ * the contract turns that blocking callback into a DURABLE pause (a `suspended` event carrying a
+ * `CheckpointGate`) plus a `decide` verb. This module is the marshalling layer between the two worlds.
+ *
+ * What it does (the three contract laws this file pins):
+ *
+ *  1. **suspended ↔ canUseTool with the D-1 TOCTOU guard** (contract/04 §2.2, §D-1; 08 IH-4).
+ *     When CC asks "may I run THIS tool?", the bridge finds the matching `PendingCheckpoint` the human SAW
+ *     (joined by `toolCallId` → `boundCallId`), reads its `boundCallId` + `boundInputHash` two-tuple, and
+ *     echoes them back into `approvals.decide(...)` VERBATIM. The hash is a server-minted opaque sha256 over
+ *     the pending args at mint time — the bridge NEVER recomputes it (a false mismatch would fail-close a
+ *     legitimate approval, approvals.ts:33). `updatedInput` (approve-with-edit, design/37 last-wins) is
+ *     applied AFTER the binding check and does NOT change the binding — the hash still binds the ORIGINAL
+ *     input the human reviewed. A 409 `approval_binding_mismatch` is a SAFETY signal: re-present to the
+ *     human, NEVER auto-retry (contract/04 §9.1 fail-closed law).
+ *
+ *  2. **AskUserQuestion answer marshalling** (contract/04 §4.1; 08 CS-16/IH-4). The same suspended → decide
+ *     loop, but the gate's `toolName` is `"AskUserQuestion"` and the answer rides `ApprovalDecision.answer`
+ *     as the worker-validated wire shape `{ answers: [{ header, selected, note? }] }` — `header` MATCHES the
+ *     question's header, `selected` is an ARRAY (multi-select → multiple entries), `note` is optional free
+ *     text. The SDK types `answer` as `unknown`, so this is hand-marshalled (catalog mock-fill); the
+ *     transport is sdk-covered. The D-1 binding still binds (AskUserQuestion is still a checkpoint).
+ *
+ *  3. **plan_review** (contract/04 §3; 08 CS-17/IH-6). CC's plan mode ends a planning turn with a markdown
+ *     plan; the human approves/edits/rejects the PLAN itself (no bound tool action). This resolves on a
+ *     DISTINCT wire — `assistant.planReview(taskId, { decision, editedPlan?, reason? })` — NOT `decide` and
+ *     NOT `resume`. `editedPlan` is REQUIRED iff `decision === "edit"` and FORBIDDEN otherwise (→ 400). A
+ *     non-`plan_review` gate routed here would 409 `gate_not_plan_review`; the bridge guards the gate kind
+ *     before it calls.
+ *
+ * Provider- and presentation-agnostic (contract/04 laws 2-3; 08 invariants): every verb stays at
+ * `ApprovalDecision` / `PlanReviewRequest` / `CheckpointGate` altitude. No Anthropic `effort`/`fast_mode`
+ * vocabulary, no claude.ai permission-rule destinations, no widget/glyph/keybinding crosses this seam. The
+ * backend supplies the SIGNAL; the shell owns the chrome.
+ */
+import type { AgentEvent, ApprovalDecision, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
+/** CC `PermissionDecision` 的结构切片 —— 本桥运行时真正读的三个键。 */
+export interface HitlPermissionDecisionLike {
+    behavior: 'allow' | 'ask' | 'deny';
+    /** deny 臂的人话理由(CC `PermissionDenyDecision.message`),approve 臂缺席。 */
+    message?: string;
+    /** approve-with-edit(design/37 last-wins);在**绑定校验之后**生效,绑定仍绑原始 input。 */
+    updatedInput?: unknown;
+}
+/**
+ * CC `CanUseToolFn` 的结构形(`useCanUseTool.tsx:28`)。tool / toolUseContext / assistantMessage
+ * 三个位对本桥是**不透明**的(只读 `tool.name`),所以按最小形声明 —— 壳侧那个更窄的真类型
+ * 可赋值到这里(函数参数双变),`makeHitlCanUseTool` 的返回值也就能直接当 `CanUseToolFn` 用。
+ */
+export type HitlCanUseToolFn<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike> = (tool: {
+    name: string;
+}, input: Record<string, unknown>, toolUseContext: never, assistantMessage: never, toolUseID: string, forceDecision?: D) => Promise<D>;
+export interface ApprovalsResourceLike {
+    /** GET /v1/approvals — the rich decide-ready queue (approvals.ts:45). NEVER carries a capability token. */
+    list(opts?: {
+        signal?: AbortSignal;
+    }): Promise<PendingCheckpoint[]>;
+    /** POST /v1/approvals/:sessionId/decide — resolve THAT checkpoint; the resumed run continues its stream
+     *  (approvals.ts:52). NOT a submit → no retry (a decide must never double-act). */
+    decide(sessionId: string, decision: ApprovalDecision, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface AssistantResourceLike {
+    /** POST /v1/assistant/tasks/:id/plan_review — the 3-state plan gate (assistant.ts:87). */
+    planReview(taskId: string, req: PlanReviewRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AssistantTaskStatus>;
+    /** POST /v1/assistant/tasks/:id/resume — continue a resource_limit slice, NO body (assistant.ts:75). */
+    resume(taskId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AssistantTaskStatus>;
+}
+export interface HitlClientLike {
+    approvals: ApprovalsResourceLike;
+    assistant: AssistantResourceLike;
+}
+/** The marshalled AskUserQuestion answer body — the worker-validated wire shape (contract/04 §4.1). */
+export interface AskAnswer {
+    /** MATCHES the question's `header`. */
+    header: string;
+    /** ARRAY — multi-select yields multiple entries; single-select is a one-element array. */
+    selected: string[];
+    /** Optional operator free-text note. */
+    note?: string;
+}
+/** A plan-review outcome the shell collected (contract/04 §3.1). `editedPlan` REQUIRED iff decision==="edit". */
+export interface PlanReviewOutcome {
+    decision: 'approve' | 'edit' | 'reject';
+    editedPlan?: string;
+    reason?: string;
+}
+/** A safety stop: a contract law was about to be violated (e.g. a binding mismatch, a wrong-gate route).
+ *  The caller MUST re-present to the human or surface the error — NEVER silently retry or auto-decide
+ *  (contract/04 §9.1 fail-closed law). */
+export declare class HitlSafetyError extends Error {
+    /** A stable code the shell can branch on (`binding_mismatch` | `no_pending` | `wrong_gate` | `bad_plan_edit`). */
+    readonly code: string;
+    constructor(message: string, 
+    /** A stable code the shell can branch on (`binding_mismatch` | `no_pending` | `wrong_gate` | `bad_plan_edit`). */
+    code: string);
+}
+/** The active gate the downstream stream most recently suspended on (null when running). */
+export interface ActiveGate {
+    gate: CheckpointGate;
+    /** The durable seq of the `suspended` event, for rewind/dedup correlation (types.ts:48 eventSeq). */
+    seq?: string;
+}
+/**
+ * The bridge state. One per run/session. The shell feeds it `suspended` events (observe) and the human's
+ * outcome (decide / answer / planReview); it owns the `approvals.list()` join + the verbatim binding echo.
+ */
+export declare class HitlBridge {
+    private readonly client;
+    /** The suspended run's taskId — the handle plan_review/resume address (RunReceipt.taskId). */
+    private readonly taskId;
+    private active;
+    constructor(client: HitlClientLike, 
+    /** The suspended run's taskId — the handle plan_review/resume address (RunReceipt.taskId). */
+    taskId: string);
+    /** Observe a downstream event; latch the gate on `suspended`, clear it on a resuming/terminal arm. */
+    observe(ev: AgentEvent): void;
+    /** The gate currently awaiting a human, if any. The shell branches on `gate.kind` to pick the chrome. */
+    currentGate(): CheckpointGate | null;
+    /**
+     * Find the `PendingCheckpoint` the human is about to decide on. Joins by `toolCallId` when CC hands a
+     * `toolUseID`; otherwise falls back to the single pending row for this run's `taskId`. Returns null when
+     * the queue is empty (e.g. resolved/expired under the human → the caller must refetch + re-present).
+     */
+    private findPending;
+    /**
+     * Build the D-1 binding off the pending row the human SAW. Echo VERBATIM — NEVER recompute the hash
+     * (contract/04 §2.2). Returns `{}` against a pre-D-1 worker (no binding fields) so the server can fall
+     * back to resolve-by-sessionId. `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
+     * compliant clients send ONLY the two-tuple, approvals.ts:23-27).
+     */
+    private bindingOf;
+    /**
+     * Resolve a `human` / `irreversible_ask` permission gate (contract/04 §2, §6.2; 08 IH-4/IH-10).
+     *
+     *  - `approve` → `{decision:"approve", boundCallId, boundInputHash}`; `updatedInput` rides along for
+     *    approve-with-edit (applied AFTER the binding check — the hash still binds the ORIGINAL input).
+     *  - `deny`    → `{decision:"deny", reason}`. CANCEL a suspended run by DENYING, never by `runs.cancel`
+     *    (which 409s on a suspended run — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is
+     *    "the run ends after the deny", carried by the backend, not a wire flag.
+     *
+     * The resumed run continues its SAME durable stream. A binding mismatch (409) is re-raised as a
+     * `HitlSafetyError('binding_mismatch')` — the caller re-presents, NEVER auto-retries.
+     */
+    decideTool(outcome: {
+        decision: 'approve';
+        updatedInput?: unknown;
+        remember?: 'session';
+    } | {
+        decision: 'deny';
+        reason?: string;
+    }, toolUseID?: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /**
+     * Answer an `AskUserQuestion` gate (contract/04 §4; 08 CS-16). Same suspended → decide loop as a
+     * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
+     * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
+     * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
+     */
+    answerQuestion(answers: AskAnswer[], toolUseID?: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /**
+     * Resolve a plan-mode gate (contract/04 §3; 08 IH-6). Routed to `assistant.planReview`, NOT `decide`/
+     * `resume`. Guards the gate kind locally (a non-`plan_review` gate routed here would 409
+     * `gate_not_plan_review`) and the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
+     * otherwise → 400) so the bad call never leaves the shell.
+     */
+    reviewPlan(outcome: PlanReviewOutcome, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AssistantTaskStatus>;
+    /**
+     * Continue a `resource_limit` slice pause (contract/04 §6.1; 08 IH-9). Bodyless `assistant.resume` — NOT
+     * `decide`. A `human`/`irreversible_ask` gate routed here would 409 `gate_not_resumable` (a "continue"
+     * must NEVER bypass a human approval); the bridge guards locally first.
+     */
+    resumeResourceLimit(opts?: {
+        signal?: AbortSignal;
+    }): Promise<AssistantTaskStatus>;
+    private decideRaw;
+}
+/** The shell's presentation hook: surface a gate, resolve to a CC `PermissionDecision`. */
+export type GatePrompt<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike> = (ctx: {
+    toolName: string;
+    input: Record<string, unknown>;
+    toolUseID: string;
+    gate: CheckpointGate | null;
+}) => Promise<D>;
+/**
+ * Build a `CanUseToolFn` backed by the bridge. CC's loop calls it before any guarded tool; it surfaces the
+ * gate via `prompt`, routes the human's decision to `approvals.decide` (binding echoed verbatim), and
+ * returns the same `PermissionDecision` to unblock the loop. A `forceDecision` (CC's pre-resolved path)
+ * short-circuits the prompt but STILL drives the decide verb so the backend resolves the checkpoint.
+ */
+export declare function makeHitlCanUseTool<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike>(bridge: HitlBridge, prompt: GatePrompt<D>): HitlCanUseToolFn<D>;
+/** CC `PermissionDenyDecision` 的逐字形(`decisionReason` 的 `asyncAgent` 臂)。 */
+export interface HitlBackendDenyDecision {
+    behavior: 'deny';
+    message: string;
+    decisionReason: {
+        type: 'asyncAgent';
+        reason: string;
+    };
+}
+/** Build a CC deny `PermissionDecision` from a backend-driven denial (e.g. an SLA / policy auto-deny).
+ *  The decisionReason is `asyncAgent` — the denial originated upstream, not from a local rule/mode. */
+export declare function backendDeny(reason: string): HitlBackendDenyDecision;

package/dist/hitl/hitlBridge.js

@@ -0,0 +1,267 @@
+import { eventSeq } from '../adapter/types.js';
+// ── Errors the bridge surfaces (fail-closed; never auto-retried) ───────────────
+/** A safety stop: a contract law was about to be violated (e.g. a binding mismatch, a wrong-gate route).
+ *  The caller MUST re-present to the human or surface the error — NEVER silently retry or auto-decide
+ *  (contract/04 §9.1 fail-closed law). */
+export class HitlSafetyError extends Error {
+    code;
+    constructor(message, 
+    /** A stable code the shell can branch on (`binding_mismatch` | `no_pending` | `wrong_gate` | `bad_plan_edit`). */
+    code) {
+        super(message);
+        this.code = code;
+        this.name = 'HitlSafetyError';
+    }
+}
+/**
+ * The bridge state. One per run/session. The shell feeds it `suspended` events (observe) and the human's
+ * outcome (decide / answer / planReview); it owns the `approvals.list()` join + the verbatim binding echo.
+ */
+export class HitlBridge {
+    client;
+    taskId;
+    active = null;
+    constructor(client, 
+    /** The suspended run's taskId — the handle plan_review/resume address (RunReceipt.taskId). */
+    taskId) {
+        this.client = client;
+        this.taskId = taskId;
+    }
+    /** Observe a downstream event; latch the gate on `suspended`, clear it on a resuming/terminal arm. */
+    observe(ev) {
+        switch (ev.type) {
+            case 'suspended':
+                // gate may be null (Event_suspended 'null' arm) → a generic "needs you" pause (contract/08 CS-9).
+                if (ev.gate) {
+                    this.active = { gate: ev.gate, seq: eventSeq(ev) };
+                }
+                else {
+                    this.active = { gate: { kind: 'human' }, seq: eventSeq(ev) };
+                }
+                break;
+            case 'done':
+            case 'failed':
+                this.active = null;
+                break;
+            default:
+                // running again (text / tool_start / turn_end / …) → the gate cleared when decide resumed the stream.
+                if (this.active && (ev.type === 'text' || ev.type === 'tool_start' || ev.type === 'turn_end')) {
+                    this.active = null;
+                }
+                break;
+        }
+    }
+    /** The gate currently awaiting a human, if any. The shell branches on `gate.kind` to pick the chrome. */
+    currentGate() {
+        return this.active?.gate ?? null;
+    }
+    /**
+     * Find the `PendingCheckpoint` the human is about to decide on. Joins by `toolCallId` when CC hands a
+     * `toolUseID`; otherwise falls back to the single pending row for this run's `taskId`. Returns null when
+     * the queue is empty (e.g. resolved/expired under the human → the caller must refetch + re-present).
+     */
+    async findPending(toolUseID, opts) {
+        const pending = await this.client.approvals.list(opts);
+        if (pending.length === 0)
+            return null;
+        if (toolUseID) {
+            const byCall = pending.find((p) => p.boundCallId === toolUseID || p.toolCallId === toolUseID);
+            if (byCall)
+                return byCall;
+        }
+        // Fall back to this run's pending row (the suspended run holding the session claim).
+        const byTask = pending.find((p) => p.taskId === this.taskId);
+        return byTask ?? pending[0] ?? null;
+    }
+    /**
+     * Build the D-1 binding off the pending row the human SAW. Echo VERBATIM — NEVER recompute the hash
+     * (contract/04 §2.2). Returns `{}` against a pre-D-1 worker (no binding fields) so the server can fall
+     * back to resolve-by-sessionId. `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
+     * compliant clients send ONLY the two-tuple, approvals.ts:23-27).
+     */
+    bindingOf(p) {
+        const binding = {};
+        if (p.boundCallId !== undefined)
+            binding.boundCallId = p.boundCallId;
+        if (p.boundInputHash !== undefined)
+            binding.boundInputHash = p.boundInputHash;
+        return binding;
+    }
+    // ── §2. Permission gate: approve / deny a tool ──────────────────────────────
+    /**
+     * Resolve a `human` / `irreversible_ask` permission gate (contract/04 §2, §6.2; 08 IH-4/IH-10).
+     *
+     *  - `approve` → `{decision:"approve", boundCallId, boundInputHash}`; `updatedInput` rides along for
+     *    approve-with-edit (applied AFTER the binding check — the hash still binds the ORIGINAL input).
+     *  - `deny`    → `{decision:"deny", reason}`. CANCEL a suspended run by DENYING, never by `runs.cancel`
+     *    (which 409s on a suspended run — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is
+     *    "the run ends after the deny", carried by the backend, not a wire flag.
+     *
+     * The resumed run continues its SAME durable stream. A binding mismatch (409) is re-raised as a
+     * `HitlSafetyError('binding_mismatch')` — the caller re-presents, NEVER auto-retries.
+     */
+    async decideTool(outcome, toolUseID, opts) {
+        const pending = await this.findPending(toolUseID, opts);
+        if (!pending) {
+            throw new HitlSafetyError('no pending checkpoint to decide (resolved/expired under the human) — refetch + re-present', 'no_pending');
+        }
+        const decision = outcome.decision === 'approve'
+            ? {
+                decision: 'approve',
+                ...this.bindingOf(pending),
+                // updatedInput is applied AFTER the binding check; binding still binds the ORIGINAL input.
+                ...(outcome.updatedInput !== undefined ? { updatedInput: outcome.updatedInput } : {}),
+                // accept-session 的 durable-park 半场(server 1.191 decide 契约 `remember:"session"` →
+                // approvalExemptionStore.grant(sessionId, toolName)= 同 session 该工具后续 ask 免 park。
+                // 需要 binding(上面已 echo)。调用方只在三选第 2 项才带;老 server 收到未知键按契约 400,
+                // 故带 remember 的 decide 失败时调用方要能回退纯 approve(见 liveToolApprovalWire)。
+                ...(outcome.remember !== undefined ? { remember: outcome.remember } : {}),
+            }
+            : {
+                decision: 'deny',
+                ...this.bindingOf(pending),
+                ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
+            };
+        return this.decideRaw(pending.sessionId, decision, opts);
+    }
+    // ── §3. AskUserQuestion: answer through the same gate ───────────────────────
+    /**
+     * Answer an `AskUserQuestion` gate (contract/04 §4; 08 CS-16). Same suspended → decide loop as a
+     * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
+     * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
+     * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
+     */
+    async answerQuestion(answers, toolUseID, opts) {
+        const pending = await this.findPending(toolUseID, opts);
+        if (!pending) {
+            throw new HitlSafetyError('no pending AskUserQuestion checkpoint to answer — refetch + re-present', 'no_pending');
+        }
+        const decision = {
+            decision: 'approve',
+            answer: { answers: answers.map((a) => marshalAnswer(a)) },
+            ...this.bindingOf(pending),
+        };
+        return this.decideRaw(pending.sessionId, decision, opts);
+    }
+    // ── §4. plan_review: the distinct wire ──────────────────────────────────────
+    /**
+     * Resolve a plan-mode gate (contract/04 §3; 08 IH-6). Routed to `assistant.planReview`, NOT `decide`/
+     * `resume`. Guards the gate kind locally (a non-`plan_review` gate routed here would 409
+     * `gate_not_plan_review`) and the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
+     * otherwise → 400) so the bad call never leaves the shell.
+     */
+    async reviewPlan(outcome, opts) {
+        // Gate-kind guard (contract/04 §3.1): plan_review parks as needs_review / plan_review, distinct from the
+        // approval family. If the active gate is a tool/resource gate, refuse locally rather than 409 the server.
+        const kind = this.active?.gate.kind;
+        if (kind && kind !== 'plan_review' && kind !== 'needs_review') {
+            throw new HitlSafetyError(`cannot plan-review a "${kind}" gate — a plan decision must never resolve a tool approval`, 'wrong_gate');
+        }
+        // editedPlan invariant (contract/04 §3.1): REQUIRED iff edit, FORBIDDEN otherwise.
+        if (outcome.decision === 'edit') {
+            if (!outcome.editedPlan || outcome.editedPlan.length === 0) {
+                throw new HitlSafetyError('plan-review "edit" requires a non-empty editedPlan', 'bad_plan_edit');
+            }
+        }
+        else if (outcome.editedPlan !== undefined) {
+            throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry editedPlan`, 'bad_plan_edit');
+        }
+        const req = { decision: outcome.decision };
+        if (outcome.decision === 'edit')
+            req.editedPlan = outcome.editedPlan;
+        if (outcome.reason !== undefined)
+            req.reason = outcome.reason;
+        return this.client.assistant.planReview(this.taskId, req, opts);
+    }
+    // ── §5. resource_limit: continue ────────────────────────────────────────────
+    /**
+     * Continue a `resource_limit` slice pause (contract/04 §6.1; 08 IH-9). Bodyless `assistant.resume` — NOT
+     * `decide`. A `human`/`irreversible_ask` gate routed here would 409 `gate_not_resumable` (a "continue"
+     * must NEVER bypass a human approval); the bridge guards locally first.
+     */
+    async resumeResourceLimit(opts) {
+        const kind = this.active?.gate.kind;
+        if (kind && kind !== 'resource_limit') {
+            throw new HitlSafetyError(`cannot resume a "${kind}" gate — "continue" must never bypass a human approval; use decide`, 'wrong_gate');
+        }
+        return this.client.assistant.resume(this.taskId, opts);
+    }
+    // ── decide transport (the single choke point; maps 409 binding mismatch → safety stop) ──
+    async decideRaw(sessionId, decision, opts) {
+        try {
+            const r = await this.client.approvals.decide(sessionId, decision, opts);
+            // A successful decide resumes the SAME durable stream; the gate clears on the next running arm.
+            this.active = null;
+            return r;
+        }
+        catch (e) {
+            if (isBindingMismatch(e)) {
+                // contract/04 §2.2 / §9.1: a binding mismatch means the pending action changed under the human.
+                // SAFETY signal — re-present to the human, NEVER auto-retry / auto-re-decide.
+                throw new HitlSafetyError('approval_binding_mismatch — the pending action changed under the human; refetch + re-present', 'binding_mismatch');
+            }
+            throw e;
+        }
+    }
+}
+/**
+ * Build a `CanUseToolFn` backed by the bridge. CC's loop calls it before any guarded tool; it surfaces the
+ * gate via `prompt`, routes the human's decision to `approvals.decide` (binding echoed verbatim), and
+ * returns the same `PermissionDecision` to unblock the loop. A `forceDecision` (CC's pre-resolved path)
+ * short-circuits the prompt but STILL drives the decide verb so the backend resolves the checkpoint.
+ */
+export function makeHitlCanUseTool(bridge, prompt) {
+    return async (tool, input, _toolUseContext, _assistantMessage, toolUseID, forceDecision) => {
+        const gate = bridge.currentGate();
+        const decision = forceDecision ??
+            (await prompt({ toolName: tool.name, input, toolUseID, gate }));
+        if (decision.behavior === 'deny') {
+            // Deny → cancel-by-deny (contract/04 §2.4). The deny message rides `reason`.
+            await bridge.decideTool({ decision: 'deny', reason: decision.message }, toolUseID);
+            return decision;
+        }
+        if (decision.behavior === 'allow') {
+            // Approve (+ approve-with-edit via updatedInput, applied after the binding check).
+            await bridge.decideTool(decision.updatedInput !== undefined
+                ? { decision: 'approve', updatedInput: decision.updatedInput }
+                : { decision: 'approve' }, toolUseID);
+            return decision;
+        }
+        // behavior === 'ask': not a wire decision — re-surface (the shell loops the prompt). Returned as-is so
+        // CC's loop re-asks; the bridge does NOT decide on an `ask`.
+        return decision;
+    };
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+/** Marshal one answer into the worker-validated wire entry (contract/04 §4.1). Drops undefined `note`. */
+function marshalAnswer(a) {
+    const entry = {
+        header: a.header,
+        selected: a.selected,
+    };
+    if (a.note !== undefined)
+        entry.note = a.note;
+    return entry;
+}
+/** Detect a 409 `approval_binding_mismatch` across the SDK error shape variants (errorCode / code / status). */
+function isBindingMismatch(e) {
+    if (!e || typeof e !== 'object')
+        return false;
+    const o = e;
+    const code = o.errorCode ?? o.code;
+    if (code === 'approval_binding_mismatch')
+        return true;
+    // SDK throws a named ApprovalBindingMismatchError (index.ts:19).
+    if (typeof o.name === 'string' && o.name === 'ApprovalBindingMismatchError')
+        return true;
+    return false;
+}
+/** Build a CC deny `PermissionDecision` from a backend-driven denial (e.g. an SLA / policy auto-deny).
+ *  The decisionReason is `asyncAgent` — the denial originated upstream, not from a local rule/mode. */
+export function backendDeny(reason) {
+    return {
+        behavior: 'deny',
+        message: reason,
+        decisionReason: { type: 'asyncAgent', reason },
+    };
+}

package/dist/hitl/planReviewWire.d.ts

@@ -0,0 +1,17 @@
+/** done 帧的 plan_review park 形状(结构性读,别的终态一律 false)。 */
+export declare function isPlanReviewPark(result: unknown): result is {
+    taskId: string;
+    sessionId?: string;
+};
+/**
+ * Arm the approval card for a parked plan_review (call with the RAW done.result). Returns true when
+ * armed (live path + shape matched); false = caller renders the terminal as usual. Fail-soft: any
+ * error inside must never break the stream drain.
+ */
+export declare function armPlanReviewApproval(result: unknown): boolean;
+/** POST the decision; on settle enqueue an isMeta turn so the model reports the resume outcome.
+ *  SDK 宪法迁移批:SDK 0.0.52 assistant.planReview verb(同 wire `POST /v1/assistant/tasks/:id/
+ *  plan_review` 同 body {decision})——raw fetch 退役。错误模型:非 2xx 抛 APIError(message =
+ *  server body.error 原文)→ 同款「HTTP <status> <error>」outcome 文案;网络失败走原「could not
+ *  reach the engine」臂。 */
+export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject'): Promise<void>;