agentopology 0.9.1 → 0.10.0

package/dist/__tests__/e2e/conformance.test.js

@@ -0,0 +1,109 @@
+/**
+ * Conformance v0: the claude-code binding's generated hooks, run against
+ * Claude Code's hook contract (src/conformance/claude-code.ts, checked against
+ * the docs for Claude Code 2.1.319).
+ *
+ * For every example and fixture: the settings.json hooks and each agent's
+ * frontmatter hooks are checked statically, then every command hook is run
+ * the way Claude Code runs it (a shell, the session's current directory,
+ * CLAUDE_PROJECT_DIR set, the event's JSON on stdin). The working directory is
+ * a subfolder on purpose: hooks run where Claude is, not at the project root.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "../../parser/index.js";
+import { claudeCodeBinding } from "../../bindings/claude-code.js";
+import { checkHooks, checkStdout, payloadFor, unanchoredScript, VERIFIED_ON, HOOK_EVENTS } from "../../conformance/claude-code.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, "../../..");
+const CORPUS = [
+    ...fs.readdirSync(join(repo, "examples")).filter((f) => f.endsWith(".at")).map((f) => join(repo, "examples", f)),
+    join(here, "fixtures/compile.at"),
+    join(here, "fixtures/hazards.at"),
+    join(repo, "kitchen-sink.at"),
+];
+const hasJq = spawnSync("/bin/sh", ["-c", "command -v jq"]).status === 0;
+/** Command hooks from settings.json and from agent frontmatter. */
+function commandHooks(files) {
+    const out = [];
+    const settings = files.find((f) => f.path === ".claude/settings.json");
+    for (const [event, entries] of Object.entries((settings ? JSON.parse(settings.content).hooks : {}) ?? {})) {
+        for (const e of entries) {
+            for (const h of e.hooks)
+                if (h.type === "command" && h.command)
+                    out.push({ event, matcher: e.matcher, command: h.command, where: "settings.json" });
+        }
+    }
+    for (const f of files.filter((x) => x.path.startsWith(".claude/agents/") && x.path.endsWith(".md"))) {
+        const front = f.content.split(/\n---\n/)[0];
+        let event = "";
+        for (const line of front.split("\n")) {
+            const ev = /^ {2}([A-Za-z]+):\s*$/.exec(line);
+            if (ev)
+                event = ev[1];
+            const cmd = /^\s+(?:- )?command: (".*")\s*$/.exec(line);
+            if (cmd && event)
+                out.push({ event: event === "Stop" ? "SubagentStop" : event, command: JSON.parse(cmd[1]), where: f.path });
+        }
+    }
+    return out;
+}
+it(`[N28] [CF0] the contract names the Claude Code version it was checked on (${VERIFIED_ON})`, () => {
+    expect(VERIFIED_ON).toMatch(/^\d+\.\d+\.\d+$/);
+    expect(HOOK_EVENTS.size).toBe(33);
+});
+it("[N28] [CF0] a relative script path is caught; an anchored or absolute one is not", () => {
+    expect(unanchoredScript("bash .claude/skills/t/scripts/x.sh")).toBe(".claude/skills/t/scripts/x.sh");
+    expect(unanchoredScript('bash "$CLAUDE_PROJECT_DIR/.claude/skills/t/scripts/x.sh"')).toBeNull();
+    expect(unanchoredScript("python3 /opt/check.py --strict")).toBeNull();
+    expect(unanchoredScript("echo hi")).toBeNull();
+});
+for (const file of CORPUS) {
+    const name = file.replace(repo + "/", "");
+    describe(`conformance: ${name}`, () => {
+        const files = claudeCodeBinding.scaffold(parse(fs.readFileSync(file, "utf8")));
+        const settings = files.find((f) => f.path === ".claude/settings.json");
+        const hooks = commandHooks(files);
+        let root;
+        let sub;
+        beforeAll(() => {
+            root = fs.mkdtempSync(join(os.tmpdir(), "at-conformance-"));
+            for (const f of files) {
+                const p = join(root, f.path);
+                fs.mkdirSync(dirname(p), { recursive: true });
+                fs.writeFileSync(p, f.content);
+                if (f.executable)
+                    fs.chmodSync(p, 0o755);
+            }
+            sub = join(root, "src/deep");
+            fs.mkdirSync(sub, { recursive: true });
+        });
+        afterAll(() => fs.rmSync(root, { recursive: true, force: true }));
+        it("[N28] [CF1] settings.json hooks match the contract (events, matchers, handler fields, onFailure, anchored paths)", () => {
+            expect(checkHooks(settings ? JSON.parse(settings.content).hooks ?? {} : {})).toEqual([]);
+        });
+        it("[N28] [CF1] agent frontmatter command hooks name their scripts by an anchored path", () => {
+            const loose = hooks.filter((h) => h.where !== "settings.json").map((h) => unanchoredScript(h.command)).filter(Boolean);
+            expect(loose).toEqual([]);
+        });
+        it.skipIf(!hasJq)("[N28] [CF2] every command hook runs from a subfolder: found, exits 0 or 2, and its stdout is valid for its event", () => {
+            const results = hooks.map((h) => {
+                const r = spawnSync("/bin/sh", ["-c", h.command], {
+                    cwd: sub,
+                    input: JSON.stringify(payloadFor(h.event, sub, h.matcher)),
+                    env: { ...process.env, CLAUDE_PROJECT_DIR: root },
+                    encoding: "utf8",
+                    timeout: 20_000,
+                });
+                const bad = r.status !== 0 && r.status !== 2 ? `exit ${r.status}: ${r.stderr.trim().split("\n").pop()}` : r.status === 0 ? checkStdout(h.event, r.stdout) : null;
+                return bad ? `${h.event} ${h.matcher ?? ""} ${h.command} → ${bad}` : null;
+            });
+            expect(results.filter(Boolean)).toEqual([]);
+        });
+    });
+}
+//# sourceMappingURL=conformance.test.js.map

package/dist/__tests__/e2e/conformance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.test.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/conformance.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/e2e/contract-drift.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Claude Code's hook contract as a committed snapshot (N37).
+ *
+ * spec/claude-code/hooks-contract.json is extracted from the hooks reference
+ * page by scripts/claude-code-drift.mjs; the minimum version's contract
+ * (hooks-contract.2.1.295.json) is derived from it by dropping what requires a
+ * newer version. These tests are offline: they hold the code to the snapshot,
+ * and the script holds the snapshot to the live page.
+ */
+export {};
+//# sourceMappingURL=contract-drift.test.d.ts.map

package/dist/__tests__/e2e/contract-drift.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-drift.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/contract-drift.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/e2e/contract-drift.test.js

@@ -0,0 +1,142 @@
+/**
+ * Claude Code's hook contract as a committed snapshot (N37).
+ *
+ * spec/claude-code/hooks-contract.json is extracted from the hooks reference
+ * page by scripts/claude-code-drift.mjs; the minimum version's contract
+ * (hooks-contract.2.1.295.json) is derived from it by dropping what requires a
+ * newer version. These tests are offline: they hold the code to the snapshot,
+ * and the script holds the snapshot to the live page.
+ */
+import { describe, it, expect } from "vitest";
+import * as fs from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "../../parser/index.js";
+import { claudeCodeBinding } from "../../bindings/claude-code.js";
+import { HOOK_EVENTS, NO_MATCHER_EVENTS, HANDLER_REQUIRED, ON_FAILURE_TYPES, VERIFIED_ON, MINIMUM_VERSION, } from "../../conformance/claude-code.js";
+import { extractHookContract, contractAt, diffContracts, hasDrift, renderDiff } from "../../conformance/extract.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, "../../..");
+const read = (p) => JSON.parse(fs.readFileSync(join(repo, p), "utf8"));
+const current = read("spec/claude-code/hooks-contract.json");
+const minimum = read(`spec/claude-code/hooks-contract.${MINIMUM_VERSION}.json`);
+const fieldsOf = (c, type) => ({ ...c.fields.common, ...c.fields[type === "agent" ? "prompt" : type] });
+describe("the code agrees with the snapshot", () => {
+    it("[N37] [SD1] the event list, the no-matcher events, the handler types and onFailure match the snapshot", () => {
+        expect([...HOOK_EVENTS].sort()).toEqual([...current.events].sort());
+        expect([...NO_MATCHER_EVENTS].sort()).toEqual(current.noMatcherEvents);
+        expect(Object.keys(HANDLER_REQUIRED).sort()).toEqual([...current.handlerTypes].sort());
+        for (const type of current.handlerTypes) {
+            const required = Object.entries(fieldsOf(current, type)).filter(([n, f]) => f.required && n !== "type").map(([n]) => n);
+            expect([...HANDLER_REQUIRED[type]].sort(), type).toEqual(required.sort());
+        }
+        const withOnFailure = current.handlerTypes.filter((t) => "onFailure" in fieldsOf(current, t));
+        expect([...ON_FAILURE_TYPES].sort()).toEqual(withOnFailure.sort());
+    });
+    it("[N37] [SD2] the snapshot is of the verified version; the minimum's is derived from it at MINIMUM_VERSION", () => {
+        expect(current.claudeCode).toBe(VERIFIED_ON);
+        expect(minimum).toEqual(contractAt(current, MINIMUM_VERSION));
+        expect(minimum).toMatchObject({ derived: true, claudeCode: MINIMUM_VERSION });
+    });
+    it("[N37] [SD3] everything the binding writes exists at the minimum version: every event, every handler field", () => {
+        const files = [
+            ...fs.readdirSync(join(repo, "examples")).filter((f) => f.endsWith(".at")).map((f) => join(repo, "examples", f)),
+            ...["compile.at", "hazards.at"].map((f) => join(here, "fixtures", f)),
+            join(repo, "kitchen-sink.at"),
+        ];
+        const problems = [];
+        for (const file of files) {
+            const out = claudeCodeBinding.scaffold(parse(fs.readFileSync(file, "utf8")));
+            const settings = out.find((f) => f.path === ".claude/settings.json");
+            if (!settings)
+                continue;
+            for (const [event, entries] of Object.entries(JSON.parse(settings.content).hooks ?? {})) {
+                if (!minimum.events.includes(event))
+                    problems.push(`${file}: event ${event}`);
+                for (const entry of entries) {
+                    for (const h of entry.hooks ?? []) {
+                        const allowed = fieldsOf(minimum, h.type);
+                        for (const key of Object.keys(h))
+                            if (!(key in allowed))
+                                problems.push(`${file}: ${event} ${h.type}.${key}`);
+                    }
+                }
+            }
+        }
+        expect(problems).toEqual([]);
+    });
+});
+const PAGE = `# Hooks reference
+
+### Matcher patterns
+
+| Matcher value | Evaluated as | Example |
+| :- | :- | :- |
+| \`"*"\` | Match all | every |
+| Only letters | Exact string | \`Bash\` |
+
+| Event | What the matcher filters | Example matcher values |
+| :- | :- | :- |
+| \`PreToolUse\` | tool name | \`Bash\` |
+| \`Stop\`, \`Ping\` | no matcher support | always fires |
+
+#### Common fields
+
+| Field | Required | Description |
+| :- | :- | :- |
+| \`type\` | yes | \`"command"\` or \`"http"\` |
+| \`timeout\` | no | Seconds |
+
+#### Command hook fields
+
+| Field | Required | Description |
+| :- | :- | :- |
+| \`command\` | yes | Shell command |
+| \`onFailure\` | no | Block or continue. Requires Claude Code v2.1.295 or later |
+
+## Hook events
+
+### PreToolUse
+
+\`\`\`bash
+#!/bin/bash
+# a comment in an example, not a heading
+\`\`\`
+
+### Ping
+
+Ping requires Claude Code v2.1.400 or later.
+
+### Stop
+
+## Debug hooks
+`;
+const meta = { source: "test", fetched: "2026-11-10", claudeCode: "2.1.319" };
+describe("the extractor and the diff", () => {
+    it("[N37] [SD4] events, their versions, the no-matcher events, handler fields; a # comment in a code block is not a heading", () => {
+        const c = extractHookContract(PAGE, meta);
+        expect(c.events).toEqual(["PreToolUse", "Ping", "Stop"]);
+        expect(c.eventRequires).toEqual({ Ping: "2.1.400" });
+        expect(c.noMatcherEvents).toEqual(["Ping", "Stop"]);
+        expect(c.handlerTypes).toEqual(["command", "http"]);
+        expect(c.fields.command).toEqual({ command: { required: true }, onFailure: { required: false, requires: "2.1.295" } });
+        expect(c.matcherRules).toHaveLength(2);
+    });
+    it("[N37] [SD5] the contract at an older version drops what needs a newer one", () => {
+        const c = extractHookContract(PAGE, meta);
+        expect(contractAt(c, "2.1.300").events).toEqual(["PreToolUse", "Stop"]);
+        expect(Object.keys(contractAt(c, "2.1.290").fields.command)).toEqual(["command"]);
+    });
+    it("[N37] [SD6] a diff names what moved, and the same page has none", () => {
+        const before = extractHookContract(PAGE, meta);
+        expect(hasDrift(diffContracts(before, before))).toBe(false);
+        expect(renderDiff(diffContracts(before, before))).toEqual(["no drift"]);
+        const page = PAGE.replace("### Stop", "### Stop\n\n### Wake").replace("v2.1.295", "v2.1.300").replace("| `timeout` | no | Seconds |\n", "");
+        const d = diffContracts(before, extractHookContract(page, meta));
+        expect(d.eventsAdded).toEqual(["Wake"]);
+        expect(d.fieldsRemoved).toEqual(["common.timeout"]);
+        expect(d.changed).toEqual(["command.onFailure: requires 2.1.295 → 2.1.300"]);
+        expect(hasDrift(d)).toBe(true);
+    });
+});
+//# sourceMappingURL=contract-drift.test.js.map

