Self-improving AI Employees for everyone
Claude Code interactive mode (subprocess + stream-json)
TL;DR.
ClaudeSessionPoolkeeps a warmclaudesubprocess per session key (the RFC-0002 conversation keycontext_bridge.pool_keywhen a Context node is wired; the legacysimpleMemory.node_idoninput-memorygraphs —bound_keyinAICliService.run_batch) and drives it with the same flags Anthropic's own VSCode extension uses — stdio pipes,--output-format stream-json --input-format stream-json --verbose --ide. Multi-turn happens by writing newline-delimited JSON toproc.stdinof the long-lived subprocess. Events arrive onproc.stdout. The on-disk JSONL is no longer the runtime contract — claude writes it for--resumepersistence but theresultevent is stdout-only in stream-json mode.
Why we cut over from -p
Pre-cutover OpenCompany spawned claude -p --output-format stream-json
and parsed NDJSON events on stdout. Two reasons to leave -p:
- Anthropic billing change (2026-06-15). Per
code.claude.com/docs/en/headless, subscription plans billclaude -pand Agent-SDK usage from a separate "monthly Agent SDK credit." The expectation was that the interactive entrypoint (claude-vscode, notsdk-cli) stays on the subscription's interactive bucket once-pis dropped. This is unverified: nothing in OpenCompany checks which entrypoint or billing bucket the CLI reports for these spawns. - Match how Anthropic itself drives
claudeprogrammatically. The VSCode extension ($VSCODE_EXT_DIR/anthropic.claude-code-2.1.140-<platform>/extension.js, line 156) spawns claude with exactly four flags (--output-format stream-json --input-format stream-json --verbose --ide) and never emits-p. That's the wire we reuse.
Architecture
One transport (asyncio.create_subprocess_exec with stdin/stdout/stderr=PIPE),
one protocol (line-delimited stream-json events on stdout). No PTY.
A background stdout_reader_task parses each line and dispatches via
_handle_stream_event.
| Layer | Mechanism |
|---|---|
| Transport | asyncio.subprocess.Process with stdio pipes — same on POSIX + Windows |
| Send turn | proc.stdin.write(json.dumps({"type":"user","message":{"role":"user","content":...}}) + "\n") |
| Read events | proc.stdout.readline() loop → json.loads(line) → _handle_stream_event |
| Completion detect | stream-json event where type == "result" (set via provider.is_final_event); stdout EOF also wakes the turn, which then fails with the child's exit code |
Context reset (/clear equivalent) |
kill subprocess + drop captured UUID — stream-json input has no slash-command path (confirmed in VSCode extension source). Primitive: pool.clear (no production caller today); Context-bound sessions are reset by terminate_conversations and the generation fence in acquire |
| Crash recovery | acquire() checks process.returncode; respawns with --resume <captured_uuid> so the same on-disk JSONL keeps growing. Only while the dead entry is still in the pool — an idle reap or LRU eviction removes the entry and its UUID |
Code layout
Per the canonical plugin-folder pattern, every claude-specific
module lives under server/nodes/agent/claude_code_agent/. The
generic framework under server/services/cli_agent/ owns only
the shared dispatcher + per-provider registries that the plugin
self-registers into on import.
server/nodes/agent/claude_code_agent/
├── __init__.py # plugin class + 4 self-registration lines (provider, pool, materialiser, ws handlers)
├── _provider.py # AnthropicClaudeProvider — interactive_argv emits the four VSCode-pattern flags
├── _pool.py # ClaudeSessionPool — subprocess-based warm-process reuse
├── _skills.py # materialise_skills — per-workflow SKILL.md materialisation + live diff
├── _oauth.py # claude_binary_path, claude_auth_* — project-local install + the documented CLI subcommands
└── _handlers.py # claude_code_login / claude_code_logout WS handlers
server/services/cli_agent/ (generic framework — shared by all CLI plugins)
├── factory.py # register_provider / register_session_pool / register_skill_materialiser registries
├── service.py # AICliService.run_batch — dispatcher; every claude task goes to the pool (registry lookup)
├── session.py # AICliSession — generic PTY + JSONL path; NOT used for claude (GitHub #133 / #134)
├── mcp_server.py # BatchContext + FastMCP bridge (shared by every CLI provider)
├── context_bridge.py # SpecializedAgentContextBridge — Context pool_key, transcript-in-prompt, record_turn
├── workflow_tools.py / worktree.py / lockfile.py / jsonl_watcher.py / config.py / protocol.py / types.py / _cli_auth.py
└── _handlers.py # codex WS handlers only (will move once codex_agent migrates)
argv shape
Built by AnthropicClaudeProvider.interactive_argv.
Stable head, task-driven tail:
claude
--output-format stream-json
--input-format stream-json
--verbose
--ide
[--mcp-config <json> --strict-mcp-config]
--model <name>
[--resume <UUID> | --continue | --session-id <UUID>]
--allowedTools <csv>
--permission-mode dontAsk
[--append-system-prompt <text>]
[--effort low|medium|high]
[--add-dir <path>]...
[--disallowedTools <csv>]
[--agent <name>]
Notable absences (intentional):
| Flag | Reason omitted |
|---|---|
-p / --print |
Drops us into the SDK billing bucket; the whole point of the cutover. |
Positional prompt (-- "<text>") |
Prompt arrives via stdin in stream-json input mode; an argv positional would double-send the first turn. interactive_argv's include_prompt parameter is kept for back-compat but ignored. |
--continue |
Not set by the node's own continuity logic. The CLI reference says it skips sessions created non-interactively (-p / stream-json input), which is exactly what the pool spawns, so it never found the prior conversation. Memory-bound runs pass --resume <last_session_id> instead (the UUID persisted on the memory node by _persist_memory). It is still emitted when a task in the node's tasks list sets continue_session: true, because ClaudeTaskSpec keeps the field. |
--include-partial-messages, --include-hook-events, --max-turns, --max-budget-usd, --fallback-model |
All -p-only. ClaudeTaskSpec keeps the fields for back-compat; they're silently dropped here. External cost / turn caps are a Phase 2 follow-up. |
Emitted for session identity:
| Flag | When |
|---|---|
--session-id <UUID> |
Cold spawn with no continuity flag. ClaudeSessionPool._spawn mints a uuid4 so current_session_uuid is known before the first stream event; crash-recovery respawns then always have a UUID to --resume. The CLI requires a valid UUID and rejects one already in use. |
--resume <UUID> |
Crash-recovery respawn of a pooled session, and every memory-bound run that has a persisted last_session_id. Works from any directory on the pinned CLI (2.1.223+). |
--permission-mode dontAsk is the documented mode for "only
pre-approved tools, no prompts" per
code.claude.com/docs/en/permission-modes:
a call that would otherwise prompt is denied instead (non-interactive
automation has no human at the keyboard to click "Allow"). Only calls
matching --allowedTools run, plus read-only Bash commands, which the
same doc says run without a rule. --allowedTools pre-approves; it
does not remove Claude's other built-ins from the model's context
(--tools / --disallowedTools do that, and neither is emitted by
default), so the model can still call Read, Bash and the rest and
receive a denial. The earlier bypassPermissions default "skips the
permission layer entirely" (same doc, §"Skip all checks"), which
turned --allowedTools / --disallowedTools into documentation-only
fields and let claude's built-in Read / Edit / Bash /
Glob / Grep / Write / Skill / WebSearch / WebFetch fire
regardless of wiring. acceptEdits was the prior config default but
would prompt for any non-Edit tool — hanging the headless agent.
dontAsk is the mode that combines no prompts with denial of
everything not pre-approved.
Session pool — warm-process reuse
ClaudeSessionPool is
keyed by the RFC-0002 conversation key context_bridge.pool_key
((workflow_id, agent_node_id, generation)), falling back to the legacy
simpleMemory.node_id only on input-memory graphs (bound_key in
AICliService.run_batch). Each entry is a
PooledClaudeSession carrying the live asyncio.subprocess.Process,
the session UUID (set at spawn from the --session-id the pool mints
or the --resume UUID; filled in from the first event that has one
only when neither flag was passed, i.e. a task forced --continue),
the MCP bearer token embedded in the spawn argv, a turn_lease and a
narrower lock (both asyncio.Lock), an asyncio.Event signalled by
the stdout reader on result, and a per-turn event buffer.
| Operation | Behaviour |
|---|---|
acquire(memory_node_id, ...) |
For a Context key (workflow_id, agent_node_id, generation), first terminates any entry for the same workflow and agent with a different generation (reason generation_changed), so a Reset's generation bump fences the old process. Then: live + healthy entry → wait for its turn_lease, re-check it is still the pooled entry, and warm-reuse it (_prepare_warm_reuse rebinds the MCP BatchContext and applies the skill diff). Live + dead entry → drop, capture its UUID, spawn fresh with --resume <UUID> so the same JSONL keeps growing. No entry → cold spawn. At cap → LRU evict (skipping entries whose lock or turn_lease is held). Returns with the turn_lease held. |
send_turn(session, prompt, ...) |
Holds session.lock. Clears result_event + events_this_turn. Writes one stream-json line to proc.stdin, awaits result_event (timeout = 600s default). Returns a SessionResult built from the per-turn event buffer. Persists result.session_id onto session.current_session_uuid. |
clear(session, ...) |
Kill the subprocess, drop the captured UUID. Next acquire spawns fresh with a newly minted --session-id. Emits claude.session.cleared. Has no production caller today. |
release(session) |
Releases the turn_lease and updates last_used_at so the reaper measures idle from now. |
terminate(memory_node_id) |
Force-drop a specific entry: close stdin → 2s grace → proc.kill() → cancel reader/drain tasks. |
terminate_conversations(workflow_id, ...) |
Terminate the Context-keyed entries of a workflow (optionally one agent); the Context panel's Clear calls it (reason conversation_cleared). |
shutdown_all() |
Stop the reaper + terminate every entry. Wire into FastAPI's lifespan shutdown. |
Lifecycle policy:
- Idle TTL 30 min (
_DEFAULT_IDLE_TTL). Background reaper task terminates pooled sessions whoselast_used_atexceeds the cap and whoselockandturn_leaseare both free. - Max size 16 (
_DEFAULT_MAX_SIZE). LRU eviction at cap (skipping in-flight entries). - Concurrency — the
turn_leaseis held fromacquirethrough the context rebind,send_turnandrelease, so a second batch cannot rebind the MCPBatchContextafter the first batch acquired the session but before its turn ran. The narrowerlockis held insidesend_turnso two calls can't interleave their stream-json lines on stdin.
Stream-json event dispatch
_handle_stream_event has three concerns:
- UUID capture. The UUID is normally known from spawn (the minted
--session-idor the--resumeUUID). Any event carryingsession_id(orsessionId) seedssession.current_session_uuidonly if it is still empty (a--continuespawn), andsend_turnoverwrites it with theresultevent's value at turn end. Crash-recovery respawns read this field to emit--resume <UUID>. - Per-turn buffering. Every event is appended to
events_this_turn. Whenprovider.is_final_event(event)returns True (i.e.event.type == "result"),result_eventis set andsend_turnreturns.SessionResultis built byAnthropicClaudeProvider.event_to_session_resultover the buffered events — same shape-pused to produce. - Native compaction forwarding.
type == "system"+subtype == "compact_boundary"events forward toCompactionService.record(...)via_record_native_compactionso the local-threshold path doesn't double-fire on claude's auto- compaction. Trigger metadata (pre_tokens,trigger: auto|manual) is preserved on the compaction record.
Continuity across process restarts
The pool's continuity model is two-layered:
- Intra-process (warm pool). Within a live subprocess, every turn
writes to the same
proc.stdinand claude itself keeps the conversation in memory. No--resumeneeded — same session UUID flows across turns. Verified: turn 113ac5819-..., turn 2 same UUID. - Cross-process (cold spawn / crash recovery). A cold spawn with no
continuity flag mints a
uuid4and emits--session-id <UUID>, so the UUID is known before the first event. Memory-bound runs emit--resume <last_session_id>(the UUID_persist_memorystored on the memory node after the previous successful run). Ifacquirefinds the pooled subprocess has died, it splices--resume <current_session_uuid>into the spec so the new subprocess continues the same on-disk JSONL. - Idle reap / LRU eviction / generation change.
_terminate_lockedpops the entry, and its UUID goes with it, so the nextacquireis a plain cold spawn with a new--session-id. Memory-bound runs still resume through the memory node'slast_session_id. Context-bound runs store no session UUID anywhere, so they start a fresh Claude session and keep only the text the context bridge renders into the prompt (see "Known gaps").
ClaudeTaskSpec carries session_id, resume_session_id and
continue_session; precedence in argv is resume, then continue, then
session-id. --continue is never set by the node: the CLI reference says
it skips sessions created non-interactively (-p / stream-json input),
which is every session the pool creates, so it silently started a fresh
conversation each batch. A stale last_session_id (claude reports
No conversation found with session ID) is cleared by _persist_memory
so the next run spawns fresh.
MCP bearer token lifecycle
claude handles its own MCP authentication. We embed the bearer in
--mcp-config at spawn time; the spawned claude uses it for the
lifetime of its process — the JSON blob (token included) is frozen
into argv and can never be rotated without respawning. The pool
stashes the spawn-time token on
PooledClaudeSession.batch_token
so subsequent batches can find and update its bound BatchContext.
Token lifecycle, three phases:
- Cold spawn.
AICliService.run_batchissues a fresh token T, callsregister_batch(T, ctx)(which adds T to_active_tokensand bumps FastMCP refcounts for eachctx.connected_toolsentry viaexpose_workflow_tools), then passes T topool.acquire. The pool spawns claude with T baked into--mcp-configargv and recordssession.batch_token = T. - Warm reuse with a changed surface. A subsequent batch issues
a NEW token T_new and registers
ctx_newagainst it. Poolacquiredetects warm reuse and callsrebind_batchon T (the persistent token claude bakes into MCP requests), transplantingctx_new'sconnected_tools/connected_skill_names/allowed_credentials/workspace_dironto T'sBatchContextin place. The diff is applied to FastMCP —unexpose_workflow_toolsdecrements refcounts for tools dropped between batches (so a disconnectedduckduckgoSearchfalls off the FastMCP tool list when its refcount hits zero),expose_workflow_toolsincrements for added tools. T_new is then immediately unregistered (it would sit orphaned otherwise — claude's argv never references it). - Termination.
_terminate_lockedcallsunregister_batch(T)so the dying subprocess's FastMCP refcounts drain cleanly on pool eviction /pool.clear/shutdown_all. Closes the long-standing leak where every pooled run permanently incremented the refcount of every wired tool.
The per-handler scope check in
workflow_tools._build_handler
reads ctx.connected_tools at call time — so even if claude's
frozen --allowedTools argv still lists a tool that's since been
disconnected, the handler returns
{"error": "...not connected to this batch", "status": 403}.
On the claude side, --permission-mode dontAsk denies a call to any
tool that is not pre-approved. The --allowedTools list is frozen in
the spawn argv, though: a tool wired after the warm process started is
exposed over MCP by the rebind but is not pre-approved, so claude
denies it until the process is respawned (see "Known gaps").
CloudEvents broadcasts
Four typed WorkflowEvent factories on
server/services/events/envelope.py,
fired via the corresponding broadcaster.broadcast_claude_session_*
methods on
server/services/status_broadcaster.py:
| Event type | When fired |
|---|---|
com.opencompany.claude.session.spawned |
Cold spawn (new subprocess) |
com.opencompany.claude.session.cleared |
Explicit pool.clear → new UUID on next acquire |
com.opencompany.claude.session.terminated |
Pool terminate (reason: idle / evicted / crashed / generation_changed / conversation_cleared / acquire_failed / shutdown / explicit) |
com.opencompany.claude.session.usage |
Each result event (per-turn cost + tokens + duration + num_turns) |
The usage event is the source of truth for the simpleMemory usage panel
— /usage is TUI-only plain text per Anthropic and not parseable.
Frontend listeners switch on envelope.type and route the inner data
payload (memory_node_id, session_uuid, cost, tokens, …) into the
store that renders the panel.
Tools and skills
Tools (MCP) — pre-approved allowlist, no claude built-ins
pre-approved. Spawn argv
carries --mcp-config <json> (HTTP transport, bearer header) +
--strict-mcp-config so the spawned claude only loads OpenCompany's
FastMCP server. The mcpServers.opencompany block sets alwaysLoad: true to opt out of MCP tool-search deferral so all
mcp__opencompany__* tools enter context at session start.
--allowedTools is the explicit pre-approval list, and it does NOT
include claude's built-in escape hatches (Read, Edit, Bash,
Glob, Grep, Write, WebSearch, WebFetch) — every workflow
already wires the equivalents (fileRead, fileModify, fsSearch,
shell, browser, perplexitySearch, …) as MCP tools, and the
built-ins were the leakage path that let the agent invoke
capabilities the workflow didn't explicitly grant. The built-ins stay
in the model's context, though: calling them is denied under
dontAsk, except read-only Bash commands, which run. The default
allowlist is:
mcp__opencompany__<node_type>per node connected to the agent'sinput-toolshandle (LLM sees their typed Pydantic schemas via FastMCP'stools/listreflection on the pluginParams).- The claude built-in
Skill— conditional, present iff at least one skill is wired through the agent'sinput-skillhandle. Paired with thematerialise_skillshelper (below) which writes the connected SKILL.md trees under<workspace_dir>/.claude/skills/(reached through--add-dir) so the built-in skill loader has something to discover. The one exception to the "no claude built-ins" rule, because the alternative (forcing the agent to load every skill through thegetSkillMCP round-trip) is materially worse UX for the common case where the workflow pre-wired which skills should be on the table. - The OpenCompany MCP infrastructure tools —
getWorkspaceFiles,listSkills,getSkill,readSkillResource,searchSkillResource,getCredential,broadcastLog(listed inAnthropicClaudeProvider.interactive_argv; defined inmcp_server._build_tools) — which are how the agent reads its workspace, discovers connected skills (when no wiring is present), pages through and searches a loaded skill's declared resources, fetches scoped credentials, and surfaces intermediate progress to the FE.
Callers wanting specific claude built-ins back in opt in per-task via
ClaudeTaskSpec.allowed_tools (the field is honored verbatim — no
auto-merge with workflow tools). Default value: empty string.
Combined with --permission-mode dontAsk, anything not pre-approved
is denied apart from read-only Bash commands (see "argv shape" above
for why bypassPermissions was the wrong default).
Skills — per-workflow workspace, live-watched, diff-based.
nodes/agent/claude_code_agent/_skills.py::materialise_skills
writes one SKILL.md tree per connected-and-enabled skill under
<workspace_dir>/.claude/skills/<name>/. The workspace dir
(~/.opencompany/workspaces/<workflow_slug>/ — Wave 14 keys it by the
human-readable slug, not the UUID id) is already passed via
--add-dir, and per the skills spec's
Automatic discovery from parent and nested directories
rule, claude scans .claude/skills/ inside every --add-dir path.
Two properties fall out:
- Per-workflow isolation. Workflow A's wired skills never bleed into workflow B's subprocess: each runs in its own worktree under its own workspace dir.
- Live add/remove. Claude live-watches the skills tree (same
skills spec, Live change detection),
so warm-reuse turns can toggle skills without respawning. Pool's
acquirecallsmaterialise_skills(workspace_dir, new_set, previous_skill_names=session.materialised_skills)to apply just the delta —rmtree'd skills disappear from claude's registry, newly-written ones become invocable. Same UX win as the MCP tool rebind.
Filesystem skills (declared under server/skills/<group>/<name>/)
are copied wholesale via shutil.copytree so scripts/ and
references/ subdirs survive. Database skills (user-created in
the UI) reconstruct the frontmatter (name, description,
allowed-tools, metadata) + the markdown body. Failure modes
are non-fatal: a skill that fails to load or write logs at WARN
and is skipped — the spawn continues. The helper is called from
ClaudeSessionPool._spawn (cold spawn) and _prepare_warm_reuse
(diff on warm reuse); AICliSession._pre_spawn still calls it for the
generic path other providers use.
Migration note. Pre-cutover code wrote SKILL.md trees into
<repo_root>/.claude/skills/ so they accumulated in the user's
actual repo. The repo's .claude/ is gitignored but visible;
future runs only write into per-workflow workspaces. Run
rm -rf .claude/skills/ once from the repo root to clean
accumulated trees — we deliberately do NOT auto-prune because
the repo's .claude/ may contain user-authored skills outside
the OpenCompany registry.
Why filesystem (not MCP). We surveyed alternatives: MCP
resources/prompts require explicit @mention//command
invocation by the user, not auto-loaded into context. Hooks fire
after skill discovery, not before. settings.json doesn't expose
per-session skill paths. Anthropic's own
Agent SDK uses
the same filesystem-first pattern. There is no programmatic
skill-injection channel — workspace-dir + live-watch is canonical.
Workspace dir — routed via --add-dir.
AICliService.run_batch
splices the per-workflow workspace
(~/.opencompany/workspaces/<workflow_slug>/, injected into ctx.raw by
workflow.py:_get_workspace_dir) into each task's add_dir list
right after task_list is built — interactive_argv already emits
--add-dir <path> per entry. Runs BEFORE the pool branch so every
pooled session gets it. Without this, the workspace is invisible to
claude: sessions spawn in a git worktree under
<workspace>/<node>/ (wt_session for bound runs, one per task
otherwise), which does not see files dropped by upstream nodes
(fileDownloader,
documentParser, code executors, etc.). Mirrors the ai_agent
pattern (the tool config built in AIService.execute_agent and
execute_chat_agent in services/ai.py —
config["workspace_dir"] = context.get("workspace_dir", "")) but
uses claude's native --add-dir instead of MCP-tool-config injection
because claude has its own filesystem tools (Read, Edit, Glob,
Grep, Write, Bash) rather than MCP-injected ones. Verified
end-to-end: a marker file dropped into a workspace is reachable via
claude's Read tool inside a pooled turn.
/usage and /compact semantics
/usage— TUI-only plain text per Anthropic. Not parseable. We surface the same data (cost, tokens, duration, num_turns) via theclaude.session.usageCloudEvent built from everyresultevent./clear— the stream-json input wire has no slash-command path (confirmed in the VSCode extension source). Context reset ispool.clear(session)— kill subprocess, drop UUID, next acquire spawns fresh./compact— emitssystem/compact_boundaryon stdout withcompact_metadata.pre_tokens+compact_metadata.trigger(auto vs manual)._handle_stream_eventforwards it toCompactionService.record(...)so the local-threshold path doesn't double-fire on claude's native auto-compaction.
Known gaps
Recorded from the code; none is fixed yet, because each fix changes how the agent runs.
- Context-bound runs lose Claude's own session after a reap, an
eviction or a generation change. The pool entry and its UUID are
dropped and no UUID is stored for Context-bound runs, so the next run
is a fresh Claude session. What survives is the stored conversation,
which holds only each turn's original prompt and final response
(
SpecializedAgentContextBridge.record_turn), not tool calls or their results. - The stored transcript is sent again on every turn.
run_batchrenders the whole stored conversation into the prompt (augment_prompt) for every Context-bound run, warm or cold. A warm process already holds the earlier turns, so it sees each earlier exchange again inside every new prompt, and the repeated part grows with the conversation. A crash-recovery--resumespawn gets the same duplication. --ideis passed with no lockfile, and the spawn inherits the backend's environment._run_pooled_turncopiesos.environwhole and adds onlyPYTHONUNBUFFERED,CLAUDE_CONFIG_DIRand the parent-run ids. When the backend was started from an editor's terminal, that editor's variables (including any IDE-integration variables) reach the CLI, where--idemay act on them. Not verified at runtime.getCredentialandbroadcastLogare visible to the model and pre-approved.getCredentialreturns the plaintext value of any credential named in the node's hiddenallowed_credentialsparameter (empty by default, so every call gets a 403); a prompt injection could ask for such a key.broadcastLoglets the model write lines into the Terminal panel. See R5 in cli_agent_canonical_patterns_rfc.md.- Warm reuse keeps the spawn-time flags.
_prepare_warm_reuserebinds only the MCPBatchContextand the materialised skill files.--model,--allowedTools(including whetherSkillis on it),--permission-mode,--append-system-prompt,--add-dirand--effortstay as they were at spawn until the process is reaped, evicted or fenced. A tool, or a first skill, wired after the spawn is exposed but not pre-approved, sodontAskdenies it. The rebind also leavesconnected_skill_descriptorsunchanged, sogetSkill,readSkillResourceandsearchSkillResourcecan work from stale skill descriptors.
What changed (historical note)
The previous iteration of this doc described a PTY transport
(pywinpty on Windows, ptyprocess on POSIX) reading events from the
on-disk session JSONL via JsonlWatcher / JsonlDirWatcher. That path
was abandoned for the pool: pywinpty's ConPTY emulation did not
deliver keystrokes to claude's Ink TUI on Windows (empirically
confirmed across four test variants). Stdio pipes + stream-json work
cross-platform and match the pattern the official Agent SDKs use. The
non-pooled AICliSession was kept as the plain-run path for a while,
but it never wrote the prompt to the child and a PTY stdin makes the
CLI reject --input-format stream-json (GitHub #133 / #134), so
AICliService.run_batch now routes every Claude task through the pool:
bound runs get a warm keyed session, unbound runs get an ephemeral
session per task (<node_id>:<turn_execution_id>:<index>) terminated
after the batch. A child that exits without a result wakes
send_turn on stdout EOF with its exit code instead of burning the
turn timeout. The CLI version is pinned via package_version in
config/ai_cli_providers.json (currently 2.1.258).