claudecode-linter 2.1.136 → 2.1.138-patch.1

package/.claudecode-lint.defaults.yaml

@@ -110,3 +110,10 @@ rules:
   claude-md/no-absolute-paths: info
   claude-md/no-todo-markers: info
   claude-md/no-trailing-whitespace: info
+
+  # ── Misplaced files ──────────────────────────────────────
+  # Reserved artifact basenames (plugin.json, hooks.json,
+  # marketplace.json, SKILL.md) found at non-canonical paths inside
+  # a plugin tree. Claude Code silently ignores them — easy to make,
+  # hard to debug.
+  misplaced-file/canonical-location: warning

package/dist/canonical-paths.js

@@ -0,0 +1,43 @@
+export const CANONICAL_ARTIFACTS = [
+    {
+        basename: "plugin.json",
+        expectedPath: ".claude-plugin/plugin.json",
+        description: "plugin manifest",
+    },
+    {
+        basename: "marketplace.json",
+        expectedPath: ".claude-plugin/marketplace.json",
+        description: "marketplace manifest",
+    },
+    {
+        basename: "hooks.json",
+        expectedPath: "hooks/hooks.json",
+        description: "plugin hooks config",
+    },
+    {
+        basename: "SKILL.md",
+        expectedPattern: "skills/*/SKILL.md",
+        description: "skill manifest",
+    },
+    {
+        basename: ".mcp.json",
+        expectedPath: ".mcp.json",
+        description: "plugin MCP server definitions",
+    },
+    {
+        basename: ".lsp.json",
+        expectedPath: ".lsp.json",
+        description: "plugin LSP server configurations",
+    },
+    {
+        basename: "monitors.json",
+        expectedPath: "monitors/monitors.json",
+        description: "plugin background-monitor declarations",
+    },
+    {
+        basename: "settings.json",
+        expectedPath: "settings.json",
+        description: "plugin default settings",
+    },
+];
+//# sourceMappingURL=canonical-paths.js.map

package/dist/contracts.js

@@ -1,5 +1,5 @@
 // Auto-generated from contracts/claude-code-contracts.json
-// Claude Code v2.1.136 — extracted 2026-05-08T18:40:06.818Z
+// Claude Code v2.1.138 — extracted 2026-05-09T06:52:55.909Z
 // Do not edit manually. Run: npm run generate-contracts
 export const TOOLS = new Set([
     "Agent",
@@ -311,7 +311,10 @@ export const SETTINGS_USER_FIELDS = new Set([
     "worktree",
     "wslInheritsWindowsSettings",
 ]);
-export const SETTINGS_PROJECT_FIELDS = new Set([
-    "permissions",
-]);
+export const SETTINGS_PROJECT_FIELDS = new Set(["permissions"]);
+// Hand-curated denylist of tools declared in agent frontmatter that never
+// reach plugin-defined subagents at runtime. Source: tracked upstream bugs
+//   https://github.com/anthropics/claude-code/issues/52055
+//   https://github.com/anthropics/claude-code/issues/52004
+export const PLUGIN_SUBAGENT_BLOCKED_TOOLS = new Set(["Glob", "Grep"]);
 //# sourceMappingURL=contracts.js.map

package/dist/discovery.js

@@ -1,8 +1,9 @@
 import { statSync, existsSync, readFileSync } from "node:fs";
-import { basename, dirname, resolve, join } from "node:path";
+import { basename, dirname, resolve, join, relative } from "node:path";
 import { homedir } from "node:os";
 import { globSync } from "tinyglobby";
 import { minimatch } from "minimatch";
+import { CANONICAL_ARTIFACTS } from "./canonical-paths.js";
 const CLAUDE_USER_DIR = join(homedir(), ".claude");
 function loadIgnoreFile(dir) {
     const ignoreFile = join(dir, ".claudecode-lint-ignore");
@@ -221,8 +222,58 @@ function discoverInDirectory(dir) {
             scope: detectScope(claudeMd),
         });
     }
+    // Misplaced-file scan: only meaningful inside a plugin tree
+    // (we use `.claude-plugin/` as the marker). Outside plugin
+    // trees, a stray `plugin.json` / `hooks.json` could legitimately
+    // belong to some other tool and we don't want to false-positive.
+    if (existsSync(join(dir, ".claude-plugin"))) {
+        for (const m of findMisplacedFiles(dir)) {
+            artifacts.push(m);
+        }
+    }
     return artifacts;
 }
