claudecode-linter 2.1.144 → 2.1.148-patch.2

package/contracts/skill-frontmatter.schema.json

@@ -0,0 +1,378 @@
+{
+	"extractedFromClaudeCodeVersion": "2.1.146",
+	"extractedAt": "2026-05-22T08:49:59.762Z",
+	"schema": {
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		"title": "Claude Code SKILL.md frontmatter",
+		"type": "object",
+		"properties": {
+			"name": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Display name. Defaults to the filename without extension."
+			},
+			"description": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "One-line summary shown in listings and the Skill tool."
+			},
+			"model": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Model override (`haiku`, `sonnet`, `opus`, or a full ID). Use `inherit` to match the parent conversation."
+			},
+			"allowed-tools": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Tools available to the model while this file is active. Comma-separated string or YAML list."
+			},
+			"argument-hint": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Placeholder text shown after the slash command name."
+			},
+			"arguments": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "@internal — typed variant of argument-hint; argument-hint is the documented form"
+			},
+			"disable-model-invocation": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "If true, the model cannot invoke this via the Skill tool; only users can type the slash command."
+			},
+			"user-invocable": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "If false, hides the slash command from users; only the model can invoke it via the Skill tool."
+			},
+			"effort": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Thinking effort for the model: `low`, `medium`, `high`, `max`, or an integer."
+			},
+			"shell": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Shell for `!`-command blocks: `bash` or `powershell`. Defaults to bash regardless of platform."
+			},
+			"version": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "@internal — bookkeeping, not surfaced to users"
+			},
+			"when_to_use": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Guidance for when the model should reach for this skill. Becomes part of the tool description."
+			},
+			"paths": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Glob patterns this skill applies to. The skill only loads when the model touches matching files."
+			},
+			"hooks": {
+				"description": "Hooks registered while this skill is active. Same shape as settings.json `hooks`."
+			},
+			"context": {
+				"enum": [
+					"inline",
+					"fork",
+					null
+				],
+				"description": "Where the skill runs: `inline` expands into the current conversation; `fork` spawns a subagent."
+			},
+			"agent": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Agent type to spawn when `context: fork`."
+			},
+			"fallback": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "@internal — interim defense-in-depth for thin-pointer skill stubs. If true, this skill yields to a same-suffix plugin or MCP skill (`<plugin>:<name>` / `<server>:<name>`) when one is loaded. Stubs carrying this should be deleted once their canonical plugin/MCP skill ships, not maintained."
+			},
+			"created_by": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "@internal — provenance marker (e.g. dream-proposal)"
+			},
+			"improved_by": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "@internal — provenance marker (e.g. dream-proposal)"
+			},
+			"mcpServers": {
+				"description": "@internal"
+			},
+			"lspServers": {
+				"description": "@internal"
+			},
+			"agents": {
+				"description": "@internal"
+			},
+			"outputStyles": {
+				"description": "@internal"
+			},
+			"themes": {
+				"description": "@internal"
+			},
+			"workflows": {
+				"description": "@internal"
+			},
+			"channels": {
+				"description": "@internal"
+			},
+			"monitors": {
+				"description": "@internal"
+			},
+			"settings": {
+				"description": "@internal"
+			},
+			"experimental": {
+				"description": "@internal"
+			},
+			"dependencies": {
+				"description": "@internal"
+			},
+			"metadata": {
+				"description": "@internal"
+			}
+		},
+		"description": "Claude Code SKILL.md YAML frontmatter. Validates the structure of known fields; the object is intentionally permissive — unknown frontmatter keys are not schema errors (Claude Code still loads the skill), they are reported by the advisory skill-md/no-unknown-frontmatter rule."
+	}
+}

package/dist/contracts.js

@@ -1,11 +1,14 @@
 // Auto-generated from contracts/claude-code-contracts.json
