@sema-agent/core 7.49.5 → 7.50.0

package/dist/core/shell-read-silence.d.ts

@@ -0,0 +1,23 @@
+import type { ShellReadVerdict } from "../tools/fs/shell-read-check.js";
+import type { GatePass } from "./runner/gate-exit.js";
+import type { AskGuard } from "./tool-policy.js";
+/** Whose silence a station's answer carries, each its own class on the question it keeps or mints: unread rows are a rule that could
+ *  not be read (the rule lane's class); the finding `unanswered` is, unless rows are unread, the environment's silence — shell text the
+ *  engine cannot read (a guard) — and the marks only pick whose. Either is a question only a person answers; `probe` follows the finding. */
+export declare function silencedBy(verdict: ShellReadVerdict, d: {
+    readonly guards?: readonly AskGuard[];
+    readonly ruleUnreadable?: unknown;
+}): {
+    ruleUnreadable?: "persisted_rows";
+    guards?: readonly AskGuard[];
+    requiresRealApproval?: true;
+};
+/** The finding `unanswered` IS the silence, applied once, before any disposition arm: a station — a host-mounted one included — may
+ *  spell `vouch` or `mandated` beside it, and neither word vouches for what nobody judged. A deny stands; an ask keeps its words and
+ *  gains the silence's class; an allow becomes the silence's question (`ask.message`), one only a person answers. Nothing is admitted,
+ *  no `probe` is stamped and no grant is offered — the station made no finding. */
+export declare function applyUnansweredSilence(pass: GatePass, verdict: ShellReadVerdict, ask: {
+    readonly message: string;
+    readonly account: string | undefined;
+    readonly tightenedBy: "shell_gate" | "safety";
+}): void;

package/dist/core/shell-read-silence.js

@@ -0,0 +1,18 @@
+export function silencedBy(verdict, d) {
+    const environment = verdict.environmentSilent === true || (verdict.finding === "unanswered" && verdict.rowsUnread !== true);
+    const rows = verdict.rowsUnread === true && d.ruleUnreadable === undefined ? { ruleUnreadable: "persisted_rows" } : {};
+    const guards = environment && d.guards?.includes("unverifiable_shell_text") !== true ? { guards: [...(d.guards ?? []), "unverifiable_shell_text"] } : {};
+    return environment || verdict.rowsUnread === true ? { ...rows, ...guards, requiresRealApproval: true } : {};
+}
+export function applyUnansweredSilence(pass, verdict, ask) {
+    if (verdict.details !== undefined)
+        pass.shellReadDetails = verdict.details;
+    if (pass.decision.action === "ask") {
+        pass.decision = { ...pass.decision, ...silencedBy(verdict, pass.decision) };
+        return;
+    }
+    if (pass.decision.action !== "allow")
+        return;
+    pass.decision = { action: "ask", message: ask.message, decisionReason: "safety", ...silencedBy(verdict, {}), ...(ask.account !== undefined ? { probeReason: ask.account } : {}) };
+    pass.tightenedBy = ask.tightenedBy;
+}

package/dist/core/synthetic-read-verdict.d.ts

