agentopology 0.5.2 → 0.7.0

package/dist/bindings/claude-code.js

@@ -8,9 +8,11 @@
  */
 import { deduplicateFiles } from "./types.js";
 import { shellStub, STUB_MARKER } 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";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -21,13 +23,43 @@ import { gateAnchors } from "../parser/ast.js";
 function convertMcpToolName(tool) {
     if (!tool.startsWith("mcp."))
         return tool;
-    // mcp.server-name.method_name → mcp__server-name__method_name
-    // Only replace the first two dots (mcp + server separator)
-    const parts = tool.split(".");
-    if (parts.length >= 3) {
-        return `mcp__${parts[1]}__${parts.slice(2).join(".")}`;
+    // mcp.server → mcp__server (every tool on it); mcp.server.* → mcp__server__*;
+    // mcp.server.method_name → mcp__server__method_name. Only the first dot after
+    // the server separates; a dotted method name keeps its own dots.
+    const rest = tool.slice(4);
+    const dot = rest.indexOf(".");
+    if (dot === -1)
+        return `mcp__${rest}`;
+    return `mcp__${rest.slice(0, dot)}__${rest.slice(dot + 1)}`;
+}
+/**
+ * Whether Claude Code accepts `model` as written: an alias (optionally with a
+ * context suffix such as [1m]), inherit, or a full claude-* model id. Any other
+ * value (gpt-4o, gemini-2.5-pro) was written to the agent file unchecked.
+ */
+function isClaudeCodeModel(model) {
+    return /^(?:sonnet|opus|haiku|fable)(?:\[[0-9a-z]+\])?$|^inherit$|^claude-[a-z0-9.-]+(?:\[[0-9a-z]+\])?$/.test(model);
+}
+/**
+ * Claude Code hook events for the language's universal names. A hook on a
+ * name Claude Code does not know never fires, so AgentStop used to be dead.
+ */
+const UNIVERSAL_EVENTS = {
+    AgentStart: "SubagentStart",
+    AgentStop: "SubagentStop",
+    ToolUse: "PostToolUse",
+    Error: "PostToolUseFailure",
+};
+function claudeEvent(on) {
+    return UNIVERSAL_EVENTS[on] ?? on;
+}
+/** A settings.json hook handler for a command or prompt hook. */
+function hookHandler(hook, command) {
+    // A prompt hook asks a model to judge the event; its run: is the prompt.
+    if (hook.type === "prompt") {
+        return { type: "prompt", prompt: hook.run, ...(hook.timeout ? { timeout: hook.timeout } : {}) };
     }
-    return tool;
+    return { type: "command", command: command(), ...(hook.timeout ? { timeout: hook.timeout } : {}) };
 }
 /**
  * Downshift all markdown headings by one level so they nest properly
@@ -54,6 +86,8 @@ function toTitle(id) {
  */
 /** Characters that require quoting in YAML scalar values. */
 const YAML_SPECIAL = /[:#\[\]{}&*!|>'"%@`]/;
+/** Plain scalars YAML reads as something other than a string (yes → true, 1.0 → a number). */
+const YAML_NOT_STRING = /^(?:y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF|null|Null|NULL|~|[-+]?(?:\d[\d_]*)?\.?\d+(?:[eE][-+]?\d+)?|0x[0-9a-fA-F]+|0o[0-7]+|\.inf|\.nan)$/;
 function frontmatter(fields) {
     const lines = ["---"];
     for (const [key, value] of Object.entries(fields)) {
@@ -67,13 +101,13 @@ function frontmatter(fields) {
                 lines.push(`  - ${item}`);
             }
         }
-        else if (typeof value === "boolean") {
+        else if (typeof value === "boolean" || typeof value === "number") {
             lines.push(`${key}: ${value}`);
         }
         else {
             // Auto-quote strings containing YAML-special characters
             const str = String(value);
-            const needsQuotes = YAML_SPECIAL.test(str) || str.trim() !== str;
+            const needsQuotes = YAML_SPECIAL.test(str) || str.trim() !== str || str === "" || YAML_NOT_STRING.test(str);
             lines.push(`${key}: ${needsQuotes ? `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : str}`);
         }
     }
@@ -105,7 +139,96 @@ function getDelegationMode(ast) {
     const orch = ast.nodes.find((n) => n.type === "orchestrator");
     return orch?.delegation === "inline" ? "inline" : "subagent";
 }
-/** Generate an empty directory marker (a .gitkeep file). */
+function gateWiring(ast, gate) {
+    if (getDelegationMode(ast) === "inline")
+        return { kind: "none" };
+    const afters = gateAnchors(gate, "after");
+    if (afters.length > 0 && afters.every((a) => isRegisteredSubagentType(ast, a))) {
+        return { kind: "subagent-stop", anchors: afters };
+    }
+    const agents = gateAnchors(gate, "before").filter((b) => isRegisteredSubagentType(ast, b));
+    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) {
+    if (getDelegationMode(ast) === "inline")
+        return [];
+    const out = ast.edges.filter((e) => e.from === human.id && !e.isError).map((e) => e.to);
+    return [...new Set(out)].filter((id) => isRegisteredSubagentType(ast, id));
+}
+/** 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"`;
+}
+/**
+ * One PreToolUse hook on the Agent tool for the whole topology: before Claude
+ * Code launches a subagent it runs that agent's gates (from actions or
+ * humans), then asks the user to approve when a human step stands before it.
+ * Null when nothing needs it.
+ */
+function generateBeforeAgentScript(ast) {
+    const name = ast.topology.name;
+    const steps = new Map();
+    const add = (agent, lines) => steps.set(agent, [...(steps.get(agent) ?? []), ...lines]);
+    for (const node of ast.nodes) {
+        if (node.type !== "gate")
+            continue;
+        const gate = node;
+        if (!gate.run || gate.behavior === "advisory" || !scriptNameFromRun(gate.run))
+            continue;
+        const wiring = gateWiring(ast, gate);
+        if (wiring.kind !== "before-agent")
+            continue;
+        for (const agent of wiring.agents) {
+            add(agent, [
+                `    # gate ${gate.id} (after: ${gateAnchors(gate, "after").join(", ") || "-"})`,
+                `    bash "$DIR/gate-${gate.id}.sh" >&2 || exit 2`,
+            ]);
+        }
+    }
+    for (const node of ast.nodes) {
+        if (node.type !== "human")
+            continue;
+        const human = node;
+        const reason = `Approval step "${human.id}"${human.description ? `: ${human.description}` : ""}`;
+        for (const agent of approvalTargets(ast, human)) {
+            add(agent, [`    # approval step ${human.id}`, `    ask ${shellQuote(reason)}`]);
+        }
+    }
+    if (steps.size === 0)
+        return null;
+    const lines = [
+        "#!/usr/bin/env bash",
+        `# Before Claude Code launches a subagent of topology "${name}".`,
+        "# Auto-generated by agentopology scaffold. Wired in .claude/settings.json as a",
+        "# 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",
+        'cd "$CLAUDE_PROJECT_DIR"',
+        `DIR=".claude/skills/${name}/scripts"`,
+        'AGENT=$(jq -r \'.tool_input.subagent_type // ""\')',
+        "",
+        "ask() {",
+        "  jq -n --arg r \"$1\" '{hookSpecificOutput: {hookEventName: \"PreToolUse\", permissionDecision: \"ask\", permissionDecisionReason: $r}}'",
+        "}",
+        "",
+        'case "$AGENT" in',
+    ];
+    for (const [agent, body] of steps) {
+        lines.push(`  ${agent})`, ...body, "    ;;");
+    }
+    lines.push("esac", "exit 0", "");
+    return {
+        path: `.claude/skills/${name}/scripts/before-agent.sh`,
+        content: lines.join("\n"),
+        category: "script",
+        executable: true,
+    };
+}
+/** Single-quote a string for bash. */
+function shellQuote(text) {
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
 function gitkeep(dirPath) {
     return { path: `${dirPath}/.gitkeep`, content: "", category: "machine" };
 }
@@ -251,7 +374,7 @@ function workflowRunLabel(ast, run) {
  */
 function mapPermissionMode(perm) {
     // Claude Code native values — pass through
-    const nativeValues = ["plan", "default", "acceptEdits", "dontAsk", "bypassPermissions"];
+    const nativeValues = ["plan", "default", "acceptEdits", "auto", "dontAsk", "bypassPermissions"];
     if (nativeValues.includes(perm)) {
         // "default" is the default, omit it
         if (perm === "default")
@@ -264,14 +387,16 @@ function mapPermissionMode(perm) {
             return "plan";
         case "autonomous":
             return undefined; // default, omit
-        case "auto":
-            return undefined; // default, omit
+        case "confirm":
+            return undefined; // asks before each action: Claude Code's default
         case "interactive":
             return "acceptEdits";
         case "unrestricted":
+        case "bypass":
             return "bypassPermissions";
         default:
-            return perm; // unknown — pass through as-is
+            // Claude Code rejects an unknown permissionMode; V27 already warned.
+            return undefined;
     }
 }
 /** Format a SchemaType to a human-readable string. Optionally resolves refs. */
@@ -325,45 +450,24 @@ function generateActionNodes(ast) {
         if (action.join) {
             lines.push(`# Join semantics: ${action.join}`);
         }
-        switch (action.kind) {
-            case "external":
-                lines.push(`# External source: ${action.source ?? "unknown"}`);
-                lines.push("");
-                lines.push(`echo "TODO: implement external action — fetch from ${action.source ?? "source"}"`);
-                break;
-            case "inline":
-                if (action.commands && action.commands.length > 0) {
-                    lines.push("");
-                    for (const cmd of action.commands) {
-                        lines.push(cmd);
-                    }
-                }
-                else {
-                    lines.push("");
-                    lines.push('echo "TODO: implement inline action"');
-                }
-                break;
-            case "git":
-                lines.push("");
-                lines.push("# Git operation");
-                if (action.commands && action.commands.length > 0) {
-                    for (const cmd of action.commands) {
-                        lines.push(cmd);
-                    }
-                }
-                else {
-                    lines.push('echo "TODO: implement git action"');
-                }
-                break;
-            case "report":
-                lines.push("");
-                lines.push("# Report generation");
-                lines.push('echo "TODO: implement report action"');
-                break;
-            default:
-                lines.push("");
-                lines.push(`echo "TODO: implement ${action.kind ?? "unknown"} action"`);
-                break;
+        if (action.kind === "external")
+            lines.push(`# External source: ${action.source ?? "unknown"}`);
+        lines.push("");
+        // The action's own commands, whatever its kind: an external or report
+        // action used to drop them for a TODO line.
+        if (action.commands && action.commands.length > 0) {
+            lines.push(...action.commands);
+        }
+        else if (!action.kind || action.kind === "inline") {
+            // Done by the orchestrator in conversation (the playbook says how).
+            lines.push(`# Performed by the orchestrator in conversation; nothing to run.`);
+        }
+        else {
+            // A placeholder that reports itself as one (agentopology stubs), never a
+            // silent success.
+            lines.splice(3, 0, STUB_MARKER);
+            lines.push(`echo "TODO: implement ${action.kind ?? "this"} action ${action.id}" >&2`);
+            lines.push("exit 1");
         }
         lines.push("");
         files.push({
@@ -392,17 +496,24 @@ function generateAgents(ast) {
         const fm = {};
         fm.name = agent.id;
         // Description: prefer agent.description, then role description from roles block.
-        // For manual agents, omit description to prevent Claude Code auto-delegation.
-        if (agent.invocation !== "manual") {
-            const desc = agent.description ?? ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role;
-            if (desc) {
-                fm.description = desc;
+        // Claude Code skips an agent without one, so a manual agent keeps it and
+        // says it runs only when asked (there is no frontmatter field for that).
+        const desc = agent.description ?? ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role ?? toTitle(agent.id);
+        fm.description = agent.invocation === "manual"
+            ? `${desc.replace(/[.\s]*$/, "")}. Use only when the user asks for this agent by name; never delegate to it on your own.`
+            : desc;
+        if (agent.model) {
+            if (isClaudeCodeModel(agent.model)) {
+                fm.model = agent.model;
+            }
+            else {
+                console.warn(`[claude-code] Agent "${agent.id}" model "${agent.model}" is not a Claude Code model ` +
+                    `(sonnet, opus, haiku, fable, inherit, or a claude-* id); omitted, so the agent ` +
+                    `runs on the session's model.`);
             }
         }
-        if (agent.model)
-            fm.model = agent.model;
         if (agent.maxTurns != null)
-            fm.maxTurns = String(agent.maxTurns);
+            fm.maxTurns = agent.maxTurns;
         if (agent.tools && agent.tools.length > 0)
             fm.tools = agent.tools.map(convertMcpToolName).join(", ");
         if (agent.disallowedTools && agent.disallowedTools.length > 0)
@@ -426,8 +537,6 @@ function generateAgents(ast) {
         if (agent.fallbackChain && agent.fallbackChain.length > 0) {
             fm["fallback-chain"] = agent.fallbackChain.join(", ");
         }
-        // invocation: manual — Claude Code doesn't parse this field. Instead, omit
-        // description to prevent auto-delegation for manual agents.
         if (agent.skills && agent.skills.length > 0)
             fm.skills = agent.skills;
         // scale is NOT a Claude Code frontmatter field — rendered only in body as prompt text
@@ -449,28 +558,30 @@ function generateAgents(ast) {
             const topologyName = ast.topology.name;
             const hooksByEvent = {};
             for (const hook of agent.hooks) {
-                if (!hooksByEvent[hook.on])
-                    hooksByEvent[hook.on] = [];
-                hooksByEvent[hook.on].push(hook);
+                if (hook.type === "mod")
+                    continue; // engine-wide only (V94)
+                // In an agent's frontmatter Claude Code turns Stop into SubagentStop itself.
+                const event = hook.on === "AgentStop" ? "Stop" : claudeEvent(hook.on);
+                if (!hooksByEvent[event])
+                    hooksByEvent[event] = [];
+                hooksByEvent[event].push(hook);
             }
             const hookLines = ["hooks:"];
             for (const [eventName, hooks] of Object.entries(hooksByEvent)) {
                 hookLines.push(`  ${eventName}:`);
                 for (const hook of hooks) {
-                    const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
-                    const command = `bash .claude/skills/${topologyName}/scripts/${agent.id}-${scriptName}`;
-                    if (hook.matcher) {
-                        hookLines.push(`    - matcher: "${hook.matcher}"`);
-                    }
-                    else {
-                        hookLines.push(`    -`);
-                    }
+                    const scriptName = scriptNameFromRun(hook.run);
+                    if (hook.type !== "prompt" && !scriptName)
+                        continue; // V96: prose in run names no script
+                    const handler = hookHandler(hook, () => `bash .claude/skills/${topologyName}/scripts/${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)}` : `    -`);
                     hookLines.push(`      hooks:`);
-                    hookLines.push(`        - type: ${hook.type ?? "command"}`);
-                    hookLines.push(`          command: "${command}"`);
-                    if (hook.timeout) {
-                        hookLines.push(`          timeout: ${hook.timeout}`);
-                    }
+                    const [first, ...rest] = Object.entries(handler);
+                    hookLines.push(`        - ${first[0]}: ${JSON.stringify(first[1])}`);
+                    for (const [k, v] of rest)
+                        hookLines.push(`          ${k}: ${JSON.stringify(v)}`);
                 }
             }
             // Insert hooks before the closing ---
@@ -488,6 +599,9 @@ function generateAgents(ast) {
         }
         sections.push("## Instructions");
         sections.push("");
+        // Only the text between the markers is the prompt: sync and re-scaffold
+        // read it there, so generated sections below never leak into the .at.
+        sections.push(PROMPT_FENCE_OPEN);
         if (agent.prompt) {
             sections.push(downshiftHeadings(agent.prompt));
         }
@@ -502,6 +616,7 @@ function generateAgents(ast) {
         else {
             sections.push("Complete the assigned task.");
         }
+        sections.push(PROMPT_FENCE_CLOSE);
         sections.push("");
         // Reads section
         if (agent.reads && agent.reads.length > 0) {
@@ -809,35 +924,6 @@ function generateAgents(ast) {
     }
     return files;
 }
-/** Generate AGENT.md files for each human node. */
-function generateHumanNodes(ast) {
-    const files = [];
-    for (const node of ast.nodes) {
-        if (node.type !== "human")
-            continue;
-        const human = node;
-        const sections = [];
-        sections.push(`# ${toTitle(human.id)} (Human-in-the-Loop)`);
-        sections.push("");
-        if (human.description) {
-            sections.push(human.description);
-            sections.push("");
-        }
-        if (human.timeout) {
-            sections.push(`Timeout: ${human.timeout}`);
-        }
-        if (human.onTimeout) {
-            sections.push(`On timeout: ${human.onTimeout}`);
-        }
-        sections.push("");
-        files.push({
-            path: `.claude/agents/${human.id}/AGENT.md`,
-            content: sections.join("\n") + "\n",
-            category: "machine",
-        });
-    }
-    return files;
-}
 /**
  * Generate group chat artifacts:
  *   - Orchestrator AGENT.md — spawns members sequentially
@@ -1254,6 +1340,29 @@ function generateTopologySkill(ast) {
             sections.push("");
         }
     }
+    // Approval steps: a human node is a point where the user decides. It used to
+    // compile to an AGENT.md without frontmatter, which Claude Code ignores.
+    const humans = ast.nodes.filter((n) => n.type === "human");
+    if (humans.length > 0) {
+        sections.push("## Approval steps");
+        sections.push("");
+        sections.push("At each step below, stop and ask the user (AskUserQuestion), then continue only on their approval.");
+        sections.push("");
+        for (const human of humans) {
+            sections.push(`### ${toTitle(human.id)}`);
+            if (human.description)
+                sections.push(human.description);
+            const before = approvalTargets(ast, human);
+            if (before.length > 0) {
+                sections.push(`Before: ${before.join(", ")} (Claude Code also asks the user before launching ${before.length > 1 ? "them" : "it"})`);
+            }
+            if (human.timeout)
+                sections.push(`Timeout: ${human.timeout}`);
+            if (human.onTimeout)
+                sections.push(`On timeout: ${human.onTimeout}`);
+            sections.push("");
+        }
+    }
     // Schedules section
     if (ast.schedules.length > 0) {
         sections.push("## Schedules");
@@ -1448,9 +1557,19 @@ function generateSkills(ast) {
             }
             sections.push("");
         }
+        // The instructions themselves, or a file that holds them. "See: path" was
+        // written before: Claude Code loads a skill's other files only when the
+        // skill tells it to, so the instructions never reached the model.
         if (skill.prompt) {
-            sections.push("## Prompt");
-            sections.push(`See: ${skill.prompt}`);
+            sections.push("## Instructions");
+            sections.push("");
+            const path = skill.prompt.trim();
+            if (!/\s/.test(path) && /\.(md|txt)$/.test(path)) {
+                sections.push(`Read \`${path}\` before anything else and follow it: it holds this skill's instructions.`);
+            }
+            else {
+                sections.push(downshiftHeadings(skill.prompt));
+            }
             sections.push("");
         }
         files.push({
@@ -1641,15 +1760,22 @@ function generateGateScripts(ast) {
         if (node.type !== "gate")
             continue;
         const gate = node;
-        if (gate.run) {
-            // Extract script name from the run command
-            const scriptName = gate.run.replace(/^.*\//, "").replace(/\s.*$/, "");
-            files.push({
-                path: `.claude/skills/${name}/scripts/${scriptName}`,
-                content: shellStub(`Gate: ${gate.id} — ${gate.run}`),
-                category: "script",
-            });
-        }
+        const scriptName = scriptNameFromRun(gate.run);
+        if (!scriptName)
+            continue;
+        const { script } = runParts(gate.run);
+        // The user's own script, outside the project: never stubbed.
+        if (script.startsWith("/"))
+            continue;
+        // A project path names the user's script: a stub only fills the gap until
+        // it exists, and is never written over it.
+        const project = isProjectPath(script);
+        files.push({
+            path: project ? script.replace(/^\.\//, "") : `.claude/skills/${name}/scripts/${scriptName}`,
+            content: shellStub(`Gate: ${gate.id} — ${gate.run}`),
+            category: "script",
+            ...(project ? { createOnly: true } : {}),
+        });
     }
     return files;
 }
@@ -1665,18 +1791,22 @@ function generateGateWrapperScripts(ast) {
             continue;
         if (gate.behavior === "advisory")
             continue;
-        const gateScriptName = gate.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        if (!scriptNameFromRun(gate.run))
+            continue; // V96: prose in run names no script
+        const gateCommand = hookCommand(gate.run, name);
         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 inlineMode = getDelegationMode(ast) === "inline";
-        const gateAfters = gateAnchors(gate, "after");
-        const wiredAsHook = !inlineMode &&
-            gateAfters.length > 0 &&
-            gateAfters.every((a) => isRegisteredSubagentType(ast, a));
+        const wiring = gateWiring(ast, gate);
+        const wiredAsHook = wiring.kind === "subagent-stop";
         let enforcementNote;
         let enforcementNote2;
-        if (inlineMode) {
+        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.`;
+        }
+        else if (inlineMode) {
             enforcementNote = `# Enforcement: NOT wired as a SubagentStop hook (orchestrator.delegation is "inline").`;
             enforcementNote2 = `#              Invoke this script from your /${ast.topology.name} playbook at the right step.`;
         }
@@ -1712,10 +1842,10 @@ function generateGateWrapperScripts(ast) {
             contentLines.push("while [ $ATTEMPT -le $MAX_RETRIES ] && [ $GATE_RESULT -ne 0 ]; do");
             contentLines.push("  ATTEMPT=$((ATTEMPT + 1))");
             if (gate.timeout) {
-                contentLines.push(`  timeout ${gate.timeout} bash .claude/skills/${name}/scripts/${gateScriptName} && GATE_RESULT=0 || GATE_RESULT=$?`);
+                contentLines.push(`  timeout ${gate.timeout} ${gateCommand} && GATE_RESULT=0 || GATE_RESULT=$?`);
             }
             else {
-                contentLines.push(`  bash .claude/skills/${name}/scripts/${gateScriptName} && GATE_RESULT=0 || GATE_RESULT=$?`);
+                contentLines.push(`  ${gateCommand} && GATE_RESULT=0 || GATE_RESULT=$?`);
             }
             contentLines.push('  if [ $GATE_RESULT -ne 0 ] && [ $ATTEMPT -le $MAX_RETRIES ]; then');
             contentLines.push(`    echo "Gate '${gate.id}' attempt $ATTEMPT failed, retrying..."`);
@@ -1728,10 +1858,10 @@ function generateGateWrapperScripts(ast) {
             contentLines.push("# Run the gate check script");
             contentLines.push(`GATE_RESULT=0`);
             if (gate.timeout) {
-                contentLines.push(`timeout ${gate.timeout} bash .claude/skills/${name}/scripts/${gateScriptName} || GATE_RESULT=$?`);
+                contentLines.push(`timeout ${gate.timeout} ${gateCommand} || GATE_RESULT=$?`);
             }
             else {
-                contentLines.push(`bash .claude/skills/${name}/scripts/${gateScriptName} || GATE_RESULT=$?`);
+                contentLines.push(`${gateCommand} || GATE_RESULT=$?`);
             }
         }
         contentLines.push("");
@@ -1761,7 +1891,7 @@ function observabilityStub(hookName, eventName, matcherHint) {
     if (isFinishEvent) {
         return [
             "#!/usr/bin/env bash",
-            `# Auto-generated by agentopology scaffold on ${new Date().toISOString().slice(0, 10)}`,
+            `# Auto-generated by agentopology scaffold`,
             `# Hook: ${hookName} · Event: ${eventName} · Matcher: ${matcherHint || "*"}`,
             "# Replace this stub with your implementation.",
             "# Stdin JSON payload from Claude Code is available on FD 0.",
@@ -1777,7 +1907,7 @@ function observabilityStub(hookName, eventName, matcherHint) {
     }
     return [
         "#!/usr/bin/env bash",
-        `# Auto-generated by agentopology scaffold on ${new Date().toISOString().slice(0, 10)}`,
+        `# Auto-generated by agentopology scaffold`,
         `# Hook: ${hookName} · Event: ${eventName} · Matcher: ${matcherHint || "*"}`,
         "# Replace this stub with your implementation.",
         "# Stdin JSON payload from Claude Code is available on FD 0.",
@@ -1790,6 +1920,123 @@ function observabilityStub(hookName, eventName, matcherHint) {
         "",
     ].join("\n");
 }
+/**
+ * `type: mod` hooks → a Claude Code plugin (function hooks, early access).
+ *
+ * A Mod is a TypeScript module loaded INSIDE the engine; settings.json cannot
+ * carry it. The engine loads ONE module per plugin (hooks.json `modules`,
+ * measured on 2.1.283), so the plugin's single entry is a generated
+ * `hooks/at-register.ts` that imports each declared Mod's `register(on)` and
+ * calls it. A `flag:` is the Mod's OWN switch: the Mod reads it per event with
+ * `$.env.get`, and the launch script sets it. The entry cannot gate it: a
+ * module has no `process`, and the engine refuses an `on` that is wrapped or
+ * kept (measured 2.1.283: "on is always on(\"<event>\", hook)"). The launch script
+ * sets CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (without it the module never
+ * loads), each flag, and `--plugin-dir`.
+ *
+ * The plugin root is the folder that HOLDS the Mods' modules, because the
+ * engine refuses a hooks module that imports outside its plugin folder
+ * (measured 2.1.283: "cannot import … it is outside the plugin's folder").
+ * The entry has its own name so it never overwrites a hand-written
+ * `hooks/register.ts`. The Mods' own modules are the user's code: nothing is
+ * written at a `run:` path. A topology without Mods gets no plugin.
+ */
+export const MOD_PLUGIN_ENV = "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS";
+export const MOD_ENTRY = "at-register.ts";
+/**
+ * The plugin root: the deepest folder shared by every Mod's `run:` path, less
+ * a trailing `hooks` (the plugin's own hooks/ folder). "" is the project root.
+ * null when a `run:` is absolute: it cannot be placed inside the project.
+ */
+export function modPluginDir(ast) {
+    const runs = ast.hooks.filter((h) => h.type === "mod" && h.run).map((h) => h.run);
+    if (runs.length === 0 || runs.some((r) => r.startsWith("/")))
+        return null;
+    const dirs = runs.map((r) => r.split("/").filter((p) => p && p !== ".").slice(0, -1));
+    const shared = [];
+    for (let i = 0; dirs.every((d) => i < d.length && d[i] === dirs[0][i]); i++)
+        shared.push(dirs[0][i]);
+    if (shared[shared.length - 1] === "hooks")
+        shared.pop();
+    return shared.join("/");
+}
+function generateModPlugin(ast) {
+    const mods = ast.hooks.filter((h) => h.type === "mod" && h.run);
+    if (mods.length === 0)
+        return [];
+    const name = ast.topology.name;
+    const dir = modPluginDir(ast);
+    if (dir === null) {
+        console.warn(`[claude-code] Mods ${mods.map((m) => m.name).join(", ")}: a run: path is absolute, so no plugin folder ` +
+            `can hold the modules (the engine refuses imports outside it). Use project-relative run: paths. Skipped.`);
+        return [];
+    }
+    const at = (p) => (dir ? `${dir}/${p}` : p);
+    const hooksDir = at("hooks");
+    // `run:` is project-relative (or absolute); the import is relative to hooks/.
+    // Bindings stay free of node: imports, so the relative path is computed here.
+    const importPath = (run) => {
+        const target = run.replace(/\.(ts|js|mjs)$/, "");
+        if (target.startsWith("/"))
+            return target;
+        const to = target.split("/").filter((p) => p && p !== ".");
+        const from = hooksDir.split("/");
+        let common = 0;
+        while (common < from.length && common < to.length - 1 && from[common] === to[common])
+            common++;
+        const rel = [...from.slice(common).map(() => ".."), ...to.slice(common)].join("/");
+        return rel.startsWith(".") ? rel : `./${rel}`;
+    };
+    const ident = (hookName) => "mod_" + hookName.replace(/[^A-Za-z0-9_]/g, "_");
+    const summary = mods
+        .map((m) => `${m.name} (${m.on}${m.flag ? `, ${m.flag}` : ""})`)
+        .join("; ");
+    const pluginJson = {
+        name: `${name}-mods`,
+        version: ast.topology.version || "0.0.0",
+        description: `Mods of the ${name} topology, generated by agentopology: ${summary}.`,
+    };
+    const hooksJson = {
+        description: `The engine loads ONE module per plugin: ${MOD_ENTRY} registers every Mod ` +
+            `declared in ${name}.at. Off unless ${MOD_PLUGIN_ENV}=1.`,
+        modules: [`./${MOD_ENTRY}`],
+    };
+    const register = [
+        "// Generated by agentopology scaffold from the topology's `type: mod` hooks.",
+        "// The engine loads ONE module per plugin: this one registers every Mod.",
+        "// Edit the .at file, not this file.",
+        "import type { On } from 'claude-code'",
+        "",
+        ...mods.map((m) => `import { register as ${ident(m.name)} } from '${importPath(m.run)}'`),
+        "",
+        "export function register(on: On) {",
+        ...mods.map((m) => `  // ${m.name} · on ${m.on}${m.flag ? ` · the Mod reads its own switch, ${m.flag}` : ""}\n  ${ident(m.name)}(on)`),
+        "}",
+        "",
+    ].join("\n");
+    const flags = [...new Set(mods.map((m) => m.flag).filter((f) => !!f))];
+    const launch = [
+        "#!/usr/bin/env bash",
+        `# Launch Claude Code with the Mods of ${name} (generated by agentopology).`,
+        "# Mods run inside the engine (function hooks, early access).",
+        "# Each flag defaults to on here; set it to 0 before launching to turn a Mod off.",
+        "set -euo pipefail",
+        'PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+        `export ${MOD_PLUGIN_ENV}=1`,
+        ...flags.map((f) => {
+            const users = mods.filter((m) => m.flag === f).map((m) => `${m.name} · ${m.on}`).join(", ");
+            return `export ${f}="\${${f}:-1}"   # ${users}`;
+        }),
+        'exec claude --plugin-dir "$PLUGIN_DIR" "$@"',
+        "",
+    ].join("\n");
+    return [
+        { path: at(".claude-plugin/plugin.json"), content: JSON.stringify(pluginJson, null, 2) + "\n" },
+        { path: `${hooksDir}/hooks.json`, content: JSON.stringify(hooksJson, null, 2) + "\n" },
+        { path: `${hooksDir}/${MOD_ENTRY}`, content: register },
+        { path: at("launch-mods.sh"), content: launch, executable: true },
+    ];
+}
 /** Generate hook script stubs for every hook's `run` field (Changes 1, 4, 5). */
 function generateHookScripts(ast) {
     const files = [];
@@ -1797,18 +2044,36 @@ function generateHookScripts(ast) {
     for (const hook of ast.hooks) {
         if (!hook.run)
             continue;
+        // A Mod's run: is the user's TypeScript module — never overwrite it with a
+        // bash stub. generateModPlugin imports it instead.
+        if (hook.type === "mod" || hook.type === "prompt")
+            continue;
         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.*$/, "")}`;
+        if (proseInRun(runPath))
+            continue; // V96: prose in run names no script
+        const { script } = runParts(runPath);
+        // An absolute script is the user's own, outside the project: never stubbed.
+        if (script.startsWith("/"))
+            continue;
+        const scoped = scriptNameFromRun(script);
+        const filePath = isProjectPath(script)
+            ? script
+            : scoped
+                ? `.claude/skills/${name}/scripts/${scoped}`
+                : null;
+        if (!filePath)
+            continue;
         files.push({
             path: filePath,
             content: observabilityStub(hook.name, hook.on, hook.matcher ?? ""),
             category: "script",
             executable: true,
+            // A run that names its own path names the user's script: a stub only
+            // fills the gap until it exists. --force used to overwrite it.
+            ...(isProjectPath(script) ? { createOnly: true } : {}),
         });
     }
     return files;
@@ -1824,9 +2089,11 @@ function generateAgentHookScripts(ast) {
         if (!agent.hooks || agent.hooks.length === 0)
             continue;
         for (const hook of agent.hooks) {
-            if (!hook.run)
+            if (!hook.run || hook.type === "mod" || hook.type === "prompt")
                 continue;
-            const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+            const scriptName = scriptNameFromRun(hook.run);
+            if (!scriptName)
+                continue; // V96: prose in run names no script
             files.push({
                 path: `.claude/skills/${name}/scripts/${agent.id}-${scriptName}`,
                 content: [
@@ -1845,19 +2112,45 @@ function generateAgentHookScripts(ast) {
     return files;
 }
 /**
- * Generate hook configuration in .claude/settings.json.
+ * The shell command for a command hook's or gate's `run:`.
  *
- * Hooks are grouped by event name as an object:
- *   { "hooks": { "PostToolUse": [ { hooks: [...], matcher? } ], ... } }
+ * A `run:` whose script (see runParts) is a project path names the user's own
+ * script. A project-relative one runs through `$CLAUDE_PROJECT_DIR` (a hook's
+ * cwd is the session's, which moves); an absolute one is kept as written. It
+ * runs by the interpreter the `run:` names, else the one its extension names
+ * (`.py` → python3, anything else → bash). Arguments are kept.
+ *
+ * Any other `run:` is a script this topology's skill scaffolds, by basename.
  */
-function generateSettings(ast) {
-    const settings = {};
+export function hookCommand(run, topologyName) {
+    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(" ");
+    }
+    const interpreter = named ?? (first.endsWith(".py") ? "python3" : "bash");
+    const where = first.startsWith("/")
+        ? first
+        : `"$CLAUDE_PROJECT_DIR/${first.replace(/^\.\//, "")}"`;
+    return [interpreter, where, ...rest].join(" ");
+}
+/**
+ * The settings.json `hooks` entries of the topology's own `hooks {}` block
+ * (command hooks only; a Mod is a plugin, see generateModPlugin), grouped by
+ * event. Gate wiring is added by generateSettings, not here: a caller that
+ * wants the reflexes alone (e.g. a drift check against a live settings file)
+ * reads this.
+ */
+export function settingsHooksOf(ast) {
     const topologyName = ast.topology.name;
     const isInline = getDelegationMode(ast) === "inline";
-    // Hooks section — grouped by event name
     const hooksByEvent = {};
     for (const hook of ast.hooks) {
-        const eventName = hook.on;
+        // A Mod is a module inside the engine, not a settings.json command: it is
+        // emitted as a plugin (generateModPlugin).
+        if (hook.type === "mod")
+            continue;
+        const eventName = claudeEvent(hook.on);
         // Inline orchestrator mode never spawns subagents, so SubagentStop /
         // SubagentStart hooks would never fire. Warn the user and skip emission
         // — keeping them in settings.json would be a maintenance trap.
@@ -1868,27 +2161,13 @@ function generateSettings(ast) {
                 `delegation to "subagent".`);
             continue;
         }
+        if (hook.type !== "prompt" && proseInRun(hook.run))
+            continue; // V96: prose in run names no script
         if (!hooksByEvent[eventName]) {
             hooksByEvent[eventName] = [];
         }
-        // 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: [
-                {
-                    type: hook.type ?? "command",
-                    command,
-                    ...(hook.timeout ? { timeout: hook.timeout } : {}),
-                },
-            ],
+            hooks: [hookHandler(hook, () => hookCommand(hook.run, topologyName))],
         };
         // Only add matcher when it has a value
         if (hook.matcher) {
@@ -1896,6 +2175,19 @@ function generateSettings(ast) {
         }
         hooksByEvent[eventName].push(hookEntry);
     }
+    return hooksByEvent;
+}
+/**
+ * Generate hook configuration in .claude/settings.json.
+ *
+ * Hooks are grouped by event name as an object:
+ *   { "hooks": { "PostToolUse": [ { hooks: [...], matcher? } ], ... } }
+ */
+function generateSettings(ast) {
+    const settings = {};
+    const topologyName = ast.topology.name;
+    // Hooks section — grouped by event name
+    const hooksByEvent = settingsHooksOf(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.
@@ -1927,8 +2219,8 @@ function generateSettings(ast) {
     const delegationMode = getDelegationMode(ast);
     const gates = ast.nodes.filter((n) => n.type === "gate");
     for (const gate of gates) {
-        if (!gate.run)
-            continue;
+        if (!scriptNameFromRun(gate.run))
+            continue; // no run, or V96 prose
         if (gate.behavior === "advisory")
             continue; // advisory gates stay in markdown only
         if (delegationMode === "inline") {
@@ -1938,11 +2230,15 @@ function generateSettings(ast) {
                 `orchestrator playbook at the right step.`);
             continue;
         }
-        // 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.
+        // SubagentStop matcher must be a registered subagent_type. A gate after an
+        // action or a human runs before its next agent instead (before-agent.sh,
+        // wired below); with no agent on either side, warn and skip so we don't
+        // ship dead config that never fires.
         const anchors = gateAnchors(gate, "after");
-        if (anchors.length === 0 || !anchors.every((a) => isRegisteredSubagentType(ast, a))) {
+        const wiring = gateWiring(ast, gate);
+        if (wiring.kind === "before-agent")
+            continue;
+        if (wiring.kind !== "subagent-stop") {
             const bad = anchors.filter((a) => !isRegisteredSubagentType(ast, a));
             const targetDesc = anchors.length
                 ? `non-agent target ${bad.map((b) => `"${b}"`).join(", ")}`
@@ -1981,6 +2277,15 @@ function generateSettings(ast) {
     // Blackboard implies a host-side observer that watches the workflow rung's
     // Write tool-calls LIVE. This is the host's piece of the hybrid's concurrent
     // observability (the deterministic workflow rung cannot express it).
+    if (generateBeforeAgentScript(ast)) {
+        if (!hooksByEvent.PreToolUse)
+            hooksByEvent.PreToolUse = [];
+        hooksByEvent.PreToolUse.push({
+            // Agent is the subagent tool; Task is its earlier name.
+            matcher: "Agent|Task",
+            hooks: [{ type: "command", command: beforeAgentCommand(ast) }],
+        });
+    }
     const observeHook = buildHybridObserveHook(ast, topologyName);
     if (observeHook) {
         if (!hooksByEvent[observeHook.event])
@@ -1999,13 +2304,12 @@ function generateSettings(ast) {
     // Permissions section from settings block — nested under "permissions" key
     const perms = ast.settings;
     if (perms) {
-        const allow = perms.allow;
-        const deny = perms.deny;
         const permObj = {};
-        if (allow && allow.length > 0)
-            permObj.allow = allow;
-        if (deny && deny.length > 0)
-            permObj.deny = deny;
+        for (const key of ["allow", "ask", "deny"]) {
+            const rules = perms[key];
+            if (rules && rules.length > 0)
+                permObj[key] = rules.map(convertMcpToolName);
+        }
         if (Object.keys(permObj).length > 0)
             settings.permissions = permObj;
     }
@@ -2059,9 +2363,12 @@ function generateMcpJson(ast) {
     for (const [name, config] of Object.entries(ast.mcpServers)) {
         const entry = {};
         for (const [key, value] of Object.entries(config)) {
-            if (key === "command" || key === "url") {
+            if (key === "command" || key === "url" || key === "type") {
                 entry[key] = value;
             }
+            else if (key === "headers" && typeof value === "object" && value !== null) {
+                entry.headers = value;
+            }
             else if (key === "args" && Array.isArray(value)) {
                 entry.args = value;
             }
@@ -2073,8 +2380,11 @@ function generateMcpJson(ast) {
         // Only include servers that have a command or url (filter parser artifacts)
         if (!("command" in entry) && !("url" in entry))
             continue;
-        // Always include env field for Claude Code .mcp.json
-        if (!("env" in entry)) {
+        // Claude Code reads a url entry without type as stdio and skips it.
+        if ("url" in entry && !("type" in entry))
+            entry.type = "http";
+        // Always include env field for a stdio server in .mcp.json
+        if (!("url" in entry) && !("env" in entry)) {
             entry.env = {};
         }
         servers[name] = entry;
@@ -2155,6 +2465,7 @@ function generateToolScripts(ast) {
             shebang,
             `# Tool: ${tool.id} — ${tool.description}`,
             "# Auto-generated by agentopology scaffold — edit as needed.",
+            tool.lang === "node" ? `// ${STUB_MARKER}` : STUB_MARKER,
             "",
         ];
         if (tool.lang === "bash" || !tool.lang) {
@@ -2175,14 +2486,50 @@ function generateToolScripts(ast) {
             lines.push(`echo "TODO: implement ${tool.id}"`);
         }
         lines.push("");
+        // The stub goes where the tool's script: says, not to a copy beside it: a
+        // project path is the user's script (create-only); an absolute one is never
+        // touched; a bare name lives in the skill's scripts folder.
+        const script = tool.script ? runParts(tool.script).script : "";
+        if (script.startsWith("/"))
+            continue;
+        const project = isProjectPath(script);
+        const base = script.replace(/^.*\//, "");
         files.push({
-            path: `.claude/skills/${name}/scripts/${tool.id}.${ext}`,
+            path: project
+                ? script.replace(/^\.\//, "")
+                : `.claude/skills/${name}/scripts/${base || `${tool.id}.${ext}`}`,
             content: lines.join("\n"),
             category: "script",
+            ...(project ? { createOnly: true } : {}),
         });
     }
     return files;
 }
+/**
+ * A cron expression for an `every:` duration, or null when cron cannot say
+ * it. Only "1h", "daily" and a few words converted before; anything else
+ * became a commented-out crontab line that never ran.
+ */
+function everyToCron(every) {
+    const text = every.trim().toLowerCase();
+    const words = { hourly: "0 * * * *", daily: "0 0 * * *", weekly: "0 0 * * 0" };
+    if (words[text])
+        return words[text];
+    const m = text.match(/^(\d+)\s*(m|min|mins|minutes?|h|hours?|d|days?|w|weeks?)$/);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = m[2][0];
+    if (n <= 0)
+        return null;
+    if (unit === "m")
+        return n < 60 && 60 % n === 0 ? (n === 1 ? "* * * * *" : `*/${n} * * * *`) : null;
+    if (unit === "h")
+        return n < 24 && 24 % n === 0 ? (n === 1 ? "0 * * * *" : `0 */${n} * * *`) : null;
+    if (unit === "d")
+        return n === 1 ? "0 0 * * *" : null;
+    return n === 1 ? "0 0 * * 0" : null;
+}
 /** Generate schema documentation files. */
 function generateSchemas(ast) {
     const files = [];
@@ -2227,15 +2574,18 @@ function generateScheduleScripts(ast) {
             `# Schedule: ${job.id} — invokes ${target}`,
             "# Auto-generated by agentopology scaffold — edit as needed.",
             'set -euo pipefail',
+            "# cron starts in $HOME: run from the project root (this script is in scripts/).",
+            'cd "$(dirname "$0")/.."',
             "",
         ];
         if (job.agent) {
+            // Headless: cron has no terminal, so an interactive session never ran.
             lines.push(`# Invoke agent: ${job.agent}`);
-            lines.push(`claude --agent ${job.agent}`);
+            lines.push(`claude -p "Run your scheduled task (${job.id})." --agent ${job.agent}`);
         }
         else if (job.action) {
             lines.push(`# Invoke action: ${job.action}`);
-            lines.push(`bash scripts/action-${job.action}.sh`);
+            lines.push(`bash .claude/skills/${ast.topology.name}/scripts/action-${job.action}.sh`);
         }
         if (job.enabled === false) {
             lines.unshift("# DISABLED — this schedule is not enabled");
@@ -2245,18 +2595,12 @@ function generateScheduleScripts(ast) {
         // Add crontab entry
         let cronExpr = job.cron ?? "# every: " + (job.every ?? "unknown");
         if (!job.cron && job.every) {
-            // Convert common "every" expressions to cron
-            const everyMap = {
-                "1h": "0 * * * *",
-                "1 hour": "0 * * * *",
-                "hourly": "0 * * * *",
-                "1d": "0 0 * * *",
-                "1 day": "0 0 * * *",
-                "daily": "0 0 * * *",
-                "1w": "0 0 * * 0",
-                "weekly": "0 0 * * 0",
-            };
-            cronExpr = everyMap[job.every.toLowerCase()] ?? `# every: ${job.every}`;
+            const converted = everyToCron(job.every);
+            if (!converted) {
+                console.warn(`[claude-code] Schedule "${job.id}" every: ${job.every} has no cron form; ` +
+                    `its crontab line is commented out. Use cron: instead.`);
+            }
+            cronExpr = converted ?? `# every: ${job.every}`;
         }
         const enabledPrefix = job.enabled === false ? "# DISABLED: " : "";
         cronLines.push(`${enabledPrefix}${cronExpr} bash ${scriptPath}  # ${job.id}`);
@@ -2424,7 +2768,11 @@ function generateWorkspaceProtocol(ast) {
  * destroy their content.
  */
 function generateContextFile(ast) {
-    const DEFAULT_PATH = ".claude/CLAUDE.md";
+    // A rules file, one per topology: Claude Code loads .claude/rules/*.md like
+    // CLAUDE.md, so the context still reaches every session, but it never
+    // competes with the project's own CLAUDE.md or .claude/CLAUDE.md (it used to
+    // be written to .claude/CLAUDE.md, a conflict in any project that had one).
+    const DEFAULT_PATH = `.claude/rules/${ast.topology.name}.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") {
@@ -2621,7 +2969,7 @@ function generateWorkflowLaunchArtifacts(ast) {
 }
 /**
  * HYBRID: build the "Hybrid run order" markdown block appended to the generated
- * context file (.claude/CLAUDE.md) and the topology SKILL.md. It states the
+ * context file (.claude/rules/<topology>.md) and the topology SKILL.md. It states the
  * host's interleaving with the embedded workflow rung, in the SAME run-order
  * vocabulary the claude-workflow binding's SEAM.md uses, so the two bindings
  * stay in sync. Returns null when the topology is not a hybrid.
@@ -2738,49 +3086,28 @@ function generateObserveBlackboardScript(ast) {
 /**
  * Merge `ast.env` into the settings.json output under an `env` key.
  *
- * When `ast.providers` includes an "anthropic" provider with an api-key,
- * that env var is included automatically (enabling API-key mode instead
- * of subscription mode).
+ * Claude Code applies settings `env` values exactly as written — no shell
+ * expands them — and they override the variable exported in the shell. So a
+ * reference such as `${ANTHROPIC_API_KEY}` must never be emitted: it replaced
+ * the real key with that literal text, and every session in the project failed
+ * with "Invalid API key" (6 of the 10 examples did this). Only literal values
+ * are written; references, secrets and encrypted values stay with the shell.
+ * The anthropic provider's api-key is the same kind of reference and is not
+ * emitted either.
  *
  * Returns the env record if non-empty, otherwise null.
  */
 function generateEnvToSettings(ast) {
     const env = {};
     for (const [key, val] of Object.entries(ast.env)) {
-        if (typeof val === "string") {
-            env[key] = val;
-        }
-        else {
-            const sv = val;
-            if (sv.secretRef) {
-                // Secret reference — emit placeholder with comment-style URI
-                env[key] = `\${${key}}`; // placeholder
-                env[`# ${key}_SECRET`] = sv.secretRef.uri;
-            }
-            else if (sv.sensitive) {
-                // Sensitive value — never emit the actual value
-                env[key] = `\${${key}}`;
-            }
-            else if (sv.encrypted) {
-                // Encrypted value — emit placeholder with warning
-                env[key] = `\${${key}}`;
-                env[`# ${key}_ENCRYPTED`] = "WARNING: value is SOPS-encrypted, decrypt before use";
-            }
-            else {
-                env[key] = sv.value;
-            }
-        }
-    }
-    // If an anthropic provider exists, scaffold the API key env var
-    if (ast.providers && ast.providers.length > 0) {
-        const anthropicProvider = ast.providers.find((p) => p.name === "anthropic");
-        if (anthropicProvider?.apiKey) {
-            // Extract env var name from ${ENV_VAR} format
-            const envVarMatch = anthropicProvider.apiKey.match(/^\$\{(.+)\}$/);
-            if (envVarMatch) {
-                env[envVarMatch[1]] = anthropicProvider.apiKey;
-            }
-        }
+        const literal = typeof val === "string"
+            ? val
+            : val.secretRef || val.sensitive || val.encrypted
+                ? undefined
+                : val.value;
+        if (literal === undefined || literal.includes("${"))
+            continue;
+        env[key] = literal;
     }
     if (Object.keys(env).length === 0)
         return null;
@@ -2804,6 +3131,80 @@ function generateTriggers(ast) {
 // Binding export
 // ---------------------------------------------------------------------------
 /** Claude Code binding — the reference binding implementation. */
+/**
+ * Drop every generated file that belongs to a hand-written node (`file:`).
+ *
+ * An authored node keeps its file (a group also its skill and runtime
+ * folder); an authored skill keeps its whole folder
+ * (SKILL.md, scripts, references); an authored command keeps its file. The
+ * topology still describes them — gates still wire to an authored agent by
+ * name — but the binding never writes inside them. Without this, importing a
+ * hand-built .claude and scaffolding it back replaced 37 of 72 files and cut
+ * the rest down (a 404-line SKILL.md came back as 9 lines).
+ */
+function withoutAuthored(ast, files) {
+    const exact = new Set();
+    const folders = [];
+    for (const node of ast.nodes) {
+        if (!node.file)
+            continue;
+        // Everything the binding would write for this node: its agent file, and
+        // for a group its skill and its runtime folder.
+        exact.add(`.claude/agents/${node.id}/AGENT.md`);
+        exact.add(`.claude/agents/${node.id}.md`);
+        exact.add(normalizeRel(node.file));
+        if (node.type === "group") {
+            folders.push(`.claude/skills/${node.id}/`, `.claude/groups/${node.id}/`);
+        }
+    }
+    for (const skill of ast.skills ?? []) {
+        if (!skill.file)
+            continue;
+        folders.push(`.claude/skills/${skill.id}/`);
+        exact.add(normalizeRel(skill.file));
+    }
+    for (const trigger of ast.triggers ?? []) {
+        if (!trigger.file)
+            continue;
+        exact.add(`.claude/commands/${trigger.name}.md`);
+        exact.add(normalizeRel(trigger.file));
+    }
+    if (exact.size === 0 && folders.length === 0)
+        return files;
+    const isAuthored = (path) => {
+        const p = normalizeRel(path);
+        return exact.has(p) || folders.some((dir) => p.startsWith(dir));
+    };
+    const dropped = files.filter((f) => isAuthored(f.path)).map((f) => normalizeRel(f.path));
+    return files
+        .filter((f) => !isAuthored(f.path))
+        .map((f) => (/(^|\/)\.claude\/settings\.json$/.test(f.path) ? withoutHooksRunning(f, dropped) : f));
+}
+/**
+ * settings.json without the hook groups that run a script this scaffold no
+ * longer writes. A gate whose wrapper sits in an authored skill folder would
+ * otherwise be wired to a file that does not exist, and fire on every stop.
+ */
+function withoutHooksRunning(file, dropped) {
+    if (dropped.length === 0)
+        return file;
+    const settings = JSON.parse(file.content);
+    if (!settings.hooks)
+        return file;
+    for (const [event, groups] of Object.entries(settings.hooks)) {
+        const kept = groups.filter((g) => !(g.hooks ?? []).some((h) => dropped.some((p) => (h.command ?? "").includes(p))));
+        if (kept.length > 0)
+            settings.hooks[event] = kept;
+        else
+            delete settings.hooks[event];
+    }
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    return { ...file, content: JSON.stringify(settings, null, 2) + "\n" };
+}
+function normalizeRel(p) {
+    return p.replace(/^\.\//, "");
+}
 export const claudeCodeBinding = {
     name: "claude-code",
     description: "Anthropic Claude Code CLI — generates .claude/ directory structure, .mcp.json, and scripts.",
@@ -2815,7 +3216,7 @@ export const claudeCodeBinding = {
             files.push(...generateTopologySkill(ast));
             files.push(...generateAgents(ast));
             files.push(...generateSchemas(ast));
-            return deduplicateFiles(files);
+            return withoutAuthored(ast, deduplicateFiles(files));
         }
         const files = [];
         // Action nodes
@@ -2825,7 +3226,6 @@ export const claudeCodeBinding = {
         // Agent files — may include group conversation protocol sections
         files.push(...generateAgents(ast));
         // Human nodes
-        files.push(...generateHumanNodes(ast));
         // Main topology skill (with frontmatter)
         const skillFiles = generateTopologySkill(ast);
         // Append trigger info to the main skill
@@ -2844,10 +3244,15 @@ export const claudeCodeBinding = {
         // Gate scripts
         files.push(...generateGateScripts(ast));
         files.push(...generateGateWrapperScripts(ast));
+        const beforeAgent = generateBeforeAgentScript(ast);
+        if (beforeAgent)
+            files.push(beforeAgent);
         // Hook scripts (global)
         files.push(...generateHookScripts(ast));
         // Hook scripts (per-agent)
         files.push(...generateAgentHookScripts(ast));
+        // Mods (type: mod) → a plugin directory; never settings.json
+        files.push(...generateModPlugin(ast));
         // HYBRID: host-side launch directives for the embedded workflow rung(s).
         files.push(...generateWorkflowLaunchArtifacts(ast));
         // HYBRID: host-layer concurrent Blackboard observer script (paired with the
@@ -2879,7 +3284,7 @@ export const claudeCodeBinding = {
             files.push(meteringFile);
         // Context file (.claude/CONTEXT.md or custom — never root CLAUDE.md)
         files.push(generateContextFile(ast));
-        return deduplicateFiles(files);
+        return withoutAuthored(ast, deduplicateFiles(files));
     },
 };
 //# sourceMappingURL=claude-code.js.map