amness 0.0.0-stage → 0.1.0

package/dist/src/patch.js

@@ -0,0 +1,219 @@
+const strip = (p) => p.replace(/^\s+|\s+$/g, "").replace(/^"|"$/g, "").replace(/^[ab]\//, "");
+export function parsePatch(text) {
+    const L = text.replace(/\r\n/g, "\n").split("\n");
+    return L.some((l) => l.startsWith("*** Begin Patch") || /^\*\*\* (Update|Add|Delete) File:/.test(l)) ? parseEnvelope(L) : parseUnified(L);
+}
+function parseEnvelope(L) {
+    const ops = [];
+    let cur, hunk;
+    const flush = () => { if (cur && hunk && hunk.lines.length)
+        cur.hunks.push(hunk); hunk = undefined; };
+    for (const l of L) {
+        let m;
+        if (l.startsWith("*** Begin Patch") || l.startsWith("*** End Patch") || l.startsWith("*** End of File")) {
+            flush();
+            if (l.startsWith("*** End Patch"))
+                break;
+            continue;
+        }
+        if ((m = /^\*\*\* (Update|Add|Delete) File:\s*(.+)$/.exec(l))) {
+            flush();
+            cur = { path: strip(m[2]), op: m[1].toLowerCase(), hunks: [] };
+            ops.push(cur);
+            continue;
+        }
+        if (!cur)
+            continue;
+        if ((m = /^\*\*\* Move to:\s*(.+)$/.exec(l))) {
+            cur.moveTo = strip(m[1]);
+            continue;
+        }
+        if (l.startsWith("@@")) {
+            flush();
+            hunk = { anchor: l.slice(2).trim() || undefined, lines: [] };
+            continue;
+        }
+        if (cur.op === "delete")
+            continue;
+        const c = l[0];
+        if (c === "+" || c === "-" || c === " " || l === "") {
+            hunk ??= { lines: [] };
+            hunk.lines.push({ t: (c === "+" || c === "-" ? c : " "), s: l === "" ? "" : l.slice(1) });
+        }
+    }
+    flush();
+    for (const o of ops)
+        if (o.op === "add") {
+            const all = o.hunks.flatMap((h) => h.lines.map((x) => x.s));
+            o.hunks = [{ lines: all.map((s) => ({ t: "+", s })) }];
+        }
+    return ops;
+}
+function parseUnified(L) {
+    const ops = [];
+    let cur, hunk, from = "";
+    const flush = () => { if (hunk) {
+        while (hunk.lines.length && hunk.lines.at(-1).t === " " && hunk.lines.at(-1).s === "")
+            hunk.lines.pop();
+    } if (cur && hunk && hunk.lines.length)
+        cur.hunks.push(hunk); hunk = undefined; }; // the blank line after the last newline is not context
+    for (let i = 0; i < L.length; i++) {
+        const l = L[i];
+        if (l.startsWith("--- ") && L[i + 1]?.startsWith("+++ ")) {
+            flush();
+            from = l.slice(4).split("\t")[0];
+            const to = L[++i].slice(4).split("\t")[0];
+            const add = /^\/dev\/null/.test(from), del = /^\/dev\/null/.test(to);
+            cur = { path: strip(del ? from : to), op: add ? "add" : del ? "delete" : "update", hunks: [] };
+            ops.push(cur);
+            continue;
+        }
+        if (!cur)
+            continue;
+        const h = /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@\s*(.*)$/.exec(l);
+        if (h) {
+            flush();
+            hunk = { hint: Number(h[1]), anchor: h[2] || undefined, lines: [] };
+            continue;
+        }
+        if (!hunk || l.startsWith("\\"))
+            continue;
+        const c = l[0];
+        if (c === "+" || c === "-" || c === " ")
+            hunk.lines.push({ t: c, s: l.slice(1) });
+        else if (l === "")
+            hunk.lines.push({ t: " ", s: "" });
+    }
+    flush();
+    return ops;
+}
+/** Every path a patch touches (for permission checks). */
+export function patchPaths(text) { try {
+    return [...new Set(parsePatch(text).flatMap((o) => [o.path, ...(o.moveTo ? [o.moveTo] : [])]))];
+}
+catch {
+    return [];
+} }
+const same = (a, b) => a === b || a.trimEnd() === b.trimEnd();
+const loose = (a, b) => a.trim() === b.trim();
+/** First index >= from where `seq` matches the file lines (exactly, then ignoring trailing space, then ignoring indentation). */
+function find(file, seq, from) {
+    if (!seq.length)
+        return { at: Math.min(from, file.length), fuzzy: false };
+    for (const [eq, fuzzy] of [[(a, b) => a === b, false], [same, false], [loose, true]]) {
+        for (let i = from; i + seq.length <= file.length; i++) {
+            let ok = true;
+            for (let j = 0; j < seq.length && ok; j++)
+                ok = eq(file[i + j], seq[j]);
+            if (ok)
+                return { at: i, fuzzy };
+        }
+    }
+    return undefined;
+}
+/** Re-indent replacement lines when the match was found ignoring indentation: shift by the difference in leading whitespace of the first matched line. */
+function reindent(newLines, oldFirst, fileFirst) {
+    const lead = (s) => /^\s*/.exec(s)[0], a = lead(oldFirst), b = lead(fileFirst);
+    if (a === b)
+        return newLines;
+    return newLines.map((l) => (l.trim() === "" ? l : l.startsWith(a) ? b + l.slice(a.length) : l));
+}
+export function applyOps(ops, read) {
+    const applied = [], errors = [], seen = new Set();
+    for (const o of ops) {
+        if (seen.has(o.path)) {
+            errors.push(`${o.path}: appears twice in the patch; put all its hunks under one heading`);
+            continue;
+        }
+        seen.add(o.path);
+        const before = read(o.path);
+        if (o.op === "add") {
+            if (before !== undefined)
+                errors.push(`${o.path}: cannot add, the file already exists (use Update File)`);
+            else
+                applied.push({ path: o.path, before: null, after: o.hunks.flatMap((h) => h.lines.map((x) => x.s)).join("\n") + "\n", fuzzy: 0 });
+            continue;
+        }
+        if (before === undefined) {
+            errors.push(`${o.path}: no such file`);
+            continue;
+        }
+        if (o.op === "delete") {
+            applied.push({ path: o.path, before, after: null, fuzzy: 0 });
+            continue;
+        }
+        const trailing = before.endsWith("\n"), file = before.split("\n");
+        if (trailing)
+            file.pop();
+        let cursor = 0, fuzzy = 0, bad = false;
+        o.hunks.forEach((h, hi) => {
+            if (bad)
+                return;
+            const oldSeq = h.lines.filter((x) => x.t !== "+").map((x) => x.s), newSeq = h.lines.filter((x) => x.t !== "-").map((x) => x.s);
+            let from = cursor;
+            if (h.anchor) {
+                const a = find(file, [h.anchor], cursor);
+                if (a)
+                    from = a.at;
+            } // "@@ function name" narrows where to look
+            else if (h.hint && h.hint - 1 >= cursor && h.hint - 1 <= file.length) {
+                const near = find(file, oldSeq, Math.max(cursor, h.hint - 1 - 3));
+                if (near && near.at <= h.hint - 1 + 3)
+                    from = near.at;
+            }
+            const m = find(file, oldSeq, from) ?? (from > cursor ? find(file, oldSeq, cursor) : undefined);
+            if (!m) {
+                errors.push(`${o.path}, hunk ${hi + 1}: the lines to replace were not found${h.anchor ? ` after "${h.anchor}"` : ""}. First line looked for: ${JSON.stringify(oldSeq.find((s) => s.trim()) ?? oldSeq[0] ?? "")}`);
+                bad = true;
+                return;
+            }
+            if (m.fuzzy)
+                fuzzy++;
+            file.splice(m.at, oldSeq.length, ...(m.fuzzy ? reindent(newSeq, oldSeq[0] ?? "", file[m.at] ?? "") : newSeq));
+            cursor = m.at + newSeq.length;
+        });
+        if (!bad)
+            applied.push({ path: o.moveTo ?? o.path, before, after: file.join("\n") + (trailing ? "\n" : ""), fuzzy });
+        if (!bad && o.moveTo && o.moveTo !== o.path)
+            applied.push({ path: o.path, before, after: null, fuzzy: 0 });
+    }
+    return { applied: errors.length ? [] : applied, errors };
+}
+/** Replace `old` by `nw` in `content`: exactly once. When there is no exact match and `old` spans whole lines, a match that differs only in indentation or trailing space is accepted if it is unique (and reported). */
+export function replaceOnce(content, old, nw) {
+    if (!old)
+        return { error: "`old` is empty" };
+    const n = content.split(old).length - 1;
+    if (n === 1)
+        return { out: content.replace(old, () => nw) };
+    if (n > 1)
+        return { error: `\`old\` matched ${n} times; it must match exactly once. Include more surrounding lines.` };
+    const oldLines = old.replace(/\n$/, "").split("\n"), file = content.split("\n"), hits = [];
+    if (oldLines.length >= 1 && (oldLines.length > 1 || oldLines[0].trim() === (file.find((l) => l.trim() === oldLines[0].trim()) ?? "\0").trim()))
+        for (let i = 0; i + oldLines.length <= file.length; i++) {
+            let ok = true;
+            for (let j = 0; j < oldLines.length && ok; j++)
+                ok = file[i + j].trim() === oldLines[j].trim();
+            if (ok)
+                hits.push(i);
+        }
+    if (hits.length === 1) {
+        const rep = reindent(nw.replace(/\n$/, "").split("\n"), oldLines[0], file[hits[0]]);
+        file.splice(hits[0], oldLines.length, ...rep);
+        return { out: file.join("\n"), fuzzy: true };
+    }
+    return { error: hits.length > 1 ? `\`old\` did not match exactly, and ${hits.length} places match ignoring indentation; include more surrounding lines.` : "`old` was not found in the file (check the exact text, including indentation; read the file again if it may have changed)." };
+}
+/** Apply several edits in order to one file's text; all-or-nothing. */
+export function replaceMany(content, edits) {
+    let cur = content, fuzzy = 0;
+    for (const [i, e] of edits.entries()) {
+        const r = replaceOnce(cur, e.old, e.new);
+        if ("error" in r)
+            return { error: `edit ${i + 1} of ${edits.length}: ${r.error}` };
+        cur = r.out;
+        if (r.fuzzy)
+            fuzzy++;
+    }
+    return { out: cur, fuzzy };
+}

package/dist/src/permissions.d.ts

@@ -0,0 +1,46 @@
+export type PermConfig = {
+    allow?: string[];
+    ask?: string[];
+    deny?: string[];
+};
+export type Verdict = {
+    action: "allow" | "ask" | "deny" | "none";
+    rule?: string;
+    reason?: string; /** came from the built-in floor: session shortcuts must not bypass it */
+    floor?: boolean;
+};
+export type PermissionChecker = {
+    check(tool: string, args: Record<string, any>): Verdict;
+};
+/** Split a shell command into the commands it runs. Quotes are respected; anything we cannot reason about (subshells, backticks) is reported. */
+export declare function splitCommand(cmd: string): {
+    parts: string[];
+    opaque: boolean;
+};
+/** A command the way the shell will see it, for detection: quotes and backslash escapes inside words removed (r""m, r\m, "rm"), $'\x72m' decoded, ${IFS} turned into a space. Never used to RUN anything. */
+export declare function normalizeCommand(cmd: string): string;
+/** The command plus every other form it may take: normalised, and the text of nested `sh -c '...'`, `bash -c "..."` and `eval "..."` (recursively). All of them are checked against the floor and the risk list. */
+export declare function commandViews(cmd: string, depth?: number): string[];
+/** Decoding a payload and running it is how checks get dodged; it always deserves a human look. */
+export declare const OBFUSCATED_EXEC: RegExp;
+export declare function floorCheck(tool: string, args: Record<string, any>, cwd: string): Verdict;
+export declare class Permissions implements PermissionChecker {
+    private cfg;
+    private cwd;
+    constructor(cfg: PermConfig, cwd: string);
+    static projectFile(cwd: string): string;
+    /** `deny` and `ask` from any file always apply (they only restrict); `allow` from a project file needs `trustProject`, since it removes prompts. */
+    static load(cwd: string, o?: {
+        trustProject?: boolean;
+        userDir?: string;
+    }): Permissions;
+    /** Append a rule to the project file (used by the approval dialog and `/permissions`). */
+    static addProjectRule(cwd: string, list: "allow" | "ask" | "deny", rule: string): void;
+    rules(): Required<PermConfig>;
+    private matches;
+    /** Per-command matching for shell: a compound command is checked piece by piece. */
+    private anyMatch;
+    check(tool: string, args: Record<string, any>): Verdict;
+}
+/** Fingerprint of the project files that can remove prompts or run commands (hooks and permission rules): approve once, re-approve when they change. */
+export declare function projectConfigFingerprint(cwd: string): string | undefined;

package/dist/src/permissions.js

@@ -0,0 +1,245 @@
+// Permission rules and a hard floor. Rules live in .amness/permissions.json (project) and ~/.amness/permissions.json (yours):
+//   { "allow": ["sh(npm test*)", "edit(src/**)"], "ask": ["sh(git commit*)"], "deny": ["sh(git push*)", "edit(.env)"] }
+// Order of precedence: floor > deny > ask > allow > the permission mode. The floor holds in EVERY mode, yolo included.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { patchPaths } from "./patch.js";
+const SHELL = new Set(["sh", "sh_start"]), EDIT = new Set(["edit_file", "write_file", "apply_patch"]), READ = new Set(["read_file", "grep", "list_files"]);
+const kindOf = (tool) => (SHELL.has(tool) ? "sh" : EDIT.has(tool) ? "edit" : READ.has(tool) ? "read" : tool);
+/** `*` matches within a path segment... except in commands, where it matches anything; `**` crosses folders. */
+const glob = (pat, loose) => {
+    const re = pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\u0000").replace(/\*/g, loose ? ".*" : "[^/]*").replace(/\u0000/g, ".*").replace(/\?/g, loose ? "." : "[^/]");
+    return new RegExp(`^${re}$`, "s");
+};
+const parseRule = (r) => { const m = /^([\w:.-]+?)(?:\((.*)\))?$/s.exec(r.trim()); return m ? { kind: m[1], pat: m[2] } : undefined; };
+/** Split a shell command into the commands it runs. Quotes are respected; anything we cannot reason about (subshells, backticks) is reported. */
+export function splitCommand(cmd) {
+    const parts = [];
+    let cur = "", q = "", opaque = false;
+    for (let i = 0; i < cmd.length; i++) {
+        const c = cmd[i], n = cmd[i + 1];
+        if (q) {
+            if (c === q)
+                q = "";
+            else if (c === "\\" && q === '"') {
+                cur += c + (n ?? "");
+                i++;
+                continue;
+            }
+            else if (q === '"' && (c === "`" || (c === "$" && n === "(")))
+                opaque = true;
+            cur += c;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            q = c;
+            cur += c;
+            continue;
+        }
+        if (c === "\\") {
+            cur += c + (n ?? "");
+            i++;
+            continue;
+        }
+        if (c === "`" || (c === "$" && n === "(") || ((c === "<" || c === ">") && n === "("))
+            opaque = true;
+        if (c === ";" || c === "\n" || c === "|" || c === "&") {
+            if (cur.trim())
+                parts.push(cur.trim());
+            cur = "";
+            if ((c === "|" || c === "&") && n === c)
+                i++;
+            continue;
+        }
+        cur += c;
+    }
+    if (cur.trim())
+        parts.push(cur.trim());
+    return { parts, opaque };
+}
+;
+/** A command the way the shell will see it, for detection: quotes and backslash escapes inside words removed (r""m, r\m, "rm"), $'\x72m' decoded, ${IFS} turned into a space. Never used to RUN anything. */
+export function normalizeCommand(cmd) {
+    let s = cmd.replace(/\$'((?:[^'\\]|\\.)*)'/g, (_m, body) => body.replace(/\\x([0-9a-fA-F]{2})/g, (_x, h) => String.fromCharCode(parseInt(h, 16))).replace(/\\([0-7]{1,3})/g, (_x, o) => String.fromCharCode(parseInt(o, 8))).replace(/\\(.)/g, "$1"));
+    s = s.replace(/\$\{IFS\}|\$IFS/g, " ");
+    return s.replace(/\\(?=[A-Za-z0-9_./~-])/g, "").replace(/(["'])\1/g, "").replace(/["']/g, "");
+}
+/** The command plus every other form it may take: normalised, and the text of nested `sh -c '...'`, `bash -c "..."` and `eval "..."` (recursively). All of them are checked against the floor and the risk list. */
+export function commandViews(cmd, depth = 0) {
+    const views = new Set([cmd, normalizeCommand(cmd)]);
+    if (depth < 3)
+        for (const m of cmd.matchAll(/\b(?:ba|z|da|k)?sh\s+(?:-\w*c\w*)\s+(?:"((?:[^"\\]|\\.)*)"|'([^']*)')|\beval\s+(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+))/g)) {
+            const inner = m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5];
+            if (inner)
+                for (const v of commandViews(inner, depth + 1))
+                    views.add(v);
+        }
+    return [...views];
+}
+/** Decoding a payload and running it is how checks get dodged; it always deserves a human look. */
+export const OBFUSCATED_EXEC = /\b(?:base64|b64decode|xxd\s+-r|openssl\s+(?:enc|base64)\b)[^|;&]*\|\s*(?:sudo\s+)?(?:ba|z|da|k)?sh\b|\beval\s+["']?\$\(|\b(?:ba|z|da|k)?sh\s+<\(\s*(?:curl|wget)|\bpython3?\s+-c\s+["'][^"']*(?:base64|exec\(|__import__)/;
+// ---- the floor: refused or always-asked, whatever the mode ------------------------------------------------------------------------------
+const PROTECTED = /(^|\/)\.amness\/(hooks|permissions)\.json$/;
+const FLOOR_DENY = [
+    [/\brm\s+(?:-\S+\s+)*-\S*[rRf]\S*\s+(?:-\S+\s+)*(?:\/\*?|~\/?\*?|\$HOME\/?\*?|\$\{HOME\}\/?\*?|\.\.(?:\/\S*)?)(?=\s|$)/, "recursive delete of the root, your home folder or a parent folder"],
+    [/(?:^|[\s;&|])(?:sudo\s+)?mkfs(?:\.\w+)?\b/, "formatting a filesystem"],
+    [/\bdd\b[^|;&]*\bof=\/dev\/(?:sd|nvme|disk|hd|mmcblk)/, "writing raw data to a disk device"],
+    [/>\s*\/dev\/(?:sd|nvme|disk|hd|mmcblk)/, "writing to a disk device"],
+    [/:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, "a fork bomb"],
+    [/\bchmod\s+-R\s+0?777\s+\/(?:\s|$)/, "making the whole filesystem world-writable"],
+    [/\bgit\s+(?:-\S+\s+)*push\b[^|;&]*\s(?:--force(?!-with-lease)|-f)\b[^|;&]*\b(?:main|master)\b/, "force-pushing to main or master"],
+    // Windows families (PowerShell and cmd): the same kinds of damage
+    [/\b(?:Remove-Item|ri|rm|del|erase)\b[^|;&\n]*-Recurse\b[^|;&\n]*(?:\s|['"])(?:[A-Za-z]:[\\/]?(?=\s|['"]|$)|[\\/](?=\s|['"]|$)|~(?=[\\/]?(?:\s|['"]|$))|\$HOME\b|\$env:(?:USERPROFILE|HOMEPATH|SystemRoot|SystemDrive)\b)/i, "recursive delete of a drive, your home folder or the system folder"],
+    [/\b(?:rd|rmdir|del|erase)\s+(?:\/[a-z]\s+)*\/s\b[^&|\n]*\s(?:[A-Za-z]:[\\/]?(?:\*(?:\.\*)?)?|%(?:USERPROFILE|HOMEPATH|SystemRoot|SystemDrive)%)(?=\s|$)/i, "recursive delete of a drive, your home folder or the system folder"],
+    [/\bFormat-Volume\b|\bformat(?:\.com)?\s+[A-Za-z]:(?=\s|$)|\bClear-Disk\b|\bInitialize-Disk\b/i, "formatting or wiping a disk"],
+];
+const FLOOR_ASK = [
+    [/\b(?:curl|wget)\b[^|;&]*\|\s*(?:sudo\s+)?(?:ba|z|da|k)?sh\b/, "downloads and runs a script"],
+    [/\bgit\s+(?:-\S+\s+)*push\b[^|;&]*\s(?:--force|--force-with-lease|-f)\b/, "force-pushes"],
+    [/\b(?:Invoke-WebRequest|iwr|Invoke-RestMethod|irm|curl|wget)\b[^|;\n]*\|\s*(?:Invoke-Expression|iex)\b/i, "downloads and runs a script"],
+    [/(?:^|[\s;&|])-(?:EncodedCommand|enc|ec)\s+\S+|\bFromBase64String\b[^;\n]*\b(?:Invoke-Expression|iex)\b/i, "runs an encoded command"],
+];
+const WRITES_PROTECTED = /\.amness\/(?:hooks|permissions)\.json/;
+const READONLY_VERB = /^\s*(?:cat|head|tail|less|grep|rg|ls|wc|stat|file|diff)\b/;
+/** The text of an apply_patch call: inline, or read from the patch file it names (so rules and the floor see the real paths). */
+const patchOf = (args, cwd) => { if (typeof args.patch === "string")
+    return args.patch; try {
+    return typeof args.file === "string" ? readFileSync(resolve(cwd, args.file), "utf8") : "";
+}
+catch {
+    return "";
+} };
+export function floorCheck(tool, args, cwd) {
+    if (tool === "apply_patch") {
+        for (const p of patchPaths(patchOf(args, cwd))) {
+            const v = floorCheck("edit_file", { path: p }, cwd);
+            if (v.action !== "none")
+                return v;
+        }
+        return { action: "none" };
+    }
+    const kind = kindOf(tool);
+    if (kind === "edit" && typeof args.path === "string") {
+        const rel = relative(cwd, resolve(cwd, args.path)).split("\\").join("/");
+        if (rel === ".git" || rel.startsWith(".git/"))
+            return { action: "deny", floor: true, reason: "the .git folder is protected: change history with git commands you can see, not by editing its files" };
+        if (PROTECTED.test(rel))
+            return { action: "deny", floor: true, reason: "the agent may not edit its own hooks or permission rules" };
+    }
+    if (kind === "sh" && typeof args.cmd === "string") {
+        const cmd = args.cmd;
+        if (WRITES_PROTECTED.test(cmd) && !splitCommand(cmd).parts.every((p) => READONLY_VERB.test(p)))
+            return { action: "deny", floor: true, reason: "the agent may not change its own hooks or permission rules" };
+        const views = commandViews(cmd);
+        for (const [re, why] of FLOOR_DENY)
+            if (views.some((v) => re.test(v)))
+                return { action: "deny", floor: true, reason: why };
+        for (const [re, why] of FLOOR_ASK)
+            if (views.some((v) => re.test(v)))
+                return { action: "ask", floor: true, reason: why };
+        if (OBFUSCATED_EXEC.test(cmd) || OBFUSCATED_EXEC.test(views[1] ?? ""))
+            return { action: "ask", floor: true, reason: "decodes or downloads a payload and runs it" };
+    }
+    return { action: "none" };
+}
+const readCfg = (file) => {
+    if (!existsSync(file))
+        return {};
+    const j = JSON.parse(readFileSync(file, "utf8")), out = {};
+    for (const k of ["allow", "ask", "deny"]) {
+        const l = j[k];
+        if (l === undefined)
+            continue;
+        if (!Array.isArray(l) || l.some((x) => typeof x !== "string" || !parseRule(x)))
+            throw new Error(`${file}: "${k}" must be a list of rules like "sh(npm test*)" or "edit(src/**)"`);
+        out[k] = l;
+    }
+    return out;
+};
+export class Permissions {
+    cfg;
+    cwd;
+    constructor(cfg, cwd) { this.cfg = { allow: cfg.allow ?? [], ask: cfg.ask ?? [], deny: cfg.deny ?? [] }; this.cwd = resolve(cwd); }
+    static projectFile(cwd) { return join(cwd, ".amness", "permissions.json"); }
+    /** `deny` and `ask` from any file always apply (they only restrict); `allow` from a project file needs `trustProject`, since it removes prompts. */
+    static load(cwd, o = {}) {
+        const user = readCfg(join(o.userDir ?? process.env.AMNESS_HOME ?? join(homedir(), ".amness"), "permissions.json")), proj = readCfg(Permissions.projectFile(cwd));
+        return new Permissions({ allow: [...(user.allow ?? []), ...(o.trustProject ? proj.allow ?? [] : [])], ask: [...(user.ask ?? []), ...(proj.ask ?? [])], deny: [...(user.deny ?? []), ...(proj.deny ?? [])] }, cwd);
+    }
+    /** Append a rule to the project file (used by the approval dialog and `/permissions`). */
+    static addProjectRule(cwd, list, rule) {
+        if (!parseRule(rule))
+            throw new Error(`not a rule: ${rule}`);
+        const f = Permissions.projectFile(cwd);
+        let cur = {};
+        try {
+            cur = existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {};
+        }
+        catch { /* start fresh */ }
+        cur[list] = [...new Set([...(cur[list] ?? []), rule])];
+        mkdirSync(dirname(f), { recursive: true });
+        writeFileSync(f, JSON.stringify(cur, null, 2) + "\n");
+    }
+    rules() { return this.cfg; }
+    matches(rule, tool, args) {
+        const r = parseRule(rule);
+        if (!r)
+            return false;
+        const kind = kindOf(tool);
+        if (r.kind !== kind && r.kind !== tool)
+            return false;
+        if (r.pat === undefined)
+            return true;
+        if (kind === "sh")
+            return typeof args.cmd === "string" && glob(r.pat, true).test(args.cmd.trim());
+        const p = typeof args.path === "string" ? args.path : typeof args.pattern === "string" ? args.pattern : undefined;
+        if (p !== undefined && (kind === "edit" || kind === "read")) {
+            const rel = relative(this.cwd, isAbsolute(p) ? p : resolve(this.cwd, p)).split("\\").join("/");
+            return glob(r.pat, false).test(rel) || glob(r.pat, false).test(p);
+        }
+        return glob(r.pat, true).test(JSON.stringify(args));
+    }
+    /** Per-command matching for shell: a compound command is checked piece by piece. */
+    anyMatch(list, tool, args) {
+        if (kindOf(tool) === "sh" && typeof args.cmd === "string") {
+            const { parts } = splitCommand(args.cmd);
+            return list.find((rule) => this.matches(rule, tool, args) || parts.some((p) => this.matches(rule, tool, { ...args, cmd: p })));
+        }
+        return list.find((r) => this.matches(r, tool, args));
+    }
+    check(tool, args) {
+        if (tool === "apply_patch") { // a patch is judged file by file: any denied file denies it, any "ask" asks, and it is only allowed when every file is
+            const paths = patchPaths(patchOf(args, this.cwd)), per = paths.map((p) => this.check("edit_file", { path: p }));
+            return per.find((v) => v.action === "deny") ?? per.find((v) => v.action === "ask") ?? (per.length && per.every((v) => v.action === "allow") ? { action: "allow", rule: per[0].rule } : { action: "none" });
+        }
+        const floor = floorCheck(tool, args, this.cwd);
+        if (floor.action !== "none")
+            return floor;
+        const deny = this.anyMatch(this.cfg.deny, tool, args);
+        if (deny)
+            return { action: "deny", rule: deny, reason: `denied by your permission rule \`${deny}\`` };
+        const ask = this.anyMatch(this.cfg.ask, tool, args);
+        if (ask)
+            return { action: "ask", rule: ask, reason: `matches your rule \`${ask}\`, which requires approval` };
+        if (kindOf(tool) === "sh" && typeof args.cmd === "string") {
+            const { parts, opaque } = splitCommand(args.cmd);
+            if (!opaque && parts.length && parts.every((p) => this.cfg.allow.some((r) => this.matches(r, tool, { ...args, cmd: p }))))
+                return { action: "allow", rule: this.cfg.allow.find((r) => this.matches(r, tool, { ...args, cmd: parts[0] })) };
+            return { action: "none" };
+        }
+        const allow = this.cfg.allow.find((r) => this.matches(r, tool, args));
+        return allow ? { action: "allow", rule: allow } : { action: "none" };
+    }
+}
+/** Fingerprint of the project files that can remove prompts or run commands (hooks and permission rules): approve once, re-approve when they change. */
+export function projectConfigFingerprint(cwd) {
+    const files = [join(cwd, ".amness", "hooks.json"), Permissions.projectFile(cwd)].filter(existsSync);
+    if (!files.length)
+        return undefined;
+    const h = createHash("sha256");
+    for (const f of files)
+        h.update(f).update(readFileSync(f));
+    return h.digest("hex").slice(0, 16);
+}

package/dist/src/plugins.d.ts

@@ -0,0 +1,148 @@
+import type { Case, MetricFn, Variant } from "./evals.ts";
+import type { Grader } from "./grade.ts";
+import type { Guard, Message, Model, Tool } from "./harness.ts";
+import type { MemoryBackend } from "./memory.ts";
+import type { RouteInfo } from "./router.ts";
+import type { HookEvent, HookRunner } from "./hooks.ts";
+export type HookReturn = {
+    block?: string;
+    context?: string;
+    args?: Record<string, unknown>; /** PreModel only: the tools that may be called in this turn */
+    tools?: string[];
+    then?: string;
+} | string | void;
+export type HookHandler = (payload: Record<string, unknown> & {
+    event: HookEvent;
+    cwd: string;
+}) => HookReturn | Promise<HookReturn>;
+/** A harness variant for `amness eval`, as data (switch guards off, add plugins, change the prompt) or as code (`build` returns the whole Variant). */
+export type VariantSpec = {
+    off?: Guard[];
+    maxSteps?: number; /** run with the case's verify command as the finish gate (default true) */
+    verify?: boolean;
+    review?: boolean;
+    /** plugins (by name) active in this variant, in addition to the plugin that defines it */ plugins?: string[];
+    system?: (base: string) => string;
+    build?: (model: Model, o: {
+        maxSteps?: number;
+        maxTokens?: number;
+    }) => Variant;
+};
+/** What a plugin's slash command can do: print, send a message to the agent, run a command, read the folder. Nothing else of the UI is exposed on purpose. */
+export type PluginCtx = {
+    cwd: string;
+    say(text: string): void; /** send a message to the agent, as if you had typed it */
+    ask(text: string): Promise<void>;
+    run(cmd: string, timeoutMs?: number): Promise<{
+        code: number;
+        output: string;
+    }>;
+};
+export type PluginCommand = {
+    name: string;
+    help: string;
+    args?: string;
+    run(ctx: PluginCtx, arg: string): void | Promise<void>;
+};
+/** A tool call about to run, as a policy sees it. */
+export type PolicyCall = {
+    tool: string;
+    args: Record<string, unknown>;
+    cwd: string;
+};
+export type PolicyDecision = {
+    action: "allow" | "ask" | "deny";
+    reason?: string;
+    plugin?: string;
+};
+export type PolicyResult = "allow" | "ask" | "deny" | {
+    action: "allow" | "ask" | "deny";
+    reason?: string;
+} | void;
+/**
+ * Ask every plugin's `policy`. A deny always wins, then an ask, then an allow. The caller decides what each answer may do:
+ * the harness never lets a policy relax the safety floor or the untrusted-text check, only tighten them or skip an ordinary prompt.
+ */
+export declare function checkPolicies(plugins: Plugin[], call: PolicyCall): Promise<PolicyDecision | undefined>;
+/** A finish gate: your own check that must pass before the agent may finish. It sees what really happened (files changed, whether tests passed after the last edit) and can run commands. */
+export type GateCtx = {
+    summary: string;
+    task: string;
+    changed: string[];
+    testsAfterLastEdit?: boolean;
+    notes: string[];
+    cwd: string;
+    run: PluginCtx["run"]; /** how many times this gate has already rejected this task */
+    rejections: number;
+};
+export type GateResult = boolean | string | string[] | {
+    pass: boolean;
+    findings?: string[];
+} | void;
+export type FinishGate = {
+    name: string; /** rejections before the run may finish anyway (default 2, so a wrong gate cannot trap the agent) */
+    maxRejections?: number;
+    check(ctx: GateCtx): GateResult | Promise<GateResult>;
+};
+/** Several reviewers vote: the finish is accepted when at least `quorum` of them pass ("all", "majority", or a number). */
+export declare function votingGate(name: string, reviewers: {
+    name: string;
+    review(ctx: GateCtx): GateResult | Promise<GateResult>;
+}[], quorum?: "all" | "majority" | number, maxRejections?: number): FinishGate;
+export type Plugin = {
+    name: string;
+    description?: string;
+    tools?: Tool[];
+    hooks?: Partial<Record<HookEvent, HookHandler>>;
+    /** a handler that throws blocks instead of warning (for hooks that enforce a rule) */ failClosed?: boolean;
+    /** your own context strategy (compaction, clearing, memory injection): called before every model request, may return a replacement message list */ context?: (msgs: Message[], info: {
+        step: number;
+        promptTokens: number;
+        budget: number;
+    }) => Message[] | void | Promise<Message[] | void>;
+    /** replace the built-in memory (notes saved and recalled across sessions) with your own backend; the first plugin that provides one wins */ memory?: MemoryBackend | ((cwd: string) => MemoryBackend);
+    /** choose the model for each request: return a model id (same provider; needs `modelById`), or nothing to use the default. Sees the conversation, its size and what the last steps were. */ route?: (info: RouteInfo) => string | undefined | void;
+    /** a short line shown in the sidebar (and updated as you work): branch policy, build state, ticket id, anything. Keep it fast: it runs on every redraw (the result is cached for one second). */ status?: (ctx: {
+        cwd: string;
+        running: boolean;
+    }) => string | undefined | void;
+    /** policy as code: decide allow, ask or deny for each tool call before it runs. It can tighten anything, and it can skip an ordinary approval prompt, but it can never loosen the safety floor or the untrusted-text check. */ policy?: (call: PolicyCall) => PolicyResult | Promise<PolicyResult>;
+    /** finish gates: your own checks that must pass before the agent may finish (see GateCtx) */ gates?: FinishGate[];
+    /** slash commands for the chat (a name that a built-in command already uses is skipped) */ commands?: PluginCommand[];
+    /** rewrite the system prompt (runs once per conversation start) */ system?: (base: string, ctx: {
+        cwd: string;
+    }) => string;
+    /** evaluation: tasks with graders written as functions, and harness variants */ cases?: Case[]; /** graders for real sessions (`amness plugin grade`): functions of a recorded session that return a score */
+    graders?: Record<string, Grader>; /** custom numbers to record for every eval run (see MetricFn) */
+    metrics?: Record<string, MetricFn>;
+    variants?: Record<string, VariantSpec>;
+};
+/** Identity function that gives you types and completion while writing a plugin. */
+export declare const definePlugin: (p: Plugin) => Plugin;
+export declare const projectPluginDir: (cwd: string) => string;
+export declare const projectPluginFiles: (cwd: string) => string[];
+/** A fingerprint of the project's plugin files: approval is remembered for exactly this content. */
+export declare function pluginFingerprint(cwd: string): string | undefined;
+export type Loaded = {
+    plugins: Plugin[];
+    warnings: string[]; /** project plugins exist but were not loaded because they are not approved */
+    untrusted?: {
+        count: number;
+        fingerprint: string;
+    };
+};
+/** Import one plugin file (also used by `amness eval --plugin <file>`, where passing the file is the approval). */
+export declare function importPlugins(file: string): Promise<{
+    plugins: Plugin[];
+    warnings: string[];
+}>;
+/** User plugins always load; project plugins only when `trustProject`. Problems are warnings, never exceptions: a broken plugin must not stop the agent starting. */
+export declare function loadPlugins(cwd: string, o?: {
+    trustProject?: boolean;
+    userDir?: string;
+}): Promise<Loaded>;
+/** Hooks from plugins, run in-process after the shell hooks. Same rules as shell hooks: the first block stops the rest, context accumulates, the last rewritten args win. */
+export declare function composeHooks(shell: HookRunner | undefined, plugins: Plugin[], cwd: string): HookRunner | undefined;
+export declare const applySystem: (plugins: Plugin[], base: string, cwd: string) => string;
+/** A starting point for `amness plugin new <name>`. */
+export declare const pluginTemplate: (name: string) => string;