@hasna/skills 0.10.72 → 0.10.73

package/README.md

@@ -113,6 +113,27 @@ skills hook install --selection-profile default --json
 skills hook install --selection-profile default --apply --json
 ```
 
+`--include-vendor` resolves configured plugin discovery, so it needs a reviewed
+`--discovery-inputs` file when a configured plugin declares hooks. Without it,
+`skills migrate native --include-unmanaged` archives user and project copies
+only. Migration never archives Codex system skills (`.codex/skills/.system`),
+even with `--include-vendor`. Codex refreshes its OpenAI marketplace plugin
+caches on its own; retire those copies with a Codex `[[skills.config]]` rule
+(`name = "<plugin>:<skill>"` or the exact `path` of the `SKILL.md`, with
+`enabled = false`) rather than by archiving. The live Codex prompt hook accepts
+a name rule only for a copy with no Hasna marker, its remote install receipt, a
+refresh-safe plugin and no rule that enables it. Other checks (`skills hook
+install` reusing a saved review, `skills hook trust`) do not accept a
+hand-added name rule; for them, and for system skills, run `skills hook install
+--agent codex --discovery-inputs <file> --apply` with a fresh discovery review
+(no `--discovery-inputs` on an automatic binding; add a fresh
+`--codex-native-catalog <file>` for a plugin Skills has enrolled), which writes
+and records the disables. Run the same refresh after editing `config.toml` when
+the binding's recorded configuration witness counts the edit: on automatic
+bindings, after removing a rule that enables skills, and on reviewed bindings
+whose witness counts disable rows. A `NATIVE_SKILL_DRIFT` refusal names the
+step for each copy it lists, including that follow-up.
+
 Without `--agent`, hook installation selects configured or detected consumers:
 existing managed bridge bindings, provider-specific home configuration, or an
 installed native CLI found through PATH. Detection reads metadata and never
@@ -264,8 +285,8 @@ discovery-witness changes such a refresh provably makes:
   unknown keys refuse. There is no `hooks`, `commands` or `agents` directory, no
   `hooks.json` or `.mcp.json` (names compared without regard to case), no root,
   `.claude-plugin` or `.cursor-plugin` manifest, no link
-  and no `SKILL.md` that the inventory cannot see (below a dot-named or
-  `node_modules` directory, or nested in another skill). One exception keeps
+  and no `SKILL.md` below a dot-named or `node_modules` directory, or nested
+  in another skill. One exception keeps
   today's vendor plugins working: every current OpenAI vendor plugin declares
   its connector as `apps = "./.app.json"`, so exactly that declaration is
   allowed when `.app.json` is a regular file of at most 1 MiB, strict UTF-8, that
@@ -541,6 +562,20 @@ is bounded to 20,000 discovery entries and 4 MiB of UTF-8 path metadata before
 directory entries are retained or sorted. Unsupported special files and unsafe
 directory links are refused.
 
+Codex 0.162.1 loads `SKILL.md` files below `node_modules` inside its skill
+roots, so Codex inventory and the prompt guard walk `node_modules` in
+`~/.codex/skills`, `~/.agents/skills`, each project's `.codex/skills` and
+`.agents/skills` and configured plugin skill roots. In `~/.codex/plugins/cache`
+they walk it only where it can lie in a plugin skill root: below a version's
+default `skills` directory or a manifest-declared skills path, or as a
+marketplace, plugin or version directory named `node_modules`; an unreadable
+manifest walks every `node_modules` in its version. Dot-named directories such
+as `node_modules/.pnpm`, a plugin version's own dependencies and any
+`node_modules` outside a skill root stay unscanned, because Codex does not load
+them; other agents' roots keep skipping `node_modules`. Depth limits are
+unchanged: Codex reads six directory levels below a root, and an ordinary root
+records a skill four levels down and refuses anything deeper.
+
 Native archives persist a version 2 recovery journal before moving payloads;
 `migrate native --json --apply` returns its `receiptPath`. The journal records
 every source, archive path, expected hash, and move status, then marks successful
@@ -702,6 +737,25 @@ receipt permits only verified registry/cache transitions. See
 [plugin admission](docs/plugin-admission.md) for the package, review and runtime
 contracts; these commands do not change live agent registrations or settings.
 
+The read-only `skills hook review-claude-candidate` check requires its reviewed
+discovery inputs to bind the user settings, both project settings files and
+both plugin registries. A project `.claude/settings.json` or
+`.claude/settings.local.json` that the review omits is exempt only when no other
+expected source shares its path and it is either absent, or present with exact
+preimage bytes that parse strictly as one JSON object (strict UTF-8, no
+byte-order mark, comments, trailing content or duplicate keys) and carry only
+allowlisted settings: `permissions` with `allow`, `deny`, `ask` and
+`defaultMode`, plus `outputStyle`, `model`, `theme`, `effortLevel`, `verbose`
+and `spinnerTipsEnabled`. Any discovery key (`enabledPlugins`,
+`extraKnownMarketplaces`, `additionalMarketplaces`, `skillOverrides`), `env`,
+`hooks`, `permissions.additionalDirectories` or unknown key keeps the file
+required. The allowlist is a reviewed list of settings, not a proof that Claude
+cannot discover anything from the file. This admits the permissions-only
+`~/.claude/settings.local.json` that Claude writes when it saves a permission
+rule. Each exempt file is re-checked against its exact preimage until the
+result; user settings and the registries are never exempt. See
+[prospective Claude candidate review](docs/plugin-admission.md#prospective-claude-candidate-review).
+
 If your home `.claude` or `.codex` directory intentionally links to another
 directory within your home, add `--allow-root-aliases` to hook installation and
 native migration. The plan records and rechecks the exact link and target;
@@ -1009,6 +1063,209 @@ reports an incomplete outcome, inspect `sessions show` and the preserved
 operation receipt before retrying. The archive contains both original and
 prepared bytes even if the final receipt write fails.
 
+### Claude installer witness CLI (`capture-claude-installer`)
+
+```text
+skills hook capture-claude-installer --request /absolute/request.json --json
+```
+
+Installers obtain Skills-owned witnesses through the configured Skills command
+instead of reimplementing them. Every request is a JSON object of at most
+64 KiB with exactly the keys of one operation: `schema`
+(`skills.claude-installer-capture/v1`), `commandPath` (the normalized absolute
+path of the configured Skills command), `operation`, and that operation's
+inputs. The command checks that `commandPath` resolves to this installed
+`@hasna/skills` CLI and runtime, before and after the operation, and prints
+one receipt on stdout with exit status 0:
+
+```json
+{
+  "schema": "skills.claude-installer-capture-result/v1",
+  "producer": {
+    "schema": "skills.cli-producer-identity/v1",
+    "configuredCommandPath": "<commandPath>",
+    "physicalLauncher": { "path": "<absolute>", "sha256": "<64 hex>" },
+    "runtimeEntry": { "path": "<absolute>", "sha256": "<64 hex>" },
+    "runtime": { "path": "<absolute>", "sha256": "<64 hex>" },
+    "package": { "name": "@hasna/skills", "version": "<x.y.z>", "manifestSha256": "<64 hex>" }
+  },
+  "operation": "<operation>",
+  "result": {}
+}
+```
+
+A refusal prints nothing on stdout, exits 1 and writes one line to stderr,
+`CODE: fixed text`, which never echoes request or file contents. The
+per-file operations (`settings`, `marketplace-registry`,
+`managed-plugin-registry`, `path-bytes`, `discovery-directories`,
+`plugin-manifest` and `candidate`) are described in
+[docs/plugin-admission.md](docs/plugin-admission.md#claude-installer-witness-cli).
+
+#### Verify the stored Claude discovery binding (`discovery-binding`)
+
+`discovery-binding` checks the Claude discovery binding stored in the Skills
+policy (`bridge.discovery.claude` in `agent-policy.json`) with the discovery
+verification the managed prompt hook runs on it: the root alias recheck,
+`verifyAgentDiscovery` and, for an automatic binding, the automatic closure
+check. It then reports every stored witness. An installer calls it once
+instead of re-capturing each stored witness. Per-file capture requires every
+file to exist, so it refuses witnesses that Skills keeps on purpose after
+Claude deletes a retired plugin-cache version; this operation reports those as
+`retained-absent`. It does not check the bridge files, hook commands or
+project-directory settings, which the hook checks separately.
+
+The request has exactly these keys:
+
+```json
+{
+  "schema": "skills.claude-installer-capture/v1",
+  "commandPath": "/home/me/.local/bin/skills",
+  "operation": "discovery-binding",
+  "policyPath": "/home/me/.hasna/skills/agent-policy.json"
+}
+```
+
+`policyPath` must equal `agent-policy.json` in the data directory the installed
+package resolves (`$HASNA_SKILLS_DIR`, default `~/.hasna/skills`), as for the
+`candidate` operation.
+
+The receipt's `result`:
+
+```json
+{
+  "schema": "skills.claude-discovery-binding-verification/v1",
+  "ok": true,
+  "policySha256": "<64 hex>",
+  "discoverySha256": "<64 hex>",
+  "agent": "claude",
+  "method": "reviewed",
+  "rootCount": 2,
+  "sources": [
+    { "index": 0, "path": "/home/me/.claude/settings.json", "hashMode": "claude-settings-v4", "format": null, "sha256": "<64 hex>", "status": "current" },
+    { "index": 3, "path": "/home/me/.claude/plugins/cache/market/plugin/1.0.0/.claude-plugin/plugin.json", "hashMode": "claude-plugin-manifest-v1", "format": null, "sha256": "<64 hex>",
+      "status": "retained-absent", "retention": { "rule": "absent-retired-claude-version", "root": "/home/me/.claude/plugins/cache/market/plugin/1.0.0", "witness": "claude-plugin-manifest-v1" } }
+  ],
+  "directories": [ { "index": 0, "path": "/home/me/.claude/plugins/cache/market/plugin/2.0.0", "status": "current" } ],
+  "failures": []
+}
+```
+
+- `policySha256` is the SHA-256 of the exact policy file bytes that were
+  verified. It is the value a prospective review request passes as
+  `skills.policySha256`. The policy is read again before the result is
+  returned; if it changed, the request is refused.
+- `discoverySha256` is `hashClaudeDiscoveryBinding` of the stored binding, the
+  same digest the `candidate` operation returns.
+- `agent`, `method` (`reviewed` or `automatic`) and `rootCount` (the number of
+  stored discovery roots) come from the stored binding.
+- `sources` has one row per stored source, in stored order. `index` is the
+  position in `bridge.discovery.claude.sources`. `path`, `hashMode`, `format`
+  and `sha256` repeat the stored values: `hashMode` is `null` for a legacy
+  full-file witness without a mode, `format` is `null` unless the source is a
+  field projection (Claude reviews also keep the automatic `json` projection of
+  `settings.json`), and a `null` `sha256` pins absence. `status` is one of:
+  - `current`: the source's own witness reproduces the stored digest now.
+  - `retained-absent`: the file was not read, because the
+    `absent-retired-claude-version` rule keeps its stored digest. The rule
+    holds when the whole version directory `retention.root`
+    (`<...>/.claude/plugins/cache/<marketplace>/<plugin>/<version>`) is absent,
+    the reviewed witnesses of `settings.json` and
+    `plugins/installed_plugins.json` are current, settings enable the plugin
+    and no settings hook names that directory, every registration of the
+    plugin is a valid user or project row for one existing sibling version in
+    the same plugin directory (with a user row among them), no registration of
+    any plugin points into or contains the absent directory, and the sibling's
+    `.claude-plugin/plugin.json` is bound and current. It applies only to
+    reviewed bindings. `retention.witness` names the retained witness class:
+    `bytes` (a full byte witness, `hashMode` `null` or `bytes`),
+    `claude-plugin-manifest-v1` or `claude-plugin-orphaned-at-v1` (the typed
+    presence witness of a version-root `.orphaned_at` marker). No other
+    witness is retained: `path-bytes`, field projections and typed settings
+    or registry witnesses stay checked. Settings and registry files are
+    never retained.
+  - `drift`, with `reason`: `MISSING` (the path is absent and the rule does
+    not retain it), `APPEARED` (the stored witness pins absence and the path
+    now exists), `CHANGED` (the path exists but its witness does not
+    reproduce the stored digest or refuses the current file, for example
+    edited settings or a symlink), `MARKER_INVALID` (a
+    `claude-plugin-orphaned-at-v1` marker exists but is not a valid Claude
+    marker; see below) or `REFUSED` (the path's presence could not be
+    determined).
+- `directories` has one row per stored directory membership witness, with
+  `status` `current`, or `drift` with `reason` `MEMBERSHIP_CHANGED` or
+  `REFUSED`.
+- `failures` lists every drifted source and directory as
+  `{ "kind": "source" | "directory", "index", "path", "reason" }`, followed by
+  `{ "kind": "binding", "reason": "DISCOVERY_REFUSED" }` whenever the hook's
+  own discovery verification refuses the binding. That covers checks no single
+  row shows, such as a changed root alias, a retired directory that reappeared
+  during verification or an invalid witness combination.
+- `ok` is `true` only when `failures` is empty: the hook's verification
+  accepts the binding, every source is `current` or `retained-absent` and
+  every directory is `current`.
+
+`ok: false` is a completed verification and still exits 0, so the caller
+reads which witnesses drifted and why. Installers must require `ok === true`.
+To bind the result, compare each `sources` row (`index`, `path`, `hashMode`,
+`format`, `sha256`) with the binding they read themselves, compare
+`discoverySha256` with the `candidate` capture and `policySha256` with the
+policy bytes they review, and repeat the call immediately before the first
+native change, because the verdict describes one moment.
+
+Claude writes `.orphaned_at` at the root of a plugin-cache version it plans to
+delete (`<...>/.claude/plugins/cache/<marketplace>/<plugin>/<version>/.orphaned_at`),
+rewrites its timestamp at each start, may replace the file, and later deletes
+the marker or the whole version. A fresh Skills discovery review binds such a
+marker as `claude-plugin-orphaned-at-v1`, a witness of its presence only, and
+`discovery-binding` reports it with that witness's own check, exactly as the
+hook does:
+
+- A rewritten timestamp or a replaced file (new inode) is `current`, provided
+  the marker is a regular, non-symlink file owned by the current user whose
+  content is exactly 13 ASCII digits without a leading zero (no byte-order
+  mark, no newline).
+- Any other content, a symlink or another owner is `drift` with
+  `MARKER_INVALID`.
+- A deleted marker whose version directory still exists is `drift` with
+  `MISSING`; the hook refuses this state too.
+- When Claude deletes the whole version directory and the registered sibling
+  version stays bound and current, the marker and every other retainable
+  witness below that directory are `retained-absent` under
+  `absent-retired-claude-version`.
+- A recreated version directory is no longer absent, so each of its witnesses
+  is checked again: a valid marker and an unchanged manifest are `current`,
+  and a missing marker is `drift` with `MISSING`.
+- Marker witnesses stored by an older review as `bytes` or `path-bytes` keep
+  their exact meaning and report `CHANGED` once Claude rewrites the marker,
+  until a fresh discovery review rebinds them as typed witnesses.
+
+Installers must not restore, copy back or rewrite `.orphaned_at` files, or any
+other witness file, to make a binding verify. A restored file has a new inode,
+which a `path-bytes` witness rejects, and it can hide a change Claude made. Act
+on the `discovery-binding` result instead. When it reports drift, the binding
+needs a fresh Skills discovery review (`skills hook install` with fresh
+`--discovery-inputs`), not a file repair.
+
+Refusal codes for this operation, besides the shared request and producer
+codes (`INVALID_REQUEST_FILE`, `INVALID_REQUEST_JSON`, `INVALID_REQUEST`,
+`INVALID_SCHEMA`, `INVALID_REQUEST_FIELDS`, `INVALID_PATH`,
+`PRODUCER_UNVERIFIED`, `PRODUCER_CHANGED` and `CAPTURE_REJECTED`):
+
+- `POLICY_PATH_MISMATCH`: `policyPath` is not the package-owned policy path.
+- `POLICY_UNAVAILABLE`: the policy file is absent.
+- `POLICY_UNREADABLE`: the policy is not a regular, bounded, valid managed
+  policy file.
+- `BINDING_UNAVAILABLE`: the policy stores no Claude discovery binding.
+- `BINDING_INVALID`: the stored binding is not a Claude binding with a
+  `reviewed` or `automatic` method, or its sources, directories or root
+  aliases do not match the binding schema.
+- `POLICY_CHANGED`: the policy changed while it was being verified.
+- `DISCOVERY_BINDING_REJECTED`: any other failure.
+
+The operation is read-only. It reads the policy and the stored witness paths
+and directories. It writes no file, cache, selection pin or policy, and it does
+not start Claude or change native state.
+
 ## Profiles, station sync and rollback
 
 ```bash
@@ -2850,6 +3107,17 @@ Review the plan before adding `--apply`; the original review preimage must match
 its original mode, and unrelated changes refuse. This preserves the native
 configuration, root aliases, other witnesses and active session pins.
 
+Verifying a typed Codex settings witness from `codex-settings-v1` to
+`codex-settings-v5` also accepts the one write Codex 0.162.1 makes on its own
+first TUI or desktop launch: the boolean `tui.screen_reader_detection_done`
+receipt, added, removed or flipped (V6 already omits it). No digest changes
+meaning, and verification alone records or rebinds nothing. A non-boolean receipt, any other TUI key
+(including the `animations = false` Codex adds when it detects a screen
+reader) and every other change still drift, including Codex's
+`[projects."<dir>"]` trust entries. A planned Skills write to `config.toml`
+rebinds the witness to the written document, which adopts at most that
+receipt.
+
 `claude-settings-v4` is an explicit successor to `claude-settings-v3`. It
 additionally ignores only a top-level `theme` whose value is exactly one of the
 documented built-in values (`auto`, `dark`, `light`, `dark-daltonized`,