@sema-agent/core 7.10.0 → 7.11.1

package/dist/core/runner/stream-steer-verb.js

@@ -0,0 +1,185 @@
+import { uuidv7 } from "../../internal/harness.js";
+import { snapshotActorAssertion } from "../../internal/llm.js";
+import { LEGACY_PENDING_STEER_INPUT_ID, MAX_STEER_INPUT_ID_CHARS } from "../checkpoint-store.js";
+import { formatHookFeedback, hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { buildHumanInputEvent, frameMidTurnUserInput, projectHumanInput } from "../human-input-projection.js";
+import { isSystemInjectionPriority, SYSTEM_INJECTION_PRIORITIES } from "../task-notification.js";
+import { deliverEngineNotice } from "../types.js";
+import { inlineUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
+import { nextHumanInputSeq, sameAcceptedSteerInput } from "./steer-admission.js";
+export function streamSteerVerb(input) {
+    const { spec, internals, queue, acceptedSteerInputs, live, ready, orTimeout, readyTimeoutMs: READY_TIMEOUT_MS, steeringError, runner } = input;
+    let steerChain = Promise.resolve();
+    const steer = async (text, options) => {
+        const trusted = options?.trusted ? true : false;
+        if (trusted && sanitizeUntrustedText(text) !== text) {
+            throw steeringError("trusted steering text must not contain a </system-reminder> tag", "steering.invalid_content");
+        }
+        const inputId = options?.inputId;
+        if (inputId !== undefined) {
+            if (typeof inputId !== "string") {
+                throw steeringError("inputId must be a string when supplied", "steering.invalid_content");
+            }
+            if (inputId === "" || inputId.length > MAX_STEER_INPUT_ID_CHARS) {
+                throw steeringError(`inputId must be a non-empty string of at most ${MAX_STEER_INPUT_ID_CHARS} characters`, "steering.invalid_content");
+            }
+            if (inputId === LEGACY_PENDING_STEER_INPUT_ID) {
+                throw steeringError(`inputId "${LEGACY_PENDING_STEER_INPUT_ID}" is reserved for a pre-queue parked steer and cannot be supplied by a caller`, "steering.invalid_content");
+            }
+        }
+        const priorityIn = options?.priority;
+        if (priorityIn !== undefined && !isSystemInjectionPriority(priorityIn)) {
+            throw steeringError(`priority must be one of ${SYSTEM_INJECTION_PRIORITIES.join("/")} when supplied`, "steering.invalid_content");
+        }
+        const priority = priorityIn ?? "next";
+        const actorIn = options?.actor;
+        const actor = actorIn === undefined ? undefined : snapshotActorAssertion(actorIn);
+        const projected = projectHumanInput({ text, actor, source: "steer" });
+        const effectiveInputId = typeof inputId === "string" ? inputId : uuidv7();
+        const parkRecord = {
+            text,
+            trusted,
+            inputId: effectiveInputId,
+            ...(priorityIn !== undefined ? { priority } : {}),
+            ...(actor !== undefined ? { actor } : {}),
+        };
+        let payload;
+        let mintsAFrame;
+        let replay;
+        const noteAccepted = (h) => {
+            if (!mintsAFrame)
+                return;
+            if (typeof inputId === "string")
+                acceptedSteerInputs.set(inputId, replay);
+            queue.push({
+                ...buildHumanInputEvent({
+                    carrier: "steer",
+                    source: "steer",
+                    delivery: "queued",
+                    sessionSeq: nextHumanInputSeq(h.harness),
+                    inputId: effectiveInputId,
+                    ...(actor !== undefined ? { actor } : {}),
+                    ...(actor?.issuer !== undefined ? { issuer: actor.issuer } : {}),
+                    ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+                }),
+                eventId: uuidv7(),
+                ...(internals?.parentToolCallId !== undefined
+                    ? { parentToolCallId: internals.parentToolCallId, ...(spec.taskId !== undefined ? { sourceTaskId: spec.taskId } : {}) }
+                    : {}),
+            });
+        };
+        const deliver = async () => {
+            if (live.resultValue)
+                throw steeringError("the task has already finished");
+            const h = live.handle ?? (await orTimeout(ready));
+            if (!h)
+                throw steeringError("the task is not running");
+            payload = trusted ? formatHookFeedback(projected, h.reminderMark) : frameMidTurnUserInput(projected);
+            mintsAFrame = payload.trim().length !== 0;
+            replay = { payload, trusted, priority, ...(actor !== undefined ? { actor } : {}) };
+            if (typeof inputId === "string") {
+                const prior = acceptedSteerInputs.get(inputId);
+                if (prior !== undefined) {
+                    if (live.resultValue !== undefined || h.loop.ended)
+                        throw steeringError("the task is no longer running");
+                    if (!sameAcceptedSteerInput(prior, replay)) {
+                        throw steeringError("a different steering instruction was already accepted under this inputId — re-issue this one with a fresh inputId " +
+                            "(an identical payload would have been an idempotent retry)", "steering.duplicate_input_id");
+                    }
+                    return;
+                }
+            }
+            if (live.resultValue !== undefined || h.loop.ended)
+                throw steeringError("the task is no longer running");
+            if (mintsAFrame) {
+                const screen = (spec.hooks ?? runner.deps.hooks)?.userPromptSubmit;
+                if (screen !== undefined) {
+                    let decision;
+                    try {
+                        const seat = await runHookSeat("userPromptSubmit", { timeoutMs: h.hookTimeoutMs, signal: h.abortController.signal, abortEnds: true }, (sig) => screen(text, { identity: h.hookIdentity, signal: sig, source: "steer", inputId: effectiveInputId, ...(actor !== undefined ? { actor: snapshotActorAssertion(actor) } : {}) }));
+                        if (seat.expired) {
+                            if (seat.cause === "timeout") {
+                                try {
+                                    runner.deps.onError?.(hookSeatExpiredError("userPromptSubmit", h.hookTimeoutMs, seat.cause, "the steering input was NOT accepted (fail-closed) and the caller was refused typed"), { phase: "hook", sessionId: h.sessionId });
+                                }
+                                catch {
+                                }
+                            }
+                            throw steeringError(seat.cause === "timeout"
+                                ? `the deployment's userPromptSubmit hook did not answer within its ${h.hookTimeoutMs}ms bound while screening this steering input; the input was NOT accepted (fail-closed)`
+                                : `the task was cancelled while the deployment's userPromptSubmit hook was still screening this steering input; the input was NOT accepted (fail-closed)`, "steering.blocked_by_hook");
+                        }
+                        decision = seat.value;
+                    }
+                    catch (hookErr) {
+                        if (hookErr instanceof Error && hookErr.code === "steering.blocked_by_hook")
+                            throw hookErr;
+                        const err = hookErr instanceof Error ? hookErr : new Error(String(hookErr));
+                        try {
+                            runner.deps.onError?.(err, { phase: "hook", sessionId: h.sessionId });
+                        }
+                        catch {
+                        }
+                        throw steeringError(`the deployment's userPromptSubmit hook crashed while screening this steering input (${inlineUntrusted(err.message)}); the input was NOT accepted (fail-closed)`, "steering.blocked_by_hook");
+                    }
+                    if (decision?.block !== undefined && decision.block !== "") {
+                        throw steeringError(`the deployment's userPromptSubmit hook blocked this steering input: ${inlineUntrusted(decision.block)}`, "steering.blocked_by_hook");
+                    }
+                    if (decision?.additionalContext !== undefined && decision.additionalContext !== "") {
+                        payload = `${formatHookFeedback(decision.additionalContext, h.reminderMark)}\n\n${payload}`;
+                    }
+                }
+            }
+            const injectFramed = async () => {
+                const noteOptions = { provenance: "engine-note", callerAuthored: true, parkRecord, ...(actor !== undefined ? { actor } : {}) };
+                if (priority === "later") {
+                    await h.harness.followUp(payload, noteOptions);
+                    noteAccepted(h);
+                    return;
+                }
+                const frame = await h.harness.steer(payload, { ...noteOptions, ...(priority === "now" ? { immediate: true } : {}) });
+                noteAccepted(h);
+                if (priority === "now" && frame !== undefined && h.harness.interruptTurn(frame)) {
+                    deliverEngineNotice(runner.deps.onNotice, {
+                        code: "task.turn_interrupted",
+                        message: "a caller-provenance steer with priority \"now\" interrupted the running turn: in-flight work was cut at " +
+                            "a manufactured boundary (finished tool calls keep their real results; never-started ones settle as " +
+                            "interrupted) and the run continues with the steer at the queue head.",
+                        detail: {
+                            inputId: effectiveInputId,
+                            sessionId: h.sessionId,
+                            runId: h.runId,
+                            ...(actor?.id !== undefined ? { actorId: actor.id } : {}),
+                            ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}),
+                        },
+                    });
+                }
+            };
+            try {
+                await injectFramed();
+                return;
+            }
+            catch (e) {
+                if (!(e instanceof Error && e.code === "invalid_state"))
+                    throw e;
+            }
+            const birthDeadline = Date.now() + READY_TIMEOUT_MS;
+            while (live.resultValue === undefined && !h.loop.ended && Date.now() < birthDeadline) {
+                try {
+                    await injectFramed();
+                    return;
+                }
+                catch (e2) {
+                    if (!(e2 instanceof Error && e2.code === "invalid_state"))
+                        throw e2;
+                }
+                await new Promise((r) => setTimeout(r, 10));
+            }
+            throw steeringError("the task is no longer running");
+        };
+        const p = steerChain.then(deliver);
+        steerChain = p.then(() => undefined, () => undefined);
+        return p;
+    };
+    return { steer };
+}

