@sema-agent/core 7.49.5 → 7.50.1

package/dist/core/task-event.d.ts

@@ -6,7 +6,7 @@
  * nothing else. Layer 0 vocabulary; `types.ts` re-exports every name below, so no consumer's import
  * changes.
  */
-import type { ActorAssertion } from "../internal/llm.js";
+import type { ActorAssertion, UserAttachmentKind, UserAttachmentOutcome } from "../internal/llm.js";
 import type { TaskResult } from "./task-result.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
 import type { ProviderCondition, ProviderConditionSource } from "../brain/provider-dialect.js";
@@ -383,17 +383,28 @@ export type TaskEvent = ({
      * (previously dropped here); the internal `details` payload is NOT exposed (e.g. a sub-agent tool's
      * `details` is the entire child `TaskResult`).
      *
-     * **Type is `unknown` and intentionally non-uniform** — within size it passes through AS-IS to keep
-     * structure a UI wants (a `string`, or `(TextContent|ImageContent)[]` blocks); when the serialized body
-     * exceeds the core size cap it degrades to a single TRUNCATED STRING (see {@link truncated}). A consumer
-     * must handle both shapes.
+     * **Type is `unknown` and intentionally non-uniform** — a `string` result stays a string (over the core text cap it is
+     * cut and ends with the `…[+N chars truncated]` marker); a `(TextContent|ImageContent|DocumentContent)[]` result stays
+     * an array whose blocks keep their slots. One rule for the array (see {@link truncated}): its text blocks (each at its
+     * text plus whatever else it carries) — with any block that is neither text nor an admitted image/document, at its
+     * serialization — are one character stream under the text cap, cut IN
+     * PLACE where the cap runs out (that block ends with the marker, the stream's later blocks leave); MEDIA blocks are not
+     * measured against the text cap and ride AS-IS while the leg's media budget lasts (`RunnerDeps.mediaByteCapBytes`,
+     * default `AGGREGATE_MEDIA_BUDGET_BYTES`: decoded bytes, spent as base64 on the wire — x 4/3 — after the text's
+     * serialized size), past which a block becomes `{ type, mimeType?, bytes, truncated: true }` in its slot (never a
+     * string; a media type over 255 characters is not echoed), and when not even a descriptor fits, it and every later
+     * media block fold into ONE `{ type: "omitted", blocks, bytes, truncated: true }` in its slot, so the media in an event
+     * is bounded at any block count. A consumer must handle both shapes.
      *
      * **UNTRUSTED RAW + for OBSERVABILITY ONLY**: it is external tool output (file reads, shell stderr, API
      * bodies) and may carry secrets/paths/PII — core bounds only its SIZE; a consumer MUST redact and MAY
      * further bound before it persists or displays it (same contract as `tool_start.args`). It is for a live
      * UI / trace, NOT for re-feeding to a model: a truncated body would mislead an LLM, and the model already
      * has the full, untruncated result in its own context — build model prompts from the session, never by
-     * replaying this field. Absent when the tool produced no content body.
+     * replaying this field. The engine's two model-facing readers of it, the observer digest and the sub-agent step
+     * outcome, render a block through the one block rendering (text as text, any other block as its `[type: mimeType]`
+     * marker, never its payload).
+     * Absent when the tool produced no content body.
      */
     output?: unknown;
     /**
@@ -543,29 +554,31 @@ export type TaskEvent = ({
      */
     notExecuted?: true;
     /**
-     * design/99 §E1 — `true` when {@link output} was SIZE-bounded by core (the full body exceeded the cap and
-     * was degraded to a truncated string). Lets a consumer detect truncation programmatically instead of
-     * parsing the `…[+N chars truncated]` marker out of the string. Absent/false = `output` is the complete
-     * content body. (The full untruncated result still lives in the model's context / `ToolResultStore`.)
+     * design/99 §E1 — `true` exactly when {@link output} is not the content the tool returned: text was cut at the cap
+     * (the string, or the block at the cut, carries the marker; the stream's later blocks left), a media block was
+     * replaced by its descriptor, media folded into the summary, or content that could not be read was replaced by the
+     * one `[unserializable tool output]` string. Lets a consumer detect truncation programmatically
+     * instead of parsing the marker out of the text; a media block carries `truncated: true` on its own descriptor.
+     * Absent/false = `output` IS the returned content, every block in its slot. (The full untruncated result still
+     * lives in the model's context / `ToolResultStore`.)
      */
     truncated?: boolean;
     /**
-     * Present iff {@link truncated}: the TRUE original size (characters) of
-     * the content this event's {@link output} was degraded from — for a string result, the string's own
+     * Present iff {@link truncated} and the content could be read: the TRUE original size (characters) of
+     * the value this event's {@link output} was bounded from — for a string result, the string's own
      * length; for a non-string result (a blocks array), the SUM of each block's own true size (a text
-     * block's `.text.length`; an image/document block's `.data.length`, i.e. its base64 payload) — never
-     * `JSON.stringify(content).length`, which is polluted by two different kinds of noise: structural
-     * overhead (field-name/punctuation bytes that aren't content at all) AND, for text containing quotes/
-     * backslashes/control characters, escape inflation (the same class of bug this field was created to
-     * fix in the first place — a real result: 17298 reported vs 13696 true content characters — reappearing
-     * in a subtler form if the true count were ever taken from the serialized form instead of the blocks).
+     * block's `.text.length` plus whatever else it carries at its serialized length; an image/document block's
+     * `.data.length`, i.e. its base64 payload, whether the
+     * block rode as-is or was replaced by its descriptor; any other block, outside the tool contract, its serialized
+     * length) — never `JSON.stringify(content).length`, which is
+     * polluted by two different kinds of noise: structural overhead (field-name/punctuation bytes that aren't
+     * content at all) AND, for text containing quotes/backslashes/control characters, escape inflation (a
+     * real result: 17298 reported vs 13696 true content characters).
      *
-     * **Not always arithmetically tied to the marker's own `N`**: the marker counts how much MORE of the
-     * shown raw-text rendering exists beyond the cut point; `totalChars` counts the true size of the
-     * ORIGINAL value, which for mixed content includes non-text blocks (e.g. an inlined image) that
-     * `output` never renders as text at all. The two can legitimately diverge — `totalChars` may run far
-     * ahead of the cap plus the marker's `N` — and that gap is itself the honest signal that non-text bulk
-     * was dropped, not an inconsistency to paper over.
+     * **Not arithmetically tied to the marker's own `N`**: the marker counts how much MORE of the shown text
+     * exists beyond the cut point; `totalChars` counts the whole ORIGINAL value, media blocks included, so it
+     * can run far ahead of the cap plus `N`. Read what was cut from the marker (text) and from the
+     * descriptors' own `bytes` (media), not from the gap.
      */
     totalChars?: number;
 } & TaskEventIdentity) | ({
@@ -869,6 +882,10 @@ export type TaskEvent = ({
      *  serving layer replaying the ledger); the core's live emissions precede the commit and
      *  omit it — consumers there join via `message_committed` + stream order. */
     entryId?: string;
+    /** Present only on the `"applied"` frame of an objective that declared attachments: per attachment, in order, what
+     *  the engine read for it and will send (`outcome`) — an admission result, not a delivery. Each attachment is
+     *  delivered as its own message after the objective; its `message_committed` is the delivery. */
+    attachments?: readonly HumanInputAttachment[];
 } & TaskEventIdentity) | ({
     /**
      * design/99 §E3/§E10 — a live BRAIN-LAYER status the brain would otherwise absorb
@@ -897,11 +914,74 @@ export type TaskEvent = ({
      *  fact, not a default: a pre-373 producer event, or a parked record whose tier was not
      *  carried (the terminal sweep's re-pend) — never read absence as `"later"`. */
     priority?: import("./task-notification.js").SystemInjectionPriority;
+} & TaskEventIdentity) | ({
+    /**
+     * A DELEGATED CHILD STARTED: the one frame that says who the child is, at the beat it starts —
+     * before its first model request, so a consumer opens the child's row (a foreground child's panel
+     * line, a background child's fleet entry) without waiting a model turn for the first
+     * `task_progress`. Mirrors CC's `system/task_started`.
+     *
+     * ONE MINT PER CYCLE, at the child leg's spawn station, for every delegation lane alike
+     * (foreground, background, fork, workflow agent, named teammate): a first spawn mints it, and so
+     * does every revival of a completed child (a new cycle — `seq` moves on, the `taskId`/`sessionId`
+     * of the revived run say which). A durable RESUME of a parked leg is the same cycle continuing and
+     * mints NOTHING; a child whose prepare throws never reaches the station and mints nothing either
+     * (its terminal still arrives on the lane that spawned it). Ordered strictly after the leg's
+     * `wiring_manifest` and strictly before anything its first turn produces, so on the forward
+     * channel it is the child's first frame. Rides the same door as `task_progress` (the child's own
+     * stream, and the forward channel to the deployment); the process-level delegation-lifecycle
+     * `spawn` frame is a projection of this mint, delivered at the same instant under the same gate.
+     *
+     * Live and ephemeral like `task_progress`: never persisted, never replayed on resume, absent from
+     * checkpoints. Every member below is a value the run already speaks elsewhere — this frame
+     * introduces no new reading of any of them.
+     *
+     * CC mapping: `task_id` → {@link taskId} (run domain; a background child's registry handle rides
+     * {@link TaskEventIdentity.bgAgentId}), `tool_use_id` → `parentToolCallId`, `description` →
+     * {@link name}, `subagent_type` → {@link agentType}, `task_type`/`is_backgrounded` → {@link taskType}
+     * (absent = a foreground child), `run_id` → {@link seq} (the cycle), `parent_task_id` →
+     * {@link parentTaskId}, `session_id` → {@link sessionId}. Not carried: `prompt` (a delegated
+     * objective can hold a secret — the same reason {@link name} never falls back to it), `awaited`,
+     * `spawn_depth` (the nesting is the `parentTaskId` chain), and the shell/monitor-only members.
+     */
+    type: "task_started";
+    /** The child RUN's id (`spec.taskId ?? sessionId`) — the key its `task_progress` frames carry. */
+    taskId: string;
+    /** The child run's session id — the handle its transcript is read by. */
+    sessionId: string;
+    /** The fleet-task kind, exactly as the child's `task_progress.taskType`: ABSENT for a foreground
+     *  (synchronous) child, which has no fleet row. */
+    taskType?: DelegationTaskType;
+    /** The registry row's cycle generation, exactly as `task_progress.seq` (absent where the child has no
+     *  `a*` row). A revived cycle's frame carries the bumped value. */
+    seq?: number;
+    /** Workflow-lane self-identification, as on `task_progress` (stamped where the workflow forwards). */
+    workflowRunId?: string;
+    /** The workflow agent's label, riding with {@link workflowRunId}. */
+    workflowAgentLabel?: string;
+    /** The spawning run's task id, exactly as `task_progress.parentTaskId`. */
+    parentTaskId?: string;
+    /** The spawning run's session id (the always-on parent linkage). */
+    parentSessionId?: string;
+    /** The delegation tree's root host session. */
+    rootSessionId?: string;
+    /** The child's display label, the same bounded single-line value its `task_progress.name` and its
+     *  hook identity's `agentName` carry. UNTRUSTED display text. */
+    name?: string;
+    /** The explicit `Agent({name})` spawn identity (the teammate key), when the spawn carried one. */
+    spawnName?: string;
+    /** The resolved subagent type the child was spawned as (absent on a workflow-lane agent). */
+    agentType?: string;
+    /** The model the child leg was PREPARED with — the value its `task_progress.model` and
+     *  `TaskResult.model` carry. */
+    model: string;
+    /** Epoch ms at the mint. */
+    startedAt: number;
 } & TaskEventIdentity) | ({
     /**
      * design/99 MF-10 — a SUBAGENT PROGRESS TICK: the delegated sub-run's usage ACCRUING
      * over time, emitted at each turn boundary WHILE it runs, so a parent UI animates the Task card's rollup
-     * (tokens/tool-uses climbing). Emitted ONLY for a subagent (a task with `parentToolCallId`); a top-level
+     * (tokens/tool-uses climbing). Emitted ONLY for a delegated leg (the same eligibility as `task_started`); a top-level
      * run's own usage is the consumer's own. `status:"running"` mid-run; the terminal usage is the `done` result.
      * Live/ephemeral — NOT persisted (a resumable trace re-derives usage from the result), like `status`.
      * Maps to CC `SDKTaskProgress` (camelCase here → snake_case `task_id`/`total_tokens`/`tool_uses`/`duration_ms`
@@ -1075,6 +1155,14 @@ export type TaskEvent = ({
 export type HumanInputEvent = Extract<TaskEvent, {
     type: "human_input";
 }>;
+/** One attachment on a `human_input` frame: its position, the kind the engine found (absent when the read was refused
+ *  before the kind was known), what reached the model of its contents, and the path or name it was declared with. */
+export interface HumanInputAttachment {
+    readonly ordinal: number;
+    readonly kind?: UserAttachmentKind;
+    readonly outcome: UserAttachmentOutcome;
+    readonly label: string;
+}
 /**
  * Outcome of a manual {@link TaskStream.compact} request (the enum names align with
  * the diagnosis decision tree's drain exits, so a consumer can tell "202 processed" states apart):

package/dist/core/task-spec.d.ts

@@ -31,6 +31,39 @@ export type ImageInput = {
     /** URL the runner will fetch and inline as base64 before sending to the model. */
     url: string;
 };
+/**
+ * One file the user attached to the objective, by WHO HOLDS ITS BYTES (never by what kind of file it is — the engine
+ * finds that out and reports it):
+ *  - `{ path, lines? }` — a file or directory the engine can reach in its workspace: the engine reads it through the
+ *    Read tool's own read and admission (read-deny table, roots, the run's deny rules), as if the model had read it,
+ *    minus the questions — the user's declaration is the answer to an ordinary ask; a read some layer would put to a
+ *    person other than the asker (an organization rule, a deployment-authored or real-approval ask) is not attached.
+ *    `lines` reads a line range (1-based, `end` inclusive).
+ *  - `{ name, text, startLine? }` — text the host holds (a local file a remote engine cannot reach, an unsaved buffer):
+ *    delivered as given, line-numbered from `startLine` (default 1). It opens nothing an objective could not carry,
+ *    and records no read state.
+ *  - `{ name, image: { data, mimeType } }` — an image file the host holds (base64), admitted like an image the Read tool
+ *    serves.
+ * Each attachment reaches the model as its own message right after the objective, marked as the engine's: two
+ * marked sentences around the data, the name or path only in the data. See `USER_ATTACHMENT_SEAT` for the limits.
+ */
+export type UserAttachment = {
+    readonly path: string;
+    readonly lines?: {
+        readonly start: number;
+        readonly end?: number;
+    };
+} | {
+    readonly name: string;
+    readonly text: string;
+    readonly startLine?: number;
+} | {
+    readonly name: string;
+    readonly image: {
+        readonly data: string;
+        readonly mimeType: string;
+    };
+};
 /** A single self-contained task with its full configuration. */
 /** The shell-gate FLOOR vocabulary — {@link TaskSpec.shellGate}'s value set, the word the engine persists on a
  *  shell-gated ask (`RiskDescriptor.shellGateDoctrine`) and carries down a delegation chain. One value: `"always"`
@@ -133,6 +166,17 @@ export interface TaskSpec {
     interactiveQuestionFallback?: boolean;
     /** Optional images attached to this turn's user message (model must support vision). */
     images?: ImageInput[];
+    /**
+     * Files the user attached to this objective ({@link UserAttachment}): at most 20, delivered after the
+     * UserPromptSubmit hook lets the objective through (a hook that blocks it reads nothing), each as its own
+     * engine-minted message right after the objective. A path entry needs a workspace (hands on). A malformed entry,
+     * a text entry over the Read limit (100 000 rendered characters), an image the API would not accept, a path entry
+     * on a run without a workspace, or any entry on a durable resume leg is refused at the door:
+     * `config.user_attachment_invalid`, the message opening with the field path (`TaskSpec.userAttachments[2].text: …`).
+     * A file the engine may not read is not refused: its message says it was not attached and why, and the
+     * `human_input` event's `attachments[]` reports each outcome.
+     */
+    userAttachments?: readonly UserAttachment[];
     /** Reuse an existing in-memory session for chat continuity; omit to start fresh. */
     sessionId?: string;
     /**

package/dist/core/task-tool-shape.d.ts

@@ -44,7 +44,7 @@ export interface TaskToolCapabilities {
     /** TaskStop accepts a background agent's spawn NAME as task_id (registry name resolution only). */
     nameAddressing: boolean;
 }
-/** Full-capability profile = the registry-backed mount with notifications wired (CC-209 verbatim form). */
+/** Full-capability profile = the registry-backed mount with notifications wired (CC 209 verbatim form). */
 export declare const REGISTRY_TASK_TOOL_CAPS: TaskToolCapabilities;
 /** The env-direct thin-shell profile: cursor polling over a background shell, nothing else. */
 export declare const ENV_DIRECT_TASK_TOOL_CAPS: TaskToolCapabilities;

package/dist/core/tool-catalog-entries.js

@@ -97,8 +97,22 @@ export const TOOL_CATALOG_ENTRIES = [
             compactable: true,
         },
     },
