@hasna/skills 0.10.72 → 0.10.73

package/dist/lib/agent-discovery.d.ts

@@ -1,6 +1,7 @@
 import type { IntegrationAgent } from "./agent-adapters.js";
 import { type DiscoveryDirectory } from "./agent-discovery-directories.js";
 import { type CodexReviewedHookSource } from "./codex-hook-mcp-dependencies.js";
+import { CLAUDE_ORPHAN_MARKER_MODE } from "./claude-plugin-cache-marker.js";
 import { type NativeDiscoveryWitnessTolerance } from "./native-discovery-witness-change.js";
 import { type ManagedPluginRegistrationWitness } from "./plugin-discovery.js";
 import { type CodexHookDiscoveryRecovery } from "./codex-hook-discovery-recovery.js";
@@ -95,6 +96,11 @@ export declare function projectNativeDiscoveryFields(text: string, format: "json
 /** Called only after the owning planner validated discovery and capabilities.
  * New roots must already be body-free; absent roots need the prior typed proof. */
 export declare function captureRetiredCodexDiscovery(binding: AgentDiscoveryBinding, controls: CodexPluginSkillControl[], rules: unknown): AgentDiscoveryBinding;
+/** The witness class that may keep its reviewed digest beneath a positively
+ * verified absent root: a full byte witness, the installer's full manifest
+ * projection or a present version-root orphan marker. Null for every other
+ * source, which must stay current. */
+export type RetainedAbsentWitness = "bytes" | "claude-plugin-manifest-v1" | typeof CLAUDE_ORPHAN_MARKER_MODE;
 /** Only native capability locations covered by the complete typed cache census
  * qualify. Historical sources remain stored; arbitrary missing files do not. */
 export declare function codexSemanticCacheSourceRole(source: DiscoverySource, cacheRoot: string, parents: readonly string[], hookParents?: readonly string[]): boolean;
@@ -109,6 +115,25 @@ export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding, cod
     alias: string;
     target: string;
 }[], witnessTolerance?: NativeDiscoveryWitnessTolerance): void;
+/** One stored Claude discovery source as an installer sees it. */
+export type ClaudeDiscoverySourceVerdict = {
+    status: "current";
+} | {
+    status: "retained-absent";
+    root: string;
+    witness: RetainedAbsentWitness;
+} | {
+    status: "drift";
+    reason: "MISSING" | "APPEARED" | "CHANGED" | "MARKER_INVALID" | "REFUSED";
+};
+/** Read-only, per-source report on a stored Claude discovery binding, in
+ * stored order. A source is retained only through the same absent retired
+ * version rule and predicate verifyAgentDiscovery applies; a refused rule
+ * retains nothing. Every other source is checked by its own witness, exactly
+ * as verification checks it (a typed orphan marker by the marker predicate).
+ * This report never accepts a binding by itself: a caller must also require
+ * verifyAgentDiscovery to accept the same binding. */
+export declare function classifyClaudeDiscoverySources(binding: AgentDiscoveryBinding): ClaudeDiscoverySourceVerdict[];
 export declare function rebindAgentDiscovery(binding: AgentDiscoveryBinding, changes: Map<string, string>): AgentDiscoveryBinding;
 /** Explicit streaming integrity witness. Never read an executable as text or execute it. */
 export declare function captureDiscoveryExecutableSources(paths: string[]): DiscoverySource[];
@@ -116,6 +141,11 @@ export declare function captureDiscoveryExecutableSources(paths: string[]): Disc
 export declare function captureDiscoveryByteSources(paths: string[]): DiscoverySource[];
 /** Capture executable/source path identity, including links and absent targets. */
 export declare function captureDiscoveryPathSources(paths: string[]): DiscoverySource[];
+/** Top-level keys whose presence, at any value, makes a project Claude settings
+ * file a higher-precedence discovery source that needs review. Claude 2.1.300
+ * rewrites `additionalMarketplaces` into `extraKnownMarketplaces` on every
+ * settings read, including local settings, so the alias counts as well. */
+export declare const CLAUDE_PROJECT_DISCOVERY_KEYS: readonly ["enabledPlugins", "extraKnownMarketplaces", "additionalMarketplaces", "skillOverrides"];
 /** Project settings can introduce a higher-precedence discovery source. Until
  * its native merge format is supported, refuse that layer rather than certify
  * the home-only inventory. Ordinary unrelated project settings remain usable. */
