luca 2.0.0 → 3.0.2

package/src/agi/features/claude-code.ts

@@ -0,0 +1,1584 @@
+// @ts-nocheck
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { type AvailableFeatures } from 'luca/feature'
+import { Feature } from '../feature.js'
+
+declare module 'luca/feature' {
+  interface AvailableFeatures {
+    claudeCode: typeof ClaudeCode
+  }
+}
+
+// --- Stream JSON types from the Claude CLI ---
+
+export interface ClaudeInitEvent {
+  type: 'system'
+  subtype: 'init'
+  session_id: string
+  cwd: string
+  model: string
+  tools: string[]
+  mcp_servers: string[]
+  permissionMode: string
+  claude_code_version: string
+}
+
+export interface ClaudeAssistantMessage {
+  type: 'assistant'
+  message: {
+    id: string
+    model: string
+    role: 'assistant'
+    content: Array<{ type: 'text'; text: string } | { type: 'tool_use'; id: string; name: string; input: any }>
+    stop_reason: string | null
+    usage: {
+      input_tokens: number
+      output_tokens: number
+      cache_read_input_tokens?: number
+      cache_creation_input_tokens?: number
+    }
+  }
+  session_id: string
+  parent_tool_use_id: string | null
+}
+
+export interface ClaudeToolResult {
+  type: 'tool_result'
+  tool_use_id: string
+  content: string
+  session_id: string
+}
+
+export interface ClaudeStreamEvent {
+  type: 'stream_event'
+  event: {
+    type: 'message_start' | 'content_block_start' | 'content_block_delta' | 'content_block_stop' | 'message_delta' | 'message_stop'
+    index?: number
+    delta?: { type: string; text?: string }
+    content_block?: { type: string; text?: string }
+    message?: any
+    usage?: any
+  }
+  session_id: string
+  parent_tool_use_id: string | null
+}
+
+export interface ClaudeResultEvent {
+  type: 'result'
+  subtype: 'success' | 'error'
+  is_error: boolean
+  result: string
+  session_id: string
+  duration_ms: number
+  num_turns: number
+  total_cost_usd: number
+  usage: Record<string, any>
+}
+
+export type ClaudeEvent = ClaudeInitEvent | ClaudeAssistantMessage | ClaudeToolResult | ClaudeStreamEvent | ClaudeResultEvent | { type: string; [key: string]: any }
+
+// --- Session types ---
+
+export interface ClaudeSession {
+  id: string
+  sessionId?: string
+  status: 'idle' | 'running' | 'completed' | 'error'
+  prompt: string
+  result?: string
+  error?: string
+  costUsd: number
+  turns: number
+  messages: ClaudeAssistantMessage[]
+  process?: any
+}
+
+// --- MCP server config types ---
+
+export interface McpStdioServer {
+  type: 'stdio'
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+}
+
+export interface McpHttpServer {
+  type: 'http'
+  url: string
+  headers?: Record<string, string>
+}
+
+export interface McpSseServer {
+  type: 'sse'
+  url: string
+  headers?: Record<string, string>
+}
+
+export type McpServerConfig = McpStdioServer | McpHttpServer | McpSseServer
+
+// --- Feature state and options ---
+
+export const ClaudeCodeStateSchema = FeatureStateSchema.extend({
+  /** Map of session IDs to ClaudeSession objects */
+  sessions: z.record(z.string(), z.any()).describe('Map of session IDs to ClaudeSession objects'),
+  /** List of currently running session IDs */
+  activeSessions: z.array(z.string()).describe('List of currently running session IDs'),
+  /** Whether the Claude CLI binary is available */
+  claudeAvailable: z.boolean().describe('Whether the Claude CLI binary is available'),
+  /** Detected Claude CLI version string */
+  claudeVersion: z.string().optional().describe('Detected Claude CLI version string'),
+})
+
+export const FileLogLevelSchema = z.enum(['verbose', 'normal', 'minimal']).describe(
+  'Log verbosity: verbose=all events including stream deltas, normal=messages+tool calls+results, minimal=init+result/error only'
+)
+
+export type FileLogLevel = z.infer<typeof FileLogLevelSchema>
+
+export const ClaudeCodeOptionsSchema = FeatureOptionsSchema.extend({
+  /** Claude CLI session ID to resume by default. When set, subsequent run()/start() calls will resume this session unless overridden. */
+  session: z.string().optional().describe('Claude CLI session ID to resume by default'),
+  /** Path to the claude CLI binary. Defaults to 'claude'. */
+  claudePath: z.string().optional().describe('Path to the claude CLI binary'),
+  /** Default model to use for sessions. */
+  model: z.string().optional().describe('Default model to use for sessions'),
+  /** Default working directory for sessions. */
+  cwd: z.string().optional().describe('Default working directory for sessions'),
+  /** Default system prompt prepended to all sessions. */
+  systemPrompt: z.string().optional().describe('Default system prompt prepended to all sessions'),
+  /** Default append system prompt for all sessions. */
+  appendSystemPrompt: z.string().optional().describe('Default append system prompt for all sessions'),
+  /** Default permission mode. */
+  permissionMode: z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan', 'dontAsk']).optional().describe('Default permission mode for Claude CLI sessions'),
+  /** Default allowed tools. */
+  allowedTools: z.array(z.string()).optional().describe('Default allowed tools for sessions'),
+  /** Default disallowed tools. */
+  disallowedTools: z.array(z.string()).optional().describe('Default disallowed tools for sessions'),
+  /** Whether to stream partial messages (token-by-token). Defaults to false. */
+  streaming: z.boolean().optional().describe('Whether to stream partial messages token-by-token'),
+  /** MCP config file paths to pass to sessions. */
+  mcpConfig: z.array(z.string()).optional().describe('MCP config file paths to pass to sessions'),
+  /** MCP servers to inject into sessions, keyed by server name. Automatically written to a temp config file. */
+  mcpServers: z.record(z.string(), z.any()).optional().describe('MCP server configs keyed by name, injected into sessions via temp config file'),
+  /** Path to write a parseable NDJSON session log file. Each line is a JSON object with timestamp, sessionId, event type, and event data. */
+  fileLogPath: z.string().optional().describe('Path to write a parseable NDJSON session log file'),
+  /** Verbosity level for file logging. Defaults to "normal". */
+  fileLogLevel: FileLogLevelSchema.optional().describe('Verbosity level for file logging. Defaults to "normal"'),
+  /** Default effort level for Claude reasoning. */
+  effort: z.enum(['low', 'medium', 'high']).optional().describe('Default effort level for Claude reasoning'),
+  /** Maximum cost budget in USD per session. */
+  maxBudgetUsd: z.number().optional().describe('Maximum cost budget in USD per session'),
+  /** Fallback model when the primary model is unavailable. */
+  fallbackModel: z.string().optional().describe('Fallback model when the primary model is unavailable'),
+  /** Default agent to use. */
+  agent: z.string().optional().describe('Default agent to use'),
+  /** Disable session persistence across runs. */
+  noSessionPersistence: z.boolean().optional().describe('Disable session persistence across runs'),
+  /** Default tools to make available. */
+  tools: z.array(z.string()).optional().describe('Default tools to make available'),
+  /** Require strict MCP config validation. */
+  strictMcpConfig: z.boolean().optional().describe('Require strict MCP config validation'),
+  /** Path to a custom settings file. */
+  settingsFile: z.string().optional().describe('Path to a custom settings file'),
+  /** Directories containing Claude Code skills (SKILL.md files) to load into sessions. Passed as --add-dir. */
+  skillsFolders: z.array(z.string()).optional().describe('Directories containing Claude Code skills to load into sessions'),
+  /** Launch Claude Code with a Chrome browser tool. */
+  chrome: z.boolean().optional().describe('Launch Claude Code with a Chrome browser tool'),
+  /** Base URL for the Anthropic API. Injected as ANTHROPIC_BASE_URL env var. */
+  baseURL: z.string().optional().describe('Base URL for the Anthropic API, injected as ANTHROPIC_BASE_URL'),
+  /** Auth token for the Anthropic API. Injected as ANTHROPIC_AUTH_TOKEN env var. */
+  authToken: z.string().optional().describe('Auth token for the Anthropic API, injected as ANTHROPIC_AUTH_TOKEN'),
+  /** Use local models. Sets baseURL and model from LOCAL_CHAT_ENDPOINT and LOCAL_CODER_MODEL env vars. */
+  local: z.boolean().optional().describe('Use local models, sets baseURL to LOCAL_CHAT_ENDPOINT and model to LOCAL_CODER_MODEL'),
+})
+
+export const ClaudeCodeEventsSchema = FeatureEventsSchema.extend({
+  'session:start': z.tuple([z.object({ sessionId: z.string(), prompt: z.string() })]).describe('Fired when a new Claude Code session is spawned'),
+  'session:init': z.tuple([z.object({ sessionId: z.string(), init: z.any() })]).describe('Fired when the CLI emits its init system event'),
+  'session:event': z.tuple([z.object({ sessionId: z.string(), event: z.any() })]).describe('Fired for every parsed JSON event from the CLI stream'),
+  'session:stream': z.tuple([z.object({ sessionId: z.string(), streamEvent: z.any() })]).describe('Fired for stream_event type events from the CLI'),
+  'session:delta': z.tuple([z.object({ sessionId: z.string(), text: z.string(), role: z.string() })]).describe('Fired for each text delta from an assistant message'),
+  'session:message': z.tuple([z.object({ sessionId: z.string(), message: z.any() })]).describe('Fired when a complete assistant message is received'),
+  'session:result': z.tuple([z.object({ sessionId: z.string(), result: z.string() })]).describe('Fired when a session completes with a final result'),
+  'session:error': z.tuple([z.object({ sessionId: z.string(), error: z.any(), exitCode: z.number().optional() })]).describe('Fired when a session encounters an error'),
+  'session:abort': z.tuple([z.object({ sessionId: z.string() })]).describe('Fired when a session is aborted by the user'),
+  'session:warning': z.tuple([z.object({ sessionId: z.string(), message: z.string() })]).describe('Fired when the log reader encounters a warning'),
+  'session:log-error': z.tuple([z.object({ sessionId: z.string(), error: z.any() })]).describe('Fired when the log reader encounters an error'),
+  'session:parse-error': z.tuple([z.object({ sessionId: z.string(), line: z.string() })]).describe('Fired when a JSON line from the CLI cannot be parsed'),
+}).describe('ClaudeCode events')
+
+export type ClaudeCodeState = z.infer<typeof ClaudeCodeStateSchema>
+export type ClaudeCodeOptions = z.infer<typeof ClaudeCodeOptionsSchema>
+
+export interface RunOptions {
+  /** Override model for this session. */
+  model?: string
+  /** Override working directory. */
+  cwd?: string
+  /** System prompt for this session. */
+  systemPrompt?: string
+  /** Append system prompt for this session. */
+  appendSystemPrompt?: string
+  /** Permission mode override. */
+  permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk'
+  /** Allowed tools override. */
+  allowedTools?: string[]
+  /** Disallowed tools override. */
+  disallowedTools?: string[]
+  /** Whether to stream partial messages. */
+  streaming?: boolean
+  /** Resume a previous session by ID. */
+  resumeSessionId?: string
+  /** Continue the most recent conversation. */
+  continue?: boolean
+  /** Additional directories to allow tool access to. */
+  addDirs?: string[]
+  /** Directories containing Claude Code skills (SKILL.md files) to load into sessions. Merged with addDirs as --add-dir. */
+  skillsFolders?: string[]
+  /** MCP config file paths. */
+  mcpConfig?: string[]
+  /** MCP servers to inject, keyed by server name. */
+  mcpServers?: Record<string, McpServerConfig>
+  /** Skip all permission checks (only for sandboxed environments). */
+  dangerouslySkipPermissions?: boolean
+  /** Additional arbitrary CLI flags. */
+  extraArgs?: string[]
+  /** Path to write a parseable NDJSON session log file. Overrides feature-level fileLogPath. */
+  fileLogPath?: string
+  /** Verbosity level for file logging. Overrides feature-level fileLogLevel. */
+  fileLogLevel?: FileLogLevel
+  /** Effort level for Claude reasoning. */
+  effort?: 'low' | 'medium' | 'high'
+  /** Maximum cost budget in USD. */
+  maxBudgetUsd?: number
+  /** Fallback model when the primary is unavailable. */
+  fallbackModel?: string
+  /** JSON schema for structured output validation. */
+  jsonSchema?: string | object
+  /** Agent to use for this session. */
+  agent?: string
+  /** Resume or fork a specific Claude session by ID. */
+  sessionId?: string
+  /** Disable session persistence for this run. */
+  noSessionPersistence?: boolean
+  /** Fork from an existing session instead of resuming. */
+  forkSession?: boolean
+  /** Tools to make available. */
+  tools?: string[]
+  /** Require strict MCP config validation. */
+  strictMcpConfig?: boolean
+  /** Enable debug output. Pass a string for specific debug channels, or true for all. */
+  debug?: string | boolean
+  /** Path to write debug output to a file. */
+  debugFile?: string
+  /** Path to a custom settings file. */
+  settingsFile?: string
+  /** Launch Claude Code with a Chrome browser tool. */
+  chrome?: boolean
+  /** Base URL for the Anthropic API. Injected as ANTHROPIC_BASE_URL in the subprocess env. */
+  baseURL?: string
+  /** Auth token for the Anthropic API. Injected as ANTHROPIC_AUTH_TOKEN in the subprocess env. */
+  authToken?: string
+  /** Use local models. Sets baseURL to LOCAL_CHAT_ENDPOINT (or http://localhost:1234) and model to LOCAL_CODER_MODEL (or qwen/qwen3.6-27b). */
+  local?: boolean
+}
+
+/**
+ * Claude Code CLI wrapper feature. Spawns and manages Claude Code sessions
+ * as subprocesses, streaming structured JSON events back through the
+ * container's event system.
+ *
+ * Sessions are long-lived: each call to `run()` spawns a `claude -p` process
+ * with `--output-format stream-json`, parses NDJSON from stdout line-by-line,
+ * and emits typed events on the feature's event bus.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const cc = container.feature('claudeCode')
+ *
+ * // Listen for events
+ * cc.on('session:delta', ({ sessionId, text }) => process.stdout.write(text))
+ * cc.on('session:result', ({ sessionId, result }) => console.log('Done:', result))
+ *
+ * // Run a prompt
+ * const session = await cc.run('Explain the architecture of this project')
+ * console.log(session.result)
+ * ```
+ */
+export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
+  static override stateSchema = ClaudeCodeStateSchema
+  static override optionsSchema = ClaudeCodeOptionsSchema
+  static override eventsSchema = ClaudeCodeEventsSchema
+  static override shortcut = 'features.claudeCode' as const
+  static override envVars = ['TMPDIR']
+
+  static { Feature.register(this, 'claudeCode') }
+
+  override get initialState(): ClaudeCodeState {
+    return {
+      ...super.initialState,
+      sessions: {},
+      activeSessions: [],
+      claudeAvailable: false
+    }
+  }
+
+  /**
+   * Resolve the path to the claude CLI binary.
+   *
+   * @returns {string} The path to the claude binary
+   */
+  private _resolvedClaudePath: string | null = null
+
+  get claudePath(): string {
+    if (this.options.claudePath) return this.options.claudePath
+    if (this._resolvedClaudePath) return this._resolvedClaudePath
+    try {
+      this._resolvedClaudePath = this.container.feature('proc').resolveRealPath('claude')
+    } catch {
+      this._resolvedClaudePath = 'claude'
+    }
+    return this._resolvedClaudePath
+  }
+
+  /**
+   * Parsed semver components from the detected CLI version, or undefined if not yet checked.
+   *
+   * @returns {{ major: number; minor: number; patch: number } | undefined} Parsed version
+   */
+  get parsedVersion(): { major: number; minor: number; patch: number } | undefined {
+    const ver = this.state.current.claudeVersion
+    if (!ver) return undefined
+    const match = ver.match(/^(\d+)\.(\d+)\.(\d+)/)
+    if (!match) return undefined
+    return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10), patch: parseInt(match[3], 10) }
+  }
+
+  /**
+   * Assert that the detected CLI version meets a minimum major.minor requirement.
+   * Throws if the CLI version is below the specified minimum.
+   *
+   * @param {number} major - Minimum major version
+   * @param {number} minor - Minimum minor version
+   */
+  assertMinVersion(major: number, minor: number): void {
+    const v = this.parsedVersion
+    if (!v) throw new Error('Claude CLI version not detected. Call checkAvailability() first.')
+    if (v.major < major || (v.major === major && v.minor < minor)) {
+      throw new Error(`Claude CLI ${this.state.current.claudeVersion} is below minimum ${major}.${minor}`)
+    }
+  }
+
+  /**
+   * Check if the Claude CLI is available and capture its version.
+   *
+   * @returns {Promise<boolean>} Whether the CLI is available
+   *
+   * @example
+   * ```typescript
+   * const available = await cc.checkAvailability()
+   * if (!available) throw new Error('Claude CLI not found')
+   * ```
+   */
+  async checkAvailability(): Promise<boolean> {
+    try {
+      const proc = this.container.feature('proc')
+      const result = await proc.spawnAndCapture(this.claudePath, ['--version'])
+      const stdout = result.stdout
+      const exitCode = result.exitCode
+
+      if (exitCode === 0) {
+        const version = stdout.trim()
+        this.setState({ claudeAvailable: true, claudeVersion: version })
+
+        const v = this.parsedVersion
+        if (v && (v.major < 2 || (v.major === 2 && v.minor < 1))) {
+          this.emit('session:warning', {
+            message: `Claude CLI ${version} is below minimum 2.1. Some features may not work.`
+          })
+        }
+
+        return true
+      }
+
+      this.setState({ claudeAvailable: false })
+      return false
+    } catch {
+      this.setState({ claudeAvailable: false })
+      return false
+    }
+  }
+
+  /** Tracks temp MCP config files created for cleanup */
+  private mcpTempFiles: string[] = []
+
+  /** Tracks active file log paths per session */
+  private sessionLogPaths: Map<string, { path: string; level: FileLogLevel }> = new Map()
+
+  /**
+   * Resolve the file log path for a session, checking per-session options then feature-level defaults.
+   *
+   * @param {RunOptions} options - Per-session options
+   * @returns {{ path: string; level: FileLogLevel } | undefined} Log config if logging is enabled
+   */
+  private resolveFileLog(options: RunOptions = {}): { path: string; level: FileLogLevel } | undefined {
+    const path = options.fileLogPath ?? this.options.fileLogPath
+    if (!path) return undefined
+    const level = options.fileLogLevel ?? this.options.fileLogLevel ?? 'normal'
+    return { path, level }
+  }
+
+  /**
+   * Write a log entry to the session's NDJSON log file.
+   * Each line is a self-contained JSON object with timestamp, sessionId, event type, and data.
+   *
+   * @param {string} sessionId - The local session ID
+   * @param {string} type - Event type label (e.g. 'session:init', 'session:message')
+   * @param {any} data - Event payload
+   */
+  private async writeLogEntry(sessionId: string, type: string, data: any): Promise<void> {
+    const logConfig = this.sessionLogPaths.get(sessionId)
+    if (!logConfig) return
+
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      session: sessionId,
+      type,
+      data
+    }) + '\n'
+
+    try {
+      await this.container.feature('fs').appendFileAsync(logConfig.path, entry)
+    } catch (err) {
+      this.emit('session:log-error', { sessionId, error: err })
+    }
+  }
+
+  /**
+   * Determine if an event should be logged based on the configured log level.
+   *
+   * - verbose: all events (stream deltas, partial messages, everything)
+   * - normal: assistant messages, tool results, init, result, errors (no stream_event)
+   * - minimal: init and result/error only
+   *
+   * @param {string} eventType - The Claude event type
+   * @param {FileLogLevel} level - The configured log level
+   * @returns {boolean} Whether to log this event
+   */
+  private shouldLog(eventType: string, level: FileLogLevel): boolean {
+    switch (level) {
+      case 'verbose':
+        return true
+      case 'normal':
+        return eventType !== 'stream_event'
+      case 'minimal':
+        return eventType === 'system' || eventType === 'result'
+      default:
+        return true
+    }
+  }
+
+  /**
+   * Write an MCP server config map to a temp file suitable for `--mcp-config`.
+   *
+   * @param {Record<string, McpServerConfig>} servers - Server configs keyed by name
+   * @returns {Promise<string>} Path to the generated temp config file
+   *
+   * @example
+   * ```typescript
+   * const configPath = await cc.writeMcpConfig({
+   *   'my-api': { type: 'http', url: 'https://api.example.com/mcp' },
+   *   'local-tool': { type: 'stdio', command: 'bun', args: ['run', 'server.ts'] }
+   * })
+   * ```
+   */
+  async writeMcpConfig(servers: Record<string, McpServerConfig>): Promise<string> {
+    const config = { mcpServers: servers }
+    const tmpDir = process.env.TMPDIR || '/tmp'
+    const tmpPath = `${tmpDir}/luca-mcp-${crypto.randomUUID()}.json`
+    await this.container.feature('fs').writeFileAsync(tmpPath, JSON.stringify(config, null, 2))
+    this.mcpTempFiles.push(tmpPath)
+    return tmpPath
+  }
+
+  /**
+   * Build the argument array for a claude CLI invocation.
+   *
+   * @param {string} prompt - The prompt text
+   * @param {RunOptions} options - Session options
+   * @returns {Promise<string[]>} CLI arguments
+   */
+  private async buildArgs(prompt: string, options: RunOptions = {}): Promise<string[]> {
+    const args: string[] = ['-p', '--output-format', 'stream-json', '--verbose']
+
+    const streaming = options.streaming ?? this.options.streaming ?? false
+    if (streaming) {
+      args.push('--include-partial-messages')
+    }
+
+    const isLocal = options.local ?? this.options.local
+    const model = options.model ?? this.options.model ?? (isLocal ? (process.env.LOCAL_CODER_MODEL || 'qwen/qwen3.6-27b') : undefined)
+    if (model) args.push('--model', model)
+
+    const systemPrompt = options.systemPrompt ?? this.options.systemPrompt
+    if (systemPrompt) args.push('--system-prompt', systemPrompt)
+
+    const appendSystemPrompt = options.appendSystemPrompt ?? this.options.appendSystemPrompt
+    if (appendSystemPrompt) args.push('--append-system-prompt', appendSystemPrompt)
+
+    const permissionMode = options.permissionMode ?? this.options.permissionMode
+    if (permissionMode) args.push('--permission-mode', permissionMode)
+
+    const allowedTools = options.allowedTools ?? this.options.allowedTools
+    if (allowedTools?.length) args.push('--allowed-tools', ...allowedTools)
+
+    const disallowedTools = options.disallowedTools ?? this.options.disallowedTools
+    if (disallowedTools?.length) args.push('--disallowed-tools', ...disallowedTools)
+
+    // Collect all --mcp-config paths
+    const configPaths: string[] = []
+
+    const mcpConfig = options.mcpConfig ?? this.options.mcpConfig
+    if (mcpConfig?.length) configPaths.push(...mcpConfig)
+
+    // Merge mcpServers from feature-level defaults and per-session overrides
+    const defaultServers = this.options.mcpServers as Record<string, McpServerConfig> | undefined
+    const sessionServers = options.mcpServers
+    const mergedServers = { ...defaultServers, ...sessionServers }
+
+    if (Object.keys(mergedServers).length > 0) {
+      const tmpPath = await this.writeMcpConfig(mergedServers)
+      configPaths.push(tmpPath)
+    }
+
+    if (configPaths.length) args.push('--mcp-config', ...configPaths)
+
+    const resumeSessionId = options.resumeSessionId ?? (options.sessionId ? undefined : this.options.session)
+    if (resumeSessionId) args.push('--resume', resumeSessionId)
+    if (options.continue) args.push('--continue')
+    if (options.dangerouslySkipPermissions) args.push('--dangerously-skip-permissions')
+
+    // Merge addDirs and skillsFolders (both feature-level and per-session) into --add-dir
+    const addDirs: string[] = [
+      ...(options.addDirs ?? []),
+      ...(options.skillsFolders ?? []),
+      ...(this.options.skillsFolders ?? []),
+    ]
+    if (addDirs.length) {
+      args.push('--add-dir', ...addDirs)
+    }
+
+    // --- New v2.1 flags ---
+    const effort = options.effort ?? this.options.effort
+    if (effort) args.push('--effort', effort)
+
+    const maxBudgetUsd = options.maxBudgetUsd ?? this.options.maxBudgetUsd
+    if (maxBudgetUsd != null) args.push('--max-budget-usd', String(maxBudgetUsd))
+
+    const fallbackModel = options.fallbackModel ?? this.options.fallbackModel
+    if (fallbackModel) args.push('--fallback-model', fallbackModel)
+
+    const agent = options.agent ?? this.options.agent
+    if (agent) args.push('--agent', agent)
+
+    const noSessionPersistence = options.noSessionPersistence ?? this.options.noSessionPersistence
+    if (noSessionPersistence) args.push('--no-session-persistence')
+
+    const tools = options.tools ?? this.options.tools
+    if (tools?.length) args.push('--tools', ...tools)
+
+    const strictMcpConfig = options.strictMcpConfig ?? this.options.strictMcpConfig
+    if (strictMcpConfig) args.push('--strict-mcp-config')
+
+    const settingsFile = options.settingsFile ?? this.options.settingsFile
+    if (settingsFile) args.push('--settings', settingsFile)
+
+    // Per-session only flags
+    if (options.jsonSchema) {
+      const schemaStr = typeof options.jsonSchema === 'string' ? options.jsonSchema : JSON.stringify(options.jsonSchema)
+      args.push('--json-schema', schemaStr)
+    }
+
+    if (options.sessionId) args.push('--session-id', options.sessionId)
+    if (options.forkSession) args.push('--fork-session')
+
+    if (options.debug != null) {
+      if (typeof options.debug === 'string') {
+        args.push('--debug', options.debug)
+      } else if (options.debug) {
+        args.push('--debug')
+      }
+    }
+
+    if (options.debugFile) args.push('--debug-file', options.debugFile)
+
+    const chrome = options.chrome ?? this.options.chrome
+    if (chrome) args.push('--chrome')
+
+    if (options.extraArgs?.length) {
+      args.push(...options.extraArgs)
+    }
+
+    // Prompt is piped via stdin rather than passed as a positional arg,
+    // to avoid content like '---' being parsed as CLI flags.
+    return args
+  }
+
+  /**
+   * Build the environment object for a claude CLI invocation.
+   * Injects ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN when baseURL/authToken are set,
+   * or when local mode is enabled.
+   *
+   * @param {RunOptions} options - Session options
+   * @returns {Record<string, string>} Environment variables
+   */
+  private buildEnv(options: RunOptions = {}): Record<string, string> {
+    const env = { ...process.env }
+    const isLocal = options.local ?? this.options.local
+
+    if (isLocal) {
+      const baseURL = process.env.LOCAL_CHAT_ENDPOINT || 'http://localhost:1234'
+      env.ANTHROPIC_BASE_URL = baseURL
+      if (!options.authToken) {
+        env.ANTHROPIC_AUTH_TOKEN = process.env.LOCAL_CHAT_AUTH_TOKEN || 'sk-anticropic-00000000000000000000001'
+      }
+    }
+
+    const baseURL = options.baseURL
+    if (baseURL) {
+      env.ANTHROPIC_BASE_URL = baseURL
+    }
+
+    const authToken = options.authToken
+    if (authToken) {
+      env.ANTHROPIC_AUTH_TOKEN = authToken
+    }
+
+    return env
+  }
+
+  /**
+   * Create a unique session ID.
+   *
+   * @returns {string} A UUID-based session ID
+   */
+  private createSessionId(): string {
+    return crypto.randomUUID()
+  }
+
+  /**
+   * Update a session in state.
+   *
+   * @param {string} id - The local session ID
+   * @param {Partial<ClaudeSession>} update - Fields to merge
+   */
+  private updateSession(id: string, update: Partial<ClaudeSession>): void {
+    const sessions = { ...this.state.current.sessions }
+    const existing = sessions[id]
+    if (existing) {
+      sessions[id] = { ...existing, ...update }
+      this.setState({ sessions })
+    }
+  }
+
+  /**
+   * Process a parsed JSON event from the Claude CLI stream.
+   *
+   * @param {string} sessionId - The local session ID
+   * @param {ClaudeEvent} event - The parsed event
+   */
+  private handleEvent(sessionId: string, event: ClaudeEvent): void {
+    this.emit('session:event', { sessionId, event })
+
+    // File logging
+    const logConfig = this.sessionLogPaths.get(sessionId)
+    if (logConfig && this.shouldLog(event.type, logConfig.level)) {
+      this.writeLogEntry(sessionId, event.type, event)
+    }
+
+    switch (event.type) {
+      case 'system': {
+        const init = event as ClaudeInitEvent
+        this.updateSession(sessionId, { sessionId: init.session_id })
+        this.emit('session:init', { sessionId, init })
+        break
+      }
+
+      case 'stream_event': {
+        const streamEvent = event as ClaudeStreamEvent
+        if (streamEvent.event.type === 'content_block_delta' && streamEvent.event.delta?.text) {
+          this.emit('session:delta', {
+            sessionId,
+            text: streamEvent.event.delta.text,
+            parentToolUseId: streamEvent.parent_tool_use_id
+          })
+        }
+        this.emit('session:stream', { sessionId, streamEvent })
+        break
+      }
+
+      case 'assistant': {
+        const msg = event as ClaudeAssistantMessage
+        const session = this.state.current.sessions[sessionId]
+        if (session) {
+          this.updateSession(sessionId, {
+            messages: [...session.messages, msg]
+          })
+        }
+        this.emit('session:message', { sessionId, message: msg })
+        break
+      }
+
+      case 'result': {
+        const result = event as ClaudeResultEvent
+        this.updateSession(sessionId, {
+          status: result.is_error ? 'error' : 'completed',
+          result: result.result,
+          error: result.is_error ? result.result : undefined,
+          costUsd: result.total_cost_usd,
+          turns: result.num_turns
+        })
+
+        const activeSessions = this.state.current.activeSessions.filter(id => id !== sessionId)
+        this.setState({ activeSessions })
+
+        this.emit('session:result', {
+          sessionId,
+          result: result.result,
+          isError: result.is_error,
+          costUsd: result.total_cost_usd,
+          turns: result.num_turns,
+          durationMs: result.duration_ms
+        })
+        break
+      }
+    }
+  }
+
+  /**
+   * Run a prompt in a new Claude Code session. Spawns a subprocess,
+   * streams NDJSON events, and resolves when the session completes.
+   *
+   * @param {string} prompt - The instruction/prompt to send
+   * @param {RunOptions} [options] - Session configuration overrides
+   * @returns {Promise<ClaudeSession>} The completed session with result
+   *
+   * @example
+   * ```typescript
+   * // Simple one-shot
+   * const session = await cc.run('What files are in this project?')
+   * console.log(session.result)
+   *
+   * // With options
+   * const session = await cc.run('Refactor the auth module', {
+   *   model: 'opus',
+   *   cwd: '/path/to/project',
+   *   permissionMode: 'acceptEdits',
+   *   streaming: true
+   * })
+   *
+   * // With injected MCP servers
+   * const session = await cc.run('Use the database tools to list tables', {
+   *   mcpServers: {
+   *     'db-tools': { type: 'stdio', command: 'bun', args: ['run', 'db-mcp.ts'] },
+   *     'api': { type: 'http', url: 'https://api.example.com/mcp' }
+   *   }
+   * })
+   *
+   * // Resume a previous session
+   * const session = await cc.run('Now add tests for that', {
+   *   resumeSessionId: previousSession.sessionId
+   * })
+   * ```
+   */
+  async run(prompt: string, options: RunOptions = {}): Promise<ClaudeSession> {
+    const id = this.createSessionId()
+    const args = await this.buildArgs(prompt, options)
+    const cwd = options.cwd ?? this.options.cwd ?? (this.container as any).cwd
+
+    // Set up file logging for this session
+    const fileLog = this.resolveFileLog(options)
+    if (fileLog) {
+      this.sessionLogPaths.set(id, fileLog)
+      this.writeLogEntry(id, 'session:start', { prompt, cwd, args: [this.claudePath, ...args] })
+    }
+
+    const session: ClaudeSession = {
+      id,
+      status: 'running',
+      prompt,
+      costUsd: 0,
+      turns: 0,
+      messages: []
+    }
+
+    // Register session in state
+    const sessions = { ...this.state.current.sessions, [id]: session }
+    const activeSessions = [...this.state.current.activeSessions, id]
+    this.setState({ sessions, activeSessions })
+
+    this.emit('session:start', { sessionId: id, prompt })
+
+    const proc = this.container.feature('proc').spawn(this.claudePath, args, {
+      cwd,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: Buffer.from(prompt),
+      environment: this.buildEnv(options),
+    })
+
+    this.updateSession(id, { process: proc })
+    await this.consumeStream(id, proc)
+
+    return this.state.current.sessions[id]!
+  }
+
+  /**
+   * Run a prompt without waiting for completion. Returns the session ID
+   * immediately so you can subscribe to events.
+   *
+   * @param {string} prompt - The instruction/prompt to send
+   * @param {RunOptions} [options] - Session configuration overrides
+   * @returns {string} The session ID to track via events
+   *
+   * @example
+   * ```typescript
+   * const sessionId = cc.start('Build a REST API for users')
+   *
+   * cc.on('session:delta', ({ sessionId: sid, text }) => {
+   *   if (sid === sessionId) process.stdout.write(text)
+   * })
+   *
+   * cc.on('session:result', ({ sessionId: sid, result }) => {
+   *   if (sid === sessionId) console.log('\nDone:', result)
+   * })
+   * ```
+   */
+  async start(prompt: string, options: RunOptions = {}): Promise<string> {
+    const id = this.createSessionId()
+    const args = await this.buildArgs(prompt, options)
+    const cwd = options.cwd ?? this.options.cwd ?? (this.container as any).cwd
+
+    // Set up file logging for this session
+    const fileLog = this.resolveFileLog(options)
+    if (fileLog) {
+      this.sessionLogPaths.set(id, fileLog)
+      this.writeLogEntry(id, 'session:start', { prompt, cwd, args: [this.claudePath, ...args] })
+    }
+
+    const session: ClaudeSession = {
+      id,
+      status: 'running',
+      prompt,
+      costUsd: 0,
+      turns: 0,
+      messages: []
+    }
+
+    const sessions = { ...this.state.current.sessions, [id]: session }
+    const activeSessions = [...this.state.current.activeSessions, id]
+    this.setState({ sessions, activeSessions })
+
+    this.emit('session:start', { sessionId: id, prompt })
+
+    const proc = this.container.feature('proc').spawn(this.claudePath, args, {
+      cwd,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: Buffer.from(prompt),
+      environment: this.buildEnv(options),
+    })
+
+    this.updateSession(id, { process: proc })
+
+    // Process in background
+    this.consumeStream(id, proc)
+
+    return id
+  }
+
+  /**
+   * Consume the stdout stream of a running process in the background.
+   *
+   * @param {string} sessionId - The local session ID
+   * @param {any} proc - The process handle returned by features.proc.spawn()
+   */
+  private async consumeStream(sessionId: string, proc: any): Promise<void> {
+    if (!proc?.stdout || !proc?.stderr) {
+      const error = 'Process streams are not available'
+      this.updateSession(sessionId, { status: 'error', error })
+      this.emit('session:error', { sessionId, error })
+      return
+    }
+
+    let buffer = ''
+    let stderr = ''
+
+    proc.stderr.on('data', (chunk: Buffer | string) => {
+      stderr += Buffer.isBuffer(chunk) ? chunk.toString() : String(chunk)
+    })
+
+    const stdoutDone = new Promise<void>((resolve, reject) => {
+      proc.stdout.on('data', (chunk: Buffer | string) => {
+        buffer += Buffer.isBuffer(chunk) ? chunk.toString() : String(chunk)
+        const lines = buffer.split('\n')
+        buffer = lines.pop() || ''
+
+        for (const line of lines) {
+          const trimmed = line.trim()
+          if (!trimmed) continue
+
+          try {
+            const event = JSON.parse(trimmed) as ClaudeEvent
+            this.handleEvent(sessionId, event)
+          } catch {
+            this.emit('session:parse-error', { sessionId, line: trimmed })
+          }
+        }
+      })
+
+      proc.stdout.on('end', () => {
+        if (buffer.trim()) {
+          try {
+            const event = JSON.parse(buffer.trim()) as ClaudeEvent
+            this.handleEvent(sessionId, event)
+          } catch {
+            // ignore trailing partial data
+          }
+        }
+        resolve()
+      })
+
+      proc.stdout.on('error', reject)
+    })
+
+    const exitCodePromise = new Promise<number>((resolve, reject) => {
+      proc.once('error', reject)
+      proc.once('close', (code: number | null) => resolve(code ?? 0))
+    })
+
+    try {
+      await stdoutDone
+    } catch (err) {
+      this.updateSession(sessionId, {
+        status: 'error',
+        error: err instanceof Error ? err.message : String(err)
+      })
+      this.emit('session:error', { sessionId, error: err })
+    }
+
+    let exitCode = 1
+    try {
+      exitCode = await exitCodePromise
+    } catch (err) {
+      this.updateSession(sessionId, {
+        status: 'error',
+        error: err instanceof Error ? err.message : String(err),
+      })
+      this.emit('session:error', { sessionId, error: err })
+    }
+
+    if (exitCode !== 0 && this.state.current.sessions[sessionId]?.status !== 'completed') {
+      this.updateSession(sessionId, {
+        status: 'error',
+        error: stderr || `Process exited with code ${exitCode}`
+      })
+      this.emit('session:error', { sessionId, error: stderr, exitCode })
+    }
+
+    // Finalize file log
+    if (this.sessionLogPaths.has(sessionId)) {
+      const finalSession = this.state.current.sessions[sessionId]!
+      await this.writeLogEntry(sessionId, 'session:end', {
+        status: finalSession.status,
+        result: finalSession.result,
+        error: finalSession.error,
+        costUsd: finalSession.costUsd,
+        turns: finalSession.turns,
+        messageCount: finalSession.messages.length
+      })
+      this.sessionLogPaths.delete(sessionId)
+    }
+  }
+
+  /**
+   * Kill a running session's subprocess.
+   *
+   * @param {string} sessionId - The local session ID to abort
+   *
+   * @example
+   * ```typescript
+   * const sessionId = cc.start('Do something long')
+   * // ... later
+   * cc.abort(sessionId)
+   * ```
+   */
+  abort(sessionId: string): void {
+    const session = this.state.current.sessions[sessionId]
+    if (session?.process && session.status === 'running') {
+      session.process.kill()
+      this.updateSession(sessionId, { status: 'error', error: 'Aborted by user' })
+      const activeSessions = this.state.current.activeSessions.filter(id => id !== sessionId)
+      this.setState({ activeSessions })
+      this.emit('session:abort', { sessionId })
+
+      if (this.sessionLogPaths.has(sessionId)) {
+        this.writeLogEntry(sessionId, 'session:abort', { reason: 'Aborted by user' })
+        this.sessionLogPaths.delete(sessionId)
+      }
+    }
+  }
+
+  /**
+   * Get a session by its local ID.
+   *
+   * @param {string} sessionId - The local session ID
+   * @returns {ClaudeSession | undefined} The session if it exists
+   *
+   * @example
+   * ```typescript
+   * const session = cc.getSession(sessionId)
+   * if (session?.status === 'completed') {
+   *   console.log(session.result)
+   * }
+   * ```
+   */
+  getSession(sessionId: string): ClaudeSession | undefined {
+    return this.state.current.sessions[sessionId]
+  }
+
+  /**
+   * Wait for a running session to complete.
+   *
+   * @param {string} sessionId - The local session ID
+   * @returns {Promise<ClaudeSession>} The completed session
+   *
+   * @example
+   * ```typescript
+   * const id = cc.start('Build something cool')
+   * const session = await cc.waitForSession(id)
+   * console.log(session.result)
+   * ```
+   */
+  async waitForSession(sessionId: string): Promise<ClaudeSession> {
+    const session = this.state.current.sessions[sessionId]
+    if (!session) throw new Error(`Session ${sessionId} not found`)
+    if (session.status === 'completed' || session.status === 'error') return session
+
+    return new Promise((resolve) => {
+      const handler = (data: { sessionId: string }) => {
+        if (data.sessionId === sessionId) {
+          this.off('session:result')
+          this.off('session:error')
+          resolve(this.state.current.sessions[sessionId]!)
+        }
+      }
+      this.on('session:result', handler)
+      this.on('session:error', handler)
+    })
+  }
+
+  /**
+   * Get aggregated usage statistics across all sessions, or for a specific session.
+   *
+   * @param {string} [sessionId] - Optional session ID to get usage for a single session
+   * @returns {{ totalCostUsd: number; totalInputTokens: number; totalOutputTokens: number; totalCacheReadTokens: number; totalCacheCreationTokens: number; totalTurns: number; sessionCount: number; sessions: Array<{ id: string; costUsd: number; turns: number; inputTokens: number; outputTokens: number; status: string }> }} Usage statistics
+   *
+   * @example
+   * ```typescript
+   * const stats = cc.usage()
+   * console.log(`Total cost: $${stats.totalCostUsd.toFixed(4)}`)
+   * console.log(`Tokens: ${stats.totalInputTokens} in / ${stats.totalOutputTokens} out`)
+   *
+   * // Single session
+   * const sessionStats = cc.usage(sessionId)
+   * ```
+   */
+  usage(sessionId?: string) {
+    const allSessions = this.state.current.sessions
+    const entries = sessionId
+      ? (allSessions[sessionId] ? [allSessions[sessionId]] : [])
+      : Object.values(allSessions)
+
+    let totalCostUsd = 0
+    let totalInputTokens = 0
+    let totalOutputTokens = 0
+    let totalCacheReadTokens = 0
+    let totalCacheCreationTokens = 0
+    let totalTurns = 0
+    const sessions: Array<{ id: string; costUsd: number; turns: number; inputTokens: number; outputTokens: number; status: string }> = []
+
+    for (const session of entries as ClaudeSession[]) {
+      let inputTokens = 0
+      let outputTokens = 0
+      let cacheRead = 0
+      let cacheCreation = 0
+
+      for (const msg of session.messages || []) {
+        const u = msg.message?.usage
+        if (u) {
+          inputTokens += u.input_tokens || 0
+          outputTokens += u.output_tokens || 0
+          cacheRead += u.cache_read_input_tokens || 0
+          cacheCreation += u.cache_creation_input_tokens || 0
+        }
+      }
+
+      totalCostUsd += session.costUsd || 0
+      totalInputTokens += inputTokens
+      totalOutputTokens += outputTokens
+      totalCacheReadTokens += cacheRead
+      totalCacheCreationTokens += cacheCreation
+      totalTurns += session.turns || 0
+
+      sessions.push({
+        id: session.id,
+        costUsd: session.costUsd || 0,
+        turns: session.turns || 0,
+        inputTokens,
+        outputTokens,
+        status: session.status,
+      })
+    }
+
+    // Budget remaining: if maxBudgetUsd is configured, compute what's left
+    const maxBudgetUsd = this.options.maxBudgetUsd
+    const budgetRemainingUsd = maxBudgetUsd != null ? Math.max(0, maxBudgetUsd - totalCostUsd) : undefined
+    const budgetUsedPercent = maxBudgetUsd != null && maxBudgetUsd > 0 ? Math.min(100, (totalCostUsd / maxBudgetUsd) * 100) : undefined
+
+    return {
+      totalCostUsd,
+      totalInputTokens,
+      totalOutputTokens,
+      totalCacheReadTokens,
+      totalCacheCreationTokens,
+      totalTurns,
+      sessionCount: sessions.length,
+      maxBudgetUsd: maxBudgetUsd ?? null,
+      budgetRemainingUsd: budgetRemainingUsd ?? null,
+      budgetUsedPercent: budgetUsedPercent ?? null,
+      sessions,
+    }
+  }
+
+  /**
+   * The Claude CLI session ID of the most recently initialized session,
+   * or the session set via the `session` option. Useful for resuming later.
+   *
+   * @returns {string | undefined} The Claude CLI session ID
+   *
+   * @example
+   * ```typescript
+   * const cc = container.feature('claudeCode')
+   * await cc.run('Do something')
+   * console.log(cc.sessionId) // the Claude CLI session ID
+   * ```
+   */
+  get sessionId(): string | undefined {
+    // Check if a default session was set via options
+    if (this.options.session) return this.options.session
+
+    // Find the most recently created session that has a Claude CLI sessionId
+    const sessions = Object.values(this.state.current.sessions) as ClaudeSession[]
+    if (sessions.length === 0) return undefined
+
+    // Return the last session's Claude CLI session ID
+    const last = sessions[sessions.length - 1]
+    return last?.sessionId
+  }
+
+  /**
+   * Export session history as a readable markdown document.
+   * Reads from a raw JSONL file (Claude CLI session log or this feature's NDJSON log)
+   * so it works independently of in-memory state.
+   *
+   * Can also accept a local session ID to export from in-memory state as a fallback.
+   *
+   * @param {string} [source] - Path to a JSONL file, a local session ID, or omit for the most recent session
+   * @returns {Promise<string>} Markdown-formatted session history
+   *
+   * @example
+   * ```typescript
+   * // From a JSONL file (works without any prior state)
+   * const md = await cc.sessionHistoryToMarkdown('/path/to/session.jsonl')
+   *
+   * // From the most recent in-memory session
+   * const md = await cc.sessionHistoryToMarkdown()
+   *
+   * // From a specific local session ID
+   * const md = await cc.sessionHistoryToMarkdown(localSessionId)
+   * ```
+   */
+  async sessionHistoryToMarkdown(source?: string): Promise<string> {
+    // If source looks like a file path, read JSONL from disk
+    if (source && (source.includes('/') || source.endsWith('.jsonl'))) {
+      return this.jsonlToMarkdown(source)
+    }
+
+    // Otherwise try to resolve from in-memory state
+    const sessionId = source || this.findLastSessionId()
+    if (!sessionId) throw new Error('No session found. Pass a JSONL file path or run a session first.')
+
+    const session = this.state.current.sessions[sessionId] as ClaudeSession | undefined
+    if (!session) throw new Error(`Session ${sessionId} not found in state. Pass a JSONL file path instead.`)
+
+    return this.sessionToMarkdown(session)
+  }
+
+  /**
+   * Find the local ID of the most recent session.
+   */
+  private findLastSessionId(): string | undefined {
+    const ids = Object.keys(this.state.current.sessions)
+    return ids.length > 0 ? ids[ids.length - 1] : undefined
+  }
+
+  /**
+   * Parse a JSONL file and convert its events to markdown.
+   */
+  private async jsonlToMarkdown(filePath: string): Promise<string> {
+    const fs = this.container.feature('fs')
+    const content = await fs.readFileAsync(filePath, 'utf-8')
+    const lines = content.split('\n').filter((l: string) => l.trim())
+
+    const events: ClaudeEvent[] = []
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line)
+        // Support both raw Claude events and our wrapper format (which has a .data field)
+        events.push(parsed.data ?? parsed)
+      } catch {
+        // skip malformed lines
+      }
+    }
+
+    return this.eventsToMarkdown(events, filePath)
+  }
+
+  /**
+   * Convert a ClaudeSession (from state) to markdown.
+   */
+  private sessionToMarkdown(session: ClaudeSession): string {
+    const lines: string[] = []
+
+    lines.push(`# Session: ${session.id}`)
+    if (session.sessionId) lines.push(`**Claude Session ID:** \`${session.sessionId}\``)
+    lines.push(`**Status:** ${session.status}`)
+    if (session.costUsd) lines.push(`**Cost:** $${session.costUsd.toFixed(4)}`)
+    if (session.turns) lines.push(`**Turns:** ${session.turns}`)
+    lines.push('')
+
+    lines.push(`## Prompt`)
+    lines.push('')
+    lines.push(session.prompt)
+    lines.push('')
+
+    if (session.messages.length > 0) {
+      lines.push(`## Conversation`)
+      lines.push('')
+
+      for (const msg of session.messages) {
+        this.renderAssistantMessage(lines, msg)
+      }
+    }
+
+    if (session.result) {
+      lines.push(`## Result`)
+      lines.push('')
+      lines.push(session.result)
+      lines.push('')
+    }
+
+    if (session.error) {
+      lines.push(`## Error`)
+      lines.push('')
+      lines.push(`\`\`\`\n${session.error}\n\`\`\``)
+      lines.push('')
+    }
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Convert raw Claude events to markdown.
+   */
+  private eventsToMarkdown(events: ClaudeEvent[], source: string): string {
+    const lines: string[] = []
+    let sessionId: string | undefined
+    let model: string | undefined
+    let prompt: string | undefined
+    let costUsd: number | undefined
+    let turns: number | undefined
+    let durationMs: number | undefined
+
+    // Extract metadata from init and result events
+    for (const event of events) {
+      if (event.type === 'system' && (event as any).subtype === 'init') {
+        const init = event as ClaudeInitEvent
+        sessionId = init.session_id
+        model = init.model
+      }
+      if (event.type === 'result') {
+        const result = event as ClaudeResultEvent
+        costUsd = result.total_cost_usd
+        turns = result.num_turns
+        durationMs = result.duration_ms
+      }
+    }
+
+    lines.push(`# Session History`)
+    lines.push(`**Source:** \`${source}\``)
+    if (sessionId) lines.push(`**Session ID:** \`${sessionId}\``)
+    if (model) lines.push(`**Model:** ${model}`)
+    if (costUsd != null) lines.push(`**Cost:** $${costUsd.toFixed(4)}`)
+    if (turns != null) lines.push(`**Turns:** ${turns}`)
+    if (durationMs != null) lines.push(`**Duration:** ${(durationMs / 1000).toFixed(1)}s`)
+    lines.push('')
+
+    lines.push(`## Conversation`)
+    lines.push('')
+
+    for (const event of events) {
+      if (event.type === 'assistant') {
+        this.renderAssistantMessage(lines, event as ClaudeAssistantMessage)
+      } else if (event.type === 'tool_result') {
+        const tr = event as ClaudeToolResult
+        lines.push(`<details>`)
+        lines.push(`<summary>Tool Result (${tr.tool_use_id})</summary>`)
+        lines.push('')
+        lines.push('```')
+        lines.push(tr.content.length > 2000 ? tr.content.slice(0, 2000) + '\n... (truncated)' : tr.content)
+        lines.push('```')
+        lines.push(`</details>`)
+        lines.push('')
+      } else if (event.type === 'result') {
+        const result = event as ClaudeResultEvent
+        lines.push(`## Result`)
+        lines.push('')
+        if (result.is_error) {
+          lines.push(`**Error:**`)
+          lines.push(`\`\`\`\n${result.result}\n\`\`\``)
+        } else {
+          lines.push(result.result)
+        }
+        lines.push('')
+      }
+    }
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Render a single assistant message to markdown lines.
+   */
+  private renderAssistantMessage(lines: string[], msg: ClaudeAssistantMessage): void {
+    lines.push(`### Assistant`)
+    if (msg.message?.usage) {
+      const u = msg.message.usage
+      lines.push(`*${u.input_tokens} in / ${u.output_tokens} out tokens*`)
+    }
+    lines.push('')
+
+    for (const block of msg.message?.content || []) {
+      if (block.type === 'text') {
+        lines.push(block.text)
+        lines.push('')
+      } else if (block.type === 'tool_use') {
+        lines.push(`**Tool Use:** \`${block.name}\``)
+        lines.push('```json')
+        lines.push(JSON.stringify(block.input, null, 2))
+        lines.push('```')
+        lines.push('')
+      }
+    }
+  }
+
+  /**
+   * List all Claude Code processes currently registered in ~/.claude/sessions/.
+   * Returns each session's metadata along with whether the process is still alive.
+   *
+   * @returns {Promise<Array<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string; alive: boolean }>>}
+   *
+   * @example
+   * const sessions = await cc.listProcessSessions()
+   * for (const s of sessions) {
+   *   console.log(`[${s.alive ? 'LIVE' : 'dead'}] PID ${s.pid} in ${s.cwd}`)
+   * }
+   */
+  async listProcessSessions(): Promise<Array<{
+    pid: number
+    sessionId: string
+    cwd: string
+    startedAt: number
+    kind: string
+    entrypoint: string
+    alive: boolean
+  }>> {
+    const fs = this.container.feature('fs')
+    const proc = this.container.feature('proc')
+    const home = this.container.feature('os').homedir
+    const sessionsDir = `${home}/.claude/sessions`
+
+    let files: string[]
+    try {
+      files = await fs.readdir(sessionsDir)
+    } catch {
+      return []
+    }
+
+    const jsonFiles = files.filter((f: string) => f.endsWith('.json'))
+
+    const results = await Promise.all(jsonFiles.map(async (file: string) => {
+      try {
+        const raw = await fs.readFile(`${sessionsDir}/${file}`, 'utf8')
+        const data = JSON.parse(raw)
+        let alive = false
+        try {
+          await proc.exec(`kill -0 ${data.pid}`)
+          alive = true
+        } catch {
+          alive = false
+        }
+        return { ...data, alive }
+      } catch {
+        return null
+      }
+    }))
+
+    return results.filter(Boolean)
+  }
+
+  /**
+   * Read a single process session by PID from ~/.claude/sessions/<pid>.json.
+   *
+   * @param {number} pid - The process ID
+   * @returns {Promise<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string } | null>}
+   *
+   * @example
+   * const session = await cc.getProcessSession(12345)
+   * console.log(session?.cwd)
+   */
+  async getProcessSession(pid: number): Promise<{
+    pid: number
+    sessionId: string
+    cwd: string
+    startedAt: number
+    kind: string
+    entrypoint: string
+  } | null> {
+    const fs = this.container.feature('fs')
+    const home = this.container.feature('os').homedir
+    try {
+      const raw = await fs.readFile(`${home}/.claude/sessions/${pid}.json`, 'utf8')
+      return JSON.parse(raw)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Read the conversation history for a Claude Code session from its JSONL file in
+   * ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl.
+   *
+   * Returns an array of parsed message objects (user, assistant, tool_use, tool_result).
+   *
+   * @param {string} sessionId - The Claude CLI session ID (from listProcessSessions or getProcessSession)
+   * @param {string} cwd - The working directory of the session (used to locate the project folder)
+   * @returns {Promise<any[]>} Array of parsed JSONL records
+   *
+   * @example
+   * const sessions = await cc.listProcessSessions()
+   * const s = sessions[0]
+   * const history = await cc.getConversationHistory(s.sessionId, s.cwd)
+   * console.log(history.length, 'turns')
+   */
+  async getConversationHistory(sessionId: string, cwd?: string): Promise<any[]> {
+    const fs = this.container.feature('fs')
+    const home = this.container.feature('os').homedir
+    const resolvedCwd = cwd ?? this.options.cwd ?? (this.container as any).cwd
+    const encodedCwd = resolvedCwd.replace(/[\\/]/g, '-').replace(/@/g, '-')
+    const filePath = `${home}/.claude/projects/${encodedCwd}/${sessionId}.jsonl`
+    try {
+      const raw = await fs.readFile(filePath, 'utf8')
+      return raw
+        .split('\n')
+        .filter((line: string) => line.trim())
+        .map((line: string) => JSON.parse(line))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * List all conversation sessions stored for a given working directory.
+   * Reads ~/.claude/projects/<encoded-cwd>/ and returns metadata for each .jsonl file.
+   *
+   * @param {string} cwd - The working directory path to look up
+   * @returns {Promise<Array<{ sessionId: string; filePath: string; messageCount: number }>>}
+   *
+   * @example
+   * const sessions = await cc.listSessionsForCwd('/Users/me/my-project')
+   * for (const s of sessions) {
+   *   console.log(s.sessionId, s.messageCount, 'messages')
+   * }
+   */
+  async listSessionsForCwd(cwd?: string): Promise<Array<{
+    sessionId: string
+    filePath: string
+    messageCount: number
+  }>> {
+    const fs = this.container.feature('fs')
+    const home = this.container.feature('os').homedir
+    const resolvedCwd = cwd ?? this.options.cwd ?? (this.container as any).cwd
+    const encodedCwd = resolvedCwd.replace(/[\\/]/g, '-').replace(/@/g, '-')
+    const projectDir = `${home}/.claude/projects/${encodedCwd}`
+
+    let files: string[]
+    try {
+      files = await fs.readdir(projectDir)
+    } catch {
+      return []
+    }
+
+    const jsonlFiles = files.filter((f: string) => f.endsWith('.jsonl'))
+
+    const results = await Promise.all(jsonlFiles.map(async (file: string) => {
+      const sessionId = file.replace(/\.jsonl$/, '')
+      const filePath = `${projectDir}/${file}`
+      try {
+        const raw = await fs.readFile(filePath, 'utf8')
+        const messageCount = raw.split('\n').filter((l: string) => l.trim()).length
+        return { sessionId, filePath, messageCount }
+      } catch {
+        return { sessionId, filePath, messageCount: 0 }
+      }
+    }))
+
+    return results
+  }
+
+  /**
+   * Clean up any temp MCP config files created during sessions.
+   */
+  async cleanupMcpTempFiles(): Promise<void> {
+    for (const path of this.mcpTempFiles) {
+      try { await this.container.feature('fs').rm(path) } catch { /* already gone */ }
+    }
+    this.mcpTempFiles = []
+  }
+
+  /**
+   * Initialize the feature.
+   *
+   * @param {any} [options] - Enable options
+   * @returns {Promise<this>} The enabled feature
+   */
+  override async enable(options: any = {}): Promise<this> {
+    await super.enable(options)
+    return this
+  }
+}
+
+export default ClaudeCode