-    { id: "repo-map", name: "RepoMap", source: "builtin", definedIn: "src/tools/fs/repo-map.ts", mountedBy: ["hands"], cards: ["repo-map"], face: { family: "search", effect: "read", contract: c("core.repo_map@1") } },
-    { id: "lsp", name: "LSP", source: "builtin", definedIn: "src/core/lsp.ts", mountedBy: ["hands"], cards: [], face: { family: "search", effect: "read", contract: c("core.lsp@1") } },
+    {
+        id: "repo-map", name: "RepoMap", source: "builtin", definedIn: "src/tools/fs/repo-map.ts", mountedBy: ["hands"], cards: ["repo-map"],
+        face: {
+            family: "search", effect: "read", contract: c("core.repo_map@1"),
+            pathTarget: { param: "path", access: "read", base: "root", absent: "base" },
+            ruleFace: { params: ["path", "max_chars", "max_files"] },
+        },
+    },
+    {
+        id: "lsp", name: "LSP", source: "builtin", definedIn: "src/core/lsp.ts", mountedBy: ["hands"], cards: [],
+        face: {
+            family: "search", effect: "read", contract: c("core.lsp@1"),
+            pathTarget: { param: "filePath", access: "read", base: "cwd", absent: "none" },
+            ruleFace: { params: ["operation", "filePath", "line", "character", "query"] },
+        },
+    },
     {
         id: "artifact", name: ARTIFACT_TOOL_NAME, source: "builtin", definedIn: "src/tools/artifact/artifact-tool.ts", mountedBy: ["optional"], cards: ["artifact"],
         face: { family: "other", effect: "write", contract: c("core.artifact@1"), ruleFace: { primaryParams: ["action"] }, renderHints: { summaryParams: ["action", "file_path", "url"] } },

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

@@ -234,6 +234,9 @@ export interface EngineAttestation {
     readonly unresolvableCause?: import("./ask-unresolvable-notice.js").AskUnresolvableCause;
     /** The classes of the asks a policy fold collapsed — the proof behind a decision's `foldedAskClasses`. */
     readonly foldedClasses?: readonly import("./ask-origin.js").AskClass[];
+    /** Where a path deny row refused the call — the row, the view of the target it met, the face the call is on. The gate's
+     *  exit mints the refusal's card from it; the judge that found the row is its only writer. */
+    readonly pathDenial?: import("../tools/fs/safety.js").PathDenialEvidence;
 }
 /** The members a station attests — everything but the call binding. */
 export type AttestationMembers = Omit<EngineAttestation, "toolCallId" | "toolName">;
@@ -302,6 +305,8 @@ export declare function screenApproverAttribution(v: unknown): {
     approver?: string;
     defect?: string;
 };
+/** An integrity guard an ask stands on ({@link PermissionResult}'s `guards`). */
+export type AskGuard = "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "artifact_shared_read";
 /**
  * A three-state permission decision for a tool call (design/37). Upgrades the old two-state
  * `{allow|deny}`:
@@ -327,11 +332,13 @@ export declare function screenApproverAttribution(v: unknown): {
  * record ({@link EngineAttestation}) the receipt refuses in any other form, and the gate's exit mints the one
  * settlement record ({@link import("./gate-outcome.js").GateOutcome}) from it; a policy that puts a `settledBy`
  * or `approver` member on its verdict is putting an unread property on it.
- * RB-479-B① (ruled 2026-08-02): the legacy `reason` field is REMOVED — one name for one thing.
+ * RB-479-B① (ruled 2026-08-02): the legacy `reason` field is REMOVED — one name for one thing. The ask arm's one-word
+ * `guard` is retired the same way, for `guards`.
  *
  * The TYPE carries that retirement only where a decision is a literal in an annotated position; an inferred `check`
- * return compiles green with a stray `reason`, so the enforcement is at RUNTIME — every point that consumes a decision
- * refuses one carrying an own `reason` property, fail-closed ({@link refuseOutOfContractDecision}).
+ * return compiles green with a stray `reason` or `guard`, so the enforcement is at RUNTIME — every point that consumes a
+ * decision refuses one that carries a retired member ({@link RETIRED_DECISION_MEMBERS}), fail-closed
+ * ({@link refuseOutOfContractDecision}).
  */
 export type PermissionResult = {
     action: "allow";
@@ -454,18 +461,21 @@ export type PermissionResult = {
     /** The ask's whole class set, in {@link import("./ask-origin.js").ASK_CLASSES} order (see
      *  {@link AskRequest.classes}). Stamped beside {@link askClass}, under the same rule. */
     classes?: readonly import("./ask-origin.js").AskClass[];
-    /** WHICH integrity guard minted this ask — a removal of a protected location, an unverifiable recursive delete,
-     *  shell text the engine cannot read or the session-transcript write. ENGINE-STAMPED by the guard policies; a fold-internal fact the class
-     *  derivation reads ({@link import("./ask-origin.js").classifyAsk}) so the guards, which mint the same
-     *  `requiresRealApproval` ask, are told apart by a fact and not by their prose. Never copied onto the
-     *  approval request or the park row. */
-    guard?: "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "artifact_shared_read";
+    /** WHICH integrity guards stand behind this ask — a removal of a protected location, an unverifiable recursive delete,
+     *  shell text the engine cannot read (or an environment that did not answer the read station), the session-transcript
+     *  write. A set: one ask may stand on several, and each keeps its class. ENGINE-STAMPED by the guard policies and the
+     *  gate fold; a fold-internal fact the class derivation reads ({@link import("./ask-origin.js").classifyAsk}) so the
+     *  guards, which mint the same `requiresRealApproval` ask, are told apart by a fact and not by their prose. Never
+     *  copied onto the approval request or the park row. Replaces the one-word `guard`, which a decision no longer carries:
+     *  a decision that still does is refused by name ({@link RETIRED_DECISION_MEMBERS}). */
+    guards?: readonly AskGuard[];
     /** The call could not be READ against a rule that may reach it — a content-form deny row, a content-form
-     *  ask row, or a persisted-rule row (the lexer's word). ENGINE-STAMPED at the three unreadable mint sites;
-     *  the class derivation reads it as `rule_unreadable` (a mode may release it, a person may clear it, no
+     *  ask row, a persisted-rule row (the lexer's word), or rows the shell read station's boundary stands on that
+     *  could not be read (`persisted_rows`). ENGINE-STAMPED at the four unreadable mint sites;
+     *  the class derivation reads it as `rule_unreadable` (no mode releases it, a person may clear it, no
      *  automatic lane may). It replaces the former practice of stamping `matchedAskRule` on an unreadable
      *  read: a rule that COULD NOT be matched is not a rule that matched. Fold-internal; not on the request. */
-    ruleUnreadable?: "content_deny" | "content_ask" | "persisted_call";
+    ruleUnreadable?: "content_deny" | "content_ask" | "persisted_call" | "persisted_rows";
     /** The ask was authored by the DEPLOYMENT's own governance (an operator's must-ask list, a managed command
      *  policy's default ask) — a fact a host's policy states on its own ask so the class derivation reads it
      *  as `operator_forced`: a permission mode releases nothing an operator mandated (`dontAsk` refuses it like
@@ -853,8 +863,8 @@ export declare const DECISION_MEMBERS: readonly DecisionMember[];
  * taken off the carrier's own descriptor (a member outside the contract is neither read nor carried — a policy's self-declared
  * record on another name finds no reader); any other spelling refused by name — an accessor (never invoked), a member the
  * prototype or a non-enumerable property supplies unless that descriptor spells absence (an `undefined` data value) — judged by
- * descriptor, never read; (3) the retired `reason` field as an OWN property, judged without a read (authorship of the old
- * spelling: a prototype exposing it never wrote it; ignoring it silently dropped the policy's text); (4) the VALUES, off the engine's
+ * descriptor, never read; (3) a retired member ({@link RETIRED_DECISION_MEMBERS}: `reason`, `guard`) carried by the same presence law as a contract
+ * member — own, held by an accessor, or supplied by the prototype — judged without a read (ignoring it silently dropped the policy's text or the ask's guard); (4) the VALUES, off the engine's
  * one-read record, never a second read of the caller's object — the retired window absent, `action` in
  * its closed set (`screenContractValues`, decision-receipt.ts — every closed-set member is held to its set there; a consumer ranks a decision by testing two of its words, so any other value used to rank as an
  * allow; a `canUseTool` result outside its set is a failure in CC) and `decisionReason` in {@link DECISION_REASONS} when
@@ -1085,7 +1095,7 @@ export declare function createCoarseCommandNamePolicy(opts: {
     tools?: string[];
 }): ToolPolicy;
 /**
- * CC 220 "Unverifiable Deletion Target" parity (auto-mode rule): ASK on a recursive+forced delete whose
+ * CC 220 "Unverifiable Deletion Target" parity (auto-mode rule; its text is in 220–245, gone from 2.1.250 on): ASK on a recursive+forced delete whose
  * target is a variable / substitution that cannot be resolved from the command itself — fail-closed in the
  * sense that with no live classifier/approver the ask degrades to deny (see {@link PermissionResult}'s
  * `ask` doc), never to allow. The guard reads ONE plan, the read station's (`removalReadingOf`,

package/dist/core/tool-policy.js

@@ -16,7 +16,7 @@ import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
 import { describeRejectedValue } from "./tool-search-setting.js";
 import { thrownText } from "./thrown-value.js";
-import { assertNoRetiredToolPolicyKeys } from "./retired-keys.js";
+import { assertNoRetiredToolPolicyKeys, RETIRED_DECISION_MEMBERS } from "./retired-keys.js";
 import { isEngineRefusal, nestedRecordsOf, receiveContract, receiveNestedRecords, refusedOutOfContract, screenContractValues } from "./decision-receipt.js";
 export { isEngineRefusal } from "./decision-receipt.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
@@ -43,6 +43,7 @@ const ATTESTATION_GROUP_OF = {
     classifierRound: "classifierRound",
     unresolvableCause: "unresolvableCause",
     foldedClasses: "foldedClasses",
+    pathDenial: "pathDenial",
 };
 const ATTESTATION_MEMBERS = Object.keys(ATTESTATION_GROUP_OF);
 const groupLead = (g) => ATTESTATION_MEMBERS.find((k) => ATTESTATION_GROUP_OF[k] === g);
@@ -238,18 +239,15 @@ export function constraintChainDigest(chain) {
 }
 const ALLOW = Object.freeze({ action: "allow" });
 const ALLOW_BY_RULE = Object.freeze({ action: "allow", decisionReason: "rule" });
-const RETIRED_TEXT_FIELD = "reason";
 export const DECISION_MEMBERS = Object.keys({
     action: 0, updatedInput: 0, message: 0, decisionReason: 0, requiresRealApproval: 0, denialLimitFallback: 0, classifierNoRuling: 0, allowRuleShadowed: 0, probeReason: 0,
     probeCause: 0, probeMandated: 0, mandated: 0, mandate: 0, probeReadRootCandidate: 0, matchedAskRule: 0, ruleEvidence: 0, segmentCoverage: 0,
-    origin: 0, askClass: 0, classes: 0, guard: 0, ruleUnreadable: 0, authoredBy: 0, foldedAskClasses: 0, attestation: 0,
+    origin: 0, askClass: 0, classes: 0, guards: 0, ruleUnreadable: 0, authoredBy: 0, foldedAskClasses: 0, attestation: 0,
 });
 const HOOK_RESULT_MEMBERS = [...DECISION_MEMBERS, "additionalContext"];
 const HOOK_SEAM_UNREAD = new Set(["decisionReason"]);
 const HOOK_SEAM_OPTIONAL = new Set(["action"]);
 const HOOK_RECEIPTS = new WeakSet();
-const RETIRED_TEXT_FIELD_DENY_MESSAGE = `a permission decision carries the retired "${RETIRED_TEXT_FIELD}" field — rename it to "message" (the one text field ` +
-    `a decision carries); denied fail-closed rather than executing a decision whose text this layer cannot read`;
 const ENGINE_RECEIPTS = new WeakSet();
 export function refuseOutOfContractDecision(d, opts) {
     const hookSeam = opts?.reasonIsNonInput === true;
@@ -260,11 +258,9 @@ export function refuseOutOfContractDecision(d, opts) {
     }
     if ((hookSeam ? HOOK_RECEIPTS : ENGINE_RECEIPTS).has(d) || isEngineRefusal(d))
         return d;
-    const decision = receiveContract(d, hookSeam ? HOOK_RESULT_MEMBERS : DECISION_MEMBERS, "");
+    const decision = receiveContract(d, hookSeam ? HOOK_RESULT_MEMBERS : DECISION_MEMBERS, "", RETIRED_DECISION_MEMBERS);
     if (decision.kind === "refused")
         return decision.refused;
-    if (Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD))
-        return refusedOutOfContract(RETIRED_TEXT_FIELD_DENY_MESSAGE);
     const contract = decision.held;
     const refused = receiveNestedRecords(contract) ?? screenContractValues(contract, hookSeam ? { skip: HOOK_SEAM_UNREAD, optional: HOOK_SEAM_OPTIONAL } : undefined);
     if (refused !== undefined)
@@ -293,9 +289,9 @@ export function refuseOutOfContractDecision(d, opts) {
             `the engine keeps its own copy of what it read; denied fail-closed`);
     }
     const receipt = Object.freeze(attestation !== undefined ? { ...detached.value, attestation } : detached.value);
-    for (const k of ["classes", "foldedAskClasses"])
-        if (Object.hasOwn(receipt, k) && Array.isArray(receipt[k]))
-            Object.freeze(receipt[k]);
+    for (const v of Object.values(receipt))
+        if (Array.isArray(v))
+            Object.freeze(v);
     for (const record of nestedRecordsOf(receipt)) {
         for (const v of Object.values(record))
             if (Array.isArray(v))
@@ -711,7 +707,7 @@ function removalAsk(guard, text) {
         unverifiable_delete: `Unverifiable recursive delete (fail-closed unless cleared): ${text}. Re-run the delete with the resolved literal path written into the command itself (or assign the variable a literal path in the same command, e.g. \`DIR=/exact/path; rm -rf "$DIR"\`) so the target can be verified.`,
         unverifiable_shell_text: `Unverifiable shell text (fail-closed unless cleared): ${text}. Write the text into the command itself (a \`-c\` string, a here-document or a here-string) and the engine reads it as it reads any command.`,
     };
-    return { action: "ask", decisionReason: "safety", requiresRealApproval: true, guard, message: messages[guard] };
+    return { action: "ask", decisionReason: "safety", requiresRealApproval: true, guards: [guard], message: messages[guard] };
 }
 function pathSegments(p) {
     return p.split(/[\\/]/).filter(Boolean);
@@ -784,7 +780,7 @@ export function createTranscriptIntegrityPolicy(opts) {
         action: "ask",
         decisionReason: "safety",
         requiresRealApproval: true,
-        guard: "transcript_write",
+        guards: ["transcript_write"],
         message: `Session-transcript write (fail-closed unless cleared): ${what}. Session transcripts (the .jsonl files ` +
             `under the agent data dir's sessions/ directory) are harness-written session state, not agent working ` +
             `files — modifying or deleting them tampers with the run's own audit trail. Reading them (ls/cat/grep ` +

package/dist/core/trace.d.ts

@@ -475,8 +475,9 @@ export type TraceEvent = {
 } | {
     /**
      * design/179 — the person's persisted rule store could not be read (at prepare, or for one call), so
-     * that read's rows took no part: the decision it served was made with ZERO persisted rows. The operator's
-     * per-read record; the person hears it once per run (`permission.rule_store_unavailable`).
+     * that read's rows took no part: a call it served was judged without them — and, at a call, asks a person (the
+     * rows could hold a deny). The operator's per-read record; the person hears it once per run
+     * (`permission.rule_store_unavailable`).
      */
     kind: "permission.rule_store_unreadable";
     version: 1;

package/dist/core/types.d.ts

@@ -13,7 +13,7 @@ import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVer
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
 export { MODEL_ROLES } from "./model-seat.js";
-export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine } from "./task-spec.js";
+export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine, UserAttachment } from "./task-spec.js";
 export type { PermissionMode } from "./ask-origin.js";
 export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
@@ -22,12 +22,12 @@ export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse,
 export type { TaskLimits } from "./task-limits.js";
 export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";
 export type { TerminalCause, PausedCause } from "./terminal-cause.js";
-export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, CompactOutcome } from "./task-event.js";
+export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, HumanInputAttachment, CompactOutcome } from "./task-event.js";
 export type { TaskStream } from "./task-stream.js";
 export type { WorkflowGovernanceBaseline, RuntimeCaps, AutoModeDenySource } from "./runtime-caps.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export type { BackgroundChildEvent, DelegationLifecycleEvent } from "./delegation-frames.js";
