@hasna/skills 0.10.83 → 0.10.89

package/README.md

@@ -471,8 +471,12 @@ Retire native payloads before use. Legacy `skills-cli.md` files can shadow the
 bridge and must also be preserved and retired before proceeding. Only `skill_view(name:
 "skills-cli")` is allowed natively; author payloads with Skills CLI commands.
 Hermes itself fails open on `pre_llm_call` errors. A returned refusal is visible
-context, and the trusted pre-tool guard blocks drift and native skill fallback;
-this is not a claim that Hermes can prevent every model call after a failed
+context. The trusted pre-tool guard blocks native payload skills and a
+`skill_view(skills-cli)` call while the bridge is unverified or can be
+shadowed (a legacy `skills-cli.md`, a bridge-named copy, or an environment
+override above that leaves the effective discovery unchecked); other discovery
+drift is reported and recorded, not blocked, and other tools proceed. This is
+not a claim that Hermes can prevent every model call after a failed
 prompt hook or guarantee refusal if the native host/supervisor itself dies. Arbitrary project/plugin paths still require a discovery audit.
 
 Reviewed discovery can also bind `directories: [{ path, sha256 }]` alongside
@@ -604,7 +608,16 @@ inventory entry outside the manifest remains untouched.
 
 `skills hook agents --json` reports the supported adapters and coverage limits.
 Claude and Codex have lifecycle context hooks; Gemini uses `BeforeAgent`, and
-OpenCode uses its awaited message plugin. Cursor receives selected context at
+OpenCode uses a v2 object plugin with awaited `prompt` and `context` hooks.
+The OpenCode adapter targets the v2.0.32 Promise plugin contract. Prompt
+admission stages genuine user text transiently. Request context matches that
+text and restores verified selections
+into transient system context without changing message history. Native skill
+tools and prompt attachments allow only `skills-cli`. Disposal removes hook
+registrations and cancels pending Skills hook children. Exact managed v1 plugin
+bytes remain recognizable for reviewed upgrades. The isolated contract tests
+do not establish adoption by an installed OpenCode process.
+Cursor receives selected context at
 session start and gates later prompt submission; its prompt hook does not
 inject context on the supported installed path. Other inventoried clients do
 not automatically gain a working prompt adapter.
@@ -989,13 +1002,78 @@ own bounded native client; it does not reload an existing agent session.
 Neither a receipt nor a config write proves an existing session adopted new rules;
 use the actual native session's supported acceptance path separately.
 
-At session start, the hook authenticates and refreshes the profile. Prompt hooks
+At session start, the hook authenticates and refreshes the profile within a
+five-second bound; a refresh that does not finish is named in one line and the
+session uses its last verified profile. Prompt hooks
 select complete skill instructions from that verified cache using explicit
 `$skill` references, profile keywords, paths and always-required selections.
