@tanstack/ai-claude-code 0.1.0

package/src/adapters/text.ts

@@ -0,0 +1,539 @@
+import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
+import { toRunErrorRawEvent } from '@tanstack/ai/adapter-internals'
+import { BaseTextAdapter } from '@tanstack/ai/adapters'
+import {
+  SandboxCapability,
+  approvalId,
+  buildApprovalRequestedEvent,
+  createBridgeEventChannel,
+  getSandbox,
+  getSandboxPolicy,
+  getToolBridgeProvisioner,
+  getWorkspaceProjection,
+  mergeChunkStreams,
+  nodeHttpBridgeProvisioner,
+  resolveApproval,
+  spawnNdjson,
+} from '@tanstack/ai-sandbox'
+import { buildPrompt } from '../messages/prompt'
+import { translateSdkStream } from '../stream/translate'
+import { mapPolicyToClaudeFlags } from './policy-map'
+import { projectClaudeWorkspace } from './projection'
+import type { ClaudePolicyFlags } from './policy-map'
+import type {
+  BridgeEventChannel,
+  HostToolBridge,
+  PermissionToolResult,
+  SandboxHandle,
+  SandboxPolicy,
+} from '@tanstack/ai-sandbox'
+import type {
+  StructuredOutputOptions,
+  StructuredOutputResult,
+} from '@tanstack/ai/adapters'
+import type {
+  DefaultMessageMetadataByModality,
+  Modality,
+  StreamChunk,
+  TextOptions,
+} from '@tanstack/ai'
+import type { ClaudeCodeModel } from '../model-meta'
+import type { ClaudeCodeTextProviderOptions } from '../provider-options'
+import type { AgentSdkMessage } from '../stream/sdk-types'
+
+export type ClaudeCodePermissionMode =
+  | 'default'
+  | 'acceptEdits'
+  | 'bypassPermissions'
+  | 'plan'
+
+const DEFAULT_WORKDIR = '/workspace'
+
+export interface ClaudeCodeTextConfig {
+  /**
+   * Working directory inside the sandbox where `claude` runs. Defaults to
+   * `/workspace` (the conventional sandbox workspace root).
+   */
+  cwd?: string
+  /**
+   * Claude Code permission mode passed via `--permission-mode`. Defaults to
+   * `'bypassPermissions'` — a sandbox is isolated, so the agent is allowed to
+   * edit files and run commands without prompting. Tighten via `defineSandboxPolicy`
+   * / this option for less autonomy.
+   */
+  permissionMode?: ClaudeCodePermissionMode
+  /** Built-in tools the harness may use (`--allowedTools`). */
+  allowedTools?: Array<string>
+  /** Built-in tools removed from the harness (`--disallowedTools`). */
+  disallowedTools?: Array<string>
+  /** Extra directories the agent may access (`--add-dir`). */
+  addDirs?: Array<string>
+  /** Maximum harness-internal turns (`--max-turns`). */
+  maxTurns?: number
+  /**
+   * How `systemPrompts` from `chat()` are applied:
+   * - `'append'` (default): `--append-system-prompt` on top of the preset.
+   * - `'replace'`: `--system-prompt` as the entire system prompt.
+   */
+  systemPromptMode?: 'append' | 'replace'
+  /** Path/name of the claude executable inside the sandbox. Defaults to `claude`. */
+  claudeExecutable?: string
+  /** Emit token-level deltas via `--include-partial-messages` (default true). */
+  streamPartials?: boolean
+  /** Extra environment variables for the claude process inside the sandbox. */
+  env?: Record<string, string>
+  /** Emit a `file.changed` CUSTOM event with the git diff after the run (default true). */
+  emitDiff?: boolean
+}
+
+/** POSIX single-quote escape for embedding values in the `claude …` command. */
+function q(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/** Format a host tool-bridge as claude's `--mcp-config` JSON. */
+function bridgeToMcpConfig(bridge: HostToolBridge): string {
+  return JSON.stringify({
+    mcpServers: {
+      [bridge.name]: {
+        type: 'http',
+        url: bridge.url,
+        headers: { Authorization: `Bearer ${bridge.token}` },
+      },
+    },
+  })
+}
+
+export class ClaudeCodeTextAdapter<
+  TModel extends ClaudeCodeModel,
+> extends BaseTextAdapter<
+  TModel,
+  ClaudeCodeTextProviderOptions,
+  ReadonlyArray<Modality> & readonly ['text'],
+  DefaultMessageMetadataByModality,
+  ReadonlyArray<string>,
+  unknown,
+  never
+> {
+  readonly name = 'claude-code' as const
+
+  // Harness adapter: requires a sandbox to run the agent CLI inside.
+  override readonly requires = [SandboxCapability] as const
+
+  private readonly adapterConfig: ClaudeCodeTextConfig
+
+  constructor(config: ClaudeCodeTextConfig, model: TModel) {
+    super({}, model)
+    this.adapterConfig = config
+  }
+
+  private sandboxFrom(
+    options: TextOptions<ClaudeCodeTextProviderOptions>,
+  ): SandboxHandle {
+    const ctx = options.capabilities
+    if (!ctx) {
+      throw new Error(
+        'Adapter "claude-code" requires a sandbox. Add withSandbox(defineSandbox({ ... })) ' +
+          'to chat() middleware (e.g. with the local-process or docker provider).',
+      )
+    }
+    return getSandbox(ctx)
+  }
+
+  private workdir(options: TextOptions<ClaudeCodeTextProviderOptions>): string {
+    return (
+      options.modelOptions?.cwd ?? this.adapterConfig.cwd ?? DEFAULT_WORKDIR
+    )
+  }
+
+  /** Build the `claude` command line (prompt goes via stdin, not argv). */
+  private buildCommand(
+    options: TextOptions<ClaudeCodeTextProviderOptions>,
+    resume: string | undefined,
+    policyFlags: ClaudePolicyFlags,
+    mcpConfigPath: string | undefined,
+    permissionPromptTool: string | undefined,
+  ): string {
+    const config = this.adapterConfig
+    const modelOptions = options.modelOptions
+    const exe = config.claudeExecutable ?? 'claude'
+
+    const args: Array<string> = [
+      '-p',
+      '--output-format',
+      'stream-json',
+      '--verbose',
+      '--model',
+      q(this.model),
+    ]
+
+    if (config.streamPartials !== false) args.push('--include-partial-messages')
+    if (resume !== undefined) args.push('--resume', q(resume))
+
+    // Precedence: per-call modelOptions > adapter config > policy > sandbox default.
+    const permissionMode =
+      modelOptions?.permissionMode ??
+      config.permissionMode ??
+      policyFlags.permissionMode ??
+      'bypassPermissions'
+    args.push('--permission-mode', q(permissionMode))
+
+    const maxTurns = modelOptions?.maxTurns ?? config.maxTurns
+    if (maxTurns !== undefined) args.push('--max-turns', String(maxTurns))
+
+    for (const dir of config.addDirs ?? []) args.push('--add-dir', q(dir))
+
+    const allowedTools = [
+      ...(modelOptions?.allowedTools ?? config.allowedTools ?? []),
+      ...policyFlags.allowedTools,
+    ]
+    if (allowedTools.length > 0) {
+      args.push('--allowedTools', q([...new Set(allowedTools)].join(',')))
+    }
+    const disallowedTools = [
+      ...(modelOptions?.disallowedTools ?? config.disallowedTools ?? []),
+      ...policyFlags.disallowedTools,
+    ]
+    if (disallowedTools.length > 0) {
+      args.push('--disallowedTools', q([...new Set(disallowedTools)].join(',')))
+    }
+
+    const systemPrompts = normalizeSystemPrompts(options.systemPrompts)
+      .map((prompt) => prompt.content)
+      .filter((content) => content.trim() !== '')
+    if (systemPrompts.length > 0) {
+      const joined = systemPrompts.join('\n\n')
+      const flag =
+        config.systemPromptMode === 'replace'
+          ? '--system-prompt'
+          : '--append-system-prompt'
+      args.push(flag, q(joined))
+    }
+
+    if (mcpConfigPath !== undefined) args.push('--mcp-config', q(mcpConfigPath))
+    if (permissionPromptTool !== undefined) {
+      args.push('--permission-prompt-tool', q(permissionPromptTool))
+    }
+
+    return `${exe} ${args.join(' ')}`
+  }
+
+  /**
+   * Build the permission-prompt resolver the host MCP bridge exposes to claude
+   * (`--permission-prompt-tool`). Maps claude's permission request onto the
+   * sandbox policy + client approvals; on an `ask` action with no decision yet,
+   * records an approval-requested event and denies (the client re-runs to grant).
+   */
+  private buildPermissionResolver(
+    policy: SandboxPolicy | undefined,
+    approvals: ReadonlyMap<string, boolean> | undefined,
+    scripts: Record<string, string> | undefined,
+    sink: Array<StreamChunk>,
+    threadId: string,
+    runId: string,
+  ): (input: { tool_name?: string; input?: unknown }) => PermissionToolResult {
+    const writeTools = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit'])
+    const networkTools = new Set(['WebFetch', 'WebSearch'])
+    return (request) => {
+      const toolName = request.tool_name ?? 'tool'
+      const cmdInput = request.input
+      const command =
+        toolName === 'Bash' &&
+        cmdInput !== null &&
+        typeof cmdInput === 'object' &&
+        'command' in cmdInput &&
+        typeof (cmdInput as { command?: unknown }).command === 'string'
+          ? (cmdInput as { command: string }).command
+          : undefined
+      const capability = writeTools.has(toolName)
+        ? 'fileWrite'
+        : networkTools.has(toolName)
+          ? 'network'
+          : undefined
+      const id = approvalId({
+        provider: 'claude-code',
+        kind: command !== undefined ? 'command' : (capability ?? 'tool'),
+        target: command ?? toolName,
+      })
+      const outcome = resolveApproval({
+        policy,
+        approvals,
+        id,
+        scripts,
+        ...(command !== undefined ? { command } : {}),
+        ...(capability !== undefined ? { capability } : {}),
+      })
+      if (outcome.needsApproval) {
+        sink.push(
+          buildApprovalRequestedEvent({
+            approvalId: id,
+            title: `Approve ${toolName}${command !== undefined ? `: ${command}` : ''}`,
+            threadId,
+            runId,
+            detail: { provider: 'claude-code', toolName },
+          }),
+        )
+        return {
+          behavior: 'deny',
+          message:
+            'Awaiting client approval. Approve in the UI and re-run to continue.',
+        }
+      }
+      return outcome.decision === 'allow'
+        ? { behavior: 'allow' }
+        : { behavior: 'deny', message: 'Denied by sandbox policy.' }
+    }
+  }
+
+  async *chatStream(
+    options: TextOptions<ClaudeCodeTextProviderOptions>,
+  ): AsyncIterable<StreamChunk> {
+    const { logger } = options
+    let bridge: HostToolBridge | undefined
+    let channel: BridgeEventChannel | undefined
+    const approvalRequests: Array<StreamChunk> = []
+    // Temp files written for the run (bridge MCP config, redirected prompt) that
+    // carry the bearer token / prompt; removed in `finally` so they don't linger
+    // in the sandbox after the run.
+    let cleanupSandbox: SandboxHandle | undefined
+    const tempFiles: Array<string> = []
+    try {
+      const sandbox = this.sandboxFrom(options)
+      cleanupSandbox = sandbox
+      const cwd = this.workdir(options)
+      const runId = options.runId ?? this.generateId()
+      const threadId = options.threadId ?? this.generateId()
+      // Surfaces custom events from bridged tools (e.g. code mode console logs)
+      // on this run's live output stream.
+      channel = createBridgeEventChannel({ model: this.model, threadId, runId })
+
+      // Idempotently project workspace skills/plugins/MCP into the sandbox in
+      // claude's native format (guarded by the projection marker file).
+      const projection = options.capabilities
+        ? getWorkspaceProjection(options.capabilities, { optional: true })
+        : undefined
+      if (projection) await projectClaudeWorkspace(sandbox, projection)
+
+      const policy = options.capabilities
+        ? getSandboxPolicy(options.capabilities, { optional: true })
+        : undefined
+
+      // A permission-prompt tool gates the agent's native tools when a policy
+      // can `ask`/`deny` (interactive approvals).
+      const permission =
+        policy !== undefined
+          ? {
+              toolName: 'approval_prompt',
+              resolve: this.buildPermissionResolver(
+                policy,
+                options.approvals,
+                projection?.scripts,
+                approvalRequests,
+                threadId,
+                runId,
+              ),
+            }
+          : undefined
+
+      // Bridge chat()-provided server tools (and/or the permission tool) into
+      // the sandbox over MCP.
+      const hasTools = options.tools !== undefined && options.tools.length > 0
+      if (hasTools || permission !== undefined) {
+        const provisioner =
+          (options.capabilities
+            ? getToolBridgeProvisioner(options.capabilities, { optional: true })
+            : undefined) ?? nodeHttpBridgeProvisioner
+        bridge = await provisioner.provision(options.tools ?? [], {
+          provider: sandbox.provider,
+          context: options.context,
+          emitCustomEvent: channel.emitCustomEvent,
+          ...(permission !== undefined ? { permission } : {}),
+          ...(options.abortController?.signal
+            ? { signal: options.abortController.signal }
+            : {}),
+        })
+      }
+
+      const { prompt, resume } = buildPrompt(
+        options.messages,
+        options.modelOptions?.sessionId,
+      )
+      // The bridge MCP config carries the per-run bearer token. Write it to a
+      // file and pass claude the PATH, so the token never appears in argv (where
+      // any process in the sandbox could read it via `ps` / `/proc/<pid>/cmdline`).
+      let mcpConfigArg: string | undefined
+      if (bridge) {
+        // Pass claude a path RELATIVE to its cwd (the real workdir the handle
+        // runs the process in). An absolute VIRTUAL path like `/workspace/…` is
+        // wrong wherever claude runs outside a sandbox that literally uses
+        // `/workspace` — e.g. local-process on Windows, where git-bash resolves
+        // `/workspace` to `C:\Program Files\Git\workspace` and the file is "not
+        // found". The bare filename resolves correctly on every provider.
+        const mcpConfigFile = `.tanstack-mcp-bridge-${runId}.json`
+        const mcpConfigPath = `${cwd}/${mcpConfigFile}`
+        await sandbox.fs.write(mcpConfigPath, bridgeToMcpConfig(bridge))
+        tempFiles.push(mcpConfigPath)
+        mcpConfigArg = mcpConfigFile
+      }
+      const command = this.buildCommand(
+        options,
+        resume,
+        mapPolicyToClaudeFlags(policy),
+        mcpConfigArg,
+        bridge && permission
+          ? `mcp__${bridge.name}__${permission.toolName}`
+          : undefined,
+      )
+
+      // Deliver the prompt. The default feeds it over stdin (keeps it out of
+      // argv). Providers without a writable host→process stdin (e.g. Cloudflare)
+      // can't accept that write, so write the prompt to a file and redirect the
+      // CLI's stdin from it in-shell (`claude -p … < file`) — still out of argv.
+      let runCommand = command
+      let stdinInput: string | undefined = prompt
+      if (sandbox.capabilities.writableStdin === false) {
+        const promptPath = `/tmp/tanstack-claude-prompt-${runId}`
+        await sandbox.fs.write(promptPath, prompt)
+        tempFiles.push(promptPath)
+        runCommand = `${command} < ${q(promptPath)}`
+        stdinInput = undefined
+      }
+
+      logger.request(
+        `activity=chat provider=claude-code model=${this.model} sandbox=${sandbox.provider} messages=${options.messages.length} resume=${resume ?? 'none'}`,
+        { provider: 'claude-code', model: this.model },
+      )
+
+      const rawEvents = spawnNdjson(sandbox, runCommand, {
+        cwd,
+        ...(stdinInput !== undefined ? { input: stdinInput } : {}),
+        // claude maps `bypassPermissions` to `--dangerously-skip-permissions`,
+        // which it refuses to run as root. Sandbox containers routinely run as
+        // root (Docker / Cloudflare), so set `IS_SANDBOX=1` — claude's
+        // documented escape hatch for skip-permissions in an isolated
+        // environment — merged over the sandbox env (a caller-provided value
+        // wins). Safe to set unconditionally; it is a no-op for stricter modes.
+        env: { IS_SANDBOX: '1', ...this.adapterConfig.env },
+        ...(options.abortController?.signal
+          ? { signal: options.abortController.signal }
+          : options.request?.signal
+            ? { signal: options.request.signal }
+            : {}),
+        onNonJsonLine: (line) =>
+          logger.provider(`provider=claude-code non-json line: ${line}`, {
+            chunk: line,
+          }),
+      })
+
+      async function* asMessages(): AsyncIterable<AgentSdkMessage> {
+        for await (const event of rawEvents) yield event as AgentSdkMessage
+      }
+
+      yield* mergeChunkStreams(
+        translateSdkStream(asMessages(), {
+          model: this.model,
+          runId,
+          threadId,
+          ...(options.parentRunId !== undefined && {
+            parentRunId: options.parentRunId,
+          }),
+          genId: () => this.generateId(),
+          onSdkMessage: (message) =>
+            logger.provider(`provider=claude-code type=${message.type}`, {
+              chunk: message,
+            }),
+        }),
+        channel.stream,
+      )
+
+      // Surface the working-tree diff so UIs can render what the agent changed.
+      if (this.adapterConfig.emitDiff !== false) {
+        try {
+          const diff = await sandbox.process.exec(`git -C ${q(cwd)} diff`, {
+            cwd,
+          })
+          if (diff.exitCode === 0 && diff.stdout.trim() !== '') {
+            yield {
+              type: EventType.CUSTOM,
+              name: 'file.changed',
+              value: { path: '.', diff: diff.stdout },
+              timestamp: Date.now(),
+              threadId,
+              runId,
+            }
+          }
+        } catch {
+          // not a git repo / git unavailable — skip the diff event
+        }
+      }
+
+      // Surface any pending approval requests (policy `ask` actions awaiting a
+      // client decision); the client approves and re-runs to continue.
+      for (const event of approvalRequests) yield event
+    } catch (error: unknown) {
+      const err = error as Error & { code?: string }
+      const rawEvent = toRunErrorRawEvent(error)
+      logger.errors('claude-code.chatStream fatal', {
+        error,
+        source: 'claude-code.chatStream',
+      })
+      yield {
+        type: EventType.RUN_ERROR,
+        model: options.model,
+        timestamp: Date.now(),
+        message: err.message || 'Unknown error occurred',
+        ...(err.code !== undefined && { code: err.code }),
+        ...(rawEvent !== undefined && { rawEvent }),
+        error: {
+          message: err.message || 'Unknown error occurred',
+          ...(err.code !== undefined && { code: err.code }),
+        },
+      }
+    } finally {
+      channel?.close()
+      if (bridge) await bridge.close()
+      // Remove the per-run token/prompt files. Best-effort: a cleanup failure
+      // must not mask the run's own outcome.
+      if (cleanupSandbox) {
+        for (const path of tempFiles) {
+          try {
+            await cleanupSandbox.fs.remove(path)
+          } catch {
+            // file already gone / sandbox torn down — nothing to clean up
+          }
+        }
+      }
+    }
+  }
+
+  structuredOutput(
+    _options: StructuredOutputOptions<ClaudeCodeTextProviderOptions>,
+  ): Promise<StructuredOutputResult<unknown>> {
+    return Promise.reject(
+      new Error(
+        'Structured output is not yet supported by the in-sandbox Claude Code adapter. ' +
+          'Use a model adapter (e.g. anthropic) for structured output, or omit outputSchema.',
+      ),
+    )
+  }
+}
+
+/**
+ * Creates a Claude Code harness adapter that runs **inside a sandbox**.
+ *
+ * Unlike HTTP provider adapters, this is a *harness* adapter: it spawns the
+ * `claude` CLI inside the sandbox provided by `withSandbox(...)` (the adapter
+ * declares `requires: [SandboxCapability]`), streams its `stream-json` stdout
+ * back as AG-UI events, and lets Claude Code run its own agent loop and native
+ * tools (Bash, file edits, search, …) against the sandbox workspace. The
+ * sandbox image must provide the `claude` executable and `ANTHROPIC_API_KEY`
+ * in its environment (e.g. via `workspace.secrets`). The session id is
+ * surfaced via a CUSTOM `claude-code.session-id` event so follow-up calls can
+ * resume through `modelOptions.sessionId`.
+ */
+export function claudeCodeText<TModel extends ClaudeCodeModel>(
+  model: TModel,
+  config: ClaudeCodeTextConfig = {},
+): ClaudeCodeTextAdapter<TModel> {
+  return new ClaudeCodeTextAdapter(config, model)
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export { ClaudeCodeTextAdapter, claudeCodeText } from './adapters/text'
+export type {
+  ClaudeCodeTextConfig,
+  ClaudeCodePermissionMode,
+} from './adapters/text'
+export type { ClaudeCodeTextProviderOptions } from './provider-options'
+export { CLAUDE_CODE_MODELS } from './model-meta'
+export type { ClaudeCodeModel, KnownClaudeCodeModel } from './model-meta'
+export {
+  SESSION_ID_EVENT,
+  BRIDGED_MCP_SERVER_NAME,
+  translateSdkStream,
+  stripMcpPrefix,
+} from './stream/translate'
+export type {
+  ClaudeCodeProviderUsageDetails,
+  TranslateContext,
+} from './stream/translate'
+export type { AgentSdkMessage } from './stream/sdk-types'
+export { buildPrompt } from './messages/prompt'
+export type { BuiltPrompt } from './messages/prompt'

package/src/messages/prompt.ts

@@ -0,0 +1,68 @@
+import type { ModelMessage } from '@tanstack/ai'
+
+export interface BuiltPrompt {
+  prompt: string
+  /** Claude Code session id to resume, when the caller threaded one through. */
+  resume?: string
+}
+
+function extractText(content: ModelMessage['content']): string {
+  if (content === null) return ''
+  if (typeof content === 'string') return content
+  return content
+    .map((part) =>
+      part.type === 'text' && typeof part.content === 'string'
+        ? part.content
+        : '',
+    )
+    .join('')
+}
+
+/**
+ * Convert TanStack chat history into the Agent SDK's `{ prompt, resume }`
+ * inputs.
+ *
+ * With a `sessionId`, the harness already holds the conversation context, so
+ * only the trailing user message is sent and the session is resumed. Without
+ * one, prior turns are flattened into a plain-text transcript preamble (tool
+ * messages and tool-call-only assistant turns are harness-internal noise and
+ * are skipped; prompts are text-only in v1).
+ */
+export function buildPrompt(
+  messages: Array<ModelMessage>,
+  sessionId: string | undefined,
+): BuiltPrompt {
+  const lastMessage = messages.at(-1)
+  const lastUserText =
+    lastMessage?.role === 'user' ? extractText(lastMessage.content).trim() : ''
+
+  if (!lastUserText) {
+    throw new Error(
+      'Claude Code adapter requires a trailing user message with text content.',
+    )
+  }
+
+  if (sessionId !== undefined) {
+    return { prompt: lastUserText, resume: sessionId }
+  }
+
+  const priorTurns = messages
+    .slice(0, -1)
+    .filter(
+      (message) =>
+        (message.role === 'user' || message.role === 'assistant') &&
+        extractText(message.content).trim() !== '',
+    )
+    .map(
+      (message) =>
+        `${message.role === 'user' ? 'User' : 'Assistant'}: ${extractText(message.content).trim()}`,
+    )
+
+  if (priorTurns.length === 0) {
+    return { prompt: lastUserText }
+  }
+
+  return {
+    prompt: `Previous conversation:\n${priorTurns.join('\n')}\n\n${lastUserText}`,
+  }
+}

package/src/model-meta.ts

@@ -0,0 +1,21 @@
+/**
+ * Models known to work with Claude Code. The harness accepts any Anthropic
+ * model id (and the `opus` / `sonnet` / `haiku` aliases resolved by the CLI),
+ * so this list exists for autocomplete — any string is accepted via the
+ * `(string & {})` escape hatch in {@link ClaudeCodeModel}.
+ */
+export const CLAUDE_CODE_MODELS = [
+  'claude-opus-4-8',
+  'claude-opus-4-7',
+  'claude-opus-4-6',
+  'claude-sonnet-4-6',
+  'claude-haiku-4-5',
+  'opus',
+  'sonnet',
+  'haiku',
+] as const
+
+export type KnownClaudeCodeModel = (typeof CLAUDE_CODE_MODELS)[number]
+
+/** Any Claude model id accepted by Claude Code; known ids get autocomplete. */
+export type ClaudeCodeModel = KnownClaudeCodeModel | (string & {})

package/src/provider-options.ts

@@ -0,0 +1,30 @@
+type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'
+
+/**
+ * Per-call provider options for the Claude Code adapter, passed via
+ * `modelOptions` on `chat()`.
+ */
+export interface ClaudeCodeTextProviderOptions {
+  /**
+   * Resume an existing Claude Code session. The adapter emits the session id
+   * of every run via a CUSTOM `claude-code.session-id` stream event; thread
+   * it back here to continue that session (only the latest user message is
+   * sent — the harness already holds the prior context).
+   */
+  sessionId?: string
+  /**
+   * When resuming, fork to a new session id instead of continuing the
+   * original session.
+   */
+  forkSession?: boolean
+  /** Per-call override of the configured max harness turns. */
+  maxTurns?: number
+  /** Per-call override of the configured permission mode. */
+  permissionMode?: PermissionMode
+  /** Per-call override of the allowed built-in tool list. */
+  allowedTools?: Array<string>
+  /** Per-call override of the disallowed built-in tool list. */
+  disallowedTools?: Array<string>
+  /** Per-call override of the harness working directory. */
+  cwd?: string
+}