-export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
+export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle, emitsChildRowFrames, taskStartedFrame } from "./delegation-frames.js";
 export type { ProjectMemoryLoad, ResumePreflightInfo, ResumePreflightVerdict, RunnerDeps } from "./runner-deps.js";
 export type { EngineNotice, OwedUserInputAccount, UserInputUndrainedCause } from "./engine-notice.js";
 export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";

package/dist/core/types.js

@@ -1,4 +1,4 @@
 export { MODEL_ROLES } from "./model-seat.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
-export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
+export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle, emitsChildRowFrames, taskStartedFrame } from "./delegation-frames.js";
 export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";

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

@@ -330,8 +330,8 @@ export declare function cutEngineSegments(text: string, segments: unknown): {
  * offsets are DEFINED: a user-lane message qualifies only when its content is a plain string or a
  * SINGLE text block (whose text is that same string). Multi-block / image-bearing content returns
  * `undefined` and consumers render the message VERBATIM with their own local flatten — the two
- * projection sides flatten blocks DIFFERENTLY (the auto-mode window joins with `\n` + `[image]`
- * placeholders; the compaction serializer drops non-text blocks and joins with no separator), so a
+ * projection sides flatten blocks DIFFERENTLY (the auto-mode window joins with `\n` + `[image: …]`
+ * block markers; the compaction serializer drops non-text blocks and joins with no separator), so a
  * single `[start, end)` range would point at different characters on each side. The restriction
  * costs nothing real: every engine-assembled prefixed/segmented message (first-frame objective
  * concatenation, resume continuation) is minted from ONE plain string — the sole exception is a