@cleocode/caamp 2026.9.19 → 2026.9.21

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { PackageArtifactBudgets, PackageArtifactRequirement, PackageArtifactFile
 import { WorktreeHandle } from '@cleocode/cant';
 import { PlatformPaths, SystemInfo } from '@cleocode/paths';
 export { PlatformPaths, SystemInfo } from '@cleocode/paths';
+import { SkillGateScanResult, SkillGatePolicyDecision, SkillGateFederationResult, SkillGateFederationInput } from '@cleocode/contracts';
 
 /**
  * Priority tier identifier stored in registry.json.
@@ -123,6 +124,62 @@ type RegistryHookCatalog = 'canonical' | 'pi';
  * @public
  */
 type SpawnMechanism = 'native' | 'native-child-process' | 'mcp' | 'cli' | 'api';
+/**
+ * Whether a provider exposes a structured-question ("ask the human") tool.
+ *
+ * - `native`  — the harness ships a built-in tool that renders selectable options.
+ * - `none`    — verified absent from the harness's built-in tool set.
+ * - `unknown` — not verified from docs or source; never guessed.
+ *
+ * @public
+ */
+type AskToolStatus = 'native' | 'none' | 'unknown';
+/**
+ * Registry record of a provider's structured-question tool.
+ *
+ * @remarks
+ * Data only. `source` says where the fact was verified so a stale entry can be
+ * re-checked; `caveat` records availability limits (mode gates, subagent
+ * restrictions). When `toolName` is `null` the agent uses
+ * {@link HitlRequestFallback} instead.
+ *
+ * @public
+ */
+interface ProviderAskTool {
+    /** Verification status of the ask tool. */
+    status: AskToolStatus;
+    /** Exact tool name the model calls, or `null` when none is known. */
+    toolName: string | null;
+    /** Availability limits, or `null` when none are known. */
+    caveat: string | null;
+    /** Where the fact was verified (doc URL, source path, or binary inspected). */
+    source: string;
+}
+/**
+ * Fallback when a provider has no (known) ask tool: the agent emits ONE LAFS
+ * envelope with this operation carrying the payload fields, then stops.
+ *
+ * @public
+ */
+interface HitlRequestFallback {
+    /** LAFS operation name of the envelope. */
+    operation: 'hitl.request';
+    /** Payload fields the envelope `data` carries. */
+    fields: readonly ['question', 'options', 'recommended'];
+    /** Shape of each option entry. */
+    optionFields: readonly ['label', 'description'];
+}
+/**
+ * Resolved ask-tool answer for one provider.
+ *
+ * @public
+ */
+interface ResolvedProviderAskTool extends ProviderAskTool {
+    /** Canonical provider id (aliases resolved). */
+    providerId: string;
+    /** The `hitl.request` fallback; use it whenever `toolName` is `null`. */
+    fallback: HitlRequestFallback;
+}
 
 /**
  * SkillLibrary interface - SDK standard contract for skill libraries.
@@ -3160,14 +3217,82 @@ declare function withFileLock<T>(targetPath: string, fn: () => Promise<T>, optio
  * @public
  */
 declare function assertNotTornRead(filePath: string, content: string, sizeOnDisk: number): void;
+/**
+ * A JSON config file could not be parsed, so it was left untouched.
+ *
+ * @remarks
+ * Thrown by {@link updateJsonConfigFile} instead of treating the file as empty.
+ * The pre-T12385 provider adapters caught the parse error and started from
+ * `{}`, so a torn read of `~/.claude/settings.json` (Claude Code rewriting it
+ * at the same moment) replaced the user's permissions, env, model and hooks
+ * with CLEO's entries alone.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await updateJsonConfigFile(path, (config) => false);
+ * } catch (err) {
+ *   if (err instanceof JsonConfigParseError) console.error(err.filePath);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class JsonConfigParseError extends Error {
+    /** Path of the file that failed to parse. */
+    readonly filePath: string;
+    /**
+     * @param filePath - Path of the file that failed to parse
+     * @param reason - Parser message
+     */
+    constructor(filePath: string, reason: string);
+}
+/**
+ * Read-modify-write a JSON object file under the cross-process lock, writing
+ * atomically, and never replacing an unparseable file.
+ *
+ * @remarks
+ * Composes the two existing primitives — {@link withFileLock} and core's
+ * `writeFileAtomic` — for provider config files such as
+ * `~/.claude/settings.json` that the provider itself also rewrites (T12385):
+ *
+ * - The whole read → mutate → write cycle holds the `<file>.lock` guard, so
+ *   two CLEO writers cannot both read the pre-state and clobber each other.
+ * - The write is tmp-then-rename, so a concurrent reader (including the
+ *   provider) sees the whole old file or the whole new one.
+ * - A missing file starts from `{}`. A file that exists but is empty on read
+ *   while non-empty on disk, is not valid JSON, or is not a JSON object throws
+ *   ({@link assertNotTornRead} / {@link JsonConfigParseError}) and the file is
+ *   left byte-identical.
+ *
+ * @param filePath - JSON file to update
+ * @param mutate - Edits the parsed object in place; returns `true` when it
+ *   changed something that must be written
+ * @returns Whether the file was written
+ * @throws {@link JsonConfigParseError} when the existing file cannot be parsed
+ *   as a JSON object; the file is not modified
+ *
+ * @example
+ * ```typescript
+ * const wrote = await updateJsonConfigFile(settingsPath, (settings) => {
+ *   if (settings.enabled === true) return false;
+ *   settings.enabled = true;
+ *   return true;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function updateJsonConfigFile(filePath: string, mutate: (config: Record<string, unknown>) => boolean): Promise<boolean>;
 
 /**
  * Skill installer - canonical + symlink model
  *
- * Skills are stored once in a canonical location (`~/.cleo/skills/<name>/`
- * per architecture-v3 §1, with legacy `~/.local/share/agents/skills/` as a
- * read-only fallback for one release cycle) and symlinked to each target
- * agent's skills directory.
+ * Skills are stored once in a canonical location (`<cleoHome>/skills/<name>/`,
+ * the platform data dir from `resolveSkillsRoot()`; T12598) and linked to each
+ * target agent's skills directory. Every link is verified to resolve after it
+ * is written; where a link cannot be created or does not resolve (Windows
+ * without Developer Mode, filesystems without symlinks) the skill is copied.
  *
  * @task T9659
  * @epic T9571
@@ -3287,6 +3412,76 @@ interface SkillInstallResult {
     /** Whether at least one agent was successfully linked. */
     success: boolean;
 }
