@sema-agent/core 7.45.0 → 7.47.0

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

@@ -1,30 +1,31 @@
+import { declaresOption, programRows } from "../tools/fs/program-read-model.js";
 export const SHELL_WRAPPER_TABLE = {
     command: { valueFlags: [], flags: ["-p"], commandString: [] },
     builtin: { valueFlags: [], flags: [], commandString: [] },
     noglob: { valueFlags: [], flags: [], commandString: [] },
     nocorrect: { valueFlags: [], flags: [], commandString: [] },
     exec: { valueFlags: ["-a"], flags: ["-c", "-l"], commandString: [] },
-    env: { valueFlags: ["-u", "-C", "-a", "-P", "--unset", "--chdir", "--argv0"], flags: ["-i", "-0", "-v", "--ignore-environment", "--null", "--debug", "--list-signal-handling", "--default-signal", "--ignore-signal", "--block-signal", "--help", "--version"], commandString: ["-S", "--split-string"], bareDash: true, assignments: true },
-    sudo: { valueFlags: ["-u", "-g", "-U", "-C", "-D", "-h", "-p", "-r", "-R", "-t", "-T", "--user", "--group", "--other-user", "--close-from", "--chdir", "--host", "--prompt", "--role", "--chroot", "--type", "--command-timeout", "-a", "--auth-type"], flags: ["-A", "-b", "-E", "-H", "-i", "-K", "-k", "-l", "-n", "-P", "-S", "-s", "-V", "-v", "--askpass", "--background", "--preserve-env", "--set-home", "--login", "--remove-timestamp", "--reset-timestamp", "--list", "--non-interactive", "--preserve-groups", "--stdin", "--shell", "--version", "--validate", "--bell", "--help"], commandString: [], assignments: true },
-    doas: { valueFlags: ["-a", "-u", "-C"], flags: ["-L", "-n", "-s"], commandString: [] },
-    pkexec: { valueFlags: ["--user"], flags: ["--disable-internal-agent", "--keep-cwd", "--version", "--help"], commandString: [] },
+    env: { valueFlags: ["--argv0", "--chdir", "--unset", "-C", "-P", "-a", "-u"], flags: ["--debug", "--default-signal", "--help", "--ignore-environment", "--ignore-signal", "--list-signal-handling", "--version", "-i", "-v"], commandString: ["--split-string", "-S"], bareDash: true, assignments: true },
+    sudo: { valueFlags: ["--auth-type", "--chdir", "--chroot", "--close-from", "--command-timeout", "--group", "--host", "--other-user", "--prompt", "--role", "--type", "--user", "-C", "-D", "-R", "-T", "-U", "-a", "-g", "-h", "-p", "-r", "-t", "-u"], flags: ["--askpass", "--background", "--bell", "--help", "--list", "--login", "--non-interactive", "--preserve-env", "--preserve-groups", "--remove-timestamp", "--reset-timestamp", "--set-home", "--shell", "--stdin", "--validate", "--version", "-A", "-E", "-H", "-K", "-P", "-S", "-V", "-b", "-i", "-k", "-l", "-n", "-s", "-v"], commandString: [], assignments: true },
+    doas: { valueFlags: ["-C", "-a", "-u"], flags: ["-L", "-n", "-s"], commandString: [] },
+    pkexec: { valueFlags: ["--user"], flags: ["--disable-internal-agent", "--help", "--keep-cwd", "--version"], commandString: [] },
     nohup: { valueFlags: [], flags: ["--help", "--version"], commandString: [] },
-    time: { valueFlags: ["-o", "--output", "-f", "--format"], flags: ["-p", "-a", "-v", "-q", "--append", "--portability", "--verbose", "--quiet", "--help", "--version"], commandString: [] },
-    nice: { valueFlags: ["-n", "--adjustment"], flags: ["--help", "--version"], commandString: [] },
-    timeout: { valueFlags: ["-k", "-s", "--kill-after", "--signal"], flags: ["-v", "--foreground", "--preserve-status", "--verbose", "--help", "--version"], commandString: [], duration: true },
-    stdbuf: { valueFlags: ["-i", "-o", "-e", "--input", "--output", "--error"], flags: ["--help", "--version"], commandString: [] },
-    xargs: { valueFlags: ["-n", "-L", "-P", "-I", "-d", "-s", "-a", "-E", "--max-args", "--max-procs", "--delimiter", "--max-chars", "--arg-file", "--process-slot-var"], flags: ["-0", "-r", "-t", "-x", "-p", "-o", "--null", "--no-run-if-empty", "--verbose", "--exit", "--interactive", "--open-tty", "--show-limits", "--help", "--version", "--replace", "--eof", "--max-lines"], attached: ["-i", "-l"], commandString: [] },
+    time: { valueFlags: ["--format", "--output", "-f", "-o"], flags: ["--append", "--help", "--portability", "--quiet", "--verbose", "--version", "-a", "-p", "-q", "-v"], commandString: [] },
+    nice: { valueFlags: ["--adjustment", "-n"], flags: ["--help", "--version"], commandString: [] },
+    timeout: { valueFlags: ["--kill-after", "--signal", "-k", "-s"], flags: ["--foreground", "--help", "--preserve-status", "--verbose", "--version", "-v"], commandString: [], duration: true },
+    stdbuf: { valueFlags: ["--error", "--input", "--output", "-e", "-i", "-o"], flags: ["--help", "--version"], commandString: [] },
+    xargs: { valueFlags: ["--arg-file", "--delimiter", "--max-args", "--max-chars", "--max-procs", "--process-slot-var", "-E", "-I", "-L", "-P", "-a", "-d", "-n", "-s"], flags: ["--eof", "--exit", "--help", "--interactive", "--max-lines", "--no-run-if-empty", "--null", "--open-tty", "--replace", "--show-limits", "--verbose", "--version", "-0", "-o", "-p", "-r", "-t", "-x"], attached: ["-i", "-l"], commandString: [] },
     watch: { valueFlags: [], flags: [], commandString: [], viaShell: true },
-    ionice: { valueFlags: ["-c", "-n", "-p", "-P", "-u", "--class", "--classdata", "--pid", "--pgid", "--uid"], flags: ["-t", "--ignore", "-h", "--help", "-V", "--version"], commandString: [] },
-    setsid: { valueFlags: [], flags: ["-c", "-f", "-w", "--ctty", "--fork", "--wait", "--help", "--version"], commandString: [] },
-    taskset: { valueFlags: [], flags: ["-a", "-p", "-c", "--all-tasks", "--pid", "--cpu-list", "--help", "--version"], commandString: [], positional: /^(?:0x)?[\da-f]+$|^[\d,:-]+$/i },
-    chrt: { valueFlags: ["-p", "--pid", "-T", "-P", "-D", "--sched-runtime", "--sched-period", "--sched-deadline"], flags: ["-b", "-f", "-i", "-o", "-r", "-d", "-m", "-a", "-R", "-v", "--batch", "--fifo", "--idle", "--other", "--rr", "--deadline", "--max", "--all-tasks", "--reset-on-fork", "--verbose", "--help", "--version"], commandString: [], positional: /^\d+$/ },
-    strace: { valueFlags: ["-e", "-o", "-p", "-s", "-E", "-P", "-S", "-a", "-b", "-I", "-u", "-X", "-O", "-U", "--output", "--trace", "--expr", "--attach", "--string-limit", "--env", "--trace-path", "--columns", "--user", "--interruptible", "--detach-on", "--const-print-style", "--summary-sort-by", "--summary-syscall-overhead", "--summary-columns"], flags: ["-f", "-ff", "-c", "-C", "-d", "-D", "-h", "-i", "-k", "-q", "-qq", "-r", "-t", "-tt", "-ttt", "-T", "-v", "-V", "-w", "-x", "-xx", "-y", "-yy", "-z", "-Z", "-F", "--follow-forks", "--summary-only", "--summary", "--debug", "--help", "--version"], commandString: [] },
-    ltrace: { valueFlags: ["-a", "-A", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-x", "-D", "-F", "--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "-w", "--where"], flags: ["-c", "-C", "-f", "-i", "-L", "-r", "-S", "-t", "-tt", "-ttt", "-T", "-V", "--demangle", "--help", "--version"], commandString: [] },
-    flock: { valueFlags: ["-w", "-E", "--timeout", "--wait", "--conflict-exit-code"], flags: ["-s", "-x", "-u", "-n", "-o", "-F", "--shared", "--exclusive", "--unlock", "--nonblock", "--nb", "--close", "--no-fork", "--verbose", "--help", "--version"], commandString: ["-c", "--command"], positional: /^/ },
-    script: { valueFlags: [], flags: [], commandString: ["-c", "--command"], viaShell: true },
-    unshare: { valueFlags: ["-R", "-w", "-S", "-G", "--setuid", "--setgid", "--root", "--wd", "--propagation", "--setgroups", "--monotonic", "--boottime", "--map-user", "--map-group"], flags: ["-m", "-u", "-i", "-n", "-p", "-U", "-C", "-T", "-f", "-r", "-c", "--mount", "--uts", "--ipc", "--net", "--pid", "--user", "--cgroup", "--time", "--fork", "--map-root-user", "--map-current-user", "--kill-child", "--mount-proc", "--keep-caps", "--help", "--version"], commandString: [] },
-    nsenter: { valueFlags: ["-t", "-S", "-G", "--target", "--setuid", "--setgid"], flags: ["-a", "-m", "-u", "-i", "-n", "-p", "-U", "-C", "-T", "-r", "-w", "-F", "-Z", "--all", "--mount", "--uts", "--ipc", "--net", "--pid", "--user", "--cgroup", "--time", "--root", "--wd", "--no-fork", "--preserve-credentials", "--help", "--version"], commandString: [] },
+    ionice: { valueFlags: ["--class", "--classdata", "--pgid", "--pid", "--uid", "-P", "-c", "-n", "-p", "-u"], flags: ["--help", "--ignore", "--version", "-V", "-h", "-t"], commandString: [] },
+    setsid: { valueFlags: [], flags: ["--ctty", "--fork", "--help", "--version", "--wait", "-c", "-f", "-w"], commandString: [] },
+    taskset: { valueFlags: [], flags: ["--all-tasks", "--cpu-list", "--help", "--pid", "--version", "-a", "-c", "-p"], commandString: [], positional: /^(?:0x)?[\da-f]+$|^[\d,:-]+$/i },
+    chrt: { valueFlags: ["--pid", "--sched-deadline", "--sched-period", "--sched-runtime", "-D", "-P", "-T", "-p"], flags: ["--all-tasks", "--batch", "--deadline", "--fifo", "--help", "--idle", "--max", "--other", "--reset-on-fork", "--rr", "--verbose", "--version", "-R", "-a", "-b", "-d", "-f", "-i", "-m", "-o", "-r", "-v"], commandString: [], positional: /^\d+$/ },
+    strace: { valueFlags: ["--attach", "--columns", "--const-print-style", "--detach-on", "--env", "--expr", "--interruptible", "--output", "--string-limit", "--summary-columns", "--summary-sort-by", "--summary-syscall-overhead", "--trace", "--trace-path", "--user", "-E", "-I", "-O", "-P", "-S", "-U", "-X", "-a", "-b", "-e", "-o", "-p", "-s", "-u"], flags: ["--debug", "--follow-forks", "--help", "--summary", "--summary-only", "--version", "-C", "-D", "-F", "-T", "-V", "-Z", "-c", "-d", "-f", "-h", "-i", "-k", "-q", "-r", "-t", "-v", "-w", "-x", "-y", "-z"], commandString: [] },
+    ltrace: { valueFlags: ["--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "--where", "-A", "-D", "-F", "-a", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-w", "-x"], flags: ["--demangle", "--help", "--version", "-C", "-L", "-S", "-T", "-V", "-c", "-f", "-i", "-r", "-t"], commandString: [] },
+    flock: { valueFlags: ["--conflict-exit-code", "--timeout", "--wait", "-E", "-w"], flags: ["--close", "--exclusive", "--help", "--nb", "--no-fork", "--nonblock", "--shared", "--unlock", "--verbose", "--version", "-F", "-n", "-o", "-s", "-u", "-x"], commandString: ["--command", "-c"], positional: /^/ },
+    script: { valueFlags: [], flags: [], commandString: ["--command", "-c"], viaShell: true },
+    unshare: { valueFlags: ["--boottime", "--map-group", "--map-user", "--monotonic", "--propagation", "--root", "--setgid", "--setgroups", "--setuid", "--wd", "-G", "-R", "-S", "-w"], flags: ["--cgroup", "--fork", "--help", "--ipc", "--keep-caps", "--kill-child", "--map-current-user", "--map-root-user", "--mount", "--mount-proc", "--net", "--pid", "--time", "--user", "--uts", "--version", "-C", "-T", "-U", "-c", "-f", "-i", "-m", "-n", "-p", "-r", "-u"], commandString: [] },
+    nsenter: { valueFlags: ["--setgid", "--setuid", "--target", "-G", "-S", "-t"], flags: ["--all", "--cgroup", "--help", "--ipc", "--mount", "--net", "--no-fork", "--pid", "--preserve-credentials", "--root", "--time", "--user", "--uts", "--version", "--wd", "-C", "-F", "-T", "-U", "-Z", "-a", "-i", "-m", "-n", "-p", "-u"], attached: ["-r", "-w"], commandString: [] },
     eval: { valueFlags: [], flags: [], commandString: [], viaShell: true },
     source: { valueFlags: [], flags: [], commandString: [], viaShell: true },
     ".": { valueFlags: [], flags: [], commandString: [], viaShell: true },
@@ -41,8 +42,27 @@ export const SHELL_WRAPPER_TABLE = {
     find: { valueFlags: [], flags: [], commandString: [], executes: ["-exec", "-execdir", "-ok", "-okdir"] },
     compgen: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
     complete: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
+    busybox: { valueFlags: [], flags: [], commandString: [] },
+    su: { valueFlags: ["--group", "--shell", "--supp-group", "--whitelist-environment", "-G", "-g", "-s", "-w"], flags: ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"], commandString: ["--command", "--session-command", "-c"], viaShell: true },
+    runuser: { valueFlags: ["--group", "--shell", "--supp-group", "--user", "--whitelist-environment", "-G", "-g", "-s", "-u", "-w"], flags: ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"], commandString: ["--command", "--session-command", "-c"], viaShell: true },
+    chroot: { valueFlags: [], flags: [], commandString: [], positional: /^/ },
+    setpriv: { valueFlags: [], flags: [], commandString: [] },
+    numactl: { valueFlags: [], flags: [], commandString: [] },
+    prlimit: { valueFlags: [], flags: [], commandString: [] },
+    "systemd-run": { valueFlags: [], flags: [], commandString: [] },
+    valgrind: { valueFlags: [], flags: [], commandString: [] },
+    firejail: { valueFlags: [], flags: [], commandString: [] },
+    bwrap: { valueFlags: [], flags: [], commandString: [] },
+    ash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    mksh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    yash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    pdksh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    parallel: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    alias: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    mapfile: { valueFlags: [], flags: [], commandString: [], executes: ["-C"] },
+    readarray: { valueFlags: [], flags: [], commandString: [], executes: ["-C"] },
 };
-export const VARIABLE_OPERAND_BUILTINS = new Set(["printf", "unset", "read", "mapfile", "readarray", "declare", "typeset", "local", "export", "readonly", "test", "[", "[["]);
+export const VARIABLE_OPERAND_BUILTINS = new Set(programRows().filter((row) => row.operands?.rest?.kind === "binds-name" || declaresOption(row, (spec) => spec.value?.kind === "binds-name")).map((row) => row.key));
 export function evaluatesOperand(run) {
     if (!VARIABLE_OPERAND_BUILTINS.has(run[0]?.text ?? ""))
         return false;

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

@@ -50,6 +50,7 @@
  * visibility probe from a model's call.
  */
 import type { ToolCallRequest, ToolCallFace, ToolPolicy } from "./tool-policy.js";
+import type { CallTargetStamp } from "./effective-path-target.js";
 import { type SkillGrantLane } from "./skill-grant.js";
 import type { OrgGateVerdict, PersistedRuleAnswer } from "./hooks.js";
 /** The layers the judge consults, as named in its verdicts. */
@@ -81,6 +82,8 @@ export interface SyntheticReadLayers {
     orgRuleLane?: {
         adjudicate: (req: ToolCallRequest) => Promise<OrgGateVerdict>;
     };
+    /** The leg's target-reading stamp: the probe's request carries a reading of its target, as the live gate's does. */
+    stampCallTarget?: CallTargetStamp;
     /** The run's signal, for the engine's own layers. */
     signal?: AbortSignal;
 }

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

@@ -15,13 +15,15 @@ export function createSyntheticReadJudge(layers) {
     return async (call, face, budget) => {
         const deadlineAt = budget?.deadlineAt ?? Date.now() + ORG_ADJUDICATION_TIMEOUT_MS;
         const left = () => Math.max(0, Math.min(ORG_ADJUDICATION_TIMEOUT_MS, deadlineAt - Date.now()));
-        const req = {
+        const probe = {
             toolName: "Read",
             args: { file_path: call.file_path, ...(call.offset !== undefined ? { offset: call.offset } : {}), ...(call.limit !== undefined ? { limit: call.limit } : {}) },
             toolCallId: syntheticReadProbeId(face),
             ...(call.cwd !== undefined ? { cwd: call.cwd } : {}),
             ...(call.face !== undefined ? { face: call.face } : {}),
         };
+        const stamped = layers.stampCallTarget?.(probe, layers.signal);
+        const req = stamped !== undefined ? await stamped : probe;
         let unanswered;
         const cannot = (layer, cause, reason) => {
             unanswered ??= { verdict: "unanswerable", layer, cause, reason };

package/dist/core/tool-catalog-entries.d.ts

@@ -47,3 +47,24 @@ export declare const ENGINE_CARDS: Readonly<Record<string, string>>;
 export declare function toolFace(id: string): ToolFaceDeclaration;
 /** Definition-id → face, for the modules that spread one (`...TOOL_FACES.read`). Frozen: a face is data. */
 export declare const TOOL_FACES: Readonly<Record<string, ToolFaceDeclaration>>;
+/**
+ * The engine's own tool names, once each: every catalog entry the engine mounts itself (`source: "builtin"` — the hands,
+ * the scaffolds, the memory tools, the background-task tools), whatever face or contract it is mounted under. A host that
+ * must hand the engine a tool face with NO built-ins (`TaskSpec.excludeTools`, a shell's `--tools ""`) reads this set
+ * instead of keeping a list of its own: the catalog is the one source, and a name the engine adds later lands here with it.
+ */
+export declare const ENGINE_BUILTIN_TOOL_NAMES: readonly string[];
+/**
+ * The engine's HAND tools, once each, with the other spellings they answer to: the catalog rows mounted by `hands` — what a run
+ * mounts for itself over an execution environment (the file and shell band, the worktree pair, the band's background-shell
+ * pair). A delegated child's tool-name lists govern these beside the tools the delegation tool hands it, so the spawn reads
+ * this set rather than a list of its own.
+ */
+export declare const HAND_TOOLS: ReadonlyArray<{
+    readonly name: string;
+    readonly aliases?: readonly string[];
+}>;
+/** The wire names of {@link HAND_TOOLS}. */
+export declare const HAND_TOOL_NAMES: readonly string[];
+/** Is this name one the engine mounts itself ({@link ENGINE_BUILTIN_TOOL_NAMES})? A caller tool, an MCP tool or a skill tool is not. */
+export declare function isEngineBuiltinToolName(name: string): boolean;

package/dist/core/tool-catalog-entries.js

@@ -8,7 +8,8 @@ export const TASK_LIST_TOOL_NAME = "TaskList";
 export const TODO_WRITE_TOOL_NAME = "TodoWrite";
 export const REFRESH_MCP_TOOLS_TOOL_NAME = "RefreshMcpTools";
 export const ARTIFACT_TOOL_NAME = "Artifact";
-const SHELL_RULE_FACE = { primaryParams: ["command"], params: ["command", "timeout", "description", "run_in_background"] };
+const shellRuleFace = (params) => ({ grammar: "command", primaryParams: ["command"], params });
+const SHELL_RULE_FACE = shellRuleFace(["command", "timeout", "description", "run_in_background"]);
 const c = (contractId, implementationRevision = "1") => ({ contractId, implementationRevision });
 export const TOOL_CATALOG_ENTRIES = [
     {
@@ -108,7 +109,7 @@ export const TOOL_CATALOG_ENTRIES = [
     { id: "task-stop-hands", name: "TaskStop", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"], cards: [], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
     { id: "task-output", name: "TaskOutput", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-output"], face: { family: "delegate", effect: "read", contract: TASK_OUTPUT_CONTRACT } },
     { id: "task-stop", name: "TaskStop", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-stop"], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
-    { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start", "readonly_out_of_root", "read_unestablished"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), offloadThresholdChars: 10_000 } },
+    { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start", "readonly_out_of_root", "read_unestablished"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), ruleFace: shellRuleFace(["command", "description", "timeout_ms", "persistent"]), offloadThresholdChars: 10_000 } },
     { id: "send-message", name: "SendMessage", source: "builtin", definedIn: "src/agents/send-message-tool.ts", mountedBy: ["delegation", "hostInternals", "peerLane"], cards: ["send-message"], face: { family: "protocol", effect: "write", contract: c("core.send_message@1") } },
     { id: "agent-transcript", name: "AgentTranscript", source: "builtin", definedIn: "src/agents/agent-transcript-tool.ts", mountedBy: ["delegation"], cards: ["agent-transcript"], face: { family: "delegate", effect: "read", contract: c("core.agent_transcript@1") } },
     { id: "list-agents", name: "ListAgents", source: "builtin", definedIn: "src/agents/list-agents-tool.ts", mountedBy: ["delegation", "peerLane"], cards: ["list-agents"], face: { family: "protocol", effect: "read", aliases: ["ListPeers"], contract: c("core.list_agents@1") } },
@@ -180,3 +181,12 @@ function deepFreeze(value) {
 }
 deepFreeze(TOOL_CATALOG_ENTRIES);
 export const TOOL_FACES = Object.freeze(Object.fromEntries(TOOL_CATALOG_ENTRIES.map((e) => [e.id, e.face])));
+export const ENGINE_BUILTIN_TOOL_NAMES = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.source === "builtin").map((e) => e.name))]);
+export const HAND_TOOLS = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.mountedBy.includes("hands")).map((e) => e.name))].map((name) => {
+    const aliases = [...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.name === name && e.mountedBy.includes("hands")).flatMap((e) => e.face.aliases ?? []))];
+    return Object.freeze(aliases.length > 0 ? { name, aliases: Object.freeze(aliases) } : { name });
+}));
+export const HAND_TOOL_NAMES = Object.freeze(HAND_TOOLS.map((t) => t.name));
+export function isEngineBuiltinToolName(name) {
+    return ENGINE_BUILTIN_TOOL_NAMES.includes(name);
+}

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

@@ -201,7 +201,16 @@ export interface ToolFaceDeclaration {
     };
     aliases?: string[];
     pathTarget?: ToolPathTarget;
-    ruleFace?: ToolRuleFace;
+    /**
+     * The rule face ({@link ToolRuleFace}) and, for a definition whose primary parameter is a shell command line, the grammar
+     * that judges it — `grammar: "command"`, the SHELL FACE. Every `Bash(<command>)` rule (the command grammar's one spelling,
+     * deny / ask / allow, from every source) is judged on a call that answers to the name of such a definition, against that
+     * parameter; a bare `Bash` rule stays a rule on the tool of that name. Only a catalog row declares it (a caller's
+     * `ToolSpec.ruleFace` is a {@link ToolRuleFace}): the static catalog is the one place the shell face is read from.
+     */
+    ruleFace?: ToolRuleFace & {
+        readonly grammar?: "command";
+    };
     renderHints?: ToolRenderHints;
     offload?: boolean;
     offloadThresholdChars?: number;

package/dist/core/tool-name-readings.d.ts

@@ -69,6 +69,10 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
+    readonly "gate.askFace": {
+        readonly kind: "wire";
+        readonly file: string;
+    };
     readonly "fold.readStation": {
         readonly kind: "seat";
         readonly rank: "member";
@@ -251,6 +255,10 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
+    readonly "inherited.askFace": {
+        readonly kind: "wire";
+        readonly file: string;
+    };
     readonly "park.contentKindProjection": {
         readonly kind: "wire";
         readonly file: string;

package/dist/core/tool-name-readings.js

@@ -19,6 +19,7 @@ export const NAME_READINGS = {
     "gate.sandboxBoundary.egress": any(CHAIN),
     "gate.sandboxBoundary.hand": wire(CHAIN),
     "gate.preToolUse": wire("src/core/hooks.ts"),
+    "gate.askFace": wire("src/core/runner/gate-exit.ts"),
     "fold.readStation": seat("member", "src/tools/fs/shell-read-check.ts"),
     "lanes.contentQuestionClass": any(LANES),
     "lanes.readOnlyShellAllow": wire(LANES),
@@ -63,6 +64,7 @@ export const NAME_READINGS = {
     "activity.sink": spelling(HANDLERS),
     "reconcile.orphanEffect": spelling("src/core/session-reconcile.ts"),
     "inherited.questionFloat": wire(CHAIN),
+    "inherited.askFace": wire(CHAIN),
     "park.contentKindProjection": wire("src/core/checkpoint-store.ts"),
     "resume.contentAskRow": wire("src/core/runner/decide-continuation.ts"),
     "resume.editRecheckQuestionSkip": wire("src/core/runner/resume-apply.ts"),

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

@@ -79,6 +79,17 @@ export interface ToolCallRequest {
      * Read-only, like `cwd`.
      */
     root?: string;
+    /** The call's target reading (`readCallTarget`: lexical / canonical / hop views per reading of the path slot), stamped by the Runner on a
+     *  leg whose lanes can hold a path rule; it describes only the `args` object it was taken for (`callTargetReadingOf`). Read-only. */
+    targetReading?: import("./effective-path-target.js").CallTargetReading;
+    /**
+     * An ENGINE-INTERNAL seat, not a fact of the call: the anchors of the policy now judging this request — the leg its
+     * path rules were installed on (`installPolicyAnchors`). Present only on the copy an installed policy hands its own
+     * inner `check` (where `createPermissionRulePolicy` reads it; an inner installation's anchors win over an outer one's);
+     * the request the gate holds, an `AskRequest`, a hook's input and a parked row never carry it. A host neither sets nor
+     * reads it.
+     */
+    pathRuleAnchors?: import("./permission-rule-model.js").PathRuleBases;
     /**
      * The CANONICAL directories THIS RUN'S PROMPT ADVERTISES AS WRITABLE — the admitted list of the root
      * fence's advertised-writable-directory seat (the memory engine's write home, the deployment's
@@ -537,11 +548,14 @@ export interface ToolPolicy {
      * describes the policy must read that bit, not the field's presence.
      */
     readonly projection?: ToolPolicyProjection;
-    /** The policy's path DENY rules that speak for a face of the engine's deny table (a `Read(<pattern>)` / `Edit(<pattern>)`
-     *  deny compiled by `createPermissionRulePolicy`), as rows the prepared leg joins to its read and write tables — so the
-     *  shell's reads and writes and the traversals meet the rule, not only the tool it names. Carried through
-     *  {@link combinePolicies}; read with {@link toolPolicyPathDenyRules}. Deny-only: a row can only refuse more. */
-    readonly pathDenyRules?: readonly import("../tools/fs/read-deny.js").PathRuleDenyRow[];
+    /** The policy's PATH rules as a function of the ANCHORS of the leg they are installed on (`createPermissionRulePolicy`
+     *  sets it; present exactly when the policy judges a path target): given the leg's root and home, every path rule
+     *  bound there — the face-keyed deny rows the prepared leg joins to its read and write tables (so the shell's reads and
+     *  writes and the traversals meet the rule, not only the tool it names), and the rows its own `check` judges at the
+     *  gate. A policy the Runner already installed answers with its own installation's rows whatever it is given. Carried
+     *  through {@link combinePolicies}; read with {@link toolPolicyPathRules}. Its presence also tells the Runner to read
+     *  each call's target ({@link ToolCallRequest.targetReading}). */
+    readonly pathRules?: (anchors: import("./permission-rule-model.js").PathRuleBases) => readonly import("./path-rule-binding.js").BoundPathRule[];
     /** Does this policy guard a write to this ABSOLUTE target — would it refuse the write if a write tool made it? The
      *  policy's answer for a writer it cannot see as a call (the shell's file commands), read by the shell station's
      *  `writesPlaced` fact alone: a guarded target is not placed, so no permission mode answers the command and its ask
@@ -558,9 +572,15 @@ export interface ToolPolicy {
  * each by name off the wrapped policy, {@link combinePolicies} folds each. The fence makes a new {@link ToolPolicy} member
  * a compile error until the table names it.
  */
-declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathDenyRules", "writeTargetGuard", "nameSets"];
+declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathRules", "writeTargetGuard", "nameSets"];
 type ToolPolicyCarriedMember = (typeof TOOL_POLICY_CARRIED_MEMBERS)[number];
 export type ToolPolicyCarriesEveryMember = AssertAllKeysHandled<Exclude<Exclude<keyof ToolPolicy, "check">, ToolPolicyCarriedMember>>;
+/** The carried members that are set on `p`, each read by name — an accessor or a non-enumerable member included. */
+export declare function carriedMembersOf(p: {
+    readonly [K in ToolPolicyCarriedMember]?: ToolPolicy[K];
+}): {
+    -readonly [K in ToolPolicyCarriedMember]?: ToolPolicy[K];
+};
 /**
  * The ONE way to wrap a policy: the wrapper decides through `check`; every member {@link ToolPolicy} declares beside it
  * (projection, name sets, path deny rows, write-target guard — the carried-member table) rides as `inner` holds it, read
@@ -570,8 +590,10 @@ export type ToolPolicyCarriesEveryMember = AssertAllKeysHandled<Exclude<Exclude<
  * The ask-class brand is not carried: it attests the replaced `check`.
  */
 export declare function wrapToolPolicy<P extends ToolPolicy>(inner: P, check: ToolPolicy["check"]): Pick<P, ToolPolicyCarriedMember> & ToolPolicy;
-/** Every path deny row the given policies carry (combined policies included), in order — the deny tables' rule rows. */
-export declare function toolPolicyPathDenyRules(policies: readonly (ToolPolicy | undefined)[]): readonly import("../tools/fs/read-deny.js").PathRuleDenyRow[];
+/** Every path rule the given policies carry (combined policies included), in order, bound at `anchors` — the anchors of
+ *  the leg the policies are installed on (a policy already installed answers with its own installation's rows). The deny
+ *  tables take the rows that guard a face (`faces` non-empty) of a deny rule. */
+export declare function toolPolicyPathRules(policies: readonly (ToolPolicy | undefined)[], anchors: import("./permission-rule-model.js").PathRuleBases): readonly import("./path-rule-binding.js").BoundPathRule[];
 /** The one write-target guard the given policies carry together (combined policies included): `true` when any member
  *  guards the target, a member that throws counting as guarding it. `undefined` when none carries one. */
 export declare function toolPolicyWriteTargetGuard(policies: readonly (ToolPolicy | undefined)[]): ToolPolicy["writeTargetGuard"];
@@ -955,13 +977,14 @@ export declare function createApprovalPolicy(opts: {
  */
 export declare function combinePolicies(...policies: ToolPolicy[]): ToolPolicy;
 /**
- * The shell tools whose `{ command }` arg a coarse command-name policy parses; other tools are out of scope. `Monitor`
- * belongs here: it runs an arbitrary shell `command` through the same env seam as Bash, so the always-on parity gates
- * keyed on this list reach it too (a list of `Bash` alone let the identical command run ungated as `Monitor`). EXPORTED:
- * a downstream governance layer keeps its own copy of this list so its per-command ask-list gates the same tools core
- * does — the list itself is the fact, and publishing it removes the guess.
+ * The shell tools whose `{ command }` arg a coarse command-name policy parses; other tools are out of scope. It is the
+ * catalog's shell face ({@link shellFaceToolNames} — every definition whose `command` the command grammar judges, `Monitor`
+ * among them: it runs an arbitrary shell `command` through the same env seam as Bash), spelled out for the wire; the
+ * catalog's shell face is the truth, and a lockstep pin keeps the two one (a catalog row added or dropped turns it red):
+ * the always-on parity gates keyed on it, the `Bash(...)` rules and the shell seat reach the same tools. EXPORTED: a
+ * downstream governance layer reads it so its per-command ask-list gates the same tools core does.
  */
-export declare const COARSE_SHELL_TOOLS: string[];
+export declare const COARSE_SHELL_TOOLS: readonly ["Bash", "Monitor"];
 /**
  * design/center §10 — a COARSE allow/deny gate keyed on the LEADING command NAME (`argv[0]`) of a single
  * simple shell command. It reuses the ONE shared simple-command parser
@@ -1011,7 +1034,7 @@ export declare function createCoarseCommandNamePolicy(opts: {
     deny?: string[];
     /** What to do for a command not matched by `allow` (or un-parseable): `"ask"` (default) or `"deny"`. */
     defaultAction?: "ask" | "deny";
-    /** Override the shell tool names this gate parses (default `Bash` — bash + bash_readonly share the CC name). */
+    /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
 }): ToolPolicy;
 export declare function findUnverifiableRecursiveDelete(command: string, safeVars?: ReadonlySet<string>): string | undefined;
@@ -1090,7 +1113,7 @@ export declare function createUnverifiableDeletePolicy(opts?: {
      *  the default was `TMPDIR` alone, reading STRICTER than the gate really is; `HOME`/`PWD` are a
      *  registered sema divergence from CC's temp-only carve-out, see the RB-340 note there). */
     safeVars?: readonly string[];
-    /** Override the shell tool names this gate parses (default `Bash`). */
+    /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
     removalSeat?: RemovalGuardSeat;
 }): ToolPolicy;
@@ -1099,7 +1122,7 @@ export declare function createTranscriptIntegrityPolicy(opts?: {
     sessionsDirs?: readonly string[];
     /** argv[0] allowlist for read-only access to the transcript dir (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
     readAllow?: readonly string[];
-    /** Override the shell tool names this gate parses (default `Bash`). */
+    /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
 }): ToolPolicy;
 /**

package/dist/core/tool-policy.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
+import { withArgsReading } from "./effective-path-target.js";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { decisionAskClassesOf, headlessDenialMessage } from "./ask-origin.js";
 import { ownReadRootCandidate, readRootGrantSeat } from "./read-root-grant-screen.js";
@@ -9,7 +10,7 @@ export { policyCannotAnswer, rowDemandsAPerson } from "./real-approval.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
-import { protectivePathTargetOf } from "./tool-registry.js";
+import { protectivePathTargetOf, shellFaceToolNames } from "./tool-registry.js";
 import { heldBy } from "./tool-name-readings.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
@@ -137,8 +138,8 @@ export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "una
 export function decisionText(d) {
     return d.message;
 }
-const TOOL_POLICY_CARRIED_MEMBERS = ["projection", "pathDenyRules", "writeTargetGuard", "nameSets"];
-function carriedMembersOf(p) {
+const TOOL_POLICY_CARRIED_MEMBERS = ["projection", "pathRules", "writeTargetGuard", "nameSets"];
+export function carriedMembersOf(p) {
     const out = {};
     const carry = (k) => {
         const v = p[k];
@@ -152,8 +153,8 @@ function carriedMembersOf(p) {
 export function wrapToolPolicy(inner, check) {
     return { ...carriedMembersOf(inner), check };
 }
-export function toolPolicyPathDenyRules(policies) {
-    return policies.flatMap((p) => (Array.isArray(p?.pathDenyRules) ? p.pathDenyRules : []));
+export function toolPolicyPathRules(policies, anchors) {
+    return policies.flatMap((p) => (typeof p?.pathRules === "function" ? p.pathRules(anchors) : []));
 }
 export function toolPolicyWriteTargetGuard(policies) {
     const guards = policies.flatMap((p) => (typeof p?.writeTargetGuard === "function" ? [p.writeTargetGuard] : []));
@@ -514,7 +515,7 @@ export function createApprovalPolicy(opts) {
 }
 export function combinePolicies(...policies) {
     const nameSets = policies.flatMap(toolPolicyNameSets);
-    const pathDenyRules = toolPolicyPathDenyRules(policies);
+    const pathRuled = policies.filter((p) => typeof p?.pathRules === "function");
     const writeTargetGuard = toolPolicyWriteTargetGuard(policies);
     const childProjections = policies.map((p) => p.projection);
     const projectedComponents = [];
@@ -536,7 +537,7 @@ export function combinePolicies(...policies) {
     const folded = {
         projection: combinedProjection,
         nameSets: nameSets.length > 0 ? nameSets : undefined,
-        pathDenyRules: pathDenyRules.length > 0 ? pathDenyRules : undefined,
+        pathRules: pathRuled.length > 0 ? (anchors) => toolPolicyPathRules(pathRuled, anchors) : undefined,
         writeTargetGuard,
     };
     return {
@@ -576,7 +577,8 @@ export function combinePolicies(...policies) {
                     continue;
                 }
                 if (d.updatedInput !== undefined) {
-                    current = { ...current, args: d.updatedInput };
+                    const reread = withArgsReading(current, d.updatedInput, signal);
+                    current = reread !== undefined ? await reread : { ...current, args: d.updatedInput };
                     rewrite = d;
                     stated = d.action === "allow" ? d.decisionReason : undefined;
                 }
@@ -640,7 +642,7 @@ export function combinePolicies(...policies) {
         },
     };
 }
-export const COARSE_SHELL_TOOLS = ["Bash", "Monitor"];
+export const COARSE_SHELL_TOOLS = Object.freeze(["Bash", "Monitor"]);
 function canonicalToolNameSet(tools) {
     return new Set(tools ?? COARSE_SHELL_TOOLS);
 }

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

@@ -25,6 +25,15 @@ export declare function catalogToolNames(): ReadonlySet<string>;
 export declare function pathConfinableWriteToolNames(): ReadonlySet<string>;
 /** A-8 — every definition that names a path target at all (read or write): the file-tool glob lane. */
 export declare function pathTargetingToolNames(): ReadonlySet<string>;
+/**
+ * The SHELL FACE: every definition whose `command` argument is a shell command line the command grammar judges (today the two
+ * `Bash` definitions and `Monitor`). A `Bash(<command>)` rule reaches a call that answers to any of these names; the coarse
+ * command-name gate's default list, the shell read station and the shell seat are this set. Derived from the rows' rule faces,
+ * never a list of its own.
+ */
+export declare function shellFaceToolNames(): ReadonlySet<string>;
+/** {@link shellFaceToolNames}' membership for one name — any definition under the name on the shell face. */
+export declare function isShellFaceToolName(name: string): boolean;
 /** The tools whose declared path target is a READ (a file read, a search root): the file read station's membership. */
 export declare function readTargetToolNames(): ReadonlySet<string>;
 /** A-10 — the micro-compaction whitelist (`compactable: true`). */

package/dist/core/tool-registry.js

@@ -29,6 +29,16 @@ export function pathConfinableWriteToolNames() {
 export function pathTargetingToolNames() {
     return names((e) => e.face.pathTarget !== undefined);
 }
+const onShellFace = (e) => e.face.ruleFace?.grammar === "command";
+export function shellFaceToolNames() {
+    return names(onShellFace);
+}
+export function isShellFaceToolName(name) {
+    for (const e of TOOL_CATALOG_ENTRIES)
+        if (e.name === name && onShellFace(e))
+            return true;
+    return false;
+}
 export function readTargetToolNames() {
     return names((e) => e.face.pathTarget?.access === "read");
 }

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

@@ -212,8 +212,9 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * carries its own tool set, and a parent that mounts nothing but the delegation tool can still hand
      * its children a network tool, so the parent's roster is the wrong thing to look at.
      *
-     * ABSENT ⇔ the pool is not statically knowable — a spawn-time tool factory can inject tools whose
-     * identity does not exist until the call happens — and the reader fails closed on that.
+     * ABSENT ⇔ the pool is not statically knowable — a spawn-time tool factory with no declared roster
+     * (`SubagentToolOptions.extraToolNames`) can inject tools whose identity does not exist until the call
+     * happens — and the reader fails closed on that. A declared roster's tools are rows of the pool.
      */
     agentToolPool?: ReadonlyArray<{
         name: string;

package/dist/core/write-protect.d.ts

@@ -1,5 +1,6 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { PermissionResult } from "./tool-policy.js";
+import { type AskFace } from "./ask-origin.js";
 import { type ToolCallLike } from "./tool-registry.js";
 /**
  * How one table row matches the judged path:
@@ -173,6 +174,10 @@ export interface WriteProtectionCompileOptions {
      *  path-family source when the call carries no cwd. Omitted ⇒ relative spellings resolve against the
      *  cwd, then the environment's own working directory. */
     readonly rootPath?: string;
+    /** The host's configuration root when it keeps the agent's configuration directory somewhere other than the home's
+     *  `.sema` (`RunnerDeps.agentConfigDir`, absolute, already screened): every row that names the `.sema` directory also
+     *  names the same tail below this root, and a hit there cites the row. Omitted ⇒ the table is judged as it stands. */
+    readonly agentConfigDir?: string;
     /**
      * Called at most ONCE per judgment, at the moment the ENVIRONMENT half is found unable to contribute
      * ({@link WriteProtectionViewAbsence}) — before the judgment returns, and on the hit arm as well as the
@@ -205,11 +210,17 @@ export declare function compileWriteProtection(entries?: readonly WriteProtected
  *    message (table names are deployment-validated vocabulary); the model-authored target path deliberately
  *    does not — `message` is the classifier's `askMessage`, and the approval card already shows the args. The
  *    spelling form's sentence is the historical one byte for byte; the target form says the target RESOLVED.
- *  · `unresolvable` ⇒ `deny` naming the cause: an unjudged target is never vouched, and an ask would be a
- *    question about a file nobody can name — the rule the canonicalizing deny set follows for the same reason.
+ *  · `unresolvable` ⇒ read by the call's FACE (`face`, {@link releasableAskClassesFor}): where no permission mode releases
+ *    `write_protection_unresolved` (the file face) — `deny` naming the cause: an unjudged target is never vouched (the rule
+ *    the canonicalizing deny set follows for the same reason), so there a standing allow is refused while a standing ask
+ *    carrying the record stays a person's question in the modes that ask (dontAsk and bypassPermissions refuse it); where
+ *    a mode may release the class (the shell face) — `ask` (`safety`)
+ *    naming the cause, which the mode arbitration answers exactly as it answers that record over a standing ask
+ *    (bypassPermissions releases it, default puts it to a person, dontAsk refuses): on that face alone a standing allow
+ *    reads as a standing ask.
  *  · `clear` ⇒ `undefined`: the surviving decision stands.
  */
-export declare function writeProtectionTightenDecision(toolName: string, verdict: WriteProtectionVerdict): PermissionResult | undefined;
+export declare function writeProtectionTightenDecision(toolName: string, verdict: WriteProtectionVerdict, face: AskFace): PermissionResult | undefined;
 /**
  * @contract write_protection.verdict_is_the_mandate — the judge's two non-clear verdicts are the two facts
  * a standing allow rule may not retire, and `clear` is neither: a MATCHED row is the mandate a live decider