@sema-agent/core 7.9.0 → 7.9.2

package/dist/core/shell-scan.js

@@ -0,0 +1,183 @@
+const SPECIAL_PARAMS = "?$!#@*-0123456789";
+const SUBSTITUTION_RE = /\$\(|`|<\(|>\(|\$\[/;
+export const arithmeticHidesRun = (expr) => /[^\s\d+\-*/%&|^~!<>=?:,()]/.test(expr);
+const SUBSCRIPT_RE = /\$\{[!#]?[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*[A-Za-z_$]|(?:\[[^\]]*\])?:(?![-=+?])[^}]*[A-Za-z_$])/;
+export const carriesSubstitution = (text) => { const t = text.replace(/\\\n/g, ""); return SUBSTITUTION_RE.test(t) || SUBSCRIPT_RE.test(t); };
+const PER_ELEMENT_RE = /^\$@$|^\$\{!?@|\[@\]|^\$\{![^}]*@\}$/;
+export const freshWord = () => ({ text: "", raw: "", expands: false, started: false, braceOpen: false, braceExpands: false, bracketOpen: false, substitution: false });
+export function readDoubleQuoted(s, i, word) {
+    word.started = true;
+    while (i < s.length) {
+        const ch = s[i];
+        if (ch === '"')
+            return i + 1;
+        if (ch === "\\") {
+            const next = s[i + 1];
+            if (next === undefined)
+                return undefined;
+            if (next === "\n") {
+                i += 2;
+                continue;
+            }
+            if ('$`"\\'.includes(next)) {
+                word.text += next;
+                i += 2;
+                continue;
+            }
+            word.text += ch;
+            i++;
+            continue;
+        }
+        if (ch === "$" || ch === "`") {
+            const end = readExpansion(s, i, word, true);
+            if (end === undefined)
+                return undefined;
+            if (end === i + 1) {
+                word.text += ch;
+                i = end;
+                continue;
+            }
+            if (PER_ELEMENT_RE.test(s.slice(i, end).replace(/\\\n/g, "")))
+                word.expands = "many";
+            else if (word.expands === false)
+                word.expands = "one";
+            i = end;
+            continue;
+        }
+        word.text += ch;
+        i++;
+    }
+    return undefined;
+}
+export function readExpansion(s, i, word, inDoubleQuotes = false) {
+    if (s[i] === "`") {
+        word.substitution = true;
+        for (let j = i + 1; j < s.length; j += s[j] === "\\" ? 2 : 1)
+            if (s[j] === "`")
+                return j + 1;
+        return undefined;
+    }
+    let o = i + 1;
+    while (s[o] === "\\" && s[o + 1] === "\n")
+        o += 2;
+    const next = s[o];
+    if (next === undefined)
+        return i + 1;
+    if (next === "(") {
+        const end = skipBalanced(s, o, "(", ")");
+        if (end === undefined)
+            return undefined;
+        if (s[i] !== "$" || s[o + 1] !== "(" || arithmeticHidesRun(s.slice(o + 2, end - 2)))
+            word.substitution = true;
+        return end;
+    }
+    if (next === "[") {
+        const end = s.indexOf("]", o);
+        word.substitution = true;
+        return end < 0 ? undefined : end + 1;
+    }
+    if (next === "{") {
+        const end = skipBalanced(s, o, "{", "}");
+        if (end !== undefined && carriesSubstitution(s.slice(i, end)))
+            word.substitution = true;
+        return end;
+    }
+    if (next === "'" && !inDoubleQuotes) {
+        let j = o + 1;
+        while (j < s.length && s[j] !== "'")
+            j += s[j] === "\\" ? 2 : 1;
+        return j < s.length ? j + 1 : undefined;
+    }
+    if (/[A-Za-z_]/.test(next)) {
+        let j = o + 1;
+        while (j < s.length && /[A-Za-z0-9_]/.test(s[j]))
+            j++;
+        return j;
+    }
+    return SPECIAL_PARAMS.includes(next) ? o + 1 : i + 1;
+}
+export function skipBalanced(s, i, open, close) {
+    const stack = [];
+    for (let j = i; j < s.length; j++) {
+        const ch = s[j];
+        const top = stack[stack.length - 1];
+        if (ch === "\\") {
+            j++;
+            continue;
+        }
+        if (top?.quote === true) {
+            if (ch === '"')
+                top.quote = false;
+            else if (ch === "$" && (s[j + 1] === "(" || s[j + 1] === "{")) {
+                stack.push({ closer: s[j + 1] === "(" ? ")" : "}", quote: false });
+                j++;
+            }
+            else if (ch === "`") {
+                const k = s.indexOf("`", j + 1);
+                if (k < 0)
+                    return undefined;
+                j = k;
+            }
+            continue;
+        }
+        if (ch === "'") {
+            const k = s.indexOf("'", j + 1);
+            if (k < 0)
+                return undefined;
+            j = k;
+            continue;
+        }
+        if (ch === '"') {
+            if (top !== undefined)
+                top.quote = true;
+            continue;
+        }
+        if (ch === "`") {
+            const k = s.indexOf("`", j + 1);
+            if (k < 0)
+                return undefined;
+            j = k;
+            continue;
+        }
+        if (ch === open || ch === "(" || ch === "{") {
+            stack.push({ closer: ch === "(" ? ")" : "}", quote: false });
+            continue;
+        }
+        if (ch === close || ch === ")" || ch === "}") {
+            if (stack.pop()?.closer !== ch)
+                return undefined;
+            if (stack.length === 0)
+                return j + 1;
+        }
+    }
+    return undefined;
+}
+export function skipHeredocBodies(s, i, docs) {
+    let substitution = false;
+    for (const { delimiter, quoted, dash } of docs) {
+        for (;;) {
+            if (i >= s.length)
+                return undefined;
+            let eol = s.indexOf("\n", i);
+            let line = s.slice(i, eol < 0 ? s.length : eol);
+            while (!quoted && eol >= 0 && (/\\+$/.exec(line)?.[0].length ?? 0) % 2 === 1) {
+                const next = s.indexOf("\n", eol + 1);
+                line = line.slice(0, -1) + s.slice(eol + 1, next < 0 ? s.length : next);
+                eol = next;
+            }
+            i = eol < 0 ? s.length : eol + 1;
+            if ((dash ? line.replace(/^\t+/, "") : line) === delimiter)
+                break;
+            if (!quoted && carriesSubstitution(line))
+                substitution = true;
+        }
+    }
+    return { end: i, substitution };
+}
+export function matchOp(s, i, ops) {
+    let best;
+    for (const op of ops)
+        if (s.startsWith(op, i) && (best === undefined || op.length > best.length))
+            best = op;
+    return best;
+}

