[FEATURE] Dynamic working directory switching for instance pooling

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When deploying Claude Agent SDK in a server-side environment handling multiple concurrent users, we face critical performance bottlenecks:

1. Slow Initialization Per Instance

Each new SDK instance initialization takes 20-30+ seconds (related: #2166, #3044). For a server handling concurrent requests, this latency is unacceptable:

Initial user requests timeout or have poor UX
Cannot achieve target response time of < 2s
Resource waste during initialization

1. High Resource Consumption with Multiple Sessions

Running separate instances per session leads to:

Excessive memory/CPU usage as concurrent sessions grow
Scaling challenges for multi-tenant deployments
Increased infrastructure costs

1. No Instance Reuse Mechanism

Currently, there's no official way to:

Keep SDK processes in a "warm" state between different user sessions
Reuse initialized instances across different contexts
Dynamically change the working directory for an active instance

Proposed Solution

Feature Request: Dynamic Tool Directory Switching
Proposed API
Python:
pythonfrom claude_agent_sdk import ClaudeSDKClient

Initialize once (warm pool)

client = ClaudeSDKClient()

Dynamically switch working directory per session

client.set_working_directory("/workspace/user_session_1")
response1 = client.send_message("Analyze this project")

Reuse same instance for different session

client.set_working_directory("/workspace/user_session_2")
response2 = client.send_message("Debug this code")
TypeScript:
typescriptimport { ClaudeSDKClient } from '@anthropic-ai/claude-code';

const client = new ClaudeSDKClient();

// Switch context per session
await client.setWorkingDirectory('/workspace/user_session_1');
const response1 = await client.sendMessage('Analyze this project');

await client.setWorkingDirectory('/workspace/user_session_2');
const response2 = await client.sendMessage('Debug this code');
Benefits

Instance Pooling: Maintain a pool of pre-warmed SDK instances (e.g., 5-10 processes) that can be dynamically assigned to incoming requests
Eliminate Cold Start: Reduce request latency from 20-30s to < 1s
Better Resource Utilization: Maintain fewer processes while serving more concurrent users
Horizontal Scalability: Enable efficient load balancing across server instances

Implementation Considerations

Isolation: Ensure complete isolation of file operations between directory switches
State Reset: Provide option to reset shell environment/context when switching directories
Safety: Validate directory paths and permissions before switching
Backwards Compatibility: Add as opt-in feature without breaking existing APIs

Alternative Solutions

If dynamic directory switching is architecturally challenging, other approaches that would help:

Significantly Faster Initialization (< 1s target instead of 20-30s)
Built-in Instance Pooling: SDK-managed warm instance pool with automatic lifecycle management
Lightweight Reset API: Method to reset instance state without full reinitialization
Multi-Session Mode: Built-in support for isolated sessions within a single process

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_