@sema-agent/core 7.5.2 → 7.6.1

package/dist/agents/suspend-guard.d.ts

@@ -1,13 +1,13 @@
-import type { TaskResult } from "../core/types.js";
+import type { PausedCause, TaskResult, TerminalCause } from "../core/types.js";
 /**
- * design/45 §11 Q6 — the **durable-suspend hard boundary** (v1). A `status:"suspended"` result is only
- * safe to handle at the **top-level `runTask`** boundary: the orchestrators (cascade / verify / teacher /
- * team) run their work as *nested* `runTask`s, and none of them can drive a resume from the inside. If a
- * nested task suspends on a durable approval gate, the orchestrator must **fail fast** — not silently
- * treat it as an ordinary failure (which would escalate/re-run side effects) and not release its pinned
- * session (which would orphan the checkpoint). It maps `suspended → failed` + `errorCode:
- * "unexpected.suspended"` and **passes the `checkpointToken`/`checkpointGate` straight through** (via the
- * spread) so the top-level caller can still resume.
+ * design/45 §11 Q6 — the **durable-suspend hard boundary** (v1). A `paused` terminal is only safe to
+ * handle at the **top-level `runTask`** boundary: the orchestrators (cascade / verify / teacher / team)
+ * run their work as *nested* `runTask`s, and none of them can drive a resume from the inside. If a nested
+ * task pauses on a durable gate, the orchestrator must **fail fast** — not silently treat it as an
+ * ordinary failure (which would escalate/re-run side effects) and not release its pinned session (which
+ * would orphan the checkpoint). It maps `paused → failed` with the code `"unexpected.suspended"` (an
+ * approval / resource pause) or `"unexpected.needs_review"` (a review pause) and **carries the pause's own
+ * cause on the failed terminal's `nestedPause` seat** so the top-level caller can still resume.
  *
  * The structural prevention is upstream — an orchestrator should run nested tasks under a **non-durable**
  * approval policy (e.g. the verifier already forces `handsReadOnly` + headless auto-deny, DESIGN#5) so a
@@ -15,20 +15,32 @@ import type { TaskResult } from "../core/types.js";
  * a hard boundary, or a deployment wires durable-suspend into verify and produces silent errors."
  */
 export declare const UNEXPECTED_SUSPENDED = "unexpected.suspended";
-/** design/80 D-B: the `needs_review` durable-pause family (dry-run `needs_review` AND `plan_review`) hits the
- *  SAME nested hard boundary as `suspended` — a distinct code so a caller can tell a review pause from an approval. */
+/** design/80 D-B: the review durable-pause family (dry-run `needs_review` AND `plan_review`) hits the SAME
+ *  nested hard boundary as an approval pause — a distinct code so a caller can tell a review pause from an
+ *  approval. */
 export declare const UNEXPECTED_NEEDS_REVIEW = "unexpected.needs_review";
 /**
- * design/80 D-B: the durable-pause hard boundary covers BOTH `suspended` (an approval gate) AND `needs_review`
- * (a dry-run review OR a `plan_review` plan-gate). Both persist a checkpoint + PIN their session
- * (prepare-task.ts), and a nested orchestrator can't drive their resume — so it must surface the
- * `checkpointToken` and NOT release the pinned session (releasing it orphans the checkpoint). The `types.ts`
- * TaskStatus doc mandates orchestrators map an unexpected `needs_review` the same hard-boundary way as `suspended`.
+ * design/80 D-B: the durable-pause hard boundary covers EVERY `paused` cause — an approval gate, a resource
+ * slice, a dry-run review, a `plan_review` plan-gate. All of them persist a checkpoint + PIN their session,
+ * and a nested orchestrator can't drive their resume — so it must surface the pause and NOT release the
+ * pinned session (releasing it orphans the checkpoint). A type guard, so the caller reads the token/gate
+ * off the narrowed cause.
  */
-export declare function isDurablePause(status: TaskResult["status"]): boolean;
+export declare function isDurablePause(terminal: TerminalCause): terminal is PausedCause;
+/** A result whose terminal is known to be a pause — what {@link isDurablePause} narrows a result's
+ *  `terminal` to, spelled as a type so an orchestrator can HOLD a paused result without re-checking. */
+export type PausedResult = TaskResult & {
+    terminal: PausedCause;
+};
 /**
- * If `result` durably paused (suspended OR needs_review), return it mapped to a `failed` result carrying the
- * checkpoint token; otherwise return it unchanged. The orchestrator should also **stop** (not escalate/re-run)
+ * Which family a pause belongs to — its gate kind's registry row: `"suspended"` (an approval gate, a
+ * resource slice, a platform park) or `"needs_review"` (a dry-run or plan review). The same row the
+ * status word is projected from; read here by the orchestrators that name the family in their own faces.
+ */
+export declare function pauseFamily(t: PausedCause): "suspended" | "needs_review";
+/**
+ * If `result` durably paused, return it mapped to a `failed` result whose terminal carries the pause on
+ * `nestedPause`; otherwise return it unchanged. The orchestrator should also **stop** (not escalate/re-run)
  * and **not release** the session when this maps a pause — the checkpoint still references that session.
  */
 export declare function mapNestedSuspend(result: TaskResult): TaskResult;

