agentopology 0.2.0 → 0.2.3

package/dist/bindings/__tests__/stub-generation.test.js

@@ -0,0 +1,117 @@
+/**
+ * Tests for Change 4 + 5: Agent-scoped env var injection + stub script generation.
+ *
+ * Change 4: When scaffold generates a hook stub, it must include logic to
+ * extract ACTIVE_AGENT from the Claude Code stdin JSON payload (agent_type field).
+ *
+ * Change 5: When a hook's run: path does not exist on disk, scaffold emits a stub
+ * at that path with:
+ *   - #!/usr/bin/env bash shebang
+ *   - jq-based AGENT_TYPE extraction from stdin
+ *   - A metrics.jsonl append
+ *   - chmod +x (executable bit)
+ *   - Auto-generated marker comment
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { parse } from "../../parser/index.js";
+import { bindings } from "../index.js";
+let tmpDir;
+beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "stub-gen-test-"));
+});
+afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// Topology with a hook pointing at a non-existent script
+// ---------------------------------------------------------------------------
+const STUB_TOPOLOGY = `
+topology stub-test : [supervisor] {
+  meta { version: "1.0.0" description: "Stub generation test" }
+  orchestrator { model: opus handles: [start] }
+  action start { kind: inline }
+  agent tracker { model: sonnet phase: 1 prompt { You are tracker. } }
+  flow { start -> tracker }
+  hooks {
+    hook log-finish {
+      on: SubagentStop
+      matcher: "tracker"
+      run: ".claude/scripts/log-finish.sh"
+      type: command
+      timeout: 5000
+    }
+  }
+}
+`;
+// ---------------------------------------------------------------------------
+// Change 5 — stub generation for non-existent hook scripts
+// ---------------------------------------------------------------------------
+describe("Change 5 — hook stub generation", () => {
+    const ast = parse(STUB_TOPOLOGY);
+    const binding = bindings["claude-code"];
+    it("generates a stub script file for hook with non-existent run path", () => {
+        const files = binding.scaffold(ast);
+        // The stub should be at the path declared in hook.run
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub).toBeDefined();
+    });
+    it("stub file has category 'script'", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.category).toBe("script");
+    });
+    it("stub contains shebang line", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("#!/usr/bin/env bash");
+    });
+    it("stub contains auto-generated marker", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("Auto-generated by agentopology scaffold");
+    });
+    it("stub extracts AGENT_TYPE from stdin JSON (Change 4 — env var injection)", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        // Stub must extract agent_type from the Claude Code stdin payload
+        expect(stub.content).toContain("agent_type");
+        expect(stub.content).toContain("AGENT_TYPE");
+    });
+    it("stub appends to metrics.jsonl", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("metrics.jsonl");
+    });
+    it("stub includes hook name in header comment", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("log-finish");
+    });
+    it("stub includes event name in header comment", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("SubagentStop");
+    });
+    it("stub is marked executable (via a generated chmod hint or content)", () => {
+        // Since scaffold returns file content (not real fs writes), we check the
+        // category is 'script' — the executeActions function sets chmod on creation.
+        // The actual chmod happens in executeActions. We verify it in an integration
+        // test by writing the file and checking the mode.
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub).toBeDefined();
+        expect(stub.category).toBe("script");
+        expect(stub.executable).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// Change 5 — NO stub if the script already exists on disk (not scaffold's job)
+// ---------------------------------------------------------------------------
+// Note: scaffold() generates file lists; the incremental engine decides
+// what to write. The stub is always in the generated list — the incremental
+// engine's "script" category + shouldOverwriteScript() prevents overwriting
+// user-edited stubs. This is correct behaviour, already tested in scaffold.test.ts.
+//# sourceMappingURL=stub-generation.test.js.map

package/dist/bindings/__tests__/stub-generation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-generation.test.js","sourceRoot":"","sources":["../../../src/bindings/__tests__/stub-generation.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,IAAI,MAAc,CAAC;AAEnB,UAAU,CAAC,GAAG,EAAE;IACd,MAAM,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC;AACpE,CAAC,CAAC,CAAC;AAEH,SAAS,CAAC,GAAG,EAAE;IACb,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACtD,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAE9E,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;CAiBrB,CAAC;AAEF,8EAA8E;AAC9E,2DAA2D;AAC3D,8EAA8E;AAE9E,QAAQ,CAAC,iCAAiC,EAAE,GAAG,EAAE;IAC/C,MAAM,GAAG,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAExC,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,sDAAsD;QACtD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,yCAAyC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QACjF,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,kEAAkE;QAClE,MAAM,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QAC9C,MAAM,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,yEAAyE;QACzE,6EAA6E;QAC7E,6EAA6E;QAC7E,kDAAkD;QAClD,MAAM,KAAK,GAAoB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,+BAA+B,CAAC,CAAC;QAC3E,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3B,MAAM,CAAC,IAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,CAAC,IAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,wEAAwE;AACxE,4EAA4E;AAC5E,4EAA4E;AAC5E,oFAAoF"}

package/dist/bindings/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AA+yE/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aA0F/B,CAAC"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAk3E/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aA0F/B,CAAC"}

package/dist/bindings/claude-code.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { deduplicateFiles } from "./types.js";
+import { shellStub } from "./lib/stub.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -48,6 +49,8 @@ function toTitle(id) {
  *     - item1
  *     - item2
  */
