@hasna/skills 0.10.71 → 0.10.72

package/README.md

@@ -207,6 +207,82 @@ is recorded at `agent-hooks/codex-native-policy-acceptance.json`; user,
 repository and project copies still refuse, and format or digest checks never
 prove the runtime policy on their own.
 
+A Codex plugin refresh can deposit a new vendor skill in `~/.codex/plugins/cache`
+(for example `openai-curated-remote/sites/1.0.2-remix-b.1/skills/sites-remix`).
+Skill payloads still reach agents only through the Skills CLI, so an enabled
+vendor copy keeps blocking the Codex prompt hook. Retire it by disabling it in
+`~/.codex/config.toml`. The plugin-qualified name survives later version
+directories, so prefer it:
+
+```toml
+[[skills.config]]
+name = "sites:sites-remix"
+enabled = false
+```
+
+An exact `path = ".../sites/1.0.2-remix-b.1/skills/sites-remix/SKILL.md"` rule
+also works, but only for that version. On the live Codex prompt hook only, a
+copy is then exempt when every condition holds:
+
+- it is package-classified plugin content in `openai-bundled`, `openai-curated`
+  or `openai-curated-remote` (exact names), with Codex's remote install receipt
+  for the remote marketplace;
+- it carries no Skills or Hasna marker;
+- every cached version of its plugin passes the vendor refresh check described
+  below for membership changes, so the plugin can load nothing that the
+  inventory and this rule do not account for, and no version is a link;
+- a `[[skills.config]]` rule names its exact path or its plugin-qualified name
+  with `enabled = false`, and no matching rule enables it.
+
+A whole-plugin `[plugins."sites@openai-curated-remote"] enabled = false` table
+is not enough on its own: remote state can enable a locally disabled remote
+plugin, and a cache copy carries no proof that its plugin source is
+configuration-controlled, so the copy keeps blocking until a path or name rule
+retires it. This exemption only adds to the guard's existing ones; every copy
+that the guard already accepts, such as an exact-path disable in any plugin-cache
+marketplace or a reviewed plugin control, stays accepted on the live hook. Once
+the hook tolerates one of the witness changes below, a state the strict guard
+refuses outright, plugin-cache copies are exempt only through this vendor rule.
+
+Instead of editing by hand, `skills hook native-catalog` followed by
+`skills hook install --agent codex --codex-native-catalog <file> --apply` writes
+the same rules through the guarded install path.
+
+The hook also tolerates, with a visible `systemMessage` warning, only the
+discovery-witness changes such a refresh provably makes:
+- appended vendor disable rules or vendor plugin disables in `config.toml`,
+  accepted when removing exactly those entries or restoring a formerly enabled
+  vendor flag reproduces the reviewed digest. Candidates are tried smallest edit
+  first, at most 128; with a typed settings witness that covers any change to up
+  to two of at most eight vendor plugin tables. A change beyond the bound refuses;
+- directory membership changes under an allowlisted vendor marketplace that
+  passes the vendor refresh check: every plugin version has exactly one
+  manifest, `.codex-plugin/plugin.json`, alone in its directory, whose keys are
+  only `name`, `version`, `description`, `author`, `homepage`, `repository`,
+  `license`, `keywords`, `interface`, `skills` (the default `./skills/` only) and
+  `apps`. So hooks in any form, commands, agents, extensions, MCP servers and
+  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
+  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
+  passes the same connector validation reviewed plugin controls use (one `apps`
+  object; app entries with only `id`, `category` and `required`, of the right
+  types; no duplicate keys). Any other connector path, a file that fails that
+  validation, or the file without the declaration refuses.
+
+Every other copy and change still refuses with `NATIVE_SKILL_DRIFT`, including:
+- user, project, `.system` and Hasna-marketplace copies that the guard does not
+  already exempt;
+- an enabled vendor copy whose plugin is only disabled by a whole-plugin table;
+- capability-control changes and whole-cache membership changes;
+- plugin activation, including a vendor plugin gaining `enabled = true`;
+- missing coverage and changed roots;
+- every install, trust, migrate and sync check.
+
 Native hook invocations must use their installed adapter's selection profile.
 An old client command or environment override naming another profile refuses
 before synchronization or context loading. Review the hook installation and