package/dist/agents/suspend-guard.js

@@ -1,18 +1,24 @@
+import { PAUSE_REGISTRY } from "../core/pause-registry.js";
 export const UNEXPECTED_SUSPENDED = "unexpected.suspended";
 export const UNEXPECTED_NEEDS_REVIEW = "unexpected.needs_review";
-export function isDurablePause(status) {
-    return status === "suspended" || status === "needs_review";
+export function isDurablePause(terminal) {
+    return terminal.kind === "paused";
+}
+export function pauseFamily(t) {
+    return PAUSE_REGISTRY[t.gate.kind].taskStatus;
 }
 export function mapNestedSuspend(result) {
-    if (!isDurablePause(result.status)) {
+    const t = result.terminal;
+    if (!isDurablePause(t)) {
         return result;
     }
+    const word = pauseFamily(t);
+    const code = word === "needs_review" ? UNEXPECTED_NEEDS_REVIEW : UNEXPECTED_SUSPENDED;
+    const message = `a nested task durably paused ("${word}") on a HITL gate; durable suspend/resume and plan/` +
+        "dry-run review are only supported at the top-level runTask (design/45 v1 / design/80). Resume it via " +
+        "the pause's token, or run the orchestrated task under a non-durable policy so it auto-adjudicates instead of pausing.";
     return {
         ...result,
-        status: "failed",
-        errorCode: result.status === "needs_review" ? UNEXPECTED_NEEDS_REVIEW : UNEXPECTED_SUSPENDED,
-        errorMessage: `a nested task durably paused ("${result.status}") on a HITL gate; durable suspend/resume and plan/` +
-            "dry-run review are only supported at the top-level runTask (design/45 v1 / design/80). Resume it via " +
-            "checkpointToken, or run the orchestrated task under a non-durable policy so it auto-adjudicates instead of pausing.",
+        terminal: { kind: "failed", code, message, nestedPause: t },
     };
 }

package/dist/agents/teacher.d.ts

@@ -1,4 +1,4 @@
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import { type StrategyOrigin, type StrategyStore, type StrategyStoreIncident } from "../core/strategy-store.js";
 import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
 /**
@@ -156,4 +156,4 @@ export declare function parseTeacherAdvice(text: string): TeacherAdvice;
  * completed output (catches "passes but semantically wrong"). Correction-then-takeover, with hard
  * cost guards (escalation cap, teacher-spend ratio, bounded teacher turns).
  */
-export declare function runWithTeacher(runner: Runner, studentSpec: TaskSpec, teacher?: TeacherConfig): Promise<TeacherRunResult>;
+export declare function runWithTeacher(runner: RunnerSelfSeat, studentSpec: TaskSpec, teacher?: TeacherConfig): Promise<TeacherRunResult>;

package/dist/agents/teacher.js

@@ -119,7 +119,7 @@ export async function runWithTeacher(runner, studentSpec, teacher = {}) {
         }
     }
     const result = await runTeacherCore(runner, spec, teacher);
-    if (store && scope && result.status === "completed" && result.escalations.length > 0) {
+    if (store && scope && result.terminal.kind === "completed" && result.escalations.length > 0) {
         const advice = result.escalations[result.escalations.length - 1].teacher;
         if (advice.strategy && advice.confidence >= (teacher.minConfidenceToStore ?? 2)) {
             try {
@@ -271,7 +271,7 @@ async function runTeacherCore(runner, studentSpec, teacher) {
         ...(studentSpec.restoreGatedTools !== undefined
             ? { restoreGatedTools: Array.isArray(studentSpec.restoreGatedTools) ? [...studentSpec.restoreGatedTools] : studentSpec.restoreGatedTools }
             : {}),
-        ...(studentSpec.checkpointStore === null ? { checkpointStore: null } : {}),
+        ...(studentSpec.checkpointStore === "disabled" ? { checkpointStore: "disabled" } : {}),
     };
     const helperBase = () => teacher.helperModel
         ? { ...inheritedDeploymentConfig, model: teacher.helperModel }
@@ -407,9 +407,8 @@ async function runTeacherCore(runner, studentSpec, teacher) {
     const syntheticAborted = (sid) => ({
         taskId: sid ?? "aborted",
         sessionId: sid ?? "aborted",
-        status: "failed",
+        terminal: { kind: "failed", message: "student run did not settle promptly after stuck-abort" },
         result: "",
-        errorMessage: "student run did not settle promptly after stuck-abort",
         stats: { turns: 0, tokens: 0 },
     });
     const abortFallback = (sid) => {
@@ -451,7 +450,7 @@ async function runTeacherCore(runner, studentSpec, teacher) {
         toolLog.length = 0;
         const { result, stuck, recent } = await runStudent();
         sessionId = result.sessionId;
-        if (isDurablePause(result.status)) {
+        if (isDurablePause(result.terminal)) {
             return finalize(mapNestedSuspend(result));
         }
         let trigger;
@@ -459,10 +458,10 @@ async function runTeacherCore(runner, studentSpec, teacher) {
         if (stuck) {
             trigger = "stuck";
         }
-        else if (result.status === "blocked") {
+        else if (result.terminal.kind === "blocked") {
             trigger = "blocked";
         }
-        else if (result.status === "failed") {
+        else if (result.terminal.kind === "failed") {
             trigger = "failed";
         }
         else if (!verifyOutput) {
@@ -482,7 +481,8 @@ async function runTeacherCore(runner, studentSpec, teacher) {
             return finalize(result);
         }
         if (trigger === "failed" &&
-            /truncat|max[ _-]?tokens?|maximum tokens?|token (limit|budget)|context (length|window)|no answer text|(consumed|exceeded).{0,12}budget/i.test(result.errorMessage ?? "")) {
+            result.terminal.kind === "failed" &&
+            /truncat|max[ _-]?tokens?|maximum tokens?|token (limit|budget)|context (length|window)|no answer text|(consumed|exceeded).{0,12}budget/i.test(result.terminal.message ?? "")) {
             return finalize(result);
         }
         if (escalations.length >= maxEscalations) {
@@ -528,7 +528,7 @@ async function runTeacherCore(runner, studentSpec, teacher) {
                 signal: extSignal,
             });
             addTeacher(r);
-            if (isDurablePause(r.status)) {
+            if (isDurablePause(r.terminal)) {
                 return finalize(mapNestedSuspend(r));
             }
             return finalize(r);

package/dist/agents/team.d.ts

@@ -1,5 +1,6 @@
-import type { Runner } from "../core/runner/runtask.js";
-import type { McpServerSpec, ModelRef, ModelRole, TaskResult, TaskSpec, ToolSpec } from "../core/types.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
+import type { McpServerSpec, ModelRef, ModelRole, TaskSpec, ToolSpec } from "../core/types.js";
+import type { CheckpointGate, CheckpointToken } from "../core/checkpoint-store.js";
 export interface TeamMember {
     /** The member's role / specialty, e.g. "安全评审" or "performance". */
     role: string;
@@ -58,7 +59,7 @@ export type TeamEvent = {
     type: "done";
 };
 export interface TeamDiscussionOptions {
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /** Default model for members / synthesizer without their own. If omitted, members resolve the
      *  `team` role and the synthesizer the `synthesize` role (both fall back to `default`). */
     model?: ModelRef;
@@ -206,8 +207,8 @@ export interface TeamResult {
      *  the discussion STOPS (no synthesis on a half-done team) and surfaces the resume capability so the caller
      *  can resume the paused member via the token, then re-run. `conclusionValid` is false in this case. */
     durablePause?: boolean;
-    checkpointToken?: TaskResult["checkpointToken"];
-    checkpointGate?: TaskResult["checkpointGate"];
+    checkpointToken?: CheckpointToken;
+    checkpointGate?: CheckpointGate;
 }
 /**
  * Run a multi-round discussion across several role-specialized agents, then synthesize a conclusion.

package/dist/agents/team.js

@@ -1,5 +1,6 @@
 import { resolveToolSubset } from "./tool-filter.js";
 import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
+import { terminalProjection } from "../core/runner/terminal-projection.js";
 import { sanitizeUntrustedText } from "../core/untrusted-text.js";
 const DISCUSSION_WRAPPER_TAGS = ["statement", "discussion", "discussion-final", "earlier-discussion-summary", "previous-summary", "topic"];
 const RETIRED_WRAPPER_TAGS = ["team-discussion", "team-discussion-final"];
@@ -87,7 +88,7 @@ export async function runTeamDiscussion(opts) {
         return {
             status: "failed",
             result: conclusion,
-            errorCode: p.errorCode,
+            errorCode: terminalProjection(mapNestedSuspend(p).terminal).errorCode,
             conclusion,
             conclusionValid: false,
             transcript,
@@ -96,8 +97,8 @@ export async function runTeamDiscussion(opts) {
             failures,
             transcriptCompactions,
             durablePause: true,
-            checkpointToken: p.checkpointToken,
-            checkpointGate: p.checkpointGate,
+            checkpointToken: p.terminal.token,
+            checkpointGate: p.terminal.gate,
         };
     };
     const runTurn = async (objective, systemPrompt, modelRef, role, tools, mcp) => {
@@ -122,16 +123,17 @@ export async function runTeamDiscussion(opts) {
             tokens += res.stats.tokens + (res.stats.nested?.tokens ?? 0);
             turns += res.stats.turns + (res.stats.nested?.turns ?? 0);
             costMicroUsd += (res.stats.costMicroUsd ?? 0) + (res.stats.nested?.costMicroUsd ?? 0);
-            if (isDurablePause(res.status)) {
-                const m = mapNestedSuspend(res);
-                pendingPause = m;
+            if (isDurablePause(res.terminal)) {
+                pendingPause = { ...res, terminal: res.terminal };
+                const m = terminalProjection(mapNestedSuspend(res).terminal);
                 return { text: `[unavailable: ${m.status}/${m.errorCode}]`, ok: false };
             }
             await opts.runner.sessions.release(res.sessionId).catch(() => undefined);
-            if (res.status === "completed" && res.result.trim()) {
+            if (res.terminal.kind === "completed" && res.result.trim()) {
                 return { text: res.result, ok: true };
             }
-            last = `[unavailable: ${res.status}${res.errorCode ? `/${res.errorCode}` : ""}${res.errorMessage ? ` — ${res.errorMessage}` : ""}]`;
+            const face = terminalProjection(res.terminal);
+            last = `[unavailable: ${face.status}${face.errorCode ? `/${face.errorCode}` : ""}${face.errorMessage ? ` — ${face.errorMessage}` : ""}]`;
         }
         return { text: last || "[unavailable]", ok: false };
     };

package/dist/agents/verify.d.ts

@@ -1,8 +1,7 @@
 import { Type, type Static } from "typebox";
-import type { Runner, ResumeTaskConfig } from "../core/runner/runtask.js";
-import type { RunInternals } from "../core/runner/prepare-task.js";
+import type { ResumeTaskConfig, RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { CheckpointGate, CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
-import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js";
+import type { ModelRef, TaskResult, TaskSpec, TaskStatus, ToolSpec } from "../core/types.js";
 /**
  * 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
@@ -131,7 +130,7 @@ export interface VerifyConfig {
      */
     onVerifierPause?: (info: {
         round: number;
-        status: TaskResult["status"];
+        status: TaskStatus;
         sessionId: string;
         checkpointToken?: CheckpointToken;
         checkpointGate?: CheckpointGate;
@@ -200,7 +199,7 @@ export interface VerificationOutcome {
      */
     verifierPause?: {
         /** The verifier run's terminal pause status (`"suspended"` or `"needs_review"`). */
-        status: TaskResult["status"];
+        status: TaskStatus;
         /** The paused verifier's own session id (independent of the implementation's). */
         sessionId: string;
         /** The resume capability for the verifier's checkpoint. Undefined only if the pause carried none. */
@@ -242,7 +241,7 @@ export interface VerificationResult extends TaskResult {
  * override is given, the verifier uses {@link STATIC_VERIFICATION_PROMPT} (read the diff/results; don't try
  * to execute — that was L2's job), avoiding the "PARTIAL on everything" failure in a read-only sandbox.
  */
-export declare function verifyCompleted(runner: Runner, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig, 
+export declare function verifyCompleted(runner: RunnerSelfSeat, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig, 
 /**
  * The TRUSTED, run-scoped internals channel — the same object `Runner.runTask` takes as its second
  * argument — forwarded to EVERY leg this gate drives under the composition forward contract (identity,
@@ -303,7 +302,7 @@ internals?: RunInternals): Promise<VerificationResult>;
  * failed-with-token (verdict `unverified`); the caller approves and calls {@link resumeWithVerification}
  * to resume AND verify (design/51 P1-b: the durable + HITL + verify integration).
  */
-export declare function runWithVerification(runner: Runner, implSpec: TaskSpec, config?: VerifyConfig, 
+export declare function runWithVerification(runner: RunnerSelfSeat, implSpec: TaskSpec, config?: VerifyConfig, 
 /** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives —
  *  the implementation run, then (on completion) the verifier + fix legs of the gate. Full contract,
  *  including the attribution and forwarded-whole rules, on {@link verifyCompleted}. Absent ⇒ every
@@ -324,7 +323,7 @@ internals?: RunInternals): Promise<VerificationResult>;
  * after approval, so a pre-suspend diff would grade stale code. The verifier already verifies the current working
  * tree (verifierObjective), so dropping the stale diff closes the timing window.
  */
-export declare function resumeWithVerification(runner: Runner, token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, objective: string, config?: VerifyConfig, 
+export declare function resumeWithVerification(runner: RunnerSelfSeat, token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, objective: string, config?: VerifyConfig, 
 /** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives —
  *  `Runner.resume`'s own internals argument for the RESUMED implementation leg, then (on completion)
  *  the verifier + fix legs of the gate. Note that this seat carries the resume-path duty of the same
@@ -344,7 +343,7 @@ export interface DeveloperTaskConfig extends VerifyConfig {
  * Pair with a role map that gives a strong implementation model and cheaper helper/verifier models for
  * "auto model selection" (design/28 §3.2): `roles: { default: strong, subagent: cheap, verifier: strong }`.
  */
-export declare function runDeveloperTask(runner: Runner, spec: TaskSpec, config?: DeveloperTaskConfig, 
+export declare function runDeveloperTask(runner: RunnerSelfSeat, spec: TaskSpec, config?: DeveloperTaskConfig, 
 /** The trusted run-scoped internals channel, forwarded UNCHANGED to every leg this entry drives — in
  *  BOTH arms: the lone implementation run when `verify: false`, and the whole gate otherwise. The two
  *  arms differ in ONE respect: the gate's door refusal of `isolation` (see {@link verifyCompleted})

package/dist/agents/verify.js

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { CODE_AGENT_PROMPT } from "../prompts/default.js";
 import { releaseSession } from "./session-util.js";
-import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
+import { mapNestedSuspend, isDurablePause, pauseFamily } from "./suspend-guard.js";
 import { delimitUntrusted, sanitizeUntrustedText } from "../core/untrusted-text.js";
 import { createSafeNotifier } from "../core/safe-notify.js";
 import { createCumulativeStatsTracker } from "./cumulative-stats.js";
@@ -102,7 +102,7 @@ function verifierObjective(originalObjective, impl, evidence) {
 }
 export async function verifyCompleted(runner, result, specBase, objective, config, internals) {
     refuseUnhonorableInternals(internals, "door");
-    if (result.status !== "completed") {
+    if (result.terminal.kind !== "completed") {
         return { ...result, verification: { verdict: "unverified", unverifiedReason: "impl_incomplete", rounds: 0, findings: [] } };
     }
     const maxRounds = Number.isFinite(config.maxRounds) ? Math.max(1, Math.floor(config.maxRounds)) : 2;
@@ -168,10 +168,10 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
         }, legInternals());
         try {
             const cost = (v.stats.costMicroUsd ?? 0) + (v.stats.nested?.costMicroUsd ?? 0);
-            return { verdict: v.structuredOutput, cost, ...(isDurablePause(v.status) ? { paused: v } : {}) };
+            return { verdict: v.structuredOutput, cost, ...(isDurablePause(v.terminal) ? { paused: { ...v, terminal: v.terminal } } : {}) };
         }
         finally {
-            if (!isDurablePause(v.status))
+            if (!isDurablePause(v.terminal))
                 await releaseSession(runner, v.sessionId);
         }
     };
@@ -202,18 +202,18 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
                 findings: [],
                 verifierCost: verifierSpend,
                 verifierPause: {
-                    status: v.paused.status,
-                    sessionId: v.paused.sessionId,
-                    ...(v.paused.checkpointToken ? { checkpointToken: v.paused.checkpointToken } : {}),
-                    ...(v.paused.checkpointGate ? { checkpointGate: v.paused.checkpointGate } : {}),
+                    status: pauseFamily(paused.terminal),
+                    sessionId: paused.sessionId,
+                    checkpointToken: paused.terminal.token,
+                    checkpointGate: paused.terminal.gate,
                 },
             };
             notifier.notify(() => config.onVerifierPause?.({
                 round,
-                status: paused.status,
+                status: pauseFamily(paused.terminal),
                 sessionId: paused.sessionId,
-                ...(paused.checkpointToken ? { checkpointToken: paused.checkpointToken } : {}),
-                ...(paused.checkpointGate ? { checkpointGate: paused.checkpointGate } : {}),
+                checkpointToken: paused.terminal.token,
+                checkpointGate: paused.terminal.gate,
             }), VERIFY_ON_VERIFIER_PAUSE_SITE);
             notifier.notify(() => config.onRound?.({ round, verdict: outcome.verdict, findings: outcome.findings }), VERIFY_ON_ROUND_SITE);
             break;
@@ -248,10 +248,10 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
         }, legInternals());
         spend += (current.stats.costMicroUsd ?? 0) + (current.stats.nested?.costMicroUsd ?? 0);
         implAccount.add(current.stats);
-        if (isDurablePause(current.status)) {
+        if (isDurablePause(current.terminal)) {
             return { ...mapNestedSuspend(carryFrozenPosture(withImplAccount(current))), verification: outcome };
         }
-        if (current.status !== "completed")
+        if (current.terminal.kind !== "completed")
             break;
     }
     return { ...carryFrozenPosture(withImplAccount(current)), verification: outcome };
@@ -259,8 +259,8 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
 export async function runWithVerification(runner, implSpec, config = {}, internals) {
     refuseUnhonorableInternals(internals, "door");
     const result = await runner.runTask(implSpec, internals);
-    if (isDurablePause(result.status)) {
-        return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: result.status === "needs_review" ? "needs_review" : "suspended", rounds: 0, findings: [] } };
+    if (isDurablePause(result.terminal)) {
+        return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: pauseFamily(result.terminal), rounds: 0, findings: [] } };
     }
     refuseUnhonorableInternals(internals, "before_leg");
     return verifyCompleted(runner, result, implSpec, implSpec.objective, config, internals);
@@ -268,8 +268,8 @@ export async function runWithVerification(runner, implSpec, config = {}, interna
 export async function resumeWithVerification(runner, token, outcome, taskConfig, objective, config = {}, internals) {
     refuseUnhonorableInternals(internals, "door");
     const result = await runner.resume(token, outcome, taskConfig, internals);
-    if (isDurablePause(result.status)) {
-        return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: result.status === "needs_review" ? "needs_review" : "suspended", rounds: 0, findings: [] } };
+    if (isDurablePause(result.terminal)) {
+        return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: pauseFamily(result.terminal), rounds: 0, findings: [] } };
     }
     refuseUnhonorableInternals(internals, "before_leg");
     return verifyCompleted(runner, result, taskConfig, objective, config, internals);

package/dist/core/a2a.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { A2A_TASK_STATES } from "./a2a-task-state.js";
-import { describeHttpTransportFailure, resolveProtocolHttpHeaders } from "./mcp.js";
+import { resolveProtocolHttpHeaders } from "./mcp.js";
+import { describeHttpTransportFailure } from "./mcp-failure.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
 import { A2A_NAMESPACE } from "./protocol-table.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";

package/dist/core/agent-definition.d.ts

@@ -0,0 +1,172 @@
+/**
+ * A delegated AGENT's definition and the skills it may mount: `AgentDefinition` (the agent a subagent
+ * tool spawns), `SkillManifest` (a skill's on-disk front matter) and `SkillSpec` (the wired form the
+ * runner mounts). Layer 0 vocabulary; `types.ts` re-exports the three, so no consumer's import changes.
+ */
+import type { ThinkingLevel } from "../internal/harness.js";
+import type { ModelRef } from "./model-seat.js";
+import type { TaskSpec } from "./task-spec.js";
+/**
+ * A declarative, reusable named sub-agent (design/38 1B). Hand a set to {@link createSubagentTool} and the
+ * model picks one (by `whenToUse`) to delegate to; the chosen definition's config builds the child task.
+ *
+ * **Deployment-side config, NOT user input** — `systemPrompt`/`allowTools` shape what the sub-agent can do
+ * and see, so they must be set by the deployment, never taken from an end-user message.
+ */
+export interface AgentDefinition {
+    /** Stable identifier + the value the delegation tool's `agent` parameter selects. Must be unique. */
+    name: string;
+    /** Guidance shown to the model for WHEN to pick this agent (listed in the delegation tool's description). */
+    whenToUse?: string;
+    /**
+     * F4 (CC 2.1.198 parity, `whenToUseLean` — 锚 pretty.js:409174 `rbm` + selection `tIl` :453029
+     * `(lean && e.whenToUseLean) || e.whenToUse`): a SHORT variant of {@link whenToUse} preferred on
+     * lean-prompt surfaces. sema posture: the engine runs the CC lean-prompt arm wholesale (web.ts
+     * lean-card precedent), so roster listings/descriptions prefer this text whenever present;
+     * {@link whenToUse} remains the fallback. Optional — a single-text agent behaves exactly as before.
+     */
+    whenToUseLean?: string;
+    /** Tool allowlist over the delegation pool (`["*"]` = all). Replaces (does not merge with) the tool's
+     *  own `allowTools`/`denyTools` when this agent is selected. F1 (CC parity): unlike the TOOL-level
+     *  allow/deny (which never filters the nested delegation tool — that stays `maxDepth`-governed), a
+     *  PER-AGENT allow/deny ALSO governs the nested delegation tool: an agent whose allow/deny excludes
+     *  the delegation tool's name cannot re-delegate (CC Explore/Plan `disallowedTools` include Agent,
+     *  pretty.js:409189/486948). */
+    allowTools?: string[];
+    /** Tool denylist (a deny always wins). See {@link allowTools} for the per-agent delegation-tool note. */
+    denyTools?: string[];
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `skills` — 锚 pretty.js:422126 `e.skills ?? []`, GA/ungated in 198:
+     * CC preloads each named skill's prompt content into the child's opening messages, warning on misses).
+     * sema shape: full {@link SkillSpec} objects (sema has no ambient skill registry to resolve bare names
+     * against) threaded into the chosen child's `TaskSpec.skills` — disclosed in its `<skills>` block +
+     * invocable via the `skill` tool. Deployment-trusted, same trust tier as `systemPrompt`.
+     */
+    skills?: SkillSpec[];
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `background` — 锚 pretty.js:453611 `H.background===!0` OR-ed into
+     * the background predicate, GA/ungated): `true` = this agent ALWAYS launches on the background lane
+     * (an omitted `run_in_background` no longer means sync, and the per-call parameter cannot force sync —
+     * CC-same OR semantics). Requires the delegation tool's `background` surface; without one the child
+     * runs synchronously (CC-same quiet fallback — CC's env kill-switch arm, :453611 `&& !sJt`).
+     */
+    background?: boolean;
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `isolation` — 锚 pretty.js:453599 `z = a ?? H.isolation`, GA):
+     * default isolation for this agent; an explicit per-call `isolation` argument wins. sema supports
+     * `"worktree"` (CC's `"remote"` arm is a claude.ai-session concern, not ported).
+     */
+    isolation?: "worktree";
+    /** Model for this agent. **Omit to INHERIT the caller's current model** (design/38 1B finding 7) — the
+     *  recommended default; a concrete `ModelRef` pins it instead. */
+    model?: ModelRef;
+    /** Thinking level for this agent. **Omit to INHERIT the caller's current thinking level** (the model
+     *  companion above — a mid-run degrade/boost on the parent carries into new children); a concrete
+     *  level pins it instead. */
+    thinking?: ThinkingLevel;
+    /** System prompt / persona for this agent. Falls back to the delegation tool's `systemPrompt`. */
+    systemPrompt?: string;
+    /** Per-agent turn cap. Falls back to the delegation tool's `limits.maxTurns`. Must be POSITIVE: a
+     *  non-positive/non-finite value is ignored (CLS-A-3) rather than folded in, because downstream an
+     *  explicit `0` DISABLES the turn cap — the opposite of the tightening this field expresses. */
+    maxTurns?: number;
+    /** Long-term memory scope for this agent (same shape as {@link TaskSpec.memory}). */
+    memory?: TaskSpec["memory"];
+    /**
+     * This agent's own {@link TaskSpec.memoryPersistenceCapable} declaration — the same three-state
+     * statement, made per definition: an agent whose closure tools persist memory declares `true`
+     * (suppressing the read-only-memory disclosure no roster inference can clear), one whose roster
+     * looks write-capable but reaches no durable store declares `false` (forcing the disclosure).
+     * Arbitration with the spawning run's declaration: a parent's explicit `false` is a FLOOR and wins
+     * over a definition `true` (the disclosure is about the deployment's storage, which choosing this
+     * agent does not change); otherwise a declared definition value wins over the parent's; absent
+     * both, the child spec carries no value and the child's own roster inference decides.
+     * On the workflow lane (`agent(…, {agentType})`) the definition value fills an ABSENT governed-spec
+     * value only — a base/spec declaration of either polarity wins (the lane's spec-pinned-fields rule).
+     */
+    memoryPersistenceCapable?: boolean;
+    /**
+     * Observer agents (CC 2.1.206 parity — 逐字锚 docs/CC206-OBSERVER-ANCHORS-2026-07-11.md, schema
+     * 面 C @28385708): "Agent type auto-spawned as a background observer whenever this agent runs.
+     * The observer receives read-only activity digests and reports via the ObserverReport tool; it
+     * never participates in the task." Resolution is warn-and-unobserved on an unknown type and
+     * refuses chaining (an observer's own `observer` declaration is ignored). Gated by
+     * {@link RuntimeCaps.allowObservers} — EXPLICIT opt-in, default OFF (the sema seat of CC's
+     * default-unset env `CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS` + default-true statsig pair).
+     */
+    observer?: string;
+    /**
+     * CC 面 C: "Supplemental postamble appended (after the harness-owned default) to each activity
+     * digest sent to the observer. Blank values are ignored."
+     */
+    observerMessage?: string;
+}
+/**
+ * A per-skill runtime capability manifest (design/77 §3 Gate-3). When present, loading the skill
+ * SCOPES the rest of the invocation to ONLY these tools/paths via runtime deny-narrowing: a tool call
+ * not in `allowTools` (intersected across nested skill frames) is DENIED, and a write whose canonical
+ * target falls outside `allowPaths` is DENIED — regardless of how permissive the task policy is.
+ *
+ * 🔴 **Safe-by-construction:** a manifest can only SUBTRACT capability. The narrowing composes via the
+ * `deny > ask > allow` fold (`combinePolicies`) where `deny` short-circuits, so a manifest can never
+ * *grant* a tool the task policy withheld — whoever sets a manifest can only restrict further.
+ * Worst case (the model never pops the frame) = no narrowing, never widening — still ⊆ task policy.
+ *
+ * The manifest is CALLER-provided here (same trust level as the rest of `SkillSpec`); deriving it
+ * automatically (the auto-promote pipeline) is a separate, deferred concern (design/77 §5).
+ */
+export interface SkillManifest {
+    /** The ONLY tool names the invocation may call while this skill's frame is active. */
+    allowTools: string[];
+    /**
+     * Optional path allowlist for WRITE tools (`write_file`/`edit_file`): a write whose canonicalized
+     * target is not inside one of these (path-segment-aware) prefixes is DENIED. Omit = no path narrowing
+     * (only `allowTools` applies). Reads are never path-narrowed (this gate restricts capability, not visibility).
+     *
+     * 🔴 **Fail-closed (MAJOR-2):** `allowPaths` can only confine tools whose write target is a parseable `path`
+     * argument (`write_file`/`edit_file`). While an `allowPaths` constraint is active, any OTHER mutating
+     * (effect:write/idempotent) allowlisted tool — notably `bash`, whose command can write anywhere — is DENIED
+     * outright, because its target cannot be path-confined. So a manifest that lists `bash` together with
+     * `allowPaths` does NOT let bash write/egress anywhere: bash is denied while the path constraint is active.
+     * Confine writes to specific paths via `write_file`/`edit_file` only.
+     */
+    allowPaths?: string[];
+    /** Reserved (design/77 §3): whether egress is permitted under this manifest. Carried through; v1 does
+     *  not act on it beyond the allowTools intersection (egress tools must also be in `allowTools`). */
+    egress?: boolean;
+    /** Stable lineage id of the artifact this manifest came from — used in deny reasons + as the scope key. */
+    lineageId: string;
+}
+/** A skill made available to this task (passed as an object; not loaded from disk). */
+export interface SkillSpec {
+    name: string;
+    description: string;
+    content: string;
+    /** Optional Gate-3 runtime capability manifest (design/77 §3) — see {@link SkillManifest}. */
+    manifest?: SkillManifest;
+    /**
+     * Optional attachments bundled with the skill (additive) — the CC bundled-skill shape (a SKILL.md whose
+     * body references sibling files by relative path) translated to sema's brain-outside posture, where the
+     * ruling is: **core never writes to disk.** CC extracts a bundle and lets the body reference files on
+     * the filesystem; sema core has no filesystem authority of its own, so materializing attachments into a
+     * working directory (making `Read`-by-path work) is the DEPLOYMENT's half. What core owns is exactly two
+     * faces, both bounded:
+     * 1. **disclosure** — each attachment's relative `path` is listed on the skill's `<skills>`-block line
+     *    (metadata only, capped like the rest of the block), so the model knows the material exists before
+     *    it loads the skill;
+     * 2. **delivery** — a `Skill` invoke appends an `## Attachments` section after the body (which is
+     *    itself delivered untruncated): each file as `### <path>` + its content, under a SEPARATE total
+     *    cap (`SKILL_ATTACHMENTS_MAX_CHARS`, 50k chars — an attachments-face budget; truncation/omission
+     *    is always disclosed in-band). Without deployment-side materialization this inline delivery is the
+     *    attachment's ONLY reachable face — that is the deliberate minimal shape, not an oversight.
+     *
+     * `path` is a relative, display-oriented identifier (how the body refers to the file); core never
+     * resolves it against a filesystem. `content` carries the SAME trust contract as {@link content}: skill
+     * material is CALLER-trusted instructions by design (see the skills module note) — a caller forwarding
+     * end-user skills is responsible for vetting attachments exactly like the body.
+     */
+    files?: Array<{
+        path: string;
+        content: string;
+    }>;
+}

package/dist/core/agent-definition.js

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