package/dist/core/shell-lexer.d.ts

@@ -9,10 +9,20 @@ export interface ShellWord {
      *  yield zero, one or several words. */
     readonly expands: false | "one" | "many";
 }
+/** One redirection of a segment, as read: the operator and its operand word (a heredoc's operand is its
+ *  delimiter; the IO number or `{name}` before the operator is folded into the operator's meaning and not
+ *  kept). The tightening reader never reads these — a rule speaks about program runs; the read-only
+ *  reader does (an output redirection is a write). */
+export interface ShellRedirection {
+    readonly op: string;
+    readonly target: ShellWord;
+}
 /** One program run the lexer found, after keyword stripping. */
 export interface ShellSegment {
     /** The run as SPELLED (a leading keyword removed): the first candidate a rule is compared against. */
     readonly argv: readonly ShellWord[];
+    /** The segment's redirections in source order (see {@link ShellRedirection}); empty when it has none. */
+    readonly redirections: readonly ShellRedirection[];
     /** The deeper candidates, one per peeled layer (leading assignments, then each wrapper of the table):
      *  `sudo -u root rm -r x` ⇒ `[[rm, -r, x]]`. Empty when nothing peeled. */
     readonly peeled: readonly (readonly ShellWord[])[];
@@ -34,6 +44,14 @@ export interface ShellCommandShape {
     /** A subshell, group, control-structure keyword or dropped empty piece bounded the segments: the
      *  connector list is not one flat chain a compound rule could spell. */
     readonly grouped: boolean;
+    /** A `&` connector anywhere — between two segments or after the last one (`ls &`): some segment runs in the
+     *  background, past any approval-time reading of the line. The connector list alone cannot say so for a
+     *  trailing `&` (a connector rides BETWEEN segments). */
+    readonly backgrounded: boolean;
+    /** A redirection on a piece that runs NO program (`> x` alone, `[ -f a ] > x`, a keyword's own redirection):
+     *  such a piece is dropped from `segments` (the tightening reader asks about program runs, and it runs
+     *  none) — but the shell still opens the target, so a reader that asks about EFFECTS must refuse the line. */
+    readonly strayRedirection: boolean;
 }
 export { SHELL_WRAPPER_TABLE, type ShellWrapperName } from "./shell-wrapper-table.js";
 /** Longer than this and the command is not read at all (one unreadable segment): every pass is linear,

package/dist/core/shell-lexer.js

@@ -13,11 +13,13 @@ const ALL_OPS = [...CONNECTOR_OPS, ...REDIRECT_OPS];
 export const MAX_SHELL_READ_CHARS = 10_000;
 export function readShellCommand(source) {
     if (source.length > MAX_SHELL_READ_CHARS)
-        return { segments: [{ argv: [], peeled: [], unreadable: `the command is longer than ${MAX_SHELL_READ_CHARS} characters — not read` }], connectors: [], grouped: false };
+        return { segments: [{ argv: [], redirections: [], peeled: [], unreadable: `the command is longer than ${MAX_SHELL_READ_CHARS} characters — not read` }], connectors: [], grouped: false, backgrounded: false, strayRedirection: false };
     const segments = [];
     const connectors = [];
     let grouped = false;
-    let seg = { words: [] };
+    let backgrounded = false;
+    let strayRedirection = false;
+    let seg = { words: [], redirections: [] };
     let word = freshWord();
     let pendingRedirect;
     let heredocs = [];
@@ -40,6 +42,7 @@ export function readShellCommand(source) {
                     badDelimiter = true;
                 heredocs.push({ delimiter: word.text, quoted: word.raw !== word.text, dash: pendingRedirect === "<<-" });
             }
+            seg.redirections.push({ op: pendingRedirect, target: publicWord(word) });
             pendingRedirect = undefined;
         }
         else {
@@ -56,17 +59,19 @@ export function readShellCommand(source) {
         let built = buildSegment(seg);
         if (built === "keyworded")
             grouped = true;
+        if ((built === "empty" || built === "keyworded") && seg.redirections.length > 0)
+            strayRedirection = true;
         if (built === "empty" || built === "keyworded") {
             const continuation = connector === "\n" && lastConnector !== undefined && lastConnector !== ";" && lastConnector !== "&" && lastConnector !== "\n";
             const legal = built === "keyworded" || afterBoundary || connector === undefined || connector === "\n" || lastConnector === "\n";
             if (!legal)
-                built = { argv: [], peeled: [], unreadable: `an empty command before \`${connector}\` — a syntax error` };
+                built = { argv: [], redirections: seg.redirections, peeled: [], unreadable: `an empty command before \`${connector}\` — a syntax error` };
             else {
                 if (connector !== undefined && connector !== "\n" && segments.length > 0)
                     grouped = true;
                 if (connector !== undefined && !continuation)
                     lastConnector = connector;
-                seg = { words: [] };
+                seg = { words: [], redirections: [] };
                 afterBoundary = false;
                 return;
             }
@@ -76,7 +81,7 @@ export function readShellCommand(source) {
         segments.push(built);
         if (connector !== undefined)
             lastConnector = connector;
-        seg = { words: [] };
+        seg = { words: [], redirections: [] };
         afterBoundary = false;
     };
     const boundary = () => { finishSegment(undefined); grouped = true; afterBoundary = true; lastConnector = undefined; };
@@ -187,6 +192,8 @@ export function readShellCommand(source) {
                     i += op.length;
                     continue;
                 }
+                if (op === "&")
+                    backgrounded = true;
                 finishSegment(op);
                 i += op.length;
                 continue;
@@ -271,7 +278,7 @@ export function readShellCommand(source) {
             seg.unreadable ??= `the connector \`${lastConnector}\` has no command after it — a syntax error`;
         finishSegment(undefined);
     }
-    return { segments, connectors, grouped };
+    return { segments, connectors, grouped, backgrounded, strayRedirection };
 }
 const publicWord = ({ text, raw, expands }) => ({ text, raw, expands });
 const SUBSTITUTION_UNREAD = "a command substitution runs a program this reader does not read";
@@ -281,8 +288,8 @@ export function isFullyReadable(shape) {
 }
 function buildSegment(seg) {
     if (seg.unreadable !== undefined)
-        return { argv: seg.words.map(publicWord), peeled: [], unreadable: seg.unreadable };
-    const carried = () => (seg.substitution === true ? { argv: [], peeled: [], peelUnreadable: SUBSTITUTION_UNREAD } : keyworded ? "keyworded" : "empty");
+        return { argv: seg.words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: seg.unreadable };
+    const carried = () => (seg.substitution === true ? { argv: [], redirections: seg.redirections, peeled: [], peelUnreadable: SUBSTITUTION_UNREAD } : keyworded ? "keyworded" : "empty");
     let keyworded = false;
     let k0 = 0;
     while (k0 < seg.words.length && seg.words[k0].expands === false && (PREFIX_KEYWORDS.has(seg.words[k0].text) || CLOSING_KEYWORDS.has(seg.words[k0].text))) {
@@ -298,7 +305,7 @@ function buildSegment(seg) {
     if (head.expands === false && (head.text === "[[" || head.text === "["))
         return carried();
     if (head.expands === false && OPAQUE_KEYWORDS.has(head.text))
-        return { argv: words.map(publicWord), peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
+        return { argv: words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
     const argv = words.map(publicWord);
     const peeled = [];
     let peelUnreadable;
@@ -338,7 +345,7 @@ function buildSegment(seg) {
     }
     if (seg.substitution === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(c)))
         peelUnreadable ??= SUBSTITUTION_UNREAD;
-    return { argv, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}) };
+    return { argv, redirections: seg.redirections, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}) };
 }
 function unwrap(words) {
     const head = words[0];

package/dist/core/shell-wrapper-table.js

@@ -50,9 +50,12 @@ export function evaluatesOperand(run) {
     return run.some((w) => namesArrayElement(w.text) || namesArrayElement(w.raw) || (integer && /^[A-Za-z_][A-Za-z0-9_]*\+?=.*[A-Za-z_$]/.test(w.text)));
 }
 function namesArrayElement(word) {
-    const open = word.indexOf("[");
-    if (open <= 0 || !/[A-Za-z0-9_]/.test(word[open - 1]))
-        return false;
-    const close = word.indexOf("]", open);
-    return close > 0 && /[A-Za-z_$]/.test(word.slice(open + 1, close));
+    for (let open = word.indexOf("["); open > 0; open = word.indexOf("[", open + 1)) {
+        if (!/[A-Za-z0-9_]/.test(word[open - 1]))
+            continue;
+        const close = word.indexOf("]", open);
+        if (close > 0 && /[A-Za-z_$]/.test(word.slice(open + 1, close)))
+            return true;
+    }
+    return false;
 }

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

@@ -99,7 +99,10 @@ export interface ToolCallRequest {
  *   - `"org_unavailable"` — an org-governed deployment could not adjudicate against a snapshot, so the
  *     whole decision boundary failed closed (see `ORG_UNAVAILABLE_DECISION_REASON`, the single
  *     spelling this word is minted from). */
-declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
+/** `read_only` (#619): the shell tool's command was PROVABLY read-only by the engine's transcribed upstream
+ *  tables (`readOnlyShellVerdict`) and the allow layer let it run without a question — after every
+ *  deny/ask lane and the person's own allow rules, never over a mandated ask. */
+declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 export type DecisionReason = (typeof DECISION_REASONS)[number];
 /** Read the engine-attested settlement off a funneled decision FOR the named call (the gate's exit is the
  *  one consumer): an attestation bound to a different call is a replayed object and answers absence.

package/dist/core/tool-policy.js

@@ -10,7 +10,7 @@ import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./unt
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
 import { protocolOf } from "./protocol-table.js";
 import { isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
-const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
+const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {
     return { kind, who: { party: "none" }, when: Date.now() };

package/dist/core/tools.d.ts

@@ -15,14 +15,34 @@ export declare function errorResult(text: string, details?: unknown): {
     isError: true;
     details?: unknown;
 };
-/** True iff `x` is an `AgentTool` this module's `defineTool` itself constructed — see {@link DEFINE_TOOL_BRAND}. */
+/** The seat's function: the mount's ctx builder and the very object being mounted (the seal compares it to the stamped one). */
+type DefineToolRebind = (enrich: ToolCtxEnricher, mounted: object) => AgentTool;
+/** True iff `x` is an `AgentTool` this module's `defineTool` itself constructed — see {@link DEFINE_TOOL_BRAND}.
+ *  An OWN property read: an object that merely INHERITS the brand (`Object.create(product)`, a Proxy over it)
+ *  is not the product — the rebind seat would rebuild the product and drop whatever the derived object
+ *  overrode, so such objects are not recognised here and fall to the spec arm's contract (which they do not
+ *  meet either; see {@link stampDefineToolBrand} for the one supported wrapper form). */
 export declare function isDefineToolProduct(x: unknown): x is AgentTool;
-/** RB-362 类修同源章点 — the ONE place the brand is stamped. `defineTool` uses it on its own product;
- *  the only OTHER legitimate caller is a wrapper that (a) starts from a branded product and (b)
- *  preserves the AgentTool `execute(toolCallId, rawParams, signal, onUpdate)` contract faithfully
- *  (e.g. teacher.ts's logging wrapper). A shallow copy that does NOT re-stamp deliberately loses the
- *  brand — that is the brand's documented survival contract, not an accident. Internal only. */
-export declare function stampDefineToolBrand<T extends object>(tool: T): T;
+/** RB-362 类修同源章点 — the ONE place the brand is stamped, and with it the rebind seat (a branded object
+ *  ALWAYS carries one; that invariant is what lets the caller mount rebind every product without a
+ *  "cannot enrich" arm). `defineTool` uses it on its own product; the only OTHER legitimate caller is a
+ *  wrapper that (a) starts from a branded product, (b) preserves the AgentTool
+ *  `execute(toolCallId, rawParams, signal, onUpdate)` contract faithfully and (c) hands over a `rebind`
+ *  that re-wraps the REBOUND inner product the same way (e.g. teacher.ts's logging wrapper) — so a mount
+ *  rebinding the wrapper gets a wrapper over an enriched product, not an enriched product without the
+ *  wrapper. A shallow copy that does NOT re-stamp deliberately loses the brand — that is the brand's
+ *  documented survival contract, not an accident. Internal only. */
+export declare function stampDefineToolBrand<T extends object>(tool: T, rebind: DefineToolRebind): T;
+/**
+ * A branded product REBOUND to a mount's ctx builder — the product's own `execute` rebuilt over its own
+ * spec with `enrich` applied per call (see {@link ToolCtxEnricher}; a builder the product was built with
+ * runs AFTER the mount's, refining the run's trusted seats, and the per-call identity is re-stamped after
+ * both). This is how a `defineTool()` product handed to `TaskSpec.tools` receives exactly the ctx a raw
+ * `ToolSpec` on the same mount receives: one mount law, whatever object shape the caller handed in.
+ * Throws on an unbranded object — the caller checks {@link isDefineToolProduct} first; a branded object
+ * without the seat cannot be constructed (both are written at the one stamp site).
+ */
+export declare function rebindDefineToolCtx(product: AgentTool, enrich: ToolCtxEnricher): AgentTool;
 /**
  * RB-409 — a per-call ctx builder a MOUNT hands to {@link defineTool}.
  *
@@ -58,3 +78,4 @@ export interface DefineToolOptions {
 }
 /** Adapt a friendly ToolSpec into the vendored AgentTool the agent loop expects. */
 export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>, options?: DefineToolOptions): AgentTool<TParams>;
