agentopology 0.6.0 → 0.8.0

package/dist/parser/validator.js

@@ -1019,16 +1019,19 @@ function v96RunIsCommand(ast) {
             ...(nodeId ? { node: nodeId, line: lookupLine(ast, nodeId) } : {}),
         });
     };
+    // Only a command hook's run: is a command: a prompt or agent hook's run: is
+    // the prompt itself, and http, mcp_tool and mod hooks are checked by V100/V95.
+    const isCommand = (hook) => (hook.type ?? "command") === "command";
     for (const node of ast.nodes) {
         if (isGate(node))
             check(`Gate "${node.id}"`, node.run, node.id);
         if (node.type === "agent") {
-            for (const hook of node.hooks ?? []) {
+            for (const hook of (node.hooks ?? []).filter(isCommand)) {
                 check(`Hook "${hook.name}" on agent "${node.id}"`, hook.run, node.id);
             }
         }
     }
-    for (const hook of ast.hooks ?? [])
+    for (const hook of (ast.hooks ?? []).filter(isCommand))
         check(`Hook "${hook.name}"`, hook.run);
     return results;
 }
@@ -1062,6 +1065,127 @@ function v97FileIsProjectPath(ast) {
         check(`Command "${trigger.name}"`, trigger.file);
     return results;
 }
