@cleocode/caamp 2026.4.6 → 2026.4.9

package/dist/index.d.ts

@@ -1488,328 +1488,501 @@ interface InstructionUpdateSummary {
 declare function updateInstructionsSingleOperation(providers: Provider[], content: string, scope?: Scope, projectDir?: string): Promise<InstructionUpdateSummary>;
 
 /**
- * Format utility functions
- */
-/**
- * Deep merge two objects, with `source` values winning on conflict.
- *
- * Recursively merges nested plain objects. Arrays and non-object values from
- * `source` overwrite `target` values.
- *
- * @param target - Base object to merge into
- * @param source - Object with values that take precedence
- * @returns A new merged object (does not mutate inputs)
+ * Three-tier scope helper for Pi harness operations.
  *
  * @remarks
- * Only plain objects are recursively merged. Arrays and primitive values from
- * `source` replace `target` values outright. Neither input is mutated.
- *
- * @example
- * ```typescript
- * const merged = deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
- * // { a: 1, b: { c: 2, d: 3 } }
- * ```
+ * Per ADR-035 §D1, CAAMP wraps Pi's native two-tier extension model
+ * (project-local `.pi/extensions/` → global `~/.pi/agent/extensions/`)
+ * with a third tier for the CleoOS-managed cross-project hub. The
+ * resulting hierarchy, in precedence order on reads:
  *
- * @public
- */
-declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
-/**
- * Get a nested value from an object using a dot-notation key path.
+ * | Tier      | Path                                           | Who owns it              |
+ * | --------- | ---------------------------------------------- | ------------------------ |
+ * | `project` | `<cwd>/.pi/<asset>/`                           | repository               |
+ * | `user`    | `$PI_CODING_AGENT_DIR` or `~/.pi/agent/<asset>`| Pi itself                |
+ * | `global`  | `$CLEO_HOME/pi-<asset>/`                       | CleoOS (this wrapper)    |
  *
- * @param obj - Object to traverse
- * @param keyPath - Dot-separated key path (e.g. `"mcpServers"` or `"a.b.c"`)
- * @returns The value at the key path, or `undefined` if not found
+ * Pi's own discovery loader is NOT modified. The `global` tier is either
+ * copied or symlinked into the `user` tier on first use (lazy
+ * materialization), so Pi's native two-tier loader picks extensions up
+ * from the familiar location without needing a patch.
  *
- * @remarks
- * Splits the key path on `.` and walks the object tree. Returns `undefined`
- * at the first missing or non-object segment.
+ * This helper intentionally lives next to {@link ../harness/pi.ts} rather
+ * than being exported at a higher level — three-tier scope is a Pi
+ * concept today, and other harnesses (if any ever land) will want their
+ * own mapping.
  *
- * @example
- * ```typescript
- * getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
- * getNestedValue({ a: 1 }, "a.b"); // undefined
- * ```
+ * @see ADR-035 §D1 (Three-tier scope hierarchy with explicit precedence)
  *
- * @public
+ * @packageDocumentation
  */
-declare function getNestedValue(obj: Record<string, unknown>, keyPath: string): unknown;
 /**
- * Ensure that the parent directories of a file path exist.
- *
- * Creates directories recursively if they do not exist.
- *
- * @param filePath - Absolute path to a file (parent directories will be created)
+ * Three-tier scope identifier for Pi harness operations.
  *
  * @remarks
- * Uses `mkdir` with `recursive: true` so existing directories are not an error.
- *
- * @example
- * ```typescript
- * await ensureDir("/path/to/new/dir/file.json");
- * // /path/to/new/dir/ now exists
- * ```
+ * Each tier maps to a distinct root directory; see the module overview
+ * for the precedence and resolution rules. This is distinct from (and
+ * coexists with) the legacy {@link HarnessScope} discriminated union,
+ * which only supports two tiers (`global`/`project`) and is preserved
+ * for back-compat with existing skill/instruction installers.
  *
  * @public
  */
-declare function ensureDir(filePath: string): Promise<void>;
+type HarnessTier = 'project' | 'user' | 'global';
 
 /**
- * Provides format-agnostic config read, write, and remove operations that
- * dispatch to JSON/JSONC, YAML, or TOML handlers based on the specified
- * format.
+ * Harness layer type definitions.
+ *
+ * @remarks
+ * Defines the contract every first-class CAAMP harness must implement.
+ * A harness is a provider that CAAMP treats natively — not through the
+ * generic MCP-config-file path. Pi is the first (and currently only)
+ * harness. The interface is intentionally generic so future harnesses
+ * (Goose, OpenCode, ...) can slot in without shape churn.
+ *
+ * All methods are async even when they could be sync, so implementations
+ * that need I/O (filesystem, child process) are not forced to lie about
+ * their return types.
  *
  * @packageDocumentation
  */
 
 /**
- * Read and parse a config file in the specified format.
- *
- * Dispatches to the appropriate format handler (JSON/JSONC, YAML, or TOML).
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @returns Parsed config object
- * @throws If the file cannot be read or the format is unsupported
+ * Scope at which a harness operation should be performed.
  *
  * @remarks
- * Supported formats: `"json"`, `"jsonc"`, `"yaml"`, `"toml"`. Throws for
- * any unrecognized format string.
+ * Harness operations target either the user's global state root (e.g.
+ * `~/.pi/agent/`) or a specific project directory. Project scope requires
+ * the caller to provide the absolute project directory path — the harness
+ * does not infer cwd.
  *
- * @example
- * ```typescript
- * const config = await readConfig("/path/to/config.json", "jsonc");
- * ```
+ * This two-tier scope is the legacy shape used by the skill and
+ * instructions install paths. Pi-specific Wave-1 verbs (extensions,
+ * sessions, models, prompts, themes) use the three-tier
+ * {@link HarnessTier} hierarchy introduced in ADR-035 §D1 alongside this
+ * type — the two coexist and neither replaces the other.
  *
  * @public
  */
-declare function readConfig(filePath: string, format: ConfigFormat): Promise<Record<string, unknown>>;
+type HarnessScope = {
+    kind: 'global';
+} | {
+    kind: 'project';
+    projectDir: string;
+};
 /**
- * Write a server entry to a config file, preserving existing content.
- *
- * Dispatches to the appropriate format handler. For JSONC files, comments are
- * preserved using `jsonc-parser`.
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @param key - Dot-notation key path to the servers section (e.g. `"mcpServers"`)
- * @param serverName - Name/key for the server entry
- * @param serverConfig - Server configuration object to write
- * @throws If the format is unsupported
+ * Options accepted by `resolveDefaultTargetProviders` (defined in
+ * `./index.ts`).
  *
  * @remarks
- * For JSONC files, comments and formatting are preserved using `jsonc-parser`.
- * For YAML and TOML, the file is fully re-serialized after deep-merging.
+ * Both fields are optional. When the entire options object is omitted the
+ * helper behaves exactly as it did pre-ADR-035 §D7 in `auto` mode with Pi
+ * installed — the no-regression contract for existing callers.
  *
- * @example
- * ```typescript
- * await writeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server", config);
- * ```
+ * Lives here in `types.ts` rather than next to the function so that
+ * downstream packages can `import type { ResolveDefaultTargetProvidersOptions }`
+ * without pulling in the harness dispatcher's runtime imports.
  *
  * @public
  */
-declare function writeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string, serverConfig: unknown): Promise<void>;
+interface ResolveDefaultTargetProvidersOptions {
+    /**
+     * Explicit list of providers requested by the user (e.g. via `--agent`).
+     *
+     * @remarks
+     * When supplied, this list signals that the caller is honouring an
+     * explicit user selection rather than asking for the implicit default.
+     * In `auto` mode, an explicit list that excludes Pi while Pi is installed
+     * triggers a one-time deprecation warning per process. In `force-pi`
+     * mode the explicit list is ignored if it does not contain Pi (Pi is
+     * still required). In `legacy` mode the list is returned verbatim with
+     * no warning.
+     *
+     * Pass `undefined` (or omit entirely) to request the implicit default
+     * resolution.
+     *
+     * @defaultValue undefined
+     */
+    explicit?: Provider[];
+}
 /**
- * Remove a server entry from a config file in the specified format.
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @param key - Dot-notation key path to the servers section
- * @param serverName - Name/key of the server entry to remove
- * @returns `true` if the entry was removed, `false` otherwise
- * @throws If the format is unsupported
+ * Controls how `resolveDefaultTargetProviders` (defined in `./index.ts`)
+ * selects target providers at runtime invocation time.
  *
  * @remarks
- * Delegates to the format-specific removal function. Returns `false` when the
- * file does not exist or the entry is not found.
+ * Introduced by ADR-035 §D7 ("v3 exclusivity") to give users an explicit
+ * knob over how aggressively CAAMP routes runtime commands through Pi
+ * versus other installed providers.
  *
- * @example
- * ```typescript
- * const removed = await removeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server");
- * ```
+ * - `'auto'` (default) — Pi is preferred when installed; explicit
+ *   `--agent <non-pi>` selections are still honoured but emit a one-time
+ *   deprecation warning per process. Behaviourally identical to v2026.4.5
+ *   when no explicit non-Pi target is supplied.
+ * - `'force-pi'` — Pi is required at runtime invocation. The dispatcher
+ *   throws with an `E_NOT_FOUND_RESOURCE`-shaped error when Pi is not
+ *   installed; callers decide whether to surface this as an exit code 4
+ *   or render a remediation hint.
+ * - `'legacy'` — Pre-exclusivity behaviour. No deprecation warnings, no
+ *   hard requirement on Pi. Matches the resolution order CAAMP shipped
+ *   before ADR-035 §D7 landed; preserved so users with brittle scripts
+ *   can pin until they migrate.
+ *
+ * **Important**: this setting affects RUNTIME INVOCATION paths only. Skill
+ * and instruction install paths
+ * (e.g. {@link dispatchInstallSkillAcrossProviders} and friends) are
+ * UNAFFECTED and continue to dispatch to multiple providers regardless of
+ * mode. See ADR-035 §D7 for the full design rationale.
  *
  * @public
  */
-declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
-
+type ExclusivityMode = 'auto' | 'force-pi' | 'legacy';
 /**
- * Skill installer - canonical + symlink model
+ * Metadata describing a Pi extension discovered on disk.
  *
- * Skills are stored once in a canonical location (.agents/skills/<name>/)
- * and symlinked to each target agent's skills directory.
+ * @remarks
+ * Returned by {@link Harness.listExtensions}. The `tier` records which
+ * tier the extension lives at so that callers can surface the
+ * precedence story in their output.
+ *
+ * @public
  */
-
+interface ExtensionEntry {
+    /** Extension name (file basename without the `.ts` extension). */
+    name: string;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the extension file. */
+    path: string;
+    /**
+     * When `true`, this entry is shadowed by a higher-precedence entry
+     * with the same name. Exposed so list output can warn about
+     * cross-tier name collisions per ADR-035 §D1.
+     * @defaultValue false
+     */
+    shadowed?: boolean;
+}
 /**
- * Result of installing a skill to the canonical location and linking to agents.
+ * Metadata describing a Pi prompt directory discovered on disk.
  *
- * @example
- * ```typescript
- * const result = await installSkill(sourcePath, "my-skill", providers, true);
- * if (result.success) {
- *   console.log(`Installed to ${result.canonicalPath}`);
- *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
- * }
- * ```
+ * @remarks
+ * Returned by {@link Harness.listPrompts}. Prompts are directories
+ * containing a `prompt.md` plus optional metadata. The list operation
+ * reads only the directory listing — never the prompt bodies — to keep
+ * token usage minimal per ADR-035 §D1.
  *
  * @public
  */
