specpipe 1.0.1 → 1.0.3

package/src/lib/hooks.js

@@ -0,0 +1,203 @@
+// Hook registry — the single source of truth for guard hooks and how each agent
+// declares them. Scripts live in kit/hooks/ and are emitted into each agent's hook
+// dir; each agent's native config file is generated from this map. Formats verified
+// 2026-06-28 against each agent's docs (see docs/multi-agent.md § Sources).
+//
+// Enforced (blocking) agents and their config shapes differ:
+//   claude      .claude/settings.json   {hooks:{Event:[{matcher,hooks:[{type,command}]}]}}
+//   codex       .codex/hooks.json       (same nested shape)              matcher "Bash"
+//   cursor      .cursor/hooks.json      {version:1,hooks:{beforeX:[{command,failClosed}]}}
+//   antigravity .agents/hooks.json      {enabled:true,Event:[{matcher,command,timeout}]}  matcher "run_command"
+//
+// Command payloads the guard scripts read (multi-payload in specpipe-shell-guard.sh):
+//   .tool_input.command (Claude/Codex) · .command (Cursor) · .tool_args.CommandLine (Antigravity)
+
+export const HOOKS_DIR = 'hooks'; // kit-relative source dir for every script
+
+// Each guard hook: its script + which agents wire it, and where.
+//   shell/read run on bash; the JS guards are Claude-only (no equivalent event elsewhere).
+export const HOOKS = {
+  'shell-guard': {
+    script: 'specpipe-shell-guard.sh', run: 'bash',
+    desc: 'block wasteful-dir exploration + secret access in shell commands',
+    wiring: {
+      claude:      { event: 'PreToolUse', matcher: 'Bash', env: { SECRET_POLICY: 'warn' } },
+      codex:       { event: 'PreToolUse', matcher: 'Bash' },
+      cursor:      { event: 'beforeShellExecution' },
+      antigravity: { event: 'PreToolUse', matcher: 'run_command' },
+    },
+  },
+  'read-guard': {
+    script: 'specpipe-read-guard.sh', run: 'bash',
+    desc: 'block reads of secret files',
+    wiring: {
+      claude: { event: 'PreToolUse', matcher: 'Read|Write|Edit|MultiEdit|Grep' },
+      cursor: { event: 'beforeReadFile' },
+    },
+  },
+  'comment-guard': {
+    script: 'comment-guard.js', run: 'node',
+    desc: 'block placeholder-comment replacements',
+    wiring: { claude: { event: 'PreToolUse', matcher: 'Edit|MultiEdit' } },
+  },
+  'glob-guard': {
+    script: 'glob-guard.js', run: 'node',
+    desc: 'block overly broad globs',
+    wiring: { claude: { event: 'PreToolUse', matcher: 'Glob' } },
+  },
+  'file-guard': {
+    script: 'file-guard.js', run: 'node',
+    desc: 'warn on large source files',
+    wiring: {
+      claude: { event: 'PostToolUse', matcher: 'Write|Edit|MultiEdit' },
+      // Cursor: generic postToolUse fires for every tool (no matcher) — the guard
+      // self-filters to writes by tool_name and injects its warning via
+      // `additional_context`. Advisory (never blocks), so no failClosed. Verified
+      // live on Cursor 2026.06: postToolUse payload carries tool_name + tool_input.file_path.
+      cursor: { event: 'postToolUse', advisory: true },
+    },
+  },
+};
+
+export const HOOK_IDS = Object.keys(HOOKS);
+export const ALL_HOOK_NAMES = HOOK_IDS;
+
+/** Agents with a droppable, verified blocking-hook config. */
+export const HOOK_AGENTS = ['claude', 'codex', 'cursor', 'antigravity'];
+
+/**
+ * Resolve a `--hooks` value into a Set of selected hook ids, or null = all.
+ * 'none' → empty Set (option A: install no guard hooks). Accepts ids with or
+ * without the `-guard` suffix (e.g. `shell` or `shell-guard`).
+ */
+export function resolveHooks(spec) {
+  if (spec === undefined || spec === null || spec === 'all') return null;
+  if (spec === 'none') return new Set();
+  const norm = (n) => (HOOKS[n] ? n : (HOOKS[`${n}-guard`] ? `${n}-guard` : n));
+  const names = spec.split(',').map((s) => s.trim()).filter(Boolean).map(norm);
+  const unknown = names.filter((n) => !HOOKS[n]);
+  if (unknown.length) {
+    throw new Error(`Unknown hook(s): ${unknown.join(', ')}. Valid: ${HOOK_IDS.join(', ')}, all, none`);
+  }
+  return new Set(names);
+}
+
+/** Whether a hook id is selected (null = all). */
+export function hookSelected(id, hooksSet) {
+  return !hooksSet || hooksSet.has(id);
+}
+
+/** The hook ids an agent wires, filtered by selection. */
+function wiredHookIds(agentId, hooksSet) {
+  return HOOK_IDS.filter((id) => HOOKS[id].wiring[agentId] && hookSelected(id, hooksSet));
+}
+
+/** Scripts an agent installs (kit-relative src + on-disk dst), filtered by selection. */
+export function hookScriptsFor(agentId, hooksDir, hooksSet = null) {
+  return wiredHookIds(agentId, hooksSet).map((id) => ({
+    src: `${HOOKS_DIR}/${HOOKS[id].script}`,
+    dst: `${hooksDir}/${HOOKS[id].script}`,
+    run: HOOKS[id].run,
+  }));
+}
+
+// Build the command string an agent's config runs for a hook.
+// `ref` is how the agent references the script path (e.g. "$CLAUDE_PROJECT_DIR"/.claude/hooks).
+function commandFor(id, agentId, ref) {
+  const h = HOOKS[id];
+  const env = h.wiring[agentId].env
+    ? Object.entries(h.wiring[agentId].env).map(([k, v]) => `${k}=${v} `).join('')
+    : '';
+  return `${env}${h.run} ${ref}/${h.script}`;
+}
+
+// Where each agent's scripts + config live, and how its config references the
+// scripts. `ref` is per-project; the global Claude install passes an absolute ref.
+export const HOOK_TARGETS = {
+  claude:      { dir: '.claude/hooks', configPath: '.claude/settings.json', ref: '"$CLAUDE_PROJECT_DIR"/.claude/hooks' },
+  codex:       { dir: '.codex/hooks',  configPath: '.codex/hooks.json',     ref: '.codex/hooks' },
+  cursor:      { dir: '.cursor/hooks', configPath: '.cursor/hooks.json',    ref: '.cursor/hooks' },
+  // Antigravity runs hook commands with cwd = <project>/.agents (verified live on 1.0.13),
+  // so the command path is relative to .agents → `hooks/<script>`, NOT `.agents/hooks/<script>`.
+  antigravity: { dir: '.agents/hooks', configPath: '.agents/hooks.json',    ref: 'hooks' },
+};
+
+/**
+ * Generate an agent's native hook-config object from the registry, honoring the
+ * hook selection. `ref` is the path prefix the agent uses to reach the installed
+ * scripts. Returns null when the agent wires no hooks (or selection is empty).
+ * Shapes are per-agent and verified; see the table at the top of the file.
+ */
+export function buildHookConfig(agentId, ref, hooksSet = null) {
+  const ids = wiredHookIds(agentId, hooksSet);
+  if (!ids.length) return null;
+
+  if (agentId === 'claude' || agentId === 'codex') {
+    // { hooks: { Event: [ { matcher, hooks: [ { type:'command', command } ] } ] } }
+    const events = {};
+    for (const id of ids) {
+      const w = HOOKS[id].wiring[agentId];
+      (events[w.event] ??= []).push({
+        matcher: w.matcher,
+        hooks: [{ type: 'command', command: commandFor(id, agentId, ref) }],
+      });
+    }
+    return { hooks: events };
+  }
+
+  if (agentId === 'cursor') {
+    // { version:1, hooks: { beforeShellExecution:[{command,failClosed}], postToolUse:[{command}] } }
+    // Blocking before-hooks use failClosed (deny if the hook errors); advisory post-hooks
+    // (file-guard, which only injects a warning) must NOT — failClosed there would block writes.
+    const events = {};
+    for (const id of ids) {
+      const w = HOOKS[id].wiring.cursor;
+      const entry = { command: `${ref}/${HOOKS[id].script}` };
+      if (!w.advisory) entry.failClosed = true;
+      (events[w.event] ??= []).push(entry);
+    }
+    return { version: 1, hooks: events };
+  }
+
+  if (agentId === 'antigravity') {
+    // { "<hook-name>": { Event: [ { matcher, hooks: [ { type:'command', command, timeout } ] } ] } }
+    // Top level is a MAP of hook-NAME → spec; events nest inside, each an ARRAY of matcher
+    // groups with a nested `hooks` array. NO top-level `enabled` (a bool there makes
+    // Antigravity's Go parser reject the whole file → no hooks load). Verified live against
+    // Antigravity CLI 1.0.13 (jsonhook schema).
+    const events = {};
+    for (const id of ids) {
+      const w = HOOKS[id].wiring.antigravity;
+      (events[w.event] ??= []).push({
+        matcher: w.matcher,
+        hooks: [{ type: 'command', command: commandFor(id, agentId, ref), timeout: 15 }],
+      });
+    }
+    return { 'specpipe-guards': events };
+  }
+
+  return null;
+}
+
+/** Whether an agent has a droppable, verified enforced-hook config. */
+export function agentHasHooks(agentId) {
+  return !!HOOK_TARGETS[agentId];
+}
+
+/**
+ * Emit an agent's enforced-hook artifacts: the scripts to copy (kit-relative src +
+ * on-disk dst) and the generated config file. Honors the hook selection (null=all,
+ * empty Set=none). Returns null when the agent wires no hooks for this selection.
+ */
+export function emitHooks(agentId, hooksSet = null) {
+  const t = HOOK_TARGETS[agentId];
+  if (!t) return null;
+  const cfg = buildHookConfig(agentId, t.ref, hooksSet);
+  if (!cfg) return null;
+  return {
+    hooksDir: t.dir,
+    scripts: hookScriptsFor(agentId, t.dir, hooksSet),
+    configPath: t.configPath,
+    configContent: JSON.stringify(cfg, null, 2) + '\n',
+  };
+}

