feat(symphony): add Claude Code runner and config extensions

Add ClaudeCodeSession runner that spawns `claude -p` with NDJSON event
stream parsing, as an alternative to the Codex JSON-RPC app-server.
Extend ServiceConfig with runner_kind() and claude_flags() getters.
Orchestrator dispatch now branches on runner kind. Includes example
WORKFLOW-claude-code.md and QUICKSTART.md documentation updates.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Terraphim CI

crates/terraphim_symphony/QUICKSTART.md

@@ -198,10 +198,12 @@ Shell scripts executed at workspace lifecycle points. All run with `sh -lc` in t
 
 | Setting | Default | Description |
 |---------|---------|-------------|
+| `agent.runner` | `"codex"` | Runner kind: `"codex"` (JSON-RPC app-server) or `"claude-code"` (Claude Code CLI) |
 | `agent.max_concurrent_agents` | `10` | Maximum parallel agent sessions |
 | `agent.max_turns` | `20` | Maximum turns per agent session |
 | `agent.max_retry_backoff_ms` | `300000` (5 min) | Cap for exponential retry backoff |
 | `agent.max_concurrent_agents_by_state` | -- | Per-state concurrency limits (map of state -> limit) |
+| `agent.claude_flags` | -- | Additional CLI flags for Claude Code runner (e.g. `"--dangerously-skip-permissions"`) |
 
 ### Codex (Agent Process)
 
@@ -212,6 +214,23 @@ Shell scripts executed at workspace lifecycle points. All run with `sh -lc` in t
 | `codex.read_timeout_ms` | `5000` (5s) | Timeout for handshake responses |
 | `codex.stall_timeout_ms` | `300000` (5 min) | Kill session after this long with no activity. Set to `-1` to disable |
 
+### Claude Code Runner
+
+When `agent.runner` is set to `"claude-code"`, Symphony uses `claude -p` (Claude Code CLI) instead of the Codex JSON-RPC app-server. This is a single-shot invocation per issue -- no handshake, no approval flow, no multi-turn continuation.
+
+**Requirements**: `claude` CLI must be on PATH. Install via `npm install -g @anthropic-ai/claude-code`.
+
+**Example** (see `examples/WORKFLOW-claude-code.md`):
+```yaml
+agent:
+  runner: claude-code
+  max_concurrent_agents: 2
+  max_turns: 10
+  claude_flags: "--dangerously-skip-permissions --allowedTools Bash,Read,Write,Edit,Glob,Grep"
+```
+
+The session spawns `claude -p "<prompt>" --output-format stream-json --max-turns N <flags>` and parses the NDJSON event stream. Token usage, turn counts, and errors are extracted from the stream and reported to the orchestrator.
+
 ### Server (Optional)
 
 | Setting | Default | Description |

crates/terraphim_symphony/examples/WORKFLOW-claude-code.md

@@ -0,0 +1,49 @@
+---
+tracker:
+  kind: gitea
+  endpoint: https://git.terraphim.cloud
+  api_key: $GITEA_TOKEN
+  owner: terraphim
+  repo: pagerank-viewer
+
+polling:
+  interval_ms: 30000
+
+agent:
+  runner: claude-code
+  max_concurrent_agents: 2
+  max_turns: 10
+  claude_flags: "--dangerously-skip-permissions --allowedTools Bash,Read,Write,Edit,Glob,Grep"
+
+workspace:
+  root: ~/symphony_workspaces
+
+hooks:
+  after_create: "git clone https://git.terraphim.cloud/terraphim/pagerank-viewer.git ."
+  before_run: "git fetch origin && git checkout main && git pull"
+  after_run: "git add -A && git commit -m 'symphony: auto-commit for {{ issue.identifier }}' || true"
+  timeout_ms: 60000
+
+codex:
+  turn_timeout_ms: 3600000
+  stall_timeout_ms: 600000
+---
+You are working on issue {{ issue.identifier }}: {{ issue.title }}.
+
+{% if issue.description %}
+## Issue Description
+
+{{ issue.description }}
+{% endif %}
+
+## Instructions
+
+1. Read the issue carefully.
+2. Examine the relevant code in this workspace.
+3. Implement the required changes following project standards.
+4. Write tests to verify your changes.
+5. Commit with a message referencing {{ issue.identifier }}.
+
+{% if attempt %}
+This is retry attempt {{ attempt }}. Review previous work and continue.
+{% endif %}

crates/terraphim_symphony/src/config/mod.rs

@@ -187,6 +187,22 @@ impl ServiceConfig {
         map
     }
 