@@ -143,6 +173,12 @@ export declare function verifyAutomaticDiscoveryClosure(binding: AgentDiscoveryB
  * the stored digest. Witness modes
  * without a replacement digest (V6, artifacts, managed registries) stay strict. */
 export declare function codexVendorConfigChangeOnly(source: DiscoverySource, cache: string): boolean;
+/** Whether replacing `path` with `text` leaves every recorded witness of it
+ * satisfied, judged by each source's own digest mode without touching the file,
+ * with the same screen-reader receipt tolerance typed V1-V5 verification applies.
+ * Fails closed: a review artifact, managed-plugin or hook-source witness, a
+ * semantic cache binding of the file, or an unsupported mode counts as changed. */
+export declare function discoveryTextKeepsWitness(binding: Pick<AgentDiscoveryBinding, "sources" | "codexSemanticCache">, path: string, text: string): boolean;
 /** `executable` is the agent's runtime: omitted, it is resolved through PATH;
  * a value (or null for none) is used as given, so verification never depends
  * on the caller's PATH. */

package/dist/lib/claude-installer-binding.d.ts

@@ -0,0 +1,65 @@
+import { type RetainedAbsentWitness } from "./agent-discovery.js";
+export declare const CLAUDE_DISCOVERY_BINDING_VERIFICATION_SCHEMA: "skills.claude-discovery-binding-verification/v1";
+/** The rule that lets a stored witness stay unverified because Claude removed
+ * its whole retired plugin-cache version while unchanged settings and
+ * registrations select a current sibling version. */
+export declare const ABSENT_RETIRED_CLAUDE_VERSION_RULE: "absent-retired-claude-version";
+export type ClaudeDiscoveryBindingRefusalCode = "POLICY_PATH_MISMATCH" | "POLICY_UNAVAILABLE" | "POLICY_UNREADABLE" | "BINDING_UNAVAILABLE" | "BINDING_INVALID" | "POLICY_CHANGED";
+/** A request, policy or stored-binding read/parse failure: no verdict. */
+export declare class ClaudeDiscoveryBindingRefusal extends Error {
+    readonly code: ClaudeDiscoveryBindingRefusalCode;
+    constructor(code: ClaudeDiscoveryBindingRefusalCode);
+}
+export type ClaudeBindingSourceFailure = "MISSING" | "APPEARED" | "CHANGED" | "MARKER_INVALID" | "REFUSED";
+export type ClaudeBindingDirectoryFailure = "MEMBERSHIP_CHANGED" | "REFUSED";
+export interface ClaudeBindingSourceReport {
+    index: number;
+    path: string;
+    hashMode: string | null;
+    format: string | null;
+    sha256: string | null;
+    status: "current" | "retained-absent" | "drift";
+    retention?: {
+        rule: typeof ABSENT_RETIRED_CLAUDE_VERSION_RULE;
+        root: string;
+        witness: RetainedAbsentWitness;
+    };
+    reason?: ClaudeBindingSourceFailure;
+}
+export interface ClaudeBindingDirectoryReport {
+    index: number;
+    path: string;
+    status: "current" | "drift";
+    reason?: ClaudeBindingDirectoryFailure;
+}
+export type ClaudeBindingFailure = {
+    kind: "source";
+    index: number;
+    path: string;
+    reason: ClaudeBindingSourceFailure;
+} | {
+    kind: "directory";
+    index: number;
+    path: string;
+    reason: ClaudeBindingDirectoryFailure;
+} | {
+    kind: "binding";
+    reason: "DISCOVERY_REFUSED";
+};
+export interface ClaudeDiscoveryBindingVerification {
+    schema: typeof CLAUDE_DISCOVERY_BINDING_VERIFICATION_SCHEMA;
+    ok: boolean;
+    policySha256: string;
+    discoverySha256: string;
+    agent: "claude";
+    method: "reviewed" | "automatic";
+    rootCount: number;
+    sources: ClaudeBindingSourceReport[];
+    directories: ClaudeBindingDirectoryReport[];
+    failures: ClaudeBindingFailure[];
+}
+/** Verify the stored `bridge.discovery.claude` binding of the package-owned
+ * Skills policy. `ok` is true only when the hook's own discovery verification
+ * accepts the binding and every source is current or retained under the
+ * absent retired version rule, and every directory witness is current. */
+export declare function verifyClaudeInstallerDiscoveryBinding(policyPath: string): ClaudeDiscoveryBindingVerification;

package/dist/lib/codex-node-modules.d.ts

@@ -0,0 +1,11 @@
+/** Whether Codex can load a skill below `path`, a `node_modules` directory
+ * `depth` levels below its plugin cache. A marketplace, plugin or version
+ * directory is an identity, so one named `node_modules` is always walked.
+ * Inside a version, the directory is walked when it lies in, or leads to, a
+ * manifest-declared skills path or the default `skills` root. Codex replaces
+ * the default with a declared path; Skills keeps walking it, as it walks every
+ * other visible directory in the cache. A manifest that cannot be read exactly
+ * (a link or special file, oversized, invalid UTF-8 or JSON, duplicate keys, an
+ * unsupported skills shape or an escaping path) walks it too, so an unreadable
+ * declaration never hides a loaded skill. */
+export declare function codexPluginCacheSkillTree(path: string, depth: number): boolean;

package/dist/lib/codex-settings-witness-v1.d.ts

@@ -1,5 +1,14 @@
 import { type ClaudeSettingsWitnessBudget } from "./claude-settings-witness.js";
 export declare function hashCodexSettingsReplacement(text: string, budget?: ClaudeSettingsWitnessBudget): string;
+/** The parsed document and numeric spellings a V1 digest binds, before the
+ * documented inference fields are removed. Callers that edit the structure
+ * (codexSettingsToleratesScreenReaderReceipt) finish each edited copy separately. */
+export declare function prepareCodexSettingsV1(text: string): {
+    config: Record<string, any>;
+    tokens: string[];
+};
+/** The V1 digest of a prepared structure. Mutates `config`. */
+export declare function finishCodexSettingsV1(config: Record<string, any>, tokens: string[]): string;
 export declare function captureCodexSettings(path: string, budget?: ClaudeSettingsWitnessBudget): {
     path: string;
     hashMode: "codex-settings-v1";

package/dist/lib/codex-settings-witness.d.ts

@@ -5,6 +5,24 @@ import { type ClaudeSettingsWitnessBudget } from "./claude-settings-witness.js";
  * `codex-settings-v2` witness binds strictly more of the same file, so it
  * supersedes this projection instead of coexisting with it. */
 export declare const CODEX_DISCOVERY_PROJECTION_FIELDS: readonly ["plugins", "marketplaces", "skills"];
+/** Typed modes whose digests bind the receipt. */
+export type CodexReceiptSettingsMode = "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5";
+/** How a current document relates to a typed V1-V5 witness's reviewed digest.
+ * `screen-reader-receipt` is the only tolerated difference. */
+export type CodexSettingsWitnessMatch = "exact" | "screen-reader-receipt";
+/** True when `text` differs from the document a typed V1-V5 witness reviewed
+ * only by the boolean screen-reader receipt, proven by reproducing `expected`
+ * under the witness's own unchanged digest from the current document with the
+ * receipt edited back. The text-bound projections (local MCP rows, V4 counts,
+ * numeric spelling) run once on the current text; a receipt line holds no
+ * numeric token. Digest values never change and nothing is recorded. Any other
+ * TUI key, a non-boolean value and every other difference stay bound.
+ * Fail-closed: errors return false. */
+export declare function codexSettingsToleratesScreenReaderReceipt(text: string, hashMode: CodexReceiptSettingsMode, expected: string): boolean;
+/** Read a typed V1-V5 settings witness file once and classify it against the
+ * reviewed digest: `exact`, `screen-reader-receipt` (the only tolerated
+ * difference), or null (drift). */
+export declare function codexSettingsWitnessMatch(path: string, hashMode: CodexReceiptSettingsMode, expected: string, budget?: ClaudeSettingsWitnessBudget): CodexSettingsWitnessMatch | null;
 export declare function hashCodexSettingsReplacementV2(text: string, budget?: ClaudeSettingsWitnessBudget): string;
 export declare function captureCodexSettingsV2(path: string, budget?: ClaudeSettingsWitnessBudget): {
     path: string;

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute7 } from "path";
 // package.json
-var version = "0.10.72";
+var version = "0.10.73";
 var package_default = {
   name: "@hasna/skills",
   version,