@chimix/agentscan 0.5.0 → 0.7.0

package/README.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/checks-26-111111?style=flat-square" alt="26 checks">
-  <img src="https://img.shields.io/badge/tests-226%20passing-111111?style=flat-square" alt="226 tests">
+  <img src="https://img.shields.io/badge/checks-27-111111?style=flat-square" alt="27 checks">
+  <img src="https://img.shields.io/badge/tests-250%20passing-111111?style=flat-square" alt="250 tests">
   <img src="https://img.shields.io/badge/network-none-111111?style=flat-square" alt="No network">
   <img src="https://img.shields.io/badge/writes-none-111111?style=flat-square" alt="Writes nothing">
   <img src="https://img.shields.io/badge/runs%20on-node%20%C2%B7%20bun-111111?style=flat-square" alt="Node or Bun">
@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <strong>26 checks &middot; 4.1k lines &middot; 0 network calls &middot; every check sourced to a published spec line</strong><br>
+  <strong>27 checks &middot; 4.2k lines &middot; 0 network calls &middot; every check sourced to a published spec line</strong><br>
   <sub>Alpha. An earlier build reported 37 findings across 17 real projects of which <strong>25 were false</strong> — two checks had been written from what real projects looked like instead of from the spec. Both were deleted, and every check that survived is recorded in <a href="docs/spec/">docs/spec/</a> with the URL it came from and the date it was read. That story is the reason this tool exists in its current shape.</sub>
 </p>
 
@@ -62,9 +62,9 @@ of the filesystem**, where nothing else in your stack will ever tell you.
 No AI, no network, no heuristics. Read the config, read the disk, compare:
 
 ```
-1. Discover    .claude/ .agents/ .mcp.json AGENTS.md skills-lock.json
+1. Discover    .claude/ .agents/ .mcp.json AGENTS.md skills-lock.json plugin hooks/
 2. Extract     immutable facts — never re-read during checking
-3. Check       26 checks, each against one published spec line
+3. Check       27 checks, each against one published spec line
 4. Report      text · --json · --output prompt (handoff for a fixing agent)
 ```
 
@@ -127,7 +127,9 @@ bunx @chimix/agentscan explain hook.missing-script:hook:PreToolUse:./x.js ~/your
 ```
 
 `check` never opens a socket and never writes to the tree it scans. Contributing
-needs **Bun** 1.1+ — the repo runs TypeScript directly and `bun run build`
+needs **Bun** 1.4+ — the version CI pins and every gate is verified on; the
+text `bun.lock` this repo ships cannot be read by 1.1 at all. The repo runs
+TypeScript directly and `bun run build`
 bundles it for Node.
 
 ### In CI
@@ -156,7 +158,7 @@ bunx agentscan check                 # text report (cwd)
 bunx agentscan check ./my-app        # explicit root
 bunx agentscan check --json          # machine-readable
 bunx agentscan check --quiet         # summary only
-bunx agentscan check --verbose       # include KEEP and info-severity findings
+bunx agentscan check --verbose       # include KEEP, info findings, and each finding's id
 bunx agentscan check --fail-on warning
 bunx agentscan check --global        # also scan global skill dirs
 
@@ -175,7 +177,7 @@ Flags for `check`:
 | `--copy` | Also copy the report to the system clipboard |
 | `--no-color` | Never colour, even on a terminal (`NO_COLOR=1` does the same) |
 | `--quiet` | Summary line only |
-| `--verbose` | Show KEEP + info-severity findings |
+| `--verbose` | Show KEEP + info-severity findings, and print each finding's id |
 | `--fail-on <level>` | `never` (default) · `warning` · `error` |
 | `--fail-under <0-100>` | Fail when the score drops below this floor |
 | `--global` | Also scan `~/.claude/skills` and `~/.codex/skills` (see below) |
@@ -186,14 +188,14 @@ Flags for `check`:
 ## Sample output
 
 ```text
-  ┌─────┐   40/100  broken  ·  touchagency
-  │ ✕ ✕ │   ██████████░░░░░░░░░░░░░░░
-  │  ⌒  │   6 error · 4 info hidden (--verbose)
+  ┌─────┐   34/100  broken  ·  touchagency
+  │ ✕ ✕ │   █████████░░░░░░░░░░░░░░░░
+  │  ⌒  │   6 error · 2 warning · 11 info hidden (--verbose)
   └─────┘
 
-agentscan v0.5.0 — touchagency
+agentscan v0.7.0 — touchagency
 
-Scanned: 46 deps · 54 skills · 1 mcp · 2 agents · packageManager=bun
+Scanned: 46 deps · 108 skills · 1 mcp · 2 agents · packageManager=bun
 
 ERROR   rule:hook.missing-script  ×6
         Hook points at a script that does not exist
@@ -202,7 +204,12 @@ ERROR   rule:hook.missing-script  ×6
           PreToolUse @ .claude/settings.json · .claude/hooks/protect-artists-json.js
           PreToolUse @ .claude/settings.json · .claude/hooks/protect-env.js
 
