@sema-agent/core 7.49.5 → 7.50.0

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

package/dist/core/user-attachment.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The USER-ATTACHMENT SEAT — the one road a file the user hands the model takes:
+ *
+ *   the host declares it on the objective (`TaskSpec.userAttachments`) → the engine screens the declaration at the
+ *   door → after the UserPromptSubmit hook lets the objective through, the engine reads a path entry with the Read
+ *   tool's own read (`ModelFileReader.readForModel`) under the run's synthetic-Read judge, or takes the host's bytes →
+ *   it mints ONE message per attachment that trails the human message: an engine note whose marked blocks hold only
+ *   static sentences and whose data (the name or path, then the contents or the refusal) sits between them → the
+ *   message's delivery record (`UserMessage.attachment`) is the one source of "what was delivered".
+ *
+ * This module owns the three steps no other module may repeat: the screen (`screenUserAttachments`), the mint
+ * (`readUserAttachments` → the frame seeds, the `human_input` projection and the pending commits) and the settlement
+ * (`createAttachmentDelivery`: a read's effects commit when its frame reaches the transcript, keyed by
+ * `(inputId, ordinal)` — never at read time, never by text).
+ *
+ * The frame, per attachment (blocks in order):
+ *   <system-reminder mark="…">\n<opening sentence>\n</system-reminder>\n     — static, the attachment's number only
+ *   Path: "<declared path>"\n   or   Name: "<name>"\n                           — data (lossless quoted label)
+ *   <data blocks>                                                             — the file's own blocks / the refusal
+ *   \n\n<system-reminder mark="…">\n<note sentence>\n</system-reminder>      — one per engine note, static
+ *   \n\n<system-reminder mark="…">\nEnd of attachment <n>.\n</system-reminder>
+ * Every marked block after data opens after a blank line (`MARKED_BLOCK_AFTER_DATA`): the completions lanes join a
+ * message's text blocks with no separator.
+ */
+import type { ImageContent, TextContent, UserAttachmentSupply, UserMessageAttachment } from "../internal/llm.js";
+import type { HumanInputAttachment } from "./task-event.js";
+import { type ModelFileReader } from "../tools/fs/fs-read.js";
+import type { SyntheticReadJudge } from "./synthetic-read-verdict.js";
+import { type ReminderDisclosureCounts } from "./reminder-disclosure.js";
+/** At most this many attachments on one objective. */
+export declare const USER_ATTACHMENTS_MAX = 20;
+/** The longest path or name an entry may carry (the platform path limit). */
+export declare const USER_ATTACHMENT_LABEL_MAX = 4096;
+/** What the engine found an attachment to be (an output, never declared): the Read lanes, a directory, host bytes. */
+export declare const USER_ATTACHMENT_KINDS: readonly ["text", "notebook", "image", "pdf", "directory", "client_text", "client_image"];
+/** Who held the bytes — the entry's arm. */
+export declare const USER_ATTACHMENT_SUPPLIES: readonly ["path", "content_text", "content_image"];
+/** What reached the model of an attachment's contents — the Read layer's own outcome words, the same frozen array. */
+export declare const USER_ATTACHMENT_OUTCOMES: readonly ["attached", "partial", "unchanged", "not_attached"];
+/**
+ * The seat's capability descriptor — what a host reads to decide, per attachment, whether to declare it here: its kind
+ * is in `kinds` and its arm in `supplies` ⇒ declare it on the objective; otherwise (a kind this seat does not carry, or
+ * an engine without the descriptor) the host carries it some other way. `entries`: the objective only — a steer carries
+ * no attachments (they go with the next objective).
+ */
+export declare const USER_ATTACHMENT_SEAT: Readonly<{
+    entries: readonly ["objective"];
+    kinds: readonly ["text", "notebook", "image", "pdf", "directory", "client_text", "client_image"];
+    supplies: readonly ["path", "content_text", "content_image"];
+    limits: Readonly<{
+        maxEntries: 20;
+        maxRenderedTextChars: 100000;
+    }>;
+}>;
+/** One declaration as the door captured it: the caller's object read once, members copied. */
+export type ScreenedUserAttachment = {
+    readonly supply: "path";
+    readonly path: string;
+    readonly lines?: {
+        readonly start: number;
+        readonly end?: number;
+    };
+} | {
+    readonly supply: "content_text";
+    readonly name: string;
+    readonly text: string;
+    readonly startLine: number;
+    readonly rendered: string;
+} | {
+    readonly supply: "content_image";
+    readonly name: string;
+    readonly data: string;
+    readonly mimeType: string;
+};
+/** The door's refusal: one code, the field named first. */
+export declare function userAttachmentRefusal(field: string, detail: string): Error & {
+    code: "config.user_attachment_invalid";
+};
+/**
+ * The door: screen the seat's value (synchronous; the caller's object is read once, member by member, before the
+ * first await of the run). `undefined` / an empty array ⇒ no attachments. `resumeLeg`: a durable resume mints no new
+ * human message, so any entry there is refused. Throws `config.user_attachment_invalid` naming the field.
+ */
+export declare function screenUserAttachments(seat: unknown, opts: {
+    resumeLeg: boolean;
+}): readonly ScreenedUserAttachment[] | undefined;
+/** A path entry on a run with no workspace: there is nothing the engine could read it from. */
+export declare function refuseUserAttachmentPathsWithoutWorkspace(screened: readonly ScreenedUserAttachment[] | undefined): void;
+/** One declared attachment as the UserPromptSubmit hook sees it (`UserPromptSubmitContext.userAttachments`). */
+export interface UserAttachmentDeclaration {
+    /** 1-based position among the objective's attachments. */
+    readonly ordinal: number;
+    /** Who holds the bytes: `path` (the engine reads it), `content_text` / `content_image` (the host sent them). */
+    readonly supply: UserAttachmentSupply;
+    readonly path?: string;
+    readonly name?: string;
+    /** A host entry's size in bytes (text as UTF-8, an image decoded). */
+    readonly bytes?: number;
+}
+/** The UserPromptSubmit hook's view of the declarations. */
+export declare function userAttachmentDeclarations(screened: readonly ScreenedUserAttachment[]): readonly UserAttachmentDeclaration[];
+/**
+ * The host images' byte admission — the one function an image the Read tool serves passes. Asynchronous (it decodes),
+ * run on the captured values before any attachment is read or delivered. Throws `config.user_attachment_invalid`.
+ */
+export declare function admitUserAttachmentImages(screened: readonly ScreenedUserAttachment[]): Promise<ReadonlyMap<number, ImageContent>>;
+/** One minted frame: the trailing message's seed, and the commit its delivery owes (absent ⇒ nothing to commit). */
+export interface MintedAttachmentFrame {
+    readonly seed: {
+        readonly content: ReadonlyArray<TextContent | ImageContent>;
+        readonly attachment: UserMessageAttachment;
+    };
+    readonly commit?: () => void;
+}
+export interface ReadUserAttachmentsInput {
+    screened: readonly ScreenedUserAttachment[];
+    /** The human input the attachments belong to (minted before the frames and the event, shared by both). */
+    inputId: string;
+    /** The leg's one file reader (absent on a run without a workspace — then only host entries exist). */
+    reader: ModelFileReader | undefined;
+    /** The run's synthetic-Read judge. */
+    judge: SyntheticReadJudge;
+    /** The admitted host images, by ordinal. */
+    images: ReadonlyMap<number, ImageContent>;
+    /** The tracked working directory a relative path resolves against (the Read tool's own). */
+    cwd: string | undefined;
+    mark: string | undefined;
+    counts: ReminderDisclosureCounts | undefined;
+    signal: AbortSignal;
+}
+/**
+ * Read every declared attachment and mint its frame. Side-effect free toward the run: nothing is committed here — each
+ * frame carries the commit its delivery owes, run only when the frame is in the transcript.
+ */
+export declare function readUserAttachments(input: ReadUserAttachmentsInput): Promise<MintedAttachmentFrame[]>;
+/** The objective lane's read: once the UserPromptSubmit hook let the objective through (a blocked objective reads
+ *  nothing), and before the pre-call gate, which prices the frames (`chars`). Commits nothing. */
+export declare function readObjectiveAttachments(prepared: Pick<import("./runner/contracts.js").Prepared, "userAttachments" | "modelFileReader" | "syntheticReadVerdict" | "cwdRef" | "reminderMark" | "reminderDisclosureCounts" | "abortController">, inputId: string, blocked: boolean): Promise<{
+    frames: MintedAttachmentFrame[];
+    chars: number;
+}>;
+/** The last attachment frame of the group the message `id` opens, or `id` when it has none (a `resumeAt` that keeps the
+ *  message keeps its group). The frames of one input are appended one after another under its message (each the child of
+ *  the one before), all carrying its input id. */
+export declare function lastAttachmentFrameOf(entries: ReadonlyArray<{
+    id: string;
+    parentId: string | null;
+    type: string;
+    message?: unknown;
+}>, id: string): string;
+/** The `human_input` projection of the minted frames. */
+export declare function humanInputAttachmentsOf(frames: readonly MintedAttachmentFrame[]): HumanInputAttachment[];
+/**
+ * The run's pending attachment commits, keyed by `(inputId, ordinal)`. A frame's commit runs exactly once, when the
+ * harness reports that frame in the transcript; a frame that never got there (a refused pre-call budget, an abort, a
+ * failed append) commits nothing — its entry is simply never settled.
+ */
+export interface AttachmentDelivery {
+    /** Stage the minted frames of one input — called only once every gate before the append has passed. */
+    stage(inputId: string, frames: readonly MintedAttachmentFrame[]): void;
+    /** The frame `(inputId, ordinal)` is in the transcript: run its commit (once) and forget it. */
+    settle(inputId: string, ordinal: number): void;
+}
+export declare function createAttachmentDelivery(): AttachmentDelivery;