+export {};

package/dist/core/tools.js

@@ -26,13 +26,46 @@ export function errorResult(text, details) {
     return details === undefined ? { content: text, isError: true } : { content: text, isError: true, details };
 }
 const DEFINE_TOOL_BRAND = Symbol("sema.core.defineTool.product");
+const DEFINE_TOOL_REBIND = Symbol("sema.core.defineTool.rebind");
 export function isDefineToolProduct(x) {
-    return typeof x === "object" && x !== null && x[DEFINE_TOOL_BRAND] === true;
+    return typeof x === "object" && x !== null && Object.getOwnPropertyDescriptor(x, DEFINE_TOOL_BRAND)?.value === true;
 }
-export function stampDefineToolBrand(tool) {
+export function stampDefineToolBrand(tool, rebind) {
     Object.defineProperty(tool, DEFINE_TOOL_BRAND, { value: true, enumerable: false });
+    Object.defineProperty(tool, DEFINE_TOOL_REBIND, { value: sealedRebind(tool, rebind), enumerable: false });
     return tool;
 }
+function sealedRebind(stamped, rebuild) {
+    const ownExecute = Object.getOwnPropertyDescriptor(stamped, "execute")?.value;
+    const stillSealed = () => {
+        const d = Object.getOwnPropertyDescriptor(stamped, "execute");
+        return d !== undefined && "value" in d && d.value === ownExecute;
+    };
+    return (enrich, mounted) => {
+        if (mounted !== stamped) {
+            throw new Error(`defineTool product ${JSON.stringify(stamped.name)}: the object being mounted is not the one this brand was stamped on (a derived object — prototype, proxy or descriptor copy — carrying a borrowed brand), so it cannot be rebound to the run's ctx without dropping its own overrides — wrap the product as a NEW object (stampDefineToolBrand with a rebind that re-wraps the rebound inner product), or author it as a raw ToolSpec`);
+        }
+        const refuse = () => {
+            throw new Error(`defineTool product ${JSON.stringify(stamped.name)}: its execute is not the own data property the factory wrote (replaced, or turned into an accessor, after the factory built it), so it cannot be rebound to the run's ctx without dropping the replacement — wrap the product as a NEW object (stampDefineToolBrand with a rebind that re-wraps the rebound inner product), or author it as a raw ToolSpec`);
+        };
+        if (!stillSealed())
+            refuse();
+        const rebound = rebuild(enrich, mounted);
+        if (!stillSealed())
+            refuse();
+        return rebound;
+    };
+}
+export function rebindDefineToolCtx(product, enrich) {
+    const rebind = Object.getOwnPropertyDescriptor(product, DEFINE_TOOL_REBIND)?.value;
+    if (typeof rebind !== "function")
+        throw new Error(`rebindDefineToolCtx: ${product.name} is not a defineTool product (no rebind seat)`);
+    return rebind(enrich, product);
+}
+function stampCallIdentity(enriched, toolCallId, signal) {
+    const own = (value) => ({ value, enumerable: true, configurable: true, writable: true });
+    return Object.create(Object.getPrototypeOf(enriched), { ...Object.getOwnPropertyDescriptors(enriched), toolCallId: own(toolCallId), signal: own(signal) });
+}
 export function defineTool(spec, options) {
     const executionMode = spec.executionMode ?? (spec.effect === "read" ? "parallel" : "sequential");
     const tool = {
@@ -77,7 +110,8 @@ export function defineTool(spec, options) {
             let ret;
             try {
                 const baseCtx = { toolCallId, signal };
-                ret = await spec.execute(params, options?.enrichCtx ? { ...options.enrichCtx(baseCtx), toolCallId, signal } : baseCtx);
+                const ctx = options?.enrichCtx ? stampCallIdentity(options.enrichCtx(baseCtx), toolCallId, signal) : baseCtx;
+                ret = await spec.execute(params, ctx);
             }
             catch (err) {
                 const wrapped = new Error(formatToolError(err));
@@ -105,6 +139,12 @@ export function defineTool(spec, options) {
             ...(spec.aliases && spec.aliases.length > 0 ? { aliases: spec.aliases } : {}),
         });
     }
-    stampDefineToolBrand(tool);
+    stampDefineToolBrand(tool, (enrich) => {
+        const composed = options?.enrichCtx === undefined ? enrich : (base) => options.enrichCtx(enrich(base));
+        const rebuilt = defineTool(spec, { ...options, enrichCtx: composed });
+        const { [DEFINE_TOOL_BRAND]: _brand, [DEFINE_TOOL_REBIND]: _seat, ...face } = Object.getOwnPropertyDescriptors(tool);
+        const copy = Object.create(Object.getPrototypeOf(tool), { ...face, execute: { value: rebuilt.execute, enumerable: true, configurable: true, writable: true } });
+        return stampDefineToolBrand(copy, (again) => rebindDefineToolCtx(rebuilt, again));
+    });
     return tool;
 }

package/dist/core/trace.d.ts

@@ -425,6 +425,21 @@ export type TraceEvent = {
     toolCallId: string;
     rules: readonly string[];
     ts: number;
+} | {
+    /**
+     * #619 — the READ-ONLY reader cleared a shell call, so no person and no classifier was asked: the
+     * allow layer's second attribution channel beside `permission.persisted_rule_allowed`. `command` is
+     * the FINAL command the gate judged (a policy rewrite included) — model-authored text, carried
+     * verbatim as the audit fact this frame exists for (a consumer rendering it applies its own
+     * display sanitizer, as it does for `tool_start` args).
+     */
+    kind: "permission.read_only_allowed";
+    version: 1;
+    taskId: string;
+    toolName: string;
+    toolCallId: string;
+    command: string;
+    ts: number;
 } | {
     /**
      * design/179 — the persisted allow-rule store could not be read, so this call was adjudicated with

package/dist/engine/harness/agent-harness.d.ts

@@ -131,6 +131,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private runPromise?;
     private pendingSessionWrites;
     private model;
+    /** The run's thinking level; `undefined` = undeclared (provider default, no wire key) — distinct from "off". */
     private thinkingLevel;
     /** RB-30 terminal fix — runner-set sink for engine-note payloads left undrained at agent_end. */
     onUndrainedEngineNotes?: (payloads: unknown[]) => void;
@@ -410,7 +411,8 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     } & UserMessageProvenance): Promise<void>;
     appendMessage(message: AgentMessage): Promise<void>;
     getModel(): Model;
-    getThinkingLevel(): ThinkingLevel;
+    /** The current level, or `undefined` when none was declared (provider default — no wire key). */
+    getThinkingLevel(): ThinkingLevel | undefined;
     setModel(model: Model): Promise<void>;
     setThinkingLevel(level: ThinkingLevel): Promise<void>;
     setActiveTools(toolNames: string[]): Promise<void>;

package/dist/engine/harness/agent-harness.js

@@ -277,7 +277,7 @@ export class AgentHarness {
             this.tools.set(tool.name, tool);
         }
         this.model = options.model;
-        this.thinkingLevel = options.thinkingLevel ?? "off";
+        this.thinkingLevel = options.thinkingLevel;
         this.activeToolNames =
             options.activeToolNames ?? (options.tools ?? []).map((tool) => tool.name);
         this.steeringQueueMode = options.steeringMode ?? "one-at-a-time";

package/dist/engine/harness/types.d.ts

@@ -1178,7 +1178,8 @@ export interface ModelSelectEvent {
 export interface ThinkingLevelSelectEvent {
     type: "thinking_level_select";
     level: ThinkingLevel;
-    previousLevel: ThinkingLevel;
+    /** `undefined` when the run had no declared level before this selection (provider default). */
+    previousLevel: ThinkingLevel | undefined;
 }
 export interface ResourcesUpdateEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
     type: "resources_update";
@@ -1346,7 +1347,8 @@ export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTempla
         env: ExecutionEnv;
         session: Session;
         model: Model;
-        thinkingLevel: ThinkingLevel;
+        /** `undefined` = no level declared (provider default). */
+        thinkingLevel: ThinkingLevel | undefined;
         activeTools: TTool[];
         resources: AgentHarnessResources<TSkill, TPromptTemplate>;
     }) => string | Promise<string>);