-Summary: 6 error · 4 info hidden (--verbose) · score 40/100 broken
+WARN    rule:agent.invalid-name  ×2
+        2 findings
+          .claude/agents/marketing-seo-specialist.md
+          .claude/agents/testing-accessibility-auditor.md
+
+Summary: 6 error · 2 warning · 11 info hidden (--verbose) · score 34/100 broken
 ```
 
 On a terminal the header is coloured green, yellow or red and the face tracks
@@ -218,7 +225,7 @@ JSON shape (abridged):
 
 ```json
 {
-  "version": "0.5.0",
+  "version": "0.7.0",
   "root": "/path/to/project",
   "factsSummary": {
     "packageManager": "bun",
@@ -389,8 +396,9 @@ This is the only place agentscan starts a subprocess, and it runs only under
 
 `ignoreRules` disables a check project-wide, which is too blunt when a single
 hook uses an exotic launcher. `ignoreFindings` takes exact finding ids — the
-same strings `agentscan explain` accepts, so the value you already have from
-reading the report is the value you paste:
+same strings `agentscan explain` accepts. `check --verbose` prints the id under
+each finding, and `--json` carries it as `.findings[].id`, so the value you copy
+out of the report is the value you paste:
 
 ```json
 { "ignoreFindings": ["hook.missing-script:hook:PreToolUse:./bin/wrapper"] }
@@ -401,21 +409,22 @@ reading the report is the value you paste:
 Every check lives in `src/checks/` and runs on every `check`. `agentscan rules`
 lists all of them with their ids; `agentscan explain <id>` details any finding.
 
-Most validate one discovered item against its own file on disk. The five
-`budget.*` entries at the bottom judge aggregate size instead —
-they are all **info**, they are sourced to `docs/spec/thresholds.md`, and they
-are retuned through `thresholds` in `.agentscanrc.json` rather than switched
-off.
+Most validate one discovered item against its own file on disk. The four
+`budget.*` entries at the bottom judge aggregate size instead, as does
+`skill.description-budget` — all five are **info**, all five are sourced to
+`docs/spec/thresholds.md`, and all five are retuned through `thresholds` in
+`.agentscanrc.json` rather than switched off.
 
 | id | Severity | Catches |
 |----|----------|---------|
 | `config.unreadable` | error | A config file that is not valid JSON, so whatever it declares is silently not in effect |
-| `hook.missing-script` | error | A registered hook whose script does not exist — it never runs |
+| `scan.truncated` | info | A file past the scan cap, so the checks that read its body saw only a prefix — about this tool's reach, not about your project |
+| `hook.missing-script` | error | A registered hook whose script does not exist — it never runs. Reads all four in-tree registration sites (see below) |
 | `hook.unknown-event` | error | A hook registered under an event name that is never dispatched |
 | `agent.missing-frontmatter` | error | An agent definition with no `---` block |
 | `agent.missing-description` | error | Agent frontmatter has no `description` |
 | `agent.missing-name` | error | Agent frontmatter has no `name` |
-| `agent.invalid-name` | error | Agent name is not lowercase letters, numbers, and hyphens |
+| `agent.invalid-name` | warning | Agent name is not lowercase letters, numbers, and hyphens |
 | `agent.duplicate-name` | error | Multiple agent files declare the same name |
 | `mcp.no-launch` | error | An MCP server with neither `command` nor `url` — unlaunchable by schema |
 | `mcp.command-missing` | error | An MCP `command` that is a path-like value whose file does not exist on disk |
@@ -431,6 +440,10 @@ off.
 | `skill.not-in-lock` | info | A skill on disk that the lockfile does not track — local and unpinned |
 | `skill.description-budget` | info | Skill names + descriptions exceed the startup character budget |
 | `skill.no-lockfile` | info | Skills present with no lockfile at all (only with `requireLock`) |
+| `budget.agents-md` | info | `AGENTS.md` past the point where added lines stop helping (>150) |
+| `budget.claude-md` | info | `CLAUDE.md` past the instruction count a model reliably follows (>200) |
+| `budget.agents` | info | More agent definitions than a focused set (>8 in `.claude/agents`) |
+| `budget.mcp` | info | More MCP servers than the point where tool selection degrades (>5) |
 
 Agent definitions are checked for structure only. An agent's frontmatter `name`
 is not compared to the filename; it must simply be a valid lowercase identifier
@@ -446,6 +459,24 @@ references measured across 17 projects, 1645 resolved skill-relative and 12 only
 at the root. Fenced code blocks are stripped first: a path in an example is
 illustration, not a pointer.
 
+### Where it looks for hooks
+
+The hooks reference lists seven places a hook can be registered. agentscan reads
+the four that live inside the scanned project:
+
+| Registered in | Script paths resolve against |
+|---|---|
+| `.claude/settings.json` · `.claude/settings.local.json` | project root, `${CLAUDE_PROJECT_DIR}` |
+| A plugin's `hooks/hooks.json` (a directory with `.claude-plugin/plugin.json`, or the scan root itself) | the plugin root, `${CLAUDE_PLUGIN_ROOT}` |
+| `SKILL.md` frontmatter | the skill's own directory, then the project root |
+| `.claude/agents/*.md` frontmatter | the agent file's directory, then the project root |
+
+`${CLAUDE_PLUGIN_ROOT}` is expanded **only** for a hook that came from a plugin.
+In a settings file it names nothing, so the path is skipped rather than guessed
+at — measured across 17 installed plugins, 31 of 33 plugin hook commands use it
+and none of them are settings hooks. `hook.unknown-event` covers all four sites
+at no extra cost. Sources and measurements: [docs/spec/hook-sources.md](docs/spec/hook-sources.md).
+
 `hook.missing-script` and `mcp.command-missing` are deliberately conservative.
 A value is only resolved when it is path-like and the answer is certain; shell
 programs (`a && b`, `$(...)`, pipes), bare PATH binaries (`npx`, `uvx`), and
@@ -478,7 +509,17 @@ When adding a check, add its spec line there first.
 - **Runtime split.** Source development and the composite Action use Bun; the
   published `dist/cli.js` runs on Node 20.11+ or Bun. The source entrypoint uses
   Bun's `import.meta.dir` / `import.meta.main` and is not the Node entrypoint.
-- Policy files are read up to 100 KB, so `policyLines` undercounts past that.
+- **Three hook locations are unread.** `~/.claude/settings.json`, managed policy
+  settings, and installed marketplace plugins under `~/.claude/plugins` all sit
+  outside the scanned project, and the docs say a plugin's install directory
+  changes on every update. A hook registered in one of those, pointing at a
+  missing script, is not reported.
+- **Bounded reads.** A `SKILL.md` is read to 64 KB and a policy file to 100 KB,
+  so `skill.broken-reference` and `policyLines` see only that much of a larger
+  file. This is reported — `scan.truncated`, at `info` — rather than left
+  silent, and it says nothing about the file being valid: it is, and the tools
+  that read it see all of it. Reporting the cap as `config.unreadable` at
+  severity error is a defect this tool shipped and [plan 019](plans/019-findings-say-true-things.md) fixed.
 
 ## Development
 

package/dist/cli.js

@@ -7120,9 +7120,9 @@ function checkAgents(facts) {
       if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent.frontmatterName)) {
         out.push(make("agent.invalid-name", `agent:${agent.name}`, {
           action: "warn",
-          severity: "error",
+          severity: "warning",
           message: `Agent name "${agent.frontmatterName}" is not a valid identifier`,
-          reason: "Agent names use lowercase letters, numbers, and hyphens so dispatch can address them reliably.",
+          reason: "The subagent reference specifies a unique identifier in lowercase letters and hyphens. A name outside that shape is not documented to load reliably, and a `:` in it is documented not to load at all. See docs/spec/agents.md.",
           evidence: [{ kind: "agent", value: agent.path }],
           suggest: "Use lowercase letters, numbers, and hyphens in the `name` field"
         }));
@@ -7156,6 +7156,18 @@ function safeDetail(detail) {
 }
 function checkConfigErrors(facts) {
   return facts.configErrors.map((err) => {
+    if (err.kind === "truncated") {
+      return make("scan.truncated", `scan:${err.path}`, {
+        action: "warn",
+        severity: "info",
+        message: `${basename2(err.path)} is larger than the scan cap — only its first bytes were read`,
+        reason: "The file itself is fine; agentscan reads a bounded prefix of it. Checks that read the body — skill.broken-reference, and the AGENTS.md / CLAUDE.md line counts — see only that prefix, so they can undercount on this file.",
+        evidence: [
+          { kind: "config", value: err.path },
+          { kind: "detail", value: err.detail }
+        ]
+      });
+    }
     const what = err.kind === "invalid-json" ? "is not valid JSON" : err.kind === "unreadable" ? "could not be read" : "has an unexpected shape";
     return make("config.unreadable", `config:${err.path}#${err.kind}:${safeDetail(err.detail)}`, {
       action: "warn",
@@ -7247,10 +7259,11 @@ function checkHooks(facts) {
       action: "warn",
       severity: "error",
       message: `${hook.event ?? hook.name} hook points at a script that does not exist: ${hook.scriptPath}`,
-      reason: "The hook is registered but its script is missing, so it never runs. A guard hook that silently does nothing is worse than no hook — the config claims a protection that is not in effect.",
+      reason: "The hook is registered but its script is missing, so it never runs. A guard hook that silently does nothing is worse than no hook — the config claims a protection that is not in effect. A relative path is looked for beside the file that declared it and at the project root; it is at neither.",
       evidence: [
         { kind: "hook", value: `${hook.event ?? hook.name} @ ${hook.path}` },
-        { kind: "script", value: hook.scriptPath }
+        { kind: "script", value: hook.scriptPath },
+        ...hook.source === undefined || hook.source === "settings" ? [] : [{ kind: "source", value: hook.source }]
       ],
       suggest: `Restore ${hook.scriptPath} or remove the hook from ${hook.path}`
     }));
@@ -7335,6 +7348,7 @@ function checkMcp(facts) {
 }
 
 // src/checks/skills.ts
+import { dirname } from "node:path";
 function skillEvidence(skill, value) {
   const evidence = [{ kind: "skill", value }];
   if (skill.source === "global") {
@@ -7345,6 +7359,9 @@ function skillEvidence(skill, value) {
 function skillSubject(skill) {
   return `skill:${skill.instanceId ?? skill.id}`;
 }
+function skillRoot(skill) {
+  return dirname(skill.path.replaceAll("\\", "/"));
+}
 function checkSkillStructure(facts) {
   const out = [];
   for (const skill of facts.skills) {
@@ -7467,9 +7484,7 @@ function checkDuplicateDescriptions(facts) {
     if (skill.runtime === "agents") {
       continue;
     }
-    const path = skill.path.replaceAll("\\", "/");
-    const namespace = path.includes(".claude/skills/") ? "claude" : path.includes(".agents/skills/") ? "agents" : skill.source;
-    const key = `${namespace}\x00${skill.description.trim().replace(/\s+/g, " ").toLowerCase()}`;
+    const key = `${skillRoot(skill)}\x00${skill.description.trim().replace(/\s+/g, " ").toLowerCase()}`;
     if (key.length === 0) {
       continue;
     }
@@ -7502,23 +7517,36 @@ function checkDescriptionBudget(facts, options) {
     return [];
   }
   const project = facts.skills.filter((s) => s.source === "project" && s.hasSkillMd && s.description !== undefined);
-  const bytes = project.reduce((sum, s) => sum + Buffer.byteLength(s.id) + Buffer.byteLength(s.description ?? ""), 0);
-  if (bytes <= ceiling) {
-    return [];
+  const byRoot = new Map;
+  for (const s of project) {
+    const root = skillRoot(s);
+    const bucket = byRoot.get(root);
+    if (bucket === undefined)
+      byRoot.set(root, [s]);
+    else
+      bucket.push(s);
   }
-  return [
-    make("skill.description-budget", "skills:description-budget", {
+  const out = [];
+  for (const [root, skills] of byRoot) {
+    const bytes = skills.reduce((sum, s) => sum + Buffer.byteLength(s.id) + Buffer.byteLength(s.description ?? ""), 0);
+    if (bytes <= ceiling) {
+      continue;
+    }
+    const where = root.startsWith(`${facts.root}/`) ? root.slice(facts.root.length + 1) : root;
+    const subject = byRoot.size === 1 ? "skills:description-budget" : `skills:description-budget:${where}`;
+    out.push(make("skill.description-budget", subject, {
       action: "warn",
       severity: "info",
-      message: `Skill descriptions total ${bytes} bytes across ${project.length} skills (over ${ceiling})`,
+      message: `Skill descriptions total ${bytes} bytes across ${skills.length} skills in ${where} (over ${ceiling})`,
       reason: "Names and descriptions for every skill are loaded at startup, within a budget of roughly 1-2% of the context window. Past it they are truncated, and a skill whose description is cut short stops being matched for the tasks it was written for.",
       evidence: [
         { kind: "count", value: `descriptionBytes=${bytes}` },
         { kind: "threshold", value: String(ceiling) }
       ],
       suggest: "Shorten the longest descriptions, or remove skills this project does not use"
-    })
-  ];
+    }));
+  }
+  return out;
 }
 // src/checks/registry.ts
 var STRUCTURAL_CHECKS = [
@@ -7526,6 +7554,10 @@ var STRUCTURAL_CHECKS = [
     id: "config.unreadable",
     description: "Config file is not valid JSON or cannot be read"
   },
+  {
+    id: "scan.truncated",
+    description: "File is larger than the scan cap, so body checks read only a prefix of it"
+  },
   {
     id: "hook.unknown-event",
     description: "Hook registered under an event name that is never dispatched"
@@ -11672,11 +11704,16 @@ function loadConfig(root, configPath) {
 
 // src/discover/index.ts
 import { homedir as homedir3 } from "node:os";
-import { join as join8, resolve as resolve3 } from "node:path";
+import { join as join9, resolve as resolve3 } from "node:path";
 
 // src/discover/agents.ts
-import { existsSync as existsSync3, readdirSync, statSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { existsSync as existsSync4, readdirSync, statSync as statSync2 } from "node:fs";
+import { dirname as dirname2, join as join4 } from "node:path";
+
+// src/discover/hooks.ts
+import { existsSync as existsSync3, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join as join3 } from "node:path";
 
 // src/discover/shared.ts
 import { closeSync, existsSync as existsSync2, openSync, readFileSync as readFileSync2, readSync } from "node:fs";
@@ -11741,6 +11778,16 @@ function readCapped(path, cap) {
     closeSync(fd);
   }
 }
+var NESTED_DISCOVERY_MAX_DEPTH = 8;
+var NESTED_DISCOVERY_SKIP = new Set([
+  ".git",
+  "node_modules",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  "vendor"
+]);
 var AGENT_CONFIG_SIGNALS = [
   ".claude",
   ".agents",
@@ -11812,8 +11859,7 @@ function readFrontmatter(skillMdPath, errors3) {
     text = text.replace(/\r\n/g, `
 `);
     if (truncated) {
-      errors3.push({ path: skillMdPath, kind: "unexpected-shape", detail: `file exceeds ${SKILL_MD_CAP} byte scan cap` });
-      return { hasFrontmatter: true, unparseable: true };
+      errors3.push({ path: skillMdPath, kind: "truncated", detail: `file exceeds ${SKILL_MD_CAP} byte scan cap` });
     }
   } catch (err) {
     errors3.push({
@@ -11869,86 +11915,19 @@ function readFrontmatter(skillMdPath, errors3) {
   if (description !== undefined) {
     out.description = description;
   }
-  return out;
-}
-
-// src/discover/agents.ts
-function agentFiles(dir, errors3) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true }).map((e) => e.isDirectory() ? `${e.name}/` : e.name);
-  } catch (err) {
-    errors3.push({
-      path: dir,
-      kind: "unreadable",
-      detail: err instanceof Error ? err.message : String(err)
-    });
-    return [];
-  }
-  const out = [];
-  for (const entry of entries) {
-    if (entry.startsWith(".")) {
-      continue;
-    }
-    if (entry.endsWith("/")) {
-      out.push(...agentFiles(join3(dir, entry.slice(0, -1)), errors3).map((p) => join3(entry.slice(0, -1), p)));
-      continue;
-    }
-    out.push(entry);
+  if (record.hooks !== undefined) {
+    out.hooks = record.hooks;
   }
   return out;
 }
-function discoverAgents(root, errors3) {
-  const dir = join3(root, ".claude", "agents");
-  if (!existsSync3(dir)) {
-    return [];
-  }
-  const entries = agentFiles(dir, errors3);
-  const facts = [];
-  for (const name of entries) {
-    if (!name.endsWith(".md")) {
-      continue;
-    }
-    const filePath = join3(dir, name);
-    try {
-      const st = statSync(filePath);
-      if (!st.isFile()) {
-        continue;
-      }
-    } catch {
-      continue;
-    }
-    const fm = readFrontmatter(filePath, errors3);
-    const fact = {
-      name: name.slice(0, -".md".length),
-      path: filePath,
-      hasFrontmatter: fm.hasFrontmatter
-    };
-    if (fm.unreadable === true) {
-      fact.unreadable = true;
-    }
-    if (fm.unparseable === true) {
-      fact.unparseableFrontmatter = true;
-    }
-    if (fm.name !== undefined) {
-      fact.frontmatterName = fm.name;
-    }
-    if (fm.description !== undefined) {
-      fact.description = fm.description;
-    }
-    facts.push(fact);
-  }
-  return facts;
-}
 
 // src/discover/hooks.ts
-import { existsSync as existsSync4, statSync as statSync2 } from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, join as join4 } from "node:path";
 var INTERPRETERS = /^(?:bash|sh|zsh|python3?|node|bun|deno)$/;
 var INLINE_CODE_FLAGS = /^-(?:e|p|c)$/;
 var SHELL_METACHARS = /[|;&`]|\$\(|\|\||&&/;
-function hookScriptPath(command) {
+var PROJECT_DIR = /^\$(?:CLAUDE_PROJECT_DIR\b|\{CLAUDE_PROJECT_DIR\})/;
+var PLUGIN_ROOT = /^\$(?:CLAUDE_PLUGIN_ROOT\b|\{CLAUDE_PLUGIN_ROOT\})/;
+function hookScriptPath(command, bases = {}) {
   const trimmed = command.trim();
   if (trimmed.length === 0 || SHELL_METACHARS.test(trimmed)) {
     return;
@@ -11983,39 +11962,106 @@ function hookScriptPath(command) {
     return;
   }
   if (candidate.startsWith("$")) {
-    return /^\$(?:CLAUDE_PROJECT_DIR\b|\{CLAUDE_PROJECT_DIR\})/.test(candidate) ? candidate : undefined;
+    if (PROJECT_DIR.test(candidate)) {
+      return candidate;
+    }
+    return bases.plugin !== undefined && PLUGIN_ROOT.test(candidate) ? candidate : undefined;
   }
   if (candidate.startsWith("/") || candidate.startsWith("./") || candidate.startsWith("../") || candidate.startsWith("~/") || candidate.startsWith(".")) {
     return candidate;
   }
   return;
 }
-function resolveHookScript(root, raw) {
-  const extracted = hookScriptPath(raw);
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function resolveHookScript(bases, raw) {
+  const extracted = hookScriptPath(raw, bases);
   if (extracted === undefined) {
     return;
   }
-  let expanded = extracted;
-  if (expanded.startsWith("~/")) {
-    expanded = join4(homedir(), expanded.slice(2));
-  } else if (expanded.startsWith("$")) {
-    expanded = expanded.replace(/^\$(?:CLAUDE_PROJECT_DIR|\{CLAUDE_PROJECT_DIR\})\/?/, "");
+  if (extracted.startsWith("~/")) {
+    return {
+      scriptPath: extracted,
+      exists: isFile(join3(homedir(), extracted.slice(2)))
+    };
   }
-  const abs = isAbsolute(expanded) ? expanded : join4(root, expanded);
-  try {
-    return { scriptPath: extracted, exists: statSync2(abs).isFile() };
-  } catch {
-    return { scriptPath: extracted, exists: false };
+  if (PROJECT_DIR.test(extracted)) {
+    const rel = extracted.replace(/^\$(?:CLAUDE_PROJECT_DIR|\{CLAUDE_PROJECT_DIR\})\/?/, "");
+    return { scriptPath: extracted, exists: isFile(join3(bases.project, rel)) };
+  }
+  if (bases.plugin !== undefined && PLUGIN_ROOT.test(extracted)) {
+    const rel = extracted.replace(/^\$(?:CLAUDE_PLUGIN_ROOT|\{CLAUDE_PLUGIN_ROOT\})\/?/, "");
+    return { scriptPath: extracted, exists: isFile(join3(bases.plugin, rel)) };
+  }
+  if (isAbsolute(extracted)) {
+    return { scriptPath: extracted, exists: isFile(extracted) };
+  }
+  const candidates = [
+    ...bases.own === undefined ? [] : [join3(bases.own, extracted)],
+    join3(bases.project, extracted)
+  ];
+  return { scriptPath: extracted, exists: candidates.some(isFile) };
+}
+function hooksFromObject(hooks, filePath, source, bases, errors3) {
+  if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
+    errors3.push({
+      path: filePath,
+      kind: "unexpected-shape",
+      detail: "`hooks` is not an object"
+    });
+    return [];
+  }
+  const facts = [];
+  for (const [event, groups] of Object.entries(hooks)) {
+    const malformed = !Array.isArray(groups) || groups.some((group) => {
+      if (group === null || typeof group !== "object" || Array.isArray(group)) {
+        return true;
+      }
+      const inner = group.hooks;
+      if (!Array.isArray(inner))
+        return true;
+      return inner.some((entry) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+          return true;
+        }
+        const item = entry;
+        return item.command !== undefined && (typeof item.command !== "string" || item.command.length === 0) || item.type === "command" && typeof item.command !== "string";
+      });
+    });
+    if (malformed) {
+      errors3.push({ path: filePath, kind: "unexpected-shape", detail: `invalid hook groups for ${event}` });
+      continue;
+    }
+    const commands = collectHookCommands(groups);
+    if (commands.length === 0) {
+      facts.push({ name: event, path: filePath, event, source });
+      continue;
+    }
+    for (const command of commands) {
+      const fact = { name: event, path: filePath, event, source, command };
+      const resolved = resolveHookScript(bases, command);
+      if (resolved !== undefined) {
+        fact.scriptPath = resolved.scriptPath;
+        fact.scriptExists = resolved.exists;
+      }
+      facts.push(fact);
+    }
   }
+  return facts;
 }
 function discoverHooks(root, errors3) {
   const files = [
-    join4(root, ".claude", "settings.json"),
-    join4(root, ".claude", "settings.local.json")
+    join3(root, ".claude", "settings.json"),
+    join3(root, ".claude", "settings.local.json")
   ];
   const facts = [];
   for (const filePath of files) {
-    if (!existsSync4(filePath)) {
+    if (!existsSync3(filePath)) {
       continue;
     }
     const raw = readJsonConfig(filePath, errors3);
@@ -12034,49 +12080,7 @@ function discoverHooks(root, errors3) {
     if (hooks === undefined) {
       continue;
     }
-    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
-      errors3.push({
-        path: filePath,
-        kind: "unexpected-shape",
-        detail: "`hooks` is not an object"
-      });
-      continue;
-    }
-    for (const [event, groups] of Object.entries(hooks)) {
-      const malformed = !Array.isArray(groups) || groups.some((group) => {
-        if (group === null || typeof group !== "object" || Array.isArray(group)) {
-          return true;
-        }
-        const inner = group.hooks;
-        if (!Array.isArray(inner))
-          return true;
-        return inner.some((entry) => {
-          if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
-            return true;
-          }
-          const item = entry;
-          return item.command !== undefined && (typeof item.command !== "string" || item.command.length === 0) || item.type === "command" && typeof item.command !== "string";
-        });
-      });
-      if (malformed) {
-        errors3.push({ path: filePath, kind: "unexpected-shape", detail: `invalid hook groups for ${event}` });
-        continue;
-      }
-      const commands = collectHookCommands(groups);
-      if (commands.length === 0) {
-        facts.push({ name: event, path: filePath, event });
-        continue;
-      }
-      for (const command of commands) {
-        const fact = { name: event, path: filePath, event, command };
-        const resolved = resolveHookScript(root, command);
-        if (resolved !== undefined) {
-          fact.scriptPath = resolved.scriptPath;
-          fact.scriptExists = resolved.exists;
-        }
-        facts.push(fact);
-      }
-    }
+    facts.push(...hooksFromObject(hooks, filePath, "settings", { project: root }, errors3));
   }
   return facts;
 }
@@ -12106,6 +12110,84 @@ function collectHookCommands(groups) {
   return out;
 }
 
+// src/discover/agents.ts
+function agentFiles(dir, errors3) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true }).map((e) => e.isDirectory() ? `${e.name}/` : e.name);
+  } catch (err) {
+    errors3.push({
+      path: dir,
+      kind: "unreadable",
+      detail: err instanceof Error ? err.message : String(err)
+    });
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (entry.startsWith(".")) {
+      continue;
+    }
+    if (entry.endsWith("/")) {
+      out.push(...agentFiles(join4(dir, entry.slice(0, -1)), errors3).map((p) => join4(entry.slice(0, -1), p)));
+      continue;
+    }
+    out.push(entry);
+  }
+  return out;
+}
+function discoverAgents(root, errors3) {
+  const dir = join4(root, ".claude", "agents");
+  if (!existsSync4(dir)) {
+    return [];
+  }
+  const entries = agentFiles(dir, errors3);
+  const facts = [];
+  for (const name of entries) {
+    if (!name.endsWith(".md")) {
+      continue;
+    }
+    const filePath = join4(dir, name);
+    try {
+      const st = statSync2(filePath);
+      if (!st.isFile()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    const fm = readFrontmatter(filePath, errors3);
+    const fact = {
+      name: name.slice(0, -".md".length),
+      path: filePath,
+      hasFrontmatter: fm.hasFrontmatter
+    };
+    if (fm.unreadable === true) {
+      fact.unreadable = true;
+    }
+    if (fm.unparseable === true) {
+      fact.unparseableFrontmatter = true;
+    }
+    if (fm.name !== undefined) {
+      fact.frontmatterName = fm.name;
+    }
+    if (fm.description !== undefined) {
+      fact.description = fm.description;
+    }
+    if (fm.hooks !== undefined) {
+      const hooks = hooksFromObject(fm.hooks, filePath, "agent", {
+        project: root,
+        own: dirname2(filePath)
+      }, errors3);
+      if (hooks.length > 0) {
+        fact.frontmatterHooks = hooks;
+      }
+    }
+    facts.push(fact);
+  }
+  return facts;
+}
+
 // src/discover/mcp.ts
 import { existsSync as existsSync5, statSync as statSync3 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
@@ -12240,14 +12322,87 @@ function discoverMcp(root, mcpPaths, errors3) {
   return facts;
 }
 
-// src/discover/policy.ts
-import { existsSync as existsSync6 } from "node:fs";
+// src/discover/plugins.ts
+import { existsSync as existsSync6, readdirSync as readdirSync2 } from "node:fs";
 import { join as join6 } from "node:path";
+function findPluginRoots(root, errors3) {
+  const found = [];
+  if (existsSync6(join6(root, "hooks", "hooks.json"))) {
+    found.push(root);
+  }
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true });
+    } catch {
+      errors3.push({
+        path: dir,
+        kind: "unreadable",
+        detail: "could not read directories while looking for plugins"
+      });
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || NESTED_DISCOVERY_SKIP.has(entry.name)) {
+        continue;
+      }
+      if (entry.name.startsWith(".") && entry.name !== ".claude") {
+        continue;
+      }
+      const child = join6(dir, entry.name);
+      if (existsSync6(join6(child, ".claude-plugin", "plugin.json"))) {
+        found.push(child);
+        continue;
+      }
+      if (depth >= NESTED_DISCOVERY_MAX_DEPTH) {
+        continue;
+      }
+      walk(child, depth + 1);
+    }
+  };
+  walk(root, 0);
+  return found;
+}
+function discoverPluginHooks(root, errors3) {
+  const facts = [];
+  for (const pluginRoot of findPluginRoots(root, errors3)) {
+    const filePath = join6(pluginRoot, "hooks", "hooks.json");
+    if (!existsSync6(filePath)) {
+      continue;
+    }
+    const raw = readJsonConfig(filePath, errors3);
+    if (raw === undefined) {
+      continue;
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      errors3.push({
+        path: filePath,
+        kind: "unexpected-shape",
+        detail: "hooks.json is not a JSON object"
+      });
+      continue;
+    }
+    const hooks = raw.hooks;
+    if (hooks === undefined) {
+      continue;
+    }
+    facts.push(...hooksFromObject(hooks, filePath, "plugin", {
+      project: root,
+      plugin: pluginRoot,
+      own: pluginRoot
+    }, errors3));
+  }
+  return facts;
+}
+
+// src/discover/policy.ts
+import { existsSync as existsSync7 } from "node:fs";
+import { join as join7 } from "node:path";
 function discoverPolicyFiles(root, policyFiles, errors3) {
   const out = [];
   for (const rel of policyFiles) {
-    const filePath = join6(root, rel);
-    if (!existsSync6(filePath)) {
+    const filePath = join7(root, rel);
+    if (!existsSync7(filePath)) {
       continue;
     }
     try {
@@ -12255,7 +12410,7 @@ function discoverPolicyFiles(root, policyFiles, errors3) {
       const text = result.buf.subarray(0, POLICY_CAP).toString("utf8");
       out.push({ path: filePath, text });
       if (result.truncated)
-        errors3.push({ path: filePath, kind: "unexpected-shape", detail: `file exceeds ${POLICY_CAP} byte scan cap` });
+        errors3.push({ path: filePath, kind: "truncated", detail: `file exceeds ${POLICY_CAP} byte scan cap` });
     } catch (err) {
       errors3.push({
         path: filePath,
@@ -12267,8 +12422,8 @@ function discoverPolicyFiles(root, policyFiles, errors3) {
   return out;
 }
 function discoverSkillsLock(root, errors3) {
-  const filePath = join6(root, "skills-lock.json");
-  if (!existsSync6(filePath)) {
+  const filePath = join7(root, "skills-lock.json");
+  if (!existsSync7(filePath)) {
     return { locked: [], present: false };
   }
   const raw = readJsonConfig(filePath, errors3);
@@ -12313,8 +12468,8 @@ function discoverSkillsLock(root, errors3) {
 }
 
 // src/discover/skills.ts
-import { existsSync as existsSync7, readdirSync as readdirSync2, statSync as statSync4 } from "node:fs";
-import { join as join7, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync8, readdirSync as readdirSync3, statSync as statSync4 } from "node:fs";
+import { join as join8, resolve as resolve2 } from "node:path";
 var BUNDLED = "scripts|references|assets|templates|examples";
 var REFERENCE_RE = new RegExp(`(?<![\\w/.-])(?:\\./)?((?:${BUNDLED})/[A-Za-z0-9_./-]+\\.[A-Za-z0-9]{1,10})(?![A-Za-z0-9_.-])`, "g");
 var FENCE_BLOCK = /^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^[ \t]*\1[ \t]*$|$)/gm;
@@ -12335,22 +12490,22 @@ function skillReferences(body) {
   return out;
 }
 function brokenReferences(body, skillDir, root) {
-  const isFile = (p) => {
+  const isFile2 = (p) => {
     try {
       return statSync4(p).isFile();
     } catch {
       return false;
     }
   };
-  return skillReferences(body).filter((rel) => !isFile(join7(skillDir, rel)) && !isFile(join7(root, rel)));
+  return skillReferences(body).filter((rel) => !isFile2(join8(skillDir, rel)) && !isFile2(join8(root, rel)));
 }
 function discoverSkillsInDir(dir, source, errors3, root) {
-  if (!existsSync7(dir)) {
+  if (!existsSync8(dir)) {
     return [];
   }
   let entries;
   try {
-    entries = readdirSync2(dir);
+    entries = readdirSync3(dir);
   } catch (err) {
     errors3.push({
       path: dir,
@@ -12366,7 +12521,7 @@ function discoverSkillsInDir(dir, source, errors3, root) {
     if (name.startsWith(".") || name === "node_modules") {
       continue;
     }
-    const skillDir = join7(dir, name);
+    const skillDir = join8(dir, name);
     let st;
     try {
       st = statSync4(skillDir);
@@ -12376,10 +12531,10 @@ function discoverSkillsInDir(dir, source, errors3, root) {
     if (!st.isDirectory()) {
       continue;
     }
-    const skillMd = join7(skillDir, "SKILL.md");
+    const skillMd = join8(skillDir, "SKILL.md");
     let dirReadable = true;
     try {
-      readdirSync2(skillDir);
+      readdirSync3(skillDir);
     } catch (err) {
       dirReadable = false;
       errors3.push({
@@ -12388,7 +12543,7 @@ function discoverSkillsInDir(dir, source, errors3, root) {
         detail: err instanceof Error ? err.message : String(err)
       });
     }
-    const hasSkillMd = dirReadable && existsSync7(skillMd);
+    const hasSkillMd = dirReadable && existsSync8(skillMd);
     const fm = hasSkillMd ? readFrontmatter(skillMd, errors3) : { hasFrontmatter: false };
     const fact = {
       id: name,
@@ -12416,26 +12571,25 @@ function discoverSkillsInDir(dir, source, errors3, root) {
     if (fm.name !== undefined) {
       fact.frontmatterName = fm.name;
     }
+    if (fm.hooks !== undefined) {
+      const hooks = hooksFromObject(fm.hooks, skillMd, "skill", {
+        project: root,
+        own: skillDir
+      }, errors3);
+      if (hooks.length > 0) {
+        fact.frontmatterHooks = hooks;
+      }
+    }
     skills.push(fact);
   }
   return skills;
 }
-var NESTED_DISCOVERY_MAX_DEPTH = 8;
-var NESTED_DISCOVERY_SKIP = new Set([
-  ".git",
-  "node_modules",
-  ".next",
-  "dist",
-  "build",
-  "coverage",
-  "vendor"
-]);
 function discoverNestedClaudeSkills(root, configuredRoots, errors3, options = {}) {
   const out = [];
   const read = (dir) => {
     options.onDirectoryRead?.();
     try {
-      return readdirSync2(dir, { withFileTypes: true });
+      return readdirSync3(dir, { withFileTypes: true });
     } catch {
       errors3.push({ path: dir, kind: "unreadable", detail: "could not read nested skill directories" });
       return;
@@ -12448,7 +12602,7 @@ function discoverNestedClaudeSkills(root, configuredRoots, errors3, options = {}
     for (const entry of entries) {
       if (!entry.isDirectory() || entry.name !== "skills")
         continue;
-      const child = join7(dir, entry.name);
+      const child = join8(dir, entry.name);
       if (configuredRoots.has(resolve2(child)))
         continue;
       out.push(...discoverSkillsInDir(child, "project", errors3, root));
@@ -12463,7 +12617,7 @@ function discoverNestedClaudeSkills(root, configuredRoots, errors3, options = {}
         continue;
       if (entry.name.startsWith(".") && entry.name !== ".claude")
         continue;
-      const child = join7(dir, entry.name);
+      const child = join8(dir, entry.name);
       if (entry.name === ".claude") {
         inspectClaude(child);
         continue;
@@ -12493,7 +12647,7 @@ function discoverAgentSurface(root, config, opts) {
   const configErrors = [];
   const skills = [];
   for (const rel of config.skillPaths) {
-    skills.push(...discoverSkillsInDir(join8(root, rel), "project", configErrors, root));
+    skills.push(...discoverSkillsInDir(join9(root, rel), "project", configErrors, root));
   }
   const configuredRoots = new Set(config.skillPaths.map((rel) => resolve3(root, rel)));
   skills.push(...discoverNestedClaudeSkills(root, configuredRoots, configErrors, {
@@ -12501,14 +12655,20 @@ function discoverAgentSurface(root, config, opts) {
   }));
   if (opts.includeGlobal) {
     const home = homedir3();
-    skills.push(...discoverSkillsInDir(join8(home, ".claude", "skills"), "global", configErrors, root));
-    skills.push(...discoverSkillsInDir(join8(home, ".codex", "skills"), "global", configErrors, root));
+    skills.push(...discoverSkillsInDir(join9(home, ".claude", "skills"), "global", configErrors, root));
+    skills.push(...discoverSkillsInDir(join9(home, ".codex", "skills"), "global", configErrors, root));
   }
   const lock = discoverSkillsLock(root, configErrors);
+  const agents = discoverAgents(root, configErrors);
   return {
     skills: disambiguateSkills(skills, root),
-    agents: discoverAgents(root, configErrors),
-    hooks: discoverHooks(root, configErrors),
+    agents,
+    hooks: [
+      ...discoverHooks(root, configErrors),
+      ...discoverPluginHooks(root, configErrors),
+      ...skills.flatMap((s) => s.frontmatterHooks ?? []),
+      ...agents.flatMap((a) => a.frontmatterHooks ?? [])
+    ],
     mcp: discoverMcp(root, config.mcpPaths, configErrors),
     policyFiles: discoverPolicyFiles(root, config.policyFiles, configErrors),
     lockedSkills: lock.locked,
@@ -12519,11 +12679,11 @@ function discoverAgentSurface(root, config, opts) {
 }
 
 // src/facts/extract.ts
-import { existsSync as existsSync8, readFileSync as readFileSync3 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync3 } from "node:fs";
+import { join as join10 } from "node:path";
 function readPackageJson(root, errors3) {
-  const path = join9(root, "package.json");
-  if (!existsSync8(path)) {
+  const path = join10(root, "package.json");
+  if (!existsSync9(path)) {
     return {};
   }
   let text;
@@ -12621,16 +12781,16 @@ function inferPackageManager(root, pkg) {
       return prefix;
     }
   }
-  if (existsSync8(join9(root, "bun.lock")) || existsSync8(join9(root, "bun.lockb"))) {
+  if (existsSync9(join10(root, "bun.lock")) || existsSync9(join10(root, "bun.lockb"))) {
     return "bun";
   }
-  if (existsSync8(join9(root, "pnpm-lock.yaml"))) {
+  if (existsSync9(join10(root, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
-  if (existsSync8(join9(root, "yarn.lock"))) {
+  if (existsSync9(join10(root, "yarn.lock"))) {
     return "yarn";
   }
-  if (existsSync8(join9(root, "package-lock.json"))) {
+  if (existsSync9(join10(root, "package-lock.json"))) {
     return "npm";
   }
   return "unknown";
@@ -12969,7 +13129,7 @@ function renderText(args) {
   lines.push(ink.dim(`Scanned: ${formatStack(facts)}`));
   lines.push("");
   for (const group of groupByRule(visible)) {
-    lines.push(...formatGroup(group, facts.root, ink));
+    lines.push(...formatGroup(group, facts.root, ink, verbose));
     lines.push("");
   }
   lines.push(summary);
@@ -13029,7 +13189,7 @@ var SEVERITY_TONE = {
   warning: "yellow",
   info: undefined
 };
-function formatGroup(group, root, ink) {
+function formatGroup(group, root, ink, verbose) {
   const first = group[0];
   const count = group.length;
   const out = [];
@@ -13041,6 +13201,9 @@ function formatGroup(group, root, ink) {
     const where = f.evidence.filter((e) => e.kind !== "count" && e.kind !== "threshold").map((e) => shortPath(e.value, root));
     const location = where.length > 0 ? where.join(" · ") : f.subject;
     out.push(ink.dim(`          ${safe(shortPath(location, root))}`));
+    if (verbose) {
+      out.push(ink.dim(`            id: ${safe(f.id)}`));
+    }
   }
   return out;
 }
@@ -13102,7 +13265,7 @@ function formatSummary(findings, verbose, ink) {
 }
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "0.7.0";
 
 // src/commands/check.ts
 async function runCheck(options) {
@@ -13149,13 +13312,13 @@ import {
   writeFileSync
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 async function runDemo() {
-  const root = mkdtempSync(join10(tmpdir(), "agentscan-demo-"));
+  const root = mkdtempSync(join11(tmpdir(), "agentscan-demo-"));
   try {
-    const claude = join10(root, ".claude");
+    const claude = join11(root, ".claude");
     mkdirSync(claude, { recursive: true });
-    writeFileSync(join10(claude, "settings.json"), `${JSON.stringify({
+    writeFileSync(join11(claude, "settings.json"), `${JSON.stringify({
       hooks: {
         PreToolUse: [
           {
@@ -13229,12 +13392,12 @@ function formatExplain(f) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync9, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join11, resolve as resolve5 } from "node:path";
+import { existsSync as existsSync10, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join12, resolve as resolve5 } from "node:path";
 async function runInit(dir, options = {}) {
   const root = resolve5(dir ?? process.cwd());
-  const path = join11(root, ".agentscanrc.json");
-  if (existsSync9(path) && !options.force) {
+  const path = join12(root, ".agentscanrc.json");
+  if (existsSync10(path) && !options.force) {
     return {
       exitCode: 2,
       stdout: "",
@@ -13270,7 +13433,7 @@ async function runRulesCommand(options = {}) {
 // src/report/clipboard.ts
 import { spawn } from "node:child_process";
 import { accessSync, constants } from "node:fs";
-import { delimiter, join as join12 } from "node:path";
+import { delimiter, join as join13 } from "node:path";
 var TOOLS = [
   ["wl-copy"],
   ["xclip", "-selection", "clipboard"],
@@ -13287,7 +13450,7 @@ function resolve6(name) {
     if (dir.length === 0) {
       continue;
     }
-    const candidate = join12(dir, name);
+    const candidate = join13(dir, name);
     try {
       accessSync(candidate, constants.X_OK);
       return candidate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chimix/agentscan",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Find broken agent configuration in a project — hooks whose scripts are gone, MCP servers misconfigured by schema, skills that disagree with their lockfile",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
   },
   "engines": {
     "node": ">=20.11.0",
-    "bun": ">=1.1.0"
+    "bun": ">=1.4.0"
   },
   "license": "MIT",
   "dependencies": {