+/**
+ * Move a fully staged entry onto `targetPath` without ever deleting the entry
+ * it replaces before the replacement is in place.
+ *
+ * @remarks
+ * T12383. The previous installer ran `rm -rf <target>` and only then copied
+ * the new source; when the copy failed (for instance because the "source" was
+ * the unresolved string `library:<name>`) the installed skill was gone.
+ *
+ * The swap moves the current entry aside to a hidden sibling, renames the
+ * staged entry into place, then deletes the set-aside copy. If the second
+ * rename fails, the set-aside copy is renamed back, so a failure at any step
+ * leaves the original entry where it was. POSIX offers no portable atomic
+ * exchange of two directories, so the path is absent for the span of one
+ * `rename(2)` — but no step discards data that has not already been superseded
+ * on disk.
+ *
+ * When a concurrent installer occupies the path between the two renames, the
+ * swap retries a bounded number of times; the last writer wins, as before.
+ *
+ * @param stagedPath - A complete replacement, on the same filesystem as `targetPath`
+ * @param targetPath - The path to replace (need not exist)
+ * @throws The underlying filesystem error when the swap cannot complete; the
+ *   original entry is restored before the error propagates
+ *
+ * @example
+ * ```typescript
+ * const staged = await stageSkillCopy("/tmp/my-skill", target);
+ * await swapIntoPlace(staged, target);
+ * ```
+ *
+ * @public
+ */
+declare function swapIntoPlace(stagedPath: string, targetPath: string): Promise<void>;
+/**
+ * Copy `sourcePath` into a hidden staging sibling of `targetPath`.
+ *
+ * @remarks
+ * Nothing at `targetPath` is touched. If the copy fails the partial staging
+ * directory is removed and the error propagates.
+ *
+ * @param sourcePath - Directory to copy
+ * @param targetPath - Path the staged copy will later replace
+ * @returns Absolute path of the complete staged copy
+ * @throws The copy error (e.g. `ENOENT` when `sourcePath` does not exist)
+ *
+ * @example
+ * ```typescript
+ * const staged = await stageSkillCopy("/tmp/my-skill", "/home/u/.cleo/skills/my-skill");
+ * ```
+ *
+ * @public
+ */
+declare function stageSkillCopy(sourcePath: string, targetPath: string): Promise<string>;
+/**
+ * Replace the directory at `targetPath` with a copy of `sourcePath`, staging
+ * the copy completely before anything existing is moved.
+ *
+ * @param sourcePath - Directory to copy
+ * @param targetPath - Directory to replace (need not exist)
+ * @throws When the copy or the swap fails; the existing directory is kept
+ *
+ * @example
+ * ```typescript
+ * await replaceDirectoryFromSource("/tmp/my-skill", "/home/u/.pi/agent/skills/my-skill");
+ * ```
+ *
+ * @public
+ */
+declare function replaceDirectoryFromSource(sourcePath: string, targetPath: string): Promise<void>;
 /**
  * Heuristic source-type classifier for installs that don't carry an explicit
  * `source_type`.
@@ -5450,6 +5645,82 @@ interface EnsureProviderInstructionFileResult {
  * @public
  */
 declare function ensureProviderInstructionFile(providerId: string, projectDir: string, options: EnsureProviderInstructionFileOptions): Promise<EnsureProviderInstructionFileResult>;
