@hasna/skills 0.10.72 → 0.10.74

package/docs/plugin-admission.md

@@ -195,7 +195,7 @@ plugin dependency declarations refuse because this validator does not resolve
 or review unselected external plugins.
 The request may declare `functionHooksEnv: "1"`; without that declaration the
 environment document is preserved unchanged. For a measured Claude 2.1.276,
-2.1.278, 2.1.282, 2.1.287, 2.1.293, 2.1.296 or 2.1.299 user-scoped install,
+2.1.278, 2.1.282, 2.1.287, 2.1.293, 2.1.296, 2.1.299 or 2.1.300 user-scoped install,
 `candidate.settingsMarketplaceSource: "directory"`
 explicitly declares the native settings registration. Skills derives
 `extraKnownMarketplaces[candidate.marketplace].source` from the exact frozen
@@ -249,6 +249,49 @@ structural refusal checks do not prove hook behavior. Recheck all preimages and
 candidate closure immediately before the first native mutation. The validator
 does not claim native install atomicity or crash recovery.
 
+The reviewed discovery inputs must bind every current Claude settings and
+registration source: the user settings, both project settings files,
+`known_marketplaces.json` and `installed_plugins.json`. A project
+`.claude/settings.json` or `.claude/settings.local.json` that the reviewed
+sources omit is exempt only when no other expected source (the target settings
+or the user settings) shares its path, and it is either:
+
+- absent, with a null preimage; or
+- present, and all of the following hold:
+  - its current bytes match its preimage SHA-256; a mismatch refuses with
+    `<name> preimage changed`;
+  - those exact bytes are strict UTF-8 without a byte-order mark and parse as
+    one JSON object within the native JSON witness limits (no comments,
+    trailing commas, trailing content or duplicate keys at any depth);
+  - none of `enabledPlugins`, `extraKnownMarketplaces`,
+    `additionalMarketplaces` or `skillOverrides` is present at any value,
+    including `null`, `{}` and `[]`;
+  - every top-level key is on the exemption allowlist with its type:
+    `permissions` (an object), `outputStyle`, `model`, `theme` and
+    `effortLevel` (strings), and `verbose` and `spinnerTipsEnabled` (booleans);
+  - `permissions` holds only `allow`, `deny` and `ask` (arrays of strings) and
+    `defaultMode` (a string).
+
+Anything else keeps the file required, including `env` (Claude reads
+`CLAUDE_CODE_PLUGIN_DIRS` from it), `hooks`, `permissions.additionalDirectories`
+(Claude loads skills, commands and agents from those directories), `__proto__`
+and unknown keys. The allowlist names settings reviewed as not configuring
+plugins, marketplaces, skills, hooks, extra directories or the environment. It
+does not prove that Claude cannot discover anything from the file; a setting
+joins it only after that review.
+
+This covers the permissions-only `~/.claude/settings.local.json` that Claude
+writes when it saves a permission rule during a user-scope install, whose
+project path is the Claude home. A present unreviewed file that fails the parse,
+discovery-key or allowlist checks refuses and names the reason. Each exempt file
+is re-checked against its exact preimage (still absent, or the same bytes) after
+discovery and again before the result, so a change, creation or removal in
+between refuses. The live hooks' project check still runs on top; it refuses
+any of the four discovery keys (`additionalMarketplaces` included, because
+Claude 2.1.300 rewrites it into `extraKnownMarketplaces` on every settings read)
+and its other project skill and hook settings. The user settings and both
+registries are never exempt.
+
 The optional release manifest witness binds the complete supplied release.json
 file bytes, path and SHA-256 in the request/receipt. Harnesses remains
 responsible for verifying that its release options correspond to every
@@ -270,8 +313,12 @@ skills hook capture-claude-installer --request /absolute/request.json --json
 The UTF-8 request is a bounded JSON object with schema
 `skills.claude-installer-capture/v1`, the exact configured `commandPath`, one
 fixed `operation` (`settings`, `marketplace-registry`, `managed-plugin-registry`,
-`path-bytes`, `discovery-directories`, `plugin-manifest`, or `candidate`), and
-only that operation's documented inputs. The result uses
+`path-bytes`, `discovery-directories`, `plugin-manifest`, `candidate`, or
+`discovery-binding`), and only that operation's documented inputs. The
+`discovery-binding` operation verifies the stored Claude discovery binding as a
+whole, including witnesses retained under an absent retired plugin-cache
+version; its request and result contract is in the README section
+"Claude installer witness CLI". The result uses
 `skills.claude-installer-capture-result/v1` and contains a Skills producer
 receipt plus the selected existing witness result. Candidate manifests include
 their plugin name, canonical path, `hashMode: "claude-plugin-manifest-v1"`, and
@@ -307,7 +354,8 @@ What the software currently enforces is narrower:
   non-null hash. A non-string `hooks` value and a `hooks` target outside the
   plugin root are refused. A manifest listed as `claude-plugin-manifest-v1`
   (the form Skills writes into the stored policy) or as `path-bytes` triggers