-// Claude Code v2.1.144 — extracted 2026-05-19T01:06:35.112Z
+// Claude Code v2.1.148 — extracted 2026-05-22T07:13:45.210Z
 // Do not edit manually. Run: npm run generate-contracts
 export const TOOLS = new Set([
     "Agent",
     "AskUserQuestion",
     "Bash",
     "Config",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
     "Edit",
     "EnterPlanMode",
     "EnterWorktree",
@@ -16,10 +19,13 @@ export const TOOLS = new Set([
     "LSP",
     "ListMcpResources",
     "Mcp",
+    "Monitor",
     "NotebookEdit",
     "NotebookRead",
+    "PushNotification",
     "Read",
     "ReadMcpResource",
+    "RemoteTrigger",
     "SendMessage",
     "Skill",
     "SubscribeMcpResource",
@@ -164,6 +170,7 @@ export const MCP_SERVER_FIELDS = new Set([
     "headersHelper",
     "oauth",
     "role",
+    "timeout",
     "type",
     "url",
 ]);
@@ -316,7 +323,63 @@ export const SETTINGS_USER_FIELDS = new Set([
     "wslInheritsWindowsSettings",
 ]);
 export const SETTINGS_PROJECT_FIELDS = new Set([
+    "hooks",
     "permissions",
+    "sandbox",
+]);
+// Allowed sub-keys of the settings `permissions` object.
+export const PERMISSIONS_FIELDS = new Set([
+    "additionalDirectories",
+    "allow",
+    "ask",
+    "defaultMode",
+    "deny",
+    "disableAutoMode",
+    "disableBypassPermissionsMode",
+]);
+// Allowed sub-keys of the settings `sandbox` object.
+export const SANDBOX_FIELDS = new Set([
+    "allowUnsandboxedCommands",
+    "autoAllowBashIfSandboxed",
+    "bwrapPath",
+    "enableWeakerNestedSandbox",
+    "enableWeakerNetworkIsolation",
+    "enabled",
+    "excludedCommands",
+    "failIfUnavailable",
+    "filesystem",
+    "ignoreViolations",
+    "network",
+    "ripgrep",
+]);
+// Allowed sub-keys of `sandbox.network` and `sandbox.filesystem`.
+export const SANDBOX_NETWORK_FIELDS = new Set([
+    "allowAllUnixSockets",
+    "allowLocalBinding",
+    "allowMachLookup",
+    "allowManagedDomainsOnly",
+    "allowUnixSockets",
+    "allowedDomains",
+    "deniedDomains",
+    "httpProxyPort",
+    "socksProxyPort",
+    "tlsTerminate",
+]);
+export const SANDBOX_FILESYSTEM_FIELDS = new Set([
+    "allowManagedReadPathsOnly",
+    "allowRead",
+    "allowWrite",
+    "denyRead",
+    "denyWrite",
+]);
+// Valid values for `permissions.defaultMode`.
+export const PERMISSION_MODES = new Set([
+    "acceptEdits",
+    "auto",
+    "bypassPermissions",
+    "default",
+    "dontAsk",
+    "plan",
 ]);
 // Hand-curated denylist of tools declared in agent frontmatter that never
 // reach plugin-defined subagents at runtime. Source: tracked upstream bugs
@@ -326,4 +389,17 @@ export const PLUGIN_SUBAGENT_BLOCKED_TOOLS = new Set([
     "Glob",
     "Grep",
 ]);
+// Hand-curated named values for the frontmatter `effort` field. The Zod
+// schema types `effort` as a permissive scalar; the field's own describe()
+// string in the Claude Code bundle reads: "Thinking effort for the model:
+// `low`, `medium`, `high`, `max`, or an integer." — so a string `effort`
+// must be one of these, and a numeric `effort` must be an integer. (The
+// runtime effortLevel enum also has `xhigh`, but the frontmatter describe
+// string deliberately omits it; we follow the frontmatter contract.)
+export const EFFORT_LEVELS = new Set([
+    "low",
+    "medium",
+    "high",
+    "max",
+]);
 //# sourceMappingURL=contracts.js.map

package/dist/discovery.js

@@ -79,6 +79,25 @@ export function discoverArtifacts(targetPath, options) {
     }
     return artifacts;
 }
+/**
+ * Detect which Claude Code artifact types are present under the given paths.
+ * Returns the distinct types, sorted; excludes the `misplaced-file` diagnostic
+ * category (it marks a misplacement, not a kind of artifact a project owns).
+ * An empty result means the path holds no recognizable Claude Code artifacts.
+ *
+ * Powers the `--detect` CLI mode: a generic git hook can call it to decide
+ * whether a repository is a Claude Code plugin / config tree before linting.
+ */
+export function detectArtifactTypes(paths, ignore = []) {
+    const found = new Set();
+    for (const targetPath of paths) {
+        for (const a of discoverArtifacts(targetPath, { ignore })) {
+            if (a.artifactType !== "misplaced-file")
+                found.add(a.artifactType);
+        }
+    }
+    return [...found].sort();
+}
 function detectScope(filePath) {
     const resolved = resolve(filePath);
     // Inside ~/.claude/ itself (not a subdirectory project)
@@ -253,8 +272,9 @@ function discoverInDirectory(dir) {
  * 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).
+ * Ignores typical noise dirs (`node_modules`, `.git`, `dist`,
+ * `.claude/worktrees/` worktree copies, the plugin install cache's
+ * `.in_use` / `.orphaned_at` markers).
  */
 function findMisplacedFiles(pluginRoot) {
     const out = [];
@@ -270,6 +290,10 @@ function findMisplacedFiles(pluginRoot) {
             ignore: [
                 "**/node_modules/**",
                 "**/.git/**",
+                // `.claude/worktrees/` holds transient git-worktree copies
+                // (Claude Code's own EnterWorktree). Linting them re-reports
+                // every artifact once per worktree — pure noise.
+                "**/.claude/worktrees/**",
                 "**/dist/**",
                 "**/.in_use/**",
                 "**/.orphaned_at/**",

package/dist/fixers/settings-json.js

@@ -1,6 +1,8 @@
 import { formatJson } from "../utils/prettier.js";
 const TOP_LEVEL_KEY_ORDER = [
     "permissions",
+    "sandbox",
+    "hooks",
     "env",
     "plugins",
     "skipDangerousModePermissionPrompt",
@@ -30,15 +32,14 @@ export const settingsJsonFixer = {
                 ordered[key] = parsed[key];
             }
         }
-        // Sort permissions.allow and permissions.deny alphabetically
+        // Sort the permissions.allow / deny / ask rule arrays alphabetically
         const permissions = ordered["permissions"];
         if (typeof permissions === "object" && permissions !== null && !Array.isArray(permissions)) {
             const perms = permissions;
-            if (Array.isArray(perms["allow"])) {
-                perms["allow"] = [...perms["allow"]].sort();
-            }
-            if (Array.isArray(perms["deny"])) {
-                perms["deny"] = [...perms["deny"]].sort();
+            for (const list of ["allow", "deny", "ask"]) {
+                if (Array.isArray(perms[list])) {
+                    perms[list] = [...perms[list]].sort();
+                }
             }
         }
         return formatJson(JSON.stringify(ordered));

package/dist/index.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import sade from "sade";
 import pc from "picocolors";
 import { loadConfig, mergeCliRules } from "./config.js";
-import { discoverArtifacts } from "./discovery.js";
+import { discoverArtifacts, detectArtifactTypes } from "./discovery.js";
 import { formatHuman } from "./formatters/human.js";
 import { formatJson } from "./formatters/json.js";
 import { pluginJsonLinter } from "./linters/plugin-json.js";
@@ -110,19 +110,20 @@ const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.met
 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("--lint", "Lint artifacts and report issues (default)", false)
+    .option("--fix", "Auto-fix lint violations, then report remaining issues", false)
+    .option("--format", "Format all artifacts for consistent style (no lint output)", false)
     .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("--quiet", "Only show errors", false)
     .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("--list-rules", "Print all rules with their default severity and exit", false)
+    .option("--detect", "Print detected Claude Code artifact type(s), one per line; exit 0 if any, 1 if none", false)
+    .option("--fix-dry-run", "Run fixers but print diff instead of writing", false)
     .option("--init", "Copy default config to path (default: current directory)")
     .action(async (opts) => {
     // sade accepts variadic positional via opts._; default to ["."] when empty.
@@ -153,6 +154,21 @@ sade("claudecode-linter", true)
             }
             process.exit(0);
         }
+        if (opts.detect) {
+            const ignoreD = opts.ignore
+                ?.split(",")
+                .map((p) => p.trim())
+                .filter(Boolean) ?? [];
+            const types = detectArtifactTypes(paths, ignoreD);
+            if (opts.output === "json") {
+                process.stdout.write(`${JSON.stringify(types)}\n`);
+            }
+            else {
+                for (const t of types)
+                    process.stdout.write(`${t}\n`);
+            }
+            process.exit(types.length > 0 ? 0 : 1);
+        }
         const enableList = opts.enable
             ? opts.enable
                 .split(",")