package/dist/index.d.ts

@@ -195,7 +195,9 @@ export { removePersistedRule, applyTombstones, sameScope, sameRuleIdentity, isVa
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, type PermissionRuleSyncTransport, type PermissionRuleSyncResult, type RuleSyncRequestBody, type RuleSyncResponseBody, } from "./core/permission-rule-sync.js";
 export { createPermissionRuleStoreProvider, effectivePermissionRules, effectiveOrThrow, ruleSourceOf, type PermissionRuleStore, type PermissionRuleStoreProvider, type PermissionRuleStoreConfig, type EffectivePermissionRules, type EffectivePermissionRule, type RemovedPermissionRule, type RuleSource, } from "./core/permission-rule-provider.js";
 export { InMemorySessionRulePartition, type SessionRulePartition, type SessionRuleAdd, type SessionRuleApplyResult, } from "./core/permission-rule-session.js";
-export { readShellCommand, isFullyReadable, MAX_SHELL_READ_CHARS, SHELL_WRAPPER_TABLE, type ShellCommandShape, type ShellSegment, type ShellWord, type ShellWrapperName, } from "./core/shell-lexer.js";
+export { readShellCommand, isFullyReadable, MAX_SHELL_READ_CHARS, SHELL_WRAPPER_TABLE, type ShellCommandShape, type ShellSegment, type ShellWord, type ShellRedirection, type ShellWrapperName, } from "./core/shell-lexer.js";
+export { readOnlyShellVerdict, type ReadOnlyShellVerdict } from "./core/read-only-shell.js";
+export { READ_ONLY_FLAG_ARITIES, FLAG_VALUE_ACCEPTS, READ_ONLY_COMMAND_TABLE, READ_ONLY_BARE_PROGRAMS, READ_ONLY_GLOB_PROGRAMS, READ_ONLY_EXACT_FORMS, READ_ONLY_BARE_ONLY, FIND_ACTION_PRIMARIES, FIND_VALUE_PRIMARIES, FIND_NEWER_PRIMARY, READ_ONLY_ENV_NAMES, XARGS_READ_ONLY_TARGETS, type ReadOnlyFlagArity, type ReadOnlyCommandRow, } from "./core/read-only-shell-table.js";
 export { orgRuleVerdictFor, type OrgRuleVerdict, orgRuleShadows, unenforceableOrgRules, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, type OrgPermissionRule, type OrgRuleSnapshot, type OrgRuleSnapshotProvider, type OrgRuleStatePersistence, type PersistedOrgRuleState, type OrgRulePartitionConfig, type OrgRuleResolution, type OrgRuleStatus, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES, type RuleSyncDropReason, type RuleQuarantineReason } from "./core/governance-codes.js";
 export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, precheckEditedRuleText, type EditedRuleTextPrecheck, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, ruleOffersOfRecord, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleOffer2, type StaleRuleApprovalRecord, type RuleConsentDeps, type RedeemResult, type RedeemedBatchMember, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, } from "./core/permission-rule-consent.js";

