@meistrari/agent-core 0.2.0-experimental.1 → 0.2.0-experimental.2

package/src/agents/claude/claude-file-change.ts

@@ -0,0 +1,128 @@
+import type { FileEditOutput, FileWriteOutput } from '@anthropic-ai/claude-agent-sdk/sdk-tools'
+import { isAbsolute, relative } from 'node:path'
+import z from 'zod'
+import { CANONICAL_TOOL } from '../../protocol/agent-tool-name'
+
+type ClaudePatchHunk = FileEditOutput['structuredPatch'][number]
+// `staged` is typed only by newer SDKs (0.3.280); older pinned runtimes omit it, so it stays optional.
+type ClaudeEditDiffEvidence = Pick<FileEditOutput, 'filePath' | 'oldString' | 'newString' | 'originalFile' | 'structuredPatch'> & { staged?: boolean }
+type ClaudeWriteDiffEvidence = Pick<FileWriteOutput, 'type' | 'filePath' | 'content' | 'structuredPatch' | 'originalFile'> & { staged?: boolean }
+interface DiffHeaderPaths { old: string, new: string }
+
+const patchHunkSchema = z.object({
+    oldStart: z.number().int().nonnegative(),
+    oldLines: z.number().int().nonnegative(),
+    newStart: z.number().int().nonnegative(),
+    newLines: z.number().int().nonnegative(),
+    lines: z.array(z.string()),
+}).passthrough() satisfies z.ZodType<ClaudePatchHunk>
+
+const editDiffEvidenceSchema = z.object({
+    filePath: z.string().min(1),
+    oldString: z.string(),
+    newString: z.string(),
+    originalFile: z.string().nullable(),
+    structuredPatch: z.array(patchHunkSchema),
+    staged: z.boolean().optional(),
+}).passthrough() satisfies z.ZodType<ClaudeEditDiffEvidence>
+
+const writeDiffEvidenceSchema = z.object({
+    type: z.enum(['create', 'update']),
+    filePath: z.string().min(1),
+    content: z.string(),
+    structuredPatch: z.array(patchHunkSchema),
+    originalFile: z.string().nullable(),
+    staged: z.boolean().optional(),
+}).passthrough() satisfies z.ZodType<ClaudeWriteDiffEvidence>
+
+/**
+ * Renders the host `tool_use_result` of a successful Claude Edit or Write call as a unified diff,
+ * the same output shape Codex reports for a file change. Returns undefined when the result does
+ * not prove a diff, so the caller keeps the model-facing text.
+ */
+export function claudeFileChangeText({ toolName, toolUseResult, cwd }: { toolName: string | undefined, toolUseResult: unknown, cwd: string | undefined }): string | undefined {
+    if (toolName === CANONICAL_TOOL.edit) {
+        const parsed = editDiffEvidenceSchema.safeParse(toolUseResult)
+        if (!parsed.success)
+            return undefined
+        const path = displayPath({ filePath: parsed.data.filePath, cwd })
+        const { oldString, newString, originalFile, structuredPatch, staged } = parsed.data
+        if (staged === true)
+            return noChangesText(path)
+        // The CLI accepts an empty old_string only for a missing or empty file ("Cannot create new
+        // file - file already exists." otherwise) and reports its original as "" (or null when the
+        // result is reconstructed), so this Edit created the file.
+        if (oldString === '' && !originalFile) {
+            const hunks = structuredPatch.length > 0 ? structuredPatch : createdFileHunks(newString)
+            return unifiedDiff({ paths: createdFilePaths(path), hunks })
+        }
+        // An empty Edit patch cannot tell an unchanged file from a diff the CLI gave up computing.
+        if (structuredPatch.length === 0)
+            return undefined
+        return unifiedDiff({ paths: gitHeaderPaths(path), hunks: structuredPatch })
+    }
+
+    if (toolName === CANONICAL_TOOL.write) {
+        const parsed = writeDiffEvidenceSchema.safeParse(toolUseResult)
+        if (!parsed.success)
+            return undefined
+        const { type, content, structuredPatch, originalFile, staged } = parsed.data
+        const path = displayPath({ filePath: parsed.data.filePath, cwd })
+        if (staged === true)
+            return noChangesText(path)
+        if (type === 'create') {
+            const hunks = structuredPatch.length > 0 ? structuredPatch : createdFileHunks(content)
+            return unifiedDiff({ paths: createdFilePaths(path), hunks })
+        }
+        if (structuredPatch.length > 0)
+            return unifiedDiff({ paths: gitHeaderPaths(path), hunks: structuredPatch })
+        // An empty update patch also covers a timed-out diff or an original too large to include.
+        return originalFile === content ? noChangesText(path) : undefined
+    }
+
+    return undefined
+}
+
+function displayPath({ filePath, cwd }: { filePath: string, cwd: string | undefined }): string {
+    if (!cwd || !isAbsolute(filePath))
+        return filePath
+    const relativePath = relative(cwd, filePath)
+    return relativePath && !relativePath.startsWith('..') && !isAbsolute(relativePath) ? relativePath : filePath
+}
+
+function gitHeaderPaths(path: string): DiffHeaderPaths {
+    return isAbsolute(path) ? { old: path, new: path } : { old: `a/${path}`, new: `b/${path}` }
+}
+
+function createdFilePaths(path: string): DiffHeaderPaths {
+    return { old: '/dev/null', new: gitHeaderPaths(path).new }
+}
+
+function createdFileHunks(content: string): ClaudePatchHunk[] {
+    if (content === '')
+        return []
+    const endsWithNewline = content.endsWith('\n')
+    const lines = (endsWithNewline ? content.slice(0, -1) : content).split('\n')
+    const hunkLines = lines.map(line => `+${line}`)
+    if (!endsWithNewline)
+        hunkLines.push('\')
+    return [{ oldStart: 1, oldLines: 0, newStart: 1, newLines: lines.length, lines: hunkLines }]
+}
+
+function unifiedDiff({ paths, hunks }: { paths: DiffHeaderPaths, hunks: ClaudePatchHunk[] }): string {
+    const lines = [`--- ${paths.old}`, `+++ ${paths.new}`]
+    for (const hunk of hunks)
+        lines.push(`@@ -${hunkRange(hunk.oldStart, hunk.oldLines)} +${hunkRange(hunk.newStart, hunk.newLines)} @@`, ...hunk.lines)
+    return `${lines.join('\n')}\n`
+}
+
+// The CLI's structuredPatch is jsdiff's, which starts an empty range at the following line; a
+// unified diff names the preceding line instead (so an empty original is `-0,0`), as jsdiff's own
+// formatPatch does.
+function hunkRange(start: number, count: number): string {
+    return `${count === 0 ? Math.max(start - 1, 0) : start},${count}`
+}
+
+function noChangesText(path: string): string {
+    return `No changes applied to ${path}.`
+}

package/src/agents/claude/claude-provider.ts

@@ -1,46 +1,171 @@
-import type { Options, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
+import type { McpStdioServerConfig, Options, Query, SDKControlInitializeResponse, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
 import type { ClaudeModelId } from '../../protocol'
 import type { AgentOperationOptions } from '../agent-operation'
 import type { AgentProvider, AgentSessionOpenInput, AgentSessionResumeInput } from '../agent-provider'
 import type { AgentTool } from '../agent-tool'
 import type { InstructionComposer } from '../instructions'
+import type { SessionContextComposer } from '../session-context'
+import type { ClaudeProviderAuth } from './claude-auth'
+import type { ClaudeDesktopConfig } from './claude-desktop'
 import type { ClaudeStartupTiming } from './claude-startup-timing'
+import type { ClaudeNativeToolActor } from './claude-tool-mapper'
+import { randomUUID } from 'node:crypto'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { query as queryClaude } from '@anthropic-ai/claude-agent-sdk'
 import { claudeModelIdSchema } from '../../protocol'
-import { AgentRunStateError } from '../agent-runtime-error'
+import { AgentProviderLaunchError, AgentRunStateError } from '../agent-runtime-error'
 import { selectAgentTools } from '../agent-tool'
+import { CodexBrowserAuthBroker } from '../codex/codex-browser-auth-broker'
+import { LazyCodexRunAuth } from '../codex/lazy-codex-run-auth'
 import { emptyInstructionComposer } from '../instructions'
 import { removeUndefined } from '../normalize'
+import { pendingSessionContext } from '../session-context'
 import { UserInputRequestStore, userInputRequestStoreRootFromTranscriptPath } from '../user-input-request'
+import { ClaudeBrowserTurnMetadata, claudeBrowserTurnMetadataHooks } from './claude-browser-turn-metadata'
+import { ClaudeCodeProcess } from './claude-code-process'
+import { claudeDesktopMcpServers } from './claude-desktop'
 import { createClaudeEventMapperState } from './claude-event-mapper'
 import { ClaudeRun } from './claude-run'
+import { ClaudeSelectedRepositoryInstructions } from './claude-selected-repository-instructions'
+import { ClaudeSkillCatalog } from './claude-skill-catalog'
 import { createClaudeStartupTiming, observeClaudeControlInitialization } from './claude-startup-timing'
-import { claudeAllowedToolNames, claudeToolActorHooks, createClaudeToolRuntimeRef, toClaudeMcpServers } from './claude-tool-mapper'
+import { claudeSteeredNotificationHooks, ClaudeSteeredNotificationStore } from './claude-steered-notifications'
+import { claudeAllowedToolNames, claudeNativeToolActorHooks, claudeToolActorHooks, createClaudeToolRuntimeRef, mergeClaudeToolHooks, toClaudeMcpServers } from './claude-tool-mapper'
+import { ClaudeWorkspaceSkills, claudeWorkspaceSkillsPluginName } from './claude-workspace-skills'
+
+export type { ClaudeNativeToolActor } from './claude-tool-mapper'
+
+export type ClaudeNativeToolActorRun = Readonly<{
+    mcpServer: Readonly<{
+        name: 'mcp_repl'
+        config: McpStdioServerConfig
+    }>
+    toolNames: readonly string[]
+    register: (input: { toolName: string, toolUseId: string, actor: ClaudeNativeToolActor, signal: AbortSignal }) => Promise<void>
+    finish: (input: { toolUseId: string }) => Promise<void>
+    close: () => Promise<void>
+}>
+
+export type ClaudeNativeToolActorBridge = Readonly<{
+    openRun: (input: { sessionId: string, signal: AbortSignal }) => Promise<ClaudeNativeToolActorRun>
+}>
+
+/**
+ * Skill sources for every run. `imagePlugin` is the image-baked local plugin whose `skills` links to
+ * the image skills directory (`null` outside the sandbox image); `workspacePluginDirectory` is where
+ * each run generates its workspace-repository skills plugin.
+ */
+export type ClaudeSkillsConfig = Readonly<{
+    imagePlugin: Readonly<{ path: string, name: string }> | null
+    workspacePluginDirectory: string
+}>
 
 export interface ClaudeProviderConfig {
+    // Routes model traffic through a credential proxy. Without it, the configured environment's own
+    // credentials (for example ANTHROPIC_API_KEY) authenticate Claude Code unchanged.
+    auth?: ClaudeProviderAuth
+    // Skill plugins for every run. Without it, runs load no generated skills plugin.
+    skills?: ClaudeSkillsConfig
+    // The sandbox desktop (Computer Use / Browser Use); omitted or `null` where no desktop exists.
+    desktop?: ClaudeDesktopConfig | null
     tools?: readonly AgentTool[]
     executable?: string
     environment?: Record<string, string | undefined>
+    nativeToolActorBridge?: ClaudeNativeToolActorBridge
+    startupDeadlineMs?: number
+    // Product instructions appended to the Claude Code preset system prompt.
     instructions?: InstructionComposer
+    // Per-session context delivered once with the first prompt of a session that has a web URL.
+    sessionContext?: SessionContextComposer
+    // Product context published with the selected-repository instructions, even with no repository.
+    selectedRepositoryContext?: string
     onStartupTiming?: (timing: ClaudeStartupTiming) => void
+    // Defaults to project and local settings; `sdk-default` leaves the SDK option unset.
+    settingSources?: 'sdk-default' | NonNullable<Options['settingSources']>
+    // Reads persisted tool results back from the transcript (default true).
+    hydratePersistedToolOutput?: boolean
+    // Native tools unavailable to the model; defaults to the interactive and out-of-session tools.
+    disallowedTools?: readonly string[]
 }
 
+// Bounds the SDK `initialize` handshake. Measured Claude Code startup in the E2B image is about
+// 0.4 to 2.7 s (locally about 0.13 s); 30 s is roughly ten times the slowest observation and matches
+// the 30 s deadline the Codex browser-auth broker applies to its native startup.
+export const CLAUDE_STARTUP_DEADLINE_MS = 30_000
+
+// Credentials that must never reach Claude Code from the inherited environment: the run's only
+// credential is the configured auth route, so an ambient key cannot silently take precedence.
+const inheritedClaudeCredentialKeys = [
+    'ANTHROPIC_API_KEY',
+    'ANTHROPIC_AUTH_TOKEN',
+    'ANTHROPIC_BASE_URL',
+    'CLAUDE_CODE_OAUTH_TOKEN',
+    'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR',
+    'CLAUDE_CODE_OAUTH_REFRESH_TOKEN',
+    // Account facts for the env token; only the auth route may state them.
+    'CLAUDE_CODE_SUBSCRIPTION_TYPE',
+    'CLAUDE_CODE_RATE_LIMIT_TIER',
+] as const
+
+// Claude Code 2.1.280 gives an env OAuth token the subscription type CLAUDE_CODE_SUBSCRIPTION_TYPE
+// (the variable it sets itself for the env-token child processes it spawns), else null. With
+// _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL, a null or team/enterprise type makes initialize fetch
+// remote managed settings and policy limits from the hard-coded https://api.anthropic.com with
+// the placeholder bearer (a 401 when reachable, ~210 ms locally; ~18 s of retries when not). For a
+// Pro or Max account the CLI skips both as it does for a stored /login (`unsupported_subscription`,
+// `prosumer_oauth`), so the environment states only those two real types; see
+// docs/packages/agents.md#claude-authentication.
+const claudeFetchFreeSubscriptionTypes = new Set(['pro', 'max'])
+
+// Interactive native tools that a headless run cannot serve.
+export const defaultClaudeDisallowedToolNames: readonly string[] = [
+    'AskUserQuestion',
+    'EnterPlanMode',
+    'ExitPlanMode',
+    'NotebookEdit',
+    'EnterWorktree',
+    'ExitWorktree',
+]
+
+// Claude Code 2.1.263 and 2.1.280 omit these native work tools from headless preset sessions unless
+// they are named in allowedTools. Keep them loaded so their lifecycle maps to work.observed.
+const claudeNativeWorkToolNames = ['TaskCreate', 'TaskGet', 'TaskList', 'TaskUpdate'] as const
+
 export class ClaudeProvider implements AgentProvider<'claude'> {
     readonly id = 'claude' as const
+    private readonly auth: ClaudeProviderAuth | undefined
+    private readonly skills: ClaudeSkillsConfig | undefined
+    private readonly desktop: ClaudeDesktopConfig | null
     private readonly tools: readonly AgentTool[]
     private readonly executable: string | undefined
     private readonly environment: Record<string, string | undefined>
+    private readonly nativeToolActorBridge: ClaudeNativeToolActorBridge | undefined
+    private readonly startupDeadlineMs: number
     private readonly instructions: InstructionComposer
+    private readonly sessionContext: SessionContextComposer | undefined
+    private readonly selectedRepositoryContext: string | undefined
     private readonly onStartupTiming: ClaudeProviderConfig['onStartupTiming']
+    private readonly settingSources: Options['settingSources']
+    private readonly hydratePersistedToolOutput: boolean
+    private readonly disallowedTools: readonly string[]
 
     private constructor(config: ClaudeProviderConfig) {
+        this.auth = config.auth
+        this.skills = config.skills
+        this.desktop = config.desktop ?? null
         this.tools = config.tools ?? []
         this.executable = config.executable
         this.environment = config.environment ?? {}
+        this.nativeToolActorBridge = config.nativeToolActorBridge
+        this.startupDeadlineMs = config.startupDeadlineMs ?? CLAUDE_STARTUP_DEADLINE_MS
         this.instructions = config.instructions ?? emptyInstructionComposer
+        this.sessionContext = config.sessionContext
+        this.selectedRepositoryContext = config.selectedRepositoryContext
         this.onStartupTiming = config.onStartupTiming
+        this.settingSources = config.settingSources === 'sdk-default' ? undefined : config.settingSources ?? ['project', 'local']
+        this.hydratePersistedToolOutput = config.hydratePersistedToolOutput ?? true
+        this.disallowedTools = config.disallowedTools ?? defaultClaudeDisallowedToolNames
     }
 
     static create(config: ClaudeProviderConfig = {}): ClaudeProvider {
@@ -62,6 +187,8 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         session: { sessionId?: string, resume?: string }
         expectedSessionId: string
         operationOptions: AgentOperationOptions
+        // Set on the one re-spawn after a spawn declared a subscription type the credential lacks.
+        respawnedForSubscriptionType?: true
     }): Promise<ClaudeRun> {
         const { input, session, expectedSessionId, operationOptions } = params
         operationOptions.signal?.throwIfAborted()
@@ -73,11 +200,25 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         const tools = selectAgentTools(this.tools, input.tools)
         const state = createClaudeEventMapperState()
         const runtime = createClaudeToolRuntimeRef({ turnId: () => state.currentTurnId })
+        // The transcript location is a pre-input fact; session-local stores live beside it.
+        const transcriptPath = join(configDir, 'projects', encodeClaudeProjectPath(input.cwd), `${expectedSessionId}.jsonl`)
+        const steeredNotifications = ClaudeSteeredNotificationStore.open({ sessionId: input.sessionId, transcriptPath })
+        const resources = await this.openRunResources({ input, expectedSessionId, signal: abortController.signal })
+        const { nativeToolActorRun, workspaceSkills, selectedRepositoryInstructions, browserAuthBroker, browserTurnMetadata } = resources
+        const claudeProcess = new ClaudeCodeProcess()
+        const declaredSubscriptionType = this.auth ? fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) : undefined
+        const runtimeMcpServers = toClaudeMcpServers({
+            tools,
+            runtime,
+            signal: abortController.signal,
+        })
         const sdkOptions: Options = removeUndefined({
             abortController,
             cwd: input.cwd,
-            settingSources: ['project', 'local'],
-            env: this.environment,
+            // Spawn is not delayed for the credential: before the first acquisition the declared type
+            // is the bootstrap's hint, which is re-checked below once the credential is acquired.
+            env: this.auth ? claudeRunEnvironment(this.environment, this.auth, declaredSubscriptionType) : this.environment,
+            settingSources: this.settingSources,
             model: input.model,
             thinking: { type: 'adaptive', display: 'summarized' },
             effort: input.reasoningEffort,
@@ -89,29 +230,62 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             permissionMode: 'bypassPermissions',
             allowDangerouslySkipPermissions: true,
             tools: { type: 'preset', preset: 'claude_code' },
-            systemPrompt: { type: 'preset', preset: 'claude_code', append: this.instructions({ provider: 'claude', tools }) },
-            disallowedTools: ['AskUserQuestion', 'EnterPlanMode', 'ExitPlanMode', 'NotebookEdit', 'EnterWorktree', 'ExitWorktree'],
-            mcpServers: toClaudeMcpServers({
-                tools,
-                runtime,
-                signal: abortController.signal,
-            }),
-            allowedTools: ['Bash', ...claudeAllowedToolNames(tools)],
-            hooks: claudeToolActorHooks(tools),
+            systemPrompt: { type: 'preset', preset: 'claude_code', append: input.instructions ?? this.instructions({ provider: 'claude', tools }) },
+            disallowedTools: [...this.disallowedTools],
+            mcpServers: {
+                ...(this.desktop && browserAuthBroker && browserTurnMetadata
+                    ? claudeDesktopMcpServers({ desktop: this.desktop, environment: this.environment, browserAuthSocketPath: browserAuthBroker.socketPath, turnMetadataPath: browserTurnMetadata.path })
+                    : {}),
+                ...runtimeMcpServers,
+                ...(nativeToolActorRun ? { [nativeToolActorRun.mcpServer.name]: nativeToolActorRun.mcpServer.config } : {}),
+            },
+            plugins: workspaceSkills
+                ? [
+                        ...(this.skills?.imagePlugin ? [{ type: 'local' as const, path: this.skills.imagePlugin.path }] : []),
+                        { type: 'local' as const, path: workspaceSkills.pluginPath },
+                    ]
+                : undefined,
+            allowedTools: ['Bash', ...claudeNativeWorkToolNames, ...claudeAllowedToolNames(tools), ...(nativeToolActorRun?.toolNames ?? [])],
+            hooks: mergeClaudeToolHooks(
+                claudeToolActorHooks(tools),
+                nativeToolActorRun
+                    ? claudeNativeToolActorHooks({
+                            expectedSessionId,
+                            toolNames: nativeToolActorRun.toolNames,
+                            register: nativeToolActorRun.register,
+                            finish: nativeToolActorRun.finish,
+                        })
+                    : undefined,
+                claudeSteeredNotificationHooks(steeredNotifications),
+                selectedRepositoryInstructions.hooks(),
+                this.desktop && browserTurnMetadata
+                    ? claudeBrowserTurnMetadataHooks({
+                            serverName: this.desktop.browserAuth.serverName,
+                            record: async () => await browserTurnMetadata.record({ sessionId: expectedSessionId, turnId: state.currentTurnId }),
+                        })
+                    : undefined,
+            ),
             pathToClaudeCodeExecutable: this.executable,
+            spawnClaudeCodeProcess: claudeProcess.spawn,
         })
 
         const recordStartup = createClaudeStartupTiming(this.onStartupTiming)
-        const query = queryClaude({ prompt: inputQueue, options: sdkOptions })
-        recordStartup('query_created')
-        if (this.onStartupTiming)
-            observeClaudeControlInitialization(query.initializationResult(), recordStartup)
+        let query: Query
+        try {
+            query = queryClaude({ prompt: inputQueue, options: sdkOptions })
+            recordStartup('query_created')
+            if (this.onStartupTiming)
+                observeClaudeControlInitialization(query.initializationResult(), recordStartup)
+        }
+        catch (error) {
+            await closeRunResources(resources)
+            throw error
+        }
         try {
             // Binding metadata comes from pre-input facts only: the live runtime emits system/init
             // only after the first user message, so the run validates identity/config on the first
             // input (init barrier). Observed runtime configuration arrives via session.started /
             // session.configured after that validation.
-            const transcriptPath = join(configDir, 'projects', encodeClaudeProjectPath(input.cwd), `${expectedSessionId}.jsonl`)
             const metadata = {
                 provider: 'claude' as const,
                 sessionId: input.sessionId,
@@ -120,40 +294,181 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
                 model: firstClaudeModelId(input.model),
                 transcriptPath,
             }
-            const userInputRequests = await UserInputRequestStore.open({
-                sessionId: metadata.sessionId,
-                rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
-            })
+            // The SDK spawns the CLI and sends the `initialize` control request inside query(); its
+            // response needs no user input. Awaiting it means an opened run, including a supervisor
+            // prewarm, holds a CLI that has finished startup, so the first prompt skips that stall.
+            // This is not system/init, which still arrives only after the first input. The
+            // credential is acquired alongside, so an account needing reauth fails the open.
+            const [userInputRequests, initialization, , sessionContext] = await Promise.all([
+                UserInputRequestStore.open({
+                    sessionId: metadata.sessionId,
+                    rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+                }),
+                awaitClaudeInitialization({ query, signal: abortController.signal, deadlineMs: this.startupDeadlineMs }),
+                this.auth?.acquire({ signal: abortController.signal }),
+                pendingSessionContext({ compose: this.sessionContext, sessionWebUrl: input.sessionWebUrl, resumedTranscriptPath: session.resume === undefined ? undefined : transcriptPath }),
+            ])
+            // A CLI told a Pro/Max type that the acquired account does not have (a stale bootstrap
+            // hint, or an account replaced since) would skip that account's policy fetches for its
+            // lifetime; it has had no input yet, so it is replaced once before the run is published.
+            if (this.auth && declaredSubscriptionType !== undefined && declaredSubscriptionType !== fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) && !params.respawnedForSubscriptionType) {
+                query.close()
+                inputQueue.close()
+                await claudeProcess.terminate()
+                await closeRunResources(resources)
+                return await this.openRun({ ...params, respawnedForSubscriptionType: true })
+            }
 
-            const run = new ClaudeRun({
+            let unsubscribeAuthFailures = (): void => undefined
+            let run: ClaudeRun | undefined
+            const skillCatalog = new ClaudeSkillCatalog({
+                pluginScopes: new Map([
+                    ...(this.skills?.imagePlugin ? [[this.skills.imagePlugin.name, 'user'] as const] : []),
+                    ...(workspaceSkills ? [[claudeWorkspaceSkillsPluginName, 'repository'] as const] : []),
+                ]),
+                emit: draft => run?.pushEvent(draft),
+            })
+            skillCatalog.publish(initialization.commands)
+            run = new ClaudeRun({
                 metadata,
                 query,
                 userInputRequests,
                 input: inputQueue,
                 eventMapperState: state,
-                recordStartup,
                 init: {
                     expectedSessionId,
                     requestedModel: input.model,
                     reasoningEffort: input.reasoningEffort,
                     environment: this.environment,
                 },
+                steeredNotifications,
+                sessionContext,
+                process: claudeProcess,
+                workspace: {
+                    skills: workspaceSkills,
+                    repositoryRoots: input.workspaceRepositoryRoots,
+                    catalog: skillCatalog,
+                    instructions: selectedRepositoryInstructions,
+                },
+                onFinished: async () => {
+                    unsubscribeAuthFailures()
+                    await closeRunResources(resources)
+                },
+                recordStartup,
+                hydratePersistedToolOutput: this.hydratePersistedToolOutput,
             })
+            const openedRun = run
+            // The proxy owns the credential; a failure it cannot retry away ends this run typed.
+            if (this.auth)
+                unsubscribeAuthFailures = this.auth.failures.subscribe(failure => openedRun.failActiveTurnAndEndRun(failure))
             runtime.attach({
-                metadata: run.metadata,
-                requestUserInput: async request => await run.requestUserInput(request),
+                metadata: openedRun.metadata,
+                requestUserInput: async request => await openedRun.requestUserInput(request),
             })
-            run.begin()
-            return run
+            openedRun.begin()
+            return openedRun
         }
         catch (error) {
             query.close()
             inputQueue.close()
+            // A failed open (for example a missed initialize deadline) must not leave its CLI behind.
+            await claudeProcess.terminate()
+            await closeRunResources(resources)
+            throw error
+        }
+    }
+
+    // Run-owned resources opened before the CLI spawns; every failure path and run end closes them.
+    private async openRunResources(input: {
+        input: AgentSessionOpenInput<'claude'> | AgentSessionResumeInput<'claude'>
+        expectedSessionId: string
+        signal: AbortSignal
+    }): Promise<ClaudeRunResources> {
+        const opened: Partial<ClaudeRunResources> = {}
+        try {
+            if (this.skills) {
+                const workspaceSkills = opened.workspaceSkills = await ClaudeWorkspaceSkills.create(join(this.skills.workspacePluginDirectory, randomUUID()))
+                // Repositories may still be initializing; prepareWorkspace re-syncs after the Git baseline.
+                await workspaceSkills.sync(input.input.workspaceRepositoryRoots)
+            }
+            // Published before the CLI spawns: Claude Code reads instruction files once per process.
+            const selectedRepositoryInstructions = await ClaudeSelectedRepositoryInstructions.open({ cwd: input.input.cwd, repositoryRoots: input.input.workspaceRepositoryRoots, sharedContext: this.selectedRepositoryContext })
+            if (this.desktop) {
+                // The broker listens now but binds a Codex account only when Browser Use first asks.
+                opened.browserAuthBroker = await CodexBrowserAuthBroker.open({
+                    executable: this.desktop.browserAuth.codexExecutable,
+                    cwd: input.input.cwd,
+                    environment: this.environment,
+                    auth: new LazyCodexRunAuth(this.desktop.browserAuth.codexAuth),
+                })
+                opened.browserTurnMetadata = await ClaudeBrowserTurnMetadata.open()
+            }
+            if (this.nativeToolActorBridge)
+                opened.nativeToolActorRun = await this.nativeToolActorBridge.openRun({ sessionId: input.expectedSessionId, signal: input.signal })
+            return { workspaceSkills: opened.workspaceSkills, selectedRepositoryInstructions, browserAuthBroker: opened.browserAuthBroker, browserTurnMetadata: opened.browserTurnMetadata, nativeToolActorRun: opened.nativeToolActorRun }
+        }
+        catch (error) {
+            await closeRunResources(opened)
             throw error
         }
     }
 }
 
+interface ClaudeRunResources {
+    nativeToolActorRun: ClaudeNativeToolActorRun | undefined
+    workspaceSkills: ClaudeWorkspaceSkills | undefined
+    selectedRepositoryInstructions: ClaudeSelectedRepositoryInstructions
+    browserAuthBroker: CodexBrowserAuthBroker | undefined
+    browserTurnMetadata: ClaudeBrowserTurnMetadata | undefined
+}
+
+async function closeRunResources(resources: Partial<ClaudeRunResources>): Promise<void> {
+    await Promise.all([
+        resources.nativeToolActorRun?.close().catch(() => undefined),
+        resources.browserAuthBroker?.close().catch(() => undefined),
+        resources.browserTurnMetadata?.close().catch(() => undefined),
+        resources.workspaceSkills?.remove().catch(() => undefined),
+    ])
+}
+
+async function awaitClaudeInitialization(input: { query: Query, signal: AbortSignal, deadlineMs: number }): Promise<SDKControlInitializeResponse> {
+    input.signal.throwIfAborted()
+    let onAbort: (() => void) | undefined
+    let deadline: ReturnType<typeof setTimeout> | undefined
+    try {
+        return await Promise.race([
+            input.query.initializationResult(),
+            new Promise<never>((_, reject) => {
+                onAbort = () => reject(input.signal.reason)
+                input.signal.addEventListener('abort', onAbort, { once: true })
+                deadline = setTimeout(() => reject(new AgentProviderLaunchError({
+                    message: `Claude Code did not finish its initialize handshake within ${input.deadlineMs}ms.`,
+                    retryable: true,
+                })), input.deadlineMs)
+            }),
+        ])
+    }
+    finally {
+        clearTimeout(deadline)
+        if (onAbort)
+            input.signal.removeEventListener('abort', onAbort)
+    }
+}
+
+function claudeRunEnvironment(environment: Record<string, string | undefined>, auth: ClaudeProviderAuth, subscriptionType: string | undefined): Record<string, string | undefined> {
+    const runEnvironment = { ...environment }
+    for (const key of inheritedClaudeCredentialKeys) delete runEnvironment[key]
+    runEnvironment.ANTHROPIC_BASE_URL = auth.baseUrl
+    runEnvironment.CLAUDE_CODE_OAUTH_TOKEN = auth.oauthToken
+    if (subscriptionType !== undefined)
+        runEnvironment.CLAUDE_CODE_SUBSCRIPTION_TYPE = subscriptionType
+    return runEnvironment
+}
+
+function fetchFreeSubscriptionType(subscriptionType: string | null): string | undefined {
+    return subscriptionType !== null && claudeFetchFreeSubscriptionTypes.has(subscriptionType) ? subscriptionType : undefined
+}
+
 function firstClaudeModelId(...values: Array<string | null | undefined>): ClaudeModelId | undefined {
     for (const value of values) {
         const parsed = claudeModelIdSchema.safeParse(value)