agentopology 0.2.0 → 0.2.1

package/dist/bindings/claude-code.js

@@ -48,6 +48,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,7 +67,10 @@ 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("---");
@@ -93,10 +98,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 +111,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 +236,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 +244,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 +843,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 +860,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 +886,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 +912,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 +1229,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 +1241,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 +1441,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,11 +1454,13 @@ 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 contentLines = [
             "#!/usr/bin/env bash",
             `# Gate wrapper: ${gate.id}`,
-            `# Enforces gate "${gate.id}" on Task tool calls.`,
+            `# Enforces gate "${gate.id}" on SubagentStop (after: ${gate.after || "any"}).`,
             `# Auto-generated by agentopology scaffold — edit as needed.`,
             "set -euo pipefail",
             "",
@@ -1601,14 +1610,17 @@ 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
+    // Gates fire AFTER an agent finishes (SubagentStop), not before a tool runs.
+    // The matcher is the gate's `after:` agent name so the hook fires when that
+    // specific agent completes.
     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";
+        const eventName = "SubagentStop";
         if (!hooksByEvent[eventName])
             hooksByEvent[eventName] = [];
         const scriptName = `gate-${gate.id}.sh`;
@@ -1620,8 +1632,12 @@ function generateSettings(ast) {
                     command,
                 },
             ],
-            matcher: "Task", // Gates fire on Task tool (agent spawning)
         };
+        // Use the gate's after: agent as matcher so the hook only fires
+        // when that specific agent completes. Without after:, match all agents.
+        if (gate.after) {
+            hookEntry.matcher = gate.after;
+        }
         hooksByEvent[eventName].push(hookEntry);
     }
     // Write hooksByEvent to settings if any hooks or gates were registered
@@ -1633,66 +1649,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 +1926,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 +2049,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") {