The whole hunk
from line 16, old and new numbered
/
lines
from line 16
1616
1717<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-sdk/hosting-subprocess-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=3fdeff3d7f44b2b67762668acfbb25f5" className="hidden dark:block" alt="Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess-dark.svg" />
1818
19One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application's working directory, so pass `cwd` on each `query()` call when sessions need separate filesystems:
19One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application's working directory. When sessions need separate filesystems, pass a distinct `cwd` in the options of each session's `query()` call:
2020
2121<CodeGroup>
2222 ```typescript TypeScript theme={null}
23 query({ prompt, options: { cwd: "/work/session-a" } })
23 import { query } from "@anthropic-ai/claude-agent-sdk";
24
25 for await (const message of query({
26 prompt: "Summarize the files in this directory",
27 options: { cwd: "/work/session-a" },
28 })) {
29 console.log(message);
30 }
2431 ```
2532
2633 ```python Python theme={null}
27 query(prompt=prompt, options=ClaudeAgentOptions(cwd="/work/session-a"))
34 import asyncio
35
36 from claude_agent_sdk import ClaudeAgentOptions, query
37
38
39 async def main():
40 async for message in query(
41 prompt="Summarize the files in this directory",
42 options=ClaudeAgentOptions(cwd="/work/session-a"),
43 ):
44 print(message)
45
46
47 asyncio.run(main())
2848 ```
2949</CodeGroup>
3050
51The TypeScript examples on this page use top-level `await`, so save them as `.mts` files or set `"type": "module"` in `package.json`.
52
3153### State that lives on local disk
3254
3355Three kinds of agent state live on the container's filesystem by default. None of them survive a container restart, a scale-down, or a move to a different node.
from line 74
5274
5375Example workloads include bug investigation and fix, invoice and receipt extraction, document translation, and media transformation.
5476
55The container runs a one-shot entrypoint that calls the SDK and exits. In TypeScript, save the file as `entrypoint.mts` or set `"type": "module"` in `package.json` so top-level `await` is available.
77The container runs a one-shot entrypoint that reads the task from the `TASK_PROMPT` environment variable, calls the SDK, and exits.
5678
5779<CodeGroup>
5880 ```typescript TypeScript theme={null}
from line 105
83105 ```
84106</CodeGroup>
85107
108The script prints each message as it arrives, including a result message whose `subtype` is `success` when the task completes within the turn limit. If the task hits the 20-turn limit instead, the result message's `subtype` is `error_max_turns` and the `query()` call raises an error after yielding it, so wrap the loop in a try block if the container needs to exit cleanly. See [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result) for the error subtypes.
109
86110### Long-running sessions
87111
88112Run persistent container instances, often hosting multiple SDK processes per container, to serve ongoing work. Best for agents that take autonomous action, serve content, or handle high-volume message streams.
from line 336
312336
313337| Limitation | What to do |
314338| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
315| No top-level session timeout | A session does not time out on its own. Set `maxTurns` in `Options` to bound how many tool-use round trips the agent takes before stopping. |
339| No top-level session timeout | A session does not time out on its own. Set `maxTurns` in TypeScript or `max_turns` in Python to bound how many tool-use round trips the agent takes before stopping. |
316340| Memory growth over long sessions | Cap session length or recycle subprocesses periodically. See [Scaling and concurrency](#scaling-and-concurrency). |
317341| Large parallel-subagent fanouts can hit rate limits | Break work into smaller batches rather than issuing one wide dispatch. |
318342| No per-subagent wall-clock deadline | Cap each [subagent](/docs/en/agent-sdk/subagents) with `maxTurns` in its `AgentDefinition`. For background subagents only, `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` sets a stall watchdog that fires when a `run_in_background` subagent stops producing output; it is not a total-runtime deadline. |