+/**
+ * Claude Code events that take only command, http and mcp_tool hooks (no
+ * prompt or agent judge), and the two that take only command and mcp_tool.
+ * From the hooks reference, 2026-10-30.
+ */
+const NO_JUDGE_EVENTS = new Set([
+    "ConfigChange", "CwdChanged", "DirectoryAdded", "Elicitation", "ElicitationResult", "FileChanged",
+    "InstructionsLoaded", "MessageDisplay", "Notification", "PostCompact", "PostModelSwitch", "PreCompact",
+    "PreModelSwitch", "SessionEnd", "StopFailure", "SubagentStart", "WorktreeCreate", "WorktreeRemove",
+    "AgentStart",
+]);
+const COMMAND_OR_MCP_EVENTS = new Set(["SessionStart", "Setup"]);
+/**
+ * V100: a hook has what its type needs, on an event that takes that type.
+ *
+ * A command needs run:, a prompt or agent hook needs run: (the prompt), an
+ * http hook url:, an mcp_tool hook server: and tool:. A prompt or agent judge
+ * on an event Claude Code runs only command hooks for never fires.
+ */
+function v100HookTypeFields(ast) {
+    const results = [];
+    for (const { hook, where } of allHooks(ast)) {
+        const type = hook.type ?? "command";
+        if (type === "mod")
+            continue; // V95
+        const err = (message) => results.push({ rule: "V100", level: "error", message: `Hook "${where}" ${message}`, node: where });
+        if ((type === "command" || type === "prompt" || type === "agent") && !hook.run) {
+            err(`is type ${type} but has no run: — ${type === "command" ? "name the command" : "write the prompt in run:"}.`);
+        }
+        if (type === "http" && !hook.url)
+            err(`is type http but has no url: — name the endpoint the event is sent to.`);
+        if (type === "mcp_tool" && (!hook.server || !hook.tool))
+            err(`is type mcp_tool but needs server: and tool:.`);
+        if (type !== "command" && hook.async !== undefined)
+            err(`sets async: but is type ${type} — async: belongs to a command hook.`);
+        const on = hook.on.trim();
+        if ((type === "prompt" || type === "agent") && NO_JUDGE_EVENTS.has(on)) {
+            err(`is a ${type} hook on ${on}, which Claude Code runs only command, http and mcp_tool hooks for — it would never fire.`);
+        }
+        else if ((type === "prompt" || type === "agent" || type === "http") && COMMAND_OR_MCP_EVENTS.has(on)) {
+            err(`is a ${type} hook on ${on}, which takes only command and mcp_tool hooks — it would never fire.`);
+        }
+    }
+    return results;
+}
+/**
+ * V101: a node's run-mode is one Claude Code has, and an independent node
+ * does not share its caller's context.
+ *
+ * runs: subagent (own agent), inline (a skill in the caller's context) or
+ * fork (a skill in a fresh forked context). An independent critic running
+ * inline would read the author's reasoning, which is what independent forbids.
+ */
+const RUN_MODES = ["subagent", "inline", "fork"];
+function v101RunMode(ast) {
+    const results = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "agent")
+            continue;
+        const agent = node;
+        if (agent.runs !== undefined && !RUN_MODES.includes(agent.runs)) {
+            results.push({
+                rule: "V101", level: "error", node: agent.id, line: lookupLine(ast, agent.id),
+                message: `Agent "${agent.id}" has runs: ${agent.runs} — a node runs as ${RUN_MODES.join(", ")}.`,
+            });
+        }
+        if (agent.independent && agent.runs === "inline") {
+            results.push({
+                rule: "V101", level: "error", node: agent.id, line: lookupLine(ast, agent.id),
+                message: `Agent "${agent.id}" is independent but runs inline, in its caller's context, where it reads the author's reasoning. Use runs: fork or runs: subagent.`,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * V98: a block that belongs inside a container is not written beside it.
+ *
+ * `gate x { }` outside `gates { }` (likewise hook, tool, job, command, level)
+ * was dropped by the parser with no message. Collected at parse time.
+ */
+function v98BlockInsideItsContainer(ast) {
+    return ast._misplacedBlockErrors ?? [];
+}
+/**
+ * V99: an agent's `skills:` and `mcp-servers:`, and a skill's `agent:`, name
+ * something this topology declares.
+ *
+ * A misspelled name compiled to a reference Claude Code could not resolve,
+ * with no message. A warning, not an error: the name may be real outside the
+ * topology (a skill on disk, a user-level MCP server, a built-in agent).
+ */
+const BUILT_IN_AGENTS = new Set(["general-purpose", "Explore", "Plan"]);
+function v99ReferencesDeclared(ast) {
+    const results = [];
+    const skills = new Set([ast.topology.name, ...(ast.skills ?? []).map((s) => s.id)]);
+    const servers = new Set([...Object.keys(ast.mcpServers ?? {}), ...(ast.stores ?? []).map((s) => s.id)]);
+    const agents = new Set(ast.nodes.filter((n) => n.type === "agent" || n.type === "group").map((n) => n.id));
+    const warn = (message, nodeId) => results.push({ rule: "V99", level: "warning", message, ...(nodeId ? { node: nodeId, line: lookupLine(ast, nodeId) } : {}) });
+    for (const node of ast.nodes) {
+        if (node.type !== "agent")
+            continue;
+        const agent = node;
+        for (const skill of agent.skills ?? []) {
+            if (!skills.has(skill)) {
+                warn(`Agent "${agent.id}" uses skill "${skill}", which this topology does not declare — scaffold writes no SKILL.md for it. If it is hand-written, declare skill ${skill} { file: ".claude/skills/${skill}/SKILL.md" }; otherwise check the name`, agent.id);
+            }
+        }
+        for (const server of agent.mcpServers ?? []) {
+            if (!servers.has(server)) {
+                warn(`Agent "${agent.id}" uses MCP server "${server}", which mcp-servers { } does not declare — it resolves only if configured outside this project`, agent.id);
+            }
+        }
+    }
+    for (const skill of ast.skills ?? []) {
+        if (skill.agent && !agents.has(skill.agent) && !BUILT_IN_AGENTS.has(skill.agent)) {
+            warn(`Skill "${skill.id}" runs in agent "${skill.agent}", which is not an agent in this topology or a built-in one (${[...BUILT_IN_AGENTS].join(", ")})`);
+        }
+    }
+    return results;
+}
 function v93EdgeHandoffDeclared(ast) {
     const results = [];
     const byId = new Map(ast.nodes.map((n) => [n.id, n]));
@@ -3030,7 +3154,7 @@ export const MOD_EVENTS_SEEN = [
     "prompt.context", "session.start", "session.end", "model.complete", "message.received",
 ];
 /** Hook types the grammar defines (`spec/grammar.md` §4.16). */
-export const HOOK_TYPES = ["command", "prompt", "mod"];
+export const HOOK_TYPES = ["command", "prompt", "agent", "http", "mcp_tool", "mod"];
 /** Every hook in the topology — global first, then per-agent — with its owner. */
 function allHooks(ast) {
     const out = ast.hooks.map((hook) => ({ hook, where: hook.name }));
@@ -3186,6 +3310,10 @@ export function validate(ast) {
         ...v95HookEventKnown(ast),
         ...v96RunIsCommand(ast),
         ...v97FileIsProjectPath(ast),
+        ...v98BlockInsideItsContainer(ast),
+        ...v99ReferencesDeclared(ast),
+        ...v100HookTypeFields(ast),
+        ...v101RunMode(ast),
         ...v25BounceBackAdvisory(ast),
         ...v26ActionKindEnum(ast),
         ...v27AgentPermissionsEnum(ast),