@hasna/skills 0.9.11 → 0.9.12

package/README.md

@@ -160,6 +160,39 @@ the same command with `--recovery-plan-digest <reviewed-digest>` to record the
 receipt. Any unreviewed change refuses. This mode preserves the policy and
 native configuration and cannot be combined with `--supersede-binding`.
 
+If another reviewed producer appended a user hook after the interrupted write,
+add `--review-native-hook-additions <private-review.json>`. This is a separate
+explicit review; a producer receipt alone never authorizes recovery. The review
+must be an absolute, owner-only regular file with these exact fields:
+
+- `version: 1`, `kind: "native-hook-additions"`, a nonempty `reason`, and a
+  `producerEvidence` reference to the independently reviewed producer operation.
+- `journalIntentSha256`, `policySha256`, `configCurrentSha256`, and
+  `hooksCurrentSha256` pin the complete current inputs and immutable intent.
+- `producerBefore` contains `configPath`, `configSha256`, `hooksPath`, and
+  `hooksSha256`. These owner-only backup files must reproduce exactly the
+  completed original trust write and the original hook declarations.
+- `additions` contains one or more `{ event, nativeHook }` records. `event` is
+  `UserPromptSubmit`, `SessionStart`, or `SubagentStart`. `nativeHook` contains
+  exactly the native inventory fields `key`, `eventName`, `handlerType`,
+  `command`, `matcher`, `timeoutSec`, `async`, `statusMessage`,
+  `additionalContextLimit`, `sourcePath`, `source`, `pluginId`, `isManaged`,
+  `currentHash`, `enabled`, and `trustStatus`.
+
+Only appended single-command groups from the same user hook file are supported:
+no matcher, asynchronous handler, custom status/context limit, plugin source,
+duplicate command, replacement or reordering. The added hooks must already be
+enabled and trusted in the actual native inventory. Every original hook and
+unrelated configuration byte remains verified. Combine this flag with
+`--review-claude-discovery` only when that independent policy transition is also
+present. The package provenance flags, private preview, exact
+`--recovery-plan-digest`, and subsequent explicit binding refresh are still
+required. Reconciliation writes only its journal receipt.
+
+When updating the Codex binding afterward, Skills replaces its single hook
+group in place so neighboring hooks retain their native indexes and trust
+identities. Ambiguous duplicate or mixed Skills groups refuse installation.
+
 Each supported agent gets one small `skills-cli` native skill containing CLI
 instructions, without a copied catalogue. Claude's native Skill tool admits
 that bridge after other copies are retired. Prompt guards verify the owned
@@ -353,6 +386,25 @@ directory within your home, add `--allow-root-aliases` to hook installation and
 native migration. The plan records and rechecks the exact link and target;
 links inside skill contents or configuration files remain refused.
 
+Cooperating installers can use the root package's
+`planClaudeStopHookUpdate({ expectedSettingsSha256, replacement })`, then
+`applyAgentIntegration(plan)`, to write an explicitly authorized Claude settings
+replacement changing only `hooks.Stop`, together with every existing discovery
+witness for that file. Every other field and hook must retain the same value;
+this includes discovery configuration and display/model preferences.
+The caller must authorize its own exact change; this API does not grant approval
+to change another owner's hooks. It checks the current native bridge, inventory,
+policy, executable witnesses and root aliases, preserves each witness mode, and
+verifies the consumer guard after applying. A concurrent edit or pre-existing
+drift refuses renewal. Failed post-write checks compensate only unchanged writes,
+retaining private backups. A `null` plan means no Skills policy exists; malformed
+or untrusted policy throws instead. This local integration operation requires no
+hosted credential, does not reload an existing agent, and cannot adopt a stale
+policy after another installer has already changed settings.
+Settings and policy are separate files: this is a guarded sequence with
+compensation, not a cross-file atomic commit. A concurrent hook can fail closed
+during installation. A successful update does not reload an existing session.
+
 At session start, the hook authenticates and refreshes the profile. Prompt hooks
 select complete skill instructions from that verified cache using explicit
 `$skill` references, profile keywords, paths and always-required selections.
@@ -1978,3 +2030,18 @@ operation did not execute. The client does not retry or issue a status read
 automatically: explicitly call `get` with the same request ID to reconcile.
 Aborting locally does not establish server cancellation. An already-aborted
 signal refuses before calling the transport.
+
+### Authoring destination checks
+
+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.
+
+Other authoring tools can use the same read-only guard from the package root:
+
+```ts
+import { assertPortableAuthoringPath } from "@hasna/skills";
+
+assertPortableAuthoringPath(destination, { homeDir: accountHome });
+// Only now create or change the private authoring destination.
+```
+
+`homeDir` defaults to the current account home. Missing destination descendants are supported. The check reads configuration without loading plugins, fetching skills, or creating directories; it throws on refusal. It is a pre-write check, not a reservation against concurrent configuration or symlink changes. Call it again immediately before each later write. Native inventory and migration remain available for preserving existing copies.