@@ -1,24 +1,40 @@
 /**
- * The synthetic-Read DENY judge — "would a `Read` of this file be refused outright?", asked without a call,
- * without an approver and without a hook. One judge, one set of layers, for every consumer that needs the
- * answer for a file the model did not itself ask to read (the changed-file notice today; a user's
- * attachment next). It answers in THREE states and never picks a direction:
+ * The synthetic-call judge — "would this call be refused outright?", asked without a model call, without an
+ * approver and without a hook. One judge, one set of layers, for every consumer that needs the answer for a file the
+ * model did not itself ask to touch. It has TWO FACES over one body (the layer walk below is written once):
+ *
+ *   READ  — a `Read` of a file the model did not ask for (the changed-file notice; a user's attachment). An ordinary
+ *           `ask` — a person's own ask rule — is not a refusal: the person who would answer it is the one asking.
+ *   WRITE — a `Write` of a path the engine itself writes in the background (the memory consolidation run). Every `ask`
+ *           is an objection here: nobody is present to answer it, so a layer that would ask a person refuses the write.
+ *
+ * It never picks a direction. The read face answers in FOUR states:
  *
  *   deny          — some layer refuses it;
- *   no_objection  — every layer it consulted answered and none refused (an `ask` is not a refusal);
- *   unanswerable  — no layer refused, and at least one could not answer (see the table below).
+ *   mandated_ask  — no layer refuses it, and some layer would put the read to a person no rule may answer for
+ *                   (the ask's own mandate reading, {@link ruleClearanceOf}: a real-approval demand, the deployment's
+ *                   own question, an ancestor's, a hook's; or an organization rule's ask) — the person who must
+ *                   answer is not necessarily the one asking;
+ *   no_objection  — every layer it consulted answered and none objected;
+ *   unanswerable  — no layer objected, and at least one could not answer (see the table below).
+ *
+ * The write face answers the same four, with `ask` in place of `mandated_ask`: any layer's ask, mandated or not.
  *
- * The CONSUMER decides where `unanswerable` goes: a notice that merely tells the model a file changed
- * reads it as no objection (the worst case is a notice about a file it then cannot re-read); a face that
- * would put a file's contents in front of the model reads it as a refusal.
+ * ONE PRECEDENCE on both faces: a deny anywhere wins over a held ask, and a held ask over an unanswerable layer; the walk
+ * goes on past an ask (a later layer's deny is the stronger answer). The faces differ only in which asks are held. The
+ * CONSUMER decides where `mandated_ask` and `unanswerable` go: a notice that merely tells the model a file changed reads
+ * both as no objection (the worst case is a notice about a file it then cannot re-read); a face that would put a file's
+ * contents in front of the model reads both as a refusal; a background write reads everything but `no_objection` as a
+ * refusal. Every answer but `unanswerable` names the location the layers judged (`judged`, the canonical view of the
+ * stamped target, when a stamp was taken), so a consumer that resolved the file itself can tell the judged file from the
+ * one it opens.
  *
- * THE LAYERS (every one that can refuse a model's own `Read`): the run's skill deny rows; the
+ * THE LAYERS (every one that can refuse a model's own call): the run's skill deny rows; the
  * deny-narrowing fold (session rules, inherited ancestor rules, frozen constraint projections); the
  * deployment's caller policy; each live inherited parent policy; the person's persisted-rule lane; the org
- * lane. Not consulted, by design: PreToolUse hooks (the deployment's screening of a model's CALL), the
- * permission mode's write gate and the integrity guards (neither refuses a read), and the read-deny table
- * and containment roots (the path's own resolution judges those before this judge is asked). A deny
- * anywhere wins over an unanswerable layer elsewhere.
+ * lane. Not consulted, by design: PreToolUse hooks (the deployment's screening of a model's CALL), the permission mode's write
+ * gate, the integrity guards and the write-protection table (a live `Write` meets them; the read face never needs them and the
+ * write face's background run is not asked), and the read-deny table and containment roots (the path's own resolution judges those first).
  *
  * FAULT → STATE (the live gate's own readings, through the same functions — never a second copy):
  *   | layer                       | fault                                                | state                         |
@@ -28,11 +44,13 @@
  *   | caller / inherited policy   | its deny carries an engine settlement (an approval   | unanswerable `approval_seat`  |
  *   |                             | seat that ended unanswered; in a combinePolicies     |                               |
  *   |                             | composition a rule deny anywhere is returned instead)|                               |
- *   | persisted lane              | store unreadable, throws, times out (readPersistedRuleLane ⇒ `{unreadable}`) | its rows take no part |
+ *   | persisted lane              | a store partition (or all of it) is unreadable, the lane throws, times out (readPersistedRuleLane ⇒ `{unreadable}`) | unanswerable `store_unreadable` (both faces: a row nobody could read may forbid the call) |
  *   | persisted lane              | the call cannot be read against the rows (`reason`) — applyPersistedTightening ⇒ `unreadable` | unanswerable `call_unreadable` |
  *   | org lane                    | unavailable: throws, garbage (readOrgRuleLane)       | unanswerable `org_unavailable` |
+ *   | any policy layer            | answers with a rewrite of the arguments (`updatedInput`) | unanswerable `rewritten`  |
+ *   | inherited parent policy     | answers `ask` (the ancestor's approver's question)    | mandated_ask (write: ask)     |
  *   | any layer                   | the judgment's budget (one dependency timeout, or a  | unanswerable `timed_out`      |
- *   |                             | batch's shared deadline) is spent                    | (persisted: rows take no part)|
+ *   |                             | batch's shared deadline) is spent                    |                               |
  *
  * NEVER AN APPROVER. A deployment policy (the caller's, an inherited parent's) is consulted with an
  * ALREADY-ABORTED signal and no approver seat: the `ToolPolicy.check` contract is that an aborted signal
@@ -45,32 +63,50 @@
  * the notice face stays silent. The engine's own layers (narrowing, skill rows, the two lanes) get the
  * run's real signal: they are pure matchers and store reads.
  *
- * THE PROBE'S IDENTITY. Every layer sees `toolName: "Read"`, the probed arguments, and the stable synthetic
- * call id `<face>-visibility-probe` ({@link syntheticReadProbeId}), so a deployment's audit can tell a
- * visibility probe from a model's call.
+ * THE PROBE'S IDENTITY. Every layer sees the probed tool's name (`Read` / `Write`), the probed arguments, and a stable
+ * synthetic call id (`<face>-visibility-probe` for a read, `<face>-write-probe` for a write; {@link syntheticReadProbeId},
+ * {@link syntheticWriteProbeId}), so a deployment's audit can tell a probe from a model's call. The write face stamps the
+ * facts the live gate stamps on a write (the roster's `Write` face, the tracked cwd and root, the advertised writable
+ * directories, the data root's exemption): a containment fence and a data-root exemption judge the probe as they judge the call.
  */
 import type { ToolCallRequest, ToolCallFace, ToolPolicy } from "./tool-policy.js";