package/dist/core/shell-wrapper-table.d.ts

@@ -0,0 +1,297 @@
+/**
+ * The wrapper programs the tightening reader ({@link import("./shell-lexer.js").readShellCommand}) peels to
+ * reach the program they run — upstream's three tables (its light strip on every arm, its full strip on
+ * the deny/ask arms, and its `xargs` clause inlined in the matcher) as ONE closed table. Peeling is
+ * ADDITIVE on the reading side: the segment keeps its spelled argv as one run candidate and adds one
+ * candidate per peeled layer, so a deny on the wrapper itself (`Bash(sudo:*)`) and a deny on the wrapped
+ * program both reach.
+ *
+ * The option grammar of every row is CLOSED, and that is the whole safety argument of the peel: a
+ * wrapper option the row does not name — short or long — stops the peel with an `unreadable` word (the
+ * caller asks a person) instead of guessing its arity, because a wrong guess names the option's VALUE
+ * or an operand as the program — a phantom run no deny matches. Three adversarial rounds found exactly
+ * that shape behind every "unknown is value-less" reading; the closed sets end the family rather than
+ * the instance. Growing a row is a data edit with upstream's manual page as its source.
+ *
+ * Per row: `valueFlags` — options whose value is the NEXT word (`-u root`; the attached `-uroot` and
+ * `--user=root` spellings are one word and need no row); `flags` — value-less options, including those
+ * whose value may only be ATTACHED (`--default-signal[=SIG]`, `xargs -i[R]`: bare, they take nothing);
+ * `attached` — short options whose OPTIONAL value may only be attached (`xargs -i[R]`: the rest of the cluster
+ * is the value, the next word never is); `commandString` — options whose value is a whole COMMAND STRING (`env -S 'rm -r x'`), unreadable here;
+ * `positional` — an operand that must precede the command (a priority, a cpu mask, a lock file; a word
+ * that does not match is unreadable, never the program); `duration` — `timeout`'s duration word;
+ * `bareDash` — `env -` (the obsolete spelling of `-i`); `assignments` — the wrapper takes `NAME=value`
+ * operands before its command (`env`, `sudo`; read dequoted, `env 'FOO=1' cmd`); `viaShell` — the program EVALUATES its
+ * operands as shell input (a command string, a script file, an expression: `watch`, `script`, `eval`,
+ * `source`, `bash -c`, `trap`, `let`), so the program behind it is never readable from the words — the
+ * string is not split and judged (upstream splits on whitespace; this reader takes the strict word);
+ * `executes` — a program that is NOT a wrapper but runs a command named after one of these words ANYWHERE
+ * in its argv (`find … -exec rm -r {} +`): such a word, or any expansion among its arguments (it could
+ * expand to that word), makes the program behind it unreadable; the program's own run is still read.
+ */
+export declare const SHELL_WRAPPER_TABLE: {
+    readonly command: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["-p"];
+        readonly commandString: readonly [];
+    };
+    readonly builtin: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly noglob: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly nocorrect: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly exec: {
+        readonly valueFlags: readonly ["-a"];
+        readonly flags: readonly ["-c", "-l"];
+        readonly commandString: readonly [];
+    };
+    readonly env: {
+        readonly valueFlags: readonly ["-u", "-C", "-a", "-P", "--unset", "--chdir", "--argv0"];
+        readonly flags: readonly ["-i", "-0", "-v", "--ignore-environment", "--null", "--debug", "--list-signal-handling", "--default-signal", "--ignore-signal", "--block-signal", "--help", "--version"];
+        readonly commandString: readonly ["-S", "--split-string"];
+        readonly bareDash: true;
+        readonly assignments: true;
+    };
+    readonly sudo: {
+        readonly valueFlags: readonly ["-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"];
+        readonly flags: readonly ["-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"];
+        readonly commandString: readonly [];
+        readonly assignments: true;
+    };
+    readonly doas: {
+        readonly valueFlags: readonly ["-a", "-u", "-C"];
+        readonly flags: readonly ["-L", "-n", "-s"];
+        readonly commandString: readonly [];
+    };
+    readonly pkexec: {
+        readonly valueFlags: readonly ["--user"];
+        readonly flags: readonly ["--disable-internal-agent", "--keep-cwd", "--version", "--help"];
+        readonly commandString: readonly [];
+    };
+    readonly nohup: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly time: {
+        readonly valueFlags: readonly ["-o", "--output", "-f", "--format"];
+        readonly flags: readonly ["-p", "-a", "-v", "-q", "--append", "--portability", "--verbose", "--quiet", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly nice: {
+        readonly valueFlags: readonly ["-n", "--adjustment"];
+        readonly flags: readonly ["--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly timeout: {
+        readonly valueFlags: readonly ["-k", "-s", "--kill-after", "--signal"];
+        readonly flags: readonly ["-v", "--foreground", "--preserve-status", "--verbose", "--help", "--version"];
+        readonly commandString: readonly [];
+        readonly duration: true;
+    };
+    readonly stdbuf: {
+        readonly valueFlags: readonly ["-i", "-o", "-e", "--input", "--output", "--error"];
+        readonly flags: readonly ["--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly xargs: {
+        readonly valueFlags: readonly ["-n", "-L", "-P", "-I", "-d", "-s", "-a", "-E", "--max-args", "--max-procs", "--delimiter", "--max-chars", "--arg-file", "--process-slot-var"];
+        readonly flags: readonly ["-0", "-r", "-t", "-x", "-p", "-o", "--null", "--no-run-if-empty", "--verbose", "--exit", "--interactive", "--open-tty", "--show-limits", "--help", "--version", "--replace", "--eof", "--max-lines"];
+        readonly attached: readonly ["-i", "-l"];
+        readonly commandString: readonly [];
+    };
+    readonly watch: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly ionice: {
+        readonly valueFlags: readonly ["-c", "-n", "-p", "-P", "-u", "--class", "--classdata", "--pid", "--pgid", "--uid"];
+        readonly flags: readonly ["-t", "--ignore", "-h", "--help", "-V", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly setsid: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["-c", "-f", "-w", "--ctty", "--fork", "--wait", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly taskset: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["-a", "-p", "-c", "--all-tasks", "--pid", "--cpu-list", "--help", "--version"];
+        readonly commandString: readonly [];
+        readonly positional: RegExp;
+    };
+    readonly chrt: {
+        readonly valueFlags: readonly ["-p", "--pid", "-T", "-P", "-D", "--sched-runtime", "--sched-period", "--sched-deadline"];
+        readonly flags: readonly ["-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"];
+        readonly commandString: readonly [];
+        readonly positional: RegExp;
+    };
+    readonly strace: {
+        readonly valueFlags: readonly ["-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"];
+        readonly flags: readonly ["-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"];
+        readonly commandString: readonly [];
+    };
+    readonly ltrace: {
+        readonly valueFlags: readonly ["-a", "-A", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-x", "-D", "-F", "--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "-w", "--where"];
+        readonly flags: readonly ["-c", "-C", "-f", "-i", "-L", "-r", "-S", "-t", "-tt", "-ttt", "-T", "-V", "--demangle", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly flock: {
+        readonly valueFlags: readonly ["-w", "-E", "--timeout", "--wait", "--conflict-exit-code"];
+        readonly flags: readonly ["-s", "-x", "-u", "-n", "-o", "-F", "--shared", "--exclusive", "--unlock", "--nonblock", "--nb", "--close", "--no-fork", "--verbose", "--help", "--version"];
+        readonly commandString: readonly ["-c", "--command"];
+        readonly positional: RegExp;
+    };
+    readonly script: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly ["-c", "--command"];
+        readonly viaShell: true;
+    };
+    readonly unshare: {
+        readonly valueFlags: readonly ["-R", "-w", "-S", "-G", "--setuid", "--setgid", "--root", "--wd", "--propagation", "--setgroups", "--monotonic", "--boottime", "--map-user", "--map-group"];
+        readonly flags: readonly ["-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"];
+        readonly commandString: readonly [];
+    };
+    readonly nsenter: {
+        readonly valueFlags: readonly ["-t", "-S", "-G", "--target", "--setuid", "--setgid"];
+        readonly flags: readonly ["-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"];
+        readonly commandString: readonly [];
+    };
+    readonly eval: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly source: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly ".": {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly trap: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly let: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly sh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly bash: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly zsh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly dash: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly ksh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly fish: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly csh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly tcsh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly find: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-exec", "-execdir", "-ok", "-okdir"];
+    };
+    readonly compgen: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-C", "-F"];
+    };
+    readonly complete: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-C", "-F"];
+    };
+};
+export type ShellWrapperName = keyof typeof SHELL_WRAPPER_TABLE;
+/** The shape of one row (see the table's contract). */
+export interface ShellWrapperRow {
+    readonly valueFlags: readonly string[];
+    readonly flags: readonly string[];
+    readonly attached?: readonly string[];
+    readonly commandString: readonly string[];
+    readonly positional?: RegExp;
+    readonly duration?: true;
+    readonly bareDash?: true;
+    readonly assignments?: true;
+    readonly viaShell?: true;
+    readonly executes?: readonly string[];
+}
+/** Builtins whose OPERANDS name variables: an operand spelling an array element with a non-numeric
+ *  subscript (`arr[a]`, quoted, bare, attached `-varr[a]`, or `arr[a]=1`) is evaluated as arithmetic —
+ *  recursively, like `$((a))` — when the builtin reads or writes it (`printf -v 'arr[a]' …`, `unset arr[a]`,
+ *  `declare arr[a]=1`, `read arr[a]`, `[[ -v arr[a] ]]`, `test -v arr[a]`), and so is the value of an
+ *  INTEGER-attribute assignment (`declare -i x=a`). The lexer marks such a run's hidden run at every peel
+ *  candidate (`command printf -v …`). An operand that is WHOLLY an expansion is not judged here (`unset "$X"`
+ *  — one more indirection; the price of reading it would be a prompt on every `export FOO="$BAR"`), nor is
+ *  an arithmetic comparison's operand (`[[ $n -gt 0 ]]` evaluates `$n` — the same price). */
+export declare const VARIABLE_OPERAND_BUILTINS: ReadonlySet<string>;
+/** Does this run of a variable-operand builtin evaluate an operand arithmetically? Linear in the words. */
+export declare function evaluatesOperand(run: readonly {
+    readonly text: string;
+    readonly raw: string;
+}[]): boolean;

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

@@ -0,0 +1,58 @@
+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: [] },
+    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: [] },
+    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: [] },
+    eval: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    source: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    ".": { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    trap: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    let: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    sh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    bash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    zsh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    dash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    ksh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    fish: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    csh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    tcsh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    find: { valueFlags: [], flags: [], commandString: [], executes: ["-exec", "-execdir", "-ok", "-okdir"] },
+    compgen: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
+    complete: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
+};
+export const VARIABLE_OPERAND_BUILTINS = new Set(["printf", "unset", "read", "mapfile", "readarray", "declare", "typeset", "local", "export", "readonly", "test", "[", "[["]);
+export function evaluatesOperand(run) {
+    if (!VARIABLE_OPERAND_BUILTINS.has(run[0]?.text ?? ""))
+        return false;
+    const integer = run.some((w) => /^-[A-Za-z]*i/.test(w.text));
+    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));
+}

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

