@hasna/skills 0.7.1 → 0.7.3

package/README.md

@@ -55,6 +55,12 @@ skills hook install --agent all --selection-profile default --json
 skills hook install --agent all --selection-profile default --apply --json
 ```
 
+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
+restart the native client to load its current commands. Explicit `skills load`,
+`skills context`, and `skills sync` commands can still select other profiles.
+
 The hook install `--include-vendor` option is retained for compatibility with
 older scripts. Hook planning always inventories and disables discovered vendor
 system skills; use `migrate native --include-vendor` when retiring their
@@ -94,6 +100,9 @@ allowlist unchanged: approve the two exact
 managed event/command pairs through Hermes normal hook trust and restart.
 The adapter refuses unreviewed installed plugin sources and custom Hermes
 homes/profiles, user-specific tilde expansion, and `TERMINAL_CWD` overrides.
+Nonempty `HERMES_BUNDLED_PLUGINS` and `HERMES_BUNDLED_SKILLS` overrides are
+also refused during discovery and hook checks; unset them to use the reviewed
+default source paths. Custom bundle locations need a dedicated discovery adapter.
 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.
@@ -102,6 +111,57 @@ 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
 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
+its full source-file hashes. The public SDK's `captureDiscoveryDirectories(paths)`
+captures recursive, sorted path/type membership without reading plugin payloads.
+Include every directory the reviewed loader scans, including plugin version
+selection parents and Python entrypoint discovery directories. Membership hashes
+detect added, removed or changed file types; keep source hashes for reviewed bytes.
+Missing directories bind as `sha256: null`. Symlinks and special nodes refuse.
+The bounds are 64 roots, 20,000 total entries, 8 MiB of path/type metadata and
+64 levels of recursion. Capture and checks require stable directory identities;
+quiesce source writers for installation because these checks are not atomic with
+a later native import.
+
+For full binary or source-byte coverage, use the public SDK's
+`captureDiscoveryByteSources(paths)` and retain its explicit `hashMode: "bytes"`
+on each source witness. It hashes the exact file bytes, including invalid UTF-8,
+with limits of 64 MiB per file and 256 MiB across one capture or verification.
+Missing files bind as `sha256: null`; symlinks, special files and changing file
+identities refuse. Raw witnesses cannot use configuration field projections.
+Existing witnesses without `hashMode` retain their original UTF-8 decoding
+contract and 16 MiB file limit; they are not silently converted into byte hashes.
+Directory membership and file bytes are separate witnesses. Neither substitutes
+for reviewing the actual executable, import paths or loader behavior.
+
+For an explicitly reviewed launcher or interpreter reached through symlinks,
+use `captureDiscoveryPathSources(paths)` and retain `hashMode: "path-bytes"`.
+Its digest binds the canonical input, directory identities, each link's identity
+and target, and the resolved regular file's identity and exact bytes. Relative
+link targets resolve component by component, including `..` after an alias.
+Missing targets also receive a digest that binds the path leading to their
+absence. Retargeting to identical bytes, replacing a link or an ancestor, or
+changing a file's metadata requires a fresh review. Unrelated sibling writes
+do not change directory identity witnesses.
+
+Path witnesses share the 64 MiB file and 256 MiB aggregate byte limits. Each
+path allows at most 40 links, 256 traversal steps and 64 KiB of metadata; one
+capture or verification permits 8 MiB of path metadata. Special nodes, cycles,
+oversized inputs and changes during capture refuse. Native hook checks repeat
+the witness verification; this does not make a later native execution atomic
+with external writers. Keep source writers quiescent during activation.
+Use `bytes` mode for configuration that hook installation will replace: path
+witnesses cannot predict the future identity of a planned write. Existing raw
+byte and directory witnesses still refuse links. Older clients reject the new
+mode; upgrade the CLI before installing a policy that uses it.
+
+Hermes requires directory witnesses, including when upgrading an older policy.
+For an automatic bridge with no runtime installed, rerun normal `skills hook install`
+to review and apply the new bindings. Existing native trust is preserved.
+Reviewed Hermes installations need fresh source and directory coverage in their
+`--discovery-inputs` file. Other agents may add directory witnesses to their
+reviewed bindings without changing existing source-only reviews.
+
 Hook installation preserves unrelated configuration, hooks, and plugin assets.
 It disables discovered Codex native skills; exact system-skill trees can remain
 only with their hash-bound disabled paths; migration preserves these package files. A client that restores or changes
@@ -112,6 +172,13 @@ copies, and `--include-vendor` retires vendor `SKILL.md` discovery files while
 preserving shared scripts and assets. Archive receipts and configuration backups
 live under the Skills data directory.
 
+After vendor documents are archived, inventory still scans their retained asset
+directories for newly introduced skills. Vendor container traversal allows 32
+directory levels; the ordinary native-root limit remains unchanged. Each inventory
+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.
+
 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
@@ -132,6 +199,11 @@ 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.
 
+Gemini's `BeforeAgent` prompt can include the Skills policy emitted at session
+start. The hook excludes that exact leading policy from skill selection, so it
+does not displace the user's requested skill. Other hook context and user text
+remain part of the selection input.
+
 Known local plugin registrations are resolved automatically. Plugins with
 instruction-injecting hooks, unresolved runtime registrations, unsupported
 legacy command formats, and higher-precedence project discovery settings need