feat: SDK Foundation — Type Declarations, Errors, and Utilities (#866)

* feat(sdk): add SDK foundation — type declarations, errors, and utilities

Adds standalone SDK building blocks with no SDK source dependencies:
- sdk.d.ts: ambient type declarations for SDK bundle
- coreSchemas.ts + coreTypes.generated.ts: Zod schemas and generated types
- errors.ts: SDK-specific error classes
- validation.ts: input validation utilities
- messageFilters.ts: extracted message filter logic
- handlePromptSubmit.ts: imports from messageFilters
- 16 generated-types tests

* fix(sdk): narrow assertFunction type from broad Function to callable signature

Code review finding: assertFunction used `asserts value is Function` which
accepts any function-like value without narrowing. Changed to
`(...args: any[]) => any` for better type safety.

* fix(sdk): update sdk.d.ts header — manually maintained, not generated

Reviewer noted the header said "Generated from index.ts" but no generator
produces this file. Updated to "Manually maintained — keep in sync with
index.ts". Drift detection added in validate-externals.ts (PR 3).

* fix(sdk): align sdk.d.ts types with canonical coreTypes.generated.ts

Tighten SDK public type contract to resolve reviewer blockers:

- PermissionResult: unknown[] → precise 6-shape discriminated union
  (addRules/replaceRules/removeRules/setMode/addDirectories/removeDirectories)
- SDKSessionInfo: snake_case → camelCase (sessionId, lastModified, etc.)
- ForkSessionResult: session_id → sessionId
- SDKPermissionRequestMessage: uuid + session_id now required
- SDKPermissionTimeoutMessage: added uuid + session_id
- SessionMessage: parent_uuid → parentUuid
- SDKMessage/SDKUserMessage/SDKResultMessage: replaced loose inline
  definitions with re-exports from coreTypes.generated.ts

---------

Co-authored-by: Ali Alakbarli <ali.alakbarli@users.noreply.github.com>

src/entrypoints/sdk.d.ts

@@ -0,0 +1,518 @@
+// Type declarations for @gitlawb/openclaude SDK
+// Manually maintained — keep in sync with src/entrypoints/sdk/index.ts
+// Drift is caught by validate-externals.ts (runs in CI)
+
+// ============================================================================
+// Error
+// ============================================================================
+
+export class AbortError extends Error {
+  override readonly name: 'AbortError'
+}
+
+export class ClaudeError extends Error {
+  constructor(message: string)
+}
+
+export class SDKError extends ClaudeError {
+  constructor(message: string)
+}
+
+export class SDKAuthenticationError extends SDKError {
+  constructor(message?: string)
+}
+
+export class SDKBillingError extends SDKError {
+  constructor(message?: string)
+}
+
+export class SDKRateLimitError extends SDKError {
+  constructor(
+    message?: string,
+    readonly resetsAt?: number,
+    readonly rateLimitType?: string,
+  )
+}
+
+export class SDKInvalidRequestError extends SDKError {
+  constructor(message?: string)
+}
+
+export class SDKServerError extends SDKError {
+  constructor(message?: string)
+}
+
+export class SDKMaxOutputTokensError extends SDKError {
+  constructor(message?: string)
+}
+
+export type SDKAssistantMessageError =
+  | 'authentication_failed'
+  | 'billing_error'
+  | 'rate_limit'
+  | 'invalid_request'
+  | 'server_error'
+  | 'unknown'
+  | 'max_output_tokens'
+
+export function sdkErrorFromType(
+  errorType: SDKAssistantMessageError,
+  message?: string,
+): SDKError | ClaudeError
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ApiKeySource = 'user' | 'project' | 'org' | 'temporary' | 'oauth' | 'none'
+
+export type RewindFilesResult = {
+  canRewind: boolean
+  error?: string
+  filesChanged?: string[]
+  insertions?: number
+  deletions?: number
+}
+
+export type McpServerStatus = {
+  name: string
+  status: 'connected' | 'failed' | 'needs-auth' | 'pending' | 'disabled'
+  serverInfo?: { name: string; version: string }
+  error?: string
+  scope?: string
+  tools?: {
+    name: string
+    description?: string
+    annotations?: {
+      readOnly?: boolean
+      destructive?: boolean
+      openWorld?: boolean
+    }
+  }[]
+}
+
+export type PermissionResult = ({
+  behavior: 'allow'
+  updatedInput?: Record<string, unknown>
+  updatedPermissions?: ({
+    type: 'addRules'
+    rules: { toolName: string; ruleContent?: string }[]
+    behavior: 'allow' | 'deny' | 'ask'
+    destination: 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg'
+  }) | ({
+    type: 'replaceRules'
+    rules: { toolName: string; ruleContent?: string }[]
+    behavior: 'allow' | 'deny' | 'ask'
+    destination: 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg'
+  }) | ({
+    type: 'removeRules'
+    rules: { toolName: string; ruleContent?: string }[]
+    behavior: 'allow' | 'deny' | 'ask'
+    destination: 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg'
+  }) | ({
+    type: 'setMode'
+    mode: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'
+    destination: 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg'
+  }) | ({
+    type: 'addDirectories'
+    directories: string[]
+    destination: 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg'
+  }) | ({
+    type: 'removeDirectories'
+    directories: string[]
+    destination: 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg'
+  })[]
+  toolUseID?: string
+  decisionClassification?: 'user_temporary' | 'user_permanent' | 'user_reject'
+}) | ({
+  behavior: 'deny'
+  message: string
+  interrupt?: boolean
+  toolUseID?: string
+  decisionClassification?: 'user_temporary' | 'user_permanent' | 'user_reject'
+})
+
+export type SDKSessionInfo = {
+  sessionId: string
+  summary: string
+  lastModified: number
+  fileSize?: number
+  customTitle?: string
+  firstPrompt?: string
+  gitBranch?: string
+  cwd?: string
+  tag?: string
+  createdAt?: number
+}
+
+export type ListSessionsOptions = {
+  dir?: string
+  limit?: number
+  offset?: number
+  includeWorktrees?: boolean
+}
+
+export type GetSessionInfoOptions = {
+  dir?: string
+}
+
+export type GetSessionMessagesOptions = {
+  dir?: string
+  limit?: number
+  offset?: number
+  includeSystemMessages?: boolean
+}
+
+export type SessionMutationOptions = {
+  dir?: string
+}
+
+export type ForkSessionOptions = {
+  dir?: string
+  upToMessageId?: string
+  title?: string
+}
+
+export type ForkSessionResult = {
+  sessionId: string
+}
+
+export type SessionMessage = {
+  role: 'user' | 'assistant' | 'system'
+  content: unknown
+  timestamp?: string
+  uuid?: string
+  parentUuid?: string | null
+  [key: string]: unknown
+}
+
+// Re-export precise SDK message types from generated types
+// These use camelCase field names and discriminated unions for full IntelliSense
+export type { SDKMessage as SDKMessage } from './sdk/coreTypes.generated.js'
+export type { SDKUserMessage as SDKUserMessage } from './sdk/coreTypes.generated.js'
+export type { SDKResultMessage as SDKResultMessage } from './sdk/coreTypes.generated.js'
+
+// ============================================================================
+// Query types
+// ============================================================================
+
+export type QueryPermissionMode =
+  | 'default'
+  | 'plan'
+  | 'auto-accept'
+  | 'bypass-permissions'
+  | 'bypassPermissions'
+  | 'acceptEdits'
+
+export type QueryOptions = {
+  cwd: string
+  additionalDirectories?: string[]
+  model?: string
+  sessionId?: string
+  /** Fork the session before resuming (requires sessionId). */
+  fork?: boolean
+  /** Alias for fork. When true, resumed session forks to a new session ID. */
+  forkSession?: boolean
+  /** Resume the most recent session for this cwd (no sessionId needed). */
+  continue?: boolean
+  resume?: string
+  /** When resuming, resume messages up to and including this message UUID. */
+  resumeSessionAt?: string
+  permissionMode?: QueryPermissionMode
+  abortController?: AbortController
+  executable?: string
+  allowDangerouslySkipPermissions?: boolean
+  disallowedTools?: string[]
+  hooks?: Record<string, unknown[]>
+  mcpServers?: Record<string, unknown>
+  settings?: {
+    env?: Record<string, string>
+    attribution?: { commit: string; pr: string }
+  }
+  /** Environment variables to apply during query execution. Overrides process.env. Takes precedence over settings.env. */
+  env?: Record<string, string | undefined>
+  /**
+   * Callback invoked before each tool use. Return `{ behavior: 'allow' }` to
+   * permit the call or `{ behavior: 'deny', message?: string }` to reject it.
+   *
+   * **Secure-by-default**: If neither `canUseTool` nor `onPermissionRequest`
+   * is provided, ALL tool uses are denied. You MUST provide at least one of
+   * these callbacks to allow tool execution.
+   */
+  canUseTool?: (
+    name: string,
+    input: unknown,
+    options?: { toolUseID?: string },
+  ) => Promise<{ behavior: 'allow' | 'deny'; message?: string; updatedInput?: unknown }>
+  /**
+   * Callback invoked when a tool needs permission approval. The host receives
+   * the request immediately and can resolve it by calling
+   * `query.respondToPermission(toolUseId, decision)` before the timeout.
+   * If omitted, tools that require permission fall through to the default
+   * permission logic immediately (no timeout).
+   */
+  onPermissionRequest?: (message: SDKPermissionRequestMessage) => void
+  systemPrompt?:
+    | string
+    | { type: 'preset'; preset: string; append?: string }
+    | { type: 'custom'; content: string }
+  /** Agent definitions to register with the query engine. */
+  agents?: Record<string, {
+    description: string
+    prompt: string
+    tools?: string[]
+    disallowedTools?: string[]
+    model?: string
+    maxTurns?: number
+  }>
+  settingSources?: string[]
+  /** When true, yields stream_event messages for token-by-token streaming. */
+  includePartialMessages?: boolean
+  /** @internal Timeout in ms for permission request resolution. Default 30000. */
+  _permissionTimeoutMs?: number
+  stderr?: (data: string) => void
+}
+
+export interface Query {
+  readonly sessionId: string
+  [Symbol.asyncIterator](): AsyncIterator<SDKMessage>
+  setModel(model: string): Promise<void>
+  setPermissionMode(mode: QueryPermissionMode): Promise<void>
+  close(): void
+  interrupt(): void
+  respondToPermission(toolUseId: string, decision: PermissionResult): void
+  /** Check if file rewind is possible. */
+  rewindFiles(): RewindFilesResult
+  /** Actually perform the file rewind. Returns files changed and diff stats. */
+  rewindFilesAsync(): Promise<RewindFilesResult>
+  supportedCommands(): string[]
+  supportedModels(): string[]
+  supportedAgents(): string[]
+  mcpServerStatus(): McpServerStatus[]
+  accountInfo(): Promise<{ apiKeySource: ApiKeySource; [key: string]: unknown }>
+  setMaxThinkingTokens(tokens: number): void
+}
+
+/**
+ * Permission request message emitted when a tool needs permission approval.
+ * Hosts can respond via respondToPermission() using the request_id.
+ */
+export type SDKPermissionRequestMessage = {
+  type: 'permission_request'
+  request_id: string
+  tool_name: string
+  tool_use_id: string
+  input: Record<string, unknown>
+  uuid: string
+  session_id: string
+}
+
+export type SDKPermissionTimeoutMessage = {
+  type: 'permission_timeout'
+  tool_name: string
+  tool_use_id: string
+  timed_out_after_ms: number
+  uuid: string
+  session_id: string
+}
+
+// ============================================================================
+// V2 API types
+// ============================================================================
+
+export type SDKSessionOptions = {
+  cwd: string
+  model?: string
+  permissionMode?: QueryPermissionMode
+  abortController?: AbortController
+  /**
+   * Callback invoked before each tool use. Return `{ behavior: 'allow' }` to
+   * permit the call or `{ behavior: 'deny', message?: string }` to reject it.
+   *
+   * **Secure-by-default**: If neither `canUseTool` nor `onPermissionRequest`
+   * is provided, ALL tool uses are denied. You MUST provide at least one of
+   * these callbacks to allow tool execution.
+   */
+  canUseTool?: (
+    name: string,
+    input: unknown,
+    options?: { toolUseID?: string },
+  ) => Promise<{ behavior: 'allow' | 'deny'; message?: string; updatedInput?: unknown }>
+  /** MCP server configurations for this session. */
+  mcpServers?: Record<string, unknown>
+  /**
+   * Callback invoked when a tool needs permission approval. The host receives
+   * the request immediately and can resolve it via respondToPermission().
+   */
+  onPermissionRequest?: (message: SDKPermissionRequestMessage) => void
+}
+
+export interface SDKSession {
+  sessionId: string
+  sendMessage(content: string): AsyncIterable<SDKMessage>
+  getMessages(): SDKMessage[]
+  interrupt(): void
+  /** Respond to a pending permission prompt. */
+  respondToPermission(toolUseId: string, decision: PermissionResult): void
+}
+
+// ============================================================================
+// MCP tool types
+// ============================================================================
+
+export interface SdkMcpToolDefinition<Schema = any> {
+  name: string
+  description: string
+  inputSchema: Schema
+  handler: (args: any, extra: unknown) => Promise<any>
+  annotations?: any
+  searchHint?: string
+  alwaysLoad?: boolean
+}
+
+// ============================================================================
+// Session functions
+// ============================================================================
+
+export function listSessions(
+  options?: ListSessionsOptions,
+): Promise<SDKSessionInfo[]>
+
+export function getSessionInfo(
+  sessionId: string,
+  options?: GetSessionInfoOptions,
+): Promise<SDKSessionInfo | undefined>
+
+export function getSessionMessages(
+  sessionId: string,
+  options?: GetSessionMessagesOptions,
+): Promise<SessionMessage[]>
+
+export function renameSession(
+  sessionId: string,
+  title: string,
+  options?: SessionMutationOptions,
+): Promise<void>
+
+export function tagSession(
+  sessionId: string,
+  tag: string | null,
+  options?: SessionMutationOptions,
+): Promise<void>
+
+export function forkSession(
+  sessionId: string,
+  options?: ForkSessionOptions,
+): Promise<ForkSessionResult>
+
+export function deleteSession(
+  sessionId: string,
+  options?: SessionMutationOptions,
+): Promise<void>
+
+// ============================================================================
+// Query functions
+// ============================================================================
+
+export function query(params: {
+  prompt: string | AsyncIterable<SDKUserMessage>
+  options?: QueryOptions
+}): Query
+
+export function queryAsync(params: {
+  prompt: string | AsyncIterable<SDKUserMessage>
+  options?: QueryOptions
+}): Promise<Query>
+
+// ============================================================================
+// V2 API functions
+// ============================================================================
+
+export function unstable_v2_createSession(options: SDKSessionOptions): SDKSession
+
+export function unstable_v2_resumeSession(
+  sessionId: string,
+  options: SDKSessionOptions,
+): Promise<SDKSession>
+
+export function unstable_v2_prompt(
+  message: string,
+  options: SDKSessionOptions,
+): Promise<SDKResultMessage>
+
+// ============================================================================
+// MCP tool functions
+// ============================================================================
+
+export function tool<Schema = any>(
+  name: string,
+  description: string,
+  inputSchema: Schema,
+  handler: (args: any, extra: unknown) => Promise<any>,
+  extras?: {
+    annotations?: any
+    searchHint?: string
+    alwaysLoad?: boolean
+  },
+): SdkMcpToolDefinition<Schema>
+
+/**
+ * MCP server transport configuration types.
+ * Matches McpServerConfigForProcessTransport from coreTypes.generated.ts.
+ */
+export type SdkMcpStdioConfig = {
+  type?: "stdio"
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+}
+
+export type SdkMcpSSEConfig = {
+  type: "sse"
+  url: string
+  headers?: Record<string, string>
+}
+
+export type SdkMcpHttpConfig = {
+  type: "http"
+  url: string
+  headers?: Record<string, string>
+}
+
+export type SdkMcpSdkConfig = {
+  type: "sdk"
+  name: string
+}
+
+export type SdkMcpServerConfig = SdkMcpStdioConfig | SdkMcpSSEConfig | SdkMcpHttpConfig | SdkMcpSdkConfig
+
+/**
+ * Scoped MCP server config with session scope.
+ * Returned by createSdkMcpServer() for use with mcpServers option.
+ */
+export type SdkScopedMcpServerConfig = SdkMcpServerConfig & {
+  scope: "session"
+}
+
+/**
+ * Wraps an MCP server configuration for use with the SDK.
+ * Adds the 'session' scope marker so the SDK knows this server
+ * should be connected per-session (not globally).
+ *
+ * @param config - MCP server config (stdio, sse, http, or sdk type)
+ * @returns Scoped config with scope: 'session' added
+ *
+ * @example
+ * ```typescript
+ * const server = createSdkMcpServer({
+ *   type: 'stdio',
+ *   command: 'npx',
+ *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+ * })
+ * const session = unstable_v2_createSession({
+ *   cwd: '/my/project',
+ *   mcpServers: { 'fs': server },
+ * })
+ * ```
+ */
+export function createSdkMcpServer(config: SdkMcpServerConfig): SdkScopedMcpServerConfig

src/entrypoints/sdk/coreSchemas.ts

@@ -55,7 +55,7 @@ export const OutputFormatSchema = lazySchema(() =>
 // ============================================================================
 
 export const ApiKeySourceSchema = lazySchema(() =>
-  z.enum(['user', 'project', 'org', 'temporary', 'oauth']),
+  z.enum(['user', 'project', 'org', 'temporary', 'oauth', 'none']),
 )
 
 export const ConfigScopeSchema = lazySchema(() =>
@@ -1851,6 +1851,18 @@ export const SDKSessionInfoSchema = lazySchema(() =>
     .describe('Session metadata returned by listSessions and getSessionInfo.'),
 )
 
+export const SDKPermissionRequestMessageSchema = lazySchema(() =>
+  z.object({
+    type: z.literal('permission_request'),
+    request_id: z.string().describe('Unique request ID for this permission prompt'),
+    tool_name: z.string().describe('Name of the tool requesting permission'),
+    tool_use_id: z.string().describe('Tool use ID for matching with respondToPermission'),
+    input: z.record(z.string(), z.unknown()).describe('Tool input parameters'),
+    uuid: UUIDPlaceholder(),
+    session_id: z.string(),
+  }),
+)
+
 export const SDKMessageSchema = lazySchema(() =>
   z.union([
     SDKAssistantMessageSchema(),
@@ -1877,6 +1889,7 @@ export const SDKMessageSchema = lazySchema(() =>
     SDKRateLimitEventSchema(),
     SDKElicitationCompleteMessageSchema(),
     SDKPromptSuggestionMessageSchema(),
+    SDKPermissionRequestMessageSchema(),
   ]),
 )
 

src/utils/errors.ts

@@ -201,6 +201,95 @@ export type AxiosErrorKind =
   | 'http' // other axios error (may have status)
   | 'other' // not an axios error
 
+// ============================================================================
+// SDK-specific error classes
+// ============================================================================
+
+/**
+ * Base class for all SDK errors. Extends ClaudeError so that existing
+ * `catch (e) { if (e instanceof ClaudeError) … }` checks still work,
+ * while giving SDK consumers a more specific base to match against.
+ */
+export class SDKError extends ClaudeError {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SDKError'
+  }
+}
+
+export class SDKAuthenticationError extends SDKError {
+  constructor(message?: string) {
+    super(message ?? 'Authentication failed')
+    this.name = 'SDKAuthenticationError'
+  }
+}
+
+export class SDKBillingError extends SDKError {
+  constructor(message?: string) {
+    super(message ?? 'Billing error - check subscription')
+    this.name = 'SDKBillingError'
+  }
+}
+
+export class SDKRateLimitError extends SDKError {
+  constructor(
+    message?: string,
+    public readonly resetsAt?: number,
+    public readonly rateLimitType?: string,
+  ) {
+    super(message ?? 'Rate limit exceeded')
+    this.name = 'SDKRateLimitError'
+  }
+}
+
+export class SDKInvalidRequestError extends SDKError {
+  constructor(message?: string) {
+    super(message ?? 'Invalid request')
+    this.name = 'SDKInvalidRequestError'
+  }
+}
+
+export class SDKServerError extends SDKError {
+  constructor(message?: string) {
+    super(message ?? 'Server error')
+    this.name = 'SDKServerError'
+  }
+}
+
+export class SDKMaxOutputTokensError extends SDKError {
+  constructor(message?: string) {
+    super(message ?? 'Max output tokens reached')
+    this.name = 'SDKMaxOutputTokensError'
+  }
+}
+
+export type SDKAssistantMessageError =
+  | 'authentication_failed'
+  | 'billing_error'
+  | 'rate_limit'
+  | 'invalid_request'
+  | 'server_error'
+  | 'unknown'
+  | 'max_output_tokens'
+
+/**
+ * Convert an SDKAssistantMessageError type string to the proper Error class.
+ */
+export function sdkErrorFromType(
+  errorType: SDKAssistantMessageError,
+  message?: string,
+): SDKError | ClaudeError {
+  switch (errorType) {
+    case 'authentication_failed': return new SDKAuthenticationError(message)
+    case 'billing_error': return new SDKBillingError(message)
+    case 'rate_limit': return new SDKRateLimitError(message)
+    case 'invalid_request': return new SDKInvalidRequestError(message)
+    case 'server_error': return new SDKServerError(message)
+    case 'max_output_tokens': return new SDKMaxOutputTokensError(message)
+    default: return new ClaudeError(message ?? 'Unknown error')
+  }
+}
+
 /**
  * Classify a caught error from an axios request into one of a few buckets.
  * Replaces the ~20-line isAxiosError → 401/403 → ECONNABORTED → ECONNREFUSED

src/utils/handlePromptSubmit.ts

@@ -2,7 +2,7 @@ import type { UUID } from 'crypto'
 import { logEvent } from 'src/services/analytics/index.js'
 import type { AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS } from 'src/services/analytics/metadata.js'
 import { type Command, getCommandName, isCommandEnabled } from '../commands.js'
-import { selectableUserMessagesFilter } from '../components/MessageSelector.js'
+import { selectableUserMessagesFilter } from './messageFilters.js'
 import type { SpinnerMode } from '../components/Spinner/types.js'
 import type { QuerySource } from '../constants/querySource.js'
 import { expandPastedTextRefs, parseReferences } from '../history.js'

src/utils/messageFilters.ts

@@ -0,0 +1,81 @@
+import type { ContentBlockParam, TextBlockParam } from '@anthropic-ai/sdk/resources/index.mjs'
+import type { Message, UserMessage } from '../types/message.js'
+import {
+  BASH_STDERR_TAG,
+  BASH_STDOUT_TAG,
+  LOCAL_COMMAND_STDERR_TAG,
+  LOCAL_COMMAND_STDOUT_TAG,
+  TASK_NOTIFICATION_TAG,
+  TEAMMATE_MESSAGE_TAG,
+  TICK_TAG,
+} from '../constants/xml.js'
+import { isSyntheticMessage, isToolUseResultMessage } from './messages.js'
+
+function isTextBlock(block: ContentBlockParam): block is TextBlockParam {
+  return block.type === 'text'
+}
+
+export function selectableUserMessagesFilter(message: Message): message is UserMessage {
+  if (message.type !== 'user') {
+    return false
+  }
+  if (Array.isArray(message.message.content) && message.message.content[0]?.type === 'tool_result') {
+    return false
+  }
+  if (isSyntheticMessage(message)) {
+    return false
+  }
+  if (message.isMeta) {
+    return false
+  }
+  if (message.isCompactSummary || message.isVisibleInTranscriptOnly) {
+    return false
+  }
+  const content = message.message.content
+  const lastBlock = typeof content === 'string' ? null : content[content.length - 1]
+  const messageText = typeof content === 'string' ? content.trim() : lastBlock && isTextBlock(lastBlock) ? lastBlock.text.trim() : ''
+
+  // Filter out non-user-authored messages (command outputs, task notifications, ticks).
+  if (messageText.indexOf(`<${LOCAL_COMMAND_STDOUT_TAG}>`) !== -1 || messageText.indexOf(`<${LOCAL_COMMAND_STDERR_TAG}>`) !== -1 || messageText.indexOf(`<${BASH_STDOUT_TAG}>`) !== -1 || messageText.indexOf(`<${BASH_STDERR_TAG}>`) !== -1 || messageText.indexOf(`<${TASK_NOTIFICATION_TAG}>`) !== -1 || messageText.indexOf(`<${TICK_TAG}>`) !== -1 || messageText.indexOf(`<${TEAMMATE_MESSAGE_TAG}`) !== -1) {
+    return false
+  }
+  return true
+}
+
+/**
+ * Checks if all messages after the given index are synthetic (interruptions, cancels, etc.)
+ * or non-meaningful content. Returns true if there's nothing meaningful to confirm -
+ * for example, if the user hit enter then immediately cancelled.
+ */
+export function messagesAfterAreOnlySynthetic(messages: Message[], fromIndex: number): boolean {
+  for (let i = fromIndex + 1; i < messages.length; i++) {
+    const msg = messages[i]
+    if (!msg) continue
+
+    // Skip known non-meaningful message types
+    if (isSyntheticMessage(msg)) continue
+    if (isToolUseResultMessage(msg)) continue
+    if (msg.type === 'progress') continue
+    if (msg.type === 'system') continue
+    if (msg.type === 'attachment') continue
+    if (msg.type === 'user' && msg.isMeta) continue
+
+    // Assistant with actual content = meaningful
+    if (msg.type === 'assistant') {
+      const content = msg.message.content
+      if (Array.isArray(content)) {
+        const hasMeaningfulContent = content.some(block => block.type === 'text' && block.text.trim() || block.type === 'tool_use')
+        if (hasMeaningfulContent) return false
+      }
+      continue
+    }
+
+    // User messages that aren't synthetic or meta = meaningful
+    if (msg.type === 'user') {
+      return false
+    }
+
+    // Other types (e.g., tombstone) are non-meaningful, continue
+  }
+  return true
+}

src/utils/user.test.ts

@@ -10,9 +10,12 @@ function installCommonMocks(options?: {
   oauthEmail?: string
   gitEmail?: string
 }) {
-  mock.module('../bootstrap/state.js', () => ({
+  // NOTE: Do NOT mock ../bootstrap/state.js here.
-    getSessionId: () => 'session-test',
+  // mock.module() is process-global in bun:test and mock.restore() does NOT
-  }))
+  // undo it. Mocking state.js leaks getSessionId = () => 'session-test' into
+  // every other test file that imports state.js (e.g. SDK CON-1 tests).
+  // The dynamic import (importFreshUserModule) will use the real state.js,
+  // which is fine — these tests only assert email, not sessionId.
 
   mock.module('./auth.js', () => ({
     getOauthAccountInfo: () =>

src/utils/validation.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared validation utilities for SDK-facing APIs.
+ */
+
+/**
+ * Validate an array of items using a per-item validator.
+ * Throws TypeError with the index and missing field if validation fails.
+ */
+export function validateArrayOf<T>(
+  items: unknown[],
+  validator: (item: unknown, index: number) => T,
+  label: string,
+): T[] {
+  if (!Array.isArray(items)) {
+    throw new TypeError(`${label}: expected an array, got ${typeof items}`)
+  }
+  return items.map((item, i) => {
+    try {
+      return validator(item, i)
+    } catch (err) {
+      if (err instanceof TypeError) {
+        throw new TypeError(`${label}: item at index ${i} - ${err.message}`)
+      }
+      throw err
+    }
+  })
+}
+
+/**
+ * Assert that a value is a non-empty string.
+ */
+export function assertNonEmptyString(value: unknown, field: string): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`missing or empty '${field}' (expected non-empty string)`)
+  }
+}
+
+/**
+ * Assert that a value is a non-null object (but not an array).
+ */
+export function assertObject(value: unknown, field: string): asserts value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`missing or invalid '${field}' (expected object)`)
+  }
+}
+
+/**
+ * Assert that a value is a function.
+ */
+export function assertFunction(value: unknown, field: string): asserts value is (...args: any[]) => any {
+  if (typeof value !== 'function') {
+    throw new TypeError(`missing or invalid '${field}' (expected function)`)
+  }
+}

tests/sdk/generated-types.test.ts

@@ -0,0 +1,279 @@
+import { describe, test, expect } from 'bun:test'
+import {
+  SDKAssistantMessageSchema,
+  SDKSystemMessageSchema,
+  SDKCompactBoundaryMessageSchema,
+  SDKMessageSchema,
+  SDKUserMessageSchema,
+  SDKResultMessageSchema,
+  SDKResultSuccessSchema,
+  SDKResultErrorSchema,
+  SDKSessionInfoSchema,
+  PermissionModeSchema,
+  ThinkingConfigSchema,
+  AgentDefinitionSchema,
+  McpServerStatusSchema,
+  ModelUsageSchema,
+  FastModeStateSchema,
+  HookInputSchema,
+  ExitReasonSchema,
+} from '../../src/entrypoints/sdk/coreSchemas.js'
+import { z } from 'zod/v4'
+
+/**
+ * Tests for generated SDK types from Zod schemas.
+ *
+ * These tests verify that:
+ * 1. All schemas materialize correctly (no lazy errors)
+ * 2. Schemas can parse valid data
+ * 3. Key discriminated fields are correct
+ * 4. The full SDKMessage union accepts all message variants
+ */
+describe('SDK Zod schemas (type generation source)', () => {
+  test('SDKAssistantMessageSchema accepts valid data', () => {
+    const schema = SDKAssistantMessageSchema()
+    const result = schema.safeParse({
+      type: 'assistant',
+      message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] },
+      parent_tool_use_id: null,
+      uuid: '12345678-1234-1234-1234-123456789012',
+      session_id: '12345678-1234-1234-1234-123456789012',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('SDKSystemMessageSchema accepts valid data', () => {
+    const schema = SDKSystemMessageSchema()
+    const result = schema.safeParse({
+      type: 'system',
+      subtype: 'init',
+      apiKeySource: 'user',
+      claude_code_version: '0.3.0',
+      cwd: '/home/user/project',
+      tools: ['Read', 'Write'],
+      mcp_servers: [{ name: 'test', status: 'connected' }],
+      model: 'claude-sonnet-4-6',
+      permissionMode: 'default',
+      slash_commands: [],
+      output_style: 'default',
+      skills: [],
+      plugins: [],
+      uuid: '12345678-1234-1234-1234-123456789012',
+      session_id: '12345678-1234-1234-1234-123456789012',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('SDKCompactBoundaryMessageSchema accepts valid data', () => {
+    const schema = SDKCompactBoundaryMessageSchema()
+    const result = schema.safeParse({
+      type: 'system',
+      subtype: 'compact_boundary',
+      compact_metadata: {
+        trigger: 'manual',
+        pre_tokens: 1000,
+      },
+      uuid: '12345678-1234-1234-1234-123456789012',
+      session_id: '12345678-1234-1234-1234-123456789012',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('SDKCompactBoundaryMessageSchema accepts preserved_segment', () => {
+    const schema = SDKCompactBoundaryMessageSchema()
+    const result = schema.safeParse({
+      type: 'system',
+      subtype: 'compact_boundary',
+      compact_metadata: {
+        trigger: 'auto',
+        pre_tokens: 50000,
+        preserved_segment: {
+          head_uuid: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+          anchor_uuid: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
+          tail_uuid: 'cccccccc-cccc-cccc-cccc-cccccccccccc',
+        },
+      },
+      uuid: '12345678-1234-1234-1234-123456789012',
+      session_id: '12345678-1234-1234-1234-123456789012',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('SDKUserMessageSchema accepts valid data', () => {
+    const schema = SDKUserMessageSchema()
+    const result = schema.safeParse({
+      type: 'user',
+      message: { role: 'user', content: 'hello' },
+      parent_tool_use_id: null,
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('SDKResultSuccessSchema accepts valid data', () => {
+    const schema = SDKResultSuccessSchema()
+    const result = schema.safeParse({
+      type: 'result',
+      subtype: 'success',
+      duration_ms: 1500,
+      duration_api_ms: 1200,
+      is_error: false,
+      num_turns: 1,
+      result: 'Done',
+      stop_reason: 'end_turn',
+      total_cost_usd: 0.01,
+      usage: { input_tokens: 100, output_tokens: 50 },
+      modelUsage: {},
+      permission_denials: [],
+      uuid: '12345678-1234-1234-1234-123456789012',
+      session_id: '12345678-1234-1234-1234-123456789012',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('SDKResultErrorSchema accepts valid data', () => {
+    const schema = SDKResultErrorSchema()
+    const result = schema.safeParse({
+      type: 'result',
+      subtype: 'error_during_execution',
+      duration_ms: 100,
+      duration_api_ms: 80,
+      is_error: true,
+      num_turns: 1,
+      stop_reason: null,
+      total_cost_usd: 0.001,
+      usage: { input_tokens: 50, output_tokens: 10 },
+      modelUsage: {},
+      permission_denials: [],
+      errors: ['Something went wrong'],
+      uuid: '12345678-1234-1234-1234-123456789012',
+      session_id: '12345678-1234-1234-1234-123456789012',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('SDKMessageSchema accepts all message types', () => {
+    const schema = SDKMessageSchema()
+
+    const messages = [
+      {
+        type: 'assistant',
+        message: {},
+        parent_tool_use_id: null,
+        uuid: '12345678-1234-1234-1234-123456789012',
+        session_id: '12345678-1234-1234-1234-123456789012',
+      },
+      {
+        type: 'user',
+        message: {},
+        parent_tool_use_id: null,
+      },
+      {
+        type: 'system',
+        subtype: 'init',
+        apiKeySource: 'user',
+        claude_code_version: '0.3.0',
+        cwd: '/tmp',
+        tools: [],
+        mcp_servers: [],
+        model: 'sonnet',
+        permissionMode: 'default',
+        slash_commands: [],
+        output_style: 'default',
+        skills: [],
+        plugins: [],
+        uuid: '12345678-1234-1234-1234-123456789012',
+        session_id: '12345678-1234-1234-1234-123456789012',
+      },
+      {
+        type: 'system',
+        subtype: 'compact_boundary',
+        compact_metadata: { trigger: 'manual', pre_tokens: 100 },
+        uuid: '12345678-1234-1234-1234-123456789012',
+        session_id: '12345678-1234-1234-1234-123456789012',
+      },
+    ]
+
+    for (const msg of messages) {
+      const result = schema.safeParse(msg)
+      expect(result.success).toBe(true)
+    }
+  })
+
+  test('SDKSessionInfoSchema accepts valid data', () => {
+    const schema = SDKSessionInfoSchema()
+    const result = schema.safeParse({
+      sessionId: '12345678-1234-1234-1234-123456789012',
+      summary: 'Test session',
+      lastModified: Date.now(),
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('PermissionModeSchema accepts valid modes', () => {
+    const schema = PermissionModeSchema()
+    const modes = ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'dontAsk']
+    for (const mode of modes) {
+      expect(schema.safeParse(mode).success).toBe(true)
+    }
+    expect(schema.safeParse('invalid').success).toBe(false)
+  })
+
+  test('ThinkingConfigSchema accepts all variants', () => {
+    const schema = ThinkingConfigSchema()
+    expect(schema.safeParse({ type: 'adaptive' }).success).toBe(true)
+    expect(schema.safeParse({ type: 'enabled' }).success).toBe(true)
+    expect(schema.safeParse({ type: 'enabled', budgetTokens: 10000 }).success).toBe(true)
+    expect(schema.safeParse({ type: 'disabled' }).success).toBe(true)
+    expect(schema.safeParse({ type: 'unknown' }).success).toBe(false)
+  })
+
+  test('FastModeStateSchema accepts valid states', () => {
+    const schema = FastModeStateSchema()
+    expect(schema.safeParse('off').success).toBe(true)
+    expect(schema.safeParse('cooldown').success).toBe(true)
+    expect(schema.safeParse('on').success).toBe(true)
+    expect(schema.safeParse('unknown').success).toBe(false)
+  })
+
+  test('ExitReasonSchema accepts valid reasons', () => {
+    const schema = ExitReasonSchema()
+    const reasons = ['clear', 'resume', 'logout', 'prompt_input_exit', 'other', 'bypass_permissions_disabled']
+    for (const r of reasons) {
+      expect(schema.safeParse(r).success).toBe(true)
+    }
+    expect(schema.safeParse('invalid').success).toBe(false)
+  })
+
+  test('ModelUsageSchema accepts valid data', () => {
+    const schema = ModelUsageSchema()
+    const result = schema.safeParse({
+      inputTokens: 100,
+      outputTokens: 50,
+      cacheReadInputTokens: 200,
+      cacheCreationInputTokens: 300,
+      webSearchRequests: 1,
+      costUSD: 0.01,
+      contextWindow: 200000,
+      maxOutputTokens: 8192,
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('AgentDefinitionSchema accepts valid data', () => {
+    const schema = AgentDefinitionSchema()
+    const result = schema.safeParse({
+      description: 'Test agent',
+      prompt: 'You are a test agent',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('McpServerStatusSchema accepts valid data', () => {
+    const schema = McpServerStatusSchema()
+    const result = schema.safeParse({
+      name: 'test-server',
+      status: 'connected',
+    })
+    expect(result.success).toBe(true)
+  })
+})