@@ -15,7 +15,7 @@ export const TOOL_CATALOG_ENTRIES = [
         cards: ["text", "notebook", "file_unchanged", "image", "document"],
         face: {
             family: "file-read", effect: "read", contract: c("core.read@1"),
-            pathTarget: { param: "file_path", aliases: ["path"], access: "read" },
+            pathTarget: { param: "file_path", aliases: ["path"], access: "read", base: "cwd", absent: "none" },
             ruleFace: { params: ["file_path", "path", "offset", "limit", "pages"] },
             renderHints: { summaryParams: ["file_path"] },
             offload: false, compactable: true, budgetExempt: true,
@@ -26,7 +26,7 @@ export const TOOL_CATALOG_ENTRIES = [
         cards: ["edit"],
         face: {
             family: "file-write", effect: "write", contract: c("core.edit@1"),
-            pathTarget: { param: "file_path", aliases: ["path"], access: "edit", skillScopeEligible: true },
+            pathTarget: { param: "file_path", aliases: ["path"], access: "edit", skillScopeEligible: true, base: "cwd", absent: "none" },
             ruleFace: { params: ["file_path", "path", "old_string", "new_string", "replace_all"] },
             renderHints: { summaryParams: ["file_path"], approvalCard: "file-edit" },
             compactable: true,
@@ -37,7 +37,7 @@ export const TOOL_CATALOG_ENTRIES = [
         cards: ["create", "update"],
         face: {
             family: "file-write", effect: "write", contract: c("core.write@1"),
-            pathTarget: { param: "file_path", aliases: ["path"], access: "create", skillScopeEligible: true },
+            pathTarget: { param: "file_path", aliases: ["path"], access: "create", skillScopeEligible: true, base: "cwd", absent: "none" },
             ruleFace: { params: ["file_path", "path", "content"] },
             renderHints: { summaryParams: ["file_path"], approvalCard: "file-write" },
             offload: false, compactable: true,
@@ -48,7 +48,7 @@ export const TOOL_CATALOG_ENTRIES = [
         cards: ["notebook-edit"],
         face: {
             family: "file-write", effect: "write", contract: c("core.notebook_edit@1"),
-            pathTarget: { param: "notebook_path", aliases: ["path"], access: "edit" },
+            pathTarget: { param: "notebook_path", aliases: ["path"], access: "edit", base: "cwd", absent: "none" },
             ruleFace: { params: ["notebook_path", "path", "cell_id", "cell_type", "edit_mode", "new_source"] },
             renderHints: { userFacingName: "Edit Notebook", summaryParams: ["notebook_path"], approvalCard: "notebook-edit" },
         },
@@ -78,7 +78,7 @@ export const TOOL_CATALOG_ENTRIES = [
         cards: ["grep"],
         face: {
             family: "search", effect: "read", contract: c("core.grep@1"),
-            pathTarget: { param: "path", access: "read" },
+            pathTarget: { param: "path", access: "read", base: "root", absent: "base" },
             ruleFace: { params: ["pattern", "path", "glob", "type", "output_mode", "head_limit", "offset", "multiline", "context", "ignore_case", "-i", "-n", "-o", "-A", "-B", "-C"] },
             renderHints: { userFacingName: "Search", summaryParams: ["pattern", "path"] },
             offloadThresholdChars: 20_000, compactable: true,
@@ -89,7 +89,7 @@ export const TOOL_CATALOG_ENTRIES = [
         cards: ["glob"],
         face: {
             family: "search", effect: "read", contract: c("core.glob@1"),
-            pathTarget: { param: "path", access: "read" },
+            pathTarget: { param: "path", access: "read", base: "root", absent: "base", patternParam: "pattern" },
             ruleFace: { params: ["pattern", "path", "max_results"] },
             renderHints: { userFacingName: "Search", summaryParams: ["pattern", "path"] },
             compactable: true,