claude_runner_core

Workspace: assistant — claude_runner_core

Claude Code process execution with builder pattern and single execution point.

Files

File / Directory	Responsibility
`Cargo.toml`	Crate manifest: deps, features, metadata
`src/`	Builder pattern implementation: `ClaudeCommand`, types, process scanner
`tests/`	Builder API, migration validation, verification framework (31 test files)
`docs/`	Behavioral requirements: features, invariants, parameter reference
`task/`	Crate-level task tracking

Responsibility Table

Entity	Responsibility	Input→Output	Scope	Out of Scope
claude_runner_core	Claude Code process execution	ClaudeCommand Config → Process Output	Command building, process spawning, output capture, token limits	❌ Session storage paths → `claude_profile`❌ Continuation detection → `claude_profile`❌ Context injection → `dream_agent`❌ Parameter parsing → `dream_agent`❌ Session strategy → `dream_agent`

Scope

Responsibility:

Claude Code process execution (Command::new("claude"))
Builder pattern API (ClaudeCommand::new().with_*())
Token limit configuration (200K default)
Process output capture (stdout/stderr)
Single execution point (duplication = 1x)

In Scope:

ClaudeCommand::new() builder entry point
with_working_directory(), with_max_output_tokens(), with_continue_conversation(), etc. (61 typed builder methods)
execute() terminal method with process spawning
stdout/stderr capture and parsing
Exit code handling and error mapping

Out of Scope:

❌ Session storage path resolution → delegated to claude_profile crate
❌ Continuation detection → delegated to claude_profile crate
❌ Context injection from wplan → delegated to dream_agent crate
❌ Parameter parsing from CLI → delegated to dream_agent crate
❌ Session lifecycle strategy → delegated to dream_agent crate

Features

Builder Pattern: Fluent API with method chaining (NO deprecated factories)
Token Limit Fix: Explicit 200K token default (prevents "exceeded maximum" errors)
Single Execution Point: Consolidates duplicate Command::new("claude") calls
Type Safety: Builder pattern enforces correct configuration
Minimal Dependencies: Only error_tools + standard library

Usage

use claude_runner_core::ClaudeCommand;

// Basic execution
let result = ClaudeCommand::new()
  .with_working_directory("/home/user/project")
  .with_max_output_tokens(200_000)
  .with_continue_conversation(true)
  .execute()?;

println!("Output: {}", result.stdout);

// Advanced configuration
let result = ClaudeCommand::new()
  .with_working_directory("/tmp/work")
  .with_max_output_tokens(200_000)
  .with_model("claude-opus-4-5")
  .with_verbose(true)
  .with_system_prompt("You are a helpful coding assistant")
  .with_message("Fix the bug in main.rs")
  .execute()?;

# Ok::<(), Box<dyn std::error::Error>>(())

Architecture

Builder Pattern Flow:

ClaudeCommand::new()
  └→ with_working_directory()      (fluent method chaining)
  └→ with_max_output_tokens()
  └→ with_continue_conversation()
  └→ execute()                     ← SINGLE execution point
      └→ CommandBuilder::build()   (construct std::process::Command)
      └→ Command::new("claude")    ← ONLY location in entire codebase
      └→ ProcessExecutor::run()    (spawn, capture output)
      └→ Return ExecutionResult

Migration from Old API

Before (DEPRECATED - DO NOT USE):

// Factory method (DEPRECATED)
ClaudeCommand::generate(/* 40 parameters */)

// Mixed execution (DEPRECATED)
session.execute_interactive()
session.execute_non_interactive()

// Duplicate execution points (2x)
Command::new("claude")  // Location 1
Command::new("claude")  // Location 2

After (THIS CRATE):

// Builder pattern (CORRECT)
ClaudeCommand::new()
  .with_*()
  .execute()

// Single execution point (1x)
Command::new("claude")  // ONLY in claude_runner_core::execute()

Token Limit Bug Fix

Problem: Default Claude Code token limit is 32K, causing "exceeded maximum" errors

Solution: Set explicit max_output_tokens to 200K:

use claude_runner_core::ClaudeCommand;

let result = ClaudeCommand::new()
  .with_max_output_tokens(200_000)  // Explicit token limit
  .execute()?;

# Ok::<(), Box<dyn std::error::Error>>(())

Reference Documentation

Parameter Reference: docs/claude_params/ — all 59 claude binary parameters (CLI flags + env vars), with builder API mapping and default comparisons
Builder API: src/command.rs doc comments — authoritative builder method documentation
Tests: tests/readme.md — full test suite coverage map
Tasks: task/ — crate-level task tracking

Dependencies

error_tools: Workspace-standard error handling (Result, Error types)

Total: 1 workspace dependency (error_tools), 0 external direct dependencies

Testing

cargo nextest run

Critical Execution Rule

Command::new("claude") MUST appear exactly once:

✅ Single occurrence in claude_runner_core::execute()
❌ Zero occurrences in dream_agent
❌ Zero occurrences in claude_profile

Verification: grep -r "Command::new.*claude" src/ should find exactly 1 match.

claude_runner_core 1.0.0