+/**
+ * Options for {@link ensureProviderRuleFile}.
+ *
+ * @public
+ */
+interface EnsureProviderRuleFileOptions {
+    /** File path relative to the project directory (e.g. `.cursor/rules/cleo.mdc`). */
+    relativePath: string;
+    /**
+     * Text the file must begin with (e.g. MDC frontmatter). When set, CAAMP owns
+     * the whole file: its content is exactly the preamble followed by one CAAMP
+     * block. When omitted, only the CAAMP block is managed and every byte outside
+     * it is preserved.
+     * @defaultValue `undefined`
+     */
+    preamble?: string;
+    /** Update the file only when it already exists; never create it. @defaultValue `false` */
+    onlyIfExists?: boolean;
+    /**
+     * `@` references to write. Defaults to the provider's registry
+     * `instructionReferences`.
+     * @defaultValue Registry `instructionReferences` for the provider
+     */
+    references?: string[];
+}
+/**
+ * Result of {@link ensureProviderRuleFile}.
+ *
+ * @public
+ */
+interface EnsureProviderRuleFileResult {
+    /** Absolute path of the rule file. */
+    filePath: string;
+    /** Action taken. */
+    action: CaampInjectionAction;
+    /** Provider ID. */
+    providerId: string;
+}
+/**
+ * Ensure a provider's auxiliary rule file (one that is not its registry
+ * `instructFile`) carries the CAAMP-managed reference block.
+ *
+ * @remarks
+ * ADR-064: every provider instruction write goes through CAAMP. Some providers
+ * read extra rule files beside their primary instruction file — Cursor reads
+ * `.cursor/rules/*.mdc` and the legacy `.cursorrules` — and the adapters used
+ * to write those with raw `writeFileSync` and a local copy of the references
+ * (T12385). This writes them the way {@link inject} writes instruction files:
+ * under the cross-process lock, atomically, with a torn-read guard, and with
+ * references from the registry.
+ *
+ * The block carries references, not embedded sources: these files sit beside
+ * the provider's primary instruction file, which
+ * {@link ensureProviderInstructionFile} already fills with the self-contained
+ * delivery, so embedding here would load the protocol twice.
+ *
+ * A file managed without a preamble that predates CAAMP markers has its bare
+ * reference lines replaced by the block rather than duplicated.
+ *
+ * @param providerId - Provider ID from the registry
+ * @param projectDir - Absolute project directory
+ * @param options - Target path, optional preamble, create policy, references
+ * @returns The result, or `null` when `onlyIfExists` is set and the file is absent
+ * @throws Error if the provider ID is not in the registry, or on a torn read
+ *
+ * @example
+ * ```typescript
+ * await ensureProviderRuleFile("cursor", "/project", {
+ *   relativePath: ".cursor/rules/cleo.mdc",
+ *   preamble: "---\nalwaysApply: true\n---\n",
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function ensureProviderRuleFile(providerId: string, projectDir: string, options: EnsureProviderRuleFileOptions): Promise<EnsureProviderRuleFileResult | null>;
 /**
  * Ensure instruction files for multiple providers at once.
  *
@@ -7377,6 +7648,47 @@ declare function getProviderCapabilities(idOrAlias: string): ProviderCapabilitie
  * @public
  */
 declare function providerSupportsById(idOrAlias: string, capabilityPath: string): boolean;