+/** Characters that require quoting in YAML scalar values. */
+const YAML_SPECIAL = /[:#\[\]{}&*!|>'"%@`]/;
 function frontmatter(fields) {
     const lines = ["---"];
     for (const [key, value] of Object.entries(fields)) {
@@ -65,23 +68,27 @@ function frontmatter(fields) {
             lines.push(`${key}: ${value}`);
         }
         else {
-            lines.push(`${key}: ${value}`);
+            // Auto-quote strings containing YAML-special characters
+            const str = String(value);
+            const needsQuotes = YAML_SPECIAL.test(str) || str.trim() !== str;
+            lines.push(`${key}: ${needsQuotes ? `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : str}`);
         }
     }
     lines.push("---");
     return lines.join("\n");
 }
-/** Generate a shell script stub with a header comment. */
-function shellStub(description) {
-    return [
-        "#!/usr/bin/env bash",
-        `# ${description}`,
-        "# Auto-generated by agentopology scaffold — edit as needed.",
-        'set -euo pipefail',
-        "",
-        'echo "TODO: implement this script"',
-        "",
-    ].join("\n");
+/**
+ * Check whether `name` refers to a node registered as a Claude Code subagent_type.
+ *
+ * Both `agent` and `group` nodes scaffold a `.claude/agents/<name>/AGENT.md`
+ * file, which is what Claude Code registers as a subagent_type. Action, gate,
+ * human, and orchestrator nodes are NOT registered and therefore CANNOT be
+ * used as SubagentStop matchers.
+ */
+function isRegisteredSubagentType(ast, name) {
+    if (!name)
+        return false;
+    return ast.nodes.some((n) => (n.type === "agent" || n.type === "group") && n.id === name);
 }
 /** Generate an empty directory marker (a .gitkeep file). */
 function gitkeep(dirPath) {
@@ -93,10 +100,10 @@ function gitkeep(dirPath) {
  */
 function mapPermissionMode(perm) {
     // Claude Code native values — pass through
-    const nativeValues = ["plan", "auto", "confirm", "bypassPermissions"];
+    const nativeValues = ["plan", "default", "acceptEdits", "dontAsk", "bypassPermissions"];
     if (nativeValues.includes(perm)) {
-        // "auto" is the default, omit it
-        if (perm === "auto")
+        // "default" is the default, omit it
+        if (perm === "default")
             return undefined;
         return perm;
     }
@@ -106,8 +113,10 @@ function mapPermissionMode(perm) {
             return "plan";
         case "autonomous":
             return undefined; // default, omit
+        case "auto":
+            return undefined; // default, omit
         case "interactive":
-            return "default";
+            return "acceptEdits";
         case "unrestricted":
             return "bypassPermissions";
         default:
@@ -229,7 +238,7 @@ function generateAgents(ast) {
         if (agent.invocation !== "manual") {
             const desc = agent.description ?? ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role;
             if (desc) {
-                fm.description = `"${desc}"`;
+                fm.description = desc;
             }
         }
         if (agent.model)
@@ -237,9 +246,9 @@ function generateAgents(ast) {
         if (agent.maxTurns != null)
             fm.maxTurns = String(agent.maxTurns);
         if (agent.tools && agent.tools.length > 0)
-            fm.tools = agent.tools.map(convertMcpToolName);
+            fm.tools = agent.tools.map(convertMcpToolName).join(", ");
         if (agent.disallowedTools && agent.disallowedTools.length > 0)
-            fm.disallowedTools = agent.disallowedTools.map(convertMcpToolName);
+            fm.disallowedTools = agent.disallowedTools.map(convertMcpToolName).join(", ");
         if (agent.mcpServers && agent.mcpServers.length > 0)
             fm.mcpServers = agent.mcpServers;
         if (agent.background === true)
@@ -836,7 +845,7 @@ function generateGroupNodes(ast) {
         const skillFm = {};
         skillFm.name = group.id;
         if (group.description)
-            skillFm.description = `"${group.description}"`;
+            skillFm.description = group.description;
         skillFm["user-invocable"] = true;
         const skillSections = [];
         skillSections.push(frontmatter(skillFm));
@@ -853,7 +862,7 @@ function generateGroupNodes(ast) {
         const agentFm = {};
         agentFm.name = group.id;
         if (group.description)
-            agentFm.description = `"${group.description}"`;
+            agentFm.description = group.description;
         const agentSections = [];
         agentSections.push(frontmatter(agentFm));
         agentSections.push("");
@@ -879,9 +888,9 @@ function generateTopologySkill(ast) {
     const fm = {};
     fm.name = name;
     if (ast.topology.description) {
-        fm.description = `"${ast.topology.description}"`;
+        fm.description = ast.topology.description;
     }
-    fm.version = `"${ast.topology.version}"`;
+    fm.version = ast.topology.version;
     fm.topology = name;
     if (ast.topology.patterns.length > 0) {
         fm.patterns = ast.topology.patterns;
@@ -905,7 +914,7 @@ function generateTopologySkill(ast) {
         if (mainSkill.agent)
             fm.agent = mainSkill.agent;
         if (mainSkill.allowedTools && mainSkill.allowedTools.length > 0) {
-            fm["allowed-tools"] = mainSkill.allowedTools.map(convertMcpToolName);
+            fm["allowed-tools"] = mainSkill.allowedTools.map(convertMcpToolName).join(", ");
         }
     }
     const sections = [];
@@ -1222,7 +1231,7 @@ function generateSkills(ast) {
         const sfm = {};
         sfm.name = skill.id;
         if (skill.description)
-            sfm.description = `"${skill.description}"`;
+            sfm.description = skill.description;
         if (skill.disableModelInvocation != null) {
             sfm["disable-model-invocation"] = skill.disableModelInvocation;
         }
@@ -1234,7 +1243,7 @@ function generateSkills(ast) {
         if (skill.agent)
             sfm.agent = skill.agent;
         if (skill.allowedTools && skill.allowedTools.length > 0) {
-            sfm["allowed-tools"] = skill.allowedTools.map(convertMcpToolName);
+            sfm["allowed-tools"] = skill.allowedTools.map(convertMcpToolName).join(", ");
         }
         // Only emit frontmatter if there are fields beyond just the name
         if (Object.keys(sfm).length > 1) {
@@ -1434,7 +1443,7 @@ function generateGateScripts(ast) {
     }
     return files;
 }
-/** Generate gate wrapper scripts that filter Task calls to the correct agent. */
+/** Generate gate wrapper scripts that run validation when agents complete. */
 function generateGateWrapperScripts(ast) {
     const files = [];
     const name = ast.topology.name;
@@ -1447,12 +1456,22 @@ function generateGateWrapperScripts(ast) {
         if (gate.behavior === "advisory")
             continue;
         const gateScriptName = gate.run.replace(/^.*\//, "").replace(/\s.*$/, "");
-        const onFailExit = gate.onFail === "halt" ? 'exit 1' : 'echo "Gate failed — bounce-back requested (advisory)"';
+        const onFailExit = gate.onFail === "halt"
+            ? `echo "Gate '${gate.id}' validation failed. Fix issues before proceeding." >&2\n  exit 2`
+            : `echo "Gate '${gate.id}' failed — bounce back and fix the issues." >&2\n  exit 2`;
+        const wiredAsHook = isRegisteredSubagentType(ast, gate.after);
+        const enforcementNote = wiredAsHook
+            ? `# Enforcement: SubagentStop hook on agent "${gate.after}". Exit 2 blocks the subagent`
+            : `# Enforcement: NOT wired as a SubagentStop hook (after: ${gate.after || "<unset>"} is not an agent).`;
+        const enforcementNote2 = wiredAsHook
+            ? `#              from stopping (Claude Code prevents stop and surfaces stderr to Claude).`
+            : `#              Invoke this script from your orchestrator playbook or a /command at the right step.`;
         const contentLines = [
             "#!/usr/bin/env bash",
             `# Gate wrapper: ${gate.id}`,
-            `# Enforces gate "${gate.id}" on Task tool calls.`,
             `# Auto-generated by agentopology scaffold — edit as needed.`,
+            enforcementNote,
+            enforcementNote2,
             "set -euo pipefail",
             "",
             "# Gate runs after: " + (gate.after || "any"),
@@ -1508,27 +1527,66 @@ function generateGateWrapperScripts(ast) {
     }
     return files;
 }
-/** Generate hook script stubs for every hook's `run` field. */
+/**
+ * Generate an observability-aware hook stub (Changes 4+5).
+ *
+ * For SubagentStop/Stop hooks: extract agent_type from the Claude Code stdin
+ * JSON payload and export as AGENT_TYPE, then append a metrics.jsonl entry.
+ * For other events: emit a simple TODO stub.
+ */
+function observabilityStub(hookName, eventName, matcherHint) {
+    const isFinishEvent = eventName === "SubagentStop" || eventName === "Stop";
+    if (isFinishEvent) {
+        return [
+            "#!/usr/bin/env bash",
+            `# Auto-generated by agentopology scaffold on ${new Date().toISOString().slice(0, 10)}`,
+            `# Hook: ${hookName} · Event: ${eventName} · Matcher: ${matcherHint || "*"}`,
+            "# Replace this stub with your implementation.",
+            "# Stdin JSON payload from Claude Code is available on FD 0.",
+            "set -euo pipefail",
+            "",
+            "PAYLOAD=$(cat)",
+            'AGENT_TYPE=$(echo "$PAYLOAD" | jq -r \'.agent_type // "unknown"\')',
+            'SESSION_ID=$(echo "$PAYLOAD" | jq -r \'.session_id // ""\')',
+            "",
+            `echo "{\\\"ts\\\":\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\",\\\"event\\\":\\\"${eventName}\\\",\\\"agent\\\":\\\"$AGENT_TYPE\\\",\\\"session\\\":\\\"$SESSION_ID\\\",\\\"hook\\\":\\\"${hookName}\\\"}" >> .claude/memory/metrics.jsonl`,
+            "",
+        ].join("\n");
+    }
+    return [
+        "#!/usr/bin/env bash",
+        `# Auto-generated by agentopology scaffold on ${new Date().toISOString().slice(0, 10)}`,
+        `# Hook: ${hookName} · Event: ${eventName} · Matcher: ${matcherHint || "*"}`,
+        "# Replace this stub with your implementation.",
+        "# Stdin JSON payload from Claude Code is available on FD 0.",
+        "set -euo pipefail",
+        "",
+        'PAYLOAD=$(cat)',
+        'AGENT_TYPE=$(echo "$PAYLOAD" | jq -r \'.agent_type // "unknown"\')',
+        "",
+        `echo "TODO: implement ${hookName} hook (event: ${eventName}, agent: $AGENT_TYPE)"`,
+        "",
+    ].join("\n");
+}
+/** Generate hook script stubs for every hook's `run` field (Changes 1, 4, 5). */
 function generateHookScripts(ast) {
     const files = [];
     const name = ast.topology.name;
     for (const hook of ast.hooks) {
         if (!hook.run)
             continue;
-        // Extract script filename from the run command
-        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        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).
+        // Otherwise scope the stub into this topology's skill scripts directory.
+        const filePath = runPath.startsWith(".") || runPath.startsWith("/")
+            ? runPath
+            : `.claude/skills/${name}/scripts/${runPath.replace(/^.*\//, "").replace(/\s.*$/, "")}`;
         files.push({
-            path: `.claude/skills/${name}/scripts/${scriptName}`,
-            content: [
-                "#!/usr/bin/env bash",
-                `# Hook: ${hook.name} — fires on ${hook.on}`,
-                "# Auto-generated by agentopology scaffold — edit as needed.",
-                'set -euo pipefail',
-                "",
-                `echo "TODO: implement ${hook.name} hook"`,
-                "",
-            ].join("\n"),
+            path: filePath,
+            content: observabilityStub(hook.name, hook.on, hook.matcher ?? ""),
             category: "script",
+            executable: true,
         });
     }
     return files;
@@ -1580,9 +1638,16 @@ function generateSettings(ast) {
         if (!hooksByEvent[eventName]) {
             hooksByEvent[eventName] = [];
         }
-        // Build the script command with proper path prefix
-        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
-        const command = `bash .claude/skills/${topologyName}/scripts/${scriptName}`;
+        // Build the script command.
+        // If hook.run starts with '.' or '/' it is already a project-relative or
+        // absolute path — use it verbatim so observability hooks like
+        // ".claude/scripts/log-subagent.sh" land at the correct location.
+        // Otherwise treat it as a bare filename scoped to this topology's skill
+        // scripts directory.
+        const runPath = hook.run;
+        const command = runPath.startsWith(".") || runPath.startsWith("/")
+            ? `bash ${runPath}`
+            : `bash .claude/skills/${topologyName}/scripts/${runPath.replace(/^.*\//, "").replace(/\s.*$/, "")}`;
         const hookEntry = {
             hooks: [
                 {
@@ -1601,26 +1666,53 @@ function generateSettings(ast) {
     // Per-agent hooks are now rendered in AGENT.md frontmatter (not in settings.json).
     // This is the Claude Code native approach: hooks in the agent file are scoped
     // to that agent automatically.
-    // Gate enforcement — compile gates with run: to PreToolUse hooks
+    // Gate enforcement — compile gates with run: to SubagentStop hooks.
+    //
+    // SubagentStop fires when a subagent finishes. Its `matcher` field is matched
+    // against `agent_type` (the registered subagent name from .claude/agents/),
+    // NOT against arbitrary node ids. So a SubagentStop hook only fires when its
+    // matcher names a real agent node — human, action, and orchestrator nodes are
+    // NOT registered as subagent_types and their matchers would silently never
+    // fire.
+    //
+    // SubagentStop with exit code 2 (or `decision: "block"`) DOES block: per the
+    // Claude Code hooks reference, exit 2 "prevents subagent from stopping" and
+    // surfaces stderr to Claude. That is the strongest enforcement available for
+    // a gate that runs after an agent completes.
+    //
+    // For gates whose `after` target is not an agent (e.g. a human checkpoint, an
+    // action, or "any"), no SubagentStop hook fires reliably. We skip emitting
+    // dead config and warn the user — the topology's orchestrator (or a slash
+    // command playbook) must invoke the gate script at the right step.
     const gates = ast.nodes.filter((n) => n.type === "gate");
     for (const gate of gates) {
         if (!gate.run)
             continue;
         if (gate.behavior === "advisory")
             continue; // advisory gates stay in markdown only
-        const eventName = "PreToolUse";
+        // SubagentStop matcher must be a registered subagent_type. If the gate
+        // doesn't target an agent node, we cannot wire it as a hook — warn and
+        // skip so we don't ship dead config that never fires.
+        if (!isRegisteredSubagentType(ast, gate.after)) {
+            const targetDesc = gate.after ? `non-agent target "${gate.after}"` : "no after: target";
+            console.warn(`[claude-code] Gate "${gate.id}" has ${targetDesc} — SubagentStop hook not emitted ` +
+                `(matcher must be an agent node id). The gate wrapper script is still generated; ` +
+                `invoke it from your orchestrator playbook or a slash command at the right step.`);
+            continue;
+        }
+        const eventName = "SubagentStop";
         if (!hooksByEvent[eventName])
             hooksByEvent[eventName] = [];
         const scriptName = `gate-${gate.id}.sh`;
         const command = `bash .claude/skills/${topologyName}/scripts/${scriptName}`;
         const hookEntry = {
+            matcher: gate.after,
             hooks: [
                 {
                     type: "command",
                     command,
                 },
             ],
-            matcher: "Task", // Gates fire on Task tool (agent spawning)
         };
         hooksByEvent[eventName].push(hookEntry);
     }
@@ -1633,66 +1725,21 @@ function generateSettings(ast) {
     if (envSettings) {
         settings.env = envSettings;
     }
-    // Permissions section from settings block
+    // Permissions section from settings block — nested under "permissions" key
     const perms = ast.settings;
     if (perms) {
         const allow = perms.allow;
         const deny = perms.deny;
-        const ask = perms.ask;
+        const permObj = {};
         if (allow && allow.length > 0)
-            settings.allow = allow;
+            permObj.allow = allow;
         if (deny && deny.length > 0)
-            settings.deny = deny;
-        if (ask && ask.length > 0)
-            settings.ask = ask;
-    }
-    // Defaults documentation
-    if (ast.defaults) {
-        const d = ast.defaults;
-        const defaultsDoc = {};
-        if (d.temperature != null)
-            defaultsDoc.temperature = d.temperature;
-        if (d.maxTokens != null)
-            defaultsDoc.maxTokens = d.maxTokens;
-        if (d.topP != null)
-            defaultsDoc.topP = d.topP;
-        if (d.topK != null)
-            defaultsDoc.topK = d.topK;
-        if (d.stop)
-            defaultsDoc.stop = d.stop;
-        if (d.seed != null)
-            defaultsDoc.seed = d.seed;
-        if (d.thinking)
-            defaultsDoc.thinking = d.thinking;
-        if (d.thinkingBudget != null)
-            defaultsDoc.thinkingBudget = d.thinkingBudget;
-        if (d.outputFormat)
-            defaultsDoc.outputFormat = d.outputFormat;
-        if (d.timeout)
-            defaultsDoc.timeout = d.timeout;
-        if (d.logLevel)
-            defaultsDoc.logLevel = d.logLevel;
-        if (Object.keys(defaultsDoc).length > 0) {
-            settings._defaults = defaultsDoc;
-        }
-    }
-    // Observability documentation
-    if (ast.observability) {
-        const o = ast.observability;
-        const obsDoc = {
-            enabled: o.enabled,
-            level: o.level,
-            exporter: o.exporter,
-            sampleRate: o.sampleRate,
-        };
-        if (o.endpoint)
-            obsDoc.endpoint = o.endpoint;
-        if (o.service)
-            obsDoc.service = o.service;
-        obsDoc.capture = o.capture;
-        obsDoc.spans = o.spans;
-        settings._observability = obsDoc;
+            permObj.deny = deny;
+        if (Object.keys(permObj).length > 0)
+            settings.permissions = permObj;
     }
+    // Defaults and observability are documented in the CLAUDE.md context file,
+    // not in settings.json (Claude Code doesn't recognize these keys).
     // Top-level extensions for claude-code
     if (ast.extensions?.["claude-code"]) {
         for (const [k, v] of Object.entries(ast.extensions["claude-code"])) {
@@ -1955,21 +2002,23 @@ function generateCommandFiles(ast) {
         // Frontmatter
         const fm = {};
         if (ast.topology.description) {
-            fm.description = `"${ast.topology.description}"`;
+            fm.description = ast.topology.description;
+        }
+        if (trigger.argument) {
+            fm["argument-hint"] = `[${trigger.argument}]`;
         }
         sections.push(frontmatter(fm));
         sections.push("");
-        // Header
+        // Header — use $ARGUMENTS for Claude Code command argument substitution
         sections.push(`# /${trigger.name}`);
         sections.push("");
-        sections.push(trigger.pattern);
-        sections.push("");
-        // Arguments
         if (trigger.argument) {
-            sections.push("## Arguments");
-            sections.push(`- ${trigger.argument}: extracted from the command pattern`);
-            sections.push("");
+            sections.push(`/${trigger.name} $ARGUMENTS`);
         }
+        else {
+            sections.push(trigger.pattern);
+        }
+        sections.push("");
         // Pipeline (from edges, enhanced)
         if (ast.edges.length > 0) {
             sections.push("## Pipeline");
@@ -2076,7 +2125,7 @@ function generateWorkspaceProtocol(ast) {
  * destroy their content.
  */
 function generateContextFile(ast) {
-    const DEFAULT_PATH = ".claude/CONTEXT.md";
+    const DEFAULT_PATH = ".claude/CLAUDE.md";
     let fileName = ast.context.file ?? DEFAULT_PATH;
     // Safety: never overwrite the user's root-level CLAUDE.md
     if (fileName === "CLAUDE.md" || fileName === "./CLAUDE.md") {