fix(claude): align Codencer adapter with real Claude Code CLI

Codencer's previous Claude adapter assumed a worker-style command contract that does not match the real Claude Code source. This change rewrites the adapter to use the actual headless CLI integration model.

Highlights:
- switch to the real Claude CLI invocation model
- pass task content non-interactively instead of relying on nonexistent worker flags
- execute in the attempt workspace/worktree
- capture raw structured output and synthesize normalized Codencer results
- harden poll/cancel/process lifecycle behavior
- add fake-binary and normalization tests
- update public docs to reflect the real integration contract

This keeps Codencer within its bridge-not-brain doctrine while making the Claude executor path materially correct and auditable.

Author: lookmanrays

.env.example

@@ -10,8 +10,9 @@ CODEX_BINARY=codex-agent
 # Set to 1 to stub only the Codex agent
 CODEX_SIMULATION_MODE=0
 
-# Path to the Claude agent binary (requires npm install -g @anthropic-ai/claude-code)
-CLAUDE_BINARY=claude-code
+# Path to the Claude agent binary (install via npm: @anthropic-ai/claude-code)
+# Codencer invokes the installed `claude` CLI in headless print mode.
+CLAUDE_BINARY=claude
 CLAUDE_SIMULATION_MODE=0
 
 # Path to the Qwen agent binary

README.md

@@ -1,6 +1,6 @@
 # Codencer: The Tactical Orchestration Bridge
 
-Codencer is a tactical orchestration bridge that manages execution, isolation, and high-fidelity audit trails for coding agents. It serves as the **system of record** between a high-level **Planner** (human or LLM) and tactical **Coding Agents** (Codex, Claude-code). 
+Codencer is a tactical orchestration bridge that manages execution, isolation, and high-fidelity audit trails for coding agents. It serves as the **system of record** between a high-level **Planner** (human or LLM) and tactical **Coding Agents** (Codex, Claude).
 
 Designed for **local-first, self-hosted developer toolchains**, Codencer provides the missing "relay" layer that ensures every task attempt is isolated, provisioned, and validated before it ever reaches your production branch.
 
@@ -29,7 +29,7 @@ Codencer is a **Tactical Orchestration Bridge**, not a strategic planner. It han
 ### Core Roles
 - **Planner (Brain)**: You, a Chat UI, or an agentic planner. Decides **what** to do.
 - **Bridge (Codencer)**: Receives the `TaskSpec`, manages workspace isolation (Git Worktrees), enforces policies, and monitors execution.
-- **Coding Agent (Worker)**: The tactical tool performing the actual work (e.g., `codex-agent`, `claude-code`).
+- **Coding Agent (Worker)**: The tactical tool performing the actual work (e.g., `codex-agent`, `claude`).
 
 ---
 
