@sema-agent/core 7.45.0 → 7.47.0

package/dist/tools/fs/shell-reentry-text.d.ts

@@ -1,10 +1,140 @@
 /**
  * The shell text a program hands back to the shell: the text a shell program runs INSTEAD of its argv (`sh -c S`,
- * `eval S` — {@link reentryText}), and the code bodies a builtin keeps AMONG its operands to run later
- * ({@link codeBodies}). The plan marks a segment carrying either as a shell re-entry (`shell-read-plan.ts`); this
- * module is the one reader of which operand that text is.
+ * `eval S`, or its standard input where the argv names no script — {@link reentryText}), and the code bodies a builtin
+ * keeps AMONG its operands to run later ({@link codeBodies}). The plan marks a segment carrying either as a shell
+ * re-entry (`shell-read-plan.ts`); this module is the one reader of which operand — or which input — that text is.
+ */
+import { type LexedSegment, type LexedWord } from "../../shell/lex.js";
+import { type ProgramPosition } from "./bash-program-position.js";
+import type { BoundValue } from "./shell-read-bindings.js";
+/**
+ * The code bodies a builtin keeps among its operands, one per body; empty for every other program. The program read
+ * model's row says where the body is: the action of a `trap` (its first operand after the options), the value of an
+ * `alias` definition, the shell-text option of `mapfile` / `readarray` / `compgen` (`-C`; compgen runs it at once, to
+ * list completions). The text is re-entry text as `eval`'s operand is — the segment re-enters the shell, the command's
+ * read set is not established, and each body is its own nested plan whose deny hits still refuse (one unreadable body
+ * cannot hide another's). What a body does when it runs is not read from the text, so a body of any content asks: a
+ * harmless `trap 'echo bye' EXIT` in front of a read asks as `eval 'echo bye'` does. The builtin's own words stay the
+ * candidates they are for any unlisted program. An absent body is no re-entry (`trap - SIG` resets, `trap '' SIG`
+ * ignores, `mapfile` without `-C`); an EMPTY alias value or `-C` value is still one. Over-reading is the direction
+ * taken: a display option (`trap -p SIG`) and a lone operand (`trap SIG`) still count their operand as the body.
  */
-/** The code bodies a builtin keeps among its operands, one per body; empty for every other program. */
 export declare function codeBodies(basename: string, args: readonly string[]): readonly string[];