-  no hook-file requirement. Nothing else is required.
+  no hook-file requirement, and neither does a manifest the absent retired
+  version rule below retains. Nothing else is required.
 - A `hooks/hooks.json` that is absent at review time and appears later is
   detected if the review pins it with `sha256: null` or covers it with a
   reviewed `directories` membership witness on the plugin root or its `hooks/`
@@ -336,7 +384,7 @@ What the software currently enforces is narrower:
   `captureDiscoveryPathSources` (including the installer `path-bytes`
   operation) produces a `claude-plugin-orphaned-at-v1` witness, and a fresh
   explicit review converts a plain byte or `path-bytes` witness of it to that
-  form. The witness binds the marker's presence or absence, not its bytes or
+  form, unless the absent retired version rule below retains it. The witness binds the marker's presence or absence, not its bytes or
   inode. Every capture and check still requires a regular, non-symlink file
   owned by the current user, at most 32 bytes, matching `^[1-9][0-9]{12}$`.
   The name stays in `directories` membership, so other added or removed names
@@ -345,17 +393,20 @@ What the software currently enforces is narrower:
   that binds the marker's bytes keeps that meaning and needs one fresh review.
 - An entirely absent retired Claude version root exempts only its plain byte
   sources (`hashMode` omitted or `"bytes"`, with no `format`, `fields` or
-  `managedPlugins`) and a present `claude-plugin-orphaned-at-v1` marker. Such a
-  source with a non-null `sha256` is also the only
+  `managedPlugins`), its `.claude-plugin/plugin.json` as a
+  `claude-plugin-manifest-v1` witness and a present
+  `claude-plugin-orphaned-at-v1` marker. Such a source with a non-null
+  `sha256` is also the only
   thing that identifies the root, and the root qualifies only while it stays
   entirely absent and the reviewed settings and registry select a different,
   verified version. Every other source under that root is re-hashed as usual,
   and one whose file existed at review no longer matches its hash, so the
-  check refuses. That includes the plugin manifest in the
-  `claude-plugin-manifest-v1` form Skills stores, so a stored review that lists
-  the retired version's manifest refuses until a fresh review replaces it. A
-  `directories` witness that covers the retired root is not exempt either. If
-  the root reappears, its sources are checked again.
+  check refuses. A `directories` witness that covers the retired root is not
+  exempt either. An explicit review (`--discovery-inputs`) keeps each exempt
+  source exactly as listed: it does not project a byte-witnessed manifest,
+  require its hook files or convert a byte-witnessed marker, so a historical
+  byte witness keeps its meaning. If the root reappears, its sources are
+  checked again.
 - It is detection-only. Later checks re-hash the stored sources and re-walk any
   reviewed `directories` witnesses. Drift makes the
   Skills hooks refuse with `NATIVE_SKILL_DRIFT`; it does not stop, unload or

package/docs/skill-standard.md

@@ -91,10 +91,24 @@ existing Codewith conventions):
   `package.json`, a non-empty `bin`, and `src/index.ts`. `skills run` executes it.
 - `kind: instruction` — a `SKILL.md`-primary prose skill for coding agents.
   `package.json`, `bin`, and `src/` are all optional. Instruction skills may still
-  bundle optional helper scripts (a `bin`/`src` is permitted, not forbidden), but
-  they are consumed by agents via `SKILL.md`, not executed. `skills run` on an
-  instruction skill returns a clear "not runnable — instruction skill" error
-  instead of executing a stub.
+  bundle optional helper scripts (a `bin`/`src` is permitted, not forbidden) and
+  are consumed by agents via `SKILL.md`. `skills run` refuses a prose-only
+  instruction skill with a clear "not runnable — instruction skill" error instead
+  of executing a stub.
+- An instruction skill may instead declare the one operation it ships: the first
+  `commands` entry, naming its helper, together with an explicit `runtime`
+  contract. `skills run` then executes exactly that declared entrypoint from the
+  selected bundle — the same immutable object, digest receipt, argument,
+  timeout, output and no-ambient-credential contract an executable skill gets —
+  and still refuses the skill when it declares no operation or no runtime. The
+  declared command entry is the authority: it must be a regular file in the
+  selected bundle, and a `runtime.entrypoint` that disagrees with it is an
+  inconsistent declaration that refuses (`LOCAL_ENTRYPOINT_MISMATCH`) rather than
+  running the other file. A declared entry missing from the bundle refuses
+  (`LOCAL_ENTRYPOINT_MISSING`) and is never substituted, and the mutable
+  authoring corpus is never executed. Executable skills keep their own
+  precedence (`runtime.entrypoint`, then `package.json` bin) unchanged, and cloud
+  execution keeps requiring an executable skill version.
 
 New scaffolds always record their selected kind. Legacy local readers retain
 their executable fallback, while the legacy publication API retains its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.10.72",
+  "version": "0.10.74",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {