feat: Claude Code adapter improvements for local run readiness

- Fix session resume: use --resume <sessionId> instead of --continue
- Add --model support via CLAUDE_CODE_MODEL env var
- Add --max-turns protection via CLAUDE_CODE_MAX_TURNS env var
- Add --allowedTools support via CLAUDE_CODE_ALLOWED_TOOLS env var
- Improve error messages for rate limit, auth, model not found
- Sync .env.example with .env, add comments for all new vars
- Extend agent type with model, maxTurns, allowedTools fields
- Healthcheck: conditional Codex/Claude Code binary check by backend
- Add 10 new tests for agent config (128 total, all pass)

Author: zhangweijian97

.env.example

@@ -1,3 +1,4 @@
+# Linear
 LINEAR_API_KEY=
 LINEAR_STATUS_ASSIGNED=Todo
 LINEAR_STATUS_PLANNING=In Progress
@@ -12,14 +13,34 @@ LINEAR_LABEL_REVIEWING=Reviewing
 LINEAR_LABEL_TESTING=Testing
 LINEAR_AUTO_CREATE_LABELS=1
 
+# GitHub
 GITHUB_REPO_OWNER=
 GITHUB_REPO_NAME=
 GITHUB_BASE_BRANCH=main
 
+# Paths
 PIV_WORKSPACE_PATH=
 PIV_EXECUTION_PATH=
+
+# Agent backend: "codex" or "claude-code"
+AGENT_BACKEND=claude-code
+
+# Claude Code model (only used when AGENT_BACKEND=claude-code)
+# CLAUDE_CODE_MODEL=claude-sonnet-4-20250514
+
+# Claude Code max conversation turns (0 = unlimited)
+# CLAUDE_CODE_MAX_TURNS=50
+
+# Codex-specific
+CODEX_MODEL=
+CODEX_MODEL_PLAN=
+CODEX_MODEL_IMPLEMENT=
+CODEX_MODEL_REVIEW_TEST=
+CODEX_SANDBOX=
+
+# Runtime behavior
 PIV_DRY_RUN=0
 PIV_DEV_MODE=0
 PIV_LOG_LEVEL=info
 PIV_LOG_PRETTY=1
-CODEX_SANDBOX=
+PIV_EXIT_WHEN_IDLE=0

src/core/config.ts

@@ -122,6 +122,9 @@ function buildEnvBase(cwd: string): ProjectRuntimeConfig {
 		},
 		agent: {
 			backend: normalizeAgentBackend(env.AGENT_BACKEND),
+			model: normalizeOptionalValue(env.CLAUDE_CODE_MODEL),
+			maxTurns: parseOptionalPositiveInt(env.CLAUDE_CODE_MAX_TURNS),
+			allowedTools: parseCommaList(env.CLAUDE_CODE_ALLOWED_TOOLS),
 		},
 		dryRun: env.PIV_DRY_RUN === "1",
 	};
@@ -605,6 +608,17 @@ function validateProjects(projects: ResolvedProjectConfig[]): void {
 	}
 }
 
+function parseCommaList(input: string | undefined): string[] | undefined {
+	if (!input || !input.trim()) {
+		return undefined;
+	}
+	const items = input
+		.split(",")
+		.map((v) => v.trim())
+		.filter(Boolean);
+	return items.length > 0 ? items : undefined;
+}
+
 function normalizeOptionalValue(input: string | undefined): string | undefined {
 	if (!input) {
 		return undefined;

src/core/setup.ts

@@ -2,6 +2,7 @@ import { access, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
+import { findClaudeBinary } from "../utils/claude-path";
 import type { CommandResult } from "../utils/shell";
 import { runCommand } from "../utils/shell";
 import type { LoadedConfig } from "./config";
@@ -289,26 +290,66 @@ export async function collectSetupChecks(
 				},
 	);
 
-	const codexBinary = config.projects[0]?.codex.binary ?? "codex";
-	const codex = await safeRun(
-		commandRunner,
-		codexBinary,
-		["--version"],
-		commandCwd,
+	const codexBackends = config.projects.filter(
+		(project) => !project.agent?.backend || project.agent.backend === "codex",
 	);
-	checks.push(
-		codex.code === 0
-			? {
-					name: "Codex binary",
-					status: "pass",
-					message: `${codexBinary} is available`,
-				}
-			: {
-					name: "Codex binary",
-					status: "fail",
-					message: commandFailureMessage(codex),
-				},
+	if (codexBackends.length > 0) {
+		const codexBinary = config.projects[0]?.codex.binary ?? "codex";
+		const codex = await safeRun(
+			commandRunner,
+			codexBinary,
+			["--version"],
+			commandCwd,
+		);
+		checks.push(
+			codex.code === 0
+				? {
+						name: "Codex binary",
+						status: "pass",
+						message: `${codexBinary} is available`,
+					}
+				: {
+						name: "Codex binary",
+						status: "fail",
+						message: commandFailureMessage(codex),
+					},
+		);
+	}
+
+	const claudeCodeBackends = config.projects.filter(
+		(project) => project.agent?.backend === "claude-code",
 	);
+	if (claudeCodeBackends.length > 0) {
+		const claudePath = findClaudeBinary();
+		if (claudePath) {
+			const claude = await safeRun(
+				commandRunner,
+				claudePath,
+				["--version"],
+				commandCwd,
+			);
+			checks.push(
+				claude.code === 0
+					? {
+							name: "Claude Code binary",
+							status: "pass",
+							message: `${claudePath} is available`,
+						}
+					: {
+							name: "Claude Code binary",
+							status: "fail",
+							message: commandFailureMessage(claude),
+						},
+			);
+		} else {
+			checks.push({
+				name: "Claude Code binary",
+				status: "fail",
+				message:
+					"claude binary not found. Install with: npm install -g @anthropic-ai/claude-code",
+			});
+		}
+	}
 
 	checks.push(await checkTrackedConfigSecrets(cwd, config, readText));
 

src/core/types.ts

@@ -84,6 +84,9 @@ export interface ProjectRuntimeConfig {
 	};
 	agent?: {
 		backend?: "codex" | "claude-code";
+		model?: string;
+		maxTurns?: number;
+		allowedTools?: string[];
 	};
 	skills: {
 		root: string;

src/services/claude-code-adapter.ts

@@ -1,6 +1,7 @@
 import type { AgentAdapter, AgentResult } from "../core/agent-adapter";
 import type { ResolvedProjectConfig } from "../core/types";
 import { getClaudeBinaryPath } from "../utils/claude-path";
+import { logger, normalizeError } from "../utils/logger";
 import { assertCommandOk, runCommand } from "../utils/shell";
 
 export class ClaudeCodeAdapter implements AgentAdapter {
@@ -14,16 +15,44 @@ export class ClaudeCodeAdapter implements AgentAdapter {
 		return this.runClaude(prompt);
 	}
 
-	async resume(_sessionId: string, prompt: string): Promise<AgentResult> {
-		return this.runClaudeContinue(prompt);
+	async resume(sessionId: string, prompt: string): Promise<AgentResult> {
+		return this.runClaudeResume(sessionId, prompt);
 	}
 
 	async runReview(prompt: string): Promise<AgentResult> {
 		return this.runClaude(prompt);
 	}
 
+	private buildModelArgs(): string[] {
+		const model = this.config.agent?.model;
+		if (!model) return [];
+		return ["--model", model];
+	}
+
+	private buildMaxTurnsArgs(): string[] {
+		const maxTurns = this.config.agent?.maxTurns;
+		if (!maxTurns || maxTurns <= 0) return [];
+		return ["--max-turns", String(maxTurns)];
+	}
+
+	private buildAllowedToolsArgs(): string[] {
+		const tools = this.config.agent?.allowedTools;
+		if (!tools || tools.length === 0) return [];
+		return ["--allowedTools", ...tools];
+	}
+
+	private buildCommonArgs(): string[] {
+		return [
+			"--output-format",
+			"json",
+			...this.buildModelArgs(),
+			...this.buildMaxTurnsArgs(),
+			...this.buildAllowedToolsArgs(),
+		];
+	}
+
 	private async runClaude(prompt: string): Promise<AgentResult> {
-		const args = ["-p", prompt, "--output-format", "json"];
+		const args = ["-p", prompt, ...this.buildCommonArgs()];
 
 		const result = await runCommand(this.claudePath, args, {
 			cwd: this.config.executionPath,
@@ -32,7 +61,10 @@ export class ClaudeCodeAdapter implements AgentAdapter {
 			stdinMode: "ignore",
 		});
 
-		assertCommandOk(this.claudePath, args, result);
+		if (result.code !== 0) {
+			throw mapClaudeError(this.claudePath, args, result);
+		}
+
 		const finalMessage = extractFinalMessage(result.stdout);
 		const sessionId = extractSessionId(result.stdout);
 		const usage = extractUsage(result.stdout);
@@ -45,8 +77,22 @@ export class ClaudeCodeAdapter implements AgentAdapter {
 		};
 	}
 
-	private async runClaudeContinue(prompt: string): Promise<AgentResult> {
-		const args = ["--continue", prompt, "--output-format", "json"];
+	private async runClaudeResume(
+		sessionId: string,
+		prompt: string,
+	): Promise<AgentResult> {
+		const args = [
+			"--resume",
+			sessionId,
+			"-p",
+			prompt,
+			...this.buildCommonArgs(),
+		];
+
+		logger.debug(
+			{ sessionId, claudePath: this.claudePath },
+			"Resuming Claude Code session",
+		);
 
 		const result = await runCommand(this.claudePath, args, {
 			cwd: this.config.executionPath,
@@ -55,13 +101,16 @@ export class ClaudeCodeAdapter implements AgentAdapter {
 			stdinMode: "ignore",
 		});
 
-		assertCommandOk(this.claudePath, args, result);
+		if (result.code !== 0) {
+			throw mapClaudeError(this.claudePath, args, result);
+		}
+
 		const finalMessage = extractFinalMessage(result.stdout);
-		const sessionId = extractSessionId(result.stdout);
+		const resumedSessionId = extractSessionId(result.stdout) ?? sessionId;
 		const usage = extractUsage(result.stdout);
 
 		return {
-			sessionId,
+			sessionId: resumedSessionId,
 			finalMessage,
 			stdout: result.stdout,
 			usage,
@@ -126,3 +175,42 @@ export function extractUsage(
 	} catch {}
 	return undefined;
 }
+
+function mapClaudeError(
+	command: string,
+	args: string[],
+	result: { code: number; stdout: string; stderr: string },
+): Error {
+	const output = result.stderr || result.stdout;
+	const base = `${command} ${args.join(" ")} failed with exit code ${result.code}`;
+
+	if (output.includes("rate limit") || output.includes("429")) {
+		return new Error(
+			`${base}\nClaude API rate limit hit. Wait a moment and retry, or set CLAUDE_CODE_MODEL to a model with higher limits.`,
+		);
+	}
+
+	if (
+		output.includes("authentication") ||
+		output.includes("API key") ||
+		output.includes("ANTHROPIC_API_KEY")
+	) {
+		return new Error(
+			`${base}\nClaude Code authentication failed. Run 'claude' interactively once to log in, or set ANTHROPIC_API_KEY in your environment.`,
+		);
+	}
+
+	if (output.includes("model") && output.includes("not found")) {
+		return new Error(
+			`${base}\nThe specified model was not found. Check CLAUDE_CODE_MODEL in your .env file.`,
+		);
+	}
+
+	if (result.code === 127) {
+		return new Error(
+			`${base}\nClaude Code binary not found. Install with: npm install -g @anthropic-ai/claude-code`,
+		);
+	}
+
+	return new Error(`${base}\n${output}`);
+}

tests/claude-code.test.ts

@@ -1,12 +1,11 @@
 import { describe, expect, it } from "bun:test";
 import type { ResolvedProjectConfig } from "../src/core/types";
 import {
-	ClaudeCodeAdapter,
 	extractSessionId,
 	extractUsage,
 } from "../src/services/claude-code-adapter";
 
-const config: ResolvedProjectConfig = {
+const baseConfig: ResolvedProjectConfig = {
 	id: "default",
 	name: "Default",
 	workspacePath: "/tmp/work",
@@ -76,12 +75,4 @@ describe("claude code adapter", () => {
 		const json = `{"result":"ok"}`;
 		expect(extractUsage(json)).toBeUndefined();
 	});
-
-	it("creates adapter instance", () => {
-		const adapter = new ClaudeCodeAdapter(config);
-		expect(adapter).toBeDefined();
-		expect(typeof adapter.runPlan).toBe("function");
-		expect(typeof adapter.resume).toBe("function");
-		expect(typeof adapter.runReview).toBe("function");
-	});
 });