claudecode-linter 2.1.148 → 2.1.149

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

@@ -23,6 +23,17 @@ Or run directly:
 npx claudecode-linter ~/projects/my-plugin/
 ```
 
+Or build it from a clone of this repository — there is no `dist/` until you build:
+
+```bash
+git clone https://github.com/retif/claudecode-linter
+cd claudecode-linter
+npm ci && npm run build      # install dependencies, compile to dist/
+node dist/index.js path/to/plugin/
+```
+
+Commands elsewhere in this README are written as `claudecode-linter …` (the global / `npx` install); from a clone, that is `node dist/index.js …`.
+
 ## Usage
 
 ### Lint
@@ -130,9 +141,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 |
@@ -211,6 +222,82 @@ Formatting is powered by [prettier](https://prettier.io/) for consistent JSON an
 | 1 | Lint errors found |
 | 2 | Fatal error |
 
+## Running on untrusted plugins
+
+claudecode-linter is a **static analyzer** — it parses and validates the artifacts it inspects, it never executes them. There is no `eval`, no `child_process`, no declared hooks are run, and no MCP servers are spawned. Linting **trusted** code needs no special isolation.
+
+For **untrusted** plugins — especially with `--fix`, which writes files back to disk — run the linter sandboxed. claudecode-linter is verified to run correctly fully confined: no network, a read-only root filesystem, all Linux capabilities dropped, `no-new-privileges`, a non-root UID, and only the target directory mounted.
+
+### The Docker image
+
+Two multi-arch (`linux/amd64`, `linux/arm64`) images are published to the GitHub Container Registry — two separate packages, each with its own `:latest` rolling tag and `:<version>` tag:
+
+| Image | Built from | Notes |
+|-------|-----------|-------|
+| `ghcr.io/retif/node-claudecode-linter` | `Dockerfile` — `node:24-alpine` | default |
+| `ghcr.io/retif/bun-claudecode-linter` | `Dockerfile.compile` — `bun build --compile` single executable | smaller (~44 MB compressed) |
+
+**Pull a published image:**
+
+```bash
+docker pull ghcr.io/retif/node-claudecode-linter   # default (node:24-alpine)
+docker pull ghcr.io/retif/bun-claudecode-linter    # smaller (bun --compile)
+```
+
+**Or build it locally** from a checkout of this repo:
+
+```bash
+docker build -t node-claudecode-linter .                       # default (Dockerfile)
+docker build -f Dockerfile.compile -t bun-claudecode-linter .   # smaller variant
+```
+
+Both images behave identically. The `docker run` recipes below use `ghcr.io/retif/node-claudecode-linter`; substitute `ghcr.io/retif/bun-claudecode-linter` or a locally-built tag as you prefer.
+
+### Sandboxed invocation
+
+**Docker — read-only lint:**
+
+```bash
+docker run --rm --network none --read-only --tmpfs /tmp \
+  --user "$(id -u):$(id -g)" --cap-drop ALL --security-opt no-new-privileges \
+  -v "$PWD":/work:ro -w /work  ghcr.io/retif/node-claudecode-linter  /work
+```
+
+**Docker — `--fix`:** the mount must be read-write so fixes can be written back. Otherwise identical, plus the `--fix` flag:
+
+```bash
+docker run --rm --network none --read-only --tmpfs /tmp \
+  --user "$(id -u):$(id -g)" --cap-drop ALL --security-opt no-new-privileges \
+  -v "$PWD":/work -w /work  ghcr.io/retif/node-claudecode-linter  --fix /work
+```
+
+All four recipes here are verified. On Linux without Docker, [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`) gives the equivalent boundary: `--unshare-all` cuts network (confirmed: `ECONNREFUSED` inside the sandbox), and nothing is writable except — for `--fix` — the target directory (confirmed: a write outside it is refused).
+
+**bwrap — read-only (lint):**
+
+```bash
+bwrap \
+  --ro-bind / / --dev /dev --proc /proc --tmpfs /tmp \
+  --unshare-all --die-with-parent \
+  --chdir "$PWD" \
+  claudecode-linter "$PWD"
+```
+
+**bwrap — read-write (`--fix`):** the later `--bind` overrides the read-only root for just the target directory:
+
+```bash
+bwrap \
+  --ro-bind / / --bind "$PWD" "$PWD" \
+  --dev /dev --proc /proc --tmpfs /tmp \
+  --unshare-all --die-with-parent \
+  --chdir "$PWD" \
+  claudecode-linter --fix "$PWD"
+```
+
+`--ro-bind / /` can be replaced with explicit per-path `--ro-bind` entries (e.g. just `/usr`, `/nix`, and the target) for least-read-authority.
+
+See [`SECURITY.md`](SECURITY.md) for the full security model, the audited input-handling hardening, and how to report a vulnerability.
+
 ## Versioning
 
 This linter's version tracks the Claude Code version it was extracted from:

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"
 			}
 		},