mtech-ai-local-runner 0.1.53 → 0.1.55

package/dist/src/guide/integrations.js

@@ -0,0 +1,335 @@
+import { constants } from "node:fs";
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseToml } from "smol-toml";
+import { claudeConfigDir, codexHome, parseCodexHooks } from "../asks/integrations.js";
+import { GUIDE_SHIM_FILE, removeShim, shimCommand, writeShim } from "../asks/shim.js";
+import { GUIDE_APPS } from "./types.js";
+/*
+ * Installing the guide hooks (Work Item d38d60f9, spec sections 3.5 and 6.5), only on request: setup --feature, or
+ * integrations install --feature guide. Claude Code gets a second skills-directory plugin, mtec-ai-gateway-guide. Codex
+ * gets two handlers appended to ~/.codex/hooks.json after a backup, after the person's own hooks and the asks handlers.
+ * Both run the stable guide shim only, so a runner upgrade changes no handler and Codex never asks for trust again.
+ * Guide keeps its own record of the dirs it used, <stateRoot>/guide-integrations.json, so asks and guide are installed and
+ * removed independently.
+ */
+export const GUIDE_PLUGIN_NAME = "mtec-ai-gateway-guide";
+export const GUIDE_INTEGRATIONS_FILE = "guide-integrations.json";
+const CLAUDE_PRE_TOOL_MATCHER = "Read|Grep|Glob|Bash|Edit|Write|mcp__.*";
+const CODEX_PRE_TOOL_MATCHER = "^(Bash|apply_patch|mcp__.*)$";
+const HANDLER_TIMEOUT_SECONDS = 5;
+const GUIDE_CODEX_COMMAND = /^"[^"]*\/mtec-ai-local-runner\/bin\/gateway-guide-hook" codex (session-start|pre-tool)$/;
+const CLAUDE_HOOKS_DESCRIPTION = "AI Gateway guide hooks, written by mtech-ai-local-runner. Remove with: npx mtech-ai-local-runner integrations remove claude --feature guide";
+const CODEX_FILE_DESCRIPTION = "Hooks written by mtech-ai-local-runner for AI Gateway guide.";
+/** Codex keys hook trust by "<hooks.json path>:<event>:<group>:<handler>", with the event in snake case. */
+const TRUST_EVENTS = { SessionStart: "session_start", PreToolUse: "pre_tool_use" };
+const RECORD_KEYS = { claude: "claude_config_dir", codex: "codex_home" };
+/** The guide hook client installed next to this module (dist/src/guide/hook-client.js in the package). */
+export function guideHookClientScript() {
+    return fileURLToPath(new URL("./hook-client.js", import.meta.url));
+}
+export function guideHookCommand(stateRoot, app, event) {
+    return shimCommand(stateRoot, GUIDE_SHIM_FILE, [app, event]);
+}
+export function guidePluginManifest() {
+    return { name: GUIDE_PLUGIN_NAME, version: "1.0.0", description: "Reminds this session to use the AI Gateway and counts how often it does.",
+        author: { name: "MTEC AI Gateway" } };
+}
+export function guideClaudeHooksFile(stateRoot) {
+    const handler = (event) => ({ type: "command", command: guideHookCommand(stateRoot, "claude", event), timeout: HANDLER_TIMEOUT_SECONDS });
+    return { description: CLAUDE_HOOKS_DESCRIPTION, hooks: {
+            SessionStart: [{ hooks: [handler("session-start")] }],
+            PreToolUse: [{ matcher: CLAUDE_PRE_TOOL_MATCHER, hooks: [handler("pre-tool")] }],
+        } };
+}
+/** The two Codex groups. Never change them: Codex trusts a hook by a hash that covers these fields. */
+export function guideCodexHookGroups(stateRoot) {
+    const handler = (event) => ({ type: "command", command: guideHookCommand(stateRoot, "codex", event), timeout: HANDLER_TIMEOUT_SECONDS });
+    return { SessionStart: { hooks: [handler("session-start")] }, PreToolUse: { matcher: CODEX_PRE_TOOL_MATCHER, hooks: [handler("pre-tool")] } };
+}
+function isGuideHandler(handler) {
+    const command = handler?.command;
+    return typeof command === "string" && GUIDE_CODEX_COMMAND.test(command);
+}
+function guideEntries(document) {
+    return Object.entries(document.hooks ?? {}).flatMap(([event, groups]) => groups.flatMap(group => group.hooks.filter(isGuideHandler).map(handler => JSON.stringify({ event, handler }))));
+}
+function hasCurrentGuideHooks(document, stateRoot) {
+    const ours = guideEntries(document);
+    const expected = Object.entries(guideCodexHookGroups(stateRoot)).map(([event, group]) => JSON.stringify({ event, handler: group.hooks[0] }));
+    return ours.length === expected.length && expected.every(entry => ours.includes(entry));
+}
+export function withoutGuideCodexHooks(document) {
+    const hooks = {};
+    let changed = false;
+    for (const [event, groups] of Object.entries(document.hooks ?? {})) {
+        const kept = [];
+        for (const group of groups) {
+            const handlers = group.hooks.filter(handler => !isGuideHandler(handler));
+            if (handlers.length === group.hooks.length) {
+                kept.push(group);
+                continue;
+            }
+            changed = true;
+            if (handlers.length > 0)
+                kept.push({ ...group, hooks: handlers });
+        }
+        if (kept.length > 0 || groups.length === 0)
+            hooks[event] = kept;
+    }
+    return { document: document.hooks === undefined ? document : { ...document, hooks }, changed };
+}
+/** The document with the two guide groups appended after everything else; one that already holds them is left as it is. */
+export function withGuideCodexHooks(document, stateRoot) {
+    if (hasCurrentGuideHooks(document, stateRoot))
+        return { document, changed: false };
+    const stripped = withoutGuideCodexHooks(document).document;
+    const hooks = { ...stripped.hooks ?? {} };
+    for (const [event, group] of Object.entries(guideCodexHookGroups(stateRoot))) {
+        hooks[event] = [...hooks[event] ?? [], group];
+    }
+    const next = { ...stripped, hooks };
+    return { document: next, changed: JSON.stringify(next) !== JSON.stringify(document) };
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeAtomic(path, content, mode) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode, flag: "wx" });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+/** Copies the Codex hooks file aside before it is changed. A backup is never overwritten. */
+async function backup(path, now) {
+    const target = `${path}.mtec-ai-local-runner-${new Date(now).toISOString().replace(/[:.]/g, "-")}.bak`;
+    await copyFile(path, target, constants.COPYFILE_EXCL);
+    return target;
+}
+const pretty = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const pluginDirIn = (configDir) => join(configDir, "skills", GUIDE_PLUGIN_NAME);
+const hooksFileIn = (home) => join(home, "hooks.json");
+const placeIn = (app, dir) => (app === "claude" ? pluginDirIn(dir) : hooksFileIn(dir));
+async function readRecord(stateRoot) {
+    const record = { claude_config_dir: [], codex_home: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(join(stateRoot, GUIDE_INTEGRATIONS_FILE), "utf8"));
+    }
+    catch {
+        return record;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return record;
+    for (const key of [RECORD_KEYS.claude, RECORD_KEYS.codex]) {
+        const dirs = parsed[key];
+        for (const dir of Array.isArray(dirs) ? dirs : []) {
+            if (typeof dir === "string" && isAbsolute(dir) && !record[key].includes(dir))
+                record[key].push(dir);
+        }
+    }
+    return record;
+}
+async function saveRecord(stateRoot, record) {
+    const path = join(stateRoot, GUIDE_INTEGRATIONS_FILE);
+    if (record.claude_config_dir.length === 0 && record.codex_home.length === 0) {
+        await rm(path, { force: true });
+        return;
+    }
+    await mkdir(stateRoot, { recursive: true, mode: 0o700 });
+    await writeAtomic(path, pretty(record), 0o600);
+}
+async function recordDirectory(app, dir, stateRoot) {
+    const record = await readRecord(stateRoot);
+    const key = RECORD_KEYS[app];
+    if (!record[key].includes(dir))
+        await saveRecord(stateRoot, { ...record, [key]: [...record[key], dir] });
+}
+async function placesOf(app, env, stateRoot) {
+    const places = [placeIn(app, app === "claude" ? claudeConfigDir(env) : codexHome(env))];
+    for (const dir of (await readRecord(stateRoot))[RECORD_KEYS[app]]) {
+        const place = placeIn(app, dir);
+        if (!places.includes(place))
+            places.push(place);
+    }
+    return places;
+}
+async function claudeState(pluginDir, stateRoot) {
+    let manifest;
+    let hooks;
+    try {
+        manifest = await readOptional(join(pluginDir, ".claude-plugin", "plugin.json"));
+        hooks = await readOptional(join(pluginDir, "hooks", "hooks.json"));
+    }
+    catch {
+        return "unreadable";
+    }
+    if (manifest === null && hooks === null)
+        return "not_installed";
+    return manifest === pretty(guidePluginManifest()) && hooks === pretty(guideClaudeHooksFile(stateRoot)) ? "installed" : "outdated";
+}
+async function codexState(hooksFile, stateRoot) {
+    let raw;
+    try {
+        raw = await readOptional(hooksFile);
+    }
+    catch {
+        return "unreadable";
+    }
+    if (raw === null)
+        return "not_installed";
+    let document;
+    try {
+        document = parseCodexHooks(raw);
+    }
+    catch {
+        return "unreadable";
+    }
+    if (guideEntries(document).length === 0)
+        return "not_installed";
+    return hasCurrentGuideHooks(document, stateRoot) ? "installed" : "outdated";
+}
+const STATE_ORDER = ["installed", "outdated", "unreadable", "not_installed"];
+export async function guideStatus(app, env, stateRoot) {
+    let best = null;
+    for (const place of await placesOf(app, env, stateRoot)) {
+        const state = app === "claude" ? await claudeState(place, stateRoot) : await codexState(place, stateRoot);
+        if (best === null || STATE_ORDER.indexOf(state) < STATE_ORDER.indexOf(best.state))
+            best = { app, state, path: place };
+    }
+    return best;
+}
+export async function installGuide(app, env, stateRoot, options = {}) {
+    const shim = () => writeShim({ stateRoot, nodePath: options.nodePath, clientPath: options.clientPath ?? guideHookClientScript(),
+        file: GUIDE_SHIM_FILE, feature: "guide" });
+    if (app === "claude") {
+        const configDir = claudeConfigDir(env);
+        const pluginDir = pluginDirIn(configDir);
+        await shim();
+        await recordDirectory("claude", configDir, stateRoot);
+        if (await claudeState(pluginDir, stateRoot) === "installed")
+            return { app, state: "installed", path: pluginDir };
+        await writeAtomic(join(pluginDir, ".claude-plugin", "plugin.json"), pretty(guidePluginManifest()), 0o644);
+        await writeAtomic(join(pluginDir, "hooks", "hooks.json"), pretty(guideClaudeHooksFile(stateRoot)), 0o644);
+        return { app, state: "installed", path: pluginDir };
+    }
+    const home = codexHome(env);
+    const hooksFile = hooksFileIn(home);
+    const raw = await readOptional(hooksFile);
+    const current = raw === null ? { description: CODEX_FILE_DESCRIPTION } : parseCodexHooks(raw);
+    const { document, changed } = withGuideCodexHooks(current, stateRoot);
+    await shim();
+    await recordDirectory("codex", home, stateRoot);
+    if (!changed)
+        return { app, state: "installed", path: hooksFile };
+    const saved = raw === null ? undefined : await backup(hooksFile, options.now ?? Date.now());
+    const mode = raw === null ? 0o600 : (await stat(hooksFile)).mode & 0o777;
+    await writeAtomic(hooksFile, pretty(document), mode);
+    return { app, state: "installed", path: hooksFile, ...(saved ? { backup: saved } : {}) };
+}
+export async function removeGuide(app, env, stateRoot, options = {}) {
+    const now = options.now ?? Date.now();
+    const places = await placesOf(app, env, stateRoot);
+    let first;
+    for (const place of places) {
+        if (app === "claude") {
+            const manifest = await readOptional(join(place, ".claude-plugin", "plugin.json"));
+            // Only a directory this runner wrote is removed.
+            if (manifest === null || JSON.parse(manifest).name !== GUIDE_PLUGIN_NAME)
+                continue;
+            await rm(place, { recursive: true, force: true });
+            first ??= { path: place };
+            continue;
+        }
+        const raw = await readOptional(place);
+        if (raw === null)
+            continue;
+        const { document, changed } = withoutGuideCodexHooks(parseCodexHooks(raw));
+        if (!changed)
+            continue;
+        const saved = await backup(place, now);
+        if (Object.keys(document.hooks ?? {}).length === 0 && document.description === CODEX_FILE_DESCRIPTION && Object.keys(document).length === 2) {
+            await rm(place, { force: true });
+        }
+        else {
+            await writeAtomic(place, pretty(document), (await stat(place)).mode & 0o777);
+        }
+        first ??= { path: place, backup: saved };
+    }
+    const record = await readRecord(stateRoot);
+    const key = RECORD_KEYS[app];
+    const kept = [];
+    for (const dir of record[key]) {
+        const state = app === "claude" ? await claudeState(placeIn(app, dir), stateRoot) : await codexState(placeIn(app, dir), stateRoot);
+        if (state !== "not_installed")
+            kept.push(dir);
+    }
+    if (kept.length !== record[key].length)
+        await saveRecord(stateRoot, { ...record, [key]: kept });
+    return { app, state: (await guideStatus(app, env, stateRoot)).state, path: first?.path ?? places[0], ...(first?.backup ? { backup: first.backup } : {}) };
+}
+export async function installedGuideApps(env, stateRoot) {
+    const apps = [];
+    for (const app of GUIDE_APPS)
+        if ((await guideStatus(app, env, stateRoot)).state === "installed")
+            apps.push(app);
+    return apps;
+}
+/** Removes the guide shim once no guide hook is left that runs it. */
+export async function removeGuideShimIfUnused(env, stateRoot) {
+    for (const app of GUIDE_APPS)
+        if ((await guideStatus(app, env, stateRoot)).state !== "not_installed")
+            return false;
+    await removeShim(stateRoot, GUIDE_SHIM_FILE);
+    return true;
+}
+/**
+ * Whether Codex trusts both guide handlers: their "<hooks.json path>:<event>:<group>:<handler>" entries under
+ * [hooks.state] in the user config.toml each carry a trusted_hash and are not disabled.
+ */
+export async function codexGuideTrust(env) {
+    const home = codexHome(env);
+    const hooksFile = hooksFileIn(home);
+    let document;
+    let config;
+    try {
+        const raw = await readOptional(hooksFile);
+        if (raw === null)
+            return "no";
+        document = parseCodexHooks(raw);
+        const toml = await readOptional(join(home, "config.toml"));
+        config = toml === null ? {} : parseToml(toml);
+    }
+    catch {
+        return "unknown";
+    }
+    const keys = [];
+    for (const [event, trustEvent] of Object.entries(TRUST_EVENTS)) {
+        const groups = document.hooks?.[event] ?? [];
+        groups.forEach((group, groupIndex) => group.hooks.forEach((handler, handlerIndex) => {
+            if (isGuideHandler(handler))
+                keys.push(`${hooksFile}:${trustEvent}:${groupIndex}:${handlerIndex}`);
+        }));
+    }
+    if (keys.length === 0)
+        return "no";
+    const state = (config.hooks?.state ?? {});
+    return keys.every(key => {
+        const entry = state[key];
+        return typeof entry?.trusted_hash === "string" && entry.trusted_hash !== "" && entry.enabled !== false;
+    }) ? "yes" : "no";
+}