-/** The shell text a re-entry program runs: `sh -c S` (the `c` letter's value), `eval` (its words joined). */
-export declare function reentryText(basename: string, args: readonly string[]): string | undefined;
+/** The shell text a re-entry program runs, by its row: the shell-text value its walk reads for a shell (`-c`'s), its
+ *  words joined for `eval`, its non-option words for `parallel`; none for `source` / `.` (a script file operand), for a
+ *  shell whose first operand (a script file) or `--` comes before any text, or for a program that is no re-entry. Where
+ *  the argv names no text and the program runs its standard input ({@link scriptSourceOf}: the row runs it unnamed, or
+ *  the script file named is standard input), the text is `stdin` — one text that may arrive there, as the caller spells it. */
+export declare function reentryText(basename: string, args: readonly string[], stdin?: string): string | undefined;
+/** One argument of the argv a launcher hands the SHELL it runs: a word of the command line passed on as it stands (`at`,
+ *  its argv index; `from` — only the word's characters from there on, an option value attached to its option word), a word
+ *  of the launcher's own (`fixed`: the `-c` in front of a text it builds), or a text it builds from several words
+ *  (`joined`: their argv indices, joined by a space; `escaped` — every character of a word's value but a letter, a digit,
+ *  `_`, `-` and `$` escaped with a backslash, as `sudo -s` builds its shell's `-c` text). */
+export type LaunchedArg = {
+    readonly at: number;
+    readonly from?: number;
+} | {
+    readonly fixed: string;
+} | {
+    readonly joined: readonly number[];
+    readonly escaped?: true;
+};
+/** What a launcher that runs a program named by no word of its own runs: `program` — absent, a SHELL named by no word
+ *  (sudo's, chroot's, the user's login shell `su` runs); `at` — the word naming it (`su -s PROGRAM`, from its `from`-th
+ *  character where the value is attached to its option word); `spelled` — a program the launcher takes from elsewhere,
+ *  as a shell spells it (`su -m`: the caller's `"$SHELL"`) — and the argv it hands that program. */
+export interface LaunchedCommand {
+    readonly program?: {
+        readonly at: number;
+        readonly from?: number;
+    } | {
+        readonly spelled: string;
+    };
+    readonly args: readonly LaunchedArg[];
+}
+/**
+ * What a launcher that runs a program named by no word of its own runs ({@link readProgramPosition}'s `runsShell`: the
+ * launcher, and the first word it hands on), one command per reading of the launcher's row where its implementations
+ * read it differently; empty when no launcher of the segment runs one. A shell's argv is read by that shell's row
+ * ({@link reentryText}, {@link scriptFileAt}): its `-c` text, its script file, else its standard input. By the launcher
+ * row (`LauncherSpec`, program-read-model.ts):
+ *  · no word handed on (`sudo -s`, `chroot DIR`, a bare `su`): the shell is handed nothing;
+ *  · `shellCommand: "escaped"` (`sudo -s CMD…`): `-c` and the words, escaped and joined;
+ *  · `shellText: "joined"` (`watch CMD…`): `-c` and the non-option words, joined — and `-c` with each shell-text value
+ *    attached to its option word (`script -c'CMD'`);
+ *  · `shellText: "user"` (`su [-] [USER [ARG…]]`): per implementation — its first operand past a lone `-` names the user;
+ *    one that reads its options anywhere hands `-c TEXT` for each shell-text value of its own (a command each) and its
+ *    operands after the user, one that stops at the user hands every word after the user. The program is the value of
+ *    its option of role `command` (`-s PROGRAM`), else the program a selected `names-program` switch takes from the
+ *    caller's environment (`-m`: `"$SHELL"`), else the user's login shell.
+ */
+export declare function launchedCommands(argv: readonly LexedWord[], pos?: ProgramPosition): readonly LaunchedCommand[];
+/** How a launched command is read: as a SHELL's argv (`shell`: the shell whose row reads it — a program that runs its
+ *  `-c` text, `sh`, `bash`, `fish`, …, or `sh` for the shell named by no word), as the command line it is (`line`: a
+ *  program that is no shell, `su -s /bin/rm …`, its words as written, so its expansions are the command line's), or
+ *  both — a program the text does not spell (`su -s "$X"`, `su -m`: the caller's `"$SHELL"`) may be any program, a shell
+ *  among them. */
+export declare function launchedReadings(argv: readonly LexedWord[], command: LaunchedCommand): {
+    readonly shell?: string;
+    readonly line?: string;
+};
+/** What a launcher runs ({@link launchedCommands}, {@link launchedReadings}), as a reader of the command line reads it:
+ *  each shell's argv in two spellings — `texts` (a word's literal value, else `spell.text`) and `args` (`spell.folded`) —
+ *  with the argv index each position stands for (`words`), one argv per reading of the values its words may take
+ *  (`spell.values`, {@link spellLaunched}); the word naming a shell (`su -s /bin/bash`, `programWords`); and each command
+ *  line a program that is no shell runs (`lines`, once each). */
+export declare function launchedInput(argv: readonly LexedWord[], pos: ProgramPosition, spell: {
+    readonly text: (k: number) => string;
+    readonly folded: (k: number) => string;
+    readonly values: (k: number) => readonly BoundValue[] | undefined;
+}): {
+    readonly shells: readonly {
+        readonly shell: string;
+        readonly texts: readonly string[];
+        readonly args: readonly string[];
+        readonly words: readonly (number | undefined)[];
+    }[];
+    readonly programWords: readonly number[];
+    readonly lines: readonly string[];
+};
+/** How a reader spells the words of a command line it hands a launched shell ({@link spellLaunched}): `word` — a word as
+ *  it stands, from its `from`-th character; `values` — for a word the shell rewrites before the launcher sees it, the
+ *  values it may take where the reader knows them (each one field, or a pattern whose matches are the fields — its parts
+ *  say which characters the shell expands), `undefined` where it does not; absent — the reader knows none. */
+export interface LaunchedSpelling {
+    readonly word: (at: number, from: number) => string;
+    readonly values?: (at: number) => readonly BoundValue[] | undefined;
+}
+/**
+ * The argv a launched shell is handed ({@link launchedCommands}), spelled as `spell` spells the command line's words — one
+ * argv per reading of the values its words may take. A word an escaping launcher joins (`sudo -s CMD…`) is handed as the
+ * launcher hands it: each FIELD the command line's shell gives the launcher, escaped ({@link sudoEscaped}) — the field a
+ * literal word spells, or each field the shell established for a word it rewrites first (`X='#'; sudo -s rm -r "$X" d`
+ * hands `rm -r \# d`: the value is an operand, never a comment), a pattern's literal characters escaped and its pattern
+ * characters bare ({@link launchedSpellingOf}). A word whose fields the reader does not know is handed AS WRITTEN: the
+ * launched shell re-reads the expansion with the command line's quoting, so the word stays one argument (an unknown there)
+ * and its neighbours stay theirs (`"#$Y" d` is never `#$Y d`). A reading gives each distinct word spelling one value — the
+ * same word spelled twice expands alike — and words with several values are read in every combination of them (a value in
+ * the program's position meets each operand); past {@link LAUNCHED_READINGS_MAX}
+ * combinations reading `i` hands each word its `i`-th value (its last where it holds fewer) — every value of every word is
+ * still read, the same word spelled twice takes one value per reading as the shell expands it, and the readings stay as
+ * many as one word's values: their cost is linear in the command, whatever its length.
+ */
+export declare function spellLaunched(argv: readonly LexedWord[], args: readonly LaunchedArg[], spell: LaunchedSpelling): string[][];
+/** The argv index of the SCRIPT FILE a shell runs where its argv carries no text ({@link scriptSourceOf}). */
+export declare function scriptFileAt(basename: string, args: readonly string[]): number | undefined;
+/** One text that may arrive on a segment's standard input: `from` = its source as written (a here-document's body,
+ *  `<<<WORD`, `<FILE`, `<&N`, the segment the pipe comes from); `literal` = the text, where the command spells it. */
+export interface StdinText {
+    readonly from: string;
+    readonly literal?: string;
+}
+/** What may arrive on a segment's standard input: each here-document (its descriptor is not read: every one counts) —
+ *  its body, literal when quoted or when nothing in it expands — each here-string (literal when its word is), `<` file
+ *  or `<&` descriptor written to no other descriptor, and the pipe it is reached through (`piped`) unless one of those
+ *  three replaces it. */
+export declare function stdinTextsOf(segment: LexedSegment, piped: StdinText | undefined): StdinText[];
+/** What one segment (its argv) writes into the pipe after it: the text a printer spells ({@link printedText}) when its
+ *  program word and every argument are literal, else only the segment as written. */
+export declare function pipedTextOf(segment: LexedSegment, argv: readonly LexedWord[]): StdinText;

