@hasna/skills 0.10.72 → 0.10.74

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
@@ -626,6 +661,10 @@ non-null `sha256`, Skills also requires plain byte witnesses for that plugin's
 `hooks/hooks.json` (when present) and any string `hooks` target in the
 manifest. A manifest listed as `claude-plugin-manifest-v1` (the form Skills
 writes into the stored policy) or as `path-bytes` triggers no such requirement.
+A source that the `absent-retired-claude-version` rule retains (see
+[`discovery-binding`](#verify-the-stored-claude-discovery-binding-discovery-binding))
+is stored exactly as listed: Skills does not project its manifest, require its
+hook files or convert its marker, because the file no longer exists.
 The version-root `.orphaned_at` timestamp that Claude rewrites at startup is
 bound by presence only, as `claude-plugin-orphaned-at-v1`, and is still
 strictly validated; see
@@ -694,6 +733,27 @@ file; drift still requires a fresh explicit review. Explicit discovery inputs
 take precedence, including when their `agents` array omits a previously reviewed
 agent. The default `--agent all` still includes every supported adapter.
 
+That recheck has two halves, and only one of them gates reuse. BINDING CUSTODY —
+the same managed bridge, home, alias set, agent, command/profile binding and
+reviewed discovery — must hold before a saved review is reused, or the plan
+refuses and names a fresh explicit review. Bridge PROTECTION — the native plugin
+bytes, the permission and hook rules and the bundled-skill switches — is written
+by the same plan, so it is asserted in full after the writes instead of gating
+the repair that fixes it; a plan that does not repair it is refused before the
+receipt is written. Hermes native shell-hook trust is the exception: it is the
+user's own consent and no Skills write creates it, so it stays a pre-write
+condition. One implementation serves both halves, so they cannot drift apart.
+
+Because that recheck includes the managed bridge, `hook install` cannot reuse a
+saved review on a host whose bridge has since broken, and in that form it cannot
+repair its own precondition. It refuses and names the reachable form,
+`skills hook install --agent <agent> --discovery-inputs <review> --apply`, which
+skips the retained-review precheck and rebuilds the bridge from the review in the
+same transaction. A reviewed binding always carries a whole-file witness for the
+agent configuration beside its projected fields, so unchanged projected fields do
+not excuse a change outside them: a fresh explicit discovery review, not a
+witness refresh, is the supported route.
+
 For reviewed Claude plugins, `skills integration plugin plan`, `admit` and
 `resolve` provide a command-source admission boundary before native discovery.
 Original packages and migrated skill/command prompts remain in private versioned
@@ -702,6 +762,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 +1088,216 @@ 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.
+
+An installer that then passes the stored full-file sources (rows with `format`
+`null`), roots and directory witnesses back to `skills hook install --agent
+claude --discovery-inputs <file>` gets the same retention: `hook install`
+retains each `retained-absent` source with the same rule and stores it
+unchanged, so a historical `bytes` witness keeps its meaning. Every other
+source is checked and, for a fresh review, typed as usual.
+
+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
@@ -1034,6 +1323,50 @@ for the named station; it is not a native-folder snapshot in this mode.
 `skills install --selection-profile default` without skill names also syncs the
 whole selection.
 
+### Reading provenance instead of trusting one record
+
+Applying a record is not adoption, and the four facts below are different. Only
+`skills provenance` reports them together, read-only:
+
+- `selected` — the shared profile the authority serves right now;
+- `activated` — the snapshot this machine last verified and activated, which is
+  what its hooks, `skills context` and `skills load` resolve from;
+- `applied` — the station receipt the authority holds. Only an explicit
+  `skills sync` writes it; the managed hook keeps station reporting off its
+  blocking lifecycle path on purpose, so this record legitimately lags the
+  activation and is not by itself evidence that a machine is adrift;
+- `pinned` — the exact immutable profile revision one live session holds. A
+  session keeps its revision when the profile moves on, so an older pin is
+  custody by design, not drift;
+- `consumed` — the skills that session actually loaded, at their exact versions.
+
+```bash
+skills provenance --json
+skills provenance --session <session-id> --json
+skills provenance --station station-example --json
+```
+
+Every consumer is classified `current`, `behind`, `pinned` or `unverified`, and
+always carries a stable `reasonCode` and its reason. Identity is part of the
+comparison: a revision that matches under a different authority, workspace or
+profile is `IDENTITY_MISMATCH`, not `current`, so a foreign pin is never
+reported as adopted and is never diffed. Each receipt source declares the
+identity fields it must record, so a receipt that omits one — or carries `null` or
+an empty string where a nonempty string is required, which the HTTP reader also
+passes through — is `INCOMPLETE_RECEIPT`, not `current` and not `behind`: an
+absent revision is not an older revision. The local activation is named as this
+machine and the authority receipt as the station named on the command line; the
+two are never collapsed into one id. The receipt also states what it does not
+attest — published version and digest evidence, native discovery and locks, and
+live consumer adoption — rather than letting a clean-looking result imply them.
+`drift` lists the bundles whose exact versions differ. The command reads and
+never writes a pin, receipt, cache entry or station record, and it renders no
+skill payload and no credential: a reader's exception text is never carried,
+only a fixed diagnostic code, because bounding foreign text is not redacting it.
+With `--cached`, or when the authority cannot be read, the reference is the
+locally synced snapshot and every consumer is reported `unverified` rather than
+`current` — a local snapshot cannot establish adoption.
+
 After hook installation has enabled CLI loading, pull operations obey the same
 profile. `--all` refreshes its selected versions rather than the full catalog,
 and a named pull must belong to that profile:
@@ -1438,6 +1771,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills context <prompt> --selection-profile <id>` | | Resolve instructions matching the prompt and profile triggers |
 | `skills hook install --selection-profile <id>` | | Plan bridges and hooks for configured/detected consumers; `--agent <agent>` selects one, explicit `--agent all` requires every adapter; `--apply` installs them, then restart and trust the hooks |
 | `skills sessions show <id> --json` | | Inspect one session's exact profile revision and receipt hash without loading payloads |
+| `skills provenance [--session <id>] [--station <id>] --json` | `--cached` | Read-only receipt of the selected, activated, applied, pinned and actually loaded skill versions, each with its status and reason; writes nothing |
 | `skills sessions reconcile <id> --from-profile <id> --from-revision <rev> --receipt-sha256 <sha> --selection-profile <id> --profile-revision <rev>` | | Plan an explicit migration of one live session; `--apply --plan-digest <digest> --plan-issued-at <time> --plan-expires-at <time>` (within five minutes) preserves its old receipt and applies the reviewed replacement |
 | `skills hook agents --json` | | Report maintained adapters and explicit coverage limits |
 | `skills migrate native` | | Inventory native copies; `--apply` archives managed copies, with explicit `--include-unmanaged`, `--include-vendor`, or reviewed `--target-manifest` selection |
@@ -2850,6 +3184,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`,