agentopology 0.9.1 → 0.10.0

package/dist/bindings/claude-code.js

@@ -7,12 +7,13 @@
  * @module
  */
 import { deduplicateFiles } from "./types.js";
-import { shellStub, STUB_MARKER } from "./lib/stub.js";
+import { shellStub, STUB_MARKER, FAIL_CLOSED, FAIL_CLOSED_DONE } from "./lib/stub.js";
 import { PROMPT_FENCE_CLOSE, PROMPT_FENCE_OPEN } from "./lib/prompt-fence.js";
 import { isWorkflowSeamAgent, seamFiles } from "./lib/seam.js";
 import { phaseOf as sharedPhaseOf } from "../resolve/phase.js";
 import { gateAnchors } from "../parser/ast.js";
-import { isProjectPath, proseInRun, runParts, scriptNameFromRun } from "../parser/run.js";
+import { gateLedger, guardedActions } from "../parser/ledger.js";
+import { isProjectPath, isShellCommand, proseInRun, runParts, scriptNameFromRun } from "../parser/run.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -20,7 +21,7 @@ import { isProjectPath, proseInRun, runParts, scriptNameFromRun } from "../parse
  * Convert .at MCP tool notation (mcp.server.method) to Claude Code format (mcp__server__method).
  * Non-MCP tool names pass through unchanged.
  */