package/dist/index.js

@@ -155,6 +155,8 @@ export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH,
 export { createPermissionRuleStoreProvider, effectivePermissionRules, effectiveOrThrow, ruleSourceOf, } from "./core/permission-rule-provider.js";
 export { InMemorySessionRulePartition, } from "./core/permission-rule-session.js";
 export { readShellCommand, isFullyReadable, MAX_SHELL_READ_CHARS, SHELL_WRAPPER_TABLE, } from "./core/shell-lexer.js";
+export { readOnlyShellVerdict } from "./core/read-only-shell.js";
+export { READ_ONLY_FLAG_ARITIES, FLAG_VALUE_ACCEPTS, READ_ONLY_COMMAND_TABLE, READ_ONLY_BARE_PROGRAMS, READ_ONLY_GLOB_PROGRAMS, READ_ONLY_EXACT_FORMS, READ_ONLY_BARE_ONLY, FIND_ACTION_PRIMARIES, FIND_VALUE_PRIMARIES, FIND_NEWER_PRIMARY, READ_ONLY_ENV_NAMES, XARGS_READ_ONLY_TARGETS, } from "./core/read-only-shell-table.js";
 export { orgRuleVerdictFor, orgRuleShadows, unenforceableOrgRules, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES } from "./core/governance-codes.js";
 export { prepareCardApproval, confirmRuleApproval, precheckEditedRuleText, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, ruleOffersOfRecord, } from "./core/permission-rule-consent.js";

