ClaudeAgentContext wraps the Claude Code CLI client via the Claude Agent SDK (claude_agent_sdk). It automatically injects d:spatch platform tools as an MCP server, augments your system prompt with platform instructions, and bridges the full response stream — messages, tool use, thinking blocks, and token usage — back to the d:spatch app.

Authentication

ClaudeAgentContext uses Claude Code CLI sessions for authentication. No API key is needed — instead, mount the credentials file from your host machine into the container:

dspatch.agent.yml

required_mounts:
  - /root/.claude/.credentials.json

When creating a workspace, d:spatch prompts you for the host path. On most systems this is ~/.claude/.credentials.json.

Active session required

You must have an active Claude Code session on the host machine. The containerized agent inherits your session credentials via the mounted file.

Full example

agent.py

from claude_agent_sdk import ClaudeAgentOptions
from dspatch import ClaudeAgentContext, DspatchEngine

dspatch = DspatchEngine()

@dspatch.agent(ClaudeAgentContext)
async def my_agent(prompt: str, ctx: ClaudeAgentContext):
    ctx.setup(
        system_prompt="You are a helpful coding assistant.",
        authority=(
            "You may freely refactor code, fix bugs, and write tests. "
            "You must escalate any changes to the public API surface, "
            "database schema migrations, and dependency upgrades."
        ),
        options=ClaudeAgentOptions(
            model="claude-sonnet-4-5-20250929",
            max_turns=200,
        ),
    )
    async with ctx:
        while True:
            try:
                await ctx.run(prompt)
            except Exception as e:
                ctx.log(f"Error: {e}", level="error")
            prompt = yield
            if prompt is None:
                break

dspatch.run()

Lifecycle

`ctx.setup()`

Stores your system prompt, authority boundaries, and ClaudeAgentOptions. Call this once before entering the context manager. It does not create the client yet.

ctx.setup(
    system_prompt="You are a senior backend engineer.",
    authority="You may refactor code and fix bugs. Escalate API changes.",
    options=ClaudeAgentOptions(model="claude-sonnet-4-5-20250929", max_turns=200),
)

`async with ctx:`

Creates the Claude SDK client. Your system prompt is augmented with d:spatch platform instructions — workspace paths, inquiry tools, and coordination tools are injected automatically. An MCP server with d:spatch tools is added to the client options. The working directory defaults to the workspace path.

`await ctx.run(prompt)`

Sends the prompt to Claude and iterates the response stream. Text is streamed token-by-token as partial messages. Thinking content is emitted as activities. Tool use is logged. Token usage is recorded automatically.

`prompt = yield`

Suspends the generator and waits for the next user message. When the user sends a new message, execution resumes with the new prompt. Yield None to end the session.

System prompt augmentation

Your system prompt is automatically extended with d:spatch platform instructions. This includes workspace directory paths, available inquiry tools, coordination tools for inter-agent communication, and authority boundaries. You never need to document these in your system prompt yourself — the context handles it.

Authority

The optional authority parameter defines what the agent may decide autonomously versus what it must escalate via the inquiry system.

ctx.setup(
    system_prompt="You are a senior backend engineer.",
    authority=(
        "You may freely refactor code, fix bugs, and write tests. "
        "You must escalate any changes to the public API surface, "
        "database schema migrations, and dependency upgrades."
    ),
)

When authority is omitted, the agent receives generic escalation guidelines — it has full autonomy for routine decisions but is instructed to escalate significant architectural choices and ambiguous requirements.

Raw client access

Inside async with ctx:, the ctx.client property exposes the underlying Claude SDK client. Use it when you need low-level control beyond ctx.run():

async with ctx:
    # Direct access to the Claude SDK client
    await ctx.client.query("What files are in the workspace?")
    async for message in ctx.client.receive_response():
        ...

ClaudeAgentContext

On this page