Claude Code CLI Adapter

interface ClaudeAdapterConfig {
  model:                    string;   // e.g. 'claude-sonnet-4-6'
  cwd?:                     string;   // working directory; auto-created if absent
  promptTemplate?:          string;   // prepended to every task prompt (supports {{variables}})
  env?:                     Record<string, string>; // per-agent env vars; values may be secret refs
  timeoutSec:               number;   // hard timeout before SIGTERM (default: 300)
  graceSec?:                number;   // seconds between SIGTERM and SIGKILL (default: 10)
  maxTurnsPerRun?:          number;   // passed as --max-turns N; caps agentic turns per heartbeat
  dangerouslySkipPermissions?: boolean; // dev only — bypasses Claude's permission prompts
}

You are {{agentName}} for tenant {{tenantId}}.
Always output in British English.
Run ID: {{runId}} — include this in your result header.

{ "BRAND_API_KEY": "secret:brand_api_key", "TONE": "formal" }

Worker process (Node.js)
│
│  1. ASSEMBLE INPUTS
│     buildActivityPrompt() → fullPrompt string
│     writeSkillsToTempDir() → /tmp/skills-{uuid}/
│
│  2. SPAWN SUBPROCESS
│     ┌─────────────────────────────────────────────────────────┐
│     │  child_process.spawn('claude', [...args], {             │
│     │    cwd:   agentConfig.cwd,                              │
│     │    env:   { ...process.env, ...resolvedSecrets },       │
│     │    stdio: ['pipe', 'pipe', 'pipe']  ← stdin+stdout piped │
│     │  })                                                      │
│     └─────────────────────────────────────────────────────────┘
│
│  3. DATA IN — CLI flags + stdin
│     --print -                         ← read prompt from stdin (avoids Windows quoting bugs)
│     --output-format stream-json       ← tells Claude to emit NDJSON
│     --verbose
│     --model claude-sonnet-4-6
│     --add-dir /tmp/skills-{uuid}/     ← skills dir (Claude reads files on demand)
│     --resume sess_abc123              ← optional: resume prior session
│     --max-turns 10                    ← cap agentic turns
│     --dangerously-skip-permissions    ← dev only
│     [stdin] = rendered prompt string  ← written to proc.stdin, then closed
│
│  4. DATA OUT — read from child.stdout line-by-line (NDJSON)
│     Each line is one complete JSON event. Adapter parses each line as it arrives.
│
└──────────────────────────────────────────────────────────────────

// Line 1 — always first. Adapter captures session_id here.
{ "type": "system", "subtype": "init", "session_id": "sess_abc123", "model": "claude-sonnet-4-6" }
 
// Lines 2..N — streaming text output, one chunk per line
{ "type": "assistant", "message": { "content": [{ "type": "text", "text": "## Why Your Google Ads" }] } }
{ "type": "assistant", "message": { "content": [{ "type": "text", "text": " Aren't Converting\n\n" }] } }
 
// Tool use — if the agent calls rag_search, wordpress_publish, etc.
{ "type": "tool_use", "id": "tu_001", "name": "rag_search", "input": { "query": "hot water systems", "dataset": "client_documents" } }
 
// Tool result — the control plane intercepts the tool call and returns a result
// (Claude Code's permission/tool layer handles this — adapter sees it in stream)
{ "type": "tool_result", "tool_use_id": "tu_001", "content": "[chunk 1]...[chunk 2]..." }
 
// Final event — process exits after this. Adapter reads usage here.
{ "type": "result", "subtype": "success", "result": "...", "usage": { "input_tokens": 14200, "output_tokens": 5900 }, "session_id": "sess_abc123" }

// packages/agent-engine/src/adapters/claude.ts (simplified)
 
async dispatch(request: DispatchRequest): Promise<DispatchResult> {
  const args = buildArgs(request);           // assemble CLI flags
  const child = spawn('claude', args, {
    cwd:   this.config.cwd,
    env:   await resolveEnv(this.config),
    stdio: ['pipe', 'pipe', 'pipe'],          // stdin piped (for prompt), stdout+stderr piped
  });
 
  // Write the full prompt to stdin and close — avoids Windows cmd.exe quoting bugs
  child.stdin.write(renderedPrompt, 'utf-8');
  child.stdin.end();
 
  let fullText     = '';
  let sessionId: string | null = null;
  let inputTokens  = 0;
  let outputTokens = 0;
 
  // Read stdout line by line — each line is one complete NDJSON event
  const rl = createInterface({ input: child.stdout });
 
  for await (const line of rl) {
    const event = JSON.parse(line);
 
    if (event.type === 'system' && event.subtype === 'init') {
      sessionId = event.session_id;              // ← capture session for resumption
    }
 
    if (event.type === 'assistant') {
      for (const block of event.message.content) {
        if (block.type === 'text') {
          fullText += block.text;                // ← accumulate streamed text
          this.emit('text_delta', block.text);   // ← live-stream to UI via SSE
        }
      }
    }
 
    if (event.type === 'result' && event.subtype === 'success') {
      inputTokens  = event.usage.input_tokens;
      outputTokens = event.usage.output_tokens;
    }
  }
 
  await onProcessExit(child);  // wait for clean exit (or timeout)
 
  return {
    text:         fullText,
    sessionId,
    usage:        { inputTokens, outputTokens },
    cost:         calculateCost(request.model, inputTokens, outputTokens),
    durationMs:   Date.now() - startTime,
  };
}

echo "<rendered prompt>" | claude --print - \
  --output-format stream-json --verbose \
  --model claude-sonnet-4-6 \
  --add-dir /tmp/skills-{uuid} \
  [--resume <sessionId>] \
  [--max-turns 10] \
  [--dangerously-skip-permissions]

async function withGracefulTimeout(
  child: ChildProcess,
  timeoutMs: number,
  graceMs: number
): Promise<void> {
  const sigterm = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
  const sigkill = setTimeout(() => child.kill('SIGKILL'), timeoutMs + graceMs);
  try {
    await onProcessExit(child);
  } finally {
    clearTimeout(sigterm);
    clearTimeout(sigkill);
  }
}