-A session retains its loaded selections; compaction restores loaded instructions,
-and subagents inherit the parent's selection. Instructions that exceed the
-context budget produce an explicit `skills load` command. A hook never executes
-a skill. Cached use is explicit and expires after 24 hours. When a session
+A keyword matches as a phrase (its words adjacent and in order); a selection
+without keywords matches its whole slug as a phrase, or a shorter run of its
+slug words that has two words of three or more letters and the slug's
+least-used word ("seating plan" for event-seating-plan, never "run of" for
+live-event-run-of-show); a one-word trigger shared by more than three
+selections selects nothing on its own; and a one-word slug counts as named
+only beside the word "skill". A prompt match scoring under half of the
+prompt's best match, and prompt matches tied at the last free slot, are
+offered as `skills load` commands instead of being injected or picked by name
+order. Weaker pointers are offered the same way, at most three and never
+injected: a multi-word keyword whose words all appear apart, one of them
+discriminating ("designs review" in "the designs app for review"), or a common
+one-word keyword; a tie that does not fit is left out. Managed prompt hooks are
+stricter than a direct `skills context` call: they inject an unnamed prompt
+match only for a phrase of two or more words, and offer anything weaker as a
+`skills load` command, so a `keywords: ["pdf"]` selection needs `$pdf`, "the pdf
+skill", a two-word keyword or `triggers.always` to arrive as a body.
+`SKILLS_HOOK_PROMPT_MIN_PHRASE_WORDS` can raise that length, never lower it.
+Sumi's plugin and Cursor's prompt hook discard a prompt call's output, so a
+pointer could not reach their models, and they keep the plain selection. Each
+`skills load` command a session is offered names that session and carries
+`--cache-first`, so it loads the pinned version from the verified cache the hook
+used, which works in a sandbox with no network. Once the cache can't serve it it
+loads from the Skills service. That happens when the pin was last verified over
+24 hours ago, which is common for a subagent, since it inherits its parent's time
+and no hook renews its own pin. With no network as well, the load refuses and says
+so, and `skills sync` doesn't renew a session's pin. Like a body the hook delivers
+from the cache, a cached load doesn't ask the service whether the selection is
+still current.
+
+A load is recorded on the session the command names, whoever runs it, so running
+another session's command marks that session as having loaded the skill, and its
+later prompts offer it no pointer. Where the session store can't be written or is
+full, as in a Codex sandbox, a load still returns its content and says it wasn't
+recorded, unless the bundle isn't cached and the cache can't be written either, in
+which case it refuses. Compaction won't restore an unrecorded skill and the session
+won't be told if it's retired. An agent or subagent with no way to run a command can't use a
+pointer.
+
+A session retains its loaded selections; compaction restores the two most
+recently loaded instructions, followed by `skills load` commands for the next
+most recent. A subagent started by a managed hook is offered its parent's
+loaded skills as `skills load` commands, and gets a body at its start only for a
+skill that `triggers.always` or a path selects. Claude Code's and Codex's
+subagent start carries no prompt, so naming a skill in a subagent's brief doesn't
+deliver its body there. OpenCode's adapter does pass the subagent's first prompt,
+so there it also gets a body for a skill it names or matches by a phrase. A
+direct `skills context` call, and Sumi's and Cursor's hooks, give it its parent's
+most recent one as a body. A
+read-only prompt does not rewrite the session receipt or take its write lock
+(a damaged lock still refuses), and receipt writers wait up to two seconds for
+another live writer's lock before refusing; a lock another writer is
+publishing or releasing at that moment counts as held, not damaged. Every
+delivered body is recorded in the receipt: when only that write lost its lock
+race, skills the receipt already records are still delivered, and each newly
+read one is offered as its `skills load` command under one fixed
+`[SESSION_WRITE_BUSY]` line. A new subagent whose parent recorded a load or
+renewed its pin while the subagent resolved is resolved once more from the
+current parent pin. Managed hooks inject at most 24,000 instruction
+characters; instructions that exceed that or another context budget produce
+an explicit `skills load` command. A hook never executes
+a skill. Cached use is explicit and expires after 24 hours. Managed hooks renew
+session pins in a detached background worker (`docs/session-pin-renewal.md`),
+ahead of expiry for root sessions (a failed renewal ahead of expiry is named
+in one line while context comes from the still-valid pin); an expired pin
+waits at most three seconds for its renewal and delivers nothing until it
+commits. 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
@@ -1015,7 +1093,7 @@ 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 refusal. If the migration cannot finish within the 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
@@ -1543,6 +1621,54 @@ 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.
 
+### Disable only Claude context delivery hooks
+
+`skills hook disable-claude-context` previews removal of exact Skills-owned
+`SessionStart`, `UserPromptSubmit` and `SubagentStart` registrations. It requires
+an explicit physical settings path, its exact SHA-256 and `0600` mode, the exact
+Skills executable and its physical byte digest, and the registered selection
+profile. It compares complete commands produced by Skills' own renderer, never
+a command substring. Unsupported near matches refuse. Duplicate JSON keys,
+aliases, unsafe paths, and changed target/command witnesses refuse too.
+
+```sh
+skills hook disable-claude-context --settings /absolute/native/settings.json \
+  --expected-settings-sha256 <exact-settings-sha256> --expected-mode 0600 \
+  --skills-command /absolute/bin/skills \
+  --expected-command-sha256 <exact-command-sha256> \
+  --selection-profile <exact-profile> --json
+```
+
+The default preview writes nothing. Add `--apply --preimage-dir <new-absolute-dir>`
+to apply. The preservation directory's parent must already exist. Apply creates
+an exclusive private directory and reads back the exact original before changing
+settings. An existing directory is never reused. The operation preserves all
+other settings and handlers, including `PreToolUse` native Skill enforcement,
+unrelated empty groups, permissions, policy, profiles and sessions. JSON spacing
+is reserialized, while unknown numeric spellings remain intact.
+
+The result distinguishes `no-data` (an explicitly absent target, using `absent`
+for both expected hash and mode), `no-op` (a present file with no exact matches),
+`preview`, `applied`, and `ambiguous`. `plannedAfterSha256` describes the proposed
+bytes. `afterSha256` is unavailable until readback verifies an applied target.
+Apply uses a descriptor-held package lock and atomic file exchange, retaining
+both a private preimage and the displaced entry. Exchange is not compare-and-swap.
+A post-exchange race or failed verification returns `ambiguous`, exit 2,
+`mutationOccurred: true` and exact recovery paths. It never claims no write or
+blindly overwrites a concurrent edit during rollback. Failed staging and all
+preservation evidence remain for recovery.
+
+This command makes no hosted request and needs no credential. It can run from
+an exact reviewed task-scoped CLI artifact without installing it as the shared
+Skills command. Its lock file remains in the target directory. Removing context
+hooks can stale enrolled settings witnesses that bind those hooks. The operation
+reports `settingsWitness: not-renewed` and does not refresh or relax them.
+`PreToolUse` enforcement can therefore still refuse on a stale witness. This is
+a context-delivery shutdown, not admission recovery or permission to reactivate
+hooks. Linux uses `renameat2(RENAME_EXCHANGE)` and macOS uses
+`renamex_np(RENAME_SWAP)`; unsupported exchange or filesystem behavior refuses.
+
+
 ## Profiles, station sync and rollback
 
 ```bash
@@ -2099,7 +2225,7 @@ on the exact entry, through `env -i` with an explicit environment allowlist:
 (`TERM`, `TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `COLORTERM`, `COLUMNS`, `LINES`),
 `NO_COLOR`, `FORCE_COLOR`, `CI`, `EDITOR`, `VISUAL`, `PAGER`, `SSH_AUTH_SOCK`,
 the server settings `HOST`, `PORT`, `NODE_ENV`, `AGENT_ID` and
