agentopology 0.5.2 → 0.7.0

package/dist/parser/paths.js

@@ -0,0 +1,34 @@
+/**
+ * Which project-relative paths are safe to write or to name as a node's file.
+ *
+ * Shared by scaffold (every generated path) and the validator (every `file:`),
+ * so a path the language accepts is a path scaffold can honour.
+ *
+ * @module
+ */
+/** One path segment a binding may produce. Junk like `E;`, `fail:`, `x)` fails. */
+const SAFE_SEGMENT = /^[A-Za-z0-9_.@+-]+$/;
+/**
+ * Why a generated relative path is unsafe to write, or null when it is fine.
+ *
+ * @param relPath - Path relative to the project root, as a binding emits it
+ */
+export function unsafePathReason(relPath) {
+    if (relPath.trim() === "")
+        return "empty path";
+    if (relPath.endsWith("/"))
+        return "ends in '/' (no file name)";
+    if (relPath.startsWith("/"))
+        return "absolute path";
+    const segments = relPath.split("/");
+    for (const seg of segments) {
+        if (seg === "")
+            return "empty path segment";
+        if (seg === "..")
+            return "climbs out of the project ('..')";
+        if (!SAFE_SEGMENT.test(seg))
+            return `unsafe name "${seg}"`;
+    }
+    return null;
+}
+//# sourceMappingURL=paths.js.map

package/dist/parser/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/parser/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,YAAY,CAAC;IAC/C,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,4BAA4B,CAAC;IAC/D,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,eAAe,CAAC;IACpD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,oBAAoB,CAAC;QAC5C,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,kCAAkC,CAAC;QAC5D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,gBAAgB,GAAG,GAAG,CAAC;IAC7D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/parser/run.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What a `run:` value is allowed to be: a command, not a sentence.
+ *
+ * A gate or hook `run` names something to execute. Bindings derive a script
+ * file name from it, so prose there became files named `E;`, `fail:` and
+ * `outputs.py)` — and a " / " in a sentence produced an empty name that
+ * crashed scaffold with EISDIR. Both the validator (V96) and every binding go
+ * through these two functions so they cannot disagree.
+ *
+ * @module
+ */
+/**
+ * A `run:` split into the interpreter it names (if any), its script, and the
+ * script's arguments. The script is the first word, or the second when the
+ * first is an interpreter (`python3 x.py`, `/opt/homebrew/bin/python3 ./y.py`).
+ *
+ * The script name used to be the text after the LAST slash of the whole line,
+ * so an argument became the script: `python3 tool.py check show/SLUG` planned
+ * a stub named `SLUG`, and `pxframes.py gate OUT/frames-critic.json` one named
+ * `frames-critic.json`.
+ */
+export declare function runParts(run: string): {
+    interpreter?: string;
+    script: string;
+    args: string[];
+};
+/**
+ * Whether a script word names a file in the project (run where it is) rather
+ * than one in the topology skill's scripts/ folder (scaffolded by basename).
+ * `./x`, `/x` and any path with a folder count, except the historical
+ * `scripts/x.sh`, which has always meant the skill's own scripts folder.
+ */
+export declare function isProjectPath(script?: string): boolean;
+/**
+ * The script file name a binding writes for `run`, or null when `run` does not
+ * name one: the basename of the script word (see runParts).
+ */
+export declare function scriptNameFromRun(run: string | undefined): string | null;
+/**
+ * Why `run` reads as prose rather than a command, or null when it looks like a
+ * command. Deliberately conservative: it flags only what a shell would reject
+ * or what no command contains, so real commands are never refused.
+ */
+export declare function proseInRun(run: string): string | null;
+//# sourceMappingURL=run.d.ts.map

package/dist/parser/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/parser/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAU9F;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAK,GAAG,OAAO,CAGlD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBrD"}

package/dist/parser/run.js

