claudecode-linter 2.1.148-patch.1 → 2.1.148-patch.2

package/.claudecode-lint.defaults.yaml

@@ -32,6 +32,10 @@ rules:
   skill-md/description-max-length: error
   skill-md/description-no-angle-brackets: error
   skill-md/description-trigger-phrases: warning
+  skill-md/model-valid: warning
+  skill-md/effort-valid: warning
+  skill-md/allowed-tools-valid: warning
+  skill-md/frontmatter-field-type: warning
   skill-md/no-unknown-frontmatter: warning
   skill-md/body-word-count: warning
   skill-md/body-has-headers: info
@@ -45,6 +49,9 @@ rules:
   agent-md/description-routing-guidance: warning
   agent-md/model-required: error
   agent-md/model-valid: warning
+  agent-md/permission-mode-valid: warning
+  agent-md/effort-valid: warning
+  agent-md/max-turns-valid: warning
   agent-md/color-required: error
   agent-md/color-valid: warning
   agent-md/system-prompt-present: error
@@ -55,11 +62,16 @@ rules:
   command-md/valid-frontmatter: error
   command-md/schema-valid: error
   command-md/description-required: error
+  command-md/name-format: warning
+  command-md/model-valid: warning
+  command-md/effort-valid: warning
+  command-md/frontmatter-field-type: warning
   command-md/allowed-tools-valid: warning
   command-md/body-present: warning
 
   # ── hooks.json ───────────────────────────────────────────
   hooks-json/valid-json: error
+  hooks-json/schema-valid: error
   hooks-json/root-hooks-key: error
   hooks-json/valid-event-names: error
   hooks-json/hook-type-required: error
@@ -98,6 +110,7 @@ rules:
   # ── mcp.json ─────────────────────────────────────────────
   mcp-json/scope-file-name: warning
   mcp-json/valid-json: error
+  mcp-json/schema-valid: error
   mcp-json/servers-required: error
   mcp-json/servers-object: error
   mcp-json/server-name-kebab: info

package/README.md

@@ -130,9 +130,9 @@ No issues found.
 | Type | Files | Rules |
 |------|-------|-------|
 | plugin-json | `.claude-plugin/plugin.json` | 13 |
-| skill-md | `skills/*/SKILL.md` | 12 |
-| agent-md | `agents/*.md` | 17 |
-| command-md | `commands/*.md` | 6 |
+| skill-md | `skills/*/SKILL.md` | 16 |
+| agent-md | `agents/*.md` | 20 |
+| command-md | `commands/*.md` | 10 |
 | hooks-json | `hooks/hooks.json` | 9 |
 | settings-json | `.claude-plugin/settings.json` | 25 |
 | mcp-json | `.claude-plugin/mcp.json` | 16 |

package/contracts/agent-frontmatter.schema.json

@@ -1,18 +1,60 @@
 {
 	"extractedFromClaudeCodeVersion": "2.1.146",
-	"extractedAt": "2026-05-21T21:04:24.810Z",
+	"extractedAt": "2026-05-22T08:49:59.765Z",
 	"schema": {
 		"$schema": "https://json-schema.org/draft/2020-12/schema",
 		"title": "Claude Code agent .md frontmatter",
 		"type": "object",
 		"properties": {
 			"name": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Agent identifier. Required — this is how the Agent tool and `--agent` flag address it."
 			},
 			"description": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "When to use this agent. Required — shown in the Agent tool listing."
 			},
 			"model": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Model override for this agent. Use `inherit` to match the spawning conversation."
 			},
 			"tools": {
@@ -70,12 +112,54 @@
 				"description": "Tools removed from the default set. Ignored if `tools` is set."
 			},
 			"color": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "@internal — display color in the agents UI"
 			},
 			"effort": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Thinking effort: `low`, `medium`, `high`, `max`, or an integer."
 			},
 			"permissionMode": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Permission mode the agent runs in."
 			},
 			"mcpServers": {
@@ -126,15 +210,71 @@
 				"description": "Skills preloaded for this agent."
 			},
 			"initialPrompt": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Auto-submitted first message when this agent runs as the main session (via `--agent` or settings). Not read when spawned as a subagent."
 			},
 			"memory": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Memory scope: `user`, `project`, or `local`."
 			},
 			"background": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "If true, the agent runs in the background by default."
 			},
 			"isolation": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Filesystem isolation: `worktree` runs in a temporary git worktree."
 			}
 		},

package/contracts/command-frontmatter.schema.json