package/dist/orchestration/run-workflow-tool.d.ts

@@ -260,8 +260,11 @@ export interface RunWorkflowToolDeps {
     /** The HOST task's effective working root — threaded into every spawned agent's trusted internals so a
      *  TOC env factory can root the child at the parent's cwd (CC parity, 2026-07-03). */
     parentCwd?: string;
-    /** Call-time getter for the HOST task's current thinking level — a spawned agent with no explicit
-     *  script/baseline `thinking` inherits it (the parentCwd/model-snapshot companion). */
+    /** Call-time getter for the level a spawned agent runs at when neither the script, the agentType
+     *  definition nor the governance baseline set `thinking` (the mount folds the deployment's STATED
+     *  `roles.subagent.thinking` over the HOST task's current level — the child thinking seat's lower rungs).
+     *  Threaded to the workflow as `defaultThinking` and applied at the launch site AFTER the agentType fold,
+     *  the `parentModel` → `defaultModel` companion. */
     parentThinking?: () => import("../core/types.js").TaskSpec["thinking"];
     /** 5.30 merge-rescan (design/199 parity gap) — call-time getter for the HOST task's RESOLVED
      *  read-face containment; folds stricter-wins into every spawned workflow child (see

package/dist/orchestration/run-workflow-tool.js

@@ -488,7 +488,7 @@ export async function createRunWorkflowTool(d) {
                 }
                 : governance;
             const scriptFn = (wfCtx) => {
-                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, d.parentThinking, principal, ctx.checkpointStoreDisabledForChildren === true || d.parentCheckpointStoreDisabled === true, d.parentReadFace, d.parentReadDenyPatterns, ctx.handsReadOnly === true || d.parentHandsReadOnly === true, ctx.interactiveTools === false || d.parentInteractiveTools === false);
+                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, principal, ctx.checkpointStoreDisabledForChildren === true || d.parentCheckpointStoreDisabled === true, d.parentReadFace, d.parentReadDenyPatterns, ctx.handsReadOnly === true || d.parentHandsReadOnly === true, ctx.interactiveTools === false || d.parentInteractiveTools === false);
                 return d.scriptRunner.run({ scriptSource: script, primitives, scriptArgs: effectiveArgs, signal: wfCtx.signal }).then((r) => r.result);
             };
             if (ctx.signal?.aborted) {
@@ -546,6 +546,7 @@ export async function createRunWorkflowTool(d) {
                         return d.parentMemoryCaptureState !== undefined ? { parentMemoryCaptureState: d.parentMemoryCaptureState } : {};
                     })(),
                     ...(d.parentModel !== undefined ? { defaultModel: d.parentModel } : {}),
+                    ...(d.parentThinking !== undefined ? { defaultThinking: d.parentThinking } : {}),
                     ...(d.parentGetApiKeyAndHeaders !== undefined ? { defaultGetApiKeyAndHeaders: d.parentGetApiKeyAndHeaders } : {}),
                     ...(hostDurableApproval !== undefined && d.store !== undefined ? { defaultDurableApproval: { ...hostDurableApproval } } : {}),
                     ...(resumeFromRunId !== undefined && d.parkedResume !== undefined && d.parkedResume(resumeFromRunId) !== undefined ? { parkedResume: d.parkedResume(resumeFromRunId) } : {}),