@sema-agent/core 7.10.0 → 7.11.0

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

@@ -0,0 +1,316 @@
+import { readShellCommand } from "./shell-lexer.js";
+import { FIND_ACTION_PRIMARIES, FIND_NEWER_PRIMARY, FIND_VALUE_PRIMARIES, FLAG_VALUE_ACCEPTS, READ_ONLY_BARE_ONLY, READ_ONLY_BARE_PROGRAMS, READ_ONLY_COMMAND_TABLE, READ_ONLY_ENV_NAMES, READ_ONLY_EXACT_FORMS, READ_ONLY_GLOB_PROGRAMS, XARGS_READ_ONLY_TARGETS, dockerRetargetDanger, } from "./read-only-shell-table.js";
+const NOT = (reason) => ({ readOnly: false, reason });
+const READ_ONLY = { readOnly: true };
+const BARE_PROGRAMS = new Set(READ_ONLY_BARE_PROGRAMS.filter((p) => !p.includes(" ")));
+const BARE_MULTIWORD = READ_ONLY_BARE_PROGRAMS.filter((p) => p.includes(" ")).map((p) => p.split(" "));
+const GLOB_PROGRAMS = new Set(READ_ONLY_GLOB_PROGRAMS);
+const BARE_ONLY = new Set(READ_ONLY_BARE_ONLY);
+const ENV_NAMES = new Set(READ_ONLY_ENV_NAMES);
+const FIND_ACTIONS = new Set(FIND_ACTION_PRIMARIES);
+const FIND_VALUES = new Set(FIND_VALUE_PRIMARIES);
+const XARGS_TARGETS = XARGS_READ_ONLY_TARGETS;
+const TABLE_ROWS = Object.entries(READ_ONLY_COMMAND_TABLE)
+    .map(([key, row]) => ({ words: key.split(" "), row }))
+    .sort((a, b) => b.words.length - a.words.length);
+const READING_REDIRECTS = new Set(["<", "<<", "<<-", "<&", "<<<"]);
+const LITERAL_ASSIGNMENT = /^([A-Za-z_][A-Za-z0-9_]*)\+?=(?:"[^"$`\\]*"|'[^']*'|[A-Za-z0-9_./:+-]*)$/;
+const ASSIGNMENT_NAME = /^([A-Za-z_][A-Za-z0-9_]*)(?:\[[^\]]*\])?\+?=/;
+const FLAG_WORD = /^-[a-zA-Z0-9_-]/;
+const NUMBER_LITERAL = /^[-+]?(0[xX][0-9a-fA-F]+|[0-9]+#[0-9a-zA-Z]+|[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)$/;
+const PRINTF_LENGTH = "[lLhqjzZt]*";
+const PRINTF_ESCAPE = new RegExp(`%[^%a-zA-Z]*${PRINTF_LENGTH}\\\\[0-7xX]`);
+const PRINTF_NUMERIC = new RegExp(`%[-+ 0#']*[0-9.*]*${PRINTF_LENGTH}[diouxXeEfFgGaAn]`);
+const JQ_DANGER_FLAG = /^['"]?-[a-zA-Z]*[fL]/;
+const JQ_DANGER_TEXT = /--from-file|--rawfile|--slurpfile|--run-tests|--library-path|\benv\b|\$ENV\b|\binclude\b|\bimport\b/;
+export function readOnlyShellVerdict(command, shape = readShellCommand(command)) {
+    if (shape.grouped)
+        return NOT("a subshell, group or control structure — not a flat list of simple commands");
+    if (shape.segments.length === 0)
+        return NOT("no command");
+    if (shape.backgrounded)
+        return NOT("a background `&` defers execution past the approval-time reading");
+    if (shape.strayRedirection)
+        return NOT("a redirection on a piece that runs no program — the shell still opens its target");
+    for (const seg of shape.segments) {
+        if (seg.unreadable !== undefined)
+            return NOT(seg.unreadable);
+        if (seg.peelUnreadable !== undefined)
+            return NOT(seg.peelUnreadable);
+        for (const w of [...seg.argv, ...seg.redirections.map((r) => r.target)]) {
+            if (expansionKind(w) === "variable")
+                return NOT("a variable, arithmetic or command substitution — its value is not known at approval time");
+            if (w.expands !== false && /[()]/.test(w.raw))
+                return NOT("a pattern with a parenthesised part (an extended pattern or a shell-specific glob qualifier)");
+            if (/^=[A-Za-z_]/.test(w.raw) || w.raw.includes("~["))
+                return NOT("a shell-specific expansion spelling (`=cmd`, `~[…]`)");
+        }
+    }
+    const programs = shape.segments.map((s) => peelBuiltinPrefix(s.argv.slice(leadingAssignmentCount(s.argv)).map((w) => w.text))[0] ?? "");
+    if (shape.segments.length > 1 && programs.includes("cd") && programs.includes("git"))
+        return NOT("a compound that changes directory and runs git");
+    for (const seg of shape.segments) {
+        const verdict = segmentVerdict(seg);
+        if (!verdict.readOnly)
+            return verdict;
+    }
+    return READ_ONLY;
+}
+function expansionKind(w) {
+    if (w.expands === false)
+        return "none";
+    if (/[$`]|[<>]\(/.test(w.raw))
+        return "variable";
+    if (w.expands === "many")
+        return "glob";
+    return "none";
+}
+function leadingAssignmentCount(argv) {
+    let k = 0;
+    while (k < argv.length && ASSIGNMENT_NAME.test(argv[k].raw))
+        k++;
+    return k;
+}
+function peelBuiltinPrefix(words) {
+    let t = words;
+    for (;;) {
+        if (t[0] === "command") {
+            let r = 1;
+            while (t[r] !== undefined && /^-p+$/.test(t[r]))
+                r++;
+            if (t[r] === "--")
+                r++;
+            if (r >= t.length || t[r].startsWith("-"))
+                return t;
+            t = t.slice(r);
+        }
+        else if (t[0] === "builtin") {
+            const r = t[1] === "--" ? 2 : 1;
+            if (r >= t.length)
+                return t;
+            t = t.slice(r);
+        }
+        else if (t[0] === "noglob") {
+            if (t.length <= 1)
+                return t;
+            t = t.slice(1);
+        }
+        else
+            return t;
+    }
+}
+function segmentVerdict(seg) {
+    for (const r of seg.redirections) {
+        const target = r.target.text;
+        if (!READING_REDIRECTS.has(r.op) && target !== "/dev/null" && !(r.op === ">&" && /^\d+$/.test(target)))
+            return NOT(`the redirection \`${r.op} ${target}\` writes`);
+        if (/^\/dev\/(tcp|udp)\//.test(target))
+            return NOT("a redirection to a network pseudo-device");
+    }
+    const k = leadingAssignmentCount(seg.argv);
+    for (const w of seg.argv.slice(0, k)) {
+        const m = LITERAL_ASSIGNMENT.exec(w.raw);
+        if (m === null)
+            return NOT(`the assignment \`${w.raw}\` is not a literal value`);
+        if (!ENV_NAMES.has(m[1]))
+            return NOT(`the environment variable \`${m[1]}\` can alter what a program does`);
+    }
+    const run = seg.argv.slice(k);
+    if (run.length === 0)
+        return NOT("a bare assignment runs no program");
+    const words = peelBuiltinPrefix(run.map((w) => w.text));
+    const program = words[0];
+    if (run.some((w) => expansionKind(w) === "glob"))
+        return GLOB_PROGRAMS.has(program) ? READ_ONLY : NOT(`\`${program}\` with a glob argument — the glob may name anything`);
+    const structural = structuralReading(words);
+    if (structural !== null)
+        return structural ? READ_ONLY : NOT(`\`${program}\` with these arguments is not a read-only form`);
+    return tableReading(words, run);
+}
+function structuralReading(words) {
+    const program = words[0];
+    if (BARE_ONLY.has(program))
+        return words.length === 1;
+    for (const form of READ_ONLY_EXACT_FORMS)
+        if (words.length === form.length && words.every((w, i) => w === form[i]))
+            return true;
+    if (BARE_PROGRAMS.has(program))
+        return true;
+    for (const form of BARE_MULTIWORD)
+        if (words.length >= form.length && form.every((w, i) => words[i] === w))
+            return form[0] !== "docker" || !dockerRetargetDanger(words);
+    if (program === "echo")
+        return true;
+    if (program === "printf")
+        return printfReading(words);
+    if (program === "ls")
+        return true;
+    if (program === "cd")
+        return words.length <= 2;
+    if (program === "find") {
+        for (let i = 1; i < words.length; i++) {
+            const w = words[i];
+            if (FIND_ACTIONS.has(w))
+                return false;
+            if (FIND_VALUES.has(w) || FIND_NEWER_PRIMARY.test(w)) {
+                i++;
+                continue;
+            }
+        }
+        return true;
+    }
+    if (program === "history")
+        return words.length === 1 || (words.length === 2 && /^\d+$/.test(words[1]));
+    if (program === "arch")
+        return words.length === 1 || (words.length === 2 && (words[1] === "-h" || words[1] === "--help"));
+    if (program === "ifconfig")
+        return words.length === 1 || (words.length === 2 && /^[a-zA-Z]/.test(words[1]));
+    return null;
+}
+function printfReading(words) {
+    if (words[1]?.startsWith("-") === true && words[1] !== "--")
+        return false;
+    const at = words[1] === "--" ? 2 : 1;
+    const format = words[at] ?? "";
+    if (format.includes("$"))
+        return false;
+    const stripped = format.replace(/%%/g, "");
+    if (PRINTF_ESCAPE.test(stripped) || /\\[uU]/.test(stripped))
+        return false;
+    if (PRINTF_NUMERIC.test(stripped) || /%[^%a-zA-Z]*\*/.test(stripped)) {
+        for (let i = at + 1; i < words.length; i++) {
+            const operand = words[i];
+            if (operand.includes("[") || operand.includes("`") || operand.includes("$(") || !NUMBER_LITERAL.test(operand))
+                return false;
+        }
+    }
+    return true;
+}
+function tableReading(words, run) {
+    const program = words[0];
+    const hit = TABLE_ROWS.find((r) => words.length >= r.words.length && r.words.every((w, i) => words[i] === w));
+    if (hit !== undefined) {
+        const args = words.slice(hit.words.length);
+        for (const a of args) {
+            if (a.includes("$"))
+                return NOT(`\`${program}\`: an argument spells \`$\``);
+            if (a.includes("{") && (a.includes(",") || a.includes("..")))
+                return NOT(`\`${program}\`: a brace pattern argument`);
+        }
+        if (!flagWalk(args, hit.row, program))
+            return NOT(`\`${program}\`: an option outside its read-only set (or a malformed option value)`);
+        if (hit.row.wordsShape !== undefined ? !hit.row.wordsShape(args) : run.some((w) => w.raw.includes("`")))
+            return NOT(`\`${program}\`: arguments outside its read-only form`);
+        if (hit.row.wordsShape === undefined && (program === "rg" || program === "grep" || program === "egrep" || program === "fgrep") && run.some((w) => /[\n\r]/.test(w.raw)))
+            return NOT(`\`${program}\`: a line break inside an argument`);
+        if (hit.row.dangerous?.(args) === true)
+            return NOT(`\`${program}\`: an argument form upstream marks as writing, executing or resolving`);
+        return READ_ONLY;
+    }
+    if (program === "uniq" && words.slice(1).every((w, i, all) => /^-[a-zA-Z]+$/.test(w) || /^--[a-zA-Z-]+(=\S+)?$/.test(w) || (i > 0 && /^-[fsw]$/.test(all[i - 1]) && /^\d+$/.test(w))))
+        return gitOptionGuard(words);
+    if (program === "jq" && jqReading(run.slice(run.length - words.length + 1)))
+        return gitOptionGuard(words);
+    return NOT(`\`${program}\` is not a read-only program (or not in a read-only form)`);
+}
+function gitOptionGuard(words) {
+    if (words.includes("git") && words.some((w) => /^-c(=|$)|^--exec-path(=|$)|^--config-env(=|$)/.test(w)))
+        return NOT("a git configuration override on the line");
+    return READ_ONLY;
+}
+function jqReading(args) {
+    if (args.some((w) => JQ_DANGER_FLAG.test(w.raw) || JQ_DANGER_TEXT.test(w.raw)))
+        return false;
+    let i = 0;
+    while (i < args.length && (/^-[a-zA-Z]+$/.test(args[i].raw) || /^--[a-zA-Z-]+(=\S+)?$/.test(args[i].raw)))
+        i++;
+    if (i >= args.length)
+        return false;
+    for (; i < args.length; i++) {
+        const w = args[i];
+        const quoted = /^'[^'`]*'$|^"[^"`]*"$/.test(w.raw);
+        if (!quoted && (/^[-'"\s]/.test(w.raw) || /['"]/.test(w.raw)))
+            return false;
+    }
+    return true;
+}
+function flagWalk(args, row, program) {
+    let i = 0;
+    while (i < args.length) {
+        let word = args[i];
+        if (word === "") {
+            i++;
+            continue;
+        }
+        if (program === "xargs" && (!word.startsWith("-") || word === "--")) {
+            if (word === "--" && i + 1 < args.length) {
+                i++;
+                word = args[i];
+            }
+            return XARGS_TARGETS.includes(word);
+        }
+        if (word === "--") {
+            if (row.respectsDoubleDash !== false)
+                break;
+            i++;
+            continue;
+        }
+        if (FLAG_WORD.test(word)) {
+            const eq = word.indexOf("=");
+            const flag = eq === -1 ? word : word.slice(0, eq);
+            const attached = eq === -1 ? undefined : word.slice(eq + 1);
+            const arity = row.safeFlags[flag];
+            if (arity === undefined) {
+                if (program === "git" && /^-\d+$/.test(flag)) {
+                    i++;
+                    continue;
+                }
+                if ((program === "grep" || program === "egrep" || program === "fgrep" || program === "rg") && !flag.startsWith("--") && flag.length > 2) {
+                    const base = flag.slice(0, 2);
+                    const rest = flag.slice(2);
+                    const baseArity = row.safeFlags[base];
+                    if (baseArity !== undefined && /^\d+$/.test(rest) && (baseArity === "number" || baseArity === "string")) {
+                        if (FLAG_VALUE_ACCEPTS[baseArity](rest)) {
+                            i++;
+                            continue;
+                        }
+                        return false;
+                    }
+                }
+                if (!flag.startsWith("--") && flag.length > 2) {
+                    for (let c = 1; c < flag.length; c++)
+                        if (row.safeFlags[`-${flag[c]}`] !== "none")
+                            return false;
+                    i++;
+                    continue;
+                }
+                return false;
+            }
+            if (arity === "none") {
+                if (attached !== undefined)
+                    return false;
+                i++;
+                continue;
+            }
+            let value;
+            if (attached !== undefined) {
+                value = attached;
+                i++;
+            }
+            else {
+                const next = args[i + 1];
+                if (next === undefined || FLAG_WORD.test(next))
+                    return false;
+                value = next;
+                i += 2;
+            }
+            if (arity === "string" && value.startsWith("-") && !(flag === "--sort" && program === "git" && /^-[a-zA-Z]/.test(value)))
+                return false;
+            if (!FLAG_VALUE_ACCEPTS[arity](value))
+                return false;
+            continue;
+        }
+        i++;
+    }
+    return true;
+}

package/dist/core/roles.d.ts

@@ -104,8 +104,9 @@ export interface ResolvedRole {
  * `modelRole` and NO run model: it runs on the deployment's roles alone — the boot default at the end of
  * its chain — and never follows the model a run was switched to. Only a run's CHILDREN follow the parent:
  * the delegation seat (`childModelSeat`) passes the parent's `Model` as `spec.model` with the role kept
- * on `modelRole`, so the role's presets still apply. A side channel that must follow a run passes that
- * run's model explicitly; nothing here infers it.
+ * on `modelRole` — and keeps that role on an EXPLICIT-model seat too, so the explicit branch below reads
+ * the child's presets off the subagent role, not the default one. A side channel that must follow a run
+ * passes that run's model explicitly; nothing here infers it.
  */
 export declare function resolveTaskModel(spec: {
     model?: ModelRef;

package/dist/core/runner/gate-exit.d.ts

@@ -218,6 +218,11 @@ export interface GatePass {
      *  touch. Recorded by the gate rather than read off `decisionReason` because that member is a policy's to
      *  compose (a policy stamping `"safety"` on its own ask must read as `policy`). Writer: the fold. */
     tightenedBy: AskOriginFacts["tightened"];
+    /** borrowed-mutable — the reversibility probe was consulted on this pass and DID NOT ANSWER (it threw or
+     *  timed out). The out-of-root mandate has no other source than the probe's answer, so an unanswered probe
+     *  leaves the call's boundary UNKNOWN: the allow layer (a stored allow rule, the read-only reader) must
+     *  not clear the surviving ask — a person confirms it. Writer: the fold. Reader: the lanes' mandate. */
+    probeUnanswered?: true;
     /** borrowed-mutable — the rewrite remembered BEFORE a hook-ask promotion / tighten, re-applied on the
      *  approved path (a redaction is not cancelled because a person confirmed). Writer: the fold. Readers: the
      *  fold's probe and write-protection judges, the lanes, the allow exit. */

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -7,7 +7,7 @@ import { isSelfOrchestrationActive } from "../../orchestration/workflow-script-r
 import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
 import { thinkingOffExpressible } from "../../brain/reasoning.js";
 import { autoModeArmingRecipeOf } from "../auto-mode-arming.js";
-import { AUTO_MODE_CLASSIFIER_MAX_TOKENS } from "../auto-mode-defaults.js";
+import { AUTO_MODE_CLASSIFIER_MAX_TOKENS, AUTO_MODE_CLASSIFIER_THINKING_ALLOWANCE_TOKENS } from "../auto-mode-defaults.js";
 import { buildAutoModePrompt, renderAutoModeAction, renderAutoModeWindow } from "../auto-mode-prompt.js";
 import { createAutoModeDecider, createAutoModeDenialTracker } from "../auto-mode.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
@@ -17,9 +17,20 @@ import { resolveTaskModel } from "../roles.js";
 import { brainToRuntime } from "../runtime.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { emitTrace } from "../trace.js";
-import { defineTool, isDefineToolProduct } from "../tools.js";
+import { defineTool, isDefineToolProduct, rebindDefineToolCtx } from "../tools.js";
 import { derivedRouteFallsBack } from "./derived-route-fallback.js";
 import { REPORT_FINDINGS_TOOL_NAME, createReportBlockedTool, createReportFindingsTool } from "./synthetic-tools.js";
+function classifierReplyText(reply) {
+    return reply.content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+}
+function classifierReplyEmptyAtCap(reply) {
+    if (classifierReplyText(reply) !== "")
+        return false;
+    return reply.stopReason === "length" || (reply.stopReason === "error" && reply.errorKind === "length_empty");
+}
 import { RosterBuilder, callerMountSource } from "../tool-roster.js";
 function assembleParentCaptureState(o, i, ctl, ancestors) {
     const build = (optedOut, indeterminate) => ({
@@ -72,9 +83,8 @@ export async function prepareCapsAndWorkflow(input) {
         roster.mount(mounted, { source: callerMountSource(mounted), mountedBy: "scenario" });
     }
     function mountCallerTool(t) {
-        if (isDefineToolProduct(t)) {
-            return maybeOffload(t, t);
-        }
+        if (isDefineToolProduct(t))
+            return maybeOffload(rebindDefineToolCtx(t, enrichSpecToolCtx), t);
         return maybeOffload(defineTool({
             ...t,
             execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
@@ -191,17 +201,18 @@ export async function prepareCapsAndWorkflow(input) {
                     (m.role === "user" || m.role === "assistant" || m.role === "toolResult"));
                 const userPrompt = renderAutoModeWindow(known, am.window) + renderAutoModeAction(input);
                 const classifierAuth = await spec.getApiKeyAndHeaders?.(classifierModel);
-                const response = await classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, {
+                const request = (cap) => classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, {
                     signal,
                     reasoning: "off",
-                    ...classifierCap,
+                    ...cap,
                     ...(classifierAuth?.apiKey !== undefined ? { apiKey: classifierAuth.apiKey } : {}),
                     ...(classifierAuth?.headers !== undefined ? { headers: classifierAuth.headers } : {}),
                 });
-                return response.content
-                    .filter((c) => c.type === "text")
-                    .map((c) => c.text)
-                    .join("");
+                let response = await request(classifierCap);
+                if (classifierCap.maxTokens !== undefined && classifierReplyEmptyAtCap(response)) {
+                    response = await request({ maxTokens: classifierCap.maxTokens + AUTO_MODE_CLASSIFIER_THINKING_ALLOWANCE_TOKENS });
+                }
+                return classifierReplyText(response);
             },
         });
         if (am.persistArming === true)

package/dist/core/runner/prepare-gate-stations.js

@@ -139,6 +139,15 @@ export function prepareGateStations(input) {
                                 },
                             }
                             : {}),
+                        onReadOnlyAllowed: (info) => emitTrace(deps.tracer, () => ({
+                            kind: "permission.read_only_allowed",
+                            version: 1,
+                            taskId: hostTaskId,
+                            toolName: info.toolName,
+                            toolCallId: info.toolCallId,
+                            command: info.command,
+                            ts: Date.now(),
+                        })),
                         ...(permissionRuleOrgLane
                             ? {
                                 orgRules: {

package/dist/core/runner/prepare-task.js

@@ -634,7 +634,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             session,
             tools: [...harnessTools],
             model,
-            thinkingLevel: thinking ?? "off",
+            thinkingLevel: thinking,
             systemPrompt: systemPromptSeat.current,
             ...(systemBlocks ? { systemBlocks } : {}),
             getApiKeyAndHeaders: spec.getApiKeyAndHeaders,

package/dist/core/runner/prepare-turn-wiring.js

@@ -26,7 +26,7 @@ export function prepareTurnWiring(input) {
         layoutGroups: (systemBlocks ?? [{ groupId: "body", cacheControlBoundary: true }]).map((b) => ({ groupId: b.groupId, cacheControlBoundary: b.cacheControlBoundary })),
         stableSystemText: systemPromptSeat.current,
         toolWire: toolsToFingerprintInputs(harnessTools),
-        thinkingLevel: (thinking ?? "off"),
+        thinkingLevel: thinking ?? null,
         maxTokens: model.maxTokens,
         hasOutputSchema: spec.outputSchema !== undefined,
         sessionId,

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() };