agentsmesh 0.33.0 → 0.35.0

package/dist/targets.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { stringify, parseDocument, parse, isMap, Document, isSeq, isScalar, Scalar, Pair, YAMLSeq } from 'yaml';
+import { existsSync, realpathSync, readFileSync, constants, statSync } from 'fs';
 import { basename, win32, posix, join, relative, dirname, extname } from 'path';
 import { readFile, readdir, mkdir, lstat, unlink, writeFile, rename, chmod, rm, realpath, stat, access } from 'fs/promises';
 import 'timers/promises';
-import { existsSync, realpathSync, readFileSync, constants, statSync } from 'fs';
 import { parse as parse$1, stringify as stringify$1 } from 'smol-toml';
 import { Buffer } from 'buffer';
 
@@ -86,8 +86,17 @@ var init_target_descriptor_schema = __esm({
     managedOutputsSchema = z.object({
       dirs: z.array(z.string()),
       files: z.array(z.string()),
-      coOwnedFiles: z.array(z.string()).optional()
+      coOwnedFiles: z.array(z.string()).optional(),
+      supersededFiles: z.array(z.string()).optional()
     }).passthrough().superRefine((value, ctx) => {
+      for (const file of value.supersededFiles ?? []) {
+        if (!value.files.includes(file) && !(value.coOwnedFiles ?? []).includes(file)) continue;
+        ctx.addIssue({
+          code: "custom",
+          path: ["supersededFiles"],
+          message: `"${file}" is in managedOutputs.supersededFiles and another managedOutputs list.`
+        });
+      }
       for (const file of value.coOwnedFiles ?? []) {
         if (!value.files.includes(file)) continue;
         ctx.addIssue({
@@ -375,24 +384,28 @@ var init_target_ids = __esm({
   }
 });
 function parseFrontmatter(content) {
-  const open = content.indexOf("---");
-  if (open !== 0) {
-    return { frontmatter: {}, body: content.trim() };
-  }
-  const close = content.indexOf("---", 3);
-  if (close === -1) {
-    return { frontmatter: {}, body: content.trim() };
-  }
-  const yamlStr = content.slice(3, close).trim();
-  const body = content.slice(close + 3).trim();
+  const split = splitFrontmatter(content);
+  if (split === null) return { frontmatter: {}, body: content.trim() };
+  const yamlStr = split.yaml.trim();
   const frontmatter = yamlStr === "" ? {} : parse(yamlStr) ?? {};
-  return { frontmatter, body };
+  return { frontmatter, body: split.body };
+}
+function splitFrontmatter(content) {
+  const opener = OPENER.exec(content);
+  if (opener === null) return null;
+  const yamlStart = opener[0].length;
+  const closer = CLOSER.exec(content.slice(yamlStart));
+  if (closer === null) return null;
+  const closeStart = yamlStart + closer.index;
+  const closeEnd = closeStart + closer[0].length;
+  return {
+    yaml: content.slice(yamlStart, closeStart),
+    body: content.slice(closeEnd).trim(),
+    prefix: content.slice(0, closeEnd)
+  };
 }
 function extractBody(content) {
-  if (content.indexOf("---") !== 0) return content.trim();
-  const close = content.indexOf("---", 3);
-  if (close === -1) return content.trim();
-  return content.slice(close + 3).trim();
+  return splitFrontmatter(content)?.body ?? content.trim();
 }
 function tryParseFrontmatter(content, filePath2) {
   try {
@@ -415,8 +428,11 @@ ${yamlStr}
 
 ${body}`;
 }
+var OPENER, CLOSER;
 var init_markdown = __esm({
   "src/utils/text/markdown.ts"() {
+    OPENER = /^---[ \t]*\r?\n/;
+    CLOSER = /^---[ \t]*\r?$/m;
   }
 });
 
@@ -476,11 +492,25 @@ var init_command_skill = __esm({
     LEGACY_CODEX_COMMAND_SKILL_PREFIX = "ab-command-";
   }
 });
+var RECALL_HOOK_COMMAND;
+var init_recall_hook_scaffold = __esm({
+  "src/lessons/recall-hook-scaffold.ts"() {
+    RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
+  }
+});
 
 // src/core/hook-types.ts
+function isBestEffortHookEvent(event, entries) {
+  if (!BEST_EFFORT_HOOK_EVENTS.has(event)) return false;
+  if (!Array.isArray(entries)) return true;
+  return entries.every(
+    (entry) => typeof entry === "object" && entry !== null && typeof entry.command === "string" && entry.command.includes(RECALL_HOOK_COMMAND)
+  );
+}
 var BEST_EFFORT_HOOK_EVENTS;
 var init_hook_types = __esm({
   "src/core/hook-types.ts"() {
+    init_recall_hook_scaffold();
     BEST_EFFORT_HOOK_EVENTS = /* @__PURE__ */ new Set([
       "UserPromptSubmit",
       "PostToolUseFailure",
@@ -666,7 +696,7 @@ var init_conf_merge = __esm({
 });
 
 // src/core/errors.ts
-var AgentsMeshError, FileSystemError;
+var AgentsMeshError, CanonicalParseError, FileSystemError;
 var init_errors = __esm({
   "src/core/errors.ts"() {
     AgentsMeshError = class extends Error {
@@ -677,6 +707,21 @@ var init_errors = __esm({
         this.code = code;
       }
     };
+    CanonicalParseError = class extends AgentsMeshError {
+      path;
+      constructor(path, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(
+          "AM_CONFIG_INVALID",
+          `Invalid canonical file ${path}: ${detail}. Fix the syntax and try again.`,
+          {
+            cause
+          }
+        );
+        this.name = "CanonicalParseError";
+        this.path = path;
+      }
+    };
     FileSystemError = class extends AgentsMeshError {
       path;
       errnoCode;
@@ -1172,6 +1217,7 @@ function extractEmbeddedRules(content) {
 var ROOT_CONTRACT_START, ROOT_CONTRACT_END, EMBEDDED_RULES_START, EMBEDDED_RULES_END, EMBEDDED_RULE_END, EMBEDDED_RULE_START_PREFIX, EMBEDDED_RULE_START_SUFFIX;
 var init_managed_blocks = __esm({
   "src/targets/projection/managed-blocks.ts"() {
+    init_markdown();
     ROOT_CONTRACT_START = "<!-- agentsmesh:root-generation-contract:start -->";
     ROOT_CONTRACT_END = "<!-- agentsmesh:root-generation-contract:end -->";
     EMBEDDED_RULES_START = "<!-- agentsmesh:embedded-rules:start -->";
@@ -1333,10 +1379,17 @@ async function serializeImportedCommandWithFallback(destinationPath, imported, b
   })();
   const description = imported.hasDescription ? imported.description ?? "" : typeof existingFrontmatter.description === "string" ? existingFrontmatter.description : "";
   const allowedTools = imported.hasAllowedTools ? imported.allowedTools ?? [] : existingAllowedTools;
+  const {
+    description: _d,
+    "allowed-tools": _a,
+    allowedTools: _c,
+    ...preserved
+  } = existingFrontmatter;
   return serializeFrontmatter(
     {
       description,
-      "allowed-tools": allowedTools
+      "allowed-tools": allowedTools,
+      ...preserved
     },
     body.trim() || ""
   );
@@ -2234,6 +2287,26 @@ var init_link_rebaser_resolution = __esm({
   }
 });
 
+// src/core/reference/link-uri-encoding.ts
+function decodeLinkPath(token, role) {
+  if (role !== "markdown-link-dest" || !token.includes("%")) return token;
+  try {
+    return decodeURIComponent(token);
+  } catch {
+    return token;
+  }
+}
+function encodeLinkPath(path, enabled) {
+  if (!enabled) return path;
+  return path.split("/").map(
+    (segment) => segment === "" || segment === "." || segment === ".." ? segment : encodeURIComponent(segment)
+  ).join("/");
+}
+var init_link_uri_encoding = __esm({
+  "src/core/reference/link-uri-encoding.ts"() {
+  }
+});
+
 // src/core/reference/link-token-guards.ts
 function isTildeHomeRelativePathToken(fullContent, matchOffset, matchText) {
   if (matchOffset >= 2 && fullContent[matchOffset - 2] === "~" && fullContent[matchOffset - 1] === "/") {
@@ -2363,10 +2436,11 @@ function rewriteFileLinks(input) {
     const { candidate: punctStripped, suffix } = stripTrailingPunctuation(match);
     if (!punctStripped) return match;
     const lineNumMatch = LINE_NUMBER_SUFFIX.exec(punctStripped);
-    const candidate = lineNumMatch ? punctStripped.slice(0, lineNumMatch.index) : punctStripped;
+    const rawCandidate = lineNumMatch ? punctStripped.slice(0, lineNumMatch.index) : punctStripped;
     const lineNumSuffix = lineNumMatch ? lineNumMatch[0] : "";
-    if (!candidate) return match;
-    const tokenContext = getTokenContext(fullContent, offset, offset + candidate.length);
+    if (!rawCandidate) return match;
+    const tokenContext = getTokenContext(fullContent, offset, offset + rawCandidate.length);
+    const candidate = decodeLinkPath(rawCandidate, tokenContext.role);
     if (tokenContext.role !== "markdown-link-dest" && WINDOWS_ABSOLUTE_PATH.test(candidate)) {
       return match;
     }
@@ -2436,7 +2510,7 @@ function rewriteFileLinks(input) {
     const targetTop = targetFromRoot.split("/").filter(Boolean)[0] ?? "";
     const tokenIsCanonicalMesh = normalizeSeparators(candidate).startsWith(".agentsmesh/");
     const preferRelativeProseInSameSurface = !tokenIsCanonicalMesh && !targetIsDirectory && destTop.length > 0 && destTop === targetTop && destTop.startsWith(".") && destTop !== ".agentsmesh";
-    const forceRelative = preferRelativeProseInSameSurface || tokenContext.role === "markdown-link-dest" || isMarkdownLinkDestinationToken(fullContent, offset, candidate);
+    const forceRelative = preferRelativeProseInSameSurface || tokenContext.role === "markdown-link-dest" || isMarkdownLinkDestinationToken(fullContent, offset, rawCandidate);
     const rewritten = formatLinkPathForDestination(
       input.projectRoot,
       input.destinationFile,
@@ -2453,7 +2527,7 @@ function rewriteFileLinks(input) {
       }
     );
     if (!rewritten) return match;
-    return `${rewritten}${lineNumSuffix}${suffix}`;
+    return `${encodeLinkPath(rewritten, candidate !== rawCandidate)}${lineNumSuffix}${suffix}`;
   });
   return { content, missing: [...missing] };
 }
@@ -2463,6 +2537,7 @@ var init_link_rebaser = __esm({
     init_link_rebaser_helpers();
     init_link_rebaser_output();
     init_link_rebaser_resolution();
+    init_link_uri_encoding();
     init_link_token_guards();
     init_link_token_context();
   }
@@ -3316,7 +3391,7 @@ function unsupportedHookEventNames(hooks, supportedEvents) {
   if (!hooks) return [];
   const supported = new Set(supportedEvents);
   return Object.keys(hooks).filter(
-    (event) => !supported.has(event) && !BEST_EFFORT_HOOK_EVENTS.has(event)
+    (event) => !supported.has(event) && !isBestEffortHookEvent(event, hooks[event])
   );
 }
 function createUnsupportedHookWarning(event, target34, supportedEvents, options) {
@@ -6853,6 +6928,17 @@ var init_embedded_rules = __esm({
   }
 });
 
+// src/canonical/features/syntax-error.ts
+function failSyntax(filePath2, cause, onParseError) {
+  const error = new CanonicalParseError(filePath2, cause);
+  throw error;
+}
+var init_syntax_error = __esm({
+  "src/canonical/features/syntax-error.ts"() {
+    init_errors();
+  }
+});
+
 // src/canonical/features/mcp.ts
 function parseStringMap(raw) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
@@ -6935,14 +7021,14 @@ function stripJsonComments(text) {
   }
   return result2;
 }
-async function parseMcp(mcpPath) {
+async function parseMcp(mcpPath, onParseError) {
   const content = await readFileSafe(mcpPath);
   if (!content) return null;
   let parsed;
   try {
     parsed = JSON.parse(stripJsonComments(content));
-  } catch {
-    return null;
+  } catch (err) {
+    return failSyntax(mcpPath, err);
   }
   if (!parsed || typeof parsed !== "object") return null;
   const mcpServersRaw = parsed.mcpServers;
@@ -6957,6 +7043,7 @@ async function parseMcp(mcpPath) {
 }
 var init_mcp = __esm({
   "src/canonical/features/mcp.ts"() {
+    init_syntax_error();
     init_fs();
   }
 });
@@ -8736,10 +8823,10 @@ var init_claude_code2 = __esm({
       skillDir: ".claude/skills",
       managedOutputs: {
         dirs: [".claude/agents", ".claude/commands", ".claude/rules", ".claude/skills"],
-        // CLAUDE_NESTED_ROOT is the pre-migration project location; listing it here lets
-        // `cleanupStaleGeneratedOutputs` evict a leftover `.claude/CLAUDE.md` once generation
+        files: [CLAUDE_ROOT, ".claudeignore"],
+        // CLAUDE_NESTED_ROOT is the pre-migration project location: evicted once a run
         // writes the root `CLAUDE.md`, so Claude Code never concatenates both into context.
-        files: [CLAUDE_ROOT, CLAUDE_NESTED_ROOT, ".claudeignore"],
+        supersededFiles: [CLAUDE_NESTED_ROOT],
         // `.mcp.json` is the shared project MCP file teams hand-commit and
         // deepagents-cli writes too; agentsmesh owns only `mcpServers` in it.
         // `.claude/settings.json` is co-owned through the `SETTINGS_JSON_PATHS`
@@ -9970,9 +10057,8 @@ var init_cline2 = __esm({
     };
   }
 });
-function ruleSlug2(source) {
-  return basename(source, ".md");
-}
+
+// src/targets/codex-cli/codex-rule-paths.ts
 function directoryFromGlob(glob) {
   let normalized = glob.trim();
   if (normalized.startsWith("./")) normalized = normalized.slice(2);
@@ -9993,12 +10079,12 @@ function codexRuleDirectory(rule) {
     const dir = directoryFromGlob(glob);
     if (dir) return dir;
   }
-  return ruleSlug2(rule.source);
+  return null;
 }
 function codexNestedAgentsPath(rule) {
   const dir = codexRuleDirectory(rule);
   const filename = rule.codexInstructionVariant === "override" ? "AGENTS.override.md" : "AGENTS.md";
-  return `${dir}/${filename}`;
+  return dir === null ? filename : `${dir}/${filename}`;
 }
 var GLOB_METACHAR;
 var init_codex_rule_paths = __esm({
@@ -10006,10 +10092,9 @@ var init_codex_rule_paths = __esm({
     GLOB_METACHAR = /[*?[\]]/;
   }
 });
-
-// src/targets/codebuff/rule-paths.ts
 function codebuffNestedKnowledgePath(rule) {
-  return `${codexRuleDirectory(rule)}/AGENTS.md`;
+  const dir = codexRuleDirectory(rule) ?? basename(rule.source, ".md");
+  return `${dir}/AGENTS.md`;
 }
 var init_rule_paths = __esm({
   "src/targets/codebuff/rule-paths.ts"() {
@@ -10620,6 +10705,9 @@ function eligibleAdvisoryRules(canonical) {
     return rule.targets.length === 0 || rule.targets.includes("codex-cli");
   });
 }
+function isRootEmbedded(rule) {
+  return codexNestedAgentsPath(rule) === AGENTS_MD;
+}
 function groupByNestedPath2(rules) {
   const groups = /* @__PURE__ */ new Map();
   for (const rule of rules) {
@@ -10632,9 +10720,11 @@ function groupByNestedPath2(rules) {
 }
 function generateRules9(canonical) {
   const root = canonical.rules.find((r) => r.root);
+  const advisory = eligibleAdvisoryRules(canonical);
   const outputs = [];
   if (root) {
-    outputs.push({ path: AGENTS_MD, content: root.body.trim() });
+    const content = appendEmbeddedRulesBlock(root.body.trim(), advisory.filter(isRootEmbedded));
+    outputs.push({ path: AGENTS_MD, content });
   }
   for (const rule of canonical.rules) {
     if (rule.root) continue;
@@ -10646,7 +10736,8 @@ function generateRules9(canonical) {
       content: toSafeCodexRulesContent(rule.body)
     });
   }
-  for (const [path, rules] of groupByNestedPath2(eligibleAdvisoryRules(canonical))) {
+  const nested = advisory.filter((rule) => !isRootEmbedded(rule));
+  for (const [path, rules] of groupByNestedPath2(nested)) {
     const content = rules.map((rule) => rule.body.trim()).filter((body) => body.length > 0).join("\n\n");
     outputs.push({ path, content });
   }
@@ -11471,6 +11562,23 @@ var init_linter9 = __esm({
 });
 
 // src/targets/codex-cli/lint.ts
+function lintAgents3(canonical) {
+  const diagnostics = [];
+  for (const agent of canonical.agents) {
+    const dropped = CODEX_DROPPED_AGENT_FIELDS.filter(
+      (field) => hasAgentValue(agent, field)
+    ).sort();
+    if (dropped.length === 0) continue;
+    diagnostics.push(
+      createWarning(
+        agent.source,
+        "codex-cli",
+        `Codex agent TOML supports name, description, developer_instructions, model, sandbox_mode and mcp_servers; canonical ${dropped.join(", ")} are not projected to ${CODEX_AGENTS_DIR}/${agent.name}.toml.`
+      )
+    );
+  }
+  return diagnostics;
+}
 function lintMcp4(canonical) {
   if (!canonical.mcp || Object.keys(canonical.mcp.mcpServers).length === 0) return [];
   const diagnostics = [];
@@ -11502,11 +11610,21 @@ function lintHooks7(canonical) {
     (event) => createUnsupportedHookWarning(event, "codex-cli", CODEX_SUPPORTED_HOOK_EVENTS)
   );
 }
+var CODEX_DROPPED_AGENT_FIELDS;
 var init_lint8 = __esm({
   "src/targets/codex-cli/lint.ts"() {
     init_helpers();
     init_mcp_servers();
+    init_agents_format();
     init_constants10();
+    CODEX_DROPPED_AGENT_FIELDS = [
+      "tools",
+      "disallowedTools",
+      "maxTurns",
+      "hooks",
+      "skills",
+      "memory"
+    ];
   }
 });
 
@@ -11581,6 +11699,7 @@ var init_codex_cli2 = __esm({
       generateMcp: generateMcp6,
       generateHooks: generateHooks6,
       generatePermissions: generatePermissions7,
+      lint: lintAgents3,
       importFrom: importFromCodex
     };
     project6 = {
@@ -11628,7 +11747,7 @@ var init_codex_cli2 = __esm({
       },
       rewriteGeneratedPath(path) {
         if (path === AGENTS_MD) return CODEX_GLOBAL_AGENTS_MD;
-        if (/\/AGENTS(\.override)?\.md$/.test(path)) return null;
+        if (/(^|\/)AGENTS(\.override)?\.md$/.test(path)) return null;
         if (path.startsWith(`${CODEX_INSTRUCTIONS_DIR}/`)) return null;
         return path;
       },
@@ -12284,7 +12403,7 @@ function hasValue(agent, field) {
   if (value && typeof value === "object") return Object.keys(value).length > 0;
   return false;
 }
-function lintAgents3(canonical) {
+function lintAgents4(canonical) {
   const diagnostics = [];
   for (const agent of canonical.agents) {
     const dropped = DROPPED_FIELDS.filter((field) => hasValue(agent, field)).sort();
@@ -12452,7 +12571,7 @@ var init_continue2 = __esm({
       generateHooks: generateHooks7,
       generateIgnore: generateIgnore8,
       // Feature-independent lint hook: agent warnings must not hang off `rules`.
-      lint: lintAgents3,
+      lint: lintAgents4,
       importFrom: importFromContinue
     };
     descriptor10 = {
@@ -12709,7 +12828,7 @@ var init_hook_format = __esm({
     init_hook_entry();
   }
 });
-function ruleSlug3(source) {
+function ruleSlug2(source) {
   const name = basename(source, ".md");
   return name === "_root" ? "root" : name;
 }
@@ -12743,7 +12862,7 @@ function generateRules11(canonical) {
     if (rule.root) continue;
     if (rule.targets.length > 0 && !rule.targets.includes("copilot")) continue;
     if (rule.globs.length === 0) continue;
-    const slug = ruleSlug3(rule.source);
+    const slug = ruleSlug2(rule.source);
     const frontmatter = {
       description: rule.description || void 0,
       applyTo: rule.globs.length === 1 ? rule.globs[0] : rule.globs
@@ -14232,13 +14351,18 @@ var init_rules2 = __esm({
 
 // src/targets/cursor/generator/commands.ts
 function generateCommands13(canonical) {
-  return canonical.commands.map((cmd) => ({
-    path: `${CURSOR_COMMANDS_DIR}/${cmd.name}.md`,
-    content: cmd.body.trim() || ""
-  }));
+  return canonical.commands.map((cmd) => {
+    const frontmatter = {};
+    if (cmd.description) frontmatter.description = cmd.description;
+    return {
+      path: `${CURSOR_COMMANDS_DIR}/${cmd.name}.md`,
+      content: serializeFrontmatter(frontmatter, cmd.body.trim() || "")
+    };
+  });
 }
 var init_commands = __esm({
   "src/targets/cursor/generator/commands.ts"() {
+    init_markdown();
     init_constants13();
   }
 });
@@ -14333,7 +14457,7 @@ var init_permissions3 = __esm({
 // src/targets/cursor/hook-format.ts
 function unmappedCursorHookEvents(hooks) {
   return Object.keys(hooks).filter(
-    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_CURSOR) && !BEST_EFFORT_HOOK_EVENTS.has(event)
+    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_CURSOR) && !isBestEffortHookEvent(event, hooks[event])
   );
 }
 function toCursorHooks(hooks) {
@@ -14771,14 +14895,11 @@ async function hasGlobalCursorArtifacts(projectRoot) {
     join(projectRoot, CURSOR_GLOBAL_USER_RULES),
     join(projectRoot, CURSOR_MCP),
     join(projectRoot, CURSOR_HOOKS),
-    join(projectRoot, CURSOR_IGNORE),
-    join(projectRoot, CURSOR_SKILLS_DIR),
-    join(projectRoot, CURSOR_AGENTS_DIR),
-    join(projectRoot, CURSOR_COMMANDS_DIR)
+    join(projectRoot, CURSOR_IGNORE)
   ];
   for (const p of candidates) {
-    const stat4 = await readFileSafe(p);
-    if (stat4 !== null && stat4.trim() !== "") return true;
+    const content = await readFileSafe(p);
+    if (content !== null && content.trim() !== "") return true;
   }
   const skillFiles = await readDirRecursiveNoSymlinks(join(projectRoot, CURSOR_SKILLS_DIR));
   if (skillFiles.some((f) => f.endsWith(".md"))) return true;
@@ -15065,11 +15186,11 @@ function lintHooks10(canonical) {
   ];
 }
 function lintCommands6(canonical) {
-  return canonical.commands.filter((command) => command.description.length > 0 || command.allowedTools.length > 0).map(
+  return canonical.commands.filter((command) => command.allowedTools.length > 0).map(
     (command) => createWarning(
       command.source,
       "cursor",
-      "Cursor command files are plain Markdown; command description and allowed-tools metadata are not projected."
+      "Cursor command files project only description frontmatter; allowed-tools metadata is not projected."
     )
   );
 }
@@ -15402,7 +15523,7 @@ var init_mcp_merge4 = __esm({
 // src/targets/deepagents-cli/hooks-format.ts
 function unmappedDeepagentsHookEvents(hooks) {
   return Object.keys(hooks).filter(
-    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_DEEPAGENTS) && !BEST_EFFORT_HOOK_EVENTS.has(event)
+    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_DEEPAGENTS) && !isBestEffortHookEvent(event, hooks[event])
   );
 }
 function toDeepagentsHooks(hooks) {
@@ -15970,7 +16091,8 @@ var init_deepagents_cli2 = __esm({
         }
       },
       buildImportPaths: buildDeepagentsCliImportPaths,
-      detectionPaths: [DEEPAGENTS_CLI_ROOT_FILE, DEEPAGENTS_CLI_MCP_FILE]
+      // `.mcp.json` is co-owned with claude-code (agentsmesh writes it), so it must not enroll this target.
+      detectionPaths: [DEEPAGENTS_CLI_ROOT_FILE]
     };
   }
 });
@@ -19948,7 +20070,8 @@ var init_layout8 = __esm({
       skillDir: KIMI_CODE_SKILLS_DIR,
       managedOutputs: {
         dirs: [KIMI_CODE_AGENTS_DIR, KIMI_CODE_SKILLS_DIR],
-        files: [KIMI_CODE_ROOT_FILE, KIMI_CODE_NESTED_ROOT_FILE],
+        files: [KIMI_CODE_ROOT_FILE],
+        supersededFiles: [KIMI_CODE_NESTED_ROOT_FILE],
         // Kimi Code's own MCP config, in the same directory as the credential-
         // bearing config.toml this layout already refuses to delete.
         coOwnedFiles: [KIMI_CODE_MCP_FILE]
@@ -20596,7 +20719,7 @@ function lintMcp9(canonical) {
   }
   return diagnostics;
 }
-function lintAgents4(canonical) {
+function lintAgents5(canonical) {
   return canonical.agents.flatMap((agent) => {
     const dropped = DROPPED_AGENT_FIELDS.filter(([, has]) => has(agent)).map(([field]) => field);
     if (dropped.length === 0) return [];
@@ -20687,7 +20810,7 @@ var init_kimi_code2 = __esm({
       generateHooks: generateHooks14,
       generatePermissions: generatePermissions16,
       importFrom: importFromKimiCode,
-      lint: lintAgents4
+      lint: lintAgents5
     };
     capabilities9 = {
       rules: "native",
@@ -22985,7 +23108,7 @@ function lintAgentFields(agent) {
     )
   ];
 }
-function lintAgents5(canonical) {
+function lintAgents6(canonical) {
   const diagnostics = [];
   for (const agent of canonical.agents) {
     diagnostics.push(...lintAgentFields(agent));
@@ -23047,7 +23170,7 @@ var init_openhands2 = __esm({
       generatePermissions: generatePermissions19,
       importFrom: importFromOpenhands,
       // Ungated by feature, so agent-only feature sets still get the warning.
-      lint: lintAgents5
+      lint: lintAgents6
     };
     descriptor24 = {
       id: OPENHANDS_TARGET,
@@ -26862,7 +26985,7 @@ var init_constants34 = __esm({
     WINDSURF_GLOBAL_AGENTS_SKILLS_DIR = ".agents/skills";
   }
 });
-function ruleSlug4(source) {
+function ruleSlug3(source) {
   const name = basename(source, ".md");
   return name === "_root" ? "root" : name;
 }
@@ -26883,7 +27006,7 @@ function generateRules32(canonical) {
   for (const rule of canonical.rules) {
     if (rule.root) continue;
     if (rule.targets.length > 0 && !rule.targets.includes("windsurf")) continue;
-    const slug = ruleSlug4(rule.source);
+    const slug = ruleSlug3(rule.source);
     const normalizedTrigger = rule.trigger || (rule.globs.length > 0 ? "glob" : void 0);
     const frontmatter = {
       description: rule.description || void 0,
@@ -26987,19 +27110,34 @@ var init_mcp4 = __esm({
   }
 });
 
-// src/targets/windsurf/generator/hooks.ts
+// src/targets/windsurf/hook-events.ts
 function windsurfEventName(event) {
-  const explicit = {
-    PreToolUse: "pre_tool_use",
-    PostToolUse: "post_tool_use",
-    Notification: "notification",
-    UserPromptSubmit: "user_prompt_submit",
-    SubagentStart: "subagent_start",
-    SubagentStop: "subagent_stop"
-  };
-  if (explicit[event]) return explicit[event];
   return event.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
 }
+function canonicalHookEventName(event) {
+  if (KNOWN_CANONICAL_HOOK_EVENTS.includes(event)) return event;
+  return WINDSURF_TO_CANONICAL.get(event) ?? null;
+}
+var KNOWN_CANONICAL_HOOK_EVENTS, WINDSURF_TO_CANONICAL;
+var init_hook_events = __esm({
+  "src/targets/windsurf/hook-events.ts"() {
+    init_hook_types();
+    KNOWN_CANONICAL_HOOK_EVENTS = [
+      "PreToolUse",
+      "PostToolUse",
+      "Notification",
+      "UserPromptSubmit",
+      "SubagentStart",
+      "SubagentStop",
+      ...BEST_EFFORT_HOOK_EVENTS
+    ];
+    WINDSURF_TO_CANONICAL = new Map(
+      KNOWN_CANONICAL_HOOK_EVENTS.map((event) => [windsurfEventName(event), event])
+    );
+  }
+});
+
+// src/targets/windsurf/generator/hooks.ts
 function toWindsurfHooks(hooks) {
   const result2 = {};
   for (const [event, entries] of Object.entries(hooks)) {
@@ -27027,6 +27165,7 @@ var init_hooks4 = __esm({
   "src/targets/windsurf/generator/hooks.ts"() {
     init_hook_command();
     init_constants34();
+    init_hook_events();
   }
 });
 
@@ -27158,6 +27297,57 @@ var init_skills_adapter5 = __esm({
     init_constants34();
   }
 });
+function toHookEntry(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const obj = raw;
+  const matcher = obj.matcher;
+  if (typeof matcher !== "string") return null;
+  const command = getHookText(obj);
+  if (!command) return null;
+  const type = typeof obj.type === "string" && VALID_TYPES.includes(obj.type) ? obj.type : void 0;
+  const timeout = typeof obj.timeout === "number" && Number.isFinite(obj.timeout) ? obj.timeout : void 0;
+  const prompt = getHookPrompt(obj) || void 0;
+  return {
+    matcher,
+    command,
+    ...timeout !== void 0 && { timeout },
+    ...type && { type },
+    ...prompt && { prompt }
+  };
+}
+async function parseHooks(hooksPath, onParseError) {
+  const content = await readFileSafe(hooksPath);
+  if (content === null) return null;
+  if (!content.trim()) return {};
+  let parsed;
+  try {
+    parsed = parse(content);
+  } catch (err) {
+    return failSyntax(hooksPath, err);
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const result2 = {};
+  const obj = parsed;
+  for (const [key, val] of Object.entries(obj)) {
+    if (!Array.isArray(val)) continue;
+    const entries = [];
+    for (const item of val) {
+      const entry = toHookEntry(item);
+      if (entry) entries.push(entry);
+    }
+    if (entries.length > 0) result2[key] = entries;
+  }
+  return result2;
+}
+var VALID_TYPES;
+var init_hooks5 = __esm({
+  "src/canonical/features/hooks.ts"() {
+    init_syntax_error();
+    init_fs();
+    init_hook_command();
+    VALID_TYPES = ["command", "prompt"];
+  }
+});
 async function importWindsurfHooks(projectRoot, results) {
   const hooksPath = join(projectRoot, WINDSURF_HOOKS_FILE);
   const hooksContent = await readFileSafe(hooksPath);
@@ -27165,9 +27355,10 @@ async function importWindsurfHooks(projectRoot, results) {
   try {
     const parsed = JSON.parse(hooksContent);
     if (!parsed.hooks || typeof parsed.hooks !== "object" || Array.isArray(parsed.hooks)) return;
-    const canonical = windsurfHooksToCanonical(parsed.hooks);
-    if (Object.keys(canonical).length === 0) return;
     const destPath = join(projectRoot, WINDSURF_CANONICAL_HOOKS);
+    const existing = await parseHooks(destPath) ?? {};
+    const canonical = windsurfHooksToCanonical(parsed.hooks, existing);
+    if (Object.keys(canonical).length === 0) return;
     await mkdirp(dirname(destPath));
     await writeFileAtomic(destPath, stringify(canonical));
     results.push({
@@ -27179,54 +27370,63 @@ async function importWindsurfHooks(projectRoot, results) {
   } catch {
   }
 }
-function canonicalHookEventName(event) {
-  const explicit = {
-    pre_tool_use: "PreToolUse",
-    post_tool_use: "PostToolUse",
-    notification: "Notification",
-    user_prompt_submit: "UserPromptSubmit",
-    subagent_start: "SubagentStart",
-    subagent_stop: "SubagentStop"
-  };
-  return explicit[event] ?? event;
+function preservedMatcher(existing, event, command) {
+  const match = existing[event]?.find((entry) => entry.command === command);
+  return match?.matcher ?? WILDCARD_MATCHER;
+}
+function legacyEntries(entry) {
+  const matcher = typeof entry.matcher === "string" && entry.matcher.trim() ? entry.matcher : WILDCARD_MATCHER;
+  const hooksList = Array.isArray(entry.hooks) ? entry.hooks : [];
+  const out = [];
+  for (const item of hooksList) {
+    if (!item || typeof item !== "object") continue;
+    const hook = item;
+    const command = typeof hook.command === "string" ? hook.command : typeof hook.prompt === "string" ? hook.prompt : "";
+    if (!command.trim()) continue;
+    const canonical = {
+      matcher,
+      type: hook.type === "prompt" ? "prompt" : "command",
+      command
+    };
+    if (typeof hook.timeout === "number") canonical.timeout = hook.timeout;
+    out.push(canonical);
+  }
+  return out;
 }
-function windsurfHooksToCanonical(hooks) {
+function windsurfHooksToCanonical(hooks, existing) {
   const result2 = {};
   for (const [event, entries] of Object.entries(hooks)) {
     if (!Array.isArray(entries)) continue;
     const mappedEvent = canonicalHookEventName(event);
+    if (mappedEvent === null) continue;
     const canonicalEntries = [];
     for (const entry of entries) {
       if (!entry || typeof entry !== "object") continue;
       const e = entry;
       if (typeof e.command === "string" && e.command.trim()) {
         canonicalEntries.push({
-          matcher: ".*",
+          matcher: preservedMatcher(existing, mappedEvent, e.command),
           type: "command",
           command: e.command
         });
         continue;
       }
-      const matcher = typeof e.matcher === "string" && e.matcher.trim() ? e.matcher : ".*";
-      const hooksList = Array.isArray(e.hooks) ? e.hooks : [];
-      for (const item of hooksList) {
-        if (!item || typeof item !== "object") continue;
-        const hook = item;
-        const command = typeof hook.command === "string" ? hook.command : typeof hook.prompt === "string" ? hook.prompt : "";
-        if (!command.trim()) continue;
-        const canonical = {
-          matcher,
-          type: hook.type === "prompt" ? "prompt" : "command",
-          command
-        };
-        if (typeof hook.timeout === "number") canonical.timeout = hook.timeout;
-        canonicalEntries.push(canonical);
-      }
+      canonicalEntries.push(...legacyEntries(e));
     }
     if (canonicalEntries.length > 0) result2[mappedEvent] = canonicalEntries;
   }
   return result2;
 }
+var WILDCARD_MATCHER;
+var init_importer_hooks2 = __esm({
+  "src/targets/windsurf/importer-hooks.ts"() {
+    init_hooks5();
+    init_fs();
+    init_constants34();
+    init_hook_events();
+    WILDCARD_MATCHER = "*";
+  }
+});
 async function importWindsurfMcp(projectRoot, results) {
   const sourceCandidates = [WINDSURF_MCP_EXAMPLE_FILE, WINDSURF_MCP_CONFIG_FILE];
   for (const relPath of sourceCandidates) {
@@ -27250,8 +27450,8 @@ async function importWindsurfMcp(projectRoot, results) {
     }
   }
 }
-var init_importer_hooks_mcp = __esm({
-  "src/targets/windsurf/importer-hooks-mcp.ts"() {
+var init_importer_mcp = __esm({
+  "src/targets/windsurf/importer-mcp.ts"() {
     init_fs();
     init_constants34();
   }
@@ -27401,7 +27601,8 @@ var init_importer32 = __esm({
     init_constants34();
     init_importer_workflows();
     init_skills_adapter5();
-    init_importer_hooks_mcp();
+    init_importer_hooks2();
+    init_importer_mcp();
   }
 });
 
@@ -27486,9 +27687,28 @@ function lintPermissions22(canonical) {
     )
   ];
 }
+function lintHooks23(canonical) {
+  if (!canonical.hooks) return [];
+  const diagnostics = [];
+  for (const [event, entries] of Object.entries(canonical.hooks)) {
+    for (const entry of entries ?? []) {
+      if (WILDCARD_MATCHERS.has(entry.matcher.trim())) continue;
+      diagnostics.push(
+        createWarning(
+          ".agentsmesh/hooks.yaml",
+          "windsurf",
+          `Windsurf hooks have no matcher field; ${event} hook "${entry.command}" runs on every ${event} event (matcher "${entry.matcher}" is not projected).`
+        )
+      );
+    }
+  }
+  return diagnostics;
+}
+var WILDCARD_MATCHERS;
 var init_lint31 = __esm({
   "src/targets/windsurf/lint.ts"() {
     init_helpers();
+    WILDCARD_MATCHERS = /* @__PURE__ */ new Set(["", "*", ".*"]);
   }
 });
 
@@ -27644,6 +27864,7 @@ var init_windsurf2 = __esm({
       lintRules: lintRules32,
       lint: {
         commands: lintCommands10,
+        hooks: lintHooks23,
         mcp: lintMcp13,
         permissions: lintPermissions22
       },