@@ -550,6 +626,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.
+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
+[the full scope](docs/plugin-admission.md#reviewed-plugin-hook-attestation-scope).
 For plugins outside receipt-backed admission (a `claude-plugin-registry`
 witness, see the
 [discovery transition contract](docs/plugin-admission.md#discovery-transition-contract)),
@@ -819,16 +899,37 @@ a skill. Cached use is explicit and expires after 24 hours. When a session
 receipt expires, the hook authenticates the current profile. If every loaded
 selection still has identical metadata and bundle digest, it archives the old
 receipt and advances that session to the current profile under an exact receipt
-precondition. Unloaded selections may be added or removed. If a loaded selection
-changed or disappeared, no instructions are delivered until the explicit
-reconciliation below. A missing cache may be recovered through authenticated context.
+precondition. Unloaded selections may be added or removed. If renewal is refused
+because the same profile moved on (a loaded selection changed or disappeared, or
+another pinned selection's policy, membership or lifecycle changed), the managed
+hook applies the explicit reconciliation planner and applier below to the
+authenticated current revision: it archives the old receipt, retains unchanged
+loaded bundles, retires changed or removed ones and delivers context for the
+prompt. The first hook context that succeeds and reaches the agent afterwards
+names each retired loaded skill once and how to reload its replacement; earlier
+instructions from those skills must not be relied on. Identity, integrity and receipt failures, an
+unavailable authority and anything the planner refuses keep their refusal;
+session write-lock contention keeps `SESSION_WRITE_BUSY`. A
+session created from a project lock (`.skills/selection.lock.json`) records
+that lock in its receipt and is never migrated automatically, whatever
+directory it later prompts from. A session without that record is not migrated
+while a lock sits in the prompt's working directory or any ancestor. A loaded
+skill whose lifecycle epoch rotated while its bytes stayed the same also keeps
+the refusal. If the migration cannot finish within the four-second renewal window,
+the hook reports `SESSION_RECONCILIATION_REQUIRED` with that reason and the next
+prompt retries. Turn this off station-wide with `skills config set
+sessionPinMigration off --global` (the key is refused without `--global`, and a
+global configuration that is a symlink, cannot be read or cannot be parsed also
+turns it off); the hook
+then keeps today's refusal until the explicit reconciliation below. A missing
+cache may be recovered through authenticated context.
 
 After verifying the native bridge and input, ordinary lifecycle hooks continue
 without skill payload on typed hosted authentication/refusal/availability failures,
 context timeouts, valid concurrent writers, context CAS conflicts, or required
 session reconciliation. They emit a fixed warning that Skills-dependent actions
 are unavailable; previously loaded instructions are not an authorization fallback.
-The hook does not rewrite a session pin or remove another writer’s lock to bypass these refusals. Explicit `skills
+Apart from the automatic migration above, the hook does not rewrite a session pin or remove another writer’s lock to bypass these refusals. Explicit `skills
 load`, `skills context`, and `skills run` still refuse unavailable or unauthorized
 instructions. Native skill tool guards still deny unmanaged payloads. Invalid
 input/receipts, integrity or authority mismatches, unknown failures, and native
@@ -1009,7 +1110,10 @@ hosted publication access.
 `--profile` option chooses an isolated credential file; these are separate
 settings. `HASNA_SKILLS_SELECTION_PROFILE` overrides the installed selection
 profile. A project lock and an existing session keep exact versions until they
-are explicitly changed or a new session starts.
+are explicitly changed or a new session starts. The one exception is the
+managed hook's automatic migration of an expired session pin described above.
+It never applies to a session created from a project lock, and never while a
+lock sits in the prompt's working directory or an ancestor.
 
 ## Executable skills
 
@@ -1367,7 +1471,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills setup-info` | | Version, pinned skills, agent configs, paths |
 | `skills export` | | Export pinned skills as JSON |
 | `skills import <file>` | | Pin skills from a JSON export |
-| `skills config set <key> <value>` | | Set default agent, scope, output format, or API origin |
+| `skills config set <key> <value>` | | Set default agent, scope, output format, or API origin; `sessionPinMigration off --global` keeps managed hooks from migrating refused session pins (global scope only) |
 | `skills config unset <key>` | | Remove a configuration value (`skills config unset apiUrl` clears the stored service address and returns to running on this machine) |
 | `skills new <name>` | `scaffold` | Scaffold a portable skill under `~/.hasna/skills/installed/<name>` |
 | `skills port <path>` | `add` | Import an existing skill folder into the portable standard |