@sema-agent/core 5.61.0 → 5.62.0

package/dist/core/runner/turn-attachments.d.ts

@@ -1,4 +1,5 @@
 import type { McpDroppedTool } from "../mcp.js";
+import type { TaskSpec } from "../types.js";
 import { type SkillListingEntry } from "./synthetic-tools.js";
 /**
  * design/133 §R3 — turn-boundary attachment seam: the PURE producer layer (CC `getContextAttachments`
@@ -28,6 +29,44 @@ export declare const TOOL_SEARCH_REMINDER_CONFIG: {
     readonly EVERY_N_TURNS: 15;
     readonly MAX_NAMES: 10;
 };
+/**
+ * RB-318 — the `total_tokens_reminder` mode set, CC 2.1.245-VERBATIM and in CC's declaration order
+ * (bundle `R9o`; the settings schema declares the same five for its `totalTokensReminder` key).
+ * Each arm names what the rendered number IS, per CC's own schema prose:
+ *  - `off` — the lane is silent. Kept as a member rather than folded into the opt-in flag because it
+ *    is the DEPLOYMENT-RESOLVED kill switch (CC resolves the mode from env
+ *    `CLAUDE_CODE_TOTAL_TOKENS_REMINDER` → settings → gate; sema keeps env resolution at the shell and
+ *    carries only the resolved mode — the {@link AttachmentInputs.config.todoReminderMode} contract
+ *    verbatim, where "wired on" and "silenced by policy" are also two independent bits).
+ *  - `infinite` — the literal text `Infinite`.
+ *  - `fixed` — the constant {@link TOTAL_TOKENS_FIXED_ARM_VALUE}. Together with `infinite` these are
+ *    CC's two CONSTANT arms: they consume no measurement at all, which is exactly why they exist
+ *    (they are the controls the countdown arms are measured against).
+ *  - `countdown` — the live remaining budget, raw.
+ *  - `padded-countdown` — the same, smoothed by a monotone floor so the number never jumps back.
+ */
+export declare const TOTAL_TOKENS_REMINDER_MODES: readonly ["off", "infinite", "fixed", "countdown", "padded-countdown"];
+/**
+ * RB-318 rider — the closed set is spelled TWICE (the public `TaskSpec.attachments.
+ * totalTokensReminderMode` literal union and this array), and only the TaskSpec→array direction had
+ * a compile chain (runtask's AttachmentInputs assignment). The config door widens this array to
+ * `readonly string[]` before `includes`, so a member added HERE and never to the public union used
+ * to compile clean, pass the door, and render — while the public type declared it illegal. Both
+ * directions now refuse at compile time (the governance-codes `satisfies` lockstep form):
+ *  - array ⊆ TaskSpec — the `satisfies` on the declaration above;
+ *  - TaskSpec ⊆ array — the conditional below collapses the exported type to `never` (the default-
+ *    mode constant two lines down errors immediately) when the public union grows an unlisted member.
+ */
+type TaskSpecTotalTokensReminderMode = NonNullable<NonNullable<TaskSpec["attachments"]>["totalTokensReminderMode"]>;
+export type TotalTokensReminderMode = [TaskSpecTotalTokensReminderMode] extends [(typeof TOTAL_TOKENS_REMINDER_MODES)[number]] ? (typeof TOTAL_TOKENS_REMINDER_MODES)[number] : never;
+/** RB-318 — CC 2.1.245's own default ("Defaults to padded-countdown"). The 2026-07-30 registration of
+ *  this lane rested on the 2.1.220 premise "OFF by default even in 220"; 245 flipped it, which is the
+ *  fact that reopened the ruling. Applies only ONCE the deployment has opted the lane in. */
+export declare const TOTAL_TOKENS_REMINDER_DEFAULT_MODE: TotalTokensReminderMode;
+/** RB-318 — CC's `fixed` arm constant (bundle `A9o`). A fixed anchor is the POINT of that arm (the
+ *  number is meant not to move), so it is copied as the constant it is rather than re-pointed at a
+ *  declared ceiling — a deployment that wants its own number picks a countdown arm instead. */
+export declare const TOTAL_TOKENS_FIXED_ARM_VALUE = 5000000;
 /** F5: per-boundary stat scan upper bound — at most this many most-recently-read files are stat'ed. */
 export declare const CHANGED_FILES_MAX = 20;
 /**
@@ -39,7 +78,7 @@ export declare const CHANGED_FILES_MAX = 20;
 export declare const CHANGED_FILES_MTIME_EPS_MS = 2000;
 /** Per-boundary payload byte cap over the whole bundle (weak-model context economics). */
 export declare const ATTACHMENT_BYTE_CAP: number;