package/src/lib/installer.js

@@ -1,4 +1,4 @@
-import { copyFile as fsCopyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { copyFile as fsCopyFile, mkdir, readFile, writeFile, unlink, rmdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,14 +11,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * Component → file mappings.
  */
 export const COMPONENTS = {
-  hooks: [
-    '.claude/hooks/file-guard.js',
-    '.claude/hooks/path-guard.sh',
-    '.claude/hooks/comment-guard.js',
-    '.claude/hooks/glob-guard.js',
-    '.claude/hooks/self-review.sh',
-    '.claude/hooks/sensitive-guard.sh',
-  ],
+  // Hooks + settings.json are no longer static files — they're emitted per agent
+  // from the hook registry (hooks.js) via installAgentHooks. Kept as an (empty)
+  // component so `--only hooks` still resolves; init routes it to the emitter.
+  hooks: [],
   skills: [
     'skills/sp-explore/SKILL.md',
     'skills/sp-scaffold/SKILL.md',
@@ -44,31 +40,54 @@ export const COMPONENTS = {
     'skills/sp-md-render/components.md',
     'skills/sp-humanize/SKILL.md',
   ],
-  config: [
-    '.claude/settings.json',
-    '.claude/CLAUDE.md',
-  ],
-  docs: [
-    'docs/WORKFLOW.md',
-  ],
+  // CLAUDE.md is no longer a static file — it's emitted from the single rules source
+  // (kit/rules/specpipe-rules.md) as a marked section, like every other agent's rules.
+  config: [],
+  // docs/WORKFLOW.md was dropped — its content is covered by the skills (detailed) and
+  // the rules hub's workflow table. The user's docs/ holds only their own specs.
+  docs: [],
 };
 
+// ── Skill selection ─────────────────────────────────────────────────────────
+// Skills installed by default but safe to drop — standalone, not part of the
+// spec→build→review pipeline. Tagged "(optional)" in the interactive picker.
+export const OPTIONAL_SKILLS = ['sp-spec-render', 'sp-md-render', 'sp-humanize'];
+
+/** Every skill name (sp-*), derived from the skill component list. */
+export const ALL_SKILL_NAMES = [...new Set(COMPONENTS.skills.map((p) => p.split('/')[1]))];
+
 /**
- * Placeholder directories to create.
+ * Resolve a `--skills` value into a Set of selected skill names, or null = all.
+ * Accepts 'all', 'core' (all minus OPTIONAL_SKILLS), or a comma list of names
+ * (with or without the `sp-` prefix). Throws on an unknown name.
  */
-export const PLACEHOLDER_DIRS = [
-  'docs/specs',
-  'docs/test-plans',
-];
+export function resolveSkills(spec) {
+  if (!spec || spec === 'all') return null;
+  if (spec === 'core') return new Set(ALL_SKILL_NAMES.filter((n) => !OPTIONAL_SKILLS.includes(n)));
+  const names = spec.split(',').map((s) => s.trim()).filter(Boolean)
+    .map((n) => (n.startsWith('sp-') ? n : `sp-${n}`));
+  const unknown = names.filter((n) => !ALL_SKILL_NAMES.includes(n));
+  if (unknown.length) {
+    throw new Error(`Unknown skill(s): ${unknown.join(', ')}. Valid: ${ALL_SKILL_NAMES.join(', ')}, all, core`);
+  }
+  return new Set(names);
+}
 
 /**
- * Files that need +x permission.
+ * Whether a template file path is allowed under a skill selection (null = all).
+ * Non-skill files (hooks, config, docs) always pass; skill files pass only when
+ * their skill name is in the set.
  */
-export const EXECUTABLE_FILES = [
-  '.claude/hooks/path-guard.sh',
-  '.claude/hooks/self-review.sh',
-  '.claude/hooks/sensitive-guard.sh',
-];
+export function skillAllowed(filePath, skillsSet) {
+  if (!skillsSet) return true;
+  const m = filePath.replace(/\\/g, '/').match(/^skills\/([^/]+)\//);
+  return !m || skillsSet.has(m[1]);
+}
+
+
+// Files needing +x. Empty: guard scripts get +x at emit time (installAgentHooks
+// chmods them); none are installed as plain COMPONENTS files anymore.
+export const EXECUTABLE_FILES = [];
 
 /**
  * Get path to kit (templates) directory.
@@ -131,28 +150,44 @@ export async function installFile(relativePath, targetDir, { force = false } = {
   return 'copied';
 }
 
+/**
+ * Migration prune: delete files a PRIOR manifest tracked that the new install no
+ * longer wants — e.g. the predecessor `mf-*` (claude-devkit) / `ap-*` (agentpipe)
+ * skills, or renamed/removed hooks. Safe because it only touches paths the kit
+ * itself recorded as installed; a user's own files (e.g. a personal `mf-commit`
+ * skill that was never in our manifest) are never in `priorFiles`, so untouched.
+ * Skips preserved paths and the user's docs/. Cleans up emptied dirs.
+ * @returns {Promise<number>} count pruned
+ */
+export async function pruneOrphans(targetDir, priorFiles, keepSet, { preserve = ['.claude/CLAUDE.md'] } = {}) {
+  let pruned = 0;
+  const dirs = new Set();
+  for (const rel of Object.keys(priorFiles || {})) {
+    if (keepSet.has(rel) || preserve.includes(rel) || rel.startsWith('docs/')) continue;
+    const p = join(targetDir, rel);
+    if (!existsSync(p)) continue;
+    try {
+      await unlink(p);
+      log.del(`${rel} (legacy — superseded, removed)`);
+      pruned++;
+      let d = dirname(rel);
+      while (d && d !== '.' && d !== '/') { dirs.add(d); d = dirname(d); }
+    } catch { /* ignore */ }
+  }
+  for (const d of [...dirs].sort((a, b) => b.split('/').length - a.split('/').length)) {
+    try { await rmdir(join(targetDir, d)); } catch { /* not empty / missing */ }
+  }
+  return pruned;
+}
+
 // Per-agent install (emit skills + guardrails) lives in agent-install.js;
 // re-exported here so callers keep importing from installer.js.
 export {
   installSkillForAgent, installAgentSkills, installAgentRules,
-  mergeAgentsMdGuards, stripAgentsMdGuards,
+  mergeRulesSection, stripRulesSection,
   installAgentHooks, removeAgentHooks,
 } from './agent-install.js';
 
-/**
- * Create a placeholder directory with .gitkeep.
- */
-export async function ensurePlaceholderDir(dir, targetDir) {
-  const fullPath = join(targetDir, dir);
-  if (existsSync(fullPath)) {
-    log.skip(`${dir}/ (exists)`);
-    return;
-  }
-  await mkdir(fullPath, { recursive: true });
-  await writeFile(join(fullPath, '.gitkeep'), '');
-  log.make(`${dir}/`);
-}
-
 /**
  * Set executable permissions on relevant files.
  */
@@ -167,28 +202,34 @@ export async function setPermissions(targetDir) {
   }
 }
 
+// Every file the rules section can land in (per agent). fillTemplate fills the
+// detected Project Info into whichever ones exist.
+export const RULE_FILES = [
+  '.claude/CLAUDE.md',
+  'AGENTS.md',
+  '.cursor/rules/specpipe-rules.mdc',
+  '.agents/rules/specpipe-rules.md',
+  'SPECPIPE-RULES.md',
+];
+
 /**
- * Fill [CUSTOMIZE] placeholders in CLAUDE.md with detected project info.
+ * Fill the `[CUSTOMIZE]` Project Info placeholders in every installed rules file with
+ * the detected project info. Rules are emitted per agent (CLAUDE.md, AGENTS.md, …), so
+ * fill all of them, not just CLAUDE.md.
  */
 export async function fillTemplate(targetDir, projectInfo) {
   if (!projectInfo) return;
-
-  const claudeMdPath = join(targetDir, '.claude/CLAUDE.md');
-  try {
-    let content = await readFile(claudeMdPath, 'utf-8');
-    content = content
-      .replace(/\[CUSTOMIZE\] Language:.*/, `**Language:** ${projectInfo.lang}`)
-      .replace(/\[CUSTOMIZE\] Test framework:.*/, `**Test framework:** ${projectInfo.framework}`)
-      .replace(/\[CUSTOMIZE\] Source directory:.*/, `**Source directory:** ${projectInfo.srcDir}`)
-      .replace(/\[CUSTOMIZE\] Test directory:.*/, `**Test directory:** ${projectInfo.testDir}`)
-      // Also handle the format without [CUSTOMIZE] prefix
-      .replace(/\*\*Language:\*\* \[CUSTOMIZE\]/, `**Language:** ${projectInfo.lang}`)
-      .replace(/\*\*Test framework:\*\* \[CUSTOMIZE\]/, `**Test framework:** ${projectInfo.framework}`)
-      .replace(/\*\*Source directory:\*\* \[CUSTOMIZE\]/, `**Source directory:** ${projectInfo.srcDir}`)
-      .replace(/\*\*Test directory:\*\* \[CUSTOMIZE\]/, `**Test directory:** ${projectInfo.testDir}`);
-    await writeFile(claudeMdPath, content);
-  } catch {
-    // CLAUDE.md might not exist
+  for (const rel of RULE_FILES) {
+    const p = join(targetDir, rel);
+    try {
+      const before = await readFile(p, 'utf-8');
+      const after = before
+        .replace(/\*\*Language:\*\* \[CUSTOMIZE\]/, `**Language:** ${projectInfo.lang}`)
+        .replace(/\*\*Test framework:\*\* \[CUSTOMIZE\]/, `**Test framework:** ${projectInfo.framework}`)
+        .replace(/\*\*Source directory:\*\* \[CUSTOMIZE\]/, `**Source directory:** ${projectInfo.srcDir}`)
+        .replace(/\*\*Test directory:\*\* \[CUSTOMIZE\]/, `**Test directory:** ${projectInfo.testDir}`);
+      if (after !== before) await writeFile(p, after);
+    } catch { /* file not installed for this agent — skip */ }
   }
 }
 
@@ -208,6 +249,7 @@ export async function verifySettingsJson(targetDir) {
 // Claude's global install (~/.claude/skills + hooks + settings.json) lives in
 // claude-global.js; re-exported here so callers keep importing from installer.js.
 export {
-  getGlobalSkillsDir, getGlobalHooksDir, installHookGlobal,
-  mergeGlobalSettings, removeGlobalHooksFromSettings, installSkillGlobal,
+  getGlobalHooksDir, installHookGlobal,
+  mergeGlobalSettings, removeGlobalHooksFromSettings,
+  installSkillGlobalForAgent,
 } from './claude-global.js';

package/src/lib/reconcile.js

@@ -1,10 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { hashContent } from './hasher.js';
-import { getAllFiles, COMPONENTS, getTemplateDir } from './installer.js';
-import { emitFile, emitRules } from './agents.js';
+import { getAllFiles, COMPONENTS, getTemplateDir, skillAllowed } from './installer.js';
+import { emitFile, emitRules, AGENTS } from './agents.js';
 
-export const GUARDS_TEMPLATE_REL = 'rules/specpipe-guards.md';
+export const RULES_TEMPLATE_REL = 'rules/specpipe-rules.md';
 
 /**
  * Template files a given agent receives. Claude gets the full kit
@@ -13,7 +13,11 @@ export const GUARDS_TEMPLATE_REL = 'rules/specpipe-guards.md';
  * hooks are Claude-specific.
  */
 export function templateFilesForAgent(agentId) {
-  return agentId === 'claude' ? getAllFiles() : COMPONENTS.skills;
+  if (agentId === 'claude') return getAllFiles();
+  // Agents that don't read project-local skills (Hermes scans only ~/.hermes/skills/)
+  // get no per-project skill files — they'd be dead. Their rules doc is still emitted.
+  if (AGENTS[agentId]?.perProjectSkills === false) return [];
+  return COMPONENTS.skills;
 }
 
 /**
@@ -22,13 +26,14 @@ export function templateFilesForAgent(agentId) {
  * @returns {Promise<Map<string, {agent, templateRel, content, kitHash}>>}
  *          keyed by installed (on-disk) relative path.
  */
-export async function computeDesired(agents) {
+export async function computeDesired(agents, skillsSet = null) {
   const dir = getTemplateDir();
   const desired = new Map();
-  const guardsBody = await readFile(join(dir, GUARDS_TEMPLATE_REL), 'utf-8');
+  const guardsBody = await readFile(join(dir, RULES_TEMPLATE_REL), 'utf-8');
 
   for (const agent of agents) {
     for (const templateRel of templateFilesForAgent(agent)) {
+      if (!skillAllowed(templateRel, skillsSet)) continue;
       const content = await readFile(join(dir, templateRel), 'utf-8');
       const emitted = emitFile(agent, templateRel, content);
       desired.set(emitted.path, {
@@ -43,10 +48,10 @@ export async function computeDesired(agents) {
     // are reconciled like any other file. Codex's AGENTS.md is shared, not owned
     // here — it's merged/stripped separately.
     const rules = emitRules(agent, guardsBody);
-    if (rules && rules.mode !== 'agents-md') {
+    if (rules && rules.mode !== 'merge') {
       desired.set(rules.path, {
         agent,
-        templateRel: GUARDS_TEMPLATE_REL,
+        templateRel: RULES_TEMPLATE_REL,
         content: rules.content,
         kitHash: hashContent(rules.content),
       });

package/templates/{.claude/hooks → hooks}/file-guard.js

@@ -147,10 +147,18 @@ function main() {
   const filePath = payload.tool_input?.file_path;
   if (!filePath) process.exit(0);
 
-  // Skip files outside the project directory (e.g. ~/.claude/plans/)
-  const projectDir = process.cwd() + path.sep;
+  // Cursor's generic postToolUse fires for EVERY tool (Read, Grep, Shell, …); only act
+  // on writes/edits. Claude's PostToolUse matcher already restricts this, so tool_name is
+  // either a write-ish name or absent there — both pass.
+  const toolName = payload.tool_name;
+  if (toolName && !/^(Write|Edit|MultiEdit|write_to_file|replace_file_content)/i.test(toolName)) process.exit(0);
+
+  // Skip files outside the project directory (e.g. ~/.claude/plans/). Cursor passes the
+  // project root in workspace_roots; otherwise fall back to cwd.
+  const projectRoot = (Array.isArray(payload.workspace_roots) && payload.workspace_roots[0]) || process.cwd();
+  const projectDir = projectRoot + path.sep;
   const resolvedFile = path.resolve(filePath);
-  if (!resolvedFile.startsWith(projectDir) && resolvedFile !== process.cwd()) process.exit(0);
+  if (!resolvedFile.startsWith(projectDir) && resolvedFile !== projectRoot) process.exit(0);
 
   // Skip non-source-code files (docs, configs, templates are naturally long)
   const ext = path.extname(filePath).toLowerCase();
@@ -173,14 +181,8 @@ function main() {
   try {
     const stat = fs.statSync(filePath);
     if (stat.size > MAX_BYTES) {
-      const rel = path.relative(process.cwd(), filePath);
-      process.stdout.write(JSON.stringify({
-        continue: true,
-        hookSpecificOutput: {
-          hookEventName: "PostToolUse",
-          additionalContext: `Warning: ${rel} is ${Math.round(stat.size / 1024)}KB. Consider splitting into smaller modules.`,
-        },
-      }) + "\n");
+      const rel = path.relative(projectRoot, filePath);
+      emitWarning(`Warning: ${rel} is ${Math.round(stat.size / 1024)}KB. Consider splitting into smaller modules.`, payload);
       process.exit(0);
     }
     const buf = fs.readFileSync(filePath);
@@ -194,18 +196,21 @@ function main() {
   if (lineCount <= THRESHOLD) process.exit(0);
 
   // Inject non-blocking warning
-  const rel = path.relative(process.cwd(), filePath);
-  const warning = `Warning: ${rel} has ${lineCount} lines (threshold: ${THRESHOLD}). Consider splitting into smaller, focused modules.`;
+  const rel = path.relative(projectRoot, filePath);
+  emitWarning(`Warning: ${rel} has ${lineCount} lines (threshold: ${THRESHOLD}). Consider splitting into smaller, focused modules.`, payload);
+}
 
-  process.stdout.write(
-    JSON.stringify({
+// Inject an advisory warning in the agent's native shape. Cursor's postToolUse reads
+// `additional_context`; Claude (and Codex PostToolUse) read hookSpecificOutput.additionalContext.
+function emitWarning(warning, payload) {
+  if (payload.cursor_version || payload.hook_event_name === "postToolUse") {
+    process.stdout.write(JSON.stringify({ additional_context: warning }) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify({
       continue: true,
-      hookSpecificOutput: {
-        hookEventName: "PostToolUse",
-        additionalContext: warning,
-      },
-    }) + "\n"
-  );
+      hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: warning },
+    }) + "\n");
+  }
 }
 
 try {