+/**
+ * The fallback every agent uses when its provider has no known ask tool: emit
+ * ONE LAFS envelope `hitl.request` with `{question, options[{label,
+ * description}], recommended}` in `data`, then stop.
+ *
+ * @public
+ */
+declare const HITL_REQUEST_FALLBACK: HitlRequestFallback;
+/**
+ * Structured-question ("ask the human") tool per provider id.
+ *
+ * @remarks
+ * DATA, keyed by the canonical id in `providers/registry.json`; every registry
+ * provider has an entry (a test enforces it). Only verified names are
+ * recorded — anything not found in docs or source is `unknown`, never
+ * invented. Researched 2026-09-27 for T12482.
+ *
+ * @public
+ */
+declare const PROVIDER_ASK_TOOLS: Readonly<Record<string, ProviderAskTool>>;
+/**
+ * Resolve the structured-question tool for a provider, with the
+ * `hitl.request` fallback attached.
+ *
+ * @remarks
+ * Canonical ids are looked up directly (no registry load); anything else is
+ * alias-resolved through the registry. An id with no entry resolves to
+ * `unknown` so callers always get an answer and a fallback.
+ *
+ * @param idOrAlias - Provider ID or alias (e.g. `"claude"`)
+ * @returns The ask-tool record, its canonical provider id and the fallback
+ *
+ * @example
+ * ```typescript
+ * getProviderAskTool('claude').toolName; // "AskUserQuestion"
+ * getProviderAskTool('aider').toolName;  // null -> use fallback (hitl.request)
+ * ```
+ *
+ * @public
+ */
+declare function getProviderAskTool(idOrAlias: string): ResolvedProviderAskTool;
 
 /**
  * Spawn adapter interface for provider-neutral subagent orchestration.
@@ -8214,6 +8526,372 @@ declare function discoverSkill(skillDir: string): Promise<SkillEntry | null>;
  */
 declare function discoverSkills(rootDir: string): Promise<SkillEntry[]>;
 
