Configuration Options

interface Options {
  // Model & Execution
  model?: string;
  fallbackModel?: string;
  cwd?: string;
  maxTurns?: number;
  maxBudgetUsd?: number;
  maxThinkingTokens?: number;
  abortController?: AbortController;

  // Tools
  tools?: string[] | {type: 'preset'; preset: 'claude_code'};
  allowedTools?: string[];
  disallowedTools?: string[];

  // Permissions
  permissionMode?: PermissionMode;
  canUseTool?: CanUseTool;
  allowDangerouslySkipPermissions?: boolean;
  permissionPromptToolName?: string;

  // Environment
  additionalDirectories?: string[];
  env?: {[envVar: string]: string | undefined};
  executable?: 'bun' | 'deno' | 'node';
  executableArgs?: string[];
  pathToClaudeCodeExecutable?: string;
  extraArgs?: Record<string, string | null>;

  // Extensions
  agents?: Record<string, AgentDefinition>;
  hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
  mcpServers?: Record<string, McpServerConfig>;
  strictMcpConfig?: boolean;

  // System
  systemPrompt?: string | {type: 'preset'; preset: 'claude_code'; append?: string};
  outputFormat?: OutputFormat;
  includePartialMessages?: boolean;

  // Session
  continue?: boolean;
  resume?: string;
  resumeSessionAt?: string;
  forkSession?: boolean;
  settingSources?: SettingSource[];

  // Other
  plugins?: SdkPluginConfig[];
  sandbox?: SandboxSettings;
  betas?: SdkBeta[];
  stderr?: (data: string) => void;
}

{
  model: 'claude-sonnet-4-5-20250929',
  cwd: '/path/to/project',
  maxTurns: 20,
  maxBudgetUsd: 1.00
}

// Specific tools only
{allowedTools: ['Read', 'Grep', 'Glob']}

// All except specified
{
  tools: {type: 'preset', preset: 'claude_code'},
  disallowedTools: ['Edit', 'Write', 'Bash']
}

// Minimal toolset
{tools: ['Grep', 'Glob']}

// Auto-accept edits
{permissionMode: 'acceptEdits'}

// Planning mode (no execution)
{permissionMode: 'plan'}

// Bypass all (requires safety flag)
{
  permissionMode: 'bypassPermissions',
  allowDangerouslySkipPermissions: true
}

// Custom handler
{
  canUseTool: async (toolName, input, opts) => {
    // Custom logic
    return {behavior: 'allow', updatedInput: input};
  }
}

{
  cwd: '/path/to/project',
  additionalDirectories: ['/path/to/shared'],
  env: {
    NODE_ENV: 'production',
    API_KEY: process.env.API_KEY
  },
  executable: 'bun',
  executableArgs: ['--no-warnings']
}

// Continue previous
{continue: true}

// Resume specific session
{resume: 'session-id-123'}

// Resume and fork
{resume: 'session-id-123', forkSession: true}

// Resume from message
{resume: 'session-id', resumeSessionAt: 'msg-uuid'}

{
  agents: {
    'reviewer': {
      description: 'Reviews code',
      tools: ['Read', 'Grep'],
      prompt: 'Review code for bugs and style',
      model: 'opus'
    }
  }
}

{
  hooks: {
    PreToolUse: [{
      hooks: [async (input) => {
        console.log('Tool:', input.tool_name);
        return {continue: true};
      }]
    }]
  }
}

{
  mcpServers: {
    'db': {
      command: 'node',
      args: ['./db-server.js'],
      env: {DB_HOST: 'localhost'}
    },
    'api': {
      type: 'http',
      url: 'http://localhost:3000/mcp'
    }
  },
  strictMcpConfig: true
}

{
  sandbox: {
    enabled: true,
    autoAllowBashIfSandboxed: true,
    network: {
      allowUnixSockets: ['/var/run/docker.sock'],
      allowLocalBinding: true
    },
    excludedCommands: ['docker']
  }
}

// Custom
{systemPrompt: 'You are a TypeScript expert.'}

// Extend default
{
  systemPrompt: {
    type: 'preset',
    preset: 'claude_code',
    append: 'Explain reasoning step by step.'
  }
}

{
  outputFormat: {
    type: 'json_schema',
    schema: {
      type: 'object',
      properties: {
        complexity: {type: 'number'},
        issues: {type: 'array', items: {type: 'object'}}
      },
      required: ['complexity']
    }
  }
}

// All settings
{settingSources: ['user', 'project', 'local']}

// Isolated (no filesystem settings)
{settingSources: []}

// Project only (for CLAUDE.md)
{settingSources: ['project']}

{
  model: 'claude-sonnet-4-5-20250929',
  betas: ['context-1m-2025-08-07'] // 1M token context
}

{
  stderr: (data) => console.error('[STDERR]', data),
  includePartialMessages: true // Streaming updates
}

type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk';
type SettingSource = 'user' | 'project' | 'local';
type SdkBeta = 'context-1m-2025-08-07';

interface OutputFormat {
  type: 'json_schema';
  schema: Record<string, unknown>;
}

interface SdkPluginConfig {
  type: 'local';
  path: string;
}