package/dist/tools/fs/shell-reentry-text.js

@@ -1,25 +1,19 @@
-const CODE_BODY_OPERANDS = new Map([
-    ["trap", trapAction],
-    ["alias", aliasValues],
-    ["mapfile", callbacksOf(new Set(["d", "u", "n", "O", "C", "c", "s"]))],
-    ["readarray", callbacksOf(new Set(["d", "u", "n", "O", "C", "c", "s"]))],
-    ["compgen", callbacksOf(new Set(["o", "A", "G", "W", "P", "S", "X", "F", "C", "V"]))],
-]);
+import { literalHeredocBody, literalTextOf } from "../../shell/lex.js";
+import { programBasename, readProgramPosition } from "./bash-program-position.js";
+import { implementationsOf, printedText, programRow, readArgRoles, selectedOptions } from "./program-read-model.js";
+import { namesStandardInput } from "./safety.js";
 export function codeBodies(basename, args) {
-    return CODE_BODY_OPERANDS.get(basename)?.(args) ?? [];
-}
-function trapAction(args) {
-    let k = 0;
-    for (; k < args.length; k++) {
-        const a = args[k];
-        if (a === "--") {
-            k++;
-            break;
-        }
-        if (!a.startsWith("-") || a === "-")
-            break;
+    const row = programRow(basename);
+    switch (row?.body) {
+        case "first-operand": return firstOperandBody(row, args);
+        case "assignment-values": return aliasValues(args);
+        case "option-values": return shellTextOptionValues(row, args);
+        case undefined: return [];
     }
-    const action = args[k];
+}
+function firstOperandBody(row, args) {
+    const first = readArgRoles(row, args).find((e) => e.kind === "operand");
+    const action = first === undefined ? undefined : args[first.at];
     return action === undefined || action === "" || action === "-" ? [] : [action];
 }
 function aliasValues(args) {
@@ -31,43 +25,199 @@ function aliasValues(args) {
     }
     return values;
 }
-function callbacksOf(valueLetters) {
-    return (args) => {
-        const callbacks = [];
-        for (let k = 0; k < args.length; k++) {
-            const a = args[k];
-            if (a === "--" || !a.startsWith("-") || a === "-")
-                break;
-            for (let i = 1; i < a.length; i++) {
-                if (!valueLetters.has(a[i]))
-                    continue;
-                const value = i + 1 < a.length ? a.slice(i + 1) : args[++k];
-                if (a[i] === "C" && value !== undefined)
-                    callbacks.push(value);
-                break;
-            }
-        }
-        return callbacks;
-    };
+function shellTextOptionValues(row, args) {
+    const callbacks = [];
+    for (const e of optionSection(readArgRoles(row, args))) {
+        const text = shellTextOf(e, args);
+        if (text !== undefined)
+            callbacks.push(text);
+    }
+    return callbacks;
 }
-export function reentryText(basename, args) {
-    if (basename === "eval")
+function optionSection(events) {
+    const end = events.findIndex((e) => e.kind === "operand" || e.kind === "dash-word-operand" || e.kind === "end-of-options");
+    return end === -1 ? [...events] : events.slice(0, end);
+}
+function shellTextOf(e, args) {
+    if (e.kind === "value" && e.role?.kind === "shell-text")
+        return args[e.at];
+    if (e.kind === "option" && typeof e.reading === "object" && e.reading.role?.kind === "shell-text")
+        return e.reading.attached;
+    return undefined;
+}
+export function reentryText(basename, args, stdin) {
+    const row = programRow(basename);
+    const r = row?.reentry;
+    if (row === undefined || r?.kind !== "shell")
+        return undefined;
+    const text = argvText(row, r.text, args);
+    if (text !== undefined || stdin === undefined)
+        return text;
+    const source = scriptSourceOf(row, args);
+    return (r.stdin === "script" && source.stdin) || (source.file !== undefined && namesStandardInput(args[source.file])) ? stdin : undefined;
+}
+function argvText(row, at, args) {
+    if (at === "words")
         return args.length === 0 ? undefined : args.join(" ");
-    if (basename === "parallel")
+    if (at === "non-option-words")
         return args.filter((a) => !a.startsWith("-")).join(" ") || undefined;
-    if (basename === "source" || basename === ".")
+    if (at === "file-operand")
         return undefined;
-    for (let k = 0; k < args.length; k++) {
-        const a = args[k];
-        if (a === "--")
-            return undefined;
-        if (!a.startsWith("-") || a === "-")
-            return undefined;
-        const c = a.indexOf("c");
-        if (a.startsWith("--"))
-            continue;
-        if (c > 0)
-            return a.length > c + 1 ? a.slice(c + 1) : args[k + 1];
+    for (const e of optionSection(readArgRoles(row, args))) {
+        const text = shellTextOf(e, args);
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+}
+export function launchedCommands(argv, pos = readProgramPosition(argv)) {
+    const runs = pos.refusal?.kind === "control_syntax_at_program_position" ? pos.refusal.runsShell : undefined;
+    if (runs === undefined)
+        return [];
+    const row = programRow(programBasename(argv[runs.launcher].folded));
+    const words = argv.slice(runs.from).map((w) => w.folded);
+    const at = (k) => runs.from + k;
+    if (words.length === 0 || row?.launcher === undefined)
+        return [{ args: [] }];
+    if (row.launcher.shellText === "user")
+        return userCommands(row, words, at);
+    if (row.launcher.shellText === "joined") {
+        const joined = words.flatMap((w, k) => (w.startsWith("-") ? [] : [at(k)]));
+        const attached = readArgRoles(row, words).flatMap((e) => (e.kind === "option" ? roleValue(e, "shell-text", words, at) ?? [] : []));
+        const texts = [...(joined.length === 0 ? [] : [{ joined }]), ...attached];
+        return texts.length === 0 ? [{ args: [] }] : texts.map((t) => ({ args: [{ fixed: "-c" }, t] }));
     }
+    return [{ args: [{ fixed: "-c" }, { joined: words.map((_, k) => at(k)), escaped: true }] }];
+}
+function roleValue(e, kind, words, at) {
+    if (e.kind === "value" && e.role?.kind === kind)
+        return { at: at(e.at) };
+    if (e.kind === "option" && typeof e.reading === "object" && e.reading.role?.kind === kind)
+        return { at: at(e.at), from: words[e.at].length - e.reading.attached.length };
     return undefined;
 }
+function userCommands(row, words, at) {
+    const out = [];
+    const valued = (e, kind) => roleValue(e, kind, words, at);
+    for (const view of implementationsOf(row)) {
+        const events = readArgRoles(view, words);
+        const operands = events.filter((e) => e.kind === "operand");
+        const user = (operands[0]?.dash !== undefined ? operands[1] : operands[0])?.at;
+        const end = user ?? words.length;
+        const stops = view.grammars[0]?.afterFirstOperand === "operands";
+        const own = stops ? events.filter((e) => e.at < end) : events;
+        const named = own.flatMap((e) => valued(e, "command") ?? []).at(-1);
+        const fromEnvironment = selectedOptions(view, stops ? words.slice(0, end) : words, "one-implementation").some((o) => o.mode === "names-program");
+        const program = named !== undefined ? { program: named } : fromEnvironment ? { program: { spelled: "\"$SHELL\"" } } : {};
+        if (stops) {
+            out.push({ ...program, args: user === undefined ? [] : words.slice(user + 1).map((_, k) => ({ at: at(user + 1 + k) })) });
+            continue;
+        }
+        const rest = operands.filter((e) => user !== undefined && e.at > user).map((e) => ({ at: at(e.at) }));
+        const texts = own.flatMap((e) => valued(e, "shell-text") ?? []);
+        if (texts.length === 0)
+            out.push({ ...program, args: rest });
+        for (const text of texts)
+            out.push({ ...program, args: [{ fixed: "-c" }, text, ...rest] });
+    }
+    return out;
+}
+export function launchedReadings(argv, command) {
+    const p = command.program;
+    if (p === undefined)
+        return { shell: "sh" };
+    const raw = (k, from = 0) => {
+        if (from === 0)
+            return argv[k].raw;
+        const literal = literalTextOf(argv[k].pieces);
+        return literal === undefined ? argv[k].folded.slice(from) : `'${literal.slice(from).replace(/'/g, "'\\''")}'`;
+    };
+    const line = [("at" in p ? raw(p.at, p.from) : p.spelled), ...command.args.map((a) => ("fixed" in a ? a.fixed : "at" in a ? raw(a.at, a.from) : a.joined.map((k) => raw(k)).join(" ")))].join(" ");
+    const literal = "at" in p ? literalTextOf(argv[p.at].pieces)?.slice(p.from ?? 0) : undefined;
+    if (literal === undefined)
+        return { shell: "sh", line };
+    const basename = programBasename(literal);
+    const reentry = programRow(basename)?.reentry;
+    return reentry?.kind === "shell" && reentry.text === "c-option" ? { shell: basename } : { line };
+}
+export function launchedInput(argv, pos, spell) {
+    const spelled = (word) => (args) => spellLaunched(argv, args, { word: (k, from) => word(k).slice(from), values: spell.values });
+    const asTexts = spelled(spell.text);
+    const asArgs = spelled(spell.folded);
+    const lines = new Set();
+    const programWords = [];
+    const shells = launchedCommands(argv, pos).flatMap((c) => {
+        const { shell, line } = launchedReadings(argv, c);
+        if (line !== undefined)
+            lines.add(line);
+        if (shell === undefined)
+            return [];
+        if (line === undefined && c.program !== undefined && "at" in c.program && c.program.from === undefined)
+            programWords.push(c.program.at);
+        const words = c.args.map((x) => ("at" in x && x.from === undefined ? x.at : undefined));
+        const args = asArgs(c.args);
+        return asTexts(c.args).map((texts, i) => ({ shell, texts, args: args[i], words }));
+    });
+    return { shells, programWords, lines: [...lines] };
+}
+const LAUNCHED_READINGS_MAX = 64;
+function sudoEscaped(field) {
+    return field.replace(/[^A-Za-z0-9_$-]/gu, (c) => `\\${c}`);
+}
+function launchedSpellingOf(v) {
+    return v.glob === true ? v.parts.map((p) => (p.pattern ? p.text : sudoEscaped(p.text))).join("") : sudoEscaped(v.spelled);
+}
+export function spellLaunched(argv, args, spell) {
+    const choicesOf = (k) => {
+        const literal = literalTextOf(argv[k].pieces);
+        if (literal !== undefined)
+            return [sudoEscaped(literal)];
+        const values = spell.values?.(k);
+        return values === undefined ? [argv[k].raw] : values.map(launchedSpellingOf);
+    };
+    const choices = new Map(args.flatMap((a) => ("joined" in a && a.escaped === true ? a.joined : [])).map((k) => [k, choicesOf(k)]));
+    const distinct = new Map([...choices].map(([k, c]) => [argv[k].raw, c]));
+    const combinations = [...distinct.values()].reduce((n, c) => n * c.length, 1);
+    const readings = combinations <= LAUNCHED_READINGS_MAX
+        ? [...distinct].reduce((acc, [w, c]) => acc.flatMap((r) => c.map((x) => new Map(r).set(w, x))), [new Map()]).map((r) => new Map([...choices.keys()].map((k) => [k, r.get(argv[k].raw)])))
+        : Array.from({ length: [...choices.values()].reduce((n, c) => Math.max(n, c.length), 1) }, (_, i) => new Map([...choices].map(([k, c]) => [k, c[Math.min(i, c.length - 1)]])));
+    return readings.map((reading) => args.map((a) => ("fixed" in a ? a.fixed : "at" in a ? spell.word(a.at, a.from ?? 0) : a.joined.map((k) => (a.escaped === true ? reading.get(k) : spell.word(k, 0))).join(" "))));
+}
+export function scriptFileAt(basename, args) {
+    const row = programRow(basename);
+    return row?.reentry?.kind === "shell" && argvText(row, row.reentry.text, args) === undefined ? scriptSourceOf(row, args).file : undefined;
+}
+function scriptSourceOf(row, args) {
+    const events = readArgRoles(row, args);
+    const options = optionSection(events);
+    const end = events[options.length]?.at ?? args.length;
+    if (selectedOptions(row, args.slice(0, end), "one-implementation").some((o) => o.mode === "interactive"))
+        return { stdin: true };
+    const first = events.find((e) => e.kind === "operand");
+    if (first?.kind !== "operand" || first.dash !== undefined)
+        return { stdin: true };
+    return { file: first.at, stdin: options.some((e) => e.kind === "option" && e.reading === "speculative") };
+}
+export function stdinTextsOf(segment, piped) {
+    const out = [];
+    let replacesPipe = false;
+    for (const t of segment.tokens) {
+        if (t.kind === "heredoc") {
+            const literal = t.quoted ? t.body : literalHeredocBody(t.body);
+            out.push(literal === undefined ? { from: t.body } : { from: t.body, literal });
+        }
+        else if (t.kind === "redirect" && (t.fd ?? 0) === 0 && (t.op === "<<<" || t.op === "<" || (t.op === "<&" && t.dup !== "-"))) {
+            const literal = t.op === "<<<" && t.target !== undefined ? literalTextOf(t.target.pieces) : undefined;
+            out.push({ from: `${t.op}${t.target?.raw ?? t.dup ?? ""}`, ...(literal !== undefined ? { literal } : {}) });
+            replacesPipe = true;
+        }
+    }
+    return piped === undefined || replacesPipe ? out : [piped, ...out];
+}
+export function pipedTextOf(segment, argv) {
+    const from = `${segment.text.trim()} |`;
+    const pos = readProgramPosition(argv);
+    const program = pos.program;
+    const literal = program === undefined || pos.refusal !== undefined || literalTextOf(argv[program.index].pieces) === undefined ? undefined : printedText(programRow(program.basename), argv.slice(program.index + 1).map((w) => literalTextOf(w.pieces)));
+    return literal === undefined ? { from } : { from, literal };
+}

package/dist/tools/monitor.d.ts

@@ -28,9 +28,9 @@
  * The handle is a first-class m* registry task: TaskOutput serves the re-readable spool, TaskStop stops the
  * watch (design/134 stoppedBy attribution applies automatically).
  *
- * Security posture: `command` is an arbitrary shell script ⇒ effect:"write", same as Bash, and prepare-task
- * folds Monitor into the SAME shellGate tighten (irreversibility tier + reversibility probe on the same
- * `command` arg) — Monitor is never a policy side-door around a gated Bash.
+ * Security posture: `command` is an arbitrary shell script ⇒ effect:"write", same as Bash; the catalog puts Monitor on the
+ * SHELL FACE, so the `Bash(<command>)` rules, the shell seat, the read station and the removal guard judge its `command`
+ * as they judge Bash's — Monitor is never a policy side-door around a gated Bash.
  *
  * 深对比残差 M17 CLOSED (2026-07-09 live-CC probe, docs/cc-probe-198/live-schema-monitor-worktree-2026-07-09.json):
  * the deep-dive bundle showed a `command? + ws?:{url,protocols}` dual-mode schema; the LIVE current-CC schema is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.45.0",
+  "version": "7.47.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2617,
+  "count": 2627,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -43,6 +43,7 @@
     "ARTIFACT_PUBLISH_CONTEXTS": "variable",
     "ASK_CLASSES": "variable",
     "ASK_EVIDENCE_ABSENCE_VALUES": "variable",
+    "ASK_FACES": "variable",
     "ASK_ORIGINS": "variable",
     "ASK_UNRESOLVABLE_CAUSES": "variable",
     "ASK_USER_QUESTION_TOOL_NAME": "variable",
@@ -142,6 +143,7 @@
     "AskDelegationProvenance": "interface",
     "AskEffective": "type",
     "AskEvidenceAbsence": "type",
+    "AskFace": "type",
     "AskOrigin": "type",
     "AskOutcome": "type",
     "AskQuestion": "interface",
@@ -212,6 +214,7 @@
     "BeforeWriteHook": "type",
     "BeforeWriteRequest": "interface",
     "BeforeWriteResult": "type",
+    "BoundPathRule": "interface",
     "BoundSkillGrants": "interface",
     "Brain": "interface",
     "BrainError": "class",
@@ -265,6 +268,8 @@
     "CacheBreakFinding": "interface",
     "CacheFamily": "type",
     "CacheIdentityElements": "interface",
+    "CallTargetReading": "interface",
+    "CallTargetView": "type",
     "CascadeAttempt": "interface",
     "CascadeConfig": "interface",
     "CascadeRunResult": "interface",
@@ -443,6 +448,7 @@
     "EMPTY_DURABLE_RULE_PARTITION": "variable",
     "EMPTY_USAGE_WINDOW_RECORD": "variable",
     "ENGINE_AUTHORITY_ENVELOPE_TAGS": "variable",
+    "ENGINE_BUILTIN_TOOL_NAMES": "variable",
     "ENGINE_NOTICE_CODES": "variable",
     "ENTER_PLAN_MODE_TOOL_NAME": "variable",
     "ENV_LIFETIME_SUSPEND_MARGIN_MS": "variable",
@@ -988,6 +994,7 @@
     "PathRuleBase": "type",
     "PathRuleBases": "type",
     "PathRuleDenyRow": "interface",
+    "PathRuleSpec": "interface",
     "PathTargetReading": "type",
     "PausedCause": "type",
     "PeerAdmission": "interface",
@@ -1154,7 +1161,6 @@
     "REASONING_BUDGET_SHARE": "variable",
     "RECALL_CAVEAT": "variable",
     "RECOMMENDED_SENSITIVE_PATTERNS": "variable",
-    "RELEASABLE_ASK_CLASSES": "variable",
     "REMOTE_HARVEST_PER_FILE_BYTES": "variable",
     "REMOTE_MASS_DELETION_FUSE_RATIO": "variable",
     "REMOVAL_LIVENESS_WORDS": "variable",
@@ -1815,6 +1821,7 @@
     "artifactAttemptId": "function",
     "artifactConformanceVectors": "function",
     "artifactDeclarations": "function",
+    "askFaceOf": "function",
     "askUnresolvableNotice": "function",
     "assembleCodeTools": "function",
     "assertAdoptionBootGate": "function",
@@ -2158,6 +2165,7 @@
     "isDeclaredWrite": "function",
     "isDelegatedAgentTerminal": "function",
     "isDeniedBy": "function",
+    "isEngineBuiltinToolName": "function",
     "isEngineRefusal": "variable",
     "isFreshPeerRow": "function",
     "isFullyReadable": "function",
@@ -2403,6 +2411,7 @@
     "redactSecrets": "function",
     "redeemRuleBatch": "function",
     "redeemRuleTicket": "function",
+    "releasableAskClassesFor": "function",
     "releaseSessionRetainLedger": "function",
     "remainingBudgetMicroUsd": "function",
     "remainingTokens": "function",
@@ -2418,6 +2427,7 @@
     "renderCrossSessionIdleNotice": "function",
     "renderCrossSessionMessageFrame": "function",
     "renderCrossSessionNoticeLine": "function",
+    "renderListEntry": "function",
     "renderNamedWorkflowListing": "function",
     "renderTaskNotificationXml": "function",
     "renderUntrustedCommandText": "function",
@@ -2577,7 +2587,7 @@
     "toolFaceProblem": "function",
     "toolIdentityOf": "function",
     "toolPolicyNameSets": "function",
-    "toolPolicyPathDenyRules": "function",
+    "toolPolicyPathRules": "function",
     "toolResultContentSegment": "function",
     "toolResultProvenanceOf": "function",
     "toolResultStoreContract": "function",
@@ -2662,6 +2672,7 @@
     "ARTIFACT_PUBLISH_CONTEXTS": "advanced",
     "ASK_CLASSES": "advanced",
     "ASK_EVIDENCE_ABSENCE_VALUES": "advanced",
+    "ASK_FACES": "advanced",
     "ASK_ORIGINS": "advanced",
     "ASK_UNRESOLVABLE_CAUSES": "advanced",
     "ASK_USER_QUESTION_TOOL_NAME": "advanced",
@@ -2761,6 +2772,7 @@
     "AskDelegationProvenance": "advanced",
     "AskEffective": "advanced",
     "AskEvidenceAbsence": "advanced",
+    "AskFace": "advanced",
     "AskOrigin": "advanced",
     "AskOutcome": "advanced",
     "AskQuestion": "advanced",
@@ -2831,6 +2843,7 @@
     "BeforeWriteHook": "stable",
     "BeforeWriteRequest": "advanced",
     "BeforeWriteResult": "advanced",
+    "BoundPathRule": "advanced",
     "BoundSkillGrants": "advanced",
     "Brain": "stable",
     "BrainError": "advanced",
@@ -2884,6 +2897,8 @@
     "CacheBreakFinding": "advanced",
     "CacheFamily": "internal",
     "CacheIdentityElements": "advanced",
+    "CallTargetReading": "advanced",
+    "CallTargetView": "advanced",
     "CascadeAttempt": "advanced",
     "CascadeConfig": "advanced",
     "CascadeRunResult": "advanced",
@@ -3062,6 +3077,7 @@
     "EMPTY_DURABLE_RULE_PARTITION": "advanced",
     "EMPTY_USAGE_WINDOW_RECORD": "advanced",
     "ENGINE_AUTHORITY_ENVELOPE_TAGS": "advanced",
+    "ENGINE_BUILTIN_TOOL_NAMES": "advanced",
     "ENGINE_NOTICE_CODES": "advanced",
     "ENTER_PLAN_MODE_TOOL_NAME": "advanced",
     "ENV_LIFETIME_SUSPEND_MARGIN_MS": "internal",
@@ -3607,6 +3623,7 @@
     "PathRuleBase": "advanced",
     "PathRuleBases": "advanced",
     "PathRuleDenyRow": "advanced",
+    "PathRuleSpec": "advanced",
     "PathTargetReading": "advanced",
     "PausedCause": "advanced",
     "PeerAdmission": "advanced",
@@ -3773,7 +3790,6 @@
     "REASONING_BUDGET_SHARE": "advanced",
     "RECALL_CAVEAT": "advanced",
     "RECOMMENDED_SENSITIVE_PATTERNS": "advanced",
-    "RELEASABLE_ASK_CLASSES": "advanced",
     "REMOTE_HARVEST_PER_FILE_BYTES": "advanced",
     "REMOTE_MASS_DELETION_FUSE_RATIO": "advanced",
     "REMOVAL_LIVENESS_WORDS": "advanced",
@@ -4434,6 +4450,7 @@
     "artifactAttemptId": "advanced",
     "artifactConformanceVectors": "advanced",
     "artifactDeclarations": "advanced",
+    "askFaceOf": "advanced",
     "askUnresolvableNotice": "advanced",
     "assembleCodeTools": "advanced",
     "assertAdoptionBootGate": "advanced",
@@ -4777,6 +4794,7 @@
     "isDeclaredWrite": "advanced",
     "isDelegatedAgentTerminal": "advanced",
     "isDeniedBy": "advanced",
+    "isEngineBuiltinToolName": "advanced",
     "isEngineRefusal": "advanced",
     "isFreshPeerRow": "advanced",
     "isFullyReadable": "advanced",
@@ -5022,6 +5040,7 @@
     "redactSecrets": "advanced",
     "redeemRuleBatch": "advanced",
     "redeemRuleTicket": "advanced",
+    "releasableAskClassesFor": "advanced",
     "releaseSessionRetainLedger": "advanced",
     "remainingBudgetMicroUsd": "advanced",
     "remainingTokens": "advanced",
@@ -5037,6 +5056,7 @@
     "renderCrossSessionIdleNotice": "advanced",
     "renderCrossSessionMessageFrame": "advanced",
     "renderCrossSessionNoticeLine": "advanced",
+    "renderListEntry": "advanced",
     "renderNamedWorkflowListing": "advanced",
     "renderTaskNotificationXml": "advanced",
     "renderUntrustedCommandText": "advanced",
@@ -5196,7 +5216,7 @@
     "toolFaceProblem": "internal",
     "toolIdentityOf": "advanced",
     "toolPolicyNameSets": "advanced",
-    "toolPolicyPathDenyRules": "advanced",
+    "toolPolicyPathRules": "advanced",
     "toolResultContentSegment": "advanced",
     "toolResultProvenanceOf": "advanced",
     "toolResultStoreContract": "advanced",