@@ -85,11 +85,15 @@ Choose your execution tier in `.env` (Simulation is enabled by default in `.env.
 # Start in Simulation Mode (Background)
 make start-sim
 
-# OR Start in Real Mode (Requires agent binaries like codex-agent)
+# OR Start in Real Mode (Requires agent binaries like codex-agent or claude)
 # Edit .env: ALL_ADAPTERS_SIMULATION_MODE=0
 make start
 ```
 
+For Claude, Codencer invokes the installed CLI as `claude -p --output-format json`, sends the step prompt on `stdin`, and runs from the isolated attempt workspace as the process `cwd`.
+
+Current support level for the Claude adapter is **Supported (Beta)**: the wrapper contract is implemented and covered by prompt, normalization, lifecycle, fake-binary integration, and simulation conformance tests, but the repo test suite does not run a live authenticated Claude service call.
+
 ### 3. Run Your First Tactical Task
 Submit a task and wait for the bridge to report results. For the full auditing sequence, see the **[Canonical Local Runbook](docs/EXAMPLES.md)**.
 
@@ -168,6 +172,12 @@ Every task execution leaves a permanent audit trail:
 3. **Artifacts**: Every modified file and diff is stored in `.codencer/artifacts/`. Use `./bin/orchestratorctl step artifacts <id>` to see the exact paths and SHA-256 hashes.
 4. **Validations**: Run `./bin/orchestratorctl step validations <id>` to see specific test/lint results.
 
+For Claude attempts specifically, the standard evidence set is:
+- `prompt.txt`: the exact prompt Codencer built and sent to Claude
+- `stdout.log`: raw Claude JSON output
+- `stderr.log`: raw Claude stderr
+- `result.json`: synthesized normalized Codencer result
+
 ## 🧾 Submission Inputs
 
 Codencer supports two submit styles:

cmd/orchestratorctl/main.go

@@ -986,7 +986,7 @@ func runDoctor() {
 		env  string
 	}{
 		{"Codex", "codex-agent", "CODEX_BINARY"},
-		{"Claude", "claude-code", "CLAUDE_BINARY"},
+		{"Claude", "claude", "CLAUDE_BINARY"},
 		{"Qwen", "qwen-local", "QWEN_BINARY"},
 		{"OpenClaw", "acpx", "OPENCLAW_ACPX_BINARY"},
 	}

docs/06_adapters_and_ide.md

@@ -21,12 +21,23 @@ Why:
 - strong local CLI and IDE support
 - first-class fit for MVP
 
-### 3. Claude Code second
+### 3. Claude second
 Why:
 - mature terminal-native coding agent
 - strong second adapter
 - good contrast for adapter-neutral design
 
+Status:
+- **Supported (Beta)**: the v1 CLI wrapper contract is implemented and covered by fake-binary integration tests, prompt/normalization unit tests, lifecycle tests, and simulation conformance tests.
+- **Not covered in repo tests**: live authenticated Claude service calls.
+
+Current v1 contract:
+- binary: `claude` (configurable via `CLAUDE_BINARY`)
+- invocation: `claude -p --output-format json`
+- prompt path: `stdin`
+- workspace semantics: process `cwd` is the attempt workspace root
+- evidence model: `prompt.txt`, raw `stdout.log`, raw `stderr.log`, plus a synthesized `result.json`
+
 ### 4. OpenClaw ACPX
 - **Status**: 🧪 **Experimental (Alpha)**
 - **Description**: Standardized ACP (Agent Control Protocol) bridge to the OpenClaw ecosystem.

docs/AI_OPERATOR_GUIDE.md

@@ -40,6 +40,11 @@ Always verify the daemon's identity to ensure you are targeting the correct repo
 
 Use `submit --wait --json` for a synchronous hand-off. This simplifies your control flow by blocking until a terminal state is reached.
 
+Runtime note:
+- In real mode, Codencer expects the installed agent CLIs to be reachable through their configured binaries.
+- For Claude specifically, the bridge runs `claude -p --output-format json`, sends the submitted prompt on `stdin`, and executes from the isolated attempt workspace.
+- Claude evidence is file-backed: review `prompt.txt`, `stdout.log`, `stderr.log`, and the synthesized `result.json` through normal artifact inspection.
+
 ### Pattern: The Direct Input Loop
 Ideal for human-in-the-loop or iterative assistant tasks.
 
@@ -110,6 +115,7 @@ Follow this sequence for every tactical mission:
    ```bash
    ./bin/orchestratorctl step result <UUID> --json
    ./bin/orchestratorctl step validations <UUID> --json
+   ./bin/orchestratorctl step artifacts <UUID>
    ```
 
 ---

docs/EXAMPLES.md

@@ -80,6 +80,20 @@ Exclude the test files.
 EOF
 ```
 
+### 5.5 Claude Headless Execution
+Use the Claude adapter when the `claude` CLI is installed locally and reachable through `CLAUDE_BINARY` or `$PATH`.
+```bash
+cat <<'EOF' | ./bin/orchestratorctl submit my-run --stdin --title "Claude Audit" --adapter claude --wait --json
+Review the auth package, explain the failing behavior, and propose a minimal fix.
+EOF
+```
+
+For Claude attempts, the standard evidence set includes:
+- `prompt.txt`
+- `stdout.log`
+- `stderr.log`
+- `result.json`
+
 ### OpenClaw ACPX (Experimental / Alpha)
 Relay tasks to an OpenClaw-compatible executor via the standardized ACP bridge. Use `--wait --json` for synchronous machine-safe handoffs.
 ```bash
@@ -117,3 +131,9 @@ See exactly how the workspace was prepared.
 ```bash
 ./bin/orchestratorctl step logs <HANDLE>
 ```
+
+### Inspecting Claude-Specific Evidence
+```bash
+./bin/orchestratorctl step artifacts <HANDLE>
+./bin/orchestratorctl step result <HANDLE> --json | jq '.raw_output_ref, .artifacts["prompt.txt"], .artifacts["stderr.log"]'
+```

docs/SETUP.md

@@ -51,12 +51,14 @@ make start-sim
 ```
 
 ### 3.2 Real Mode (Tactical Execution)
-Use this mode for real-world tasks. It requires agents like `codex-agent` or `claude-code` to be installed.
+Use this mode for real-world tasks. It requires agents like `codex-agent` or `claude` to be installed.
 ```bash
 # Edit .env to set ALL_ADAPTERS_SIMULATION_MODE=0
 make start
 ```
 
+Claude is executed in headless print mode as `claude -p --output-format json`. Codencer builds the task prompt, writes it to `prompt.txt`, delivers it on `stdin`, and runs the process from the attempt workspace root.
+
 ---
 
 ## 4. Daemon Management & Targeting
@@ -89,9 +91,15 @@ Use the provided script to start and build a daemon instance for a specific proj
 ### 4.4 Environment Variables
 Codencer uses these variables to locate agent binaries and target the daemon:
 - `CODEX_BINARY`: Path to the `codex-agent` binary.
+- `CLAUDE_BINARY`: Path to the `claude` binary. Defaults to `claude`.
 - `OPENCLAW_ACPX_BINARY`: Path to the `acpx` CLI (for OpenClaw support).
 - `ORCHESTRATORD_URL`: URL of the daemon (default: `http://localhost:8085`).
 
+### 4.5 Claude Adapter Notes
+- Install the Claude CLI so the `claude` binary is available on your `$PATH`, or point `CLAUDE_BINARY` at the full path.
+- Codencer does not pass a workspace flag to Claude. The attempt workspace is supplied via process `cwd`.
+- Claude raw output is preserved in `stdout.log`; Codencer parses that JSON and synthesizes the normalized `result.json`.
+
 ---
 
 ## 5. OpenClaw Setup (Experimental / Alpha)

docs/TROUBLESHOOTING.md

@@ -23,11 +23,20 @@ Always start here to verify your environment:
 
 ### 2.2 "Agent Binary Not Found" (`failed_adapter`)
 **Symptoms**: Submitting a task fails immediately; `doctor` shows `MISSING` for an adapter.
-- **Cause**: The bridge cannot find the `codex-agent` or `claude-code` binary in your `$PATH`.
+- **Cause**: The bridge cannot find the `codex-agent` or `claude` binary in your `$PATH`.
 - **Fix**:
   - Export the specific path: `export CODEX_BINARY=/path/to/codex-agent`.
+  - Or export `CLAUDE_BINARY=/path/to/claude` if the Claude CLI is installed outside your default `$PATH`.
   - Or ensure the binary is in your global `$PATH`.
 
+### 2.2.1 "Malformed or Missing Claude Result Output" (`failed_terminal`)
+**Symptoms**: Claude starts, but the final result summary mentions malformed or missing Claude output.
+- **Cause**: The `claude` process did not emit a final JSON `result` object on stdout, or another tool/script polluted stdout.
+- **Fix**:
+  - Inspect `./bin/orchestratorctl step logs <UUID>` for the raw stdout payload.
+  - Inspect `./bin/orchestratorctl step artifacts <UUID>` and review `stderr.log` for CLI/auth/runtime errors.
+  - Re-run `claude -p --output-format json` directly in the repo if you suspect local CLI/environment issues.
+
 ### 2.3 "Workspace Creation Failed" (`failed_bridge`)
 **Symptoms**: `failed_bridge` reported during attempt.
 - **Cause**: Git worktree conflict or permission issue.
@@ -133,6 +142,7 @@ Codencer uses specific states to distinguish between **instructional failure** (
 | `failed_adapter` | **Infrastructure** | The agent binary crashed (e.g. API error, OOM). | Check `step logs`. |
 | `failed_bridge` | **Infrastructure** | Codencer failed (e.g. Disk Full, Git Error, Provisioning). | Check daemon logs. |
 | `timeout` | **Infrastructure** | Task exceeded `timeout_seconds` and was killed. | Increase timeout. |
+| `cancelled` | **Infrastructure / Operator Action** | Task was explicitly interrupted before completion. | Re-run or submit a follow-up task. |
 
 ---
 

docs/internal/GAP_AUDIT.md

@@ -19,7 +19,8 @@
 | **CLI & MCP Layer** | ✅ **Ready (Stable)** | Native | Human-readable hints, logs, and structured JSON. |
 | **Codex Adapter** | ✅ **Ready (Stable)** | CLI Wrapper | High-fidelity relay with artifact harvesting. |
 | **OpenClaw Adapter** | 🧪 **Experimental (Alpha)** | ACPX Wrapper | Functional alpha; basic lifecycle tracking. |
-| **Claude/Qwen Adapters** | 🟡 **Functional** | CLI Wrapper | Basic subprocess wrappers; lacks deep extraction. |
+| **Claude Adapter** | 🟢 **Supported (Beta)** | CLI Wrapper | Uses `claude -p --output-format json` with stdin prompt delivery, cwd-based execution, synthesized result mapping, and fake-binary integration coverage. Live authenticated Claude service calls are not exercised in repo tests. |
+| **Qwen Adapter** | 🟡 **Functional** | CLI Wrapper | Basic subprocess wrapper; narrower evidence extraction than Codex/Claude. |
 | **Simulation Mode** | ✅ **Ready (Stable)** | Native | Robust stubs for orchestrator validation. |
 | **Adaptive Routing** | 🧪 **Prototype** | Heuristic | Static fallback chain; not yet benchmark-driven. |
 | **Governance** | ✅ **Ready (Stable)** | Manual | MIT Licensed; `CONTRIBUTING.md` authored. |

internal/adapters/claude/adapter.go

@@ -2,22 +2,38 @@ package claude
 
 import (
 	"context"
+	"fmt"
 	"log/slog"
+	"os"
+	"os/exec"
 	"sync"
 
 	"agent-bridge/internal/adapters/common"
 	"agent-bridge/internal/domain"
 )
 
+const (
+	binaryName   = "claude"
+	binaryEnvVar = "CLAUDE_BINARY"
+)
+
+type processState struct {
+	cancel context.CancelFunc
+	done   chan struct{}
+
+	mu  sync.Mutex
+	cmd *exec.Cmd
+}
+
 // Adapter implements domain.Adapter for the Claude agent.
 type Adapter struct {
-	processes map[string]*context.CancelFunc
 	mu        sync.Mutex
+	processes map[string]*processState
 }
 
 func NewAdapter() *Adapter {
 	return &Adapter{
-		processes: make(map[string]*context.CancelFunc),
+		processes: make(map[string]*processState),
 	}
 }
 
@@ -31,27 +47,40 @@ func (a *Adapter) Capabilities() []string {
 
 func (a *Adapter) Start(ctx context.Context, step *domain.Step, attempt *domain.Attempt, workspaceRoot, attemptArtifactRoot string) error {
 	a.mu.Lock()
-	defer a.mu.Unlock()
-
 	if _, exists := a.processes[attempt.ID]; exists {
+		a.mu.Unlock()
 		return nil
 	}
 
+	state := &processState{done: make(chan struct{})}
+	a.processes[attempt.ID] = state
+	a.mu.Unlock()
+
+	isSimulation := common.IsSimulationEnabled(a.Name())
+	if !isSimulation {
+		if _, err := resolveBinary(); err != nil {
+			a.mu.Lock()
+			delete(a.processes, attempt.ID)
+			a.mu.Unlock()
+			return err
+		}
+	}
+
 	execCtx, cancel := context.WithCancel(context.Background())
-	a.processes[attempt.ID] = &cancel
+	state.cancel = cancel
 
 	go func() {
+		defer close(state.done)
 		defer cancel()
-		opts := common.ExecutionOptions{
-			AdapterName:  a.Name(),
-			BinaryName:   "claude-code",
-			BinaryEnvVar: "CLAUDE_BINARY",
-			Args:         []string{"run", "--workspace", workspaceRoot, "--output", attemptArtifactRoot},
-			Workspace:    workspaceRoot,
-			ArtifactRoot: attemptArtifactRoot,
+
+		var err error
+		if isSimulation {
+			err = common.RunSimulation(execCtx, step, attempt, attemptArtifactRoot, workspaceRoot)
+		} else {
+			err = runAttempt(execCtx, state, step, attempt, workspaceRoot, attemptArtifactRoot)
 		}
 
-		if err := common.InvokeLocal(execCtx, step, attempt, opts); err != nil {
+		if err != nil {
 			slog.Error("Claude Adapter: Execution failed", "attemptID", attempt.ID, "error", err)
 		}
 
@@ -65,22 +94,34 @@ func (a *Adapter) Start(ctx context.Context, step *domain.Step, attempt *domain.
 
 func (a *Adapter) Poll(ctx context.Context, attemptID string) (bool, error) {
 	a.mu.Lock()
-	defer a.mu.Unlock()
-	_, running := a.processes[attemptID]
-	return running, nil
+	state, exists := a.processes[attemptID]
+	a.mu.Unlock()
+	if !exists {
+		return false, nil
+	}
+
+	select {
+	case <-state.done:
+		return false, nil
+	default:
+		return true, nil
+	}
 }
 
 func (a *Adapter) Cancel(ctx context.Context, attemptID string) error {
 	a.mu.Lock()
-	defer a.mu.Unlock()
-
-	cancelFunc, exists := a.processes[attemptID]
+	state, exists := a.processes[attemptID]
+	a.mu.Unlock()
 	if !exists {
 		return nil
 	}
 
-	(*cancelFunc)()
-	delete(a.processes, attemptID)
+	if state.cancel != nil {
+		state.cancel()
+	}
+	if err := stopProcess(state); err != nil {
+		return err
+	}
 	return nil
 }
 
@@ -89,5 +130,20 @@ func (a *Adapter) CollectArtifacts(ctx context.Context, attemptID string, attemp
 }
 
 func (a *Adapter) NormalizeResult(ctx context.Context, attemptID string, artifacts []*domain.Artifact) (*domain.ResultSpec, error) {
-	return common.NormalizeStandardResult(attemptID, artifacts)
+	isSimulation := common.IsSimulationEnabled(a.Name())
+	return NormalizeCore(attemptID, artifacts, a.Name(), isSimulation)
+}
+
+func resolveBinary() (string, error) {
+	binary := os.Getenv(binaryEnvVar)
+	if binary == "" {
+		binary = binaryName
+	}
+
+	binaryPath, err := exec.LookPath(binary)
+	if err != nil {
+		return "", fmt.Errorf("claude binary %q not found or not executable. Set %s to a valid path or enable simulation with %s_SIMULATION_MODE=1: %w", binary, binaryEnvVar, "CLAUDE", err)
+	}
+
+	return binaryPath, nil
 }