package/dist/__tests__/e2e/contract-drift.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-drift.test.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/contract-drift.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/e2e/fail-closed.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated gates fail closed (N27).
+ *
+ * Claude Code blocks only on exit 2. Measured on 0.9.1 (2026-11-09): with
+ * CLAUDE_PROJECT_DIR unset before-agent.sh exited 1, with jq missing 127, and
+ * a gate script nobody had written exited 0. In all three the agent launched
+ * with its gate and its approval step skipped. Each case below runs the
+ * generated scripts the way Claude Code does, with stdin and an environment.
+ */
+export {};
+//# sourceMappingURL=fail-closed.test.d.ts.map

package/dist/__tests__/e2e/fail-closed.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail-closed.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/fail-closed.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/e2e/fail-closed.test.js

@@ -0,0 +1,111 @@
+/**
+ * Generated gates fail closed (N27).
+ *
+ * Claude Code blocks only on exit 2. Measured on 0.9.1 (2026-11-09): with
+ * CLAUDE_PROJECT_DIR unset before-agent.sh exited 1, with jq missing 127, and
+ * a gate script nobody had written exited 0. In all three the agent launched
+ * with its gate and its approval step skipped. Each case below runs the
+ * generated scripts the way Claude Code does, with stdin and an environment.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "../../parser/index.js";
+import { claudeCodeBinding } from "../../bindings/claude-code.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const ast = parse(fs.readFileSync(resolve(here, "fixtures/compile.at"), "utf-8"));
+const LAUNCH_DRAFTER = JSON.stringify({ tool_name: "Agent", tool_input: { subagent_type: "drafter" } });
+let root;
+/**
+ * Every case runs under /bin/bash (3.2 on macOS, whose EXIT trap sees status 0
+ * after an unset variable) and under the bash on PATH, which Claude Code's
+ * `bash "..."` command uses.
+ */
+const pathBash = spawnSync("/bin/bash", ["-c", "command -v bash"], { encoding: "utf8" }).stdout.trim();
+const SHELLS = [...new Set(["/bin/bash", pathBash].filter(Boolean))];
+let BASH = "/bin/bash";
+const scripts = () => join(root, ".claude/skills/compile/scripts");
+function run(script, opts = {}) {
+    const env = {};
+    for (const [k, v] of Object.entries({ ...process.env, CLAUDE_PROJECT_DIR: root, ...opts.env })) {
+        if (v !== undefined)
+            env[k] = v;
+    }
+    const r = spawnSync(BASH, [join(scripts(), script)], { input: opts.stdin ?? LAUNCH_DRAFTER, env, cwd: root, encoding: "utf8" });
+    return { code: r.status, out: r.stdout, err: r.stderr };
+}
+/** A PATH holding only bash and the basics, so a named command is missing. */
+function pathWithout(...missing) {
+    const bin = join(root, "bin-" + missing.join("-"));
+    fs.mkdirSync(bin, { recursive: true });
+    for (const c of ["bash", "env", "cat", "jq", "python3", "date", "echo"]) {
+        if (missing.includes(c))
+            continue;
+        const which = spawnSync("/bin/bash", ["-c", `command -v ${c}`], { encoding: "utf8" }).stdout.trim();
+        if (which.startsWith("/") && !fs.existsSync(join(bin, c)))
+            fs.symlinkSync(which, join(bin, c));
+    }
+    return bin;
+}
+const hasJq = spawnSync("/bin/bash", ["-c", "command -v jq"]).status === 0;
+beforeAll(() => {
+    root = fs.mkdtempSync(join(os.tmpdir(), "at-fail-closed-"));
+    for (const f of claudeCodeBinding.scaffold(ast)) {
+        const p = join(root, f.path);
+        fs.mkdirSync(dirname(p), { recursive: true });
+        fs.writeFileSync(p, f.content);
+        if (f.executable)
+            fs.chmodSync(p, 0o755);
+    }
+});
+afterAll(() => fs.rmSync(root, { recursive: true, force: true }));
+for (const shell of SHELLS)
+    describe(`a generated gate blocks when it cannot run (${shell})`, () => {
+        beforeAll(() => { BASH = shell; });
+        it("[N27] before-agent.sh blocks (exit 2) when CLAUDE_PROJECT_DIR is unset", () => {
+            const r = run("before-agent.sh", { env: { CLAUDE_PROJECT_DIR: undefined } });
+            expect(r.code).toBe(2);
+            expect(r.err).toContain("blocked");
+        });
+        it("[N27] before-agent.sh blocks (exit 2) when jq is missing", () => {
+            const r = run("before-agent.sh", { env: { PATH: pathWithout("jq") } });
+            expect(r.code).toBe(2);
+        });
+        it("[N27] a gate script nobody has written fails, so the launch is blocked", () => {
+            const stub = fs.readFileSync(join(scripts(), "brief-check.sh"), "utf8");
+            expect(stub).toContain("AGENTOPOLOGY_STUB");
+            expect(run("brief-check.sh").code).toBe(2);
+            expect(run("before-agent.sh").code).toBe(2);
+        });
+        it("[N27] a SubagentStop gate wrapper blocks (exit 2) when its check's interpreter is missing", () => {
+            const r = run("gate-copy-check.sh", { env: { PATH: pathWithout("python3") }, stdin: "{}" });
+            expect(r.code).toBe(2);
+        });
+        it.skipIf(!hasJq)("[N27] a written gate that passes still lets the launch through to its approval step", () => {
+            const stub = join(scripts(), "brief-check.sh");
+            const saved = fs.readFileSync(stub, "utf8");
+            fs.writeFileSync(stub, "#!/usr/bin/env bash\nexit 0\n");
+            try {
+                const r = run("before-agent.sh");
+                expect(r.code).toBe(0);
+                expect(JSON.parse(r.out).hookSpecificOutput.permissionDecision).toBe("ask");
+            }
+            finally {
+                fs.writeFileSync(stub, saved);
+            }
+        });
+        it.skipIf(!hasJq)("[N27] an agent with no gate launches untouched", () => {
+            const r = run("before-agent.sh", { stdin: JSON.stringify({ tool_input: { subagent_type: "critic" } }) });
+            expect(r.code).toBe(0);
+            expect(r.out).toBe("");
+        });
+        it("[N27] the guard's settings entry asks Claude Code to block when the hook itself fails", () => {
+            const settings = JSON.parse(claudeCodeBinding.scaffold(ast).find((f) => f.path === ".claude/settings.json").content);
+            const guard = settings.hooks.PreToolUse.find((e) => e.matcher === "Agent|Task");
+            expect(guard.hooks[0].onFailure).toBe("block");
+        });
+    });
+//# sourceMappingURL=fail-closed.test.js.map

package/dist/__tests__/e2e/fail-closed.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail-closed.test.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/fail-closed.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/e2e/guard-check.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agentopology guard <file> --check` (GC): which gates, approval steps and
+ * permission rules a project actually enforces today. It reads; it never
+ * writes. Built on compile.at: brief-check (a gate before an agent, run by
+ * before-agent.sh), copy-check (a gate after an agent, a SubagentStop hook),
+ * approve (a human step before drafter), and settings ask and deny rules.
+ */
+export {};
+//# sourceMappingURL=guard-check.test.d.ts.map

package/dist/__tests__/e2e/guard-check.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-check.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/guard-check.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}