package/dist/src/guide/matching.js

@@ -0,0 +1,314 @@
+const KB_DIRECTORIES = new Set(["KnowledgeBase", "ai-work-process-kb", "ai-work-product-specs-kb"]);
+const READ_PROGRAMS = new Set(["cat", "head", "tail", "less", "more", "sed", "awk", "grep", "egrep", "fgrep", "rg",
+    "ag", "find", "ls", "wc", "nl", "bat", "jq", "yq", "sort", "uniq", "cut", "diff", "stat", "tree", "file"]);
+const WRITE_PROGRAMS = new Set(["tee", "touch"]);
+const WRAPPERS = new Set(["sudo", "env", "command", "time", "nice", "nohup", "exec"]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash"]);
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
+const DB_PROGRAMS = new Set(["mysql", "mariadb", "psql"]);
+const AWS_VALUE_FLAGS = new Set(["--profile", "--region", "--output", "--endpoint-url", "--query", "--color",
+    "--ca-bundle", "--cli-read-timeout", "--cli-connect-timeout"]);
+const SSH_VALUE_FLAGS = new Set(["-p", "-i", "-l", "-o", "-J", "-F", "-L", "-R", "-D", "-b", "-c", "-E", "-e",
+    "-m", "-O", "-Q", "-S", "-W", "-w", "-B", "-I"]);
+const NO_VALUE_FLAGS = new Set();
+const READ_STATEMENT = /^\s*(?:select|show|describe|desc|explain)\b/i;
+const WRITE_KEYWORD = /\b(?:insert|update|delete|replace|alter|drop|truncate|create|grant|revoke|rename|load|call)\b/i;
+const QUOTED = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g;
+const MCP_TOOL = /^mcp__(.+)__([a-z][a-z0-9_]{1,63})$/;
+const PATCH_FILE = /^\*\*\* (?:Update|Add|Delete) File: (.+)$/gm;
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+export function isKnowledgeBasePath(path) {
+    return path.split("/").some(segment => KB_DIRECTORIES.has(segment));
+}
+/** The part of a KnowledgeBase path from its KnowledgeBase directory down, for local detail lines: never the folders above it. */
+export function knowledgeBaseTail(path) {
+    const segments = path.split("/");
+    const index = segments.findIndex(segment => KB_DIRECTORIES.has(segment));
+    return index < 0 ? "" : segments.slice(index).join("/");
+}
+/**
+ * The words of each simple command in a shell line, split at &&, ||, ;, |, & and newlines. Quotes and backslashes are
+ * honoured. A redirect is kept as its own word, ">" for > and >> and "<" for <; a descriptor redirect such as 2>&1 is
+ * dropped.
+ */
+export function shellCommands(line) {
+    const commands = [];
+    let words = [];
+    let word = "";
+    let inWord = false;
+    const endWord = () => { if (inWord)
+        words.push(word); word = ""; inWord = false; };
+    const endCommand = () => { endWord(); if (words.length > 0)
+        commands.push(words); words = []; };
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (char === "'") {
+            const close = line.indexOf("'", index + 1);
+            const end = close < 0 ? line.length : close;
+            word += line.slice(index + 1, end);
+            inWord = true;
+            index = end;
+        }
+        else if (char === '"') {
+            inWord = true;
+            index += 1;
+            while (index < line.length && line[index] !== '"') {
+                if (line[index] === "\\" && index + 1 < line.length && '"\\$`'.includes(line[index + 1]))
+                    index += 1;
+                word += line[index];
+                index += 1;
+            }
+        }
+        else if (char === "\\") {
+            if (index + 1 < line.length && line[index + 1] !== "\n") {
+                word += line[index + 1];
+                inWord = true;
+            }
+            index += 1;
+        }
+        else if (char === "\n" || char === ";") {
+            endCommand();
+        }
+        else if (char === "&" || char === "|") {
+            endCommand();
+            if (line[index + 1] === char)
+                index += 1;
+        }
+        else if (char === ">" || char === "<") {
+            // A descriptor number written right before the redirect, as in 2>, is not a word.
+            if (inWord && /^[0-9]+$/.test(word)) {
+                word = "";
+                inWord = false;
+            }
+            else
+                endWord();
+            if (char === ">" && line[index + 1] === ">")
+                index += 1;
+            if (line[index + 1] === "&") {
+                index += 1;
+                while (index + 1 < line.length && /[0-9-]/.test(line[index + 1]))
+                    index += 1;
+                continue;
+            }
+            words.push(char);
+        }
+        else if (char === " " || char === "\t") {
+            endWord();
+        }
+        else {
+            word += char;
+            inWord = true;
+        }
+    }
+    endCommand();
+    return commands;
+}
+const baseName = (word) => word.slice(word.lastIndexOf("/") + 1);
+/** The program after assignments and wrappers (sudo, env, rtk, rtk proxy and the like), its arguments and its redirect targets. */
+function commandOf(words) {
+    let index = 0;
+    const skipAssignments = () => { while (index < words.length && ASSIGNMENT.test(words[index]))
+        index += 1; };
+    skipAssignments();
+    for (let guard = 0; guard < 8 && index < words.length; guard += 1) {
+        const name = baseName(words[index]);
+        if (name === "rtk") {
+            index += 1;
+            if (words[index] === "proxy")
+                index += 1;
+            continue;
+        }
+        if (!WRAPPERS.has(name))
+            break;
+        index += 1;
+        while (index < words.length && words[index].startsWith("-"))
+            index += 1;
+        skipAssignments();
+    }
+    const program = words[index];
+    if (program === undefined)
+        return null;
+    const args = [];
+    const writes = [];
+    for (let next = index + 1; next < words.length; next += 1) {
+        const current = words[next];
+        const target = words[next + 1];
+        if (current === ">" || current === "<") {
+            if (target !== undefined)
+                (current === ">" ? writes : args).push(target);
+            next += 1;
+            continue;
+        }
+        args.push(current);
+    }
+    return { program: baseName(program), args, writes };
+}
+/** The words that are neither flags nor flag values, in order. A --name=value flag takes no extra word. */
+function positional(args, valueFlags) {
+    const words = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg.startsWith("-")) {
+            if (valueFlags.has(arg))
+                index += 1;
+            continue;
+        }
+        words.push(arg);
+    }
+    return words;
+}
+function databaseHost(program, args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "-h" || arg === "--host")
+            return (args[index + 1] ?? "").toLowerCase() || null;
+        if (arg.startsWith("--host="))
+            return arg.slice("--host=".length).toLowerCase() || null;
+        if (program !== "psql" && /^-h./.test(arg))
+            return arg.slice(2).toLowerCase();
+        if (program === "psql") {
+            const uri = /^postgres(?:ql)?:\/\/(?:[^@/]*@)?([^/:?]+)/i.exec(arg);
+            if (uri)
+                return uri[1].toLowerCase();
+            const conninfo = /(?:^|\s)host=(\S+)/.exec(arg);
+            if (conninfo)
+                return conninfo[1].toLowerCase();
+        }
+    }
+    return null;
+}
+function databaseStatement(program, args) {
+    const short = program === "psql" ? "-c" : "-e";
+    const long = program === "psql" ? "--command" : "--execute";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === short || arg === long)
+            return args[index + 1] ?? null;
+        if (arg.startsWith(`${long}=`))
+            return arg.slice(long.length + 1);
+        if (program !== "psql" && arg.startsWith("-e") && arg.length > 2)
+            return arg.slice(2);
+    }
+    return null;
+}
+/** A database command against a named host that is not this Mac: a read only when its statement is plainly one. */
+function databaseRule(program, args) {
+    const host = databaseHost(program, args);
+    if (host === null || LOCAL_HOSTS.has(host))
+        return null;
+    const statement = databaseStatement(program, args);
+    const read = statement !== null && READ_STATEMENT.test(statement) && !WRITE_KEYWORD.test(statement.replace(QUOTED, "''"));
+    return { kind: "cli", rule: read ? "cli_db_read" : "cli_db_write", subject: program };
+}
+function cliRule(program, args) {
+    if (program === "aws") {
+        const [service, subcommand, ...rest] = positional(args, AWS_VALUE_FLAGS);
+        if (service === "logs")
+            return { kind: "cli", rule: "cli_aws_logs", subject: "aws logs" };
+        if (service === "s3" && (subcommand === "ls" || (subcommand === "cp" && rest[0]?.startsWith("s3://") === true && rest[1]?.startsWith("s3://") !== true))) {
+            return { kind: "cli", rule: "cli_aws_s3_read", subject: "aws s3" };
+        }
+        if (service === "s3api" && (subcommand === "get-object" || subcommand?.startsWith("list-objects") === true)) {
+            return { kind: "cli", rule: "cli_aws_s3_read", subject: "aws s3api" };
+        }
+        return null;
+    }
+    if (program === "vapor")
+        return positional(args, NO_VALUE_FLAGS)[0] === "deploy" ? { kind: "cli", rule: "cli_vapor_deploy", subject: "vapor deploy" } : null;
+    if (program === "ssh") {
+        const target = positional(args, SSH_VALUE_FLAGS)[0];
+        if (target === undefined)
+            return null;
+        return LOCAL_HOSTS.has(target.slice(target.lastIndexOf("@") + 1).toLowerCase()) ? null : { kind: "cli", rule: "cli_ssh", subject: "ssh" };
+    }
+    return DB_PROGRAMS.has(program) ? databaseRule(program, args) : null;
+}
+/** Findings of one shell line: KnowledgeBase reads and writes and CLI rules, looking one level into sh -c scripts. */
+export function classifyShell(line, depth = 0) {
+    const findings = [];
+    for (const words of shellCommands(line)) {
+        const command = commandOf(words);
+        if (command === null)
+            continue;
+        const { program, args, writes } = command;
+        if (depth === 0 && SHELLS.has(program)) {
+            const flag = args.findIndex(arg => /^-[a-z]*c$/.test(arg));
+            const script = flag >= 0 ? args[flag + 1] : undefined;
+            if (script !== undefined) {
+                findings.push(...classifyShell(script, 1));
+                continue;
+            }
+        }
+        const inPlace = program === "sed" && args.some(arg => arg.startsWith("-i") || arg === "--in-place");
+        const named = args.filter(isKnowledgeBasePath);
+        const written = [...writes.filter(isKnowledgeBasePath), ...(inPlace || WRITE_PROGRAMS.has(program) ? named : [])];
+        if (written.length > 0)
+            findings.push({ kind: "kb_write", paths: written });
+        if (named.length > 0 && READ_PROGRAMS.has(program) && !inPlace)
+            findings.push({ kind: "kb_read", readKind: "shell", paths: named });
+        const cli = cliRule(program, args);
+        if (cli !== null)
+            findings.push(cli);
+    }
+    return findings;
+}
+/** The shell line of a Bash or exec_command input: command or cmd, a string or an argument list. */
+function shellLine(input) {
+    for (const key of ["command", "cmd"]) {
+        const value = input[key];
+        if (typeof value === "string")
+            return value;
+        if (Array.isArray(value) && value.length > 0 && value.every(part => typeof part === "string")) {
+            const parts = value;
+            if (parts.length >= 3 && SHELLS.has(baseName(parts[0])) && /^-[a-z]*c$/.test(parts[1]))
+                return parts[2];
+            return parts.map(part => (/^[A-Za-z0-9_./:=@%+-]+$/.test(part) ? part : `'${part.replace(/'/g, `'\\''`)}'`)).join(" ");
+        }
+    }
+    return null;
+}
+/**
+ * What one PreToolUse call shows (spec section 3.3). An MCP tool counts as knowledge_search or another Gateway tool by
+ * its last name segment. Null when the input cannot be classified: the hook counts it as undecidable.
+ */
+export function classifyToolCall(_app, toolName, toolInput, gatewayToolNames) {
+    if (typeof toolName !== "string")
+        return null;
+    const mcp = MCP_TOOL.exec(toolName);
+    if (mcp) {
+        const findings = [];
+        if (mcp[2] === "knowledge_search")
+            findings.push({ kind: "knowledge_search" });
+        if (gatewayToolNames.includes(mcp[2]))
+            findings.push({ kind: "gateway_tool" });
+        return findings;
+    }
+    if (toolInput === null || typeof toolInput !== "object" || Array.isArray(toolInput))
+        return null;
+    const input = toolInput;
+    const file = typeof input.file_path === "string" ? input.file_path : null;
+    switch (toolName) {
+        case "Read":
+            return file !== null && isKnowledgeBasePath(file) ? [{ kind: "kb_read", readKind: "read_tool", paths: [file] }] : [];
+        case "Grep":
+        case "Glob": {
+            const paths = [input.path, input.glob, toolName === "Glob" ? input.pattern : undefined]
+                .filter((value) => typeof value === "string" && isKnowledgeBasePath(value));
+            return paths.length > 0 ? [{ kind: "kb_read", readKind: "search_tool", paths }] : [];
+        }
+        case "Edit":
+        case "Write":
+            return file !== null && isKnowledgeBasePath(file) ? [{ kind: "kb_write", paths: [file] }] : [];
+        case "apply_patch": {
+            const patch = typeof input.command === "string" ? input.command : typeof input.input === "string" ? input.input : "";
+            const paths = [...patch.matchAll(PATCH_FILE)].map(match => match[1].trim()).filter(isKnowledgeBasePath);
+            return paths.length > 0 ? [{ kind: "kb_write", paths }] : [];
+        }
+        case "Bash": {
+            const line = shellLine(input);
+            return line === null ? null : classifyShell(line);
+        }
+        default:
+            return [];
+    }
+}