[FEATURE] Scripted session access: capability-scoped channel for spawned scripts.

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

Problem

When Claude Code drives multi-step work against MCP servers or the local filesystem, every iteration has to flow through the agent's context. A bulk fetch of 100 pages = 100 tool calls, each one a full conversational round-trip; large responses spill to disk, but the next call still re-enters the agent. Scripts spawned via Bash can execute shell, but they have no channel back to the session — they can't invoke MCP tools, can't use built-ins like Read/Edit/Glob, and can't ask the agent for judgment mid-run. So any workflow that combines mechanical iteration with model reasoning ("fetch, check for anomalies, branch accordingly, fetch more, summarise") has to be flattened into turn-by-turn tool calls.

The cost shows up in three places: context (bloat from tool results the agent doesn't actually need to reason over), prompt cache (invalidated on every round-trip), and expressiveness (workflows that naturally want to interleave script-driven work with agent-driven judgment can't be written as a single unit). The gap is that Claude Code treats scripts and tools as parallel tracks that only meet in the agent's context — there is no primitive for a script to participate in the session while it runs.

Proposed Solution

Proposal: Scripted Session Access for Claude Code

Concept

Claude Code should let an external script, spawned by the agent, talk back to the active session through a capability-scoped channel. The script can invoke MCP tools, use built-ins, and — most importantly — hand control back to the agent at checkpoints mid-execution, then resume.

Today, tool calls and external scripts are parallel tracks that only meet in the agent's context. A script can run shell, but it can't reach the MCP session or built-ins, so every MCP iteration becomes an agent-level tool call. That burns context, invalidates prompt cache, and makes workflows like "fetch → check → branch → fetch more" impossible to express in one go.

The proposed mechanism: on session start, Claude Code opens a local socket. When the agent spawns a script, it mints a short-lived capability token declaring what the script may do. A claude client binary on $PATH wraps the protocol. The session validates every call against the token.

What it enables

• Loops and bulk work without context bloat — only the summaries the script surfaces reach the agent.
• Conversation-flow interleaving — scripts can pause, ask the agent for judgment, and branch on the reply.
• Built-ins + memory + sub-agents available from inside the script.
• One-prompt approval — user sees the declared capability set up front instead of streaming per-call approvals.

Examples

1. Bulk fetch with interleaved judgment

# page 1
data = claude.tool("Entity_List", {...})
verdict = claude.analyze("Page 1 — anything odd?", data[:100])

if verdict.action == "investigate":
    detail = claude.tool("Entity_Get", {"id": verdict.target})
    claude.analyze("Details:", detail)

for page in range(2, 100):
    claude.tool("Entity_List", {"from": page*50})

Agent spends cycles on judgment, script handles the 100 pages. Context sees two analyses, not 100 tool calls.

2. Cross-source reconciliation

users   = claude.tool("EntityA_List", {...})
schedules = claude.tool("EntityB_List", {...})
mismatches = [u for u in users if u.id not in {s.owner for s in schedules}]
claude.analyze("Orphaned users:", mismatches)

Two large fetches + a join happen locally; only the mismatch list enters context.

3. Checkpointed refactor

files = claude.glob("src/**/*.ts")
for f in files:
    before = claude.read(f)
    patched = transform(before)
    decision = claude.analyze(f"Preview patch for {f}:", diff(before, patched))
    if decision.approve:
        claude.edit(f, patched)

Agent reviews each patch inline; script drives the iteration.

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_