-interface SkillInstallResult {
-    /** Skill name. */
+interface PromptEntry {
+    /** Prompt name (directory basename). */
     name: string;
-    /** Absolute path to the canonical installation directory. */
-    canonicalPath: string;
-    /** Provider IDs that were successfully linked. */
-    linkedAgents: string[];
-    /** Error messages from failed link operations. */
-    errors: string[];
-    /** Whether at least one agent was successfully linked. */
-    success: boolean;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the prompt directory. */
+    path: string;
+    /** See {@link ExtensionEntry.shadowed}. @defaultValue false */
+    shadowed?: boolean;
 }
 /**
- * Install a skill from a local path to the canonical location and link to agents.
+ * Metadata describing a Pi theme discovered on disk.
  *
  * @remarks
- * Copies the skill directory to the canonical skills directory and creates symlinks
- * (or copies on Windows) from each provider's skills directory to the canonical path.
- *
- * @param sourcePath - Local path to the skill directory to install
- * @param skillName - Name for the installed skill
- * @param providers - Target providers to link the skill to
- * @param isGlobal - Whether to link to global or project skill directories
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Install result with linked agents and any errors
+ * Returned by {@link Harness.listThemes}. Themes are single `.ts` or
+ * `.json` files matching Pi's native theme module shape.
  *
- * @example
- * ```typescript
- * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true, "/my/project");
- * if (result.success) {
- *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
- * }
- * ```
+ * @public
+ */
+interface ThemeEntry {
+    /** Theme name (file basename without the extension). */
+    name: string;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the theme file. */
+    path: string;
+    /** File extension of the theme file (e.g. `".ts"`, `".json"`). */
+    fileExt: string;
+    /** See {@link ExtensionEntry.shadowed}. @defaultValue false */
+    shadowed?: boolean;
+}
+/**
+ * Options accepted by the Pi install verbs (extensions, prompts, themes).
  *
  * @public
  */
-declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
+interface HarnessInstallOptions {
+    /**
+     * When `true`, overwrite an existing file at the target tier. When
+     * `false` (the default) the install verb throws if the target exists.
+     * @defaultValue false
+     */
+    force?: boolean;
+}
 /**
- * Remove a skill from the canonical location and all agent symlinks.
+ * Counts of top-level CANT sections discovered in a `.cant` file.
  *
  * @remarks
- * Removes symlinks from each provider's skills directory and then removes the
- * canonical copy from the centralized canonical skills directory.
+ * Returned by {@link Harness.listCantProfiles} and
+ * {@link Harness.validateCantProfile} so that callers can surface a
+ * concise summary of every profile (agents, workflows, pipelines,
+ * top-level hooks, and skill references declared by an agent's
+ * `skills:` property) without reading the full document body.
  *
- * @param skillName - Name of the skill to remove
- * @param providers - Providers to unlink the skill from
- * @param isGlobal - Whether to target global or project skill directories
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Object with arrays of successfully removed provider IDs and error messages
- *
- * @example
- * ```typescript
- * const { removed, errors } = await removeSkill("my-skill", providers, true, "/my/project");
- * console.log(`Removed from: ${removed.join(", ")}`);
- * ```
+ * The cant-core AST tags every section as a single-key wrapper
+ * (`{ Agent: { ... } }`, `{ Workflow: { ... } }`, etc.), so these
+ * counters are derived by walking `document.sections` and bucketing
+ * by tag. `skillCount` aggregates the unique skill names declared
+ * across every Agent section's `skills:` property — it is NOT a
+ * count of standalone `skill { ... }` blocks because cant-core does
+ * not currently expose those at the document level.
  *
  * @public
  */
-declare function removeSkill(skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<{
-    removed: string[];
-    errors: string[];
-}>;
+interface CantProfileCounts {
+    /** Number of `agent { ... }` sections in the document. */
+    agentCount: number;
+    /** Number of `workflow { ... }` sections in the document. */
+    workflowCount: number;
+    /** Number of `pipeline { ... }` sections in the document. */
+    pipelineCount: number;
+    /**
+     * Number of hook bodies discovered. Top-level `Hook` sections plus
+     * the `hooks` array nested inside every Agent section are summed.
+     */
+    hookCount: number;
+    /**
+     * Number of distinct skill names referenced via an Agent section's
+     * `skills:` property (e.g. `skills: ["ct-cleo", "ct-task-executor"]`).
+     * The count is de-duplicated across agents within a single document.
+     */
+    skillCount: number;
+}
 /**
- * List all skills installed in the canonical skills directory.
+ * Metadata describing a `.cant` profile installed at one of the three
+ * Pi harness tiers.
  *
  * @remarks
- * Returns the directory names of all skills, which correspond to skill names.
- * Includes both regular directories and symlinks in the canonical location.
- *
- * @returns Array of skill names
- *
- * @example
- * ```typescript
- * const skills = await listCanonicalSkills();
- * // ["my-skill", "another-skill"]
- * ```
+ * Returned by {@link Harness.listCantProfiles}. Mirrors the shape of
+ * {@link ExtensionEntry} so consumers can render both with the same
+ * UI primitives, but adds a {@link counts} bag with parsed AST stats
+ * so the list output can summarise each profile without forcing the
+ * caller to re-parse every file.
  *
  * @public
  */
-declare function listCanonicalSkills(): Promise<string[]>;
-
+interface CantProfileEntry {
+    /** Profile name (basename of the `.cant` file without the extension). */
+    name: string;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the `.cant` file. */
+    sourcePath: string;
+    /** Parsed section counts for the profile. */
+    counts: CantProfileCounts;
+    /**
+     * When `true`, this entry is shadowed by a higher-precedence entry
+     * with the same name. Mirrors the shadow flag emitted by
+     * {@link Harness.listExtensions} so the same UI logic applies.
+     * @defaultValue false
+     */
+    shadowedByHigherTier?: boolean;
+}
 /**
- * Harness layer type definitions.
+ * Diagnostic emitted by the cant-core 42-rule validator, normalised to
+ * the harness layer's vocabulary.
  *
  * @remarks
- * Defines the contract every first-class CAAMP harness must implement.
- * A harness is a provider that CAAMP treats natively — not through the
- * generic MCP-config-file path. Pi is the first (and currently only)
- * harness. The interface is intentionally generic so future harnesses
- * (Goose, OpenCode, ...) can slot in without shape churn.
- *
- * All methods are async even when they could be sync, so implementations
- * that need I/O (filesystem, child process) are not forced to lie about
- * their return types.
+ * Mirrors the `NativeDiagnostic` shape exported by `@cleocode/cant`'s
+ * native loader. Captured here as a first-class harness type so callers
+ * never have to import from `@cleocode/cant` directly to consume
+ * {@link Harness.validateCantProfile} results.
  *
- * @packageDocumentation
+ * @public
  */
-
+interface CantValidationDiagnostic {
+    /** Cant-core rule id (`PARSE`, `S01`, `P06`, ...). */
+    ruleId: string;
+    /** Human-readable diagnostic message. */
+    message: string;
+    /** 1-based line number where the diagnostic was emitted. */
+    line: number;
+    /** 1-based column number where the diagnostic was emitted. */
+    col: number;
+    /** Severity bucket from cant-core (`error`, `warning`, `info`, `hint`). */
+    severity: 'error' | 'warning' | 'info' | 'hint';
+}
 /**
- * Scope at which a harness operation should be performed.
+ * Result of validating a `.cant` profile via the cant-core 42-rule
+ * engine.
  *
  * @remarks
- * Harness operations target either the user's global state root (e.g.
- * `~/.pi/agent/`) or a specific project directory. Project scope requires
- * the caller to provide the absolute project directory path — the harness
- * does not infer cwd.
+ * Returned by {@link Harness.validateCantProfile}. The `valid` flag is
+ * `true` only when no error-severity diagnostics were emitted (warnings
+ * are tolerated, matching cant-core's own definition). The
+ * {@link counts} bag is populated only when parsing succeeded — when
+ * the file is so broken cant-core cannot produce a document, every
+ * counter is `0` and the diagnostics array carries the parse errors.
  *
  * @public
  */
-type HarnessScope = {
-    kind: 'global';
-} | {
-    kind: 'project';
-    projectDir: string;
-};
+interface ValidateCantProfileResult {
+    /** Whether validation passed (no error-severity diagnostics). */
+    valid: boolean;
+    /** All diagnostics emitted by the 42-rule engine, in source order. */
+    errors: CantValidationDiagnostic[];
+    /** Section counts for the profile (zero when parsing failed). */
+    counts: CantProfileCounts;
+}
+/**
+ * Summary header extracted from the first line of a Pi session JSONL file.
+ *
+ * @remarks
+ * Per ADR-035 §D2, `list`-style session operations read only line 1 of
+ * each `*.jsonl` file — never the full body — so this shape is what
+ * callers consume when enumerating sessions. The full session loader
+ * returns raw JSONL line strings as a separate type
+ * ({@link SessionDocument}).
+ *
+ * @public
+ */
+interface SessionSummary {
+    /** Session identifier as recorded in the line-1 header. */
+    id: string;
+    /** Session version as recorded in the line-1 header (e.g. `3`). */
+    version: number;
+    /** ISO-8601 timestamp from the line-1 header, or `null` when absent. */
+    timestamp: string | null;
+    /** Working directory recorded when the session was created. */
+    cwd: string | null;
+    /** Parent session id, if this session was forked from another. */
+    parentSession: string | null;
+    /** Absolute path to the session JSONL file on disk. */
+    filePath: string;
+    /** File modification time in milliseconds since the epoch. */
+    mtimeMs: number;
+}
 /**
- * Declarative description of an MCP server that should be bridged into a
- * harness's native extension mechanism.
+ * Raw content of a Pi session JSONL file, preserved line-by-line.
  *
  * @remarks
- * This is a harness-agnostic input shape. Fields mirror the MCP
- * configuration surface: stdio transports use {@link command} + {@link args},
- * remote transports use {@link url} + optional {@link headers}, and all
- * transports may carry environment variables via {@link env}.
+ * Returned by {@link Harness.showSession} when a caller needs the full
+ * body. Each element is one JSONL line as a string (empty trailing
+ * lines are stripped). Callers that need typed entries parse each line
+ * themselves; the harness does not impose a type on entry bodies
+ * because Pi's own entry schema is open-ended (`message`, `thinking`,
+ * `custom`, etc.) and we do not want to fall behind Pi's schema
+ * evolution.
+ *
+ * @public
+ */
+interface SessionDocument {
+    /** Header summary (same shape as {@link SessionSummary}). */
+    summary: SessionSummary;
+    /** Raw JSONL lines in file order, excluding the line-1 header. */
+    entries: string[];
+}
+/**
+ * Pi model definition as recorded under `models.json:providers[].models`.
  *
- * Harnesses that cannot host MCP servers as extensions will throw or omit
- * the {@link Harness.installMcpAsExtension} method entirely.
+ * @remarks
+ * Mirrors the `ModelDefinition` schema in
+ * `@mariozechner/pi-coding-agent`'s model-registry. Fields are typed
+ * loosely because Pi's schema is evolving (see ADR-035 §D3); the keys
+ * captured here are the minimum a CAAMP verb needs to reason about.
  *
  * @public
  */
-interface McpServerSpec {
-    /** Logical name of the MCP server (e.g. `"filesystem"`, `"brave-search"`). */
+interface PiModelDefinition {
+    /** Model id within the provider (e.g. `"claude-opus-4-20250514"`). */
+    id: string;
+    /** Human-readable model name. */
     name: string;
     /**
-     * Command to launch the server over stdio transport.
+     * Whether the model supports reasoning/thinking tokens.
      * @defaultValue undefined
      */
-    command?: string;
+    reasoning?: boolean;
     /**
-     * Arguments for the stdio command.
+     * Allowed input modalities (e.g. `["text"]`, `["text", "image"]`).
      * @defaultValue undefined
      */
-    args?: string[];
+    input?: Array<'text' | 'image'>;
     /**
-     * URL for SSE/HTTP transports.
+     * Context window size in tokens.
      * @defaultValue undefined
      */
-    url?: string;
+    contextWindow?: number;
     /**
-     * Environment variables for the server process.
+     * Maximum output tokens.
      * @defaultValue undefined
      */
-    env?: Record<string, string>;
+    maxTokens?: number;
+}
+/**
+ * Pi provider block as recorded under `models.json:providers[id]`.
+ *
+ * @remarks
+ * Mirrors the `ProviderConfig` schema in Pi's model-registry.
+ *
+ * @public
+ */
+interface PiModelProvider {
     /**
-     * HTTP headers for remote transports.
+     * Custom base URL for the provider (overrides default).
      * @defaultValue undefined
      */
-    headers?: Record<string, string>;
+    baseUrl?: string;
+    /**
+     * API key or `$ENV_VAR` reference.
+     * @defaultValue undefined
+     */
+    apiKey?: string;
+    /**
+     * Custom model definitions declared by the user.
+     * @defaultValue undefined
+     */
+    models?: PiModelDefinition[];
+}
+/**
+ * Entire `models.json` document shape used by Pi.
+ *
+ * @remarks
+ * Mirrors the `ModelsConfig` schema in Pi's model-registry. CAAMP reads
+ * and writes this file through {@link Harness.readModelsConfig} /
+ * {@link Harness.writeModelsConfig}.
+ *
+ * @public
+ */
+interface PiModelsConfig {
+    /** Map of provider id → provider block. */
+    providers: Record<string, PiModelProvider>;
+}
+/**
+ * A model entry as surfaced by {@link Harness.listModels}.
+ *
+ * @remarks
+ * Models are reported as a union of `models.json`-defined custom models
+ * and `settings.json:enabledModels` selections, with flags that record
+ * whether each entry is currently enabled and whether it is the
+ * configured default.
+ *
+ * @public
+ */
+interface ModelListEntry {
+    /** Provider id (e.g. `"anthropic"`). */
+    provider: string;
+    /** Model id within the provider. */
+    id: string;
+    /** Human-readable name, from `models.json` when available. */
+    name: string | null;
+    /** `true` when the model is present in `settings.json:enabledModels`. */
+    enabled: boolean;
+    /** `true` when the model is the configured default. */
+    isDefault: boolean;
+    /**
+     * `true` when this model is defined in `models.json` (custom). When
+     * `false`, the entry originates from `settings.json:enabledModels`
+     * only and is assumed to resolve against Pi's built-in registry.
+     */
+    custom: boolean;
 }
 /**
  * Description of a subagent task to be spawned under a harness.
@@ -1820,6 +1993,12 @@ interface McpServerSpec {
  * is a routing hint passed to the harness; concrete harnesses may use it
  * to select an inner agent or simply record it for observability.
  *
+ * Per ADR-035 §D6, every spawn has a stable {@link taskId} and is
+ * attributed to a parent session via {@link parentSessionId}. When the
+ * caller provides {@link parentSessionPath}, the harness records a
+ * `subagent_link` custom entry into that file so listing the parent
+ * session surfaces its children automatically.
+ *
  * @public
  */
 interface SubagentTask {
@@ -1827,6 +2006,42 @@ interface SubagentTask {
     targetProviderId: string;
     /** The prompt / instruction to give the spawned agent. */
     prompt: string;
+    /**
+     * Stable task identifier used to derive the child session filename and
+     * to correlate streamed events with their originating task.
+     *
+     * @remarks
+     * When omitted, the harness generates a short id at spawn time so
+     * legacy callers (pre-ADR-035 §D6) keep working. New callers SHOULD
+     * always supply a deterministic value.
+     *
+     * @defaultValue undefined
+     */
+    taskId?: string;
+    /**
+     * Identifier of the parent session that owns this subagent.
+     *
+     * @remarks
+     * Used to compose the child session filename
+     * (`subagent-{parentSessionId}-{taskId}.jsonl`) per ADR-035 §D6.
+     * When omitted, the harness substitutes `"orphan"` so legacy callers
+     * still produce a well-formed file path.
+     *
+     * @defaultValue undefined
+     */
+    parentSessionId?: string;
+    /**
+     * Absolute path to the parent session JSONL file.
+     *
+     * @remarks
+     * When supplied, the harness appends a {@link SubagentLinkEntry} as
+     * a `custom` entry to this file at spawn time so listing the parent
+     * surfaces its children automatically. When omitted, no link entry
+     * is written and the parent session is not modified.
+     *
+     * @defaultValue undefined
+     */
+    parentSessionPath?: string;
     /**
      * Working directory for the spawned agent.
      * @defaultValue undefined
@@ -1838,18 +2053,136 @@ interface SubagentTask {
      */
     env?: Record<string, string>;
     /**
-     * Abort signal. When it aborts, the harness will terminate the subagent.
+     * Abort signal. When it aborts, the harness will terminate the subagent
+     * via the configured SIGTERM-then-SIGKILL cleanup sequence.
      * @defaultValue undefined
      */
     signal?: AbortSignal;
 }
 /**
- * Final result of a subagent's execution.
+ * Per-call options that override harness-wide spawn defaults.
  *
  * @remarks
- * Collected once the child process exits. {@link parsed} is populated
- * on a best-effort basis: if the subagent emits JSON on stdout the
- * harness will parse it, otherwise {@link parsed} is left undefined.
+ * Introduced for ADR-035 §D6 streaming + cleanup semantics. Every field
+ * is optional so callers that just want default behaviour can omit the
+ * second argument entirely.
+ *
+ * @public
+ */
+interface SubagentSpawnOptions {
+    /**
+     * Streaming callback invoked once per parsed event from the child.
+     *
+     * @remarks
+     * The harness fires this for every line of stdout (parsed as JSON when
+     * possible), every line of stderr, the final exit, and the
+     * `subagent_link` write. Callbacks are best-effort: throwing from the
+     * callback is caught and recorded as a stderr line so the spawn loop
+     * is never aborted by user code.
+     *
+     * @defaultValue undefined
+     */
+    onStream?: (event: SubagentStreamEvent) => void;
+    /**
+     * Override the SIGTERM grace window before SIGKILL fires.
+     *
+     * @remarks
+     * When omitted, the harness reads
+     * `settings.json:pi.subagent.terminateGraceMs` (global scope) and
+     * falls back to `5000` ms if absent or invalid. Tests use very small
+     * values to keep cleanup checks fast.
+     *
+     * @defaultValue undefined
+     */
+    terminateGraceMs?: number;
+    /**
+     * Environment variable overrides layered atop the task-level env.
+     *
+     * @remarks
+     * Convenience hook for per-call secrets that should not live on the
+     * task object itself. Merged after {@link SubagentTask.env} so
+     * call-site keys win.
+     *
+     * @defaultValue undefined
+     */
+    env?: Record<string, string>;
+    /**
+     * Working directory override that wins over {@link SubagentTask.cwd}.
+     *
+     * @remarks
+     * Useful when the same task description is reused across multiple
+     * working directories.
+     *
+     * @defaultValue undefined
+     */
+    cwd?: string;
+}
+/**
+ * One streaming event surfaced through {@link SubagentSpawnOptions.onStream}.
+ *
+ * @remarks
+ * Discriminated by {@link kind}:
+ *
+ * - `"message"` — a successfully parsed JSON line from the child's
+ *   stdout. {@link payload} is the parsed object and {@link lineNumber}
+ *   is the 1-based line index within the child's stdout stream.
+ * - `"stderr"` — a single line from the child's stderr stream. The
+ *   {@link payload} is `{ line: string }`. The harness NEVER injects
+ *   stderr into the parent LLM context per ADR-035 §D6.
+ * - `"exit"` — the child has exited. {@link payload} is a
+ *   {@link SubagentExitResult}.
+ * - `"link"` — the harness wrote a `subagent_link` custom entry to the
+ *   parent session. {@link payload} is the {@link SubagentLinkEntry}.
+ *
+ * @public
+ */
+interface SubagentStreamEvent {
+    /** Event kind discriminator. */
+    kind: 'message' | 'stderr' | 'exit' | 'link';
+    /** Subagent identifier (matches {@link SubagentHandle.subagentId}). */
+    subagentId: string;
+    /**
+     * 1-based line number within the child's stdout stream. Only set for
+     * `"message"` events that originated from a parsed stdout line.
+     * @defaultValue undefined
+     */
+    lineNumber?: number;
+    /** Event payload, shaped according to {@link kind}. */
+    payload: unknown;
+}
+/**
+ * Resolution value of {@link SubagentHandle.exitPromise}.
+ *
+ * @remarks
+ * Captured exactly once when the child process exits. The promise NEVER
+ * rejects — failure is encoded by a non-zero {@link code}, a non-null
+ * {@link signal}, or partial output preserved in the child session file
+ * at {@link childSessionPath}.
+ *
+ * @public
+ */
+interface SubagentExitResult {
+    /**
+     * Process exit code, or `null` when the child was terminated by a
+     * signal before exiting normally.
+     */
+    code: number | null;
+    /** Terminating signal, or `null` when the child exited normally. */
+    signal: NodeJS.Signals | null;
+    /** Absolute path to the child session JSONL file on disk. */
+    childSessionPath: string;
+    /** Wall-clock duration from spawn to exit, in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Final result of a subagent's execution (legacy v1 shape).
+ *
+ * @remarks
+ * Preserved for back-compat with pre-ADR-035 §D6 callers. New code
+ * SHOULD await {@link SubagentHandle.exitPromise} (which resolves with
+ * a richer {@link SubagentExitResult}) instead. The harness still
+ * populates this field on every spawn so existing tests and callers
+ * keep working.
  *
  * @public
  */
@@ -1872,18 +2205,87 @@ interface SubagentResult {
  *
  * @remarks
  * Returned synchronously from {@link Harness.spawnSubagent}. The caller
- * may await {@link result} to collect the final output, or invoke
- * {@link abort} to terminate the child early.
+ * may:
+ *
+ * - Await {@link exitPromise} to collect the rich {@link SubagentExitResult}
+ *   (preferred path, ADR-035 §D6).
+ * - Await {@link result} to collect the legacy {@link SubagentResult}
+ *   (preserved for back-compat).
+ * - Invoke {@link terminate} (preferred) or {@link abort} (legacy) to
+ *   stop the child early via the configured SIGTERM-then-SIGKILL
+ *   cleanup sequence.
+ * - Inspect {@link recentStderr} for the most recent stderr lines
+ *   captured by the harness — useful for post-mortem diagnostics
+ *   without injecting stderr into the parent LLM context.
  *
  * @public
  */
 interface SubagentHandle {
+    /**
+     * Stable subagent identifier generated at spawn time.
+     *
+     * @remarks
+     * Format: `sub-{taskId}-{shortRandom}`. Used to correlate
+     * {@link SubagentStreamEvent} entries and `subagent_link` records
+     * with this handle. Always defined (the harness never returns a
+     * handle without one).
+     */
+    subagentId: string;
+    /** Task identifier from {@link SubagentTask.taskId} (or generated default). */
+    taskId: string;
+    /** Absolute path to the child session JSONL file on disk. */
+    childSessionPath: string;
     /** PID of the spawned process, or `null` if spawning did not yield one. */
     pid: number | null;
-    /** Promise resolving to the subagent's final output once the process exits. */
+    /** Wall-clock timestamp captured immediately after spawn. */
+    startedAt: Date;
+    /**
+     * Promise resolving to the rich exit result once the child process
+     * has fully terminated. NEVER rejects — failures are encoded in the
+     * resolved value (non-zero code, non-null signal, partial output in
+     * the session file).
+     */
+    exitPromise: Promise<SubagentExitResult>;
+    /**
+     * Promise resolving to the legacy {@link SubagentResult} shape.
+     *
+     * @remarks
+     * Preserved for back-compat. Resolves to the same exit code as
+     * {@link exitPromise} plus the full captured stdout / stderr buffers
+     * and a best-effort `parsed` field for callers that emit a single
+     * JSON document.
+     */
     result: Promise<SubagentResult>;
-    /** Synchronously terminate the subagent. Safe to call after exit. */
+    /**
+     * Terminate the subagent gracefully.
+     *
+     * @remarks
+     * Sends SIGTERM, waits for the configured grace window, then sends
+     * SIGKILL if the child is still alive. Idempotent — subsequent calls
+     * after the first are no-ops. Returns once the cleanup sequence has
+     * fully resolved.
+     */
+    terminate(): Promise<void>;
+    /**
+     * Synchronously trigger the cleanup sequence (legacy v1 alias for
+     * {@link terminate}).
+     *
+     * @remarks
+     * Preserved so existing callers that use `handle.abort()` keep
+     * working. Internally enqueues the same SIGTERM-then-SIGKILL flow as
+     * {@link terminate} but does not return the resulting promise.
+     */
     abort: () => void;
+    /**
+     * Snapshot of the most recent stderr lines captured for this child.
+     *
+     * @remarks
+     * Bounded ring buffer (last 100 lines) so memory cannot grow without
+     * bound under chatty stderr. Stderr is NEVER injected into the
+     * parent LLM context — this accessor is intended for diagnostics and
+     * post-mortem inspection only.
+     */
+    recentStderr(): string[];
 }
 /**
  * Contract every first-class harness must implement.
@@ -1895,9 +2297,9 @@ interface SubagentHandle {
  * harness; the interface is shaped so future harnesses (Goose, OpenCode, ...)
  * can be added without changing any caller code.
  *
- * Optional methods ({@link installMcpAsExtension}, {@link spawnSubagent},
- * {@link configureModels}) may be omitted by harnesses that cannot support
- * them. Callers MUST feature-check before invoking.
+ * Optional methods ({@link spawnSubagent}, {@link configureModels}) may be
+ * omitted by harnesses that cannot support them. Callers MUST feature-check
+ * before invoking.
  *
  * @public
  */
@@ -1965,38 +2367,31 @@ interface Harness {
      * @param scope - Instruction file scope.
      */
     removeInstructions(scope: HarnessScope): Promise<void>;
-    /**
-     * Install an MCP server as a harness extension.
-     *
-     * @remarks
-     * For legacy providers with a native MCP config file, this is a
-     * passthrough. For Pi it generates a TypeScript extension file under
-     * `extensions/` that wraps the MCP server as a Pi tool via
-     * `pi.registerTool()`.
-     *
-     * Optional — harnesses that cannot host MCP bridges should omit this
-     * method. Callers MUST feature-check before invoking.
-     *
-     * @param server - Server spec to bridge.
-     * @param scope - Install scope.
-     */
-    installMcpAsExtension?(server: McpServerSpec, scope: HarnessScope): Promise<void>;
     /**
      * Spawn a subagent under this harness's control.
      *
      * @remarks
      * For Pi: invokes `child_process.spawn` with the provider's configured
      * `capabilities.spawn.spawnCommand`, appending the task prompt as a
-     * trailing positional argument. The returned handle lets the caller await
-     * completion or abort early.
+     * trailing positional argument. The returned handle lets the caller
+     * await completion ({@link SubagentHandle.exitPromise}), terminate the
+     * child via the SIGTERM-then-SIGKILL cleanup sequence
+     * ({@link SubagentHandle.terminate}), and inspect recent stderr for
+     * post-mortem diagnostics ({@link SubagentHandle.recentStderr}).
+     *
+     * Per ADR-035 §D6, this is the **only** canonical subagent spawn path
+     * in CLEO. New callers MUST go through the harness instead of calling
+     * `child_process.spawn` directly so session attribution, streaming,
+     * and cleanup remain uniform.
      *
      * Optional — harnesses that cannot spawn other agents should omit this
      * method. Callers MUST feature-check before invoking.
      *
      * @param task - Subagent task specification.
+     * @param opts - Per-call streaming and cleanup overrides.
      * @returns A live subagent handle.
      */
-    spawnSubagent?(task: SubagentTask): Promise<SubagentHandle>;
+    spawnSubagent?(task: SubagentTask, opts?: SubagentSpawnOptions): Promise<SubagentHandle>;
     /**
      * Configure which models are available in the harness's model picker.
      *
@@ -2031,7 +2426,636 @@ interface Harness {
      * @param scope - Settings scope.
      */
     writeSettings(patch: Record<string, unknown>, scope: HarnessScope): Promise<void>;
+    /**
+     * Install a Pi extension TypeScript file from a local source path into
+     * the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D1 and the spec hook for T263, install verbs:
+     * - Validate that the source is a `.ts` file with an `export default`.
+     * - Copy (not symlink) the file into the target tier's extensions dir.
+     * - Error by default when the target already exists; the caller may
+     *   pass `opts.force = true` to enable overwrite.
+     *
+     * Optional on the interface because only first-class harnesses with a
+     * native extension mechanism support this verb.
+     *
+     * @param sourcePath - Absolute path to the source `.ts` file on disk.
+     * @param name - Extension name (used as the target file basename).
+     * @param tier - Target tier (`project`/`user`/`global`).
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @param opts - Install options (see {@link HarnessInstallOptions}).
+     */
+    installExtension?(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /**
+     * Remove a Pi extension by name from the given tier.
+     *
+     * @remarks
+     * Missing files are tolerated silently so the verb is usable as an
+     * idempotent "ensure absent" operation.
+     *
+     * @param name - Extension name (basename without `.ts`).
+     * @param tier - Target tier to remove from.
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @returns `true` when a file was removed, `false` when none existed.
+     */
+    removeExtension?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * List Pi extensions across all tiers, precedence-ordered.
+     *
+     * @remarks
+     * Entries are returned in precedence order (project → user → global).
+     * Higher-precedence tiers shadow lower-precedence entries with the
+     * same name; the returned {@link ExtensionEntry.shadowed} flag
+     * indicates shadowed copies so the caller can surface cross-tier name
+     * collisions per ADR-035 §D1.
+     *
+     * @param projectDir - Project directory for the `project` tier. When
+     *   omitted the `project` tier is skipped rather than failing.
+     */
+    listExtensions?(projectDir?: string): Promise<ExtensionEntry[]>;
+    /**
+     * List Pi sessions from the user-tier sessions directory.
+     *
+     * @remarks
+     * Per ADR-035 §D2, MUST read only line 1 of each `*.jsonl` file. The
+     * result is sorted by `mtimeMs` descending so the most recent
+     * sessions appear first.
+     *
+     * @param opts - Options controlling which directories to scan.
+     */
+    listSessions?(opts?: {
+        includeSubagents?: boolean;
+    }): Promise<SessionSummary[]>;
+    /**
+     * Load a Pi session's full body by id.
+     *
+     * @remarks
+     * Reads the entire file as-is. The caller is responsible for
+     * formatting / filtering; the harness only guarantees that the
+     * returned `entries` are the raw JSONL lines in file order.
+     *
+     * @param id - Session id as recorded in the line-1 header.
+     */
+    showSession?(id: string): Promise<SessionDocument>;
+    /**
+     * List every model known to Pi — both custom (`models.json`) and
+     * enabled selections (`settings.json:enabledModels`).
+     *
+     * @remarks
+     * Per ADR-035 §D3, this is a read-only union with per-entry flags.
+     * Mutation verbs (`add`, `remove`, `enable`, `disable`, `default`)
+     * are separate methods to preserve the dual-file authority model.
+     *
+     * @param scope - Legacy two-tier scope (global/project) that
+     *   determines which `models.json` and `settings.json` files to read.
+     */
+    listModels?(scope: HarnessScope): Promise<ModelListEntry[]>;
+    /**
+     * Read `models.json` for the given scope.
+     *
+     * @remarks
+     * Missing files resolve to `{ providers: {} }`. Malformed JSON also
+     * resolves to the empty config rather than throwing, matching
+     * {@link Harness.readSettings}'s tolerant contract.
+     */
+    readModelsConfig?(scope: HarnessScope): Promise<PiModelsConfig>;
+    /**
+     * Write `models.json` for the given scope atomically.
+     *
+     * @remarks
+     * The full config is written, not merged. Callers should read, patch,
+     * then write. Uses an atomic tmp-then-rename sequence so a crash
+     * mid-write cannot corrupt the file.
+     */
+    writeModelsConfig?(config: PiModelsConfig, scope: HarnessScope): Promise<void>;
+    /**
+     * Install a Pi prompt from a source directory into the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D1 and the spec hook for T266, the source is a
+     * directory containing `prompt.md` plus optional metadata. The
+     * directory is copied recursively into the target tier. Conflict
+     * handling mirrors {@link installExtension}.
+     */
+    installPrompt?(sourceDir: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** List Pi prompts across all tiers. */
+    listPrompts?(projectDir?: string): Promise<PromptEntry[]>;
+    /** Remove a Pi prompt by name from the given tier. */
+    removePrompt?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * Install a Pi theme from a source file into the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D1 and the spec hook for T267. The source may be a
+     * `.ts` TypeScript theme module or a `.json` theme file; the file
+     * extension is preserved so Pi picks the right loader.
+     */
+    installTheme?(sourceFile: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** List Pi themes across all tiers. */
+    listThemes?(projectDir?: string): Promise<ThemeEntry[]>;
+    /** Remove a Pi theme by name from the given tier. */
+    removeTheme?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * Install a CANT profile (`.cant` file) into the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D5 (CANT single engine), CANT profiles are first-class
+     * Pi assets consumed by the canonical `cant-bridge.ts` extension via
+     * `/cant:load <file>` at runtime. This verb copies a source `.cant`
+     * file into the requested tier so the bridge can discover it.
+     *
+     * Implementations MUST validate the source via cant-core's 42-rule
+     * engine before copying — invalid `.cant` files are rejected. The
+     * conflict-on-write rule from §D1 cross-cutting concerns applies:
+     * existing targets cause an error unless `opts.force` is set.
+     *
+     * Optional on the interface because only first-class harnesses with a
+     * native CANT bridge support this verb.
+     *
+     * @param sourcePath - Absolute path to the source `.cant` file on disk.
+     * @param name - Profile name (used as the target file basename).
+     * @param tier - Target tier (`project`/`user`/`global`).
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @param opts - Install options (see {@link HarnessInstallOptions}).
+     */
+    installCantProfile?(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+        counts: CantProfileCounts;
+    }>;
+    /**
+     * Remove a CANT profile by name from the given tier.
+     *
+     * @remarks
+     * Missing files are tolerated silently so the verb is usable as an
+     * idempotent "ensure absent" operation.
+     *
+     * @param name - Profile name (basename without `.cant`).
+     * @param tier - Target tier to remove from.
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @returns `true` when a file was removed, `false` when none existed.
+     */
+    removeCantProfile?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * List CANT profiles across all tiers, precedence-ordered.
+     *
+     * @remarks
+     * Walks every tier in {@link HarnessTier} precedence order
+     * (project → user → global) and parses each `.cant` file to extract
+     * its section counts. Higher-precedence tiers shadow lower-precedence
+     * entries with the same name; the {@link CantProfileEntry.shadowedByHigherTier}
+     * flag indicates shadowed copies so callers can warn about
+     * cross-tier name collisions per ADR-035 §D1.
+     *
+     * @param projectDir - Project directory for the `project` tier. When
+     *   omitted the `project` tier is skipped rather than failing.
+     */
+    listCantProfiles?(projectDir?: string): Promise<CantProfileEntry[]>;
+    /**
+     * Validate a `.cant` file via cant-core's 42-rule engine without
+     * installing anything.
+     *
+     * @remarks
+     * Pure helper used by `caamp pi cant validate <path>`. Reads the file,
+     * parses it, runs the validator, and returns a structured
+     * {@link ValidateCantProfileResult}. Never mutates state on disk.
+     *
+     * @param sourcePath - Absolute path to the `.cant` file on disk.
+     */
+    validateCantProfile?(sourcePath: string): Promise<ValidateCantProfileResult>;
+}
+
+/**
+ * CAAMP-wide configuration accessors.
+ *
+ * @remarks
+ * This module is the single source of truth for CAAMP configuration values
+ * that affect runtime behaviour across the package. Today it carries one
+ * setting — {@link ExclusivityMode} — introduced by ADR-035 §D7 to control
+ * how `resolveDefaultTargetProviders()` selects target providers at runtime
+ * invocation time.
+ *
+ * The accessor pattern intentionally uses a layered resolution order so the
+ * setting can be overridden by tests, by environment variables in CI, and by
+ * future programmatic callers (e.g. a `caamp config set` subcommand) without
+ * any of those layers needing to know about the others:
+ *
+ * 1. Programmatic override via {@link setExclusivityMode} (highest priority).
+ * 2. Environment variable `CAAMP_EXCLUSIVITY_MODE`.
+ * 3. Default value `'auto'`.
+ *
+ * The programmatic override exists primarily for tests and for future
+ * `caamp config set` integration; production code should prefer the
+ * environment variable when wiring CI or shell sessions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Default exclusivity mode used when no override is configured.
+ *
+ * @remarks
+ * `auto` mirrors the v2026.4.5+ behaviour: Pi is preferred when installed,
+ * but explicit non-Pi targets remain functional. This is the value the
+ * accessor returns when neither {@link setExclusivityMode} nor the
+ * `CAAMP_EXCLUSIVITY_MODE` environment variable is set.
+ *
+ * @public
+ */
+declare const DEFAULT_EXCLUSIVITY_MODE: ExclusivityMode;
+/**
+ * Environment variable name read by {@link getExclusivityMode} when no
+ * programmatic override is active.
+ *
+ * @remarks
+ * Exported as a constant so tests and downstream tooling can refer to the
+ * canonical name without typo risk. The variable accepts the same three
+ * literal values as the {@link ExclusivityMode} type.
+ *
+ * @public
+ */
+declare const EXCLUSIVITY_MODE_ENV_VAR = "CAAMP_EXCLUSIVITY_MODE";
+/**
+ * Error raised when {@link getExclusivityMode} resolves to `'force-pi'` but
+ * Pi is not installed at the moment a runtime dispatch is requested.
+ *
+ * @remarks
+ * Carries an `E_NOT_FOUND_RESOURCE`-shaped `code` so command-layer error
+ * envelopes (LAFS) can map it to a stable category. Callers decide whether
+ * to surface this as a process exit (typically code 4) or as a structured
+ * envelope; the harness layer never calls `process.exit` itself.
+ *
+ * Lives next to the configuration accessor rather than in the harness
+ * dispatcher so consumers that import the mode also pick up the matching
+ * error type without a second module hop.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const targets = resolveDefaultTargetProviders();
+ * } catch (err) {
+ *   if (err instanceof PiRequiredError) {
+ *     process.exit(4);
+ *   }
+ *   throw err;
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class PiRequiredError extends Error {
+    /** LAFS-stable error code identifying this failure mode. */
+    readonly code: "E_NOT_FOUND_RESOURCE";
+    /**
+     * Construct a new {@link PiRequiredError}.
+     *
+     * @param message - Human-readable failure description; defaults to a
+     *   stable string suitable for direct CLI display.
+     */
+    constructor(message?: string);
 }
+/**
+ * Type guard that narrows an arbitrary string to {@link ExclusivityMode}.
+ *
+ * @remarks
+ * Used both internally and by callers that need to validate untrusted input
+ * (e.g. CLI flag parsers, env var readers) before passing it through to
+ * {@link setExclusivityMode}.
+ *
+ * @param value - Candidate value to validate.
+ * @returns `true` when `value` is one of `'auto'`, `'force-pi'`, `'legacy'`.
+ *
+ * @example
+ * ```typescript
+ * if (isExclusivityMode(userInput)) {
+ *   setExclusivityMode(userInput);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function isExclusivityMode(value: string): value is ExclusivityMode;
+/**
+ * Resolve the active CAAMP exclusivity mode using the layered precedence
+ * documented in {@link DEFAULT_EXCLUSIVITY_MODE}.
+ *
+ * @remarks
+ * Resolution order:
+ *
+ * 1. Programmatic override (set via {@link setExclusivityMode}).
+ * 2. Environment variable `CAAMP_EXCLUSIVITY_MODE`.
+ * 3. {@link DEFAULT_EXCLUSIVITY_MODE} (`'auto'`).
+ *
+ * Invalid environment variable values are silently ignored (resolution
+ * falls through to the default) so a typo in CI does not crash the CLI.
+ * The value is never cached — every call re-reads the environment so tests
+ * that mutate `process.env` see consistent results without needing to
+ * reset module state.
+ *
+ * @returns The currently effective exclusivity mode.
+ *
+ * @example
+ * ```typescript
+ * const mode = getExclusivityMode();
+ * if (mode === 'force-pi') {
+ *   // ...
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function getExclusivityMode(): ExclusivityMode;
+/**
+ * Install a programmatic override for the exclusivity mode.
+ *
+ * @remarks
+ * The override takes precedence over the environment variable for the
+ * remainder of the process or until {@link resetExclusivityModeOverride}
+ * is called. Intended for tests, for future `caamp config set` wiring, and
+ * for short-lived runtime adjustments (e.g. a one-shot CLI flag).
+ *
+ * @param mode - Mode to install.
+ *
+ * @example
+ * ```typescript
+ * setExclusivityMode('force-pi');
+ * try {
+ *   await runCommand();
+ * } finally {
+ *   resetExclusivityModeOverride();
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function setExclusivityMode(mode: ExclusivityMode): void;
+/**
+ * Clear any programmatic override installed by {@link setExclusivityMode}.
+ *
+ * @remarks
+ * After calling this, {@link getExclusivityMode} resumes reading from the
+ * environment variable (and falls back to the default when the env var is
+ * unset or invalid). Idempotent — safe to call when no override is active.
+ *
+ * @public
+ */
+declare function resetExclusivityModeOverride(): void;
+
+/**
+ * Format utility functions
+ */
+/**
+ * Deep merge two objects, with `source` values winning on conflict.
+ *
+ * Recursively merges nested plain objects. Arrays and non-object values from
+ * `source` overwrite `target` values.
+ *
+ * @param target - Base object to merge into
+ * @param source - Object with values that take precedence
+ * @returns A new merged object (does not mutate inputs)
+ *
+ * @remarks
+ * Only plain objects are recursively merged. Arrays and primitive values from
+ * `source` replace `target` values outright. Neither input is mutated.
+ *
+ * @example
+ * ```typescript
+ * const merged = deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
+ * // { a: 1, b: { c: 2, d: 3 } }
+ * ```
+ *
+ * @public
+ */
+declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Get a nested value from an object using a dot-notation key path.
+ *
+ * @param obj - Object to traverse
+ * @param keyPath - Dot-separated key path (e.g. `"mcpServers"` or `"a.b.c"`)
+ * @returns The value at the key path, or `undefined` if not found
+ *
+ * @remarks
+ * Splits the key path on `.` and walks the object tree. Returns `undefined`
+ * at the first missing or non-object segment.
+ *
+ * @example
+ * ```typescript
+ * getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
+ * getNestedValue({ a: 1 }, "a.b"); // undefined
+ * ```
+ *
+ * @public
+ */
+declare function getNestedValue(obj: Record<string, unknown>, keyPath: string): unknown;
+/**
+ * Ensure that the parent directories of a file path exist.
+ *
+ * Creates directories recursively if they do not exist.
+ *
+ * @param filePath - Absolute path to a file (parent directories will be created)
+ *
+ * @remarks
+ * Uses `mkdir` with `recursive: true` so existing directories are not an error.
+ *
+ * @example
+ * ```typescript
+ * await ensureDir("/path/to/new/dir/file.json");
+ * // /path/to/new/dir/ now exists
+ * ```
+ *
+ * @public
+ */
+declare function ensureDir(filePath: string): Promise<void>;
+
+/**
+ * Provides format-agnostic config read, write, and remove operations that
+ * dispatch to JSON/JSONC, YAML, or TOML handlers based on the specified
+ * format.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Read and parse a config file in the specified format.
+ *
+ * Dispatches to the appropriate format handler (JSON/JSONC, YAML, or TOML).
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @returns Parsed config object
+ * @throws If the file cannot be read or the format is unsupported
+ *
+ * @remarks
+ * Supported formats: `"json"`, `"jsonc"`, `"yaml"`, `"toml"`. Throws for
+ * any unrecognized format string.
+ *
+ * @example
+ * ```typescript
+ * const config = await readConfig("/path/to/config.json", "jsonc");
+ * ```
+ *
+ * @public
+ */
+declare function readConfig(filePath: string, format: ConfigFormat): Promise<Record<string, unknown>>;
+/**
+ * Write a server entry to a config file, preserving existing content.
+ *
+ * Dispatches to the appropriate format handler. For JSONC files, comments are
+ * preserved using `jsonc-parser`.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section (e.g. `"mcpServers"`)
+ * @param serverName - Name/key for the server entry
+ * @param serverConfig - Server configuration object to write
+ * @throws If the format is unsupported
+ *
+ * @remarks
+ * For JSONC files, comments and formatting are preserved using `jsonc-parser`.
+ * For YAML and TOML, the file is fully re-serialized after deep-merging.
+ *
+ * @example
+ * ```typescript
+ * await writeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server", config);
+ * ```
+ *
+ * @public
+ */
+declare function writeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string, serverConfig: unknown): Promise<void>;
+/**
+ * Remove a server entry from a config file in the specified format.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section
+ * @param serverName - Name/key of the server entry to remove
+ * @returns `true` if the entry was removed, `false` otherwise
+ * @throws If the format is unsupported
+ *
+ * @remarks
+ * Delegates to the format-specific removal function. Returns `false` when the
+ * file does not exist or the entry is not found.
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server");
+ * ```
+ *
+ * @public
+ */
+declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
+
+/**
+ * Skill installer - canonical + symlink model
+ *
+ * Skills are stored once in a canonical location (.agents/skills/<name>/)
+ * and symlinked to each target agent's skills directory.
+ */
+
+/**
+ * Result of installing a skill to the canonical location and linking to agents.
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill(sourcePath, "my-skill", providers, true);
+ * if (result.success) {
+ *   console.log(`Installed to ${result.canonicalPath}`);
+ *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+interface SkillInstallResult {
+    /** Skill name. */
+    name: string;
+    /** Absolute path to the canonical installation directory. */
+    canonicalPath: string;
+    /** Provider IDs that were successfully linked. */
+    linkedAgents: string[];
+    /** Error messages from failed link operations. */
+    errors: string[];
+    /** Whether at least one agent was successfully linked. */
+    success: boolean;
+}
+/**
+ * Install a skill from a local path to the canonical location and link to agents.
+ *
+ * @remarks
+ * Copies the skill directory to the canonical skills directory and creates symlinks
+ * (or copies on Windows) from each provider's skills directory to the canonical path.
+ *
+ * @param sourcePath - Local path to the skill directory to install
+ * @param skillName - Name for the installed skill
+ * @param providers - Target providers to link the skill to
+ * @param isGlobal - Whether to link to global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Install result with linked agents and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true, "/my/project");
+ * if (result.success) {
+ *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
+/**
+ * Remove a skill from the canonical location and all agent symlinks.
+ *
+ * @remarks
+ * Removes symlinks from each provider's skills directory and then removes the
+ * canonical copy from the centralized canonical skills directory.
+ *
+ * @param skillName - Name of the skill to remove
+ * @param providers - Providers to unlink the skill from
+ * @param isGlobal - Whether to target global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Object with arrays of successfully removed provider IDs and error messages
+ *
+ * @example
+ * ```typescript
+ * const { removed, errors } = await removeSkill("my-skill", providers, true, "/my/project");
+ * console.log(`Removed from: ${removed.join(", ")}`);
+ * ```
+ *
+ * @public
+ */
+declare function removeSkill(skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<{
+    removed: string[];
+    errors: string[];
+}>;
+/**
+ * List all skills installed in the canonical skills directory.
+ *
+ * @remarks
+ * Returns the directory names of all skills, which correspond to skill names.
+ * Includes both regular directories and symlinks in the canonical location.
+ *
+ * @returns Array of skill names
+ *
+ * @example
+ * ```typescript
+ * const skills = await listCanonicalSkills();
+ * // ["my-skill", "another-skill"]
+ * ```
+ *
+ * @public
+ */
+declare function listCanonicalSkills(): Promise<string[]>;
 
 /**
  * Pi coding agent harness.
@@ -2085,10 +3109,6 @@ declare class PiHarness implements Harness {
      * Resolve the skills directory for a given scope.
      */
     private skillsDir;
-    /**
-     * Resolve the extensions directory for a given scope.
-     */
-    private extensionsDir;
     /**
      * Resolve the settings.json path for a given scope.
      */
@@ -2113,38 +3133,219 @@ declare class PiHarness implements Harness {
     /** {@inheritDoc Harness.removeInstructions} */
     removeInstructions(scope: HarnessScope): Promise<void>;
     /**
-     * {@inheritDoc Harness.installMcpAsExtension}
+     * Spawn a subagent through Pi's configured `spawnCommand` and return a
+     * live handle bound to the canonical streaming, attribution, and
+     * cleanup contract.
+     *
+     * @remarks
+     * Per ADR-035 §D6 this is the **only** sanctioned subagent spawn path
+     * in CLEO. All historical direct `child_process.spawn` callers in
+     * subagent contexts (including the `cant-bridge.ts` Pi extension and
+     * the legacy CLEO orchestrator paths) MUST migrate to this method so
+     * the contract below holds uniformly. A custom biome rule banning
+     * raw `spawn()` from subagent code is planned for v3 cleanup but is
+     * intentionally NOT enforced in v2 to keep the migration incremental.
+     *
+     * **Streaming semantics** — Pi's `--mode json` produces line-delimited
+     * JSON on stdout. The harness:
+     *
+     * - Line-buffers stdout, parses each line as JSON, and forwards a
+     *   `{ kind: 'message', subagentId, lineNumber, payload }`
+     *   {@link SubagentStreamEvent} via {@link SubagentSpawnOptions.onStream}.
+     *   Non-parseable lines increment a warning counter (recorded in the
+     *   child session as `{ type: 'raw' }`) but never crash the loop.
+     * - Line-buffers stderr separately, forwards each line as
+     *   `{ kind: 'stderr', subagentId, payload: { line } }`, and stores
+     *   it in a 100-line ring buffer accessible via
+     *   {@link SubagentHandle.recentStderr}. Stderr is **never** injected
+     *   into the parent LLM context per ADR-035 §D6.
+     * - Emits a final `{ kind: 'exit', subagentId, payload: SubagentExitResult }`
+     *   when the child terminates.
+     *
+     * **Session attribution** — Every spawn produces a child session JSONL
+     * file at
+     * `~/.pi/agent/sessions/subagents/subagent-{parentSessionId}-{taskId}.jsonl`.
+     * The header line records the subagentId, taskId, and parent linkage.
+     * When {@link SubagentTask.parentSessionPath} is supplied, a
+     * {@link SubagentLinkEntry} is appended to the parent session file as
+     * a JSONL line so listing the parent surfaces its children.
+     *
+     * **Exit propagation** — {@link SubagentHandle.exitPromise} resolves
+     * with `{ code, signal, childSessionPath, durationMs }` exactly once
+     * when the child exits. The promise NEVER rejects: failure is
+     * encoded by a non-zero `code`, a non-null `signal`, or partial
+     * output preserved in the child session file.
+     *
+     * **Cleanup** — {@link SubagentHandle.terminate} sends SIGTERM, waits
+     * the configured grace window, then sends SIGKILL if the child is
+     * still alive. The grace window is sourced from
+     * {@link SubagentSpawnOptions.terminateGraceMs} when supplied,
+     * otherwise from `settings.json:pi.subagent.terminateGraceMs`,
+     * otherwise from {@link DEFAULT_TERMINATE_GRACE_MS}. A
+     * `subagent_exit` entry with reason `terminated` is appended to the
+     * child session file when cleanup runs.
+     *
+     * **Concurrency** — Use the static helpers
+     * {@link PiHarness.raceSubagents} and
+     * {@link PiHarness.settleAllSubagents} to compose `parallel: race`
+     * and `parallel: settle` constructs from CANT workflows over multiple
+     * handles.
+     *
+     * **Orphan handling** — On the first spawn the harness registers a
+     * process-wide `'exit'` handler that terminates every still-active
+     * subagent so a parent crash never strands children.
+     *
+     * Throws immediately when the provider entry is missing a
+     * `spawnCommand` so callers see configuration errors early rather
+     * than at child-exit time.
+     *
+     * @param task - Subagent task specification.
+     * @param opts - Per-call streaming and cleanup overrides.
+     * @returns A live subagent handle.
+     */
+    spawnSubagent(task: SubagentTask, opts?: SubagentSpawnOptions): Promise<SubagentHandle>;
+    /**
+     * Race a set of subagent handles, returning the first one that exits.
      *
      * @remarks
-     * Emits a SCAFFOLD Pi extension file under `extensions/mcp-<name>.ts`.
-     * The scaffold registers a Pi tool whose `execute` function currently
-     * returns an "isError" payload explaining that the MCP bridge runtime
-     * is not yet implemented. This preserves the public lifecycle surface
-     * (install/list/remove) so orchestration code can treat the bridge as
-     * a first-class asset while the concrete JSON-RPC runtime is built out
-     * in a later wave.
+     * Maps CANT's `parallel: race` construct (per ADR-035 §D6) onto the
+     * canonical {@link spawnSubagent} contract. The losing handles are
+     * gracefully terminated via {@link SubagentHandle.terminate} once the
+     * first settles so no straggler children outlive the race.
+     *
+     * @param handles - Subagent handles to race.
+     * @returns The {@link SubagentExitResult} of the first child to exit.
+     * @throws When `handles` is empty (caller bug — a race over zero
+     *   children has no winner).
      */
-    installMcpAsExtension(server: McpServerSpec, scope: HarnessScope): Promise<void>;
+    static raceSubagents(handles: SubagentHandle[]): Promise<SubagentExitResult>;
     /**
-     * {@inheritDoc Harness.spawnSubagent}
+     * Settle a set of subagent handles, returning a parallel array of
+     * results.
      *
      * @remarks
-     * Invokes Pi's configured `spawnCommand` (e.g.
-     * `["pi", "--mode", "json", "-p", "--no-session"]`) with the task prompt
-     * appended as the trailing positional argument. The {@link SubagentTask.targetProviderId}
-     * is a routing hint carried in the prompt stream; Pi's own extension
-     * layer dispatches to the correct inner agent.
+     * Maps CANT's `parallel: settle` construct (per ADR-035 §D6) onto the
+     * canonical {@link spawnSubagent} contract. Because
+     * {@link SubagentHandle.exitPromise} never rejects, every entry in
+     * the returned array is `{ status: 'fulfilled', value: ... }` under
+     * normal operation; the `PromiseSettledResult` shape is preserved
+     * for forward compatibility with future failure modes.
+     *
+     * @param handles - Subagent handles to settle.
+     * @returns Parallel array of settled exit results, one per input.
+     */
+    static settleAllSubagents(handles: SubagentHandle[]): Promise<PromiseSettledResult<SubagentExitResult>[]>;
+    /**
+     * Per-line stdout dispatcher used by the streaming buffer flusher.
      *
-     * Throws immediately when the provider entry is missing a `spawnCommand`
-     * so callers see configuration errors early rather than at child-exit time.
+     * @remarks
+     * Extracted as a private method so the line-handling logic stays
+     * close to {@link spawnSubagent} but does not bloat the parent
+     * function. Skips empty lines (a leading newline produces a zero-
+     * length entry that has no semantic meaning).
      */
-    spawnSubagent(task: SubagentTask): Promise<SubagentHandle>;
+    private handleStdoutLine;
     /** {@inheritDoc Harness.readSettings} */
     readSettings(scope: HarnessScope): Promise<unknown>;
     /** {@inheritDoc Harness.writeSettings} */
     writeSettings(patch: Record<string, unknown>, scope: HarnessScope): Promise<void>;
     /** {@inheritDoc Harness.configureModels} */
     configureModels(modelPatterns: string[], scope: HarnessScope): Promise<void>;
+    /**
+     * Resolve the `models.json` path for a given legacy two-tier scope.
+     *
+     * @remarks
+     * Lives next to `settings.json`. Global scope uses the Pi state root,
+     * project scope uses the project's `.pi/` directory, matching the
+     * dual-file authority model documented in ADR-035 §D3.
+     */
+    private modelsConfigPath;
+    /**
+     * Resolve the sessions directory — always user-tier because Pi owns
+     * session storage and the three-tier model folds session listings to
+     * the single authoritative location per ADR-035 §D2.
+     */
+    private sessionsDir;
+    /** {@inheritDoc Harness.installExtension} */
+    installExtension(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** {@inheritDoc Harness.removeExtension} */
+    removeExtension(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /** {@inheritDoc Harness.listExtensions} */
+    listExtensions(projectDir?: string): Promise<ExtensionEntry[]>;
+    /** {@inheritDoc Harness.listSessions} */
+    listSessions(opts?: {
+        includeSubagents?: boolean;
+    }): Promise<SessionSummary[]>;
+    /** {@inheritDoc Harness.showSession} */
+    showSession(id: string): Promise<SessionDocument>;
+    /** {@inheritDoc Harness.readModelsConfig} */
+    readModelsConfig(scope: HarnessScope): Promise<PiModelsConfig>;
+    /** {@inheritDoc Harness.writeModelsConfig} */
+    writeModelsConfig(config: PiModelsConfig, scope: HarnessScope): Promise<void>;
+    /** {@inheritDoc Harness.listModels} */
+    listModels(scope: HarnessScope): Promise<ModelListEntry[]>;
+    /** {@inheritDoc Harness.installPrompt} */
+    installPrompt(sourceDir: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** {@inheritDoc Harness.listPrompts} */
+    listPrompts(projectDir?: string): Promise<PromptEntry[]>;
+    /** {@inheritDoc Harness.removePrompt} */
+    removePrompt(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /** {@inheritDoc Harness.installTheme} */
+    installTheme(sourceFile: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** {@inheritDoc Harness.listThemes} */
+    listThemes(projectDir?: string): Promise<ThemeEntry[]>;
+    /** {@inheritDoc Harness.removeTheme} */
+    removeTheme(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * {@inheritDoc Harness.installCantProfile}
+     *
+     * @remarks
+     * Validates the source via {@link validateCantProfile} before copying so
+     * we never persist a `.cant` file the runtime bridge cannot load. The
+     * target layout is `<tier-root>/cant/<name>.cant`, resolved through
+     * {@link resolveTierDir} so the project/user/global hierarchy stays
+     * consistent with the other Wave-1 verbs.
+     */
+    installCantProfile(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+        counts: CantProfileCounts;
+    }>;
+    /** {@inheritDoc Harness.removeCantProfile} */
+    removeCantProfile(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * {@inheritDoc Harness.listCantProfiles}
+     *
+     * @remarks
+     * Walks every tier in {@link TIER_PRECEDENCE} order, parsing each
+     * discovered `.cant` file via cant-core to extract a
+     * {@link CantProfileCounts} bag. Higher-precedence tiers shadow
+     * lower-precedence entries with the same name; shadowed entries
+     * still appear in the result but carry the
+     * `shadowedByHigherTier` flag so callers can render the precedence
+     * story without losing visibility of the duplicate.
+     */
+    listCantProfiles(projectDir?: string): Promise<CantProfileEntry[]>;
+    /**
+     * {@inheritDoc Harness.validateCantProfile}
+     *
+     * @remarks
+     * Pure validator. Reads the file, runs `parseDocument` to derive
+     * counts (when parsing succeeds) and `validateDocument` to collect
+     * the 42-rule diagnostic feed. The two calls are kept independent so
+     * we can still report counts for files that pass parsing but fail a
+     * lint rule.
+     */
+    validateCantProfile(sourcePath: string): Promise<ValidateCantProfileResult>;
 }
 
 /**
@@ -2226,42 +3427,52 @@ declare function getPrimaryHarness(): Harness | null;
 declare function getAllHarnesses(): Harness[];
 /**
  * Resolve the default set of target providers when the user has not passed
- * `--agent`.
+ * `--agent`, honouring the active {@link ExclusivityMode}.
  *
  * @remarks
- * Resolution policy:
+ * Resolution policy is layered. The active {@link ExclusivityMode} (read
+ * via {@link getExclusivityMode}) selects which branch of the matrix runs:
+ *
+ * | Mode | Pi installed | Pi absent |
+ * |---|---|---|
+ * | `'auto'` (default) | Returns `[piProvider]`. Explicit non-Pi targets emit a one-time deprecation warning per process. | Falls back to installed primary/high-tier providers (legacy v2026.4.5 behaviour) and emits a one-time boot warning. |
+ * | `'force-pi'` | Returns `[piProvider]`. | Throws {@link PiRequiredError}. |
+ * | `'legacy'` | Returns the full installed provider list in priority order (matches pre-exclusivity behaviour). | Same. |
  *
- * 1. If the registry's primary harness (the provider with
- *    `priority === "primary"`) is installed on the current system,
- *    return `[primaryProvider]` so that commands dispatch to the
- *    primary harness by default.
- * 2. Otherwise, return the set of installed providers at priority
- *    `"primary"` or `"high"`. This restores the legacy "detected high-tier
- *    providers" fallback that CAAMP has always used when no primary
- *    harness is available.
- * 3. If the priority filter yields an empty list (e.g. in tests that stub
- *    providers without a `priority` field, or in fresh installs with only
- *    medium/low-tier providers detected), fall back to the full installed
- *    provider list so that commands retain a valid target.
+ * **Install paths are unaffected.** Per ADR-035 §D7, this helper governs
+ * RUNTIME INVOCATION dispatch only. Skill and instruction install
+ * dispatchers ({@link dispatchInstallSkillAcrossProviders},
+ * {@link dispatchRemoveSkillAcrossProviders}) intentionally do not call
+ * this function — they target every requested provider directly so that
+ * users in `force-pi` mode can still `caamp skills install foo --agent
+ * claude-code` while Pi is being installed.
  *
- * This helper is intentionally defensive: it swallows registry-related
- * exceptions (returning an empty-primary-harness result) so stubbed test
- * environments that do not wire the full provider registry still behave
- * sensibly.
+ * The helper is intentionally defensive: registry/detection exceptions
+ * are caught and treated as "Pi unknown" so stubbed test environments
+ * that do not wire the full registry still behave sensibly.
  *
+ * @param options - Optional explicit provider selection (e.g. from
+ *   `--agent`) used by `auto`-mode deprecation warning detection. Omit to
+ *   request the implicit default resolution.
  * @returns Ordered list of providers to target by default.
+ * @throws {@link PiRequiredError} when mode is `'force-pi'` and Pi is not
+ *   installed.
  *
  * @example
  * ```typescript
+ * // Implicit default — used by `caamp skills list` and friends.
  * const targets = resolveDefaultTargetProviders();
- * if (targets.length === 0) {
- *   console.error("No target providers found. Use --agent or --all.");
- * }
+ *
+ * // Explicit user selection — emits a deprecation warning in `auto` mode
+ * // when the selection excludes Pi and Pi is installed.
+ * const explicit = resolveDefaultTargetProviders({
+ *   explicit: [getProvider('claude-code')!],
+ * });
  * ```
  *
  * @public
  */
-declare function resolveDefaultTargetProviders(): Provider[];
+declare function resolveDefaultTargetProviders(options?: ResolveDefaultTargetProvidersOptions): Provider[];
 
 /**
  * All hook event categories (8 total).
@@ -3572,6 +4783,362 @@ declare class MarketplaceClient {
     getSkill(scopedName: string): Promise<MarketplaceResult | null>;
 }
 
+/**
+ * MCP server config reader.
+ *
+ * @remarks
+ * Reads MCP server entries from a provider's per-agent config file using
+ * the format-agnostic {@link readConfig} substrate from `core/formats`.
+ * The provider's `capabilities.mcp` block is the single source of truth
+ * for the file path, format, and dot-notation key — this module never
+ * hard-codes provider-specific layout.
+ *
+ * Three operations are exported:
+ *
+ * - {@link listMcpServers} — enumerate every server entry on a single
+ *   provider's config file at a given scope.
+ * - {@link listAllMcpServers} — fan out across every MCP-capable
+ *   provider in the registry, returning a map keyed by provider id.
+ * - {@link detectMcpInstallations} — lighter-weight scan that just
+ *   reports which providers currently have any MCP config files on
+ *   disk (used by `caamp mcp detect`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Scope identifier for MCP config file resolution.
+ *
+ * @remarks
+ * Mirrors the two-tier scope model the underlying provider config files
+ * already use: `project` reads `<projectDir>/<provider.configPathProject>`
+ * and `global` reads the absolute `provider.configPathGlobal` path. The
+ * three-tier {@link HarnessTier} model used by the Pi extensions
+ * verbs is intentionally not adopted here — MCP config files are owned
+ * by individual tools and live on those tools' two-tier hierarchy, not
+ * on a CleoOS-managed hub.
+ *
+ * @public
+ */
+type McpScope = 'project' | 'global';
+/**
+ * Result of a single provider's MCP installation probe.
+ *
+ * @remarks
+ * Returned by {@link detectMcpInstallations} for each provider that
+ * declares an MCP capability in the registry. The `configPath` field
+ * is the resolved file path the probe inspected; `exists` indicates
+ * whether the file is present on disk; `serverCount` is `null` when
+ * the file is missing or unparseable, otherwise the number of server
+ * entries found at the dot-notation key.
+ *
+ * @public
+ */
+interface McpDetectionEntry {
+    /** Provider id (e.g. `"claude-code"`). */
+    providerId: string;
+    /** Human-readable provider name. */
+    providerName: string;
+    /** Resolved scope of the probed config file. */
+    scope: McpScope;
+    /** Absolute path to the provider's MCP config file. */
+    configPath: string;
+    /** Whether the config file exists on disk. */
+    exists: boolean;
+    /** Number of server entries found, or `null` when the file is missing/unparseable. */
+    serverCount: number | null;
+    /** ISO 8601 timestamp of the file's last modification, or `null` when the file is missing. */
+    lastModified: string | null;
+}
+/**
+ * Resolve a provider's MCP config file path for the given scope, or
+ * `null` if the provider does not declare an MCP capability or the
+ * scope is unsupported.
+ *
+ * @remarks
+ * Thin wrapper over {@link resolveProviderConfigPath} that filters out
+ * providers without an MCP capability up front so callers can use a
+ * single null check rather than two.
+ *
+ * @param provider - Provider to resolve a config path for.
+ * @param scope - Scope to resolve.
+ * @param projectDir - Project directory used for the `project` scope.
+ * @returns The absolute config file path, or `null` when unavailable.
+ *
+ * @public
+ */
+declare function resolveMcpConfigPath(provider: Provider, scope: McpScope, projectDir?: string): string | null;
+/**
+ * List MCP server entries declared in a single provider's config file.
+ *
+ * @remarks
+ * Reads the provider's MCP config file using the format-agnostic
+ * {@link readConfig} substrate, walks the dot-notation
+ * `provider.capabilities.mcp.configKey` to find the servers section,
+ * and returns one {@link McpServerEntry} per child key.
+ *
+ * Returns an empty array (not an error) when:
+ *
+ * - the provider does not declare an MCP capability,
+ * - the resolved config path is unavailable for the requested scope,
+ * - the config file does not exist on disk,
+ * - the config file is empty or unparseable,
+ * - the config file exists but has no MCP servers section.
+ *
+ * "No file" is a normal state for an uninstalled tool, so callers
+ * should treat the empty array as success and only escalate to an
+ * error envelope when the user explicitly asked about a missing
+ * provider.
+ *
+ * @param provider - Provider whose config file to read.
+ * @param scope - Scope to resolve (project|global).
+ * @param projectDir - Project directory used for the `project` scope
+ *   (defaults to `process.cwd()`).
+ * @returns Array of MCP server entries, or `[]` when nothing was found.
+ *
+ * @public
+ */
+declare function listMcpServers(provider: Provider, scope: McpScope, projectDir?: string): Promise<McpServerEntry[]>;
+/**
+ * Map of provider id → MCP server entries for that provider.
+ *
+ * @remarks
+ * Return shape of {@link listAllMcpServers}. Providers without an MCP
+ * capability are intentionally absent from the map (rather than mapped
+ * to an empty array) so callers can iterate the result and immediately
+ * know which providers were probed.
+ *
+ * @public
+ */
+type McpServerEntriesByProvider = Map<string, McpServerEntry[]>;
+/**
+ * List MCP server entries for every MCP-capable provider in the
+ * registry at the given scope.
+ *
+ * @remarks
+ * Iterates {@link getAllProviders}, filters to those with a
+ * `capabilities.mcp` block, calls {@link listMcpServers} on each, and
+ * collects the results into a map keyed by provider id.
+ *
+ * Each provider is probed independently — a parse failure on one
+ * provider will not affect the others. The result map only contains
+ * entries for providers that were actually probed (i.e. had an MCP
+ * capability), so consumers can iterate `result.entries()` without
+ * skipping non-MCP providers.
+ *
+ * @param scope - Scope to resolve for every provider.
+ * @param projectDir - Project directory used for the `project` scope.
+ * @returns Map of provider id → server entries.
+ *
+ * @public
+ */
+declare function listAllMcpServers(scope: McpScope, projectDir?: string): Promise<McpServerEntriesByProvider>;
+/**
+ * Probe every MCP-capable provider in the registry to determine which
+ * ones have a config file on disk and how many servers are configured.
+ *
+ * @remarks
+ * Lightweight detection used by `caamp mcp detect`. Unlike
+ * {@link listAllMcpServers} this does not return individual server
+ * entries — it just reports a count plus the file mtime so callers can
+ * answer "which tools on my machine already have MCP configured?"
+ * without paying the cost of materialising every server entry.
+ *
+ * @param scope - Scope to probe.
+ * @param projectDir - Project directory used for the `project` scope.
+ * @returns Array of detection entries, one per MCP-capable provider.
+ *
+ * @public
+ */
+declare function detectMcpInstallations(scope: McpScope, projectDir?: string): Promise<McpDetectionEntry[]>;
+
+/**
+ * MCP server config installer.
+ *
+ * @remarks
+ * Writes a single MCP server entry into a provider's config file using
+ * the format-agnostic {@link writeConfig} substrate from `core/formats`.
+ * The provider's `capabilities.mcp` block is the single source of
+ * truth for the file path, format, and dot-notation key.
+ *
+ * Conflict-on-write semantics:
+ *
+ * - When the target server name does not yet exist in the file, the
+ *   write succeeds and {@link InstallMcpServerResult.conflicted} is
+ *   `false`.
+ * - When the target server name already exists in the file and `force`
+ *   is `false`, the installer DOES NOT write — it returns
+ *   `installed: false, conflicted: true` so the caller can emit a
+ *   typed conflict error envelope.
+ * - When `force` is `true`, an existing entry is overwritten and the
+ *   result reports `installed: true, conflicted: true` so the caller
+ *   can surface the overwrite in its envelope.
+ *
+ * Parent directories of the resolved config path are created lazily on
+ * write — see {@link writeConfig} for the per-format details.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options accepted by {@link installMcpServer}.
+ *
+ * @public
+ */
+interface InstallMcpServerOptions {
+    /** Scope to write to (project|global). */
+    scope: McpScope;
+    /** When `true`, overwrite an existing server entry instead of failing. */
+    force?: boolean;
+    /** Project directory used for the `project` scope. */
+    projectDir?: string;
+}
+/**
+ * Result of an {@link installMcpServer} call.
+ *
+ * @remarks
+ * `installed` is `true` only when the file was actually written.
+ * `conflicted` is `true` whenever the target server name was already
+ * present, regardless of whether the write went through (force was
+ * supplied) or was suppressed (force was withheld).
+ *
+ * @public
+ */
+interface InstallMcpServerResult {
+    /** Whether the entry was written to the config file. */
+    installed: boolean;
+    /** Whether the target server name already existed before the call. */
+    conflicted: boolean;
+    /** Absolute path to the config file that was (or would have been) written. */
+    sourcePath: string;
+    /** Provider id the entry was written for. */
+    providerId: string;
+    /** Server name that was written. */
+    serverName: string;
+}
+/**
+ * Install an MCP server entry into a single provider's config file.
+ *
+ * @remarks
+ * Resolves the provider's MCP config path for the requested scope,
+ * checks for an existing entry with the same server name, and either
+ * writes the new config (when no conflict, or when `force` is set) or
+ * returns a non-installed conflict result.
+ *
+ * Throws a plain `Error` (not a `LAFSCommandError`) when the provider
+ * has no MCP capability or no config path for the requested scope —
+ * those are caller-side validation failures and should be caught and
+ * re-thrown as typed `LAFSCommandError`s in the command layer.
+ *
+ * @param provider - Target provider.
+ * @param serverName - Name/key for the new server entry.
+ * @param config - Canonical {@link McpServerConfig} payload to write.
+ * @param opts - Install options (scope, force, projectDir).
+ * @returns Structured install result describing what happened.
+ * @throws `Error` when the provider has no MCP capability or no
+ *   project-scoped config path is available.
+ *
+ * @public
+ */
+declare function installMcpServer(provider: Provider, serverName: string, config: McpServerConfig, opts: InstallMcpServerOptions): Promise<InstallMcpServerResult>;
+
+/**
+ * MCP server config remover.
+ *
+ * @remarks
+ * Removes a single MCP server entry from a provider's config file
+ * using the format-agnostic {@link removeConfig} substrate from
+ * `core/formats`. The provider's `capabilities.mcp` block is the
+ * single source of truth for the file path, format, and dot-notation
+ * key.
+ *
+ * Both single-provider and all-providers variants are exported. Both
+ * are idempotent: removing a server that does not exist returns
+ * `removed: false` rather than throwing.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options accepted by {@link removeMcpServer} and
+ * {@link removeMcpServerFromAll}.
+ *
+ * @public
+ */
+interface RemoveMcpServerOptions {
+    /** Scope to target (project|global). */
+    scope: McpScope;
+    /** Project directory used for the `project` scope. */
+    projectDir?: string;
+}
+/**
+ * Result of a single-provider {@link removeMcpServer} call.
+ *
+ * @remarks
+ * `removed` is `true` only when an entry was actually deleted from
+ * the file. The `reason` field carries an optional discriminator when
+ * the call was a no-op so the command layer can surface a precise
+ * envelope (e.g. "no config file" vs "entry not present").
+ *
+ * @public
+ */
+interface RemoveMcpServerResult {
+    /** Provider id the call targeted. */
+    providerId: string;
+    /** Server name the call targeted. */
+    serverName: string;
+    /** Resolved config file path, or `null` when the provider had no MCP capability. */
+    sourcePath: string | null;
+    /** Whether an entry was actually deleted. */
+    removed: boolean;
+    /**
+     * Diagnostic discriminator when `removed` is `false`.
+     *
+     * - `"no-mcp-capability"` — provider does not consume MCP servers
+     * - `"no-config-path"` — provider has no config path for the scope
+     * - `"file-missing"` — config file does not exist on disk
+     * - `"entry-missing"` — config file exists but had no matching entry
+     *
+     * Set to `null` when `removed` is `true`.
+     */
+    reason: 'no-mcp-capability' | 'no-config-path' | 'file-missing' | 'entry-missing' | null;
+}
+/**
+ * Remove an MCP server entry from a single provider's config file.
+ *
+ * @remarks
+ * Idempotent: when the entry is not present (or the file is missing
+ * entirely) the call returns `removed: false` with a structured
+ * `reason` rather than throwing.
+ *
+ * @param provider - Provider whose config file to modify.
+ * @param serverName - Server name/key to remove.
+ * @param opts - Removal options.
+ * @returns Structured result describing whether the entry was removed.
+ *
+ * @public
+ */
+declare function removeMcpServer(provider: Provider, serverName: string, opts: RemoveMcpServerOptions): Promise<RemoveMcpServerResult>;
+/**
+ * Remove an MCP server entry from every MCP-capable provider in the
+ * registry that currently has it configured.
+ *
+ * @remarks
+ * Iterates {@link getAllProviders}, calls {@link removeMcpServer} on
+ * each MCP-capable provider, and collects the per-provider results.
+ * Each provider is processed independently — a failure on one does
+ * not abort the others. The result array contains one entry per
+ * MCP-capable provider, even when the entry was not present (so
+ * callers can render a complete report).
+ *
+ * @param serverName - Server name/key to remove from every provider.
+ * @param opts - Removal options applied uniformly to every provider.
+ * @returns Array of per-provider removal results.
+ *
+ * @public
+ */
+declare function removeMcpServerFromAll(serverName: string, opts: RemoveMcpServerOptions): Promise<RemoveMcpServerResult[]>;
+
 /**
  * Scope for path resolution, either global (user home) or project-local.
  *
@@ -6345,4 +7912,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, CANONICAL_HOOK_EVENTS, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, 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 InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpServerConfig, type McpServerEntry, type McpServerSpec, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, type PlatformPaths, 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 RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, 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 SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, deepMerge, detectAllProviders, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installSkill, isCaampOwnedSkill, isMarketplaceScoped, isQuiet, isVerbose, listCanonicalSkills, loadLibraryFromModule, normalizeRecommendationCriteria, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveDefaultTargetProviders, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, 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 DetectionCacheOptions, type DetectionResult, EXCLUSIVITY_MODE_ENV_VAR, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type ExclusivityMode, 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 InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, PiRequiredError, type PlatformPaths, 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 RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, 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 SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SystemInfo, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, 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, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, isCaampOwnedSkill, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeRecommendationCriteria, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, resetDetectionCache, resetExclusivityModeOverride, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };