@sayknow-cli/coding-agent 0.4.1 → 0.4.3

package/dist/types/extensibility/shared-events.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Event payload and result shapes shared between the extensions and hooks
+ * subsystems.
+ *
+ * Both subsystems observe the same agent/session lifecycle, so the *event*
+ * payloads (what happened) and the simpler *result* shapes (handler return
+ * values that don't depend on subsystem-specific identifiers like
+ * `AgentMessage` vs `Message`) are intentionally identical.
+ *
+ * Anything that diverges between the two subsystems — UI context, runtime
+ * context, command context, tool-call discrimination, or return shapes that
+ * carry subsystem-specific message types — lives in the per-subsystem
+ * `types.ts` files and is documented there.
+ */
+import type { AgentMessage } from "@sayknow-cli/agent-core";
+import type { CompactionPreparation, CompactionResult } from "@sayknow-cli/agent-core/compaction";
+import type { ImageContent, TextContent, ToolResultMessage } from "@sayknow-cli/ai";
+import type { Rule } from "../capability/rule";
+import type { Goal, GoalModeState } from "../goals/state";
+import type { BranchSummaryEntry, CompactionEntry, SessionEntry } from "../session/session-manager";
+import type { TodoItem } from "../tools/todo-write";
+/** Fired on initial session load */
+export interface SessionStartEvent {
+    type: "session_start";
+}
+/** Fired before switching to another session (can be cancelled) */
+export interface SessionBeforeSwitchEvent {
+    type: "session_before_switch";
+    /** Reason for the switch */
+    reason: "new" | "resume" | "fork";
+    /** Session file we're switching to (only for "resume") */
+    targetSessionFile?: string;
+}
+/** Fired after switching to another session */
+export interface SessionSwitchEvent {
+    type: "session_switch";
+    /** Reason for the switch */
+    reason: "new" | "resume" | "fork";
+    /** Session file we came from */
+    previousSessionFile: string | undefined;
+}
+/** Fired before branching a session (can be cancelled) */
+export interface SessionBeforeBranchEvent {
+    type: "session_before_branch";
+    /** ID of the entry to branch from */
+    entryId: string;
+}
+/** Fired after branching a session */
+export interface SessionBranchEvent {
+    type: "session_branch";
+    previousSessionFile: string | undefined;
+}
+/** Fired before context compaction (can be cancelled or customized) */
+export interface SessionBeforeCompactEvent {
+    type: "session_before_compact";
+    /** Compaction preparation with messages to summarize, file ops, previous summary, etc. */
+    preparation: CompactionPreparation;
+    /** Branch entries (root to current leaf). Use to inspect custom state or previous compactions. */
+    branchEntries: SessionEntry[];
+    /** Optional user-provided instructions for the summary */
+    customInstructions?: string;
+    /** Abort signal - handlers should pass this to LLM calls and check it periodically */
+    signal: AbortSignal;
+}
+/** Fired before compaction summarization to customize prompts/context */
+export interface SessionCompactingEvent {
+    type: "session.compacting";
+    sessionId: string;
+    messages: AgentMessage[];
+}
+/** Fired after context compaction */
+export interface SessionCompactEvent {
+    type: "session_compact";
+    compactionEntry: CompactionEntry;
+    /** Whether the compaction entry was provided by an extension/hook */
+    fromExtension: boolean;
+}
+/** Fired on process exit (SIGINT/SIGTERM) */
+export interface SessionShutdownEvent {
+    type: "session_shutdown";
+}
+/** Preparation data for tree navigation (used by session_before_tree event) */
+export interface TreePreparation {
+    /** Node being switched to */
+    targetId: string;
+    /** Current active leaf (being abandoned), null if no current position */
+    oldLeafId: string | null;
+    /** Common ancestor of target and old leaf, null if no common ancestor */
+    commonAncestorId: string | null;
+    /** Entries to summarize (old leaf back to common ancestor or compaction) */
+    entriesToSummarize: SessionEntry[];
+    /** Whether user chose to summarize */
+    userWantsSummary: boolean;
+}
+/** Fired before navigating to a different node in the session tree (can be cancelled) */
+export interface SessionBeforeTreeEvent {
+    type: "session_before_tree";
+    /** Preparation data for the navigation */
+    preparation: TreePreparation;
+    /** Abort signal - honors Escape during summarization (model available via ctx.model) */
+    signal: AbortSignal;
+}
+/** Fired after navigating to a different node in the session tree */
+export interface SessionTreeEvent {
+    type: "session_tree";
+    /** The new active leaf, null if navigated to before first entry */
+    newLeafId: string | null;
+    /** Previous active leaf, null if there was no position */
+    oldLeafId: string | null;
+    /** Branch summary entry if one was created */
+    summaryEntry?: BranchSummaryEntry;
+    /** Whether summary came from extension/hook */
+    fromExtension?: boolean;
+}
+/** Union of all session event types */
+export interface GoalUpdatedEvent {
+    type: "goal_updated";
+    goal: Goal | null;
+    state?: GoalModeState;
+}
+export type SessionEvent = SessionStartEvent | SessionBeforeSwitchEvent | SessionSwitchEvent | SessionBeforeBranchEvent | SessionBranchEvent | SessionBeforeCompactEvent | SessionCompactingEvent | SessionCompactEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent | GoalUpdatedEvent;
+/**
+ * Fired before each LLM call.
+ *
+ * Original session messages are NOT modified - only the messages sent to the
+ * LLM are affected when a handler returns a replacement (the return shape
+ * differs between extensions and hooks; see each subsystem's
+ * `ContextEventResult`).
+ */
+export interface ContextEvent {
+    type: "context";
+    /** Messages about to be sent to the LLM (deep copy, safe to modify) */
+    messages: AgentMessage[];
+}
+/**
+ * Fired when an agent loop starts (once per user prompt).
+ */
+export interface AgentStartEvent {
+    type: "agent_start";
+}
+/** Fired when an agent loop ends */
+export interface AgentEndEvent {
+    type: "agent_end";
+    messages: AgentMessage[];
+    /** Indicates whether the loop ended normally, suspended, cancelled, or entered maintenance. */
+    stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
+}
+/** Fired at the start of each turn */
+export interface TurnStartEvent {
+    type: "turn_start";
+    turnIndex: number;
+    timestamp: number;
+}
+/** Fired at the end of each turn */
+export interface TurnEndEvent {
+    type: "turn_end";
+    turnIndex: number;
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+}
+/** Fired when auto-compaction starts */
+export interface AutoCompactionStartEvent {
+    type: "auto_compaction_start";
+    reason: "threshold" | "overflow" | "idle";
+    action: "context-full" | "handoff";
+}
+/** Fired when auto-compaction ends */
+export interface AutoCompactionEndEvent {
+    type: "auto_compaction_end";
+    action: "context-full" | "handoff";
+    result: CompactionResult | undefined;
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+    /** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
+    skipped?: boolean;
+    continuationSkipReason?: "auto_continue_disabled_non_resumable_tail";
+}
+/** Fired when auto-retry starts */
+export interface AutoRetryStartEvent {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+    unbounded?: boolean;
+}
+/** Fired when auto-retry ends */
+export interface AutoRetryEndEvent {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+}
+/** Fired when TTSR rule matching interrupts generation */
+export interface TtsrTriggeredEvent {
+    type: "ttsr_triggered";
+    rules: Rule[];
+}
+/** Fired when todo reminder logic detects unfinished todos */
+export interface TodoReminderEvent {
+    type: "todo_reminder";
+    todos: TodoItem[];
+    attempt: number;
+    maxAttempts: number;
+}
+/**
+ * Return type for `tool_call` handlers.
+ * Allows handlers to block tool execution.
+ */
+export interface ToolCallEventResult {
+    /** If true, block the tool from executing */
+    block?: boolean;
+    /** Reason for blocking (returned to LLM as error) */
+    reason?: string;
+}
+/**
+ * Return type for `tool_result` handlers.
+ * Allows handlers to modify tool results.
+ */
+export interface ToolResultEventResult {
+    /** Replacement content array (text and images) */
+    content?: (TextContent | ImageContent)[];
+    /** Replacement details */
+    details?: unknown;
+    /** Override isError flag */
+    isError?: boolean;
+}
+/** Return type for `session_before_switch` handlers */
+export interface SessionBeforeSwitchResult {
+    /** If true, cancel the switch */
+    cancel?: boolean;
+}
+/** Return type for `session_before_branch` handlers */
+export interface SessionBeforeBranchResult {
+    /**
+     * If true, abort the branch entirely. No new session file is created,
+     * conversation stays unchanged.
+     */
+    cancel?: boolean;
+    /**
+     * If true, the branch proceeds (new session file created, session state updated)
+     * but the in-memory conversation is NOT rewound to the branch point.
+     *
+     * Use case: git-checkpoint handler that restores code state separately.
+     * The handler handles state restoration itself, so it doesn't want the
+     * agent's conversation to be rewound (which would lose recent context).
+     *
+     * - `cancel: true` → nothing happens, user stays in current session
+     * - `skipConversationRestore: true` → branch happens, but messages stay as-is
+     * - neither → branch happens AND messages rewind to branch point (default)
+     */
+    skipConversationRestore?: boolean;
+}
+/** Return type for `session_before_compact` handlers */
+export interface SessionBeforeCompactResult {
+    /** If true, cancel the compaction */
+    cancel?: boolean;
+    /** Custom compaction result - SessionManager adds id/parentId */
+    compaction?: CompactionResult;
+}
+/** Return type for `session.compacting` handlers */
+export interface SessionCompactingResult {
+    /** Additional context lines to include in summary */
+    context?: string[];
+    /** Override the default compaction prompt */
+    prompt?: string;
+    /** Custom data to store in compaction entry */
+    preserveData?: Record<string, unknown>;
+}
+/** Return type for `session_before_tree` handlers */
+export interface SessionBeforeTreeResult {
+    /** If true, cancel the navigation entirely */
+    cancel?: boolean;
+    /**
+     * Custom summary (skips default summarizer).
+     * Only used if preparation.userWantsSummary is true.
+     */
+    summary?: {
+        summary: string;
+        details?: unknown;
+    };
+}

package/dist/types/extensibility/skc-plugins/activation.d.ts

@@ -0,0 +1,14 @@
+import { type LoadedSubskillActivation } from "./types";
+export interface SubskillActivationResult {
+    cleanedArgs: string;
+    activation?: LoadedSubskillActivation;
+    activeSubskillsToPersist: LoadedSubskillActivation[];
+}
+export declare function resolveSubskillActivationForSkillInvocation(input: {
+    cwd: string;
+    sessionId?: string;
+    threadId?: string;
+    turnId?: string;
+    skillName: string;
+    args: string;
+}): Promise<SubskillActivationResult>;

package/dist/types/extensibility/skc-plugins/compiler.d.ts

@@ -0,0 +1,19 @@
+import { type NormalizedSkcPluginBundle } from "./types";
+/**
+ * Stable surface extension-id builders. Kept here so install, runtime, and
+ * observability all derive identical ids.
+ */
+export declare const surfaceIds: {
+    readonly tool: (name: string) => string;
+    readonly hook: (event: string, phase: string | undefined, target: string | undefined, name: string) => string;
+    readonly mcp: (name: string) => string;
+    readonly systemAppendix: (plugin: string, name: string) => string;
+    readonly agentAppendix: (agent: string, plugin: string, name: string) => string;
+    readonly subskill: (parent: string, phase: string, activationArg: string) => string;
+};
+/**
+ * Pure compile step: reads only the manifest, subskill frontmatter, and
+ * declared files (as bytes for hashing/existence). It NEVER imports or executes
+ * plugin tool/hook code.
+ */
+export declare function compileSkcPluginBundle(root: string): Promise<NormalizedSkcPluginBundle>;

package/dist/types/extensibility/skc-plugins/constrained-hooks.d.ts

@@ -0,0 +1,29 @@
+import { type SessionQuarantine } from "./session-validation";
+/**
+ * Constrained plugin-hook loader.
+ *
+ * Third-party plugin hooks are NOT given the broad first-party HookAPI. They
+ * receive a restricted API that can only register a handler for their declared
+ * event; every session-mutation / command / shell capability throws
+ * security_policy. After the factory runs we verify it registered exactly the
+ * declared event (and nothing else), or the hook is quarantined.
+ */
+export interface ConstrainedPluginHook {
+    plugin: string;
+    event: string;
+    target?: string;
+    phase?: "before" | "after";
+    handler: (...args: any[]) => unknown;
+}
+export interface ConstrainedHookLoadResult {
+    hooks: ConstrainedPluginHook[];
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Load all always-on constrained plugin hooks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns empty when
+ * no plugins are installed.
+ */
+export declare function loadConstrainedPluginHooks(input: {
+    cwd: string;
+}): Promise<ConstrainedHookLoadResult>;

package/dist/types/extensibility/skc-plugins/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./activation";
+export * from "./compiler";
+export * from "./constrained-hooks";
+export * from "./injection";
+export * from "./installer";
+export * from "./loader";
+export * from "./mcp-policy";
+export * from "./observability";
+export * from "./paths";
+export * from "./prompt-appendix";
+export * from "./registry";
+export * from "./runtime-adapters";
+export * from "./schema";
+export * from "./session-validation";
+export * from "./state";
+export * from "./tools";
+export * from "./types";
+export * from "./validation";

package/dist/types/extensibility/skc-plugins/injection.d.ts

@@ -0,0 +1,40 @@
+import { type LoadedSubskillActivation } from "./types";
+export declare function readSubskillBody(filePath: string): Promise<string>;
+export declare function wrapSubskillBlock(activation: {
+    plugin: string;
+    subskillName: string;
+    parent: string;
+    phase: string;
+    activationArg: string;
+    filePath: string;
+}, body: string): string;
+export declare function resolveCurrentPhaseForParent(input: {
+    cwd: string;
+    sessionId?: string;
+    parent: string;
+    explicitPhase?: string;
+}): Promise<string>;
+export declare function buildSubskillInjection(input: {
+    cwd: string;
+    sessionId?: string;
+    skillName: string;
+    activation?: LoadedSubskillActivation;
+    currentPhase?: string;
+}): Promise<{
+    block: string;
+    details?: LoadedSubskillActivation;
+} | null>;
+export declare function buildAgentSubskillInjection(input: {
+    cwd: string;
+    sessionId?: string;
+    agentName: string;
+}): Promise<string>;
+import type { SkcPluginRegistryEntry } from "./types";
+/**
+ * Tier-1 advertisement for a workflow parent skill: bounded, metadata-only list
+ * of installed sub-skills bound to `parent`, rendered ONLY in that parent's
+ * prompt (never the global public-workflow-surface). No body content.
+ */
+export declare function buildSubskillAdvertisement(entries: readonly SkcPluginRegistryEntry[], parent: string, phase?: string): string;
+/** Tier-1 advertisement for a role-agent parent. */
+export declare function buildAgentSubskillAdvertisement(entries: readonly SkcPluginRegistryEntry[], agentName: string): string;

package/dist/types/extensibility/skc-plugins/installer.d.ts

@@ -0,0 +1,13 @@
+import { type SkcPluginRegistryEntry, type SkcPluginScope } from "./types";
+export interface InstallSkcPluginOptions {
+    scope: SkcPluginScope;
+    cwd: string;
+    force?: boolean;
+}
+export interface InstallSkcPluginResult {
+    status: "installed" | "updated" | "unchanged";
+    entry: SkcPluginRegistryEntry;
+}
+export declare function installSkcPluginBundle(source: string, options: InstallSkcPluginOptions): Promise<InstallSkcPluginResult>;
+/** True only when the source actually resolves to a SKC plugin bundle (root sayknow-plugin.json). */
+export declare function isSkcPluginBundleSource(source: string): Promise<boolean>;

package/dist/types/extensibility/skc-plugins/loader.d.ts

@@ -0,0 +1,3 @@
+import { type LoadedSkcPlugin } from "./types";
+export declare function loadSkcPlugin(root: string): Promise<LoadedSkcPlugin>;
+export declare function loadSkcPlugins(roots: readonly string[]): Promise<LoadedSkcPlugin[]>;

package/dist/types/extensibility/skc-plugins/mcp-policy.d.ts

@@ -0,0 +1,26 @@
+import { type SkcPluginMcpManifestEntry } from "./types";
+export declare function isDeniedIpv4(host: string): boolean;
+export declare function isDeniedIpv6(host: string): boolean;
+/**
+ * Synchronous URL policy (scheme, credentials, host literal ranges). Used for
+ * the primary endpoint and any redirect/token/discovery URL.
+ */
+export declare function assertUrlAllowed(rawUrl: string, label?: string): URL;
+/** Reject headers with control characters / CRLF injection. */
+export declare function assertHeadersAllowed(headers: Record<string, string> | undefined): void;
+/**
+ * Runtime DNS check: resolve the host and ensure no resolved address falls in a
+ * denied range (covers DNS rebinding when re-run before each connect).
+ */
+export declare function assertDnsResolvesPublic(hostname: string, label?: string): Promise<void>;
+export interface StdioPolicyContext {
+    pluginRoot: string;
+}
+/** stdio launcher/path confinement policy. */
+export declare function assertStdioAllowed(entry: SkcPluginMcpManifestEntry, ctx: StdioPolicyContext): void;
+/**
+ * Install-time MCP policy (no network required). Validates scheme/host literals
+ * and stdio confinement. Runtime connect additionally calls
+ * assertDnsResolvesPublic and re-validates redirect/token URLs.
+ */
+export declare function assertMcpInstallPolicy(entry: SkcPluginMcpManifestEntry, ctx: StdioPolicyContext): void;

package/dist/types/extensibility/skc-plugins/observability.d.ts

@@ -0,0 +1,27 @@
+import type { SkcPluginRegistryEntry, SkcPluginScope } from "./types";
+/**
+ * Observability for SKC plugin bundle surfaces, consumable by the extension
+ * dashboard / state manager. Each surface row carries its stable extension id,
+ * owning plugin, scope, source kind, enabled/disabled/quarantined status, and a
+ * content hash. MCP auth/header values are NEVER included.
+ */
+export type PluginSurfaceStatus = "enabled" | "disabled" | "quarantined";
+export interface PluginSurfaceRow {
+    extensionId: string;
+    kind: "tool" | "hook" | "mcp" | "system-appendix" | "agent-appendix" | "subskill";
+    plugin: string;
+    scope: SkcPluginScope;
+    sourceKind: SkcPluginRegistryEntry["source"]["kind"];
+    status: PluginSurfaceStatus;
+    hash: string;
+    quarantineCode?: string;
+}
+export interface PluginObservabilitySummary {
+    plugins: number;
+    surfaces: PluginSurfaceRow[];
+}
+/**
+ * Build the observability summary for the effective registry at `cwd`, including
+ * hash-drift and session-collision quarantine status.
+ */
+export declare function summarizeSkcPluginObservability(cwd: string): Promise<PluginObservabilitySummary>;

package/dist/types/extensibility/skc-plugins/paths.d.ts

@@ -0,0 +1,8 @@
+export declare function skcPluginUserRoot(): string;
+export declare function skcPluginProjectRoot(cwd: string): string;
+export declare function rootContainsSkcManifest(dir: string): Promise<boolean>;
+export declare function discoverSkcPluginRoots({ cwd }: {
+    cwd: string;
+    home?: string;
+}): Promise<string[]>;
+export declare function resolveWithinRoot(root: string, rel: string): string;

package/dist/types/extensibility/skc-plugins/prompt-appendix.d.ts

@@ -0,0 +1,16 @@
+import type { SkcPluginRegistryEntry, SkcSubskillParentAgent } from "./types";
+export interface RenderedPluginAppendices {
+    /** Combined system-appendix block text (empty if none). */
+    system: string;
+    /** Per-agent appendix block text. */
+    byAgent: Map<SkcSubskillParentAgent, string>;
+    /** Stable digest of all rendered appendix content + identities (for cache/refresh). */
+    digest: string;
+}
+/**
+ * Build appendix blocks from the active, enabled registry entries in their
+ * deterministic order. Per-appendix and total size caps are enforced
+ * fail-closed (oversize content is dropped with a marker, never silently
+ * truncated into the prompt as authoritative text).
+ */
+export declare function renderPluginAppendices(entries: readonly SkcPluginRegistryEntry[]): Promise<RenderedPluginAppendices>;

package/dist/types/extensibility/skc-plugins/registry.d.ts

@@ -0,0 +1,32 @@
+import { type SkcPluginRegistry, type SkcPluginRegistryEntry, type SkcPluginScope } from "./types";
+export declare function registryRootForScope(scope: SkcPluginScope, cwd: string): string;
+export declare function registryPathForScope(scope: SkcPluginScope, cwd: string): string;
+/**
+ * Deterministic ordering: scope (user before project) -> normalized name ->
+ * resolved plugin root. Collisions are errors elsewhere; order only controls
+ * stable hook/appendix sequencing.
+ */
+export declare function sortRegistryEntries(entries: SkcPluginRegistryEntry[]): SkcPluginRegistryEntry[];
+export declare function readRegistry(scope: SkcPluginScope, cwd: string): Promise<SkcPluginRegistry>;
+export declare function withRegistryLock<T>(scope: SkcPluginScope, cwd: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Lock-free atomic write (temp+fsync+rename). Only call while already holding
+ * the per-scope registry lock via withRegistryLock.
+ */
+export declare function writeRegistryUnlocked(registry: SkcPluginRegistry, cwd: string): Promise<void>;
+/**
+ * Atomic registry write: write to a temp sibling, fsync, then rename. Guarded
+ * by an interprocess lockfile so concurrent installs cannot clobber each other.
+ */
+export declare function writeRegistry(registry: SkcPluginRegistry, cwd: string): Promise<void>;
+/**
+ * Mutate a scope's registry as a single locked read-modify-write transaction so
+ * concurrent installs cannot lose each other's updates. The mutator receives a
+ * sorted copy and returns the next entry list.
+ */
+export declare function updateRegistry(scope: SkcPluginScope, cwd: string, mutator: (entries: SkcPluginRegistryEntry[]) => SkcPluginRegistryEntry[]): Promise<SkcPluginRegistry>;
+/**
+ * Effective registry for a cwd: user + project entries in deterministic order.
+ */
+export declare function loadEffectiveSkcPluginRegistry(cwd: string): Promise<SkcPluginRegistryEntry[]>;
+export declare function registryEntryFingerprint(entry: SkcPluginRegistryEntry): string;

package/dist/types/extensibility/skc-plugins/runtime-adapters.d.ts

@@ -0,0 +1,64 @@
+import type { CustomTool } from "../custom-tools/types";
+import { type SessionQuarantine } from "./session-validation";
+export interface AlwaysOnPluginTools {
+    tools: CustomTool[];
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Load the always-on plugin tool surfaces for the effective registry at `cwd`.
+ *
+ * Safety properties:
+ * - Hash drift quarantines the plugin (runtime_mismatch) before any import.
+ * - Session-start collisions vs reserved/built-in names quarantine fail-closed.
+ * - Manifest-declared tool names are authoritative: a factory that returns a
+ *   different/extra/missing name is rejected with runtime_mismatch and skipped.
+ * - Reserved tool names are never overwritten.
+ *
+ * Returns an empty result when no plugins are installed, so callers that always
+ * call this in `createAgentSession` incur no behavior change without plugins.
+ */
+export declare function loadAlwaysOnPluginTools(input: {
+    cwd: string;
+    reservedToolNames: string[];
+}): Promise<AlwaysOnPluginTools>;
+/**
+ * Render the always-on system-appendix blocks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns "" when no
+ * plugins are installed/enabled. Safe to call unconditionally at session start.
+ */
+export declare function renderAlwaysOnSystemAppendices(input: {
+    cwd: string;
+}): Promise<string>;
+/**
+ * Render the agent-appendix block and Tier-1 sub-skill advertisement for a role
+ * agent at session/spawn time. Hash-drift + collision quarantine applied first.
+ * Returns empty strings when nothing applies.
+ */
+export declare function renderAgentPromptAdditions(input: {
+    cwd: string;
+    agentName: string;
+}): Promise<{
+    appendix: string;
+    advertisement: string;
+}>;
+/**
+ * Render the Tier-1 sub-skill advertisement for a workflow parent skill.
+ * Returns "" when nothing applies. Quarantine applied first.
+ */
+export declare function renderSkillAdvertisement(input: {
+    cwd: string;
+    skillName: string;
+    phase?: string;
+}): Promise<string>;
+/**
+ * Convert active plugin-bundle MCP surfaces into runtime MCPServerConfig entries,
+ * applying install + runtime MCP policy (URL scheme/private-range deny, DNS
+ * re-resolution for http/sse, stdio root-confinement) before connection. Servers
+ * failing policy are quarantined and excluded. Returns {} when none.
+ */
+export declare function buildPluginMcpConfigs(input: {
+    cwd: string;
+}): Promise<{
+    configs: Record<string, any>;
+    quarantine: SessionQuarantine[];
+}>;

package/dist/types/extensibility/skc-plugins/schema.d.ts

@@ -0,0 +1,3 @@
+import { type SkcPluginManifest, type SubskillFrontmatter } from "./types";
+export declare function parseManifest(raw: unknown, manifestPath: string): SkcPluginManifest;
+export declare function parseSubskillFrontmatter(fm: Record<string, unknown>, filePath: string): SubskillFrontmatter;

package/dist/types/extensibility/skc-plugins/session-validation.d.ts

@@ -0,0 +1,42 @@
+import type { SkcPluginLoadErrorCode, SkcPluginRegistryEntry } from "./types";
+/**
+ * Session-start validation: the registry is the collision authority. Capability
+ * provider output is supplied as EVIDENCE only; plugin surfaces are never
+ * resolved by capability first-wins. Offending surfaces are quarantined
+ * fail-closed with a stable error code rather than silently shadowed.
+ */
+export interface SessionCapabilityEvidence {
+    /** Built-in + provider tool names already present before plugin insertion. */
+    toolNames?: Iterable<string>;
+    /** Non-plugin MCP server names from providers/built-ins. */
+    mcpNames?: Iterable<string>;
+    /** Non-plugin hook keys (event:phase:target:name) from providers/built-ins. */
+    hookKeys?: Iterable<string>;
+    /** Existing appendix extension ids already present. */
+    appendixIds?: Iterable<string>;
+}
+export interface SessionQuarantine {
+    plugin: string;
+    surfaceId: string;
+    code: SkcPluginLoadErrorCode;
+    message: string;
+}
+export interface SessionValidationResult {
+    /** Registry entries (enabled, non-quarantined) whose surfaces may activate. */
+    active: SkcPluginRegistryEntry[];
+    /** Per-surface quarantine records (fail-closed). */
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Re-verify that the installed files still match the registry's recorded hashes.
+ * Drift (manual edits, partial writes) quarantines the whole plugin with
+ * runtime_mismatch.
+ */
+export declare function verifyEntryHashes(entry: SkcPluginRegistryEntry): Promise<SessionQuarantine | null>;
+/**
+ * Validate the effective installed registry against the current capability
+ * universe (evidence) and across plugins. Returns the entries that may activate
+ * plus per-surface quarantine records. Disabled entries/surfaces are skipped
+ * (not an error).
+ */
+export declare function validateSessionBundles(entries: readonly SkcPluginRegistryEntry[], evidence?: SessionCapabilityEvidence, preQuarantined?: readonly SessionQuarantine[]): SessionValidationResult;

package/dist/types/extensibility/skc-plugins/state.d.ts

@@ -0,0 +1,9 @@
+import type { ActiveSubskillEntry } from "../../skill-state/active-state";
+import type { LoadedSubskillActivation } from "./types";
+export declare function toActiveSubskillEntry(activation: LoadedSubskillActivation): ActiveSubskillEntry;
+export declare function readActiveSubskillsForParent(input: {
+    cwd: string;
+    sessionId?: string;
+    parent: string;
+    phase: string;
+}): Promise<ActiveSubskillEntry[]>;