+    // --- Runner ---
+
+    /// Runner kind: `"codex"` (default) or `"claude-code"`.
+    ///
+    /// Determines which agent session type to use for dispatching issues.
+    pub fn runner_kind(&self) -> String {
+        self.get_str(&["agent", "runner"])
+            .unwrap_or_else(|| "codex".into())
+    }
+
+    /// Additional CLI flags for the Claude Code runner (e.g.
+    /// `"--dangerously-skip-permissions --max-turns 10"`).
+    pub fn claude_flags(&self) -> Option<String> {
+        self.get_str(&["agent", "claude_flags"])
+    }
+
     // --- Codex ---
 
     /// Coding-agent command to execute.
@@ -289,8 +305,18 @@ impl ServiceConfig {
             None => {} // Already caught above
         }
 
-        if self.codex_command().is_empty() {
-            checks.push("codex.command must not be empty".into());
+        match self.runner_kind().as_str() {
+            "codex" => {
+                if self.codex_command().is_empty() {
+                    checks.push("codex.command must not be empty".into());
+                }
+            }
+            "claude-code" => {
+                // No codex.command needed; claude CLI is invoked directly.
+            }
+            other => {
+                checks.push(format!("unsupported agent.runner: {other}"));
+            }
         }
 
         if checks.is_empty() {
@@ -549,6 +575,57 @@ mod tests {
         assert_eq!(cfg.codex_stall_timeout_ms(), 300_000);
     }
 
+    #[test]
+    fn default_runner_kind() {
+        let cfg = config_from_yaml("tracker:\n  kind: gitea");
+        assert_eq!(cfg.runner_kind(), "codex");
+    }
+
+    #[test]
+    fn custom_runner_kind() {
+        let cfg = config_from_yaml("agent:\n  runner: claude-code");
+        assert_eq!(cfg.runner_kind(), "claude-code");
+    }
+
+    #[test]
+    fn claude_flags_none_by_default() {
+        let cfg = config_from_yaml("tracker:\n  kind: gitea");
+        assert!(cfg.claude_flags().is_none());
+    }
+
+    #[test]
+    fn claude_flags_present() {
+        let cfg = config_from_yaml(
+            "agent:\n  claude_flags: \"--dangerously-skip-permissions --max-turns 10\"",
+        );
+        assert_eq!(
+            cfg.claude_flags().unwrap(),
+            "--dangerously-skip-permissions --max-turns 10"
+        );
+    }
+
+    #[test]
+    fn validation_claude_code_runner_no_codex_command_needed() {
+        let cfg = config_from_yaml(
+            "tracker:\n  kind: gitea\n  api_key: test\n  owner: o\n  repo: r\nagent:\n  runner: claude-code",
+        );
+        assert!(cfg.validate_for_dispatch().is_ok());
+    }
+
+    #[test]
+    fn validation_unsupported_runner() {
+        let cfg = config_from_yaml(
+            "tracker:\n  kind: gitea\n  api_key: test\n  owner: o\n  repo: r\nagent:\n  runner: unknown-runner",
+        );
+        let err = cfg.validate_for_dispatch().unwrap_err();
+        match err {
+            SymphonyError::ValidationFailed { checks } => {
+                assert!(checks.iter().any(|c| c.contains("unsupported agent.runner")));
+            }
+            _ => panic!("expected ValidationFailed"),
+        }
+    }
+
     #[test]
     fn env_var_resolution() {
         // SAFETY: test is single-threaded and uses a unique env var name

crates/terraphim_symphony/src/orchestrator/mod.rs

@@ -12,6 +12,7 @@ pub use state::{OrchestratorRuntimeState, StateSnapshot};
 use crate::config::template::render_prompt;
 use crate::config::ServiceConfig;
 use crate::error::Result;
+use crate::runner::claude_code::ClaudeCodeSession;
 use crate::runner::protocol::AgentEvent;
 use crate::runner::session::{CodexSession, WorkerOutcome};
 use crate::runner::TokenCounts;
@@ -245,6 +246,8 @@ impl SymphonyOrchestrator {
         // tracker checks in the worker and let the orchestrator handle it
         // via retry continuation.
 
+        let runner_kind = self.config.runner_kind();
+
         let worker_handle = tokio::spawn(async move {
             let per_issue_event_tx = event_tx.clone();
             let issue_id_for_events = issue_id_clone.clone();
@@ -265,75 +268,88 @@ impl SymphonyOrchestrator {
                 }
             });
 
-            // Start session
-            let session = match CodexSession::start(
-                &workspace_path,
-                &config,
-                session_event_tx.clone(),
-            )
-            .await
-            {
-                Ok(s) => s,
-                Err(e) => {
-                    forward_handle.abort();
-                    let outcome = WorkerOutcome::Failed {
-                        reason: e.to_string(),
-                        turn_count: 0,
-                        tokens: TokenCounts::default(),
-                    };
-                    let _ = exit_tx
-                        .send(WorkerExit {
-                            issue_id: issue_id_for_events,
-                            identifier: identifier_clone,
-                            outcome: WorkerOutcome::Failed {
-                                reason: e.to_string(),
-                                turn_count: 0,
-                                tokens: TokenCounts::default(),
-                            },
-                            started_at,
-                        })
-                        .await;
-                    return outcome;
-                }
-            };
-
-            // For this initial implementation, run a single turn.
-            // Multi-turn with tracker state checks will be added when
-            // we have a way to share the tracker reference.
-            let turn_timeout = Duration::from_millis(config.codex_turn_timeout_ms());
-            let mut session = session;
-
-            // Use the full prompt for the single turn approach
-            let outcome = match tokio::time::timeout(
-                turn_timeout,
-                session.run_turn_simple(&prompt_clone, &issue_clone, &session_event_tx),
-            )
-            .await
-            {
-                Ok(Ok(turn_id)) => {
-                    debug!(turn_id, "single turn completed");
-                    session.stop().await;
-                    WorkerOutcome::Normal {
-                        turn_count: 1,
-                        tokens: session.accumulated_tokens(),
-                    }
-                }
-                Ok(Err(e)) => {
-                    let tokens = session.accumulated_tokens();
-                    session.stop().await;
-                    WorkerOutcome::Failed {
-                        reason: e.to_string(),
-                        turn_count: 1,
-                        tokens,
+            let outcome = match runner_kind.as_str() {
+                "claude-code" => {
+                    // Claude Code runner: single-shot `claude -p` invocation
+                    match ClaudeCodeSession::start(
+                        &workspace_path,
+                        &config,
+                        &prompt_clone,
+                        session_event_tx.clone(),
+                    )
+                    .await
+                    {
+                        Ok(session) => {
+                            let turn_timeout =
+                                Duration::from_millis(config.codex_turn_timeout_ms());
+                            session.run_to_completion(&session_event_tx, turn_timeout).await
+                        }
+                        Err(e) => WorkerOutcome::Failed {
+                            reason: e.to_string(),
+                            turn_count: 0,
+                            tokens: TokenCounts::default(),
+                        },
                     }
                 }
-                Err(_) => {
-                    let tokens = session.accumulated_tokens();
-                    session.stop().await;
-                    WorkerOutcome::Failed {
-                        reason: format!("turn timeout after {}ms", config.codex_turn_timeout_ms()),
-                        turn_count: 1,
-                        tokens,
+                _ => {
+                    // Codex runner: JSON-RPC handshake + single turn
+                    match CodexSession::start(
+                        &workspace_path,
+                        &config,
+                        session_event_tx.clone(),
+                    )
+                    .await
+                    {
+                        Ok(mut session) => {
+                            let turn_timeout =
+                                Duration::from_millis(config.codex_turn_timeout_ms());
+
+                            match tokio::time::timeout(
+                                turn_timeout,
+                                session.run_turn_simple(
+                                    &prompt_clone,
+                                    &issue_clone,
+                                    &session_event_tx,
+                                ),
+                            )
+                            .await
+                            {
+                                Ok(Ok(turn_id)) => {
+                                    debug!(turn_id, "single turn completed");
+                                    session.stop().await;
+                                    WorkerOutcome::Normal {
+                                        turn_count: 1,
+                                        tokens: session.accumulated_tokens(),
+                                    }
+                                }
+                                Ok(Err(e)) => {
+                                    let tokens = session.accumulated_tokens();
+                                    session.stop().await;
+                                    WorkerOutcome::Failed {
+                                        reason: e.to_string(),
+                                        turn_count: 1,
+                                        tokens,
+                                    }
+                                }
+                                Err(_) => {
+                                    let tokens = session.accumulated_tokens();
+                                    session.stop().await;
+                                    WorkerOutcome::Failed {
+                                        reason: format!(
+                                            "turn timeout after {}ms",
+                                            config.codex_turn_timeout_ms()
+                                        ),
+                                        turn_count: 1,
+                                        tokens,
+                                    }
+                                }
+                            }
+                        }
+                        Err(e) => WorkerOutcome::Failed {
+                            reason: e.to_string(),
+                            turn_count: 0,
+                            tokens: TokenCounts::default(),
+                        },
                     }
                 }
             };