@@ -1,18 +1,60 @@
 {
 	"extractedFromClaudeCodeVersion": "2.1.146",
-	"extractedAt": "2026-05-21T21:04:24.812Z",
+	"extractedAt": "2026-05-22T08:49:59.767Z",
 	"schema": {
 		"$schema": "https://json-schema.org/draft/2020-12/schema",
 		"title": "Claude Code command .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": {
@@ -43,6 +85,20 @@
 				"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": {
@@ -73,18 +129,88 @@
 				"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"
 			}
 		},

package/contracts/hooks.schema.json

@@ -0,0 +1,275 @@
+{
+	"extractedFromClaudeCodeVersion": "2.1.146",
+	"extractedAt": "2026-05-22T08:16:43.683Z",
+	"schema": {
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		"title": "Claude Code hooks.json",
+		"type": "object",
+		"properties": {
+			"hooks": {
+				"type": "object",
+				"additionalProperties": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"matcher": {
+								"type": "string",
+								"description": "String pattern to match (e.g. tool names like \"Write\")"
+							},
+							"hooks": {
+								"type": "array",
+								"items": {
+									"oneOf": [
+										{
+											"type": "object",
+											"properties": {
+												"type": {
+													"const": "command",
+													"description": "Shell command hook type"
+												},
+												"command": {
+													"type": "string",
+													"description": "Shell command to execute"
+												},
+												"args": {
+													"type": "array",
+													"items": {
+														"type": "string"
+													},
+													"description": "Argument list for exec form. When present, `command` is resolved as \"+\"an executable and spawned directly with these arguments \\u2014 no shell. \"+\"Path placeholders like ${CLAUDE_PLUGIN_ROOT} are substituted per-element as plain strings, so paths with quotes, $, or backticks never reach a shell parser. When absent, `command` runs through a shell (bash on POSIX, PowerShell on Windows without Git Bash)."
+												},
+												"if": {
+													"type": "string",
+													"description": "Permission rule syntax to filter when this hook runs (e.g., \"Bash(git *)\"). Only runs if the tool call matches the pattern. Avoids spawning hooks for non-matching commands."
+												},
+												"shell": {
+													"enum": [
+														"bash",
+														"powershell"
+													],
+													"description": "Shell interpreter. 'bash' uses your $SHELL (bash/zsh/sh); 'powershell' uses pwsh. Defaults to bash (powershell on Windows without Git Bash)."
+												},
+												"timeout": {
+													"type": "number",
+													"description": "Timeout in seconds for this specific command"
+												},
+												"statusMessage": {
+													"type": "string",
+													"description": "Custom status message to display in spinner while hook runs"
+												},
+												"once": {
+													"type": "boolean",
+													"description": "If true, hook runs once and is removed after execution"
+												},
+												"async": {
+													"type": "boolean",
+													"description": "If true, hook runs in background without blocking"
+												},
+												"asyncRewake": {
+													"type": "boolean",
+													"description": "If true, hook runs in background and wakes the model on exit code 2 (blocking error). Implies async."
+												},
+												"rewakeMessage": {
+													"type": "string",
+													"minLength": 1,
+													"description": "@internal Custom prefix for the system-reminder shown to the model when an asyncRewake hook exits with code 2. The hook output is appended after this prefix."
+												},
+												"rewakeSummary": {
+													"type": "string",
+													"minLength": 1,
+													"description": "@internal One-line summary shown to the user in the terminal when an asyncRewake hook exits with code 2. Defaults to \"Stop hook feedback\"."
+												}
+											},
+											"required": [
+												"type",
+												"command"
+											]
+										},
+										{
+											"type": "object",
+											"properties": {
+												"type": {
+													"const": "prompt",
+													"description": "LLM prompt hook type"
+												},
+												"prompt": {
+													"type": "string",
+													"description": "Prompt to evaluate with LLM. Use $ARGUMENTS placeholder for hook input JSON."
+												},
+												"if": {
+													"type": "string",
+													"description": "Permission rule syntax to filter when this hook runs (e.g., \"Bash(git *)\"). Only runs if the tool call matches the pattern. Avoids spawning hooks for non-matching commands."
+												},
+												"timeout": {
+													"type": "number",
+													"description": "Timeout in seconds for this specific prompt evaluation"
+												},
+												"model": {
+													"type": "string",
+													"description": "Model to use for this prompt hook (e.g., \"claude-sonnet-4-6\"). If not specified, uses the default small fast model."
+												},
+												"continueOnBlock": {
+													"type": "boolean",
+													"description": "`Sets the continue value for the decision:\"block\" produced when ok is false. Default false (turn ends). Whether continue:true lets the turn proceed depends on the event's decision:\"block\" semantics. On PostToolUse, the reason is fed back to Claude and the turn continues.`"
+												},
+												"statusMessage": {
+													"type": "string",
+													"description": "Custom status message to display in spinner while hook runs"
+												},
+												"once": {
+													"type": "boolean",
+													"description": "If true, hook runs once and is removed after execution"
+												}
+											},
+											"required": [
+												"type",
+												"prompt"
+											]
+										},
+										{
+											"type": "object",
+											"properties": {
+												"type": {
+													"const": "agent",
+													"description": "Agentic verifier hook type"
+												},
+												"prompt": {
+													"type": "string",
+													"description": "Prompt describing what to verify (e.g. \"Verify that unit tests ran and passed.\"). Use $ARGUMENTS placeholder for hook input JSON."
+												},
+												"if": {
+													"type": "string",
+													"description": "Permission rule syntax to filter when this hook runs (e.g., \"Bash(git *)\"). Only runs if the tool call matches the pattern. Avoids spawning hooks for non-matching commands."
+												},
+												"timeout": {
+													"type": "number",
+													"description": "Timeout in seconds for agent execution (default 60)"
+												},
+												"model": {
+													"type": "string",
+													"description": "Model to use for this agent hook (e.g., \"claude-sonnet-4-6\"). If not specified, uses Haiku."
+												},
+												"statusMessage": {
+													"type": "string",
+													"description": "Custom status message to display in spinner while hook runs"
+												},
+												"once": {
+													"type": "boolean",
+													"description": "If true, hook runs once and is removed after execution"
+												}
+											},
+											"required": [
+												"type",
+												"prompt"
+											]
+										},
+										{
+											"type": "object",
+											"properties": {
+												"type": {
+													"const": "http",
+													"description": "HTTP hook type"
+												},
+												"url": {
+													"type": "string",
+													"format": "uri",
+													"description": "URL to POST the hook input JSON to"
+												},
+												"if": {
+													"type": "string",
+													"description": "Permission rule syntax to filter when this hook runs (e.g., \"Bash(git *)\"). Only runs if the tool call matches the pattern. Avoids spawning hooks for non-matching commands."
+												},
+												"timeout": {
+													"type": "number",
+													"description": "Timeout in seconds for this specific request"
+												},
+												"headers": {
+													"type": "object",
+													"additionalProperties": {
+														"type": "string"
+													},
+													"description": "Additional headers to include in the request. Values may reference environment variables using $VAR_NAME or ${VAR_NAME} syntax (e.g., \"Authorization\": \"Bearer $MY_TOKEN\"). Only variables listed in allowedEnvVars will be interpolated."
+												},
+												"allowedEnvVars": {
+													"type": "array",
+													"items": {
+														"type": "string"
+													},
+													"description": "Explicit list of environment variable names that may be interpolated in header values. Only variables listed here will be resolved; all other $VAR references are left as empty strings. Required for env var interpolation to work."
+												},
+												"statusMessage": {
+													"type": "string",
+													"description": "Custom status message to display in spinner while hook runs"
+												},
+												"once": {
+													"type": "boolean",
+													"description": "If true, hook runs once and is removed after execution"
+												}
+											},
+											"required": [
+												"type",
+												"url"
+											]
+										},
+										{
+											"type": "object",
+											"properties": {
+												"type": {
+													"const": "mcp_tool",
+													"description": "MCP tool hook type"
+												},
+												"server": {
+													"type": "string",
+													"description": "Name of an already-configured MCP server to invoke"
+												},
+												"tool": {
+													"type": "string",
+													"description": "Name of the tool on that server to call"
+												},
+												"input": {
+													"type": "object",
+													"additionalProperties": {},
+													"description": "Arguments passed to the MCP tool. String values support ${path} interpolation from the hook input JSON (e.g. \"${tool_input.file_path}\")."
+												},
+												"if": {
+													"type": "string",
+													"description": "Permission rule syntax to filter when this hook runs (e.g., \"Bash(git *)\"). Only runs if the tool call matches the pattern. Avoids spawning hooks for non-matching commands."
+												},
+												"timeout": {
+													"type": "number",
+													"description": "Timeout in seconds for this specific tool call"
+												},
+												"statusMessage": {
+													"type": "string",
+													"description": "Custom status message to display in spinner while hook runs"
+												},
+												"once": {
+													"type": "boolean",
+													"description": "If true, hook runs once and is removed after execution"
+												}
+											},
+											"required": [
+												"type",
+												"server",
+												"tool"
+											]
+										}
+									]
+								},
+								"description": "List of hooks to execute when the matcher matches"
+							}
+						},
+						"required": [
+							"hooks"
+						]
+					}
+				}
+			}
+		},
+		"required": [
+			"hooks"
+		],
+		"description": "Claude Code hooks/hooks.json. The `hooks` key maps hook-event names (PreToolUse, PostToolUse, …) to arrays of matcher entries, each holding a list of hook definitions (command / prompt / http / agent / mcp_tool). Same shape as the `hooks` block inside settings.json. Validates the structure of known fields; unknown hook fields are not schema errors — the advisory hooks-json hand-written rules report those."
+	}
+}