-import type { CallTargetStamp } from "./effective-path-target.js";
+import { type CallTargetStamp } from "./effective-path-target.js";
 import { type SkillGrantLane } from "./skill-grant.js";
 import type { OrgGateVerdict, PersistedRuleAnswer } from "./hooks.js";
 /** The layers the judge consults, as named in its verdicts. */
 export declare const SYNTHETIC_READ_LAYERS: readonly ["skill_rows", "narrowing", "caller_policy", "inherited_constraint", "persisted_rules", "org_rules"];
 export type SyntheticReadLayer = (typeof SYNTHETIC_READ_LAYERS)[number];
 /** Why a layer could not answer — the consumer's disclosure word. */
-export declare const SYNTHETIC_READ_UNANSWERABLE_CAUSES: readonly ["threw", "timed_out", "approval_seat", "call_unreadable", "org_unavailable"];
+export declare const SYNTHETIC_READ_UNANSWERABLE_CAUSES: readonly ["threw", "timed_out", "approval_seat", "call_unreadable", "org_unavailable", "rewritten", "store_unreadable"];
 export type SyntheticReadUnanswerableCause = (typeof SYNTHETIC_READ_UNANSWERABLE_CAUSES)[number];
 export type SyntheticReadVerdict = {
     verdict: "deny";
     layer: SyntheticReadLayer;
     message?: string;
+    judged?: string;
+} | {
+    verdict: "mandated_ask";
+    layer: SyntheticReadLayer;
+    message?: string;
+    judged?: string;
 } | {
     verdict: "no_objection";
+    judged?: string;
 } | {
     verdict: "unanswerable";
     layer: SyntheticReadLayer;
     cause: SyntheticReadUnanswerableCause;
     reason: string;
 };
+/** The write face's answer: the read face's states with `ask` — any layer's ask, mandated or not — in place of `mandated_ask`. */
+export type SyntheticWriteVerdict = Exclude<SyntheticReadVerdict, {
+    verdict: "mandated_ask";
+}> | {
+    verdict: "ask";
+    layer: SyntheticReadLayer;
+    message?: string;
+    judged?: string;
+};
 export interface SyntheticReadLayers {
     skillGrants?: Pick<SkillGrantLane, "denying">;
     denyNarrowingPolicy?: ToolPolicy;
@@ -97,9 +133,27 @@ export interface SyntheticReadCall {
     /** The live roster's face for `Read`, when the consumer has one. */
     face?: ToolCallFace;
 }
+/** The path a synthetic `Write` probes. The request's other facts come from the judge's {@link SyntheticWriteFacts}. */
+export interface SyntheticWriteCall {
+    file_path: string;
+}
+/** The facts the live gate stamps on a write, read at the moment of each judgment (the leg's cells move: the tracked cwd,
+ *  the advertised-directory ledger). Every member is optional — a leg without hands has no roster face, cwd or root. */
+export interface SyntheticWriteFacts {
+    /** The live roster's face for `Write` (a containment fence admits a write only by the tool's own declared path target). */
+    face?: ToolCallFace | undefined;
+    cwd?: string | undefined;
+    root?: string | undefined;
+    advertisedWritableDirs?: {
+        readonly roots: readonly string[];
+    } | undefined;
+    exemptRoots?: readonly string[] | undefined;
+}
 /** The stable synthetic call id a probe carries: `<face>-visibility-probe`, `face` a lowercase word
  *  (letters and hyphens) naming the consumer. */
 export declare function syntheticReadProbeId(face: string): string;
+/** The write face's stable synthetic call id: `<face>-write-probe`, `face` the same lowercase word. */
+export declare function syntheticWriteProbeId(face: string): string;
 /** One judgment's wait budget. `deadlineAt` (epoch ms) bounds the WHOLE judgment — every layer waits at most
  *  what is left of it, and a layer reached after it has passed is not consulted (`timed_out`). Absent ⇒ the
  *  dependency timeout from the start of this judgment. A consumer judging a batch passes one shared deadline,
@@ -108,4 +162,9 @@ export interface SyntheticReadBudget {
     deadlineAt?: number;
 }
 export type SyntheticReadJudge = (call: SyntheticReadCall, face: string, budget?: SyntheticReadBudget) => Promise<SyntheticReadVerdict>;
+export type SyntheticWriteJudge = (call: SyntheticWriteCall, face: string, budget?: SyntheticReadBudget) => Promise<SyntheticWriteVerdict>;
+/** The READ face: only a mandated ask is held (a person's own ask is that person's question). */
 export declare function createSyntheticReadJudge(layers: SyntheticReadLayers): SyntheticReadJudge;
+/** The WRITE face: every ask is held as an objection (no approver is present), and a persisted store that cannot be read is
+ *  unanswerable rather than silent. */
+export declare function createSyntheticWriteJudge(layers: SyntheticReadLayers, facts: () => SyntheticWriteFacts): SyntheticWriteJudge;

package/dist/core/synthetic-read-verdict.js

@@ -1,20 +1,36 @@
-import { attestationOf, describeThrown, refuseOutOfContractDecision } from "./tool-policy.js";
+import { callTargetReadingOf } from "./effective-path-target.js";
+import { advertisedWritableRootsSeat, attestationOf, describeThrown, exemptRootsSeat, refuseOutOfContractDecision } from "./tool-policy.js";
+import { ownedClearanceFacts, ruleClearanceOf } from "./ask-origin.js";
 import { skillRowRefusal } from "./skill-grant.js";
 import { applyPersistedTightening } from "./persisted-rule-arms.js";
 import { readOrgRuleLane, readPersistedRuleLane } from "./rule-lane-reads.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, settleOrgVerdictWithin } from "./permission-rule-org.js";
+import { deepJsonEqual } from "./runner/decide-continuation.js";
 export const SYNTHETIC_READ_LAYERS = Object.freeze(["skill_rows", "narrowing", "caller_policy", "inherited_constraint", "persisted_rules", "org_rules"]);
-export const SYNTHETIC_READ_UNANSWERABLE_CAUSES = Object.freeze(["threw", "timed_out", "approval_seat", "call_unreadable", "org_unavailable"]);
+export const SYNTHETIC_READ_UNANSWERABLE_CAUSES = Object.freeze(["threw", "timed_out", "approval_seat", "call_unreadable", "org_unavailable", "rewritten", "store_unreadable"]);
 export function syntheticReadProbeId(face) {
+    return `${probeFaceWord(face)}-visibility-probe`;
+}
+export function syntheticWriteProbeId(face) {
+    return `${probeFaceWord(face)}-write-probe`;
+}
+function probeFaceWord(face) {
     if (!/^[a-z][a-z-]*$/.test(face))
-        throw new Error(`syntheticReadProbeId: the probe face must be a lowercase word (letters and hyphens), got ${JSON.stringify(face)}`);
-    return `${face}-visibility-probe`;
+        throw new Error(`synthetic probe id: the probe face must be a lowercase word (letters and hyphens), got ${JSON.stringify(face)}`);
+    return face;
 }
 const ABORTED = AbortSignal.abort();
+function sameArguments(value, probed) {
+    try {
+        return deepJsonEqual(value, probed);
+    }
+    catch {
+        return false;
+    }
+}
 export function createSyntheticReadJudge(layers) {
+    const judge = createProbeJudge(layers, "read");
     return async (call, face, budget) => {
-        const deadlineAt = budget?.deadlineAt ?? Date.now() + ORG_ADJUDICATION_TIMEOUT_MS;
-        const left = () => Math.max(0, Math.min(ORG_ADJUDICATION_TIMEOUT_MS, deadlineAt - Date.now()));
         const probe = {
             toolName: "Read",
             args: { file_path: call.file_path, ...(call.offset !== undefined ? { offset: call.offset } : {}), ...(call.limit !== undefined ? { limit: call.limit } : {}) },
@@ -22,32 +38,76 @@ export function createSyntheticReadJudge(layers) {
             ...(call.cwd !== undefined ? { cwd: call.cwd } : {}),
             ...(call.face !== undefined ? { face: call.face } : {}),
         };
+        const v = await judge(probe, budget);
+        return v.verdict === "ask" ? { ...v, verdict: "mandated_ask" } : v;
+    };
+}
+export function createSyntheticWriteJudge(layers, facts) {
+    const judge = createProbeJudge(layers, "write");
+    return async (call, face, budget) => {
+        const f = facts();
+        const probe = {
+            toolName: "Write",
+            args: { file_path: call.file_path, content: "" },
+            toolCallId: syntheticWriteProbeId(face),
+            ...(f.cwd !== undefined ? { cwd: f.cwd } : {}),
+            ...(f.root !== undefined ? { root: f.root } : {}),
+            ...(f.face !== undefined ? { face: f.face } : {}),
+            ...advertisedWritableRootsSeat(f.advertisedWritableDirs),
+            ...(f.exemptRoots !== undefined ? exemptRootsSeat(f.exemptRoots) : {}),
+        };
+        return judge(probe, budget);
+    };
+}
+function createProbeJudge(layers, kind) {
+    const everyAskHeld = kind === "write";
+    return async (probe, budget) => {
+        const deadlineAt = budget?.deadlineAt ?? Date.now() + ORG_ADJUDICATION_TIMEOUT_MS;
+        const left = () => Math.max(0, Math.min(ORG_ADJUDICATION_TIMEOUT_MS, deadlineAt - Date.now()));
+        const probedArgs = structuredClone(probe.args);
         const stamped = layers.stampCallTarget?.(probe, layers.signal);
         const req = stamped !== undefined ? await stamped : probe;
+        const view = callTargetReadingOf(req)?.protective;
+        const judged = view?.kind === "path" && view.canonical !== undefined ? { judged: view.canonical } : {};
         let unanswered;
+        let held;
         const cannot = (layer, cause, reason) => {
             unanswered ??= { verdict: "unanswerable", layer, cause, reason };
         };
+        const ask = (layer, message, mandated) => {
+            if (everyAskHeld || mandated)
+                held ??= { verdict: "ask", layer, ...(message !== undefined ? { message } : {}), ...judged };
+        };
         const spent = (layer) => {
             if (left() > 0)
                 return false;
             cannot(layer, "timed_out", "the judgment's wait budget was spent before this layer was asked");
             return true;
         };
-        const policyLayer = async (layer, policy, signal) => {
+        const policyLayer = async (layer, policy, signal, ancestorOwned = false) => {
             if (spent(layer))
                 return undefined;
             const waitMs = left();
             let timedOut = false;
+            let thrown = undefined;
             const TIMEOUT = Symbol("timeout");
             let d;
             try {
-                d = await settleOrgVerdictWithin(Promise.resolve().then(() => policy.check(req, signal)), TIMEOUT, { ...(layers.signal !== undefined ? { signal: layers.signal } : {}), timeoutMs: waitMs, onFallback: () => void (timedOut = true) });
+                d = await settleOrgVerdictWithin(Promise.resolve()
+                    .then(() => policy.check(req, signal))
+                    .catch((err) => {
+                    thrown = { err };
+                    return TIMEOUT;
+                }), TIMEOUT, { ...(layers.signal !== undefined ? { signal: layers.signal } : {}), timeoutMs: waitMs, onFallback: () => void (timedOut = true) });
             }
             catch (err) {
                 cannot(layer, "threw", describeThrown(err));
                 return undefined;
             }
+            if (thrown !== undefined) {
+                cannot(layer, "threw", describeThrown(thrown.err));
+                return undefined;
+            }
             if (d === TIMEOUT || timedOut) {
                 cannot(layer, "timed_out", `no answer within ${waitMs}ms (or the run ended first)`);
                 return undefined;
@@ -60,18 +120,25 @@ export function createSyntheticReadJudge(layers) {
                 cannot(layer, "threw", describeThrown(err));
                 return undefined;
             }
+            if (read.action !== "deny" && ((read.updatedInput !== undefined && !sameArguments(read.updatedInput, probedArgs)) || !sameArguments(req.args, probedArgs))) {
+                cannot(layer, "rewritten", "the layer would rewrite the call's arguments, so its answer is not about this call");
+            }
+            if (read.action === "ask") {
+                ask(layer, read.message, ancestorOwned || ruleClearanceOf(ownedClearanceFacts(read), {}).mandated);
+                return undefined;
+            }
             if (read.action !== "deny")
                 return undefined;
             if (attestationOf(read, req)?.settlement !== undefined) {
-                cannot(layer, "approval_seat", "the policy would ask an approver, who is never consulted for a visibility probe");
+                cannot(layer, "approval_seat", "the policy would ask an approver, who is never consulted for a synthetic probe");
                 return undefined;
             }
-            return { verdict: "deny", layer, ...(read.message !== undefined ? { message: read.message } : {}) };
+            return { verdict: "deny", layer, ...(read.message !== undefined ? { message: read.message } : {}), ...judged };
         };
         try {
             const refusal = skillRowRefusal(layers.skillGrants, req);
             if (refusal !== undefined)
-                return { verdict: "deny", layer: "skill_rows", ...(refusal.message !== undefined ? { message: refusal.message } : {}) };
+                return { verdict: "deny", layer: "skill_rows", ...(refusal.message !== undefined ? { message: refusal.message } : {}), ...judged };
         }
         catch (err) {
             cannot("skill_rows", "threw", describeThrown(err));
@@ -82,14 +149,14 @@ export function createSyntheticReadJudge(layers) {
                 return v;
         }
         if (layers.callerPolicy !== undefined) {
-            const v = await policyLayer("caller_policy", layers.callerPolicy, ABORTED);
+            const v = await policyLayer("caller_policy", layers.callerPolicy, ABORTED, (layers.inheritedPolicies ?? []).includes(layers.callerPolicy));
             if (v !== undefined)
                 return v;
         }
         for (const parent of layers.inheritedPolicies ?? []) {
             if (parent === layers.callerPolicy)
                 continue;
-            const v = await policyLayer("inherited_constraint", parent, ABORTED);
+            const v = await policyLayer("inherited_constraint", parent, ABORTED, true);
             if (v !== undefined)
                 return v;
         }
@@ -97,17 +164,21 @@ export function createSyntheticReadJudge(layers) {
             const read = await readPersistedRuleLane(layers.persistedRuleLane, req, layers.signal, left());
             const tightened = applyPersistedTightening({ action: "allow" }, read).tightened;
             if (tightened === "deny")
-                return { verdict: "deny", layer: "persisted_rules" };
-            if (tightened === "unreadable")
-                cannot("persisted_rules", "call_unreadable", read.reason ?? "the call could not be read against the rules");
+                return { verdict: "deny", layer: "persisted_rules", ...judged };
+            if (tightened === "ask")
+                ask("persisted_rules", undefined, false);
+            if (read.unreadable === true)
+                cannot("persisted_rules", read.reason !== undefined ? "call_unreadable" : "store_unreadable", read.reason ?? "a partition of the person's rule store could not be read, so whether a standing rule forbids this call is unknown");
         }
         if (layers.orgRuleLane !== undefined && !spent("org_rules")) {
             const org = await readOrgRuleLane(layers.orgRuleLane, req, layers.signal, left());
             if (org.status === "unavailable")
                 cannot("org_rules", left() > 0 ? "org_unavailable" : "timed_out", org.disclosures.join("; ") || "organization governance could not be read");
             else if (org.verdict?.behavior === "deny")
-                return { verdict: "deny", layer: "org_rules", message: `an organization policy rule (${org.verdict.rule}) denies it` };
+                return { verdict: "deny", layer: "org_rules", message: `an organization policy rule (${org.verdict.rule}) denies it`, ...judged };
+            else if (org.verdict?.behavior === "ask")
+                ask("org_rules", `an organization policy rule (${org.verdict.rule}) requires approval for it`, true);
         }
-        return unanswered ?? { verdict: "no_objection" };
+        return held ?? unanswered ?? { verdict: "no_objection", ...judged };
     };
 }

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):