-function convertMcpToolName(tool) {
+export function convertMcpToolName(tool) {
     if (!tool.startsWith("mcp."))
         return tool;
     // mcp.server → mcp__server (every tool on it); mcp.server.* → mcp__server__*;
@@ -50,7 +51,7 @@ const UNIVERSAL_EVENTS = {
     ToolUse: "PostToolUse",
     Error: "PostToolUseFailure",
 };
-function claudeEvent(on) {
+export function claudeEvent(on) {
     return UNIVERSAL_EVENTS[on] ?? on;
 }
 /** Whether a hook runs a shell command (and so has a script). */
@@ -60,18 +61,20 @@ function isCommandHook(hook) {
 /** A settings.json hook handler, in the shape Claude Code reads for its type. */
 function hookHandler(hook, command) {
     const timeout = hook.timeout ? { timeout: hook.timeout } : {};
+    // `if` filters on the tool's arguments (permission-rule syntax); a common handler field.
+    const filter = hook.if ? { if: hook.if } : {};
     switch (hook.type ?? "command") {
         // A prompt or agent hook asks a model (or a subagent) to judge the event;
         // its run: is the prompt.
         case "prompt":
         case "agent":
-            return { type: hook.type, prompt: hook.run, ...(hook.model ? { model: hook.model } : {}), ...timeout };
+            return { type: hook.type, prompt: hook.run, ...(hook.model ? { model: hook.model } : {}), ...timeout, ...filter };
         case "http":
-            return { type: "http", url: hook.url, ...timeout };
+            return { type: "http", url: hook.url, ...timeout, ...filter };
         case "mcp_tool":
-            return { type: "mcp_tool", server: hook.server, tool: hook.tool, ...timeout };
+            return { type: "mcp_tool", server: hook.server, tool: hook.tool, ...timeout, ...filter };
         default:
-            return { type: "command", command: command(), ...(hook.async ? { async: true } : {}), ...timeout };
+            return { type: "command", command: command(), ...(hook.async ? { async: true } : {}), ...timeout, ...filter };
     }
 }
 /**
@@ -158,7 +161,7 @@ function getDelegationMode(ast) {
     const orch = ast.nodes.find((n) => n.type === "orchestrator");
     return orch?.delegation === "inline" ? "inline" : "subagent";
 }
-function gateWiring(ast, gate) {
+export function gateWiring(ast, gate) {
     if (getDelegationMode(ast) === "inline")
         return { kind: "none" };
     const afters = gateAnchors(gate, "after");
@@ -169,7 +172,7 @@ function gateWiring(ast, gate) {
     return agents.length > 0 ? { kind: "before-agent", agents } : { kind: "none" };
 }
 /** Agents a human approval step stands before: its direct flow successors. */
-function approvalTargets(ast, human) {
+export function approvalTargets(ast, human) {
     if (getDelegationMode(ast) === "inline")
         return [];
     const out = ast.edges.filter((e) => e.from === human.id && !e.isError).map((e) => e.to);
@@ -177,7 +180,7 @@ function approvalTargets(ast, human) {
 }
 /** The settings.json command for the topology's before-agent hook. */
 function beforeAgentCommand(ast) {
-    return `bash "$CLAUDE_PROJECT_DIR/.claude/skills/${ast.topology.name}/scripts/before-agent.sh"`;
+    return `bash ${skillScriptPath(ast.topology.name, "before-agent.sh")}`;
 }
 /**
  * One PreToolUse hook on the Agent tool for the whole topology: before Claude
@@ -223,6 +226,7 @@ function generateBeforeAgentScript(ast) {
         "# PreToolUse hook on the Agent tool. Exit 2 blocks the launch and shows the",
         "# reason to Claude; an \"ask\" decision makes Claude Code ask the user first.",
         "set -euo pipefail",
+        ...FAIL_CLOSED,
         'cd "$CLAUDE_PROJECT_DIR"',
         `DIR=".claude/skills/${name}/scripts"`,
         'AGENT=$(jq -r \'.tool_input.subagent_type // ""\')',
@@ -236,7 +240,7 @@ function generateBeforeAgentScript(ast) {
     for (const [agent, body] of steps) {
         lines.push(`  ${agent})`, ...body, "    ;;");
     }
-    lines.push("esac", "exit 0", "");
+    lines.push("esac", FAIL_CLOSED_DONE, "exit 0", "");
     return {
         path: `.claude/skills/${name}/scripts/before-agent.sh`,
         content: lines.join("\n"),
@@ -244,6 +248,137 @@ function generateBeforeAgentScript(ast) {
         executable: true,
     };
 }
+/** The settings.json command for the topology's before-action hook. */
+function beforeActionCommand(ast) {
+    return `bash ${skillScriptPath(ast.topology.name, "before-action.sh")}`;
+}
+/**
+ * A gate before a script step that the generated guard can check: it has a
+ * ledger to read, or a `run:` script to run. A gate with neither has nothing
+ * to check (V110) and gets no line.
+ */
+export function checkableActionGate(ast, gate) {
+    if (gate.behavior === "advisory")
+        return false;
+    if (guardedActions(ast, gate).length === 0)
+        return false;
+    return !!gateLedger(ast, gate) || !!scriptNameFromRun(gate.run);
+}
+/** Every action a gate guards, with its gates, in declaration order. */
+function actionGuards(ast) {
+    const gates = ast.nodes.filter((n) => n.type === "gate").filter((g) => checkableActionGate(ast, g));
+    const out = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "action")
+            continue;
+        const mine = gates.filter((g) => guardedActions(ast, g).some((a) => a.id === node.id));
+        if (mine.length > 0)
+            out.push({ action: node, gates: mine });
+    }
+    return out;
+}
+/**
+ * One PreToolUse hook on Bash for the whole topology: before Claude Code runs
+ * a script step's command, the gates that stand before that step are checked.
+ * A gate with a ledger lets the command through only when the LAST ledger line
+ * for its `after:` step (and the command's unit) is ok; a gate with `run:` also
+ * runs its wrapper. Null when no gate guards a script step.
+ *
+ * Why a hook and not a note in the playbook: V25 used to say "invoke the gate
+ * from your playbook", and a session that skipped it ran the step anyway. A
+ * hook only covers Claude Code sessions; a script run from a terminal checks
+ * itself with `agentopology step check`.
+ */
+function generateBeforeActionScript(ast) {
+    const guards = actionGuards(ast);
+    if (guards.length === 0)
+        return null;
+    const name = ast.topology.name;
+    const lines = [
+        "#!/usr/bin/env bash",
+        `# Before Claude Code runs a script step of topology "${name}".`,
+        "# Auto-generated by agentopology scaffold. Wired in .claude/settings.json as a",
+        "# PreToolUse hook on Bash. Exit 2 blocks the command and shows stderr to Claude.",
+        "# A ledger is JSON Lines: {\"step\": \"<id>\", \"unit\": \"<unit>\", \"ok\": true, \"at\": \"<ISO time>\"}.",
+        "# Covers Claude Code sessions only; a step run outside Claude calls",
+        "# `agentopology step check` itself.",
+        "set -euo pipefail",
+        ...FAIL_CLOSED,
+        'command -v jq >/dev/null 2>&1 || { echo "agentopology: jq is required to check this step, so it is blocked" >&2; exit 2; }',
+        'if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then echo "agentopology: CLAUDE_PROJECT_DIR is not set, so this step cannot be checked and is blocked" >&2; exit 2; fi',
+        'cd "$CLAUDE_PROJECT_DIR"',
+        `DIR=".claude/skills/${name}/scripts"`,
+        'CMD=$(jq -er \'.tool_input.command // ""\') || { echo "agentopology: the hook input is not valid JSON, so the command is blocked" >&2; exit 2; }',
+        "",
+        "deny() { echo \"agentopology: gate $1 refuses this command ($CMD): $2\" >&2; exit 2; }",
+        "",
+        "# check_ledger GATE STEP LEDGER-PATH UNIT: the last line for STEP (and UNIT) must be ok.",
+        "check_ledger() {",
+        "  local gate=$1 step=$2 tmpl=$3 unit=$4 path ok",
+        '  if [[ "$tmpl" == *"{unit}"* ]]; then',
+        '    [ -n "$unit" ] || deny "$gate" "step \\"$step\\" must have finished ok, but no unit could be read from the command to find its ledger $tmpl"',
+        '    path="${tmpl//\\{unit\\}/$unit}"',
+        "  else",
+        '    path="$tmpl"',
+        "  fi",
+        '  [ -f "$path" ] || deny "$gate" "step \\"$step\\" has no ok record for unit \\"$unit\\": the ledger $path does not exist"',
+        "  ok=$(jq -rs --arg step \"$step\" --arg unit \"$unit\" '[.[] | select(.step == $step and ($unit == \"\" or .unit == $unit))] | last | (.ok == true)' \"$path\") \\",
+        '    || deny "$gate" "step \\"$step\\" for unit \\"$unit\\": the ledger $path could not be read"',
+        '  [ "$ok" = true ] || deny "$gate" "step \\"$step\\" has no ok record for unit \\"$unit\\" in ledger $path (its last record must have ok: true)"',
+        "}",
+        "",
+        "# A Bash command is a list: `cd repo && ./tool publish ep1`, `a; b`, `a || b`, `a | b`, a",
+        "# backgrounded `a &`, or several lines. Each segment is checked on its own, because the step is",
+        "# the segment's command, not the whole line (matching only the start of the whole line let",
+        "# `cd repo && ./tool publish ep1` run the step with its gate unmet). Quoting is NOT parsed: a",
+        "# separator inside a quoted string also splits, which can only produce an extra segment that",
+        "# is checked too, so it over-blocks and never under-blocks (fail-safe). A command that runs the",
+        "# step indirectly (bash -c, eval, a script that calls it) is not seen.",
+        "SEGS=$CMD",
+        "for sep in '&' '|' ';'; do SEGS=${SEGS//\"$sep\"/$'\\n'}; done",
+        "# Leading VAR=value assignments and wrappers are not part of the command.",
+        "re_assign='^[[:space:]]*[A-Za-z_][A-Za-z0-9_]*=(\"[^\"]*\"|'\"'\"'[^'\"'\"']*'\"'\"'|[^[:space:]]*)([[:space:]]+|$)'",
+        "re_wrap='^(\\(+[[:space:]]*|\\{[[:space:]]+|(then|do|exec|time|nohup|env)([[:space:]]+|$))'",
+        "UNIT=''",
+        "",
+        "# Segments come in on fd 3 and children get stdin from /dev/null: a check that reads stdin must not swallow the later segments.",
+        "while IFS= read -r -u 3 C || [ -n \"$C\" ]; do",
+        "  prev=''",
+        '  while [ "$C" != "$prev" ]; do',
+        '    prev=$C',
+        '    C="${C#"${C%%[![:space:]]*}"}"',
+        '    if [[ "$C" =~ $re_assign ]]; then C="${C:${#BASH_REMATCH[0]}}"; elif [[ "$C" =~ $re_wrap ]]; then C="${C:${#BASH_REMATCH[0]}}"; fi',
+        "  done",
+        '  [ -n "$C" ] || continue',
+    ];
+    for (const { action, gates } of guards) {
+        const tests = (action.commands ?? []).map((c) => `[[ "$C" == ${shellQuote(c)} || "$C" == ${shellQuote(c + " ")}* ]]`);
+        lines.push(`  # step ${action.id}`, `  if ${tests.join(" || ")}; then`, "    UNIT=''");
+        if (action.unitFrom) {
+            lines.push(`  UNIT=$(jq -nr --arg c "$C" --arg re ${shellQuote(action.unitFrom)} '$c | match($re) | .captures[0].string // empty') || deny ${shellQuote(gates[0].id)} "unit-from does not compile"`, '  if ! [[ "$UNIT" =~ ^[A-Za-z0-9_.@+-]*$ ]] || [[ "$UNIT" == *..* ]]; then', `    deny ${shellQuote(gates[0].id)} "the unit \\"$UNIT\\" read from the command is not a safe file name"`, "  fi");
+        }
+        for (const gate of gates) {
+            lines.push(`  # gate ${gate.id} (after: ${gateAnchors(gate, "after").join(", ") || "-"})`);
+            const ledger = gateLedger(ast, gate);
+            if (ledger) {
+                for (const step of gateAnchors(gate, "after")) {
+                    lines.push(`  check_ledger ${shellQuote(gate.id)} ${shellQuote(step)} ${shellQuote(ledger.path.replace(/^\.\//, ""))} "$UNIT"`);
+                }
+            }
+            if (scriptNameFromRun(gate.run)) {
+                lines.push(`  bash "$DIR/gate-${gate.id}.sh" </dev/null >&2 || deny ${shellQuote(gate.id)} "its check script failed"`);
+            }
+        }
+        lines.push("  fi", "");
+    }
+    lines.push('done 3<<< "$SEGS"', "", FAIL_CLOSED_DONE, "exit 0", "");
+    return {
+        path: `.claude/skills/${name}/scripts/before-action.sh`,
+        content: lines.join("\n"),
+        category: "script",
+        executable: true,
+    };
+}
 /** Single-quote a string for bash. */
 function shellQuote(text) {
     return `'${text.replace(/'/g, `'\\''`)}'`;
@@ -611,7 +746,7 @@ function generateAgents(ast) {
                     const scriptName = scriptNameFromRun(hook.run);
                     if (isCommandHook(hook) && !scriptName)
                         continue; // V96: prose in run names no script
-                    const handler = hookHandler(hook, () => `bash .claude/skills/${topologyName}/scripts/${agent.id}-${scriptName}`);
+                    const handler = hookHandler(hook, () => isShellCommand(hook.run) ? hook.run.trim() : `bash ${skillScriptPath(topologyName, `${agent.id}-${scriptName}`)}`);
                     // JSON strings are valid YAML double-quoted scalars, so a regex
                     // matcher or a prompt with quotes or colons can never break the file.
                     hookLines.push(hook.matcher ? `    - matcher: ${JSON.stringify(hook.matcher)}` : `    -`);
@@ -1900,7 +2035,7 @@ function generateGateScripts(ast) {
         const project = isProjectPath(script);
         files.push({
             path: project ? script.replace(/^\.\//, "") : `.claude/skills/${name}/scripts/${scriptName}`,
-            content: shellStub(`Gate: ${gate.id} — ${gate.run}`),
+            content: shellStub(`Gate: ${gate.id} — ${gate.run}`, { fail: true }),
             category: "script",
             ...(project ? { createOnly: true } : {}),
         });
@@ -1930,7 +2065,11 @@ function generateGateWrapperScripts(ast) {
         const wiredAsHook = wiring.kind === "subagent-stop";
         let enforcementNote;
         let enforcementNote2;
-        if (wiring.kind === "before-agent") {
+        if (checkableActionGate(ast, gate)) {
+            enforcementNote = `# Enforcement: PreToolUse hook on Bash (before-action.sh) before Claude Code runs a command of "${gateAnchors(gate, "before").join('", "')}".`;
+            enforcementNote2 = `#              Exit 2 blocks the command and surfaces stderr to Claude.`;
+        }
+        else if (wiring.kind === "before-agent") {
             enforcementNote = `# Enforcement: PreToolUse hook (before-agent.sh) before Claude Code launches "${wiring.agents.join('", "')}".`;
             enforcementNote2 = `#              Exit 2 blocks the launch and surfaces stderr to Claude.`;
         }
@@ -1953,6 +2092,7 @@ function generateGateWrapperScripts(ast) {
             enforcementNote,
             enforcementNote2,
             "set -euo pipefail",
+            ...FAIL_CLOSED,
             "",
             "# Gate runs after: " + (gateAnchors(gate, "after").join(", ") || "any"),
             "# Gate runs before: " + (gateAnchors(gate, "before").join(", ") || "any"),
@@ -1997,6 +2137,7 @@ function generateGateWrapperScripts(ast) {
         contentLines.push(`  echo "Gate '${gate.id}' FAILED (exit code $GATE_RESULT)"`);
         contentLines.push(`  ${onFailExit}`);
         contentLines.push("fi");
+        contentLines.push(FAIL_CLOSED_DONE);
         contentLines.push("");
         const content = contentLines.join("\n");
         files.push({
@@ -2176,6 +2317,8 @@ function generateHookScripts(ast) {
         // bash stub. generateModPlugin imports it instead.
         if (!isCommandHook(hook))
             continue; // a mod's module, or no script at all
+        if (isShellCommand(hook.run))
+            continue; // run as written: no script to stub
         const runPath = hook.run;
         // If the run path starts with '.' or '/' it is already project-relative —
         // generate the stub at exactly that path (observability pattern).
@@ -2219,6 +2362,8 @@ function generateAgentHookScripts(ast) {
         for (const hook of agent.hooks) {
             if (!hook.run || !isCommandHook(hook))
                 continue;
+            if (isShellCommand(hook.run))
+                continue; // run as written: no script to stub
             const scriptName = scriptNameFromRun(hook.run);
             if (!scriptName)
                 continue; // V96: prose in run names no script
@@ -2239,6 +2384,15 @@ function generateAgentHookScripts(ast) {
     }
     return files;
 }
+/**
+ * A script this topology's skill scaffolds, as a hook command names it. A
+ * hook runs in the session's current directory, which moves when Claude
+ * changes directory, so the path is anchored to the project: a relative one
+ * is not found there, exits 127, and 127 does not block.
+ */
+export function skillScriptPath(topologyName, file) {
+    return `"$CLAUDE_PROJECT_DIR/.claude/skills/${topologyName}/scripts/${file}"`;
+}
 /**
  * The shell command for a command hook's or gate's `run:`.
  *
@@ -2251,10 +2405,12 @@ function generateAgentHookScripts(ast) {
  * Any other `run:` is a script this topology's skill scaffolds, by basename.
  */
 export function hookCommand(run, topologyName) {
+    if (isShellCommand(run))
+        return run.trim();
     const { interpreter: named, script: first, args: rest } = runParts(run);
     if (!isProjectPath(first)) {
         const base = first.replace(/^.*\//, "");
-        return [named ?? "bash", `.claude/skills/${topologyName}/scripts/${base}`, ...rest].join(" ");
+        return [named ?? "bash", skillScriptPath(topologyName, base), ...rest].join(" ");
     }
     const interpreter = named ?? (first.endsWith(".py") ? "python3" : "bash");
     const where = first.startsWith("/")
@@ -2366,6 +2522,8 @@ function generateSettings(ast) {
         const wiring = gateWiring(ast, gate);
         if (wiring.kind === "before-agent")
             continue;
+        if (checkableActionGate(ast, gate))
+            continue; // before-action.sh runs it
         if (wiring.kind !== "subagent-stop") {
             const bad = anchors.filter((a) => !isRegisteredSubagentType(ast, a));
             const targetDesc = anchors.length
@@ -2380,7 +2538,7 @@ function generateSettings(ast) {
         if (!hooksByEvent[eventName])
             hooksByEvent[eventName] = [];
         const scriptName = `gate-${gate.id}.sh`;
-        const command = `bash .claude/skills/${topologyName}/scripts/${scriptName}`;
+        const command = `bash ${skillScriptPath(topologyName, scriptName)}`;
         // ONE ENTRY PER ANCHOR. A SubagentStop matcher is a STRING — an array would
         // land in settings.json, type-check clean through Record<string, unknown>,
         // and the hook would simply never fire. Silent, and the gate would look
@@ -2411,7 +2569,18 @@ function generateSettings(ast) {
         hooksByEvent.PreToolUse.push({
             // Agent is the subagent tool; Task is its earlier name.
             matcher: "Agent|Task",
-            hooks: [{ type: "command", command: beforeAgentCommand(ast) }],
+            // onFailure "block" (Claude Code 2.1.295+): a script that cannot start,
+            // times out or exits other than 0/2 blocks the launch instead of
+            // letting it through. The script's own EXIT trap covers the rest.
+            hooks: [{ type: "command", command: beforeAgentCommand(ast), onFailure: "block" }],
+        });
+    }
+    if (generateBeforeActionScript(ast)) {
+        if (!hooksByEvent.PreToolUse)
+            hooksByEvent.PreToolUse = [];
+        hooksByEvent.PreToolUse.push({
+            matcher: "Bash",
+            hooks: [{ type: "command", command: beforeActionCommand(ast), onFailure: "block" }],
         });
     }
     const observeHook = buildHybridObserveHook(ast, topologyName);
@@ -3175,7 +3344,7 @@ function buildHybridObserveHook(ast, topologyName) {
             hooks: [
                 {
                     type: "command",
-                    command: `bash ${scriptPath}`,
+                    command: `bash ${skillScriptPath(topologyName, "observe-blackboard.sh")}`,
                 },
             ],
         },
@@ -3376,6 +3545,9 @@ export const claudeCodeBinding = {
         const beforeAgent = generateBeforeAgentScript(ast);
         if (beforeAgent)
             files.push(beforeAgent);
+        const beforeAction = generateBeforeActionScript(ast);
+        if (beforeAction)
+            files.push(beforeAction);
         // Hook scripts (global)
         files.push(...generateHookScripts(ast));
         // Hook scripts (per-agent)