-export type AttachmentSource = "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
+export type AttachmentSource = "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "total_tokens_reminder" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
 /** G1 续批 — one agent type on the delegation tool's roster (ToolSpec.agentListing, filled by
  *  createSubagentTool: defined agents + the built-in fork when offered). */
 export interface AgentListingEntry {
@@ -164,6 +203,33 @@ export interface AttachmentState {
      *  agent frame permanently starving the skills frame (each frame individually fits the cap by
      *  construction — agent roster ≤ cap by deployment size, skills block ≤ SKILLS_BLOCK_MAX_BYTES). */
     skillsListingStarved?: boolean;
+    /**
+     * RB-318 — the `padded-countdown` arm's SMOOTHING FLOOR: the highest usage figure this run has
+     * already published against. CC's `cumulativeUsed` (bundle: `Math.max(storedFloor, rolledOver +
+     * used − anchor)`, stored back) exists so the countdown never RUNS BACKWARDS when the live usage
+     * coordinate drops under it — a model that watched its budget shrink and then saw it grow again
+     * learns the number is noise.
+     *
+     * Two of CC's three maps are structurally degenerate here and that is a mapping, not a loss:
+     *  - the per-agent KEY — CC's tracker is session-scoped and keyed by `agentId ?? "main"` because one
+     *    CC session hosts the main agent and its subagents; a sema {@link AttachmentState} is already
+     *    per-RUN, and a delegated child is its own run with its own state, so this scalar IS that slot.
+     *  - the ANCHOR (`reanchorTaskBudget`, re-armed on every regular user prompt so a new user task
+     *    counts down from the full budget again) — a sema LEG is one task epoch, so the anchor is fixed
+     *    at 0 for the leg's whole life and the epoch reset is the next `runTask` invocation — a
+     *    durable-resume leg INCLUDED (it re-enters through `runTask`, rebuilds this state, re-derives
+     *    its slice window and restarts the spend coordinate, so its countdown re-anchors to the new
+     *    leg's real remaining — the CC re-anchor arm, not a floor violation; the floor deliberately
+     *    does NOT ride the checkpoint, since a carried floor against a fresh slice window would freeze
+     *    the readout at "0 tokens left" over an allowance the run genuinely holds). Same lifecycle
+     *    reasoning as the plan_mode lane's `countPlanModeAttachmentsSinceLastExit` note.
+     *  - the ROLLOVER (`rollOverContext`, which adds each compacted-away context back so the count keeps
+     *    advancing) is likewise not owed: sema feeds a CUMULATIVE spend coordinate (`stats.tokens`),
+     *    which a compaction never rewinds, where CC feeds the live context size.
+     * `undefined` = the padded arm has not rendered yet (an OFF lane, or a raw-countdown one, never
+     * allocates it).
+     */
+    totalTokensFloor?: number;
 }
 /**
  * A1-R — the date_change lane's OWN state, deliberately NOT an
@@ -314,6 +380,25 @@ export interface AttachmentInputs {
         used: number;
         total: number;
     };
+    /** RB-318 total_tokens_reminder lane (裁 B, 2026-08-26) — the TOKEN twin of {@link budgetUsd}, fed
+     *  from the same place for the same reason: `used` is the run's cumulative token spend
+     *  (`stats.tokens`) and `total` is the ceiling the budget gate enforces against it
+     *  (`rs.budget.maxTokensWindow` = min(`limits.maxTokens`, the cross-slice allocation's remainder)),
+     *  so a model-visible countdown can never disagree with an eventual `limits.max_tokens_exceeded`.
+     *  Core neither estimates nor discovers this pair: no ceiling declared ⇒ absent ⇒ the countdown arms
+     *  are silent (CC's own `maxBudgetUsd === void 0 → []` posture on the sibling lane).
+     *
+     *  COORDINATE NOTE (candidate divergence registration): CC's two countdown arms read two DIFFERENT
+     *  sources — `countdown` the live remaining context window, `padded-countdown` a synthetic task
+     *  budget (its default 15_000_000 is far larger than any real window). sema carries ONE pair, the
+     *  enforced spend coordinate, and lets the mode pick the arithmetic over it: publishing a context
+     *  window would mean publishing a figure core cannot make true (BYOM — the window, the tokenizer and
+     *  the accounting belong to the deployment's model), while the enforced ceiling is the one token
+     *  number core owns end to end. */
+    totalTokens?: {
+        used: number;
+        total: number;
+    };
     config: {
         todoReminder: boolean;
         /** 口径③ — CC `r2o()` kill-switch parity (pretty.js:479167-479171; consumed by both producers at
@@ -349,6 +434,36 @@ export interface AttachmentInputs {
          *  through a workflow governance baseline (`WorkflowGovernanceBaseline.base`, which explicitly
          *  snapshots `maxCostUsd` and every other governance field) reaches the lane. */
         budgetUsd?: boolean;
+        /**
+         * RB-318 (裁 B, 2026-08-26) — `total_tokens_reminder` (CC 2.1.245 producer `MPs`, renderer `Oje`,
+         * registered in the SHARED producer group beside `budget_usd`, so a subagent carrying its own
+         * ceiling sees it too — the RB-311 attribution verbatim). Opt-in, default OFF like every other 133
+         * member: an un-opted deployment renders no reminder frame — the ATTACHMENT lane itself is
+         * byte-identical to the pre-lane engine. (Scoped deliberately to this lane: registering
+         * `<total_tokens>` in ENGINE_ENVELOPES changed the SANITIZE/DISCLOSURE faces for every
+         * deployment, opted or not — untrusted text carrying that spelling is now defused on the fenced
+         * lanes and envelope-shaped external data trips the design/319 disclosure tail. That is the
+         * defensive direction and unconditional by design: the envelope family must be un-forgeable
+         * whether or not anyone renders the real frame.)
+         *
+         * WHY IT EXISTS NOW. The 2026-07-30 registration refused it as a product-face question and rested
+         * on "OFF by default even in 220". 245 flips exactly that premise — its settings schema reads
+         * "Defaults to padded-countdown", i.e. upstream now publishes a token countdown to the model by
+         * default. The BYOM honesty objection is answered by SHAPE rather than by dropping it: core
+         * estimates nothing. The numbers are the ones the engine already enforces against
+         * ({@link AttachmentInputs.totalTokens}), the ceiling is the deployment's own declared
+         * `limits.maxTokens`, and with no ceiling declared the countdown arms simply never fire.
+         *
+         * The arm is chosen by {@link totalTokensReminderMode} (default {@link
+         * TOTAL_TOKENS_REMINDER_DEFAULT_MODE}); `off` there silences the lane without un-wiring it.
+         */
+        totalTokensReminder?: boolean;
+        /** RB-318 — the RESOLVED mode (see {@link TOTAL_TOKENS_REMINDER_MODES}). CC resolves it from env /
+         *  settings / a server gate; sema keeps env resolution at the deployment shell and carries only the
+         *  resolved value, exactly like {@link todoReminderMode}. Absent ⇒ {@link
+         *  TOTAL_TOKENS_REMINDER_DEFAULT_MODE}. A value outside the closed set is refused at the config
+         *  door (`config.attachment_invalid`), never folded to the default. */
+        totalTokensReminderMode?: TotalTokensReminderMode;
         /** G1: post-compact background-task announce (opt-in, default OFF like the 133 members). */
         backgroundTasks?: boolean;
         /** G1: deferred-tool materialization announce (design/36 setTools delta → boundary notice). */
@@ -441,10 +556,11 @@ export interface AttachmentInputs {
  * done HERE because the caller only invokes this once per boundary after its injection gate passed —
  * splitting "decide" from "mark sent" would just invite a drift between the two.
  *
- * Returns attachments in EVIDENCE-STRENGTH order (todo/task → plan_mode → budget_usd →
- * background_tasks → tools_delta → agent_listing → skills_listing → mcp_instructions → changed_files), which is also the §R3 MED-6
- * truncation order read backwards: under the 8KB cap changed_files is sacrificed first, the todo/task
- * list last. The G1/续批 members are registry/engine ground truth (strong), but the
+ * Returns attachments in EVIDENCE-STRENGTH order (todo/task → tool_search_usage_reminder →
+ * plan_mode → budget_usd → total_tokens_reminder → background_tasks → tools_delta → agent_listing →
+ * skills_listing → mcp_instructions → mcp_dropped_tools → changed_files), which is also the §R3
+ * MED-6 truncation order read backwards: under the 8KB cap changed_files is sacrificed first, the
+ * todo/task list last. The G1/续批 members are registry/engine ground truth (strong), but the
  * todo/plan lane keeps priority: it carries the run's own work-tracking state, which the model can
  * least afford to lose.
  */
@@ -528,6 +644,21 @@ export declare function commitInstructionsChange(state: InstructionsChangeState,
     contentHash: string | null;
 }>): void;
 export declare function renderBudgetUsd(used: number, total: number): string;
+/**
+ * RB-318 — CC 2.1.245 `Oje` VERBATIM: the whole body is the one-line envelope
+ * `<total_tokens>N tokens left</total_tokens>`, where N is the arm's own substitution — the literal
+ * `Infinite`, the {@link TOTAL_TOKENS_FIXED_ARM_VALUE} constant, or the remaining count clamped at
+ * zero (CC's `Math.max(0, …)`: an over-spent run reads `0 tokens left`, never a negative number).
+ *
+ * `remaining` is ignored by the two constant arms — the caller passes whatever it has (the producer
+ * passes 0), matching CC, whose own producer computes `0` for them.
+ *
+ * The `<total_tokens>` tag is an ENGINE-MINTED authority envelope: it is registered in the
+ * `ENGINE_ENVELOPES` census (untrusted-text.ts) and is in the fenced family, so the same spelling
+ * arriving inside untrusted content is defused rather than read as this readout. Its own body needs no
+ * escaping in return — every byte here is engine copy or a finite number.
+ */
+export declare function renderTotalTokensReminder(mode: TotalTokensReminderMode, remaining: number): string;
 /**
  * SR-7 — CC 2.1.198 VERBATIM inner text (bundle pretty.js:698391-698398, `F6c`): the aggregated
  * orphaned-background-task notice a restarted/resumed leg injects ONCE (CC's own `<system-reminder>`
@@ -829,3 +960,4 @@ export declare function selectMcpDroppedBatch<T extends McpDroppedTool>(entries:
  * is unchanged: this is a pure function of (string, number).
  */
 export declare function clipToBytes(s: string, maxBytes: number): string;
+export {};

package/dist/core/runner/turn-attachments.js

@@ -15,15 +15,21 @@ export const TOOL_SEARCH_REMINDER_CONFIG = {
     EVERY_N_TURNS: 15,
     MAX_NAMES: 10,
 };
+export const TOTAL_TOKENS_REMINDER_MODES = ["off", "infinite", "fixed", "countdown", "padded-countdown"];
+export const TOTAL_TOKENS_REMINDER_DEFAULT_MODE = "padded-countdown";
+export const TOTAL_TOKENS_FIXED_ARM_VALUE = 5_000_000;
 export const CHANGED_FILES_MAX = 20;
 export const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export const ATTACHMENT_BYTE_CAP = 8 * 1024;
 const PROJECTION_ITEMS_MAX = 50;
 const PROJECTION_CONTENT_MAX = 80;
 const ATTACHMENT_TAGS_DEFAULT = [...SHELLED_BODY_ENVELOPE_TAGS];
-const ATTACHMENT_TAGS_SKILLS_OWNER = SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "skills");
+const ATTACHMENT_TAGS_OWNED = {
+    skills_listing: SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "skills"),
+    total_tokens_reminder: SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "total_tokens"),
+};
 export function attachmentEnvelopeTags(source) {
-    return source === "skills_listing" ? ATTACHMENT_TAGS_SKILLS_OWNER : ATTACHMENT_TAGS_DEFAULT;
+    return ATTACHMENT_TAGS_OWNED[source] ?? ATTACHMENT_TAGS_DEFAULT;
 }
 export const INSTRUCTIONS_CHANGE_BYTE_CAP = 512;
 export function createAttachmentState() {
@@ -166,6 +172,19 @@ export function collectDueAttachments(state, inp) {
     if (inp.config.budgetUsd && inp.budgetUsd !== undefined) {
         (out ??= []).push({ source: "budget_usd", body: renderBudgetUsd(inp.budgetUsd.used, inp.budgetUsd.total) });
     }
+    if (inp.config.totalTokensReminder === true) {
+        const mode = inp.config.totalTokensReminderMode ?? TOTAL_TOKENS_REMINDER_DEFAULT_MODE;
+        if (mode === "infinite" || mode === "fixed") {
+            (out ??= []).push({ source: "total_tokens_reminder", body: renderTotalTokensReminder(mode, 0) });
+        }
+        else if ((mode === "countdown" || mode === "padded-countdown") && inp.totalTokens !== undefined) {
+            const { used, total } = inp.totalTokens;
+            if (Number.isFinite(used) && Number.isFinite(total) && used >= 0 && total >= 0) {
+                const effectiveUsed = mode === "padded-countdown" ? (state.totalTokensFloor = Math.max(state.totalTokensFloor ?? 0, used)) : used;
+                (out ??= []).push({ source: "total_tokens_reminder", body: renderTotalTokensReminder(mode, total - effectiveUsed) });
+            }
+        }
+    }
     if (inp.config.backgroundTasks && state.postCompactPending) {
         state.postCompactPending = false;
         if (inp.backgroundTasks !== undefined && inp.backgroundTasks.length > 0) {
@@ -362,6 +381,10 @@ export function commitInstructionsChange(state, announced) {
 export function renderBudgetUsd(used, total) {
     return `USD budget: $${used}/$${total}; $${total - used} remaining`;
 }
+export function renderTotalTokensReminder(mode, remaining) {
+    const shown = mode === "infinite" ? "Infinite" : mode === "fixed" ? TOTAL_TOKENS_FIXED_ARM_VALUE : Math.max(0, remaining);
+    return `<total_tokens>${shown} tokens left</total_tokens>`;
+}
 export function renderOrphanedBackgroundTasks(tasks) {
     const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     return (`The container was restarted. The following background tasks were running and are now stopped:\n` +

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -212,6 +212,25 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
+    run("#457 previewWithheld three-form matrix: a row's spelling survives + projects; absent stays absent; an out-of-contract spelling reads as absent", async () => {
+        const store = make();
+        const oversize = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-oversize" });
+        oversize.pendingAction.previewWithheld = "oversize";
+        const unavailable = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-unavailable" });
+        unavailable.pendingAction.previewWithheld = "unavailable";
+        const absent = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-absent" });
+        const bogus = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-bogus" });
+        bogus.pendingAction.previewWithheld = "shrugged";
+        for (const cp of [oversize, unavailable, absent, bogus])
+            await store.put(cp.token, cp);
+        const back = (await store.get(oversize.token)).pendingAction;
+        assert.equal(back.previewWithheld, "oversize", "the row's previewWithheld must survive the round-trip verbatim");
+        const byId = new Map((await store.listByScope("tenant-a")).map((s) => [s.sessionId, s]));
+        assert.equal(byId.get("pw-oversize")?.previewWithheld, "oversize");
+        assert.equal(byId.get("pw-unavailable")?.previewWithheld, "unavailable");
+        assert.equal("previewWithheld" in byId.get("pw-absent"), false, "absent must project the key OMITTED, not null/empty");
+        assert.equal("previewWithheld" in byId.get("pw-bogus"), false, "an out-of-contract spelling must read as absent, never project verbatim");
+    });
     await settle();
 }
 const sortByToken = (a, b) => a.token.localeCompare(b.token);

package/dist/core/tool-errors.d.ts

@@ -118,7 +118,8 @@ export type WorkerErrorClass = "budget" | "limit" | "output" | "suspend" | "revi
  * The `limits.` namespace splits into the `budget` and `limit` classes by exact code — see
  * {@link EXACT_CODE_CLASS}. Operation-level dotted codes that are surfaced to a *caller* and never become a
  * task outcome are deliberately OUT of scope: `steering.*` (`steering.not_running`/`steering.invalid_content`/
- * `steering.duplicate_input_id`, rejected to the `steer()` caller) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
+ * `steering.duplicate_input_id`/`steering.blocked_by_hook`, rejected to the `steer()` caller — the fourth also
+ * rides the resume face as a `CheckpointError` code) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
  * reaches `TaskResult.errorCode`, so a caller will never pass them here. A genuinely unmapped code → `"unknown"` (which therefore means
  * "known-but-foreign or no code", e.g. a leaked fs/Node code, NOT "an OUR terminal class we forgot to add").
  */

package/dist/core/tool-policy.d.ts

@@ -853,6 +853,33 @@ export interface AskRequest {
      *  with contextual escaping and show {@link args} alongside — the preview can misrepresent the
      *  executable action and never replaces args. Never adjudication input. */
     readonly preview?: unknown;
+    /**
+     * #457 ② — PRESENT ⇔ this tool DECLARES an approval preview and the gate could not present a usable
+     * one, naming which way it failed: `"oversize"` (produced, but past the 16KiB display bound — the
+     * truncation stub still rides {@link preview}) or `"unavailable"` (the projection threw, or its value
+     * has no JSON serialization, so nothing was produced at all).
+     *
+     * ABSENT is the ordinary world and covers three cases that are NOT withholdings: the tool declares no
+     * preview, the projection declined to speak for these args, and the projection succeeded. A surface
+     * must therefore read presence, never absence: absence is not a claim that the preview is faithful.
+     *
+     * A DISCLOSURE, not a verdict and not a transform — the same posture as {@link hasBidiControls}. Core
+     * refuses nothing and narrows nothing on account of it: {@link args} and {@link boundInputHash} are
+     * always carried, so unlike a surface whose only content IS the projection, a core approval card can
+     * still show the person exactly what will run. What the bit buys is the honest sentence a card owes
+     * when it is rendering less than the tool meant it to — and the ground for a surface that chooses to
+     * withhold its own PERSISTENT "allow and stop asking me this" affordance while the action cannot be
+     * reviewed as intended (upstream's form: a withheld preview vetoes the standing row, leaving one-time
+     * approval only). Core deliberately does NOT apply that veto to {@link ruleOffers} itself — core's
+     * offers speak for shell COMMAND text, which rides `args` and is shown whatever the preview did.
+     *
+     * Filled at the ask MINT sites that resolve a preview (the synchronous gate leg), not at `resolveAsk`
+     * — the chokepoint receives an already-built request and has no tool table to project from. The
+     * durable park leg's twin is `PendingAction.tool_approval.previewWithheld` on the row, judged over
+     * that row's own fidelity-projected args snapshot; the two faces can honestly differ exactly as the
+     * bidi bit's two faces can.
+     */
+    readonly previewWithheld?: "oversize" | "unavailable";
     /** Canonical digest of {@link args} as presented in THIS ask, computed by the engine's one
      *  `boundInputHashOf` — the same digest a durable park binds its checkpoint to, so an aggregating
      *  approver can reconcile a synchronous ask row against a parked checkpoint row for the same call

package/dist/core/types.d.ts

@@ -1032,7 +1032,7 @@ export interface ToolExecuteContext {
      * is a DISPLAY channel ONLY — the child stream is NEVER merged into the parent's MODEL context, and nothing
      * security-relevant consumes a forwarded event. Present ONLY when the deployment opted in. The tool-ctx wrapper
      * passes `task_progress` unconditionally and — when the deployment sets `forwardSubagentEvents: true` — the
-     * transcript classes too (text_delta/reasoning_delta/tool_start/tool_end); other event types never cross it.
+     * transcript classes too (text_delta/text_end/reasoning_delta/tool_start/tool_end); other event types never cross it.
      * The delegation lane's OWN tap is trusted and forwards the child's FULL event stream (bg frames tagged
      * with bgAgentId). ⚠️ Forwarded ticks are UNTRUSTED display hints — any
      * tool holding this ctx could self-declare one, so a consumer validates `parentTaskId` against its known runs.
@@ -2543,7 +2543,7 @@ export interface TaskSpec {
     /**
      * Subagent viewing pane (dogfood finding 2026-07-03): widen the opt-in display sink
      * (`RunInternals.onForwardEvent`) from `task_progress`-only to a SUBAGENT's live CONTENT events
-     * (`text_delta` / `reasoning_delta` / `tool_start` / `tool_end`), so a UI can render a delegated
+     * (`text_delta` / `text_end` (#447) / `reasoning_delta` / `tool_start` / `tool_end`), so a UI can render a delegated
      * child's transcript live. Default OFF (progress-only, prior behavior). The child stream is still
      * NEVER merged into the parent's model context — this is purely a render channel; forwarded events
      * carry `parentToolCallId` (attribution) and the same UNTRUSTED-RAW contract as the main stream's
@@ -2823,6 +2823,51 @@ export interface TaskSpec {
          * that judgment shaped the DEFAULT-OFF posture; an opted-in deployment chooses CC parity.
          */
         budgetUsd?: true;
+        /**
+         * RB-318 (ruled 2026-08-26) — `total_tokens_reminder` (CC 2.1.245 producer `MPs`, renderer `Oje`):
+         * the TOKEN twin of {@link budgetUsd}. One line per collected boundary,
+         * `<total_tokens>N tokens left</total_tokens>`, CC-verbatim bytes.
+         *
+         * Activation, CC-exact in shape and BYOM-honest in substance: opted in here AND — for the two
+         * COUNTDOWN arms — the task carries a token ceiling (`limits.maxTokens`, or a resource-slice
+         * allocation's remainder). No ceiling ⇒ permanently silent, because core does not know and will not
+         * guess your model's context window: the number it publishes is the one it already ENFORCES
+         * (`stats.tokens` against that ceiling), so the readout can never disagree with an eventual
+         * `limits.max_tokens_exceeded`. The two CONSTANT arms (`infinite` / `fixed`) read no measurement at
+         * all and need no ceiling.
+         *
+         * Cadence, CC-exact: no threshold ladder and no throttle — every collected boundary carries it, and
+         * the "progression" is the numbers advancing with spend. Recorded deviation (shared with
+         * {@link budgetUsd}, and for the same reason): the lane only rides boundaries whose turn resolved
+         * ≥1 tool call, so a boundary steer never EXTENDS a run that reached its natural end.
+         *
+         * Default OFF like every other member of this family. NOTE: this relaxes the same design/74 "no
+         * budget language reaches the model" default that {@link budgetUsd} does — an opted-in deployment
+         * chooses CC parity (where, since 2.1.245, this readout is on by default).
+         */
+        totalTokensReminder?: true;
+        /**
+         * RB-318 — which arm of the readout, CC 2.1.245's closed set (`off` / `infinite` / `fixed` /
+         * `countdown` / `padded-countdown`); absent ⇒ CC's own default `"padded-countdown"`.
+         *
+         *  - `countdown` — remaining = ceiling − spend, raw.
+         *  - `padded-countdown` — the same, through a monotone floor, so the number NEVER JUMPS BACK
+         *    within one engine leg (CC's per-agent smoothing floor; ONE `runTask` invocation is the
+         *    epoch). A durable-resume leg is a NEW epoch by design: the slice window, the spend
+         *    coordinate and the floor all restart, so the resumed leg's readout RE-ANCHORS to its own
+         *    real remaining — which may sit above the prior leg's last readout (the fresh slice window
+         *    is a genuine new allowance; CC's own re-anchor arm counts a new task epoch down from the
+         *    full budget again). Carrying the floor across legs would publish "0 tokens left" against a
+         *    window the run genuinely still holds — a frozen falsehood, deliberately not done.
+         *  - `off` — silences the lane while leaving it wired, for a deployment that resolves the mode from
+         *    its own env/settings the way CC does (core reads no env).
+         *  - `infinite` / `fixed` — CC's two constant arms: the literal `Infinite`, and the constant
+         *    5000000. They publish no measurement (that is what they are for) and need no ceiling.
+         *
+         * A value outside the set is REFUSED at prepare (`config.attachment_invalid`), never folded to the
+         * default — a near-miss spelling must not silently publish a different readout than the one asked for.
+         */
+        totalTokensReminderMode?: "off" | "infinite" | "fixed" | "countdown" | "padded-countdown";
         /** Post-compact background-task restatement — DEFAULT ON since 5.12.0 (boolean, not `true`:
          *  explicit `false` is the opt-out; same contract as the listing family below). CC hard-codes
          *  this behavior, and the opt-in default left every non-shell host (server-driven runs) with a
@@ -3123,8 +3168,10 @@ export interface TaskResult {
      *
      * 1.37+ terminal codes use a **dotted namespace** so a caller can prefix-match a whole class:
      * `"limits.max_tokens_exceeded"` / `"limits.max_cost_exceeded"` / `"limits.max_turns_exceeded"` /
-     * `"limits.max_walltime_exceeded"` / `"config.limit_invalid"` / `"config.limit_unknown_key"`
-     * (e.g. `errorCode.startsWith("limits.")`). 1.36 brain codes (`auth`/`network`/`rate_limit`/…)
+     * `"limits.max_walltime_exceeded"` / `"config.limit_invalid"` / `"config.limit_unknown_key"` /
+     * `"config.attachment_invalid"` (RB-318 — a mode-valued `TaskSpec.attachments` member outside its
+     * closed set, refused at the same door as the limits; e.g. a near-miss `totalTokensReminderMode`
+     * spelling) (e.g. `errorCode.startsWith("limits.")`). 1.36 brain codes (`auth`/`network`/`rate_limit`/…)
      * and `"conflict"` remain flat (unchanged, to avoid breaking existing consumers).
      *
      * design/164 件四/件五 added two codes for the EXTERNAL stop causes — neither is a `limits.` code,
@@ -3137,6 +3184,14 @@ export interface TaskResult {
      *   the wait hint rides the thrown error's `retryAfterMs` (delivered through `RunnerDeps.onError`) and
      *   the message text. Retrying before the window frees will be refused again.
      * Their config-time siblings are `"config.env_lifetime_invalid"` / `"config.usage_window_invalid"`.
+     * A governance window with a MONEY ceiling adds two more, both of which say "the ceiling could not be
+     * evaluated" rather than "the ceiling was reached" — neither is retryable without a config change:
+     * - `"config.usage_window_unpriced"` — a `UsageWindow.maxCostUsd` over a run with no cost figure (no
+     *   `RunnerDeps.pricing` entry and no `Model.cost`). Raised at the door for the run's own model, and at
+     *   the accounting point when a mid-run model switch loses the price table.
+     * - `"usage_window.store_cost_unanswered"` — the wired ledger does not carry the money arm: it either
+     *   dropped the cost supplied to a charge, or answered a $ window without the cost it holds. Both mean
+     *   the ceiling was never evaluated (typically a store or decorator that predates the cost arm).
      */
     errorCode?: string;
     /**
@@ -3446,7 +3501,8 @@ export interface TaskResult {
              *  · `defused` (an MCP/web segment's exact-mark bytes were rewritten — the lane's one sanctioned
              *    byte change, always paired with a `marked` disclosure),
              *  · `envelope` (text shaped like one of the engine's OTHER authority envelopes — the DISCLOSED
-             *    subset is `task-notification` / `new-diagnostics` / `user_memory` / `skills`; `scope` is
+             *    subset is `task-notification` / `new-diagnostics` / `user_memory` / `skills` /
+             *    `total_tokens`; `scope` is
              *    fenced but not disclosed, since `<scope>…</scope>` is also an ordinary build-file element.
              *    That family carries no mark, so its sentence is positional rather than byte-testable. It
              *    rides ON the reminder copy when both families hit, so `envelope` can be bumped alongside
@@ -3670,8 +3726,15 @@ export interface ToolActivity {
 export type HumanInputSource = "objective" | "steer" | "next_turn" | "wake" | "external" | "system";
 /** design/171 §6.2 — how a human input was disposed of when its event was emitted:
  *  `"applied"` = delivered into a model turn; `"queued"` = accepted, awaiting the next turn
- *  boundary; `"parked_for_wake"` = parked for the session's next run (torn-down lane). */
-export type HumanInputDelivery = "applied" | "queued" | "parked_for_wake";
+ *  boundary; `"parked_for_wake"` = parked for the session's next run (torn-down lane);
+ *  `"blocked"` (design/373 §4.3, additive — closed-set add, consumers named in the ship post) =
+ *  a PARKED entry was withheld at resume redelivery — the screen runs on EVERY resume kind that
+ *  drains parked steers (policy_ask / dry_run_review / plan_review / resource_limit, wake
+ *  included) — by the deployment's `userPromptSubmit` screen (block verdict, or a fail-closed
+ *  non-answer/crash): the row was consumed, the frame never reached the model, and the sibling
+ *  `steering.parked_input_blocked` notice names the same inputId — "park 时收下、redeliver 时被筛"
+ *  is auditable, never a silent disappearance. */
+export type HumanInputDelivery = "applied" | "queued" | "parked_for_wake" | "blocked";
 /**
  * The fleet-task kinds a DELEGATED run can honestly claim, derived from (never a second spelling of)
  * {@link TaskNotificationPayload}'s `task_type` vocabulary — the same axis a consumer already keys
@@ -3684,6 +3747,32 @@ export type DelegationTaskType = Extract<TaskNotificationPayload["task_type"], "
 export type TaskEvent = ({
     type: "text_delta";
     delta: string;
+} & TaskEventIdentity) | ({
+    /**
+     * #447 — the assistant's streaming PROSE SEGMENT is COMPLETE: the model closed the text content
+     * block whose bytes just streamed as `text_delta`s. This is the explicit segment boundary a
+     * REMOTE consumer needs so it never has to guess segment ends from wire silence (the idle-flush
+     * heuristic this retires cut one slow-model reply into N fragments). CC-aligned: CC's agent
+     * stream yields each finished content block as its own assistant-message unit at the provider's
+     * `content_block_stop` — block completion IS the segmentation signal there; a single-process
+     * consumer reads it off the provider stream natively, and this event is that same boundary
+     * surfaced on the TaskEvent wire (CC pays the byte cost of re-carrying the block at the stop;
+     * so does this event's `content`).
+     *
+     * `content` = the authoritative FULL text of the completed segment (byte-equal to that
+     * segment's accumulated deltas, from the brain's own accumulation) — a consumer commits the
+     * segment from it instead of trusting its own delta stitching. UNTRUSTED model output for
+     * display only, same contract as `text_delta`. Emitted only for a segment that holds bytes: an
+     * empty text block closes silently (a boundary with no segment would render phantom rows).
+     *
+     * Additive + ignorable. HONEST ABSENCE: the frame exists only when the serving Brain reports
+     * block ends (`text_end` on its event stream — all three first-party brains do; a custom brain
+     * that never emits them yields a wire without this frame). A consumer treats per-segment
+     * presence as the signal and falls back to its own heuristic only on streams that carry none —
+     * absence is "unreported", never "the segment did not end".
+     */
+    type: "text_end";
+    content: string;
 } & TaskEventIdentity) | ({
     type: "reasoning_delta";
     delta: string;
@@ -4064,7 +4153,7 @@ export type TaskEvent = ({
      * repo-controlled and must not enter the event telemetry plane through this echo.
      */
     type: "steering_injected";
-    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
+    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "total_tokens_reminder" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
     preview: string;
 } & TaskEventIdentity) | ({
     /**
@@ -4417,6 +4506,23 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      *  identity (`inputId` idempotency) includes the NORMALIZED tier: the same text replayed under
      *  the same id at a different tier refuses `steering.duplicate_input_id` — an "idempotent
      *  success" that silently skipped the interrupt would be a disposition lie.
+     *
+     * design/373 §4.3 (D2, ruling of 2026-08-24) — a deployment `userPromptSubmit` hook SCREENS this verb:
+     * the steer face is a SERVICE entrance (third-party callers reach a running run through it), so
+     * the deployment's prompt filter sits at the entrance, `ctx.source:"steer"` + `ctx.inputId` +
+     * `ctx.actor` discriminated. Chain position: domain validation → liveness → `inputId` replay
+     * short-circuit → screen → accept/enqueue → (now) interrupt — an idempotent replay of an ACCEPTED
+     * id answers success WITHOUT re-running the hook (a re-run could answer differently and
+     * retro-falsify the standing receipt). Hook `block` ⇒ **typed throw `steering.blocked_by_hook`**
+     * (message carries the hook's own bounded reason); a hook timeout / cancellation / crash refuses
+     * with the SAME code, fail-closed (a screen that did not answer has not cleared the input —
+     * message discriminates the cause; the crash also reaches `onError` phase:"hook"). A blocked call
+     * was never accepted: no `human_input` frame, no undrained account, and the `inputId` stays
+     * UNBOOKED (retry freely, changed content included). `additionalContext` ⇒ prepended to the
+     * delivered frame as the engine's own reminder (never inside the untrusted mid-turn frame). The
+     * replay identity is over the CALLER's bytes — hook output never enters it. Engine-authored
+     * frames (task notifications, diagnostics) and external `notify()` text are OUT of the screen's
+     * domain (notifications are sanitized DATA, not prompts — the notify contract's ruling).
      */
     steer(text: string, options?: {
         trusted?: boolean;
@@ -5063,6 +5169,17 @@ export interface EngineNotice {
      *    implemented, so the unhonored-knob disclosure it carried has no referent; consumers must
      *    judge ladder support by VERSION, never by that code's absence.
      *
+     *  - `"steering.parked_input_blocked"` (design/373 §4.3) — a PARKED steer entry was withheld when
+     *    a resume redelivered it (any resume kind that drains parked steers — wake included) by the
+     *    deployment's `userPromptSubmit` screen (block verdict, or a fail-closed non-answer/crash):
+     *    the row was consumed with the checkpoint, the frame never reached the model, and the resume
+     *    itself proceeds (a blocked instruction must never wedge a wake). The lifecycle half of the
+     *    same fact is the entry's own `human_input` account with `delivery: "blocked"` — the two share
+     *    the inputId, so "accepted at park, screened at redelivery" is auditable end to end. Audience
+     *    `"user"` (the person whose instruction was withheld is the one entitled to re-issue it);
+     *    `detail: { inputId?, sessionId, taskId? }` — `inputId` is the parked entry's stored
+     *    correlation key.
+     *
      *  - `"memory.session_polluted"` (design/178 §3, #324a; message mode-aware since design/336) —
      *    this session's memory crossed into the one-way externally-exposed state (a tool classified
      *    as an external content source was invoked, directly or through a delegated child). Under
@@ -5807,11 +5924,17 @@ export interface RunnerDeps {
      *  `SendMessageToolOptions.admission`; read per call (a value change governs the next message). */
     peerAdmission?: Partial<import("../agents/peer-admission.js").PeerAdmissionConfig>;
     /**
-     * design/164 件五 — DEPLOYMENT-level usage governance: token allowances that span TASKS, evaluated per
+     * design/164 件五 — DEPLOYMENT-level usage governance: allowances that span TASKS, evaluated per
      * principal (or once for the whole deployment when a task declares none). A different axis from
      * `TaskSpec.limits`, which is the allowance ONE task asked for — an operator granting "N tokens per 5
      * hours" cannot express it as a task limit, because nothing stops the next task from asking again.
      *
+     * A window carries a TOKEN ceiling and, optionally, a MONEY ceiling (`UsageWindow.maxCostUsd`, absolute
+     * USD — the `TaskLimits.maxCostUsd` quantity one governance level up). The two are independent and
+     * either one binds. A $ ceiling requires a PRICED run: a task whose model has neither a {@link pricing}
+     * entry nor a `Model.cost` declaration is refused at the door (`config.usage_window_unpriced`) rather
+     * than charged the fabricated 0 an unpriced run would otherwise file into an operator's ceiling.
+     *
      * Unset (the default) ⇒ NO governance: no ledger is read or written and no task can be refused for
      * usage. When set, every window is evaluated at two moments:
      *  - **entry** (before the first model call of a fresh task): an exhausted window REFUSES the task with
@@ -5828,7 +5951,7 @@ export interface RunnerDeps {
      * would take the deployment down instead of telling the operator).
      */
     usageWindows?: readonly import("./usage-window-store.js").UsageWindow[];
-    /** design/164 件五 — the cross-task token ledger {@link usageWindows} is evaluated against. Core bundles
+    /** design/164 件五 — the cross-task usage ledger {@link usageWindows} is evaluated against. Core bundles
      *  `InMemoryUsageWindowStore` (process-local) and `FileUsageWindowStore` (restart-surviving); a fleet
      *  deployment plugs a database behind the same two-method seam. Ignored when `usageWindows` is unset. */
     usageWindowStore?: import("./usage-window-store.js").UsageWindowStore;
@@ -6075,8 +6198,11 @@ export interface RunnerDeps {
     /**
      * Default in-process hooks for all tasks (design/37) — the FULL lifecycle seam of the `Hooks`
      * interface, not just the tool-call trio: `preToolUse` (rewrite/restrict args + inject context),
-     * `postToolUse` (rewrite output + inject context), `userPromptSubmit` (block/inject before the
-     * objective becomes a message), plus `stop` (push back when the run would otherwise end and continue
+     * `postToolUse` (rewrite output + inject context), `userPromptSubmit` (design/373 §4.3: screens
+     * EVERY user-lane entrance — the objective, a live `TaskStream.steer`, a wake resume's message,
+     * and a parked steer's redelivery, discriminated by `ctx.source`; a hook that blocks
+     * unconditionally refuses steers/wakes too — see the ⚠️ WIDENED INVOCATION SET banner on
+     * {@link import("./hooks.js").Hooks.userPromptSubmit}), plus `stop` (push back when the run would otherwise end and continue
      * it), `postToolUseFailure` / `postToolBatch` / `permissionDenied` (failure, batch-boundary and
      * deny observers), `preCompact` / `postCompact` (compaction gate + observer), `stopFailure`
      * (API-error terminal observer) and the `preToolUseObservational` declaration flag — each member's

package/dist/core/untrusted-text.d.ts

@@ -100,10 +100,11 @@ export declare const FENCED_LANE_ENVELOPE_TAGS: readonly string[];
  *
  * These are not fences. They render deployment/server/model-supplied strings into a body the run loop
  * then wraps in engine authority, so a forged envelope inside one is laundered by the wrapper. The
- * wrapper itself cannot blanket-neutralize the family — it also shells the one body that legitimately
- * IS an envelope (`buildSkillsBlock`'s `<skills>` fence) — so containment is expressed as OWNERSHIP:
- * this full set for every body that owns nothing, minus its own tag for the one that does (see
- * `attachmentEnvelopeTags` in turn-attachments.ts).
+ * wrapper itself cannot blanket-neutralize the family — it also shells bodies that legitimately ARE
+ * envelopes (TWO owners today: `buildSkillsBlock`'s `<skills>` fence and `renderTotalTokensReminder`'s
+ * `<total_tokens>` body) — so containment is expressed as OWNERSHIP: this full set for every body that
+ * owns nothing, minus its own tag for each one that does (single source: `ATTACHMENT_TAGS_OWNED` in
+ * turn-attachments.ts, which the per-source `attachmentEnvelopeTags` derivation reads).
  *
  * Allocated ONCE so the sanitizer's memoized break-out regex is keyed by a stable value.
  */

package/dist/core/untrusted-text.js

@@ -48,6 +48,14 @@ export const ENGINE_ENVELOPES = Object.freeze([
         fenced: true,
         disclosed: true,
     },
+    {
+        tag: "total_tokens",
+        kind: "authority",
+        mint: "core/runner/turn-attachments.ts renderTotalTokensReminder (RB-318, CC 2.1.245-verbatim body)",
+        guard: "the body has no untrusted seat at all — every byte is engine copy or a finite number the producer validated; the fence below keeps the same spelling arriving from OUTSIDE from being read as this readout",
+        fenced: true,
+        disclosed: true,
+    },
     {
         tag: "working-file",
         kind: "framing",