+/**
+ * Shared LAFS utilities for CAAMP commands
+ *
+ * Provides standardized LAFS envelope creation, error handling, and format resolution
+ * to ensure all commands follow the LAFS (Language-Agnostic Format Specification) protocol.
+ *
+ * @module lafs
+ * @requires @cleocode/lafs
+ * @requires ../logger.js
+ */
+
+/**
+ * Common error codes for consistency.
+ *
+ * @public
+ */
+declare const ErrorCodes: {
+    readonly FORMAT_CONFLICT: "E_FORMAT_CONFLICT";
+    readonly INVALID_JSON: "E_INVALID_JSON";
+    readonly SKILL_NOT_FOUND: "E_SKILL_NOT_FOUND";
+    readonly PROVIDER_NOT_FOUND: "E_PROVIDER_NOT_FOUND";
+    readonly MCP_SERVER_NOT_FOUND: "E_MCP_SERVER_NOT_FOUND";
+    readonly FILE_NOT_FOUND: "E_FILE_NOT_FOUND";
+    readonly INVALID_INPUT: "E_INVALID_INPUT";
+    readonly INVALID_CONSTRAINT: "E_INVALID_CONSTRAINT";
+    readonly INVALID_FORMAT: "E_INVALID_FORMAT";
+    readonly INSTALL_FAILED: "E_INSTALL_FAILED";
+    readonly SKILL_TRUST_GATE_BLOCKED: "E_SKILL_TRUST_GATE_BLOCKED";
+    /** The skill security gate could not be loaded, so the install was refused (T12384). */
+    readonly SKILL_GATE_UNAVAILABLE: "E_SKILL_GATE_UNAVAILABLE";
+    readonly FEDERATION_UNKNOWN_SOURCE_INTERACTIVE_REQUIRED: "E_FEDERATION_UNKNOWN_SOURCE_INTERACTIVE_REQUIRED";
+    readonly FEDERATION_CHECKSUM_MISMATCH: "E_FEDERATION_CHECKSUM_MISMATCH";
+    readonly REMOVE_FAILED: "E_REMOVE_FAILED";
+    readonly UPDATE_FAILED: "E_UPDATE_FAILED";
+    readonly VALIDATION_FAILED: "E_VALIDATION_FAILED";
+    readonly AUDIT_FAILED: "E_AUDIT_FAILED";
+    readonly NETWORK_ERROR: "E_NETWORK_ERROR";
+    readonly FILE_SYSTEM_ERROR: "E_FILE_SYSTEM_ERROR";
+    readonly PERMISSION_DENIED: "E_PERMISSION_DENIED";
+    readonly INTERNAL_ERROR: "E_INTERNAL_ERROR";
+};
+
+/**
+ * Gated skill install pipeline — the one library entry point every skill
+ * install goes through, from `caamp skills install` and from `cleo tools skill
+ * install` alike.
+ *
+ * Before T12384 the pipeline (resolve → fetch → security gate → copy → link →
+ * record) lived inside the Commander action in `commands/skills/install.ts`,
+ * where CLEO could not reach it. CLEO therefore called the bare `installSkill`
+ * primitive, which has no gate, and passed it the literal string
+ * `library:<name>` as a filesystem path (T12383). The caamp copy of the gate
+ * also failed OPEN: when `@cleocode/core` could not be loaded it logged a
+ * warning and installed anyway.
+ *
+ * This module fixes all three:
+ *
+ * - {@link resolveSkillSource} turns any accepted source string — a registered
+ *   library id (`library:<name>` or a bare name), a local path, a GitHub or
+ *   GitLab repo/URL, a marketplace `@author/name` — into a real local
+ *   directory, or throws. It never hands an identifier to the copier.
+ * - {@link runSkillInstallGate} runs the federation checksum gate and the
+ *   skills-guard scan and FAILS CLOSED: if the gate's modules cannot be loaded,
+ *   the install is refused.
+ * - {@link installSkillFromSource} / {@link installResolvedSkill} are the only
+ *   functions that should place a skill. Both gate before any filesystem
+ *   write, and the underlying copier stages the new copy before replacing the
+ *   old one.
+ *
+ * @task T12383
+ * @task T12384
+ */
+
+/**
+ * Error codes raised by the gated install pipeline.
+ *
+ * @remarks
+ * Values are drawn from caamp's LAFS {@link ErrorCodes} table so CLI envelopes
+ * and library callers report the same code for the same refusal.
+ *
+ * @public
+ */
+type SkillInstallErrorCode = typeof ErrorCodes.SKILL_NOT_FOUND | typeof ErrorCodes.INVALID_INPUT | typeof ErrorCodes.INVALID_FORMAT | typeof ErrorCodes.NETWORK_ERROR | typeof ErrorCodes.SKILL_TRUST_GATE_BLOCKED | typeof ErrorCodes.SKILL_GATE_UNAVAILABLE | typeof ErrorCodes.FEDERATION_CHECKSUM_MISMATCH | typeof ErrorCodes.FEDERATION_UNKNOWN_SOURCE_INTERACTIVE_REQUIRED;
+/**
+ * Structured detail attached to a {@link SkillInstallError}.
+ *
+ * @public
+ */
+interface SkillInstallErrorDetails {
+    /** Scan result when the refusal came from the skills-guard scan. */
+    scan?: SkillGateScanResult;
+    /** Federation gate result when the refusal came from the checksum/source gate. */
+    federation?: SkillGateFederationResult;
+    /** Skill names the registered library does offer, when a lookup missed. */
+    availableSkills?: string[];
+    /** Underlying error message, when the refusal wraps another failure. */
+    cause?: string;
+}
+/**
+ * A skill install that was refused before anything was written.
+ *
+ * @remarks
+ * Every refusal from this module is thrown as this type, so callers can map
+ * `code` to an envelope and trust that the installed copy was not touched.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await installSkillFromSource("owner/repo", { providers, isGlobal: true });
+ * } catch (err) {
+ *   if (err instanceof SkillInstallError) console.error(err.code, err.message);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class SkillInstallError extends Error {
+    /** Machine-readable refusal code. */
+    readonly code: SkillInstallErrorCode;
+    /** Structured context for the refusal. */
+    readonly details: SkillInstallErrorDetails;
+    /**
+     * @param code - Refusal code
+     * @param message - Human-readable reason
+     * @param details - Structured context
+     */
+    constructor(code: SkillInstallErrorCode, message: string, details?: SkillInstallErrorDetails);
+}
+/**
+ * A skill source resolved to a real local directory.
+ *
+ * @public
+ */
+interface ResolvedSkillSource {
+    /** Absolute path of the directory to install from. */
+    localPath: string;
+    /** Name the skill is installed under. */
+    skillName: string;
+    /** Provenance string recorded for the install (e.g. `library:ct-foo`, a GitHub URL). */
+    sourceValue: string;
+    /** Classified source type. */
+    sourceType: SourceType;
+    /** Removes any temporary checkout; absent for sources that live on disk already. */
+    cleanup?: () => Promise<void>;
+}
+/**
+ * A resolution step worth telling a human about.
+ *
+ * @remarks
+ * The library does not print; a CLI renders these (e.g. in `--human` mode).
+ *
+ * @public
+ */
+type SkillSourceProgress = {
+    readonly kind: 'marketplace-search';
+    readonly source: string;
+} | {
+    readonly kind: 'marketplace-found';
+    readonly name: string;
+    readonly author: string;
+    readonly repo: string;
+} | {
+    readonly kind: 'catalog-found';
+    readonly name: string;
+    readonly version: string;
+    readonly category: string;
+};
+/**
+ * Resolve a skill source string to a real local directory.
+ *
+ * @remarks
+ * Accepted forms:
+ *
+ * - `library:<name>` (or `<package>:<name>`) and bare `<name>` — looked up in
+ *   the registered skill library ({@link catalog}).
+ * - An absolute, `./`, `../` or `~` path — used as is (the name comes from its
+ *   `SKILL.md` when present).
+ * - `owner/repo[/path]`, a GitHub URL or a GitLab URL — cloned to a temporary
+ *   directory; call `cleanup` when done.
+ * - `@author/name` — looked up in the skill marketplace, then cloned.
+ *
+ * Anything else is refused. An identifier is never returned as `localPath`,
+ * which is the T12383 defect: `library:<name>` used to reach `cp()` verbatim.
+ *
+ * @param source - Source string as typed by the user or stored in a lock row
+ * @param onProgress - Optional sink for human-facing resolution events
+ * @returns The resolved local source
+ * @throws {@link SkillInstallError} when the source cannot be resolved
+ *
+ * @example
+ * ```typescript
+ * const resolved = await resolveSkillSource("library:ct-cleo");
+ * try {
+ *   console.log(resolved.localPath);
+ * } finally {
+ *   await resolved.cleanup?.();
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function resolveSkillSource(source: string, onProgress?: (event: SkillSourceProgress) => void): Promise<ResolvedSkillSource>;
+/**
+ * The `@cleocode/core` functions the gate calls.
+ *
+ * @remarks
+ * Loaded lazily because core depends on caamp at build time; a static import
+ * of these modules would put core's whole skills graph on caamp's startup
+ * path. Typed against the shared `@cleocode/contracts` gate shapes, which
+ * mirror core's types structurally, so core's functions are assignable here.
+ *
+ * @public
+ */
+interface SkillGateModules {
+    /** Skills-guard static scan. */
+    scanSkill: (skillPath: string, source: string) => SkillGateScanResult;
+    /** INSTALL_POLICY decision over a scan result. */
+    shouldAllowInstall: (result: SkillGateScanResult, force: boolean) => SkillGatePolicyDecision;
+    /** Federation first-install and checksum gate. */
+    evaluateFederationInstallGate: (opts: SkillGateFederationInput) => SkillGateFederationResult;
+    /** Audit writer for operator `force` bypasses. */
+    recordTrustBypass: (result: SkillGateScanResult, reason: string | null) => object;
+}
+/**
+ * Options for {@link runSkillInstallGate}.
+ *
+ * @public
+ */
+interface SkillInstallGateOptions {
+    /** Operator override of a `block` scan decision (audited). Never overrides `ask` or a checksum mismatch. */
+    force?: boolean;
+    /** Approve a first install from an unverified federation source (non-interactive contexts). */
+    allowNewSource?: boolean;
+    /** Checksum the artefact must match, when the source declares one. */
+    expectedChecksum?: string | null;
+}
+/**
+ * What the gate decided, for callers that report it.
+ *
+ * @public
+ */
+interface SkillInstallGateReport {
+    /** The skills-guard scan of the staged source. */
+    scan: SkillGateScanResult;
+    /** The install-policy decision (always `allow` when this returns). */
+    decision: SkillGatePolicyDecision;
+    /** The federation gate result (always `allow` when this returns). */
+    federation: SkillGateFederationResult;
+    /** Whether an operator `force` bypass was used and audited. */
+    bypassed: boolean;
+}
+/**
+ * Run the federation checksum gate and the skills-guard scan over a resolved
+ * source. Fails closed.
+ *
+ * @remarks
+ * Order matters: the federation gate runs first, so a checksum mismatch or an
+ * unapproved federation source is refused before the scanner reads the bytes.
+ * Both run before any filesystem write.
+ *
+ * Unlike the pre-T12384 caamp CLI gate, a failure to load the gate's modules is
+ * a refusal (`E_SKILL_GATE_UNAVAILABLE`), not a skipped check.
+ *
+ * @param source - The resolved source to vet
+ * @param options - Operator overrides
+ * @returns The gate report when the install may proceed
+ * @throws {@link SkillInstallError} when the install is refused or the gate is unavailable
+ *
+ * @example
+ * ```typescript
+ * const report = await runSkillInstallGate(resolved, { force: false });
+ * console.log(report.scan.verdict);
+ * ```
+ *
+ * @public
+ */
+declare function runSkillInstallGate(source: ResolvedSkillSource, options?: SkillInstallGateOptions): Promise<SkillInstallGateReport>;
+/**
+ * Options for {@link installSkillFromSource} and {@link installResolvedSkill}.
+ *
+ * @public
+ */
+interface GatedSkillInstallOptions extends SkillInstallGateOptions {
+    /** Providers to link the skill into. */
+    providers: Provider[];
+    /** Global (`true`) or project scope. */
+    isGlobal: boolean;
+    /** Project directory for project scope. */
+    projectDir?: string;
+    /** Provenance sink forwarded to the canonical installer. */
+    recordRow?: InstallSkillOptions['recordRow'];
+    /** Record the install in the CAAMP lock file. @defaultValue false */
+    recordLock?: boolean;
+    /** Override the name the skill installs under. */
+    skillName?: string;
+    /** Sink for human-facing resolution events (used by {@link installSkillFromSource}). */
+    onProgress?: (event: SkillSourceProgress) => void;
+}
+/**
+ * Result of a gated install.
+ *
+ * @public
+ */
+interface GatedSkillInstallResult extends SkillInstallResult {
+    /** Provenance string recorded for the install. */
+    sourceValue: string;
+    /** Classified source type. */
+    sourceType: SourceType;
+    /** The gate's report. */
+    gate: SkillInstallGateReport;
+}
+/**
+ * Gate and install an already-resolved source.
+ *
+ * @remarks
+ * Use this when the caller has a checkout in hand (for example an update that
+ * cloned the source itself). The gate runs first; on refusal nothing is
+ * written. The canonical copy is staged before it replaces the installed one
+ * (T12383), so a failure part-way through keeps the installed skill.
+ *
+ * Does not call `source.cleanup` — the caller owns the checkout.
+ *
+ * @param source - Resolved source
+ * @param options - Targets, scope, provenance and gate overrides
+ * @returns The install result, including the gate report
+ * @throws {@link SkillInstallError} when the gate refuses the install
+ *
+ * @example
+ * ```typescript
+ * const result = await installResolvedSkill(
+ *   { localPath: "/tmp/co/skill", skillName: "demo", sourceValue: "owner/repo", sourceType: "github" },
+ *   { providers, isGlobal: true },
+ * );
+ * ```
+ *
+ * @public
+ */
+declare function installResolvedSkill(source: ResolvedSkillSource, options: GatedSkillInstallOptions): Promise<GatedSkillInstallResult>;
+/**
+ * Resolve, gate and install a skill from any accepted source string.
+ *
+ * @remarks
+ * The single entry point for installing a skill (T12384). Resolution turns the
+ * source into a real directory ({@link resolveSkillSource}); the gate vets it
+ * and fails closed ({@link runSkillInstallGate}); the installer stages the new
+ * copy before replacing the old one. Temporary checkouts are always removed.
+ *
+ * @param source - `library:<name>`, a bare library name, a local path,
+ *   `owner/repo`, a GitHub/GitLab URL, or `@author/name`
+ * @param options - Targets, scope, provenance and gate overrides
+ * @returns The install result, including the gate report
+ * @throws {@link SkillInstallError} when the source cannot be resolved or the gate refuses it
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkillFromSource("library:ct-cleo", {
+ *   providers: getInstalledProviders(),
+ *   isGlobal: true,
+ * });
+ * console.log(result.linkedAgents);
+ * ```
+ *
+ * @public
+ */
+declare function installSkillFromSource(source: string, options: GatedSkillInstallOptions): Promise<GatedSkillInstallResult>;
+
 /**
  * Skill integrity checking
  *
@@ -9153,4 +9831,4 @@ declare function parseSource(input: string): ParsedSource;
  */
 declare function isMarketplaceScoped(input: string): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type BlockInsertPosition, CANONICAL_HOOK_EVENTS, CLEO_ARTIFACT_BUDGETS, CLEO_ARTIFACT_REQUIREMENTS, type CaampBlock, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CantProfileCounts, type CantProfileEntry, type CantValidationDiagnostic, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, DEFAULT_EXCLUSIVITY_MODE, type DedupeResult, type DetectionCacheOptions, type DetectionResult, EXCLUSIVITY_MODE_ENV_VAR, EmbeddedDeliveryDowngradeError, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type ExclusivityMode, type FileLockOptions, type GlobalInstructionOptions, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstallSkillOptions, type InstructionUpdateSummary, type KnownProviderAgentFolderId, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizeResult, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, PiRequiredError, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type ReconcileResult, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type RepairResult, type ResolveDefaultTargetProvidersOptions, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillRowData, type SkillRowSourceType, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SyncGlobalInstructionsOptions, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, type WriteAgentFileOptions, type WriteAgentFileResult, _resetPlatformPathsCache, assertCleoShippedBuildShape, assertNotTornRead, blockPattern, buildBlock, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkGlobalInstructionStaleness, checkInjection, checkSkillIntegrity, checkSkillUpdate, classifyPackageFilesEntry, clearRegisteredLibrary, dedupeFile, dedupeFiles, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderAgentFolder, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderInstructionReferences, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inferSkillSourceType, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, instructionFileCascade, isCaampOwnedSkill, isEmbeddedDelivery, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, mergeBlockBodies, normalizeMarkers, normalizeRecommendationCriteria, parseBlocks, parseCaampBlocks, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, reconcile, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, repairContent, repairInstructionFiles, resetDetectionCache, resetExclusivityModeOverride, resetRegistry, resolveAlias, resolveDefaultTargetProviders, resolveGlobalInstructionPath, resolveInstructionDelivery, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, syncGlobalInstructions, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validatePackageArtifact, validateRecommendationCriteria, validateSkill, withFileLock, writeAgentFileToAllProviders, writeConfig };
