@sema-agent/core 7.54.1 → 7.56.0

package/dist/brain/status-sink.d.ts

@@ -1,5 +1,6 @@
 import type { BrainRetryErrClass, BrainStatus } from "../core/types.js";
 import type { ReasoningWireFacts } from "./reasoning.js";
+import type { CapabilityDeclaration, ModelCapability } from "./model-capability.js";
 /** Run `fn` with a per-task brain-status sink in scope. ALS propagates it through the async brain calls
  *  inside `fn` (the harness's prompt → brain.stream → connect/retry loop), so {@link emitBrainStatus}
  *  reaches THIS task's sink and nothing else. */
@@ -168,3 +169,22 @@ export declare function runWithCredentialOriginRefusals<T>(observe: (r: Credenti
  *  `routeRefusalError`; a judgment that only advises reports nothing). The
  *  observer is the Runner's own seat, whose one delivery is the guarded `deliverEngineNotice` — nothing is swallowed here. */
 export declare function reportCredentialOriginRefusal(report: CredentialOriginRefusalReport): void;
+/** A request that withheld a capability from the model it was sent to: the model, the capability, the model's declaration
+ *  that withheld it (`capabilityOf`), and how many blocks it replaced. */
+export interface CapabilityWithheldReport {
+    modelId: string;
+    capability: ModelCapability;
+    cause: Exclude<CapabilityDeclaration, "declared_on">;
+    count: number;
+}
+/**
+ * Run `fn` with a per-run withheld-capability sink in scope — the SIXTH brain→runner ALS channel, with the fourth's shape
+ * and for its reasons: the WHOLE leg (the end-of-task compaction runs after the leg's prompt, and a child leg running
+ * inside its parent's tool call must report to its own leg, not to the scope it inherited), not shielded around the leg's
+ * internal calls, not revoked on settlement, no-op outside the scope.
+ */
+export declare function runWithCapabilityWithheld<T>(observe: (r: CapabilityWithheldReport) => void, fn: () => Promise<T>): Promise<T>;
+/** Report a withheld capability to the active per-run sink, if any (called by the message assemblers' one emit,
+ *  `reportImagesWithheld`). The observer is the Runner's own seat, whose one delivery is the guarded `deliverEngineNotice`
+ *  — nothing is swallowed here: a seat that fails otherwise fails the request build, never the person's notice in silence. */
+export declare function reportCapabilityWithheld(report: CapabilityWithheldReport): void;

package/dist/brain/status-sink.js

@@ -75,3 +75,10 @@ export function runWithCredentialOriginRefusals(observe, fn) {
 export function reportCredentialOriginRefusal(report) {
     credentialOriginRefusalSinkStore.getStore()?.observe(report);
 }
+const capabilityWithheldSinkStore = new AsyncLocalStorage();
+export function runWithCapabilityWithheld(observe, fn) {
+    return capabilityWithheldSinkStore.run({ observe }, fn);
+}
+export function reportCapabilityWithheld(report) {
+    capabilityWithheldSinkStore.getStore()?.observe(report);
+}

package/dist/brain/stream-engine.js

@@ -1,7 +1,7 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { STREAM_TORN_WARNING } from "./stream-shared.js";
 import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } from "./context-overflow.js";
-import { abortLikeName, BrainError, brainErrorCodeOf, classifyFetchThrow, classifyHttp, describeNetworkError, isProviderEchoShape, namesTheFailure, proxyTunnelRefusedSentence, readConnectFailure, readProviderErrorCode, readProviderRequestId, refusedTheRequest } from "./errors.js";
+import { abortLikeName, BrainError, brainErrorCodeOf, classifyFetchThrow, classifyHttp, describeNetworkError, isProviderEchoShape, namesTheFailure, proxyTunnelRefusedSentence, readConnectFailure, readProviderErrorCode, readProviderRequestId, refusedTheRequest, thrownBrainFailure } from "./errors.js";
 import { stripUrlCredentials } from "./route-adjudicator.js";
 import { admittedRequestRoute } from "./request-route.js";
 import { isTransientStatus, isProviderCondition, isProviderConditionSource, judgeHttpFailure, PROVIDER_CONDITION_TRAITS, resolveProviderDialect, } from "./provider-dialect.js";
@@ -314,10 +314,11 @@ export function runStreamingBrain(args) {
         }
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = thrownText(err);
-        if (!aborted && brainErrorCodeOf(err) !== undefined) {
-            if (readMember(err, "inputTooLong") === true)
-                errorMsg.errorKind = "input_too_long";
-            else if (readMember(err, "inputTooLongRuledOut") === true)
+        const failure = aborted ? {} : thrownBrainFailure(err);
+        if (failure.code !== undefined) {
+            if (failure.errorKind !== undefined)
+                errorMsg.errorKind = failure.errorKind;
+            else if (failure.inputTooLongRuledOut === true)
                 errorMsg.inputTooLongRuledOut = true;
             if (readMember(err, "errorBodyIncomplete") === true)
                 errorMsg.errorBodyIncomplete = true;

package/dist/brain/stream-shared.d.ts

@@ -14,7 +14,7 @@ import { type AssistantMessage, type ModelOutputInvalid, type StreamDropCause }
  *
  * Internal module: not re-exported from `src/index.ts`.
  */
-/** The warning (CC 2.1.220's words; gone from 2.1.245 on — 2.1.296 asks for a resume instead) stamped beside `partialFinalized` when a stream ended before its close — by the
+/** The warning (the reference's former words; later replaced by a resume request) stamped beside `partialFinalized` when a stream ended before its close — by the
  *  mid-stream promotion (the body threw) and by the parsers' own finalize (content arrived, no finish frame). */
 export declare const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
 /** A provider word as a stream-end seat carries it: the word in the provider echo shape, else `?` — the fact that a

package/dist/core/a2a.d.ts

@@ -1,4 +1,5 @@
 import type { AgentTool } from "../internal/harness-types.js";
+import { type HostFloor } from "./host-floor.js";
 import type { A2aServerSpec, ToolEffect } from "./types.js";
 /** The hard per-skill description bound (ruled 2026-08-03: ~2KiB). */
 export declare const A2A_SKILL_DESCRIPTION_MAX_CHARS = 2048;
@@ -96,4 +97,4 @@ export declare class A2aRpcError extends Error {
  * `allSettled` keeps it fail-open: one unreachable peer is a skipped peer with a warning, never a task
  * that cannot start.
  */
-export declare function materializeA2aTools(specs: readonly A2aServerSpec[], principal?: string, signal?: AbortSignal): Promise<MaterializedA2a>;
+export declare function materializeA2aTools(specs: readonly A2aServerSpec[], principal?: string, signal?: AbortSignal, hostFloor?: HostFloor): Promise<MaterializedA2a>;

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 { assertEndpointBound, redirectPolicy, resolveProtocolHttpHeaders, underDeclaredHeaders } from "./protocol-http-auth.js";
+import { assertEndpointBound, carriesDeclaredHeaders, resolveProtocolHttpHeaders, underDeclaredHeaders } from "./protocol-http-auth.js";
+import { fetchFollowing, hopRefusal, HOST_FLOOR_REFUSED_CODE } from "./host-floor.js";
 import { describeHttpTransportFailure } from "./mcp-failure.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
 import { A2A_NAMESPACE } from "./protocol-table.js";
@@ -77,6 +78,7 @@ function safeId(v) {
         return undefined;
     return inlineUntrusted(s, A2A_ID_MAX_CHARS);
 }
+const A2A_MAX_REDIRECTS = 20;
 function withRequestDeadline(outer, timeoutMs) {
     const controller = new AbortController();
     let timedOut = false;
@@ -144,21 +146,25 @@ async function readBoundedText(res, what) {
 async function requestJson(t, what, init) {
     const doFetch = resolveFetch();
     const deadline = withRequestDeadline(init.signal, init.timeoutMs);
+    const peerLabel = inlineUntrusted(t.peer, A2A_ID_MAX_CHARS);
     try {
-        const res = await doFetch(init.url, {
+        const followed = await fetchFollowing(doFetch, new URL(init.url), {
             method: init.method,
-            signal: deadline.signal,
-            redirect: redirectPolicy(t.headers),
             headers: underDeclaredHeaders({ accept: "application/json", "a2a-version": A2A_PROTOCOL_VERSION, ...(init.body !== undefined ? { "content-type": "application/json" } : {}) }, t.headers),
             ...(init.body !== undefined ? { body: init.body } : {}),
-        });
-        const text = await readBoundedText(res, `${what} from A2A peer "${inlineUntrusted(t.peer, A2A_ID_MAX_CHARS)}"`);
+            signal: deadline.signal,
+        }, { refusal: (url) => hopRefusal(url, t.floor, false), follows: () => !carriesDeclaredHeaders(t.headers), maxRedirects: A2A_MAX_REDIRECTS });
+        if (followed.kind === "refused")
+            throw Object.assign(new Error(`a2a: ${what} on peer "${peerLabel}" is not sent — ${followed.reason}`), { code: HOST_FLOOR_REFUSED_CODE });
+        if (followed.kind === "too_many")
+            throw new Error(`a2a: ${what} on peer "${peerLabel}" was redirected more than ${A2A_MAX_REDIRECTS} times`);
+        const res = followed.res;
+        const text = await readBoundedText(res, `${what} from A2A peer "${peerLabel}"`);
         return { status: res.status, text };
     }
     catch (err) {
         if (init.signal?.aborted === true)
             throw err;
-        const peerLabel = inlineUntrusted(t.peer, A2A_ID_MAX_CHARS);
         if (deadline.timedOut()) {
             throw new Error(`a2a: ${what} on peer "${peerLabel}" got no answer within ${init.timeoutMs}ms. The client stopped waiting — the peer may still be acting on the request, so treat the outcome as UNKNOWN and verify before retrying.`, { cause: err });
         }
@@ -553,16 +559,16 @@ function declaredPeerOf(declared, index) {
     const judged = judgeEntryToolAxes(snapshot, "a2a");
     return judged.ok ? { spec: judged.entry } : { spec: snapshot, refusal: judged.error };
 }
-async function materializePeer(peer, principal, lifecycle, signal) {
+async function materializePeer(peer, principal, lifecycle, signal, floor) {
     if ("refusal" in peer)
         throw peer.refusal;
     const { spec } = peer;
     const declaredAxes = spec.toolAxes;
     const headers = resolveProtocolHttpHeaders(A2A_NAMESPACE.id, spec, principal);
-    const discovery = { peer: spec.name, endpoint: spec.url, headers };
+    const discovery = { peer: spec.name, endpoint: spec.url, headers, floor };
     const card = readCard(spec.name, await discoverCardBody(spec, discovery, signal), spec.url);
     assertEndpointBound(A2A_NAMESPACE.id, spec.name, card.endpoint, spec.cardUrl === undefined ? [spec.url] : [spec.url, spec.cardUrl], headers);
-    const transport = { peer: spec.name, endpoint: card.endpoint, headers };
+    const transport = { peer: spec.name, endpoint: card.endpoint, headers, floor };
     const tools = [];
     const skillAxes = [];
     for (const skill of card.skills) {
@@ -592,7 +598,7 @@ function asPeerWarning(spec, err) {
     warning.code = "a2a.peer_unavailable";
     return warning;
 }
-export async function materializeA2aTools(specs, principal, signal) {
+export async function materializeA2aTools(specs, principal, signal, hostFloor) {
     const peers = specs.map((spec, index) => declaredPeerOf(spec, index));
     if (peers.length > 0) {
         const collision = findNamespacePrefixCollision(A2A_NAMESPACE, peers.map((p) => p.spec.name));
@@ -610,7 +616,7 @@ export async function materializeA2aTools(specs, principal, signal) {
     const toolAxes = [];
     const warnings = [];
     const statuses = [];
-    const settled = await Promise.allSettled(peers.map((peer) => materializePeer(peer, principal, lifecycle, signal)));
+    const settled = await Promise.allSettled(peers.map((peer) => materializePeer(peer, principal, lifecycle, signal, hostFloor)));
     for (let i = 0; i < peers.length; i++) {
         const spec = peers[i].spec;
         const outcome = settled[i];
@@ -645,7 +651,7 @@ export async function materializeA2aTools(specs, principal, signal) {
                 }
                 const previous = statuses.find((s) => s.name === spec.name)?.toolNames ?? [];
                 try {
-                    const fresh = await materializePeer(target, principal, lifecycle, signal);
+                    const fresh = await materializePeer(target, principal, lifecycle, signal, hostFloor);
                     const names = fresh.tools.map((t) => t.name);
                     results.push({
                         peer: spec.name,

package/dist/core/advisor-verdict.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The advisor seat's two answers, each minted here once and read by every reader: whether the advisor tool attaches for
+ * a (main model, advisor model) pair on a deployment ({@link advisorAttachVerdict} — the prepare mount, a host's advisor
+ * query and its echo all ask this one function), and whether a conversation has switched the advisor off
+ * ({@link advisorHoldOf} — read off the transcript, its only source of truth, at the mount, at every call and by a host).
+ * The closed sets the answers are spelled in live beside them.
+ */
+import type { SessionTreeEntry } from "../internal/harness-types.js";
+import { type BrainErrorCode } from "../brain/errors.js";
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { EngineNotice, Model, ModelRef, RunnerDeps } from "./types.js";
+/** The tool's wire name. */
+export declare const ADVISOR_TOOL_NAME = "advisor";
+/** What a fork is told when it inherits the advisor tool with its parent's prefix — the reference's sentence. */
+export declare const ADVISOR_FORK_SENTENCE = "Never consult the advisor tool.";
+/** Why the advisor tool is not attached on a leg whose spec names an advisor model. The first six are the static verdict's
+ *  answers; the last three are the mount's (the tool selector unmounted it, its route cannot pair, the transcript could
+ *  not be read). */
+export declare const ADVISOR_NOT_ATTACHED_REASONS: readonly ["disabled", "unknown_model", "advisor_unranked", "weakest_tier", "main_unranked", "pairing", "route_refused", "excluded", "hold_unknown"];
+export type AdvisorNotAttachedReason = (typeof ADVISOR_NOT_ATTACHED_REASONS)[number];
+/**
+ * Each reason's sentence to the person (`advisor.not_attached`, once per conversation per pair) — `null` for a reason that
+ * tells nobody: the deployment switched the advisor off (it is ignored), the deployment's tool selector unmounted it
+ * (`excluded`), or its route cannot pair with the deployment's credentials (`route_refused`, told to the operator by
+ * `route.seat_detached` — only an operator can fix it).
+ */
+declare const NOT_ATTACHED_SENTENCE: {
+    readonly disabled: null;
+    readonly unknown_model: (a: string) => string;
+    readonly advisor_unranked: (a: string) => string;
+    readonly weakest_tier: (a: string) => string;
+    readonly main_unranked: (_a: string, m: string) => string;
+    readonly pairing: (a: string, m: string) => string;
+    readonly route_refused: null;
+    readonly excluded: null;
+    readonly hold_unknown: () => string;
+};
+export type NotAttachedSentenceCoversEveryReason = AssertAllKeysHandled<Exclude<AdvisorNotAttachedReason, keyof typeof NOT_ATTACHED_SENTENCE>>;
+/** The shape door of `TaskSpec.advisorModel` (read only while the deployment switch is on): absent, a non-empty ref, or a
+ *  Model object; anything else refuses (`config.advisor_model_invalid`) — a model the engine cannot read names no advisor. */
+export declare function assertAdvisorModelShape(ref: unknown): void;
+/** The three faces of one advisor call: guidance came back, the advisor model refused, or no guidance could be had. */
+export declare const ADVISOR_OUTCOMES: readonly ["reviewed", "declined", "unavailable"];
+export type AdvisorOutcome = (typeof ADVISOR_OUTCOMES)[number];
+/** The static verdict: the advisor attaches on `model`, or does not and says why. */
+export type AdvisorAttachVerdict = {
+    readonly state: "on";
+    readonly model: Model;
+} | {
+    readonly state: "not_attached";
+    readonly reason: Exclude<AdvisorNotAttachedReason, "route_refused" | "excluded" | "hold_unknown">;
+};
+/**
+ * Whether the advisor tool attaches for `advisor` beside the run's `main` model, in command order: the deployment switch,
+ * then the advisor itself (a model the catalog cannot resolve, one on no declared tier, one on the weakest tier — `lite`,
+ * the tier the `haiku` alias names), then the main model (on no declared tier, or on a WEAKER tier than the advisor's:
+ * an advisor at least as capable as the main model attaches). Tiers are read by the classifier seat's own reading
+ * ({@link tierIndexOf}) over a catalog {@link normalizeSeatDeps} expanded, so a host holding raw deps gets the engine's
+ * answer. No tiers declared ⇒ no ranks ⇒ not attached.
+ */
+export declare function advisorAttachVerdict(args: {
+    deps: Pick<RunnerDeps, "models" | "tiers" | "advisorTool">;
+    main: Model;
+    advisor: ModelRef;
+}): AdvisorAttachVerdict;
+/**
+ * Which failure of an advisor request switches the advisor off for the conversation: the advisor model's credential refused
+ * (`auth`), or a provider 400 / 422 its minter ruled out as an over-window request (`invalid_request` with
+ * `inputTooLongRuledOut`) — deterministic client faults that repeat until the conversation is compacted. Every other code,
+ * an over-window refusal and an unclassified 400 pass (the next call may succeed). Total over the brain codes by its fence.
+ */
+export declare const ADVISOR_HOLD_CAUSES: Readonly<{
+    readonly auth: "hold";
+    readonly invalid_request: "hold_unless_window";
+    readonly rate_limit: "pass";
+    readonly server: "pass";
+    readonly network: "pass";
+    readonly http: "pass";
+    readonly stream_torn: "pass";
+    readonly refusal: "pass";
+    readonly length_empty: "pass";
+}>;
+/** What one failure's code does to the conversation's advisor ({@link ADVISOR_HOLD_CAUSES}). */
+export type AdvisorHoldDisposition = "hold" | "hold_unless_window" | "pass";
+export type HoldCausesCoverEveryBrainCode = AssertAllKeysHandled<Exclude<BrainErrorCode, keyof typeof ADVISOR_HOLD_CAUSES>>;
+/** What a failed advisor request said about itself — the fields the hold reads and the card carries. */
+export interface AdvisorFailure {
+    readonly code?: BrainErrorCode;
+    readonly errorKind?: "input_too_long" | "degenerate" | "length_empty";
+    readonly inputTooLongRuledOut?: true;
+}
+/** Whether this failure switches the advisor off for the conversation ({@link ADVISOR_HOLD_CAUSES}). */
+export declare function advisorFailureHolds(f: AdvisorFailure): boolean;
+/** The conversation's advisor switch-off, with the cause of the call that switched it. */
+export interface AdvisorHold {
+    readonly code?: BrainErrorCode;
+    readonly errorKind?: AdvisorFailure["errorKind"];
+}
+/**
+ * Whether the conversation on this branch has switched the advisor off, read off the transcript: an advisor tool result
+ * recorded after the latest compaction whose card says `hold: true` — the latest such card's cause. A compaction clears it
+ * (the card lands before it); a new conversation has none; a fork copies its parent's branch and with it the hold.
+ * `undefined` = not held. Members of a recorded card outside their closed sets are not carried.
+ */
+export declare function advisorHoldOf(entries: ReadonlyArray<SessionTreeEntry>): AdvisorHold | undefined;
+/** A not-attached reason the person is told about — its own fact or one they can act on — as a type. */
+export type AdvisorToldReason = {
+    [R in AdvisorNotAttachedReason]: (typeof NOT_ATTACHED_SENTENCE)[R] extends null ? never : R;
+}[AdvisorNotAttachedReason];
+/** Whether the person is told about this reason ({@link NOT_ATTACHED_SENTENCE}: the reasons with a sentence). */
+export declare function advisorReasonTold(reason: AdvisorNotAttachedReason): reason is AdvisorToldReason;
+/** The `advisor.not_attached` notice for a reason the person is told about. */
+export declare function advisorNotAttachedNotice(args: {
+    reason: AdvisorToldReason;
+    advisorModel: string;
+    mainModel: string;
+    sessionId: string;
+    runId?: string;
+}): EngineNotice;
+export {};

package/dist/core/advisor-verdict.js

@@ -0,0 +1,92 @@
+import { ALL_BRAIN_ERROR_CODES } from "../brain/errors.js";
+import { DEFAULT_TIER_ORDER, resolveModel } from "./roles.js";
+import { normalizeSeatDeps, tierIndexOf } from "./runner/classifier-ladder.js";
+export const ADVISOR_TOOL_NAME = "advisor";
+export const ADVISOR_FORK_SENTENCE = "Never consult the advisor tool.";
+export const ADVISOR_NOT_ATTACHED_REASONS = Object.freeze(["disabled", "unknown_model", "advisor_unranked", "weakest_tier", "main_unranked", "pairing", "route_refused", "excluded", "hold_unknown"]);
+const NOT_ATTACHED_SENTENCE = {
+    disabled: null,
+    unknown_model: (a) => `The advisor model "${a}" is not in this deployment's model catalog, so the advisor is off.`,
+    advisor_unranked: (a) => `"${a}" cannot be used as an advisor: the deployment declares no tier for it (declare RunnerDeps.tiers so the engine knows which model is stronger).`,
+    weakest_tier: (a) => `"${a}" cannot be used as an advisor: it is on the weakest tier.`,
+    main_unranked: (_a, m) => `The advisor will not activate on the main model (${m}): the deployment declares no tier for it (declare RunnerDeps.tiers). Subagents may still use it.`,
+    pairing: (a, m) => `${a} is less capable than the current main model (${m}), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.`,
+    route_refused: null,
+    excluded: null,
+    hold_unknown: () => `The advisor is off for this run: whether this conversation had switched it off could not be read.`,
+};
+export function assertAdvisorModelShape(ref) {
+    if (ref === undefined || (typeof ref === "string" ? ref !== "" : typeof ref === "object" && ref !== null && typeof ref.id === "string"))
+        return;
+    const shown = typeof ref === "string" ? "an empty string" : ref === null ? "null" : Array.isArray(ref) ? "an array" : typeof ref;
+    throw Object.assign(new Error(`TaskSpec.advisorModel must be a non-empty model ref or a Model (got ${shown}) — a model the engine cannot read names no advisor.`), { code: "config.advisor_model_invalid" });
+}
+export const ADVISOR_OUTCOMES = Object.freeze(["reviewed", "declined", "unavailable"]);
+export function advisorAttachVerdict(args) {
+    if (args.deps.advisorTool === "disabled")
+        return { state: "not_attached", reason: "disabled" };
+    const deps = normalizeSeatDeps(args.deps);
+    let advisor;
+    try {
+        advisor = resolveModel(args.advisor, deps.models);
+    }
+    catch {
+        return { state: "not_attached", reason: "unknown_model" };
+    }
+    const advisorTier = tierIndexOf(deps, advisor);
+    if (advisorTier === undefined)
+        return { state: "not_attached", reason: "advisor_unranked" };
+    if (advisorTier === DEFAULT_TIER_ORDER.indexOf("lite"))
+        return { state: "not_attached", reason: "weakest_tier" };
+    const mainTier = tierIndexOf(deps, args.main);
+    if (mainTier === undefined)
+        return { state: "not_attached", reason: "main_unranked" };
+    if (advisorTier > mainTier)
+        return { state: "not_attached", reason: "pairing" };
+    return { state: "on", model: advisor };
+}
+export const ADVISOR_HOLD_CAUSES = Object.freeze({
+    auth: "hold",
+    invalid_request: "hold_unless_window",
+    rate_limit: "pass",
+    server: "pass",
+    network: "pass",
+    http: "pass",
+    stream_torn: "pass",
+    refusal: "pass",
+    length_empty: "pass",
+});
+export function advisorFailureHolds(f) {
+    if (f.code === undefined)
+        return false;
+    const row = ADVISOR_HOLD_CAUSES[f.code];
+    return row === "hold" || (row === "hold_unless_window" && f.errorKind !== "input_too_long" && f.inputTooLongRuledOut === true);
+}
+const ERROR_KINDS = new Set(["input_too_long", "degenerate", "length_empty"]);
+export function advisorHoldOf(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e.type === "compaction")
+            return undefined;
+        if (e.type !== "message" || e.message.role !== "toolResult" || e.message.toolName !== ADVISOR_TOOL_NAME)
+            continue;
+        const d = e.message.details;
+        if (d === null || typeof d !== "object" || d.type !== "advisor" || d.hold !== true)
+            continue;
+        const code = ALL_BRAIN_ERROR_CODES.find((c) => c === d.code);
+        const errorKind = typeof d.errorKind === "string" && ERROR_KINDS.has(d.errorKind) ? d.errorKind : undefined;
+        return { ...(code !== undefined ? { code } : {}), ...(errorKind !== undefined ? { errorKind } : {}) };
+    }
+    return undefined;
+}
+export function advisorReasonTold(reason) {
+    return NOT_ATTACHED_SENTENCE[reason] !== null;
+}
+export function advisorNotAttachedNotice(args) {
+    const sentence = NOT_ATTACHED_SENTENCE[args.reason];
+    return {
+        code: "advisor.not_attached",
+        message: sentence(args.advisorModel, args.mainModel),
+        detail: { advisorModel: args.advisorModel, mainModel: args.mainModel, reason: args.reason, sessionId: args.sessionId, ...(args.runId !== undefined ? { runId: args.runId } : {}) },
+    };
+}

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

@@ -19,8 +19,7 @@ export interface AgentDefinition {
     /** 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
+     * F4 (`whenToUseLean`): 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.
@@ -36,7 +35,7 @@ export interface AgentDefinition {
     /** Tool denylist (a deny always wins), tool NAMES: `Tool(content)` hides the whole `Tool`. 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:
+     * F7 (per-agent `skills`:
      * 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 +
@@ -44,7 +43,7 @@ export interface AgentDefinition {
      */
     skills?: SkillSpec[];
     /**
-     * F7 (CC 2.1.198 parity, per-agent `background` — 锚 pretty.js:453611 `H.background===!0` OR-ed into
+     * F7 (per-agent `background`, 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
@@ -52,7 +51,7 @@ export interface AgentDefinition {
      */
     background?: boolean;
     /**
-     * F7 (CC 2.1.198 parity, per-agent `isolation` — 锚 pretty.js:453599 `z = a ?? H.isolation`, GA):
+     * F7 (per-agent `isolation`):
      * 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).
      */
@@ -86,8 +85,8 @@ export interface AgentDefinition {
      */
     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.
+     * Observer agents (schema
+     * 面 C): "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
@@ -116,7 +115,7 @@ export interface SkillSpec {
      * either list asks once (`Execute skill: <name>`, the card listing what it releases); a skill the person invoked by
      * name ({@link import("./task-spec.js").TaskSpec.userInvokedSkills}) grants without asking. The grant holds for that
      * run (a steer it takes in does not end it) and the next runTask starts without it. An entry this grammar reads as nothing — `*` (it voids an allow list; on a deny list it is inert and the rest of the
-     * list still refuses), `mcp__*`, a write path, a domain — grants nothing and is announced at the start of the run (`permission.allowed_tool_not_granted`). A table whose value is not a list (a string, an object…) reads as one such entry; `null` is no table.
+     * list still refuses), `mcp__*` / `mcp__*__*` (an allow entry names a peer), a write path, a domain — grants nothing and is announced at the start of the run (`permission.allowed_tool_not_granted`). A table whose value is not a list (a string, an object…) reads as one such entry; `null` is no table.
      */
     allowedTools?: string[];
     /** The tools refused for the rest of the run this skill is activated in — the frontmatter `disallowed-tools` list,
@@ -158,4 +157,14 @@ export interface SkillSpec {
      * byte-identical result; a placeholder with no directory stays verbatim.
      */
     baseDir?: string;
+    /**
+     * The hooks this skill carries — registrations on the mods bus (the `TaskSpec.mods` form: user tier, a name unique in the
+     * run), whose handlers take part only while the skill is ACTIVE on the leg that loads it: from its activation (the `Skill`
+     * tool's success, or prepare for a skill the person invoked by name; a resumed run reopens the skills its park recorded
+     * active) to the end of that run. A host compiles a frontmatter `hooks:` table into one such registration; the engine
+     * reads no hook grammar. Each hangs `classic.*` events only (any other event refuses the prepare, `config.mods_invalid`).
+     * They are admitted with the leg's other registrations at its prepare (so a skill never activated still counts as a hook
+     * the leg may run) and stay the leg's own: a delegated child neither dispatches them nor is screened by them.
+     */
+    mods?: readonly import("./mods/classic-events.js").EngineModRegistration[];
 }