+/**
+ * Walk `pluginRoot` looking for files whose basename is reserved
+ * for a Claude Code artifact and which Claude Code reads only from
+ * a single canonical path. Anything matching a basename but
+ * sitting at a non-canonical location is returned as a
+ * `misplaced-file` artifact for the misplaced-file linter to flag.
+ *
+ * Ignores typical noise dirs (`node_modules`, `.git`, `dist`, the
+ * plugin install cache's `.in_use` / `.orphaned_at` markers).
+ */
+function findMisplacedFiles(pluginRoot) {
+    const out = [];
+    for (const entry of CANONICAL_ARTIFACTS) {
+        const found = globSync(`**/${entry.basename}`, {
+            cwd: pluginRoot,
+            absolute: true,
+            // dot: walk into dot-directories like `.claude-plugin/`
+            // — that's exactly where the most common misplacement
+            // (hooks.json under `.claude-plugin/` instead of plugin
+            // root's `hooks/`) lives.
+            dot: true,
+            ignore: [
+                "**/node_modules/**",
+                "**/.git/**",
+                "**/dist/**",
+                "**/.in_use/**",
+                "**/.orphaned_at/**",
+            ],
+        });
+        for (const filePath of found) {
+            const rel = relative(pluginRoot, filePath);
+            const isCanonical = entry.expectedPattern
+                ? minimatch(rel, entry.expectedPattern)
+                : rel === entry.expectedPath;
+            if (!isCanonical) {
+                out.push({ filePath, artifactType: "misplaced-file" });
+            }
+        }
+    }
+    return out;
+}
 function classifyFile(filePath) {
     const name = basename(filePath);
     const parent = basename(dirname(filePath));

package/dist/index.js

@@ -2,7 +2,7 @@
 import { readFileSync, writeFileSync, copyFileSync, existsSync } from "node:fs";
 import { resolve, relative, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import sade from "sade";
 import pc from "picocolors";
 import { loadConfig, mergeCliRules } from "./config.js";
 import { discoverArtifacts } from "./discovery.js";
@@ -16,6 +16,7 @@ import { hooksJsonLinter } from "./linters/hooks-json.js";
 import { settingsJsonLinter } from "./linters/settings-json.js";
 import { mcpJsonLinter } from "./linters/mcp-json.js";
 import { claudeMdLinter } from "./linters/claude-md.js";
+import { misplacedFileLinter, MISPLACED_FILE_RULES, } from "./linters/misplaced-file.js";
 import { pluginJsonFixer } from "./fixers/plugin-json.js";
 import { frontmatterFixer } from "./fixers/frontmatter.js";
 import { hooksJsonFixer } from "./fixers/hooks-json.js";
@@ -39,6 +40,7 @@ const LINTERS = {
     "settings-json": settingsJsonLinter,
     "mcp-json": mcpJsonLinter,
     "claude-md": claudeMdLinter,
+    "misplaced-file": misplacedFileLinter,
 };
 const FIXERS = {
     "plugin-json": pluginJsonFixer,
@@ -59,6 +61,7 @@ const ALL_RULES = [
     ...SETTINGS_JSON_RULES,
     ...MCP_JSON_RULES,
     ...CLAUDE_MD_RULES,
+    ...MISPLACED_FILE_RULES,
 ];
 function simpleDiff(oldContent, newContent, filePath) {
     if (oldContent === newContent)
@@ -95,27 +98,30 @@ function simpleDiff(oldContent, newContent, filePath) {
     }
     return lines.join("\n");
 }
-const program = new Command();
-program
-    .name("claudecode-linter")
-    .description("Linter for Claude Code plugin artifacts")
-    .version(JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version)
-    .argument("[paths...]", "Plugin directories or individual files", ["."])
+const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+sade("claudecode-linter", true)
+    .version(pkgVersion)
+    .describe("Linter for Claude Code plugin artifacts")
     .option("--lint", "Lint artifacts and report issues (default)")
     .option("--fix", "Auto-fix lint violations, then report remaining issues")
     .option("--format", "Format all artifacts for consistent style (no lint output)")
-    .option("--output <type>", "Output format: human | json", "human")
-    .option("--config <path>", "Config file path")
-    .option("--scope <scope>", "Filter by scope: user | project | subdirectory")
-    .option("--ignore <patterns>", "Comma-separated glob patterns to ignore")
+    .option("--output", "Output format: human | json", "human")
+    .option("--config", "Config file path")
+    .option("--scope", "Filter by scope: user | project | subdirectory")
+    .option("--ignore", "Comma-separated glob patterns to ignore")
     .option("--quiet", "Only show errors")
-    .option("--enable <rules>", "Comma-separated rule IDs to enable")
-    .option("--disable <rules>", "Comma-separated rule IDs to disable")
-    .option("--rule <rule>", "Run only this single rule ID")
+    .option("--enable", "Comma-separated rule IDs to enable")
+    .option("--disable", "Comma-separated rule IDs to disable")
+    .option("--rule", "Run only this single rule ID")
     .option("--list-rules", "Print all rules with their default severity and exit")
     .option("--fix-dry-run", "Run fixers but print diff instead of writing")
-    .option("--init [path]", "Copy default config to path (default: current directory)")
-    .action(async (paths, opts) => {
+    .option("--init", "Copy default config to path (default: current directory)")
+    .action(async (opts) => {
+    // sade accepts variadic positional via opts._; default to ["."] when empty.
+    // Multi-word flags like --list-rules arrive in kebab-case form on opts.
+    const paths = Array.isArray(opts._) && opts._.length > 0 ? opts._ : ["."];
+    const listRules = !!opts["list-rules"];
+    const fixDryRun = !!opts["fix-dry-run"];
     try {
         if (opts.init !== undefined) {
             const __filename = fileURLToPath(import.meta.url);
@@ -131,7 +137,7 @@ program
             process.stdout.write(pc.green(`Created ${targetFile}\n`));
             process.exit(0);
         }
-        if (opts.listRules) {
+        if (listRules) {
             const sevColor = { error: pc.red, warning: pc.yellow, info: pc.blue };
             for (const rule of ALL_RULES) {
                 const color = sevColor[rule.defaultSeverity];
@@ -197,7 +203,7 @@ program
                         }
                     }
                 }
-                else if (opts.fixDryRun) {
+                else if (fixDryRun) {
                     const fixer = FIXERS[artifact.artifactType];
                     if (fixer) {
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
@@ -231,7 +237,7 @@ program
             }
             process.exit(0);
         }
-        if (!opts.fixDryRun) {
+        if (!fixDryRun) {
             const output = opts.output === "json"
                 ? formatJson(results, !!opts.quiet)
                 : formatHuman(results, !!opts.quiet);
@@ -244,6 +250,6 @@ program
         process.stderr.write(pc.red(`Fatal error: ${err.message}\n`));
         process.exit(2);
     }
-});
-program.parse();
+})
+    .parse(process.argv);
 //# sourceMappingURL=index.js.map

package/dist/linters/agent-md.js

@@ -1,6 +1,59 @@
-import { AGENT_FRONTMATTER, AGENT_MODELS, AGENT_COLORS } from "../contracts.js";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AGENT_FRONTMATTER, AGENT_MODELS, AGENT_COLORS, TOOLS, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
+function findPluginRoot(agentFilePath) {
+    let dir = dirname(agentFilePath);
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(dir, ".claude-plugin", "plugin.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function loadJson(p) {
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function loadPluginName(pluginRoot) {
+    const j = loadJson(join(pluginRoot, ".claude-plugin", "plugin.json"));
+    if (j && typeof j === "object" && j !== null && "name" in j) {
+        const n = j.name;
+        return typeof n === "string" ? n : null;
+    }
+    return null;
+}
+function loadMcpServerNames(pluginRoot) {
+    const j = loadJson(join(pluginRoot, ".mcp.json"));
+    const out = new Set();
+    if (j &&
+        typeof j === "object" &&
+        j !== null &&
+        "mcpServers" in j &&
+        typeof j.mcpServers === "object" &&
+        j.mcpServers !== null) {
+        for (const k of Object.keys(j.mcpServers)) {
+            out.add(k);
+        }
+    }
+    return out;
+}
+function parseToolsField(v) {
+    if (typeof v !== "string")
+        return [];
+    return v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
 const RULES = [
     { id: "agent-md/valid-frontmatter", defaultSeverity: "error" },
     { id: "agent-md/name-required", defaultSeverity: "error" },
@@ -9,12 +62,15 @@ const RULES = [
     { id: "agent-md/description-examples", defaultSeverity: "warning" },
     { id: "agent-md/model-required", defaultSeverity: "error" },
     { id: "agent-md/model-valid", defaultSeverity: "warning" },
-    { id: "agent-md/color-required", defaultSeverity: "error" },
+    { id: "agent-md/color-required", defaultSeverity: "warning" },
     { id: "agent-md/color-valid", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-present", defaultSeverity: "error" },
     { id: "agent-md/system-prompt-length", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-second-person", defaultSeverity: "info" },
     { id: "agent-md/no-unknown-frontmatter", defaultSeverity: "info" },
+    { id: "agent-md/known-tools", defaultSeverity: "warning" },
+    { id: "agent-md/mcp-tools-resolve", defaultSeverity: "error" },
+    { id: "agent-md/plugin-subagent-blocked-tools", defaultSeverity: "warning" },
 ];
 function diag(config, filePath, ruleId, defaultSeverity, message, line, column) {
     if (!isRuleEnabled(config, ruleId))
@@ -47,10 +103,10 @@ export const agentMdLinter = {
         }
         else {
             const name = fm.data.name;
-            if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(name) ||
-                name.length < 3 ||
+            if (!/^[a-z][a-z0-9-]*[a-z0-9]?$/.test(name) ||
+                name.length < 2 ||
                 name.length > 50) {
-                push(diag(config, filePath, "agent-md/name-format", "error", `"name" must be 3-50 chars, lowercase alphanumeric + hyphens (got "${name}")`));
+                push(diag(config, filePath, "agent-md/name-format", "error", `"name" must be 2-50 chars, lowercase alphanumeric + hyphens (got "${name}")`));
             }
         }
         // description
@@ -73,7 +129,7 @@ export const agentMdLinter = {
         }
         // color
         if (!("color" in fm.data) || typeof fm.data.color !== "string") {
-            push(diag(config, filePath, "agent-md/color-required", "error", '"color" is required in frontmatter'));
+            push(diag(config, filePath, "agent-md/color-required", "warning", '"color" is required in frontmatter'));
         }
         else if (!AGENT_COLORS.has(fm.data.color)) {
             push(diag(config, filePath, "agent-md/color-valid", "warning", `"color" must be one of: ${[...AGENT_COLORS].join(", ")} (got "${fm.data.color}")`));
@@ -98,6 +154,50 @@ export const agentMdLinter = {
                 push(diag(config, filePath, "agent-md/system-prompt-second-person", "info", 'System prompt should use second person ("You are...", "You will...")', fm.bodyStartLine));
             }
         }
+        // tools
+        const declaredTools = parseToolsField(fm.data.tools);
+        if (declaredTools.length > 0) {
+            const pluginRoot = findPluginRoot(filePath);
+            const pluginName = pluginRoot ? loadPluginName(pluginRoot) : null;
+            const mcpServers = pluginRoot
+                ? loadMcpServerNames(pluginRoot)
+                : new Set();
+            for (const t of declaredTools) {
+                if (t.startsWith("mcp__")) {
+                    // Two valid shapes:
+                    //   mcp__plugin_<plugin>_<server>__<tool>   plugin-namespaced
+                    //   mcp__<server>__<tool>                   user-config (non-plugin)
+                    const ns = t.match(/^mcp__plugin_([a-z0-9-]+)_([a-z0-9-]+)__(.+)$/);
+                    const bare = t.match(/^mcp__([a-z0-9-]+)__(.+)$/);
+                    if (ns) {
+                        const declaredPlugin = ns[1];
+                        const declaredServer = ns[2];
+                        if (pluginName && declaredPlugin !== pluginName) {
+                            push(diag(config, filePath, "agent-md/mcp-tools-resolve", "error", `Tool "${t}" references plugin "${declaredPlugin}", but this plugin is named "${pluginName}".`));
+                        }
+                        if (pluginRoot &&
+                            mcpServers.size > 0 &&
+                            !mcpServers.has(declaredServer)) {
+                            push(diag(config, filePath, "agent-md/mcp-tools-resolve", "error", `Tool "${t}" references MCP server "${declaredServer}", but .mcp.json declares: [${[...mcpServers].join(", ")}].`));
+                        }
+                    }
+                    else if (bare && pluginRoot) {
+                        const server = bare[1];
+                        const rest = bare[2];
+                        if (mcpServers.has(server)) {
+                            push(diag(config, filePath, "agent-md/mcp-tools-resolve", "error", `Tool "${t}" uses bare "mcp__<server>__<tool>" form, but this is a plugin (${pluginName ?? "unknown name"}). Plugin agents must use the namespaced form: "mcp__plugin_${pluginName ?? "<plugin>"}_${server}__${rest}".`));
+                        }
+                    }
+                    continue;
+                }
+                if (!TOOLS.has(t)) {
+                    push(diag(config, filePath, "agent-md/known-tools", "warning", `Unknown built-in tool "${t}" in tools: field. Valid: ${[...TOOLS].sort().join(", ")}.`));
+                }
+                if (pluginRoot && PLUGIN_SUBAGENT_BLOCKED_TOOLS.has(t)) {
+                    push(diag(config, filePath, "agent-md/plugin-subagent-blocked-tools", "warning", `Tool "${t}" is declared but does NOT reach plugin subagents at runtime — known Claude Code bug (https://github.com/anthropics/claude-code/issues/52055). The agent will silently lack this tool. For local file ops, use Bash with rg/find, or dispatch the built-in Explore subagent.`));
+                }
+            }
+        }
         return diagnostics;
     },
 };

package/dist/linters/misplaced-file.js

@@ -0,0 +1,45 @@
+import { basename } from "node:path";
+import { CANONICAL_ARTIFACTS } from "../canonical-paths.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+export const MISPLACED_FILE_RULES = [
+    { id: "misplaced-file/canonical-location", defaultSeverity: "warning" },
+];
+/**
+ * Flag files whose basename is reserved for a Claude Code artifact
+ * but which sit at a non-canonical path. Claude Code reads each
+ * artifact only from its canonical location and silently ignores
+ * copies elsewhere, so this class of mistake is easy to make and
+ * hard to debug — `/reload-plugins` reports `0 hooks` (or skills,
+ * etc.) with no other signal.
+ *
+ * Discovery (see discovery.ts) populates this linter's inputs by
+ * walking plugin trees and matching basenames; this linter just
+ * emits one diagnostic per misplaced file with the expected
+ * location.
+ */
+export const misplacedFileLinter = {
+    artifactType: "misplaced-file",
+    lint(filePath, _content, config) {
+        const ruleId = "misplaced-file/canonical-location";
+        if (!isRuleEnabled(config, ruleId))
+            return [];
+        const base = basename(filePath);
+        const entry = CANONICAL_ARTIFACTS.find((a) => a.basename === base);
+        if (!entry)
+            return [];
+        const expected = entry.expectedPath ?? entry.expectedPattern ?? "";
+        return [
+            {
+                rule: ruleId,
+                severity: getRuleSeverity(config, ruleId, "warning"),
+                message: `${base} is at a non-canonical path; ` +
+                    `Claude Code reads ${entry.description} only from ` +
+                    `\`${expected}\` (relative to plugin root) and ` +
+                    `silently ignores copies elsewhere. ` +
+                    `Move the file there or rename it.`,
+                file: filePath,
+            },
+        ];
+    },
+};
+//# sourceMappingURL=misplaced-file.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudecode-linter",
-	"version": "2.1.136",
+	"version": "2.1.138-patch.1",
 	"description": "Standalone linter for Claude Code plugins and configuration files",
 	"type": "module",
 	"bin": {
@@ -45,10 +45,10 @@
 		"node": ">=18"
 	},
 	"dependencies": {
-		"commander": "^14.0.3",
 		"minimatch": "^10.2.4",
 		"picocolors": "^1.1.1",
 		"prettier": "^3.8.1",
+		"sade": "^1.8.1",
 		"semver": "^7.7.4",
 		"tinyglobby": "^0.2.15",
 		"yaml": "^2.8.3"