+export { type AskToolStatus, type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type BlockInsertPosition, CANONICAL_HOOK_EVENTS, CLEO_ARTIFACT_BUDGETS, CLEO_ARTIFACT_REQUIREMENTS, type CaampBlock, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CantProfileCounts, type CantProfileEntry, type CantValidationDiagnostic, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, DEFAULT_EXCLUSIVITY_MODE, type DedupeResult, type DetectionCacheOptions, type DetectionResult, EXCLUSIVITY_MODE_ENV_VAR, EmbeddedDeliveryDowngradeError, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type EnsureProviderRuleFileOptions, type EnsureProviderRuleFileResult, type ExclusivityMode, type FileLockOptions, type GatedSkillInstallOptions, type GatedSkillInstallResult, type GlobalInstructionOptions, type GlobalOptions, HITL_REQUEST_FALLBACK, HOOK_CATEGORIES, type Harness, type HarnessScope, type HitlRequestFallback, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstallSkillOptions, type InstructionUpdateSummary, JsonConfigParseError, type KnownProviderAgentFolderId, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizeResult, type NormalizedHookEvent, type NormalizedRecommendationCriteria, PROVIDER_ASK_TOOLS, type ParsedSource, PiHarness, PiRequiredError, type Provider, type ProviderAskTool, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type ReconcileResult, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type RepairResult, type ResolveDefaultTargetProvidersOptions, type ResolvedProviderAskTool, type ResolvedSkillSource, type SkillBatchOperation, type SkillEntry, type SkillGateModules, SkillInstallError, type SkillInstallErrorCode, type SkillInstallErrorDetails, type SkillInstallGateOptions, type SkillInstallGateReport, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillRowData, type SkillRowSourceType, type SkillSourceProgress, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SyncGlobalInstructionsOptions, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, type WriteAgentFileOptions, type WriteAgentFileResult, _resetPlatformPathsCache, assertCleoShippedBuildShape, assertNotTornRead, blockPattern, buildBlock, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkGlobalInstructionStaleness, checkInjection, checkSkillIntegrity, checkSkillUpdate, classifyPackageFilesEntry, clearRegisteredLibrary, dedupeFile, dedupeFiles, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, ensureProviderRuleFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderAgentFolder, getProviderAskTool, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderInstructionReferences, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inferSkillSourceType, inject, injectAll, installBatchWithRollback, installMcpServer, installResolvedSkill, installSkill, installSkillFromSource, instructionFileCascade, isCaampOwnedSkill, isEmbeddedDelivery, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, mergeBlockBodies, normalizeMarkers, normalizeRecommendationCriteria, parseBlocks, parseCaampBlocks, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, reconcile, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, repairContent, repairInstructionFiles, replaceDirectoryFromSource, resetDetectionCache, resetExclusivityModeOverride, resetRegistry, resolveAlias, resolveDefaultTargetProviders, resolveGlobalInstructionPath, resolveInstructionDelivery, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, resolveSkillSource, runSkillInstallGate, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, stageSkillCopy, supportsHook, swapIntoPlace, syncGlobalInstructions, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, updateJsonConfigFile, validateInstructionIntegrity, validatePackageArtifact, validateRecommendationCriteria, validateSkill, withFileLock, writeAgentFileToAllProviders, writeConfig };