-`ECS_CONTAINER_METADATA_URI_V4`, the agent names `TERMINAL_CWD`, `CODEX_HOME`,
+`ECS_CONTAINER_METADATA_URI_V4`, the agent names `TERMINAL_CWD`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR`,
 `HERMES_HOME` and `HERMES_ENABLE_PROJECT_PLUGINS`, and every name starting with
 `HASNA_`, `SKILLS_`, `SKILL_`, `MCP_`, `XDG_`, `LC_` or `AWS_`. Your `LC_ALL` passes
 through unchanged. Everything else never reaches the runtime, including `BUN_*`,
@@ -2107,7 +2233,7 @@ through unchanged. Everything else never reaches the runtime, including `BUN_*`,
 (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). A `bunfig.toml`, `.env` or `tsconfig.json`
 in the directory you run a command from is never read.
 
-New launchers use the V2 format with an explicit environment profile. The CLI and
+New launchers use the V3 format, preserving `CLAUDE_CONFIG_DIR`, with an explicit environment profile. The CLI and
 MCP entries use the client profile, which excludes `DATABASE_URL`,
 `HASNA_SKILLS_DATABASE_URL` and `SKILLS_DATABASE_URL` even when their prefixes are
 otherwise allowed. The API server, worker, maintenance and migration entries use
@@ -2124,10 +2250,10 @@ directory first. The receipt records the old and new launcher shape of every pat
 the backup keeps the exact previous launcher (symlink text or pinned bytes), and
 `--rollback` restores it byte for byte. Codex hook trust, the Claude settings
 projection and `skills self-update` read a managed pinned launcher as the exact
-entry it runs and bind the launcher's own bytes as well. Existing V1 launchers
-remain recognized in their exact original format. Receipts without launcher
-format metadata restore V1 bytes; new receipts bind the V2 format and environment
-profile. An upgrade does not prevent rollback to the prior V1 launcher.
+entry it runs and bind the launcher's own bytes as well. Existing V1 and V2 launchers
+remain recognized in their exact original formats. Receipts without launcher
+format metadata restore V1 bytes; new receipts bind the V3 format and environment
+profile. An upgrade preserves byte-exact rollback to a prior V1 or V2 launcher.
 
 An updater from before pinned launchers (0.10.48 and earlier) writes bare symlinks,
 including when it installs a version that has them, and an exact-version update to
@@ -3416,6 +3542,12 @@ signal refuses before calling the transport.
 
 Payload writers reject known native skill folders, physical aliases of the account's native roots, and configured home discovery roots (including OpenCode `skills.paths`) before creating directories. Malformed or unresolved native registrations fail closed and require the existing Skills discovery review. Changing the authoring data directory does not hide the account's native policy.
 
+`CODEX_HOME` and `CLAUDE_CONFIG_DIR` also exclude their selected native home and its current configured discovery roots. Relative Codex homes resolve from the caller's directory. Claude requires an absolute configuration directory. Native skills and plugin-cache subroots, Claude's synced-plugin and legacy-command subroots, and their physical targets remain excluded when those subroots are symlinks outside the selected home. Bounded metadata traversal also excludes readable descendant alias targets while allowing unrelated private authoring. The same traversal protects default homes with no override, or when the override equals or aliases the default home. Physical aliases and destinations containing an excluded root are refused too. Default and retained roots remain excluded when an override is selected. An override does not enroll a new native consumer or reuse another home's opaque-hook review. Unsupported custom Hermes homes fail closed even when the default Hermes directory is absent.
+
+Authoring derives a read-only exclusion set from current supported discovery controls and unions it with every retained policy root. A stale full-file settings witness does not by itself block a safe portable destination. For example, ordinary Claude model/theme changes without opaque hooks, or a newly added OpenCode `skills.paths` directory, do not require enrollment or policy updates. Both the old and new custom roots remain forbidden destinations. Native loading and enrollment still verify their original witnesses strictly.
+
+Unknown discovery controls, malformed or ambiguous registrations, unresolved aliases/runtimes and bounded-enumeration failures refuse before a payload write. Executable hooks whose roots cannot be enumerated still need their existing current source review. Typed Claude v5/Codex v7 settings witnesses and an already recorded narrowed witness can establish that review without a write. A legacy opaque hook registration whose full-file witness is stale and has no previously recorded narrowed proof remains unsupported. Authoring never manufactures that proof or enrolls the account. Opaque hooks also retain the existing reviewed executable/dependency source population and directory evidence: matching settings, `hooks.json`, or a manifest alone is insufficient. The authoring-only check reuses the native verifier's source, directory, semantic and retired-source predicates, exempting only the primary configuration already handled by the current bounded root pass. Missing executable closure evidence refuses. A filesystem-root exclusion such as OpenCode `skills.paths: ["/"]` excludes all descendants, including physical aliases.
+
 Other authoring tools can use the same read-only guard from the package root:
 
 ```ts
@@ -3462,6 +3594,25 @@ refuses native discovery or unknown control changes, and changes policy only.
 After explicit migration, ordinary supported local MCP updates require no
 coordinated policy write.
 
+### Native discovery drift is reported, not blocking
+
+Live prompt, session, subagent and tool hooks no longer block on
+`NATIVE_SKILL_DRIFT`. The turn proceeds without Skills context, the agent shows
+one warning naming the change and the repair command, and the hook records a
+receipt in `<skills-data>/native-drift/<agent>.json`; `skills hook drift --json`
+lists them. Invoking a native payload skill instead of the `skills-cli` bridge
+is still denied, and so is invoking the bridge while the bridge itself is
+missing or modified; install, trust and migration still refuse drift.
+
+`claude-settings-v5` and `codex-settings-v7` reviews bind only settings that can
+add, remove or redirect native skills, hooks or plugins (and, for Codex, every
+MCP server and instruction source), so a model switch, an "always allow" rule, a
+status line or Codex's folder trust and notices are not drift. Existing Claude
+and Codex reviews keep verifying through a narrowed-witness ledger the live hook
+records while they still match; a station that had already drifted, V6 and Sumi
+witnesses still need one fresh review. See
+[docs/plugin-admission.md](docs/plugin-admission.md#narrowed-discovery-reviews-claude-settings-v5-and-codex-settings-v7).
+
 ### Reproduce a reviewed runtime dependency closure
 
 For an exact-version copyfile update, supply an owner-private absolute npm