@@ -0,0 +1,91 @@
+/**
+ * What a `run:` value is allowed to be: a command, not a sentence.
+ *
+ * A gate or hook `run` names something to execute. Bindings derive a script
+ * file name from it, so prose there became files named `E;`, `fail:` and
+ * `outputs.py)` — and a " / " in a sentence produced an empty name that
+ * crashed scaffold with EISDIR. Both the validator (V96) and every binding go
+ * through these two functions so they cannot disagree.
+ *
+ * @module
+ */
+/** One path-ish token: optional ./ ../ ~/ or / prefix, then safe characters (dotfolders such as .claude/ included). */
+const EXECUTABLE = /^(?:\.{1,2}\/|~\/|\/)?[A-Za-z0-9_.][A-Za-z0-9_.\/@+-]*$/;
+/** A file name a binding may write under its scripts/ directory. */
+const SCRIPT_FILE = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+/** Words that run the script named after them. */
+const INTERPRETER = /^(?:python[0-9.]*|bash|sh|zsh|node|bun|deno|ruby|perl|tsx)$/;
+const SCRIPT_EXT = /\.(?:py|sh|ts|mjs|js)$/;
+/**
+ * A `run:` split into the interpreter it names (if any), its script, and the
+ * script's arguments. The script is the first word, or the second when the
+ * first is an interpreter (`python3 x.py`, `/opt/homebrew/bin/python3 ./y.py`).
+ *
+ * The script name used to be the text after the LAST slash of the whole line,
+ * so an argument became the script: `python3 tool.py check show/SLUG` planned
+ * a stub named `SLUG`, and `pxframes.py gate OUT/frames-critic.json` one named
+ * `frames-critic.json`.
+ */
+export function runParts(run) {
+    const words = run.trim().split(/\s+/);
+    const first = words[0] ?? "";
+    const named = words.length > 1 &&
+        !words[1].startsWith("-") && // `bash -c '...'` runs no script file
+        !SCRIPT_EXT.test(first) &&
+        (INTERPRETER.test(first.replace(/^.*\//, "")) || isProjectPath(words[1]));
+    const [script = "", ...args] = named ? words.slice(1) : words;
+    return { ...(named ? { interpreter: first } : {}), script, args };
+}
+/**
+ * Whether a script word names a file in the project (run where it is) rather
+ * than one in the topology skill's scripts/ folder (scaffolded by basename).
+ * `./x`, `/x` and any path with a folder count, except the historical
+ * `scripts/x.sh`, which has always meant the skill's own scripts folder.
+ */
+export function isProjectPath(script = "") {
+    if (script.startsWith(".") || script.startsWith("/"))
+        return true;
+    return script.includes("/") && !script.startsWith("scripts/");
+}
+/**
+ * The script file name a binding writes for `run`, or null when `run` does not
+ * name one: the basename of the script word (see runParts).
+ */
+export function scriptNameFromRun(run) {
+    if (!run)
+        return null;
+    // A slash standing alone is prose ("0.0 / 0.5 / 3.0 s"), never a path.
+    if (/\s\/\s/.test(run))
+        return null;
+    const name = runParts(run).script.replace(/^.*\//, "");
+    return SCRIPT_FILE.test(name) ? name : null;
+}
+/**
+ * Why `run` reads as prose rather than a command, or null when it looks like a
+ * command. Deliberately conservative: it flags only what a shell would reject
+ * or what no command contains, so real commands are never refused.
+ */
+export function proseInRun(run) {
+    const text = run.trim();
+    if (text === "")
+        return "it is empty";
+    if (/\r|\n/.test(text))
+        return "it spans several lines";
+    const first = text.split(/\s+/)[0];
+    if (/[:;,]$/.test(first))
+        return `its first word "${first}" ends in punctuation`;
+    if (!EXECUTABLE.test(first))
+        return `its first word "${first}" is not a command or path`;
+    // Judge only what the shell would see unquoted.
+    const bare = text.replace(/'[^']*'|"[^"]*"/g, "''");
+    if (/[^\x00-\x7F]/.test(bare))
+        return "it contains non-ASCII text outside quotes";
+    if (/\s->\s|\s=>\s|\s<=\s|\s>=\s/.test(bare))
+        return "it contains an arrow or comparison (->, >=, <=)";
+    if (/(^|[^$])\(/.test(bare))
+        return "it contains an unquoted parenthesis";
+    if (scriptNameFromRun(text) === null)
+        return "no script file name can be derived from it";
+    return null;
+}
+//# sourceMappingURL=run.js.map

package/dist/parser/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/parser/run.ts"],"names":[],"mappings":"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"}

package/dist/parser/validator.d.ts

@@ -44,5 +44,17 @@ export declare function findBackEdges(edges: EdgeDef[], nodeIds: Set<string>): E
  * @param ast - The parsed topology AST.
  * @returns An array of validation results. An empty array means no issues found.
  */
+/**
+ * Engine events a `type: mod` hook may subscribe to (Claude Code function
+ * hooks, early access, CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1).
+ *
+ * PROVEN: a Mod was loaded and fired on these (Claude Code 2.1.283).
+ * SEEN: the name is in the 2.1.283 binary but no Mod has been observed on it,
+ * so V95 accepts it with a warning rather than an error.
+ */
+export declare const MOD_EVENTS_PROVEN: readonly ["tool.call", "prompt.submit"];
+export declare const MOD_EVENTS_SEEN: readonly ["prompt.context", "session.start", "session.end", "model.complete", "message.received"];
+/** Hook types the grammar defines (`spec/grammar.md` §4.16). */
+export declare const HOOK_TYPES: readonly ["command", "prompt", "mod"];
 export declare function validate(ast: TopologyAST): ValidationResult[];
 //# sourceMappingURL=validator.d.ts.map

package/dist/parser/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/parser/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EACV,WAAW,EAKX,OAAO,EAkBR,MAAM,UAAU,CAAC;AAMlB,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAyMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,EAAE,CAyD/E;AAo0FD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB,EAAE,CAgG7D"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/parser/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAEV,WAAW,EAKX,OAAO,EAkBR,MAAM,UAAU,CAAC;AAMlB,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAyMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,EAAE,CAyD/E;AAi8FD;;;;;GAKG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,yCAA0C,CAAC;AACzE,eAAO,MAAM,eAAe,mGAElB,CAAC;AAEX,gEAAgE;AAChE,eAAO,MAAM,UAAU,uCAAwC,CAAC;AAyHhE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB,EAAE,CAsG7D"}

package/dist/parser/validator.js

@@ -20,6 +20,8 @@
  */
 import { MISSING } from "./index.js";
 import { gateAnchors } from "./ast.js";
+import { proseInRun } from "./run.js";
+import { unsafePathReason } from "./paths.js";
 // ---------------------------------------------------------------------------
 // Reserved keywords (from spec section 7)
 // ---------------------------------------------------------------------------
@@ -489,7 +491,7 @@ function v10PromptsExist(ast) {
     }
     return results;
 }
-/** V11: If agent A writes X and agent B reads X, a path A -> B must exist in flow. */
+/** V11: If agent A writes X and agent B reads X, a path A -> B must exist in flow (unless either runs on demand). */
 function v11ReadWriteConsistency(ast) {
     const results = [];
     // Build a reachability map using BFS from each node
@@ -554,7 +556,16 @@ function v11ReadWriteConsistency(ast) {
             const keyWriters = writers.get(key);
             if (!keyWriters)
                 continue; // no writer = could be external, skip
-            const hasPath = keyWriters.some((writerId) => isReachable(writerId, node.id) ||
+            // An on-demand agent (invocation: manual) sits outside the flow by
+            // definition (V4), so no flow path can exist to or from it — the order
+            // is the user's. Demanding one made every hand-built project, whose
+            // subagents are all on demand, fail on import.
+            const manual = (id) => {
+                const n = ast.nodes.find((x) => x.id === id);
+                return !!n && isAgent(n) && n.invocation === "manual";
+            };
+            const hasPath = manual(node.id) || keyWriters.some((writerId) => manual(writerId) ||
+                isReachable(writerId, node.id) ||
                 (coGroupMembers.get(node.id)?.has(writerId) ?? false));
             if (!hasPath) {
                 results.push({
@@ -984,6 +995,121 @@ function v91RequiredFieldPlaceholder(ast) {
  * `handoff-overlap-empty` pre-flagged ambiguity; having it here makes it work
  * under `scaffold` too, and for anyone who never runs `plan`.
  */
+/**
+ * V96: a `run:` value is a command, not a sentence.
+ *
+ * Gates and hooks compile to scripts named after their `run`. Prose there
+ * passed validation, then scaffold wrote junk files named `E;` and `fail:`
+ * and crashed with EISDIR on a " / " — after it had already written other
+ * files. The explanation belongs in `description`; `run` keeps the command.
+ */
+function v96RunIsCommand(ast) {
+    const results = [];
+    const check = (owner, run, nodeId) => {
+        if (run === undefined)
+            return;
+        const why = proseInRun(run);
+        if (!why)
+            return;
+        results.push({
+            rule: "V96",
+            level: "error",
+            message: `${owner} "run" is not a command — ${why}. Keep only the command in ` +
+                `"run" (e.g. run: "scripts/check.sh") and move the explanation into "description"`,
+            ...(nodeId ? { node: nodeId, line: lookupLine(ast, nodeId) } : {}),
+        });
+    };
+    // A prompt hook's run: is the prompt itself, so prose is what it should be.
+    const isCommand = (hook) => hook.type !== "prompt";
+    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 ?? []).filter(isCommand)) {
+                check(`Hook "${hook.name}" on agent "${node.id}"`, hook.run, node.id);
+            }
+        }
+    }
+    for (const hook of (ast.hooks ?? []).filter(isCommand))
+        check(`Hook "${hook.name}"`, hook.run);
+    return results;
+}
+/**
+ * V97: a `file:` is a safe project-relative path.
+ *
+ * `file:` marks a node's internals as hand-written at that path; scaffold
+ * never writes it. A path outside the project ('..', absolute) or with an
+ * unsafe name could not be honoured, so it is refused here, not at scaffold.
+ */
+function v97FileIsProjectPath(ast) {
+    const results = [];
+    const check = (owner, file, nodeId) => {
+        if (file === undefined)
+            return;
+        const why = unsafePathReason(file.replace(/^\.\//, ""));
+        if (!why)
+            return;
+        results.push({
+            rule: "V97",
+            level: "error",
+            message: `${owner} "file" is not a project-relative path — ${why}. Name the file from the project root, e.g. file: ".claude/agents/reviewer.md"`,
+            ...(nodeId ? { node: nodeId, line: lookupLine(ast, nodeId) } : {}),
+        });
+    };
+    for (const node of ast.nodes)
+        check(`Node "${node.id}"`, node.file, node.id);
+    for (const skill of ast.skills ?? [])
+        check(`Skill "${skill.id}"`, skill.file);
+    for (const trigger of ast.triggers ?? [])
+        check(`Command "${trigger.name}"`, trigger.file);
+    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]));
@@ -2939,6 +3065,140 @@ function v88CustodyRefsValid(ast) {
  * @param ast - The parsed topology AST.
  * @returns An array of validation results. An empty array means no issues found.
  */
+/**
+ * Engine events a `type: mod` hook may subscribe to (Claude Code function
+ * hooks, early access, CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1).
+ *
+ * PROVEN: a Mod was loaded and fired on these (Claude Code 2.1.283).
+ * SEEN: the name is in the 2.1.283 binary but no Mod has been observed on it,
+ * so V95 accepts it with a warning rather than an error.
+ */
+export const MOD_EVENTS_PROVEN = ["tool.call", "prompt.submit"];
+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"];
+/** 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 }));
+    for (const n of ast.nodes) {
+        if (n.type !== "agent" || !n.hooks)
+            continue;
+        for (const hook of n.hooks)
+            out.push({ hook, where: `${n.id}.${hook.name}`, agent: n.id });
+    }
+    return out;
+}
+/**
+ * V94: a hook's `type` must be one the grammar defines.
+ *
+ * `type: mod` passed silently before the grammar knew it, and the claude-code
+ * binding wrote it into settings.json as a bash command. A misspelt type
+ * (`type: comand`) did the same.
+ */
+function v94HookTypeKnown(ast) {
+    const results = [];
+    for (const { hook, where, agent } of allHooks(ast)) {
+        const type = hook.type ?? "command";
+        if (!HOOK_TYPES.includes(type)) {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" has type "${type}" — a hook is one of: ${HOOK_TYPES.join(", ")}. ` +
+                    `Use "mod" for a TypeScript module that runs inside the engine.`,
+                node: where,
+            });
+            continue;
+        }
+        if (type === "mod" && agent) {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" is a mod inside an agent — a Mod runs in the engine for the whole session; declare it in the topology's hooks block.`,
+                node: where,
+            });
+        }
+        if (hook.flag !== undefined && type !== "mod") {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" sets flag: but is type "${type}" — flag: is the env switch of a type: mod hook.`,
+                node: where,
+            });
+        }
+        else if (hook.flag !== undefined && !/^[A-Z_][A-Z0-9_]*$/.test(hook.flag)) {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" has flag "${hook.flag}" — a flag is an env variable name (e.g. MY_MOD_ON).`,
+                node: where,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * V95: a hook's `on:` must be an event its type can subscribe to.
+ *
+ * A mod subscribes to a dotted engine event (`tool.call`); a command or prompt
+ * hook to a PascalCase lifecycle event (`PreToolUse`, spec §4.16: "any
+ * identifier in PascalCase"). Mixing them is a hook that never fires. A value
+ * with whitespace is left to V90 (a swallowed field), not reported twice.
+ */
+function v95HookEventKnown(ast) {
+    const results = [];
+    const proven = MOD_EVENTS_PROVEN;
+    const seen = MOD_EVENTS_SEEN;
+    for (const { hook, where } of allHooks(ast)) {
+        const type = hook.type ?? "command";
+        const on = hook.on.trim();
+        if (/\s/.test(on))
+            continue; // V90
+        if (!on) {
+            results.push({ rule: "V95", level: "error", message: `Hook "${where}" has no on: — name the event it fires on.`, node: where });
+            continue;
+        }
+        if (type === "mod") {
+            if (!hook.run) {
+                results.push({ rule: "V95", level: "error", message: `Mod "${where}" has no run: — name its module (e.g. run: "hooks/redact.ts").`, node: where });
+            }
+            if (proven.includes(on))
+                continue;
+            if (seen.includes(on)) {
+                results.push({
+                    rule: "V95",
+                    level: "warning",
+                    message: `Mod "${where}" subscribes to "${on}" — the engine names this event, but no Mod has been observed firing on it. Proven: ${proven.join(", ")}.`,
+                    node: where,
+                });
+                continue;
+            }
+            const hint = /^[A-Z]/.test(on)
+                ? ` "${on}" is a command-hook event; a mod subscribes to an engine event.`
+                : "";
+            results.push({
+                rule: "V95",
+                level: "error",
+                message: `Mod "${where}" subscribes to unknown engine event "${on}".${hint} Engine events: ${[...proven, ...seen].join(", ")}.`,
+                node: where,
+            });
+            continue;
+        }
+        if (!/^[A-Z][A-Za-z0-9]*$/.test(on)) {
+            const hint = proven.includes(on) || seen.includes(on)
+                ? ` "${on}" is an engine event — set type: mod to subscribe a module to it.`
+                : "";
+            results.push({
+                rule: "V95",
+                level: "error",
+                message: `Hook "${where}" (type ${type}) fires on "${on}" — a ${type} hook takes a PascalCase event (e.g. PreToolUse, AgentStop).${hint}`,
+                node: where,
+            });
+        }
+    }
+    return results;
+}
 export function validate(ast) {
     return [
         ...v1UniqueNames(ast),
@@ -2970,6 +3230,12 @@ export function validate(ast) {
         ...v91RequiredFieldPlaceholder(ast),
         ...v92EdgeTwoBrackets(ast),
         ...v93EdgeHandoffDeclared(ast),
+        ...v94HookTypeKnown(ast),
+        ...v95HookEventKnown(ast),
+        ...v96RunIsCommand(ast),
+        ...v97FileIsProjectPath(ast),
+        ...v98BlockInsideItsContainer(ast),
+        ...v99ReferencesDeclared(ast),
         ...v25BounceBackAdvisory(ast),
         ...v26ActionKindEnum(ast),
         ...v27AgentPermissionsEnum(ast),