agentopology 0.5.2 → 0.6.0

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

@@ -6,7 +6,58 @@
  *
  * @module
  */
+import type { TopologyAST } from "../parser/ast.js";
 import type { BindingTarget } from "./types.js";
-/** Claude Code binding — the reference binding implementation. */
+/**
+ * `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 declare const MOD_PLUGIN_ENV = "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS";
+export declare 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 declare function modPluginDir(ast: TopologyAST): string | null;
+/**
+ * The shell command for a command hook's `run:`.
+ *
+ * A `run:` whose script (its first word, or its second when the first names
+ * the interpreter, e.g. `/opt/homebrew/bin/python3 ./x/y.py`) starts with "."
+ * or "/" 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), with its arguments kept.
+ *
+ * Any other `run:` is a script this topology's skill scaffolds, by basename.
+ */
+export declare function hookCommand(run: string, topologyName: string): string;
+/**
+ * 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 declare function settingsHooksOf(ast: TopologyAST): Record<string, unknown[]>;
 export declare const claudeCodeBinding: BindingTarget;
 //# sourceMappingURL=claude-code.d.ts.map

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;AAo5F/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aAkG/B,CAAC"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EAkBZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AA01D/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,sCAAsC,CAAC;AAClE,eAAO,MAAM,SAAS,mBAAmB,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAQ5D;AA8KD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CA6C3E;AAqgCD,eAAO,MAAM,iBAAiB,EAAE,aAqG/B,CAAC"}

package/dist/bindings/claude-code.js

@@ -11,6 +11,7 @@ import { shellStub, STUB_MARKER } from "./lib/stub.js";
 import { isWorkflowSeamAgent, seamFiles } from "./lib/seam.js";
 import { phaseOf as sharedPhaseOf } from "../resolve/phase.js";
 import { gateAnchors } from "../parser/ast.js";
+import { proseInRun, scriptNameFromRun } from "../parser/run.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -449,6 +450,8 @@ function generateAgents(ast) {
             const topologyName = ast.topology.name;
             const hooksByEvent = {};
             for (const hook of agent.hooks) {
+                if (hook.type === "mod")
+                    continue; // engine-wide only (V94)
                 if (!hooksByEvent[hook.on])
                     hooksByEvent[hook.on] = [];
                 hooksByEvent[hook.on].push(hook);
@@ -457,7 +460,9 @@ function generateAgents(ast) {
             for (const [eventName, hooks] of Object.entries(hooksByEvent)) {
                 hookLines.push(`  ${eventName}:`);
                 for (const hook of hooks) {
-                    const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+                    const scriptName = scriptNameFromRun(hook.run);
+                    if (!scriptName)
+                        continue; // V96: prose in run names no script
                     const command = `bash .claude/skills/${topologyName}/scripts/${agent.id}-${scriptName}`;
                     if (hook.matcher) {
                         hookLines.push(`    - matcher: "${hook.matcher}"`);
@@ -1641,9 +1646,8 @@ 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.*$/, "");
+        const scriptName = scriptNameFromRun(gate.run);
+        if (scriptName) {
             files.push({
                 path: `.claude/skills/${name}/scripts/${scriptName}`,
                 content: shellStub(`Gate: ${gate.id} — ${gate.run}`),
@@ -1665,7 +1669,9 @@ function generateGateWrapperScripts(ast) {
             continue;
         if (gate.behavior === "advisory")
             continue;
-        const gateScriptName = gate.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        const gateScriptName = scriptNameFromRun(gate.run);
+        if (!gateScriptName)
+            continue; // V96: prose in run names no script
         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`;
@@ -1790,6 +1796,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 +1920,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")
+            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 } = hookRun(runPath);
+        // An absolute script is the user's own, outside the project: never stubbed.
+        if (script.startsWith("/"))
+            continue;
+        const scoped = scriptNameFromRun(script);
+        const filePath = isHookPath(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.
+            ...(isHookPath(script) ? { createOnly: true } : {}),
         });
     }
     return files;
@@ -1824,9 +1965,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")
                 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: [
@@ -1844,19 +1987,54 @@ function generateAgentHookScripts(ast) {
     }
     return files;
 }
+const isHookPath = (w = "") => w.startsWith(".") || w.startsWith("/");
+/** A hook's `run:` split: the interpreter it names (if any), its script, its arguments. */
+function hookRun(run) {
+    const words = run.trim().split(/\s+/);
+    const named = words.length > 1 && !/\.(py|sh|ts|mjs|js)$/.test(words[0]) && isHookPath(words[1]);
+    const [script = "", ...args] = named ? words.slice(1) : words;
+    return { ...(named ? { interpreter: words[0] } : {}), script, args };
+}
 /**
- * Generate hook configuration in .claude/settings.json.
+ * The shell command for a command hook's `run:`.
  *
- * Hooks are grouped by event name as an object:
- *   { "hooks": { "PostToolUse": [ { hooks: [...], matcher? } ], ... } }
+ * A `run:` whose script (its first word, or its second when the first names
+ * the interpreter, e.g. `/opt/homebrew/bin/python3 ./x/y.py`) starts with "."
+ * or "/" 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), with its arguments 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 } = hookRun(run);
+    if (!isHookPath(first)) {
+        return `bash .claude/skills/${topologyName}/scripts/${first.replace(/^.*\//, "")}`;
+    }
+    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) {
+        // 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 = hook.on;
         // Inline orchestrator mode never spawns subagents, so SubagentStop /
         // SubagentStart hooks would never fire. Warn the user and skip emission
@@ -1868,24 +2046,16 @@ function generateSettings(ast) {
                 `delegation to "subagent".`);
             continue;
         }
+        if (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,
+                    command: hookCommand(hook.run, topologyName),
                     ...(hook.timeout ? { timeout: hook.timeout } : {}),
                 },
             ],
@@ -1896,6 +2066,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 +2110,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") {
@@ -2738,49 +2921,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 +2966,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 +3051,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
@@ -2848,6 +3084,8 @@ export const claudeCodeBinding = {
         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 +3117,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