@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/security/harness-guard/gates.js

@@ -0,0 +1,791 @@
+/**
+ * `@boombot/security` — deterministic tool gates (layer: `'gates'`).
+ *
+ * Fail-closed static checks that run *before* a tool executes:
+ *
+ * - `tokenizeBash` / `analyzeBash` — a hand-written bash tokenizer (quotes,
+ *   escapes, comments, operators, `$(...)`, backticks, `${...}`) plus a
+ *   rule-based risk classifier. Deterministic: the same command always yields
+ *   the same risk. When in doubt it escalates (fail-closed).
+ * - `checkHttpUrl` — outbound URL gate: protocol check, userinfo (credential
+ *   in URL) check, and hostname allowlist with `*.example.com` wildcards.
+ * - `evaluateToolCall` — the entry point the verifier imports. Routes a tool
+ *   call through deny-list / approval-list / bash-like / http-like gates.
+ *
+ * Zero dependencies. Findings are mapped to a severity and passed to `decide()`
+ * from `./policy.js` so `GuardMode` semantics stay in one place; clean checks
+ * (no finding at all) allow directly, so strict mode never denies a command
+ * or URL that nothing flagged. Every finding's reason names the exact
+ * construct that was caught.
+ */
+import { isAbsolute, resolve, sep } from 'node:path';
+import { decide } from './policy.js';
+/** Layer tag attached to every verdict produced by this module. */
+const LAYER = 'gates';
+const RISK_ORDER = ['low', 'medium', 'high', 'critical'];
+function maxRisk(a, b) {
+    return RISK_ORDER.indexOf(a) >= RISK_ORDER.indexOf(b) ? a : b;
+}
+function truncate(s, max = 160) {
+    return s.length > max ? `${s.slice(0, max - 3)}...` : s;
+}
+// ---------------------------------------------------------------------------
+// tokenizeBash
+// ---------------------------------------------------------------------------
+/**
+ * Tokenize a bash command line.
+ *
+ * Handles single/double quotes (quote-aware, quotes stripped from the token
+ * value), backslash escapes, `#` comments (only at the start of a word,
+ * outside quotes), and emits operators as standalone tokens: `|`, `||`,
+ * `&&`, `;`, `;;`, `&`, `>`, `>>`, `<`, `<<`, `(`, `)`, `{`, `}`, `` ` ``,
+ * `$(`, `${`.
+ *
+ * This is a real tokenizer, not a naive whitespace split: `echo "a b" | cat`
+ * yields `['echo', 'a b', '|', 'cat']`, and `#` inside quotes never starts a
+ * comment.
+ */
+export function tokenizeBash(command) {
+    const tokens = [];
+    let cur = '';
+    const push = () => {
+        if (cur !== '') {
+            tokens.push(cur);
+            cur = '';
+        }
+    };
+    const two = (i) => command.charAt(i) + command.charAt(i + 1);
+    let i = 0;
+    const n = command.length;
+    while (i < n) {
+        const c = command.charAt(i);
+        // whitespace separates tokens
+        if (c === ' ' || c === '\t' || c === '\r' || c === '\n') {
+            push();
+            i++;
+            continue;
+        }
+        // `#` starts a comment only at the start of a word, outside quotes
+        if (c === '#' && cur === '') {
+            while (i < n && command.charAt(i) !== '\n')
+                i++;
+            continue;
+        }
+        // single quotes: everything literal until the closing quote
+        if (c === "'") {
+            i++;
+            while (i < n) {
+                const q = command.charAt(i);
+                if (q === "'") {
+                    i++;
+                    break;
+                }
+                cur += q;
+                i++;
+            }
+            continue;
+        }
+        // double quotes: `\` only escapes `$`, `` ` ``, `"`, `\` and newline
+        if (c === '"') {
+            i++;
+            while (i < n) {
+                const q = command.charAt(i);
+                if (q === '"') {
+                    i++;
+                    break;
+                }
+                if (q === '\\') {
+                    const nxt = command.charAt(i + 1);
+                    if (nxt === '$' || nxt === '`' || nxt === '"' || nxt === '\\') {
+                        cur += nxt;
+                        i += 2;
+                    }
+                    else if (nxt === '\n') {
+                        i += 2; // line continuation inside double quotes
+                    }
+                    else {
+                        cur += '\\';
+                        i++;
+                    }
+                }
+                else {
+                    cur += q;
+                    i++;
+                }
+            }
+            continue;
+        }
+        // backslash escape outside quotes
+        if (c === '\\') {
+            const nxt = command.charAt(i + 1);
+            if (nxt === '') {
+                i++; // trailing backslash: drop it
+                continue;
+            }
+            if (nxt === '\n') {
+                i += 2; // line continuation
+                continue;
+            }
+            cur += nxt;
+            i += 2;
+            continue;
+        }
+        // two-character operators
+        const t2 = two(i);
+        if (t2 === '||' ||
+            t2 === '&&' ||
+            t2 === '>>' ||
+            t2 === '<<' ||
+            t2 === '$(' ||
+            t2 === '${' ||
+            t2 === ';;') {
+            push();
+            tokens.push(t2);
+            i += 2;
+            continue;
+        }
+        // single-character operators
+        if (c === '|' ||
+            c === '&' ||
+            c === ';' ||
+            c === '>' ||
+            c === '<' ||
+            c === '(' ||
+            c === ')' ||
+            c === '{' ||
+            c === '}' ||
+            c === '`') {
+            push();
+            tokens.push(c);
+            i++;
+            continue;
+        }
+        cur += c;
+        i++;
+    }
+    push();
+    return tokens;
+}
+const SHELL_NAMES = new Set(['sh', 'bash', 'zsh']);
+const DOWNLOADER_NAMES = new Set(['curl', 'wget']);
+const ENV_NAMES = new Set(['env', 'printenv', 'set']);
+const NET_NAMES = new Set(['curl', 'wget', 'nc', 'ncat', 'ssh', 'scp']);
+const NC_NAMES = new Set(['nc', 'ncat', 'netcat']);
+const SYSTEM_PATH_PREFIXES = [
+    '/etc/',
+    '/usr/bin/',
+    '/usr/sbin/',
+    '/bin/',
+    '/sbin/',
+    '/boot/',
+];
+const DISK_DEVICE_RE = /^\/dev\/(sd[a-z]+|hd[a-z]+|vd[a-z]+|nvme[0-9]+n[0-9]+|mmcblk[0-9]+)/;
+/** Split a token stream on command separators (`;`, `&&`, `||`, `&`). */
+function splitCommands(tokens) {
+    const cmds = [];
+    let cur = [];
+    for (const t of tokens) {
+        if (t === ';' || t === '&&' || t === '||' || t === '&') {
+            if (cur.length > 0)
+                cmds.push(cur);
+            cur = [];
+        }
+        else {
+            cur.push(t);
+        }
+    }
+    if (cur.length > 0)
+        cmds.push(cur);
+    return cmds;
+}
+/** Split one command into pipeline segments on `|`. */
+function splitPipeline(cmd) {
+    const segs = [];
+    let cur = [];
+    for (const t of cmd) {
+        if (t === '|') {
+            if (cur.length > 0)
+                segs.push(cur);
+            cur = [];
+        }
+        else {
+            cur.push(t);
+        }
+    }
+    if (cur.length > 0)
+        segs.push(cur);
+    return segs;
+}
+/**
+ * Resolve the command a pipeline segment invokes: the first token, skipping
+ * a leading `sudo` (plus its flags) and stripping any `/path/` prefix.
+ */
+function invokedCommand(seg) {
+    let i = 0;
+    if (seg[0] === 'sudo') {
+        i = 1;
+        while (i < seg.length) {
+            const t = seg[i];
+            if (t === undefined || !t.startsWith('-') || t === '--')
+                break;
+            if (t === '-u' || t === '--user' || t === '-g' || t === '--group')
+                i += 2;
+            else
+                i += 1;
+        }
+    }
+    const raw = seg[i];
+    if (raw === undefined || raw === '')
+        return null;
+    const slash = raw.lastIndexOf('/');
+    const name = slash >= 0 ? raw.slice(slash + 1) : raw;
+    if (name === '')
+        return null;
+    return { name, args: seg.slice(i + 1) };
+}
+/** Merge `${` `HOME` `}` token triples — and the single token `'${HOME}'`
+ * (from quoted `"${HOME}"`) — back into `$HOME` for analysis. */
+function normalizeTokens(tokens) {
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === '${' && tokens[i + 1] === 'HOME' && tokens[i + 2] === '}') {
+            out.push('$HOME');
+            i += 2;
+        }
+        else if (t === '${HOME}') {
+            out.push('$HOME');
+        }
+        else if (t !== undefined) {
+            out.push(t);
+        }
+    }
+    return out;
+}
+function isDestructiveRmTarget(t) {
+    return (t === '/' ||
+        t.startsWith('/*') ||
+        t === '~' ||
+        t.startsWith('~/') ||
+        /^~[A-Za-z_]/.test(t) || // ~otheruser
+        t === '$HOME' ||
+        t.startsWith('$HOME/'));
+}
+function isSystemPath(p) {
+    return SYSTEM_PATH_PREFIXES.some((pre) => p === pre.slice(0, -1) || p.startsWith(pre));
+}
+function checkRm(inv, raise) {
+    if (inv.name !== 'rm')
+        return;
+    let recursive = false;
+    let force = false;
+    const flagToks = [];
+    const targets = [];
+    let endOfFlags = false;
+    for (const a of inv.args) {
+        if (!endOfFlags && a === '--') {
+            endOfFlags = true;
+            continue;
+        }
+        if (!endOfFlags && a.startsWith('-') && a.length > 1) {
+            flagToks.push(a);
+            if (a === '--recursive')
+                recursive = true;
+            else if (a === '--force')
+                force = true;
+            else if (!a.startsWith('--')) {
+                if (a.includes('r') || a.includes('R'))
+                    recursive = true;
+                if (a.includes('f'))
+                    force = true;
+            }
+        }
+        else {
+            targets.push(a);
+        }
+    }
+    if (!recursive || !force)
+        return;
+    for (const t of targets) {
+        if (isDestructiveRmTarget(t)) {
+            raise('critical', `destructive delete: "rm ${flagToks.join(' ')} ${t}" targets a filesystem root`);
+            return;
+        }
+    }
+}
+function checkMkfs(inv, seg, raise) {
+    if (inv.name === 'mkfs' || inv.name.startsWith('mkfs.')) {
+        raise('critical', `filesystem formatter "mkfs" detected: "${truncate(seg.join(' '))}"`);
+    }
+}
+function checkDd(inv, raise) {
+    if (inv.name !== 'dd')
+        return;
+    const of = inv.args.find((a) => a.startsWith('of=/dev/'));
+    if (of !== undefined) {
+        raise('critical', `raw disk write via "dd": "${of}"`);
+    }
+}
+function checkNcListener(seg, raise) {
+    const hasNc = seg.some((t) => NC_NAMES.has(t));
+    const hasListen = seg.includes('-l') || seg.includes('--listen');
+    if (hasNc && hasListen) {
+        raise('medium', `network listener: "${truncate(seg.join(' '))}"`);
+    }
+}
+function checkChmod(inv, seg, raise) {
+    if (inv.name !== 'chmod')
+        return;
+    let recursive = false;
+    let mode777 = false;
+    let rootTarget = null;
+    for (const a of inv.args) {
+        if (a === '--recursive')
+            recursive = true;
+        else if (a.startsWith('-') && !a.startsWith('--') && /[rR]/.test(a))
+            recursive = true;
+        else if (a === '777')
+            mode777 = true;
+        else if (a === '/' || a.startsWith('/*'))
+            rootTarget = a;
+    }
+    if (recursive && mode777 && rootTarget !== null) {
+        raise('high', `recursive permission wipe: "chmod -R 777 ${rootTarget}" (${truncate(seg.join(' '))})`);
+    }
+}
+function checkFindDelete(inv, seg, raise) {
+    if (inv.name !== 'find')
+        return;
+    if (inv.args.includes('/') && inv.args.includes('-delete')) {
+        raise('medium', `mass delete via find: "${truncate(seg.join(' '))}"`);
+    }
+}
+function checkTeeSystemPath(inv, seg, raise) {
+    if (inv.name !== 'tee')
+        return;
+    for (const a of inv.args) {
+        if (a.startsWith('-'))
+            continue;
+        if (isSystemPath(a)) {
+            raise('high', `write to system path via "tee": "${truncate(seg.join(' '))}"`);
+            return;
+        }
+    }
+}
+function checkCopyToSystemPath(inv, seg, raise) {
+    if (inv.name !== 'cp' && inv.name !== 'mv' && inv.name !== 'install')
+        return;
+    const operands = inv.args.filter((a) => !a.startsWith('-'));
+    const dest = operands[operands.length - 1];
+    if (dest !== undefined && isSystemPath(dest)) {
+        raise('high', `write to system path via "${inv.name}": "${truncate(seg.join(' '))}"`);
+    }
+}
+function checkPipeToShell(pipeline, raise) {
+    let downloaderSeg = null;
+    for (const seg of pipeline) {
+        const inv = invokedCommand(seg);
+        const cmdName = inv === null ? seg[0] : inv.name;
+        if (cmdName !== undefined && SHELL_NAMES.has(cmdName) && downloaderSeg !== null) {
+            raise('high', `piping a remote download into a shell: "${truncate(`${downloaderSeg.join(' ')} | ... | ${seg.join(' ')}`)}"`);
+            return;
+        }
+        if (seg.some((t) => DOWNLOADER_NAMES.has(t)))
+            downloaderSeg = [...seg];
+    }
+}
+function checkEnvExfil(pipeline, raise) {
+    let envSeg = null;
+    for (const seg of pipeline) {
+        const inv = invokedCommand(seg);
+        const cmdName = inv === null ? seg[0] : inv.name;
+        if (cmdName === undefined)
+            continue;
+        if (envSeg === null && ENV_NAMES.has(cmdName)) {
+            envSeg = [...seg];
+            continue;
+        }
+        if (envSeg !== null && NET_NAMES.has(cmdName)) {
+            raise('high', `environment exfiltration: "${truncate(`${envSeg.join(' ')} | ... | ${seg.join(' ')}`)}"`);
+            return;
+        }
+    }
+}
+function checkForkBomb(raw, raise) {
+    const compact = raw.replace(/\s+/g, '');
+    // classic `:(){ :|:& };:` (whitespace variants collapse to the same shape)
+    if (/:\(\)\{[^}]*\|[^}]*&[^}]*\}/.test(compact)) {
+        raise('critical', 'fork bomb detected: ":(){ :|:& };:"');
+        return;
+    }
+    // named-function variant: name(){ ... name ... | ... & ... } then invoked
+    const m = /([A-Za-z_]\w*)\(\)\{([^}]*)\}/.exec(compact);
+    if (m !== null) {
+        const name = m[1];
+        const body = m[2];
+        const words = body.split(/[^A-Za-z0-9_]/);
+        const tail = compact.slice(m.index + m[0].length);
+        const tailWords = tail.split(/[^A-Za-z0-9_]/);
+        if (words.includes(name) &&
+            body.includes('|') &&
+            body.includes('&') &&
+            tailWords.includes(name)) {
+            raise('critical', `fork bomb detected: "${truncate(`${name}(){ ... }; ${name}`)}"`);
+        }
+    }
+}
+function checkCommandSubstitution(tokens, raise) {
+    let i = 0;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (t === '$(') {
+            let depth = 1;
+            let j = i + 1;
+            while (j < tokens.length && depth > 0) {
+                const u = tokens[j];
+                if (u === '$(')
+                    depth++;
+                else if (u === ')')
+                    depth--;
+                j++;
+            }
+            const inside = tokens.slice(i + 1, j - 1);
+            if (inside.some((x) => x === 'curl' || x === 'wget')) {
+                raise('high', 'command substitution downloads remote content: "$(curl ...)"');
+            }
+            i = j;
+        }
+        else if (t === '`') {
+            let j = i + 1;
+            while (j < tokens.length && tokens[j] !== '`')
+                j++;
+            const inside = tokens.slice(i + 1, j);
+            if (inside.some((x) => x === 'curl' || x === 'wget')) {
+                raise('high', 'command substitution downloads remote content: "`curl ...`"');
+            }
+            i = j + 1;
+        }
+        else {
+            i++;
+        }
+    }
+}
+function checkRedirects(tokens, raise) {
+    for (let i = 0; i + 1 < tokens.length; i++) {
+        const t = tokens[i];
+        if (t !== '>' && t !== '>>')
+            continue;
+        const target = tokens[i + 1];
+        if (target === undefined)
+            continue;
+        if (DISK_DEVICE_RE.test(target)) {
+            raise('critical', `raw disk overwrite via redirect: "${t} ${target}"`);
+        }
+        else if (isSystemPath(target)) {
+            raise('high', `write to system path via redirect: "${t} ${target}"`);
+        }
+    }
+}
+function checkSudo(tokens, raise) {
+    if (tokens.includes('sudo')) {
+        raise('medium', 'privilege escalation via "sudo"');
+    }
+}
+function checkChmodPlusXDownloaded(tokens, raise) {
+    if (!tokens.some((t) => t === 'curl' || t === 'wget'))
+        return;
+    for (const cmd of splitCommands(tokens)) {
+        for (const seg of splitPipeline(cmd)) {
+            const inv = invokedCommand(seg);
+            if (inv !== null && inv.name === 'chmod' && inv.args.includes('+x')) {
+                raise('medium', `chmod +x on a downloaded file: "${truncate(seg.join(' '))}"`);
+                return;
+            }
+        }
+    }
+}
+/**
+ * Analyze a bash command and classify its risk.
+ *
+ * - `critical`: `rm -rf /` (and `/*`, `~`, `$HOME` variants, `--recursive`
+ *   `--force` spellings), `mkfs`, `dd … of=/dev/…`, fork bombs
+ *   (`:(){ :|:& };:` and whitespace/named variants), `> /dev/sdX`.
+ * - `high`: piping a download into a shell (`curl … | sh`, `… | sudo sh`),
+ *   `$(curl …)` / backtick command substitution fetching remote content,
+ *   env exfiltration (`env | curl …`), writes to system paths (`/etc/`,
+ *   `/usr/bin`, …), `chmod -R 777 /`.
+ * - `medium`: any `sudo`, `nc -l` listeners, `chmod +x` on a downloaded
+ *   file, `find / … -delete`.
+ * - `low`: everything else.
+ *
+ * Every finding appends a reason quoting the exact construct caught; the
+ * overall risk is the maximum over all findings (fail-closed).
+ */
+export function analyzeBash(command) {
+    const reasons = [];
+    let risk = 'low';
+    const raise = (r, reason) => {
+        risk = maxRisk(risk, r);
+        reasons.push(reason);
+    };
+    const tokens = normalizeTokens(tokenizeBash(command));
+    if (tokens.length === 0)
+        return { risk: 'low', reasons: [] };
+    for (const cmd of splitCommands(tokens)) {
+        const pipeline = splitPipeline(cmd);
+        for (const seg of pipeline) {
+            const inv = invokedCommand(seg);
+            if (inv !== null) {
+                checkRm(inv, raise);
+                checkMkfs(inv, seg, raise);
+                checkDd(inv, raise);
+                checkChmod(inv, seg, raise);
+                checkFindDelete(inv, seg, raise);
+                checkTeeSystemPath(inv, seg, raise);
+                checkCopyToSystemPath(inv, seg, raise);
+            }
+            checkNcListener(seg, raise);
+        }
+        checkPipeToShell(pipeline, raise);
+        checkEnvExfil(pipeline, raise);
+    }
+    checkForkBomb(command, raise);
+    checkCommandSubstitution(tokens, raise);
+    checkRedirects(tokens, raise);
+    checkSudo(tokens, raise);
+    checkChmodPlusXDownloaded(tokens, raise);
+    return { risk, reasons };
+}
+// ---------------------------------------------------------------------------
+// checkHttpUrl
+// ---------------------------------------------------------------------------
+function hostMatchesAllowlist(host, entry) {
+    let e = entry.trim().toLowerCase();
+    if (e.endsWith('.'))
+        e = e.slice(0, -1);
+    // strip an optional `:port` suffix
+    if (!e.startsWith('[')) {
+        const portMatch = /:(\d+)$/.exec(e);
+        if (portMatch !== null)
+            e = e.slice(0, e.length - portMatch[0].length);
+    }
+    if (e.startsWith('*.')) {
+        const base = e.slice(2);
+        // wildcard matches subdomains only, never the apex itself
+        return host.length > base.length && host.endsWith(`.${base}`);
+    }
+    return host === e;
+}
+/**
+ * Gate an outbound URL (layer: `'gates'`).
+ *
+ * - Unparseable URL → deny, severity `critical`.
+ * - Non-http(s) protocol → deny, severity `high`.
+ * - Userinfo (`user:pass@host`) → deny, severity `high` ("credential in URL").
+ * - `httpMode: 'off'` → allow. `'warn'` → off-list hosts still allow, but the
+ *   reason flags them (severity `low`). `'allowlist'` → off-list hosts deny
+ *   with severity `high`.
+ *
+ * Host matching is case-insensitive, ignores ports, and supports exact and
+ * `*.example.com` wildcard entries.
+ */
+export function checkHttpUrl(rawUrl, policy) {
+    // guard off: allow unconditionally (types.ts: "off: every layer allows unconditionally")
+    if (policy.mode === 'off') {
+        return { decision: 'allow', reason: 'guard off', layer: LAYER };
+    }
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return decide(policy, LAYER, 'critical', `unparseable URL: "${truncate(rawUrl, 120)}"`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return decide(policy, LAYER, 'high', `disallowed URL protocol "${url.protocol}" (only http/https allowed): "${truncate(rawUrl, 120)}"`);
+    }
+    if (url.username !== '' || url.password !== '') {
+        return decide(policy, LAYER, 'high', 'credential in URL (userinfo present)');
+    }
+    // No finding from here on: httpMode 'off' and allowlist hits allow directly
+    // so a clean check is never denied by `decide()` in strict mode.
+    if (policy.httpMode === 'off') {
+        return { decision: 'allow', reason: 'http checks disabled by policy (httpMode=off)', layer: LAYER };
+    }
+    const host = url.hostname.toLowerCase();
+    const allowed = policy.httpAllowlist.some((entry) => hostMatchesAllowlist(host, entry));
+    if (allowed) {
+        return { decision: 'allow', reason: `URL host "${host}" is on the http allowlist`, layer: LAYER };
+    }
+    if (policy.httpMode === 'warn') {
+        // genuine finding (severity low): `decide()` allows it in warn mode with
+        // the reason attached, denies it in strict mode (fail-closed)
+        return decide(policy, LAYER, 'low', `URL host "${host}" is NOT on the http allowlist (warn mode: allowed with warning)`);
+    }
+    return decide(policy, LAYER, 'high', `URL host "${host}" is NOT on the http allowlist`);
+}
+// ---------------------------------------------------------------------------
+// evaluateToolCall
+// ---------------------------------------------------------------------------
+/** Tools whose outbound HTTP is gated by name (in addition to the regex). */
+const HTTP_TOOL_NAMES = new Set([
+    'web-fetch',
+    'research.search',
+    'research.extract',
+    'research.deep',
+    'research.academic',
+    'research.crawl',
+]);
+const BASH_NAME_RE = /(\b|_)(bash|sh|shell|exec|command|run)(s?\b|_)/i;
+const HTTP_NAME_RE = /fetch|https?|request/i;
+/** First string-valued argument among the given names, if any. */
+function stringArg(call, names) {
+    for (const n of names) {
+        const v = call.arguments[n];
+        if (typeof v === 'string')
+            return v;
+    }
+    return undefined;
+}
+/** Tool names whose writes are zone-gated. */
+const FILE_WRITE_NAMES = new Set(['file.write', 'file.edit']);
+/**
+ * Lexical containment check: is `target` inside any of `zones`?
+ *
+ * Absolute targets are normalized and compared directly. Relative targets
+ * are resolved against each zone in turn — the file tools resolve relative
+ * paths under their root, so a relative target that climbs out (`../..`)
+ * fails closed. This is an approval gate, not the security boundary itself:
+ * the handlers still enforce symlink-aware containment via `resolveWithin`
+ * at execution time.
+ */
+function isWithinZones(target, zones) {
+    const trimmed = target.trim();
+    if (trimmed === '')
+        return false;
+    for (const zone of zones) {
+        const normalizedZone = resolve(zone);
+        if (normalizedZone === '' || !isAbsolute(normalizedZone))
+            continue;
+        const absolute = isAbsolute(trimmed) ? resolve(trimmed) : resolve(normalizedZone, trimmed);
+        if (absolute === normalizedZone || absolute.startsWith(normalizedZone + sep)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Zone gate for write-capable tools. Returns a `require-approval` verdict
+ * when the call targets a path outside every configured zone, or `undefined`
+ * to let evaluation continue.
+ *
+ * - `file.write` / `file.edit`: the `path` argument is checked. A missing
+ *   or empty path fails closed (it cannot be proven in-zone).
+ * - `shell.exec`: an explicit `cwd` argument is checked. An absent `cwd`
+ *   keeps the previous behavior (the handler defaults it to the workspace
+ *   root, which the gateway puts in the zones).
+ * - Empty `writeZones` (the default): the gate is off entirely.
+ */
+function checkWriteZones(call, policy) {
+    if (policy.writeZones.length === 0)
+        return undefined;
+    if (FILE_WRITE_NAMES.has(call.name)) {
+        const target = stringArg(call, ['path']);
+        if (target === undefined || !isWithinZones(target, policy.writeZones)) {
+            return {
+                decision: 'require-approval',
+                reason: `file write "${call.name}" targets a path outside the configured write zones`,
+                layer: LAYER,
+            };
+        }
+        return undefined;
+    }
+    if (call.name === 'shell.exec') {
+        const cwd = stringArg(call, ['cwd']);
+        if (cwd !== undefined && !isWithinZones(cwd, policy.writeZones)) {
+            return {
+                decision: 'require-approval',
+                reason: 'shell.exec cwd is outside the configured write zones',
+                layer: LAYER,
+            };
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Evaluate one tool call against the gates layer.
+ *
+ * Order (first match wins):
+ * 1. guard `off` → allow unconditionally;
+ * 2. name exactly in `denyTools` → deny (`critical`);
+ * 3. name exactly in `approvalTools` → require-approval;
+ * 4. write-zone gate — `file.write`/`file.edit` (by `path`) and `shell.exec`
+ *    (by explicit `cwd`) outside every configured `writeZones` →
+ *    require-approval (fail-closed); in-zone keeps the previous behavior;
+ * 5. bash-like — name matches the bash regex **or** a string arg named
+ *    `command`/`script`/`cmd` → `analyzeBash`; risk `medium`/`high`/`critical`
+ *    goes through `decide()`, risk `low` (no findings) allows directly;
+ * 6. http-like — name in the known research/fetch set, name matches
+ *    `/fetch|https?|request/i`, **or** a string arg named `url`/`href`/`link`
+ *    → `checkHttpUrl` on that URL argument;
+ * 7. anything else → allow.
+ */
+export function evaluateToolCall(call, policy) {
+    // guard off: allow unconditionally (types.ts: "off: every layer allows unconditionally")
+    if (policy.mode === 'off') {
+        return { decision: 'allow', reason: 'guard off', layer: LAYER };
+    }
+    if (policy.denyTools.includes(call.name)) {
+        return decide(policy, LAYER, 'critical', `tool "${call.name}" is on the deny list`);
+    }
+    if (policy.approvalTools.includes(call.name)) {
+        return { decision: 'require-approval', reason: `tool "${call.name}" requires human approval`, layer: LAYER };
+    }
+    // -- write zones ---------------------------------------------------------
+    const zoneVerdict = checkWriteZones(call, policy);
+    if (zoneVerdict !== undefined)
+        return zoneVerdict;
+    // -- bash-like -----------------------------------------------------------
+    const bashArg = stringArg(call, ['command', 'script', 'cmd']);
+    const bashByName = BASH_NAME_RE.test(call.name);
+    if (bashByName || bashArg !== undefined) {
+        const analyses = [];
+        if (bashArg !== undefined)
+            analyses.push(analyzeBash(bashArg));
+        if (bashByName) {
+            // a bash-named tool may carry the script under a different arg name
+            for (const v of Object.values(call.arguments)) {
+                if (typeof v === 'string' && v !== bashArg && v.trim() !== '') {
+                    analyses.push(analyzeBash(v));
+                }
+            }
+        }
+        let risk = 'low';
+        const reasons = [];
+        for (const a of analyses) {
+            risk = maxRisk(risk, a.risk);
+            reasons.push(...a.reasons);
+        }
+        // No findings: allow directly so a clean command is never denied by
+        // `decide()` in strict mode. Findings map 1:1 onto severity.
+        if (risk === 'low') {
+            return { decision: 'allow', reason: `bash-like tool "${call.name}": no dangerous constructs detected`, layer: LAYER };
+        }
+        const severity = risk;
+        return decide(policy, LAYER, severity, reasons.join('; '));
+    }
+    // -- http-like -----------------------------------------------------------
+    // Only the url/href/link arguments are checked: a research tool carrying a
+    // plain-text `query` (no URL) must not be denied as an "unparseable URL".
+    const urlArg = stringArg(call, ['url', 'href', 'link']);
+    const httpByName = HTTP_TOOL_NAMES.has(call.name) || HTTP_NAME_RE.test(call.name);
+    if (httpByName || urlArg !== undefined) {
+        if (urlArg === undefined) {
+            return { decision: 'allow', reason: `http-like tool "${call.name}" has no URL argument to check`, layer: LAYER };
+        }
+        return checkHttpUrl(urlArg, policy);
+    }
+    // -- default --------------------------------------------------------------
+    return { decision: 'allow', reason: `tool "${call.name}" is not covered by any gate`, layer: LAYER };
+}