stonecut 1.2.1 → 1.4.0

package/src/runners/claude.ts

@@ -1,94 +1,178 @@
 /**
- * ClaudeRunner — adapter for Claude Code CLI.
+ * ClaudeRunner — adapter for Claude Code via the Agent SDK.
  *
- * Spawns a headless Claude Code session, parses the JSON output to
- * determine success/failure, and translates error subtypes into
- * human-readable messages.
+ * Calls query() from @anthropic-ai/claude-agent-sdk and consumes the
+ * async message stream internally. Console gets concise progress
+ * (tool calls, turn boundaries, errors); the log file captures the
+ * full event stream for debugging.
  */
 
+import { query as sdkQuery } from "@anthropic-ai/claude-agent-sdk";
+import type {
+	Query,
+	SDKAssistantMessage,
+	SDKMessage,
+	SDKPartialAssistantMessage,
+	SDKResultMessage,
+} from "@anthropic-ai/claude-agent-sdk";
 import type { LogWriter, Runner, RunResult } from "../types.js";
 
+const ALLOWED_TOOLS = ["Bash", "Edit", "Read", "Write", "Glob", "Grep"];
+
+type QueryFn = (params: { prompt: string; options?: Record<string, unknown> }) => Query;
+let queryFn: QueryFn = sdkQuery;
+
+/** @internal Replace the SDK query function. Returns a restore function. */
+export function _setQueryFn(fn: QueryFn): () => void {
+	const prev = queryFn;
+	queryFn = fn;
+	return () => {
+		queryFn = prev;
+	};
+}
+
 const ERROR_MESSAGES: Record<string, string> = {
 	error_max_turns: "max turns exceeded",
 	error_max_budget_usd: "max budget exceeded",
+	error_during_execution: "execution error",
+	error_max_structured_output_retries: "max structured output retries exceeded",
 };
 
 export class ClaudeRunner implements Runner {
-	logEnvironment(logger: LogWriter): void {
+	private logger: LogWriter;
+
+	constructor(logger: LogWriter) {
+		this.logger = logger;
 		const configDir = process.env.CLAUDE_CONFIG_DIR || "~/.claude (default)";
 		logger.log(`Claude config: ${configDir}`);
 	}
 
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
+		let result: SDKResultMessage | undefined;
 
-		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
 		try {
-			proc = Bun.spawn(
-				[
-					"claude",
-					"-p",
-					"--output-format",
-					"json",
-					"--allowedTools",
-					"Bash,Edit,Read,Write,Glob,Grep",
-				],
-				{ stdin: new Response(prompt), stdout: "pipe", stderr: "pipe" },
-			);
-		} catch {
-			return {
-				success: false,
-				exitCode: 1,
-				durationSeconds: (performance.now() - start) / 1000,
-				error: "claude binary not found in PATH",
-			};
+			const stream = queryFn({
+				prompt,
+				options: {
+					allowedTools: ALLOWED_TOOLS,
+					permissionMode: "acceptEdits",
+				},
+			});
+
+			for await (const message of stream) {
+				this.handleMessage(message);
+				if (message.type === "result") {
+					result = message;
+				}
+			}
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+
+			if (msg.includes("ENOENT") || msg.includes("not found") || msg.includes("spawn")) {
+				return { success: false, durationSeconds, error: "claude binary not found in PATH" };
+			}
+			return { success: false, durationSeconds, error: msg };
 		}
 
-		const exitCode = await proc.exited;
 		const durationSeconds = (performance.now() - start) / 1000;
 
-		const stdout = await new Response(proc.stdout as ReadableStream).text();
-		const output = stdout || undefined;
+		if (!result) {
+			return { success: false, durationSeconds, error: "no result message received" };
+		}
+
+		const sessionId = result.session_id;
+		const turns = result.num_turns;
+		const inputTokens = result.usage.input_tokens;
+		const outputTokens = result.usage.output_tokens;
 
-		if (output === undefined) {
+		this.logger.logFile(
+			`[claude] Result: ${result.subtype}, turns=${turns}, input=${inputTokens}, output=${outputTokens}`,
+		);
+
+		if (result.subtype === "success") {
 			return {
-				success: false,
-				exitCode,
+				success: true,
 				durationSeconds,
-				error: `no output (exit code ${exitCode})`,
+				output: result.result,
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId,
 			};
 		}
 
-		let data: unknown;
-		try {
-			data = JSON.parse(output);
-		} catch {
-			return {
-				success: false,
-				exitCode,
-				durationSeconds,
-				output,
-				error: "malformed JSON output",
-			};
+		const error = ERROR_MESSAGES[result.subtype] ?? `failed (${result.subtype})`;
+		const detail = result.errors?.length ? `: ${result.errors.join("; ")}` : "";
+		return {
+			success: false,
+			durationSeconds,
+			error: error + detail,
+			turns,
+			inputTokens,
+			outputTokens,
+			sessionId,
+		};
+	}
+
+	private handleMessage(message: SDKMessage): void {
+		switch (message.type) {
+			case "assistant":
+				this.logAssistant(message);
+				break;
+			case "stream_event":
+				this.logStreamEvent(message);
+				break;
+			case "result":
+				break;
+			default:
+				this.logger.logFile(`[claude] ${message.type}: ${JSON.stringify(message)}`);
+				break;
 		}
+	}
 
-		if (typeof data !== "object" || data === null || Array.isArray(data)) {
-			return {
-				success: false,
-				exitCode,
-				durationSeconds,
-				output,
-				error: "unexpected JSON output (not an object)",
-			};
+	private logAssistant(message: SDKAssistantMessage): void {
+		if (message.error) {
+			this.logger.log(`[claude] Error: ${message.error}`);
 		}
 
-		const subtype = (data as Record<string, unknown>).subtype ?? "";
-		if (subtype === "success") {
-			return { success: true, exitCode, durationSeconds, output };
+		for (const block of message.message.content) {
+			if (typeof block === "string") continue;
+			if (block.type === "tool_use") {
+				const target = this.toolTarget(block.name, block.input as Record<string, unknown>);
+				this.logger.log(`[claude] ${block.name}${target ? `: ${target}` : ""}`);
+			}
 		}
 
-		const error =
-			ERROR_MESSAGES[subtype as string] ?? `failed (${(subtype as string) || "unknown"})`;
-		return { success: false, exitCode, durationSeconds, output, error };
+		this.logger.logFile(`[claude] Assistant message: ${JSON.stringify(message.message.content)}`);
+	}
+
+	private logStreamEvent(message: SDKPartialAssistantMessage): void {
+		const event = message.event;
+		if (event.type === "content_block_delta") {
+			const delta = event.delta;
+			if ("text" in delta && typeof delta.text === "string") {
+				this.logger.logFile(`[claude] text: ${delta.text}`);
+			} else if ("thinking" in delta && typeof delta.thinking === "string") {
+				this.logger.logFile(`[claude] thinking: ${delta.thinking}`);
+			}
+		}
+	}
+
+	private toolTarget(name: string, input: Record<string, unknown>): string | undefined {
+		switch (name) {
+			case "Bash":
+				return typeof input.command === "string" ? input.command.slice(0, 80) : undefined;
+			case "Edit":
+			case "Read":
+			case "Write":
+				return typeof input.file_path === "string" ? input.file_path : undefined;
+			case "Glob":
+			case "Grep":
+				return typeof input.pattern === "string" ? input.pattern : undefined;
+			default:
+				return undefined;
+		}
 	}
 }

package/src/runners/codex.ts

@@ -1,81 +1,161 @@
 /**
- * CodexRunner — adapter for OpenAI Codex CLI.
+ * CodexRunner — adapter for OpenAI Codex via the Agent SDK.
  *
- * Spawns a headless Codex session in full-auto mode, uses exit code as
- * the primary success signal, and extracts error details from JSONL
- * output on failure.
+ * Creates a Codex client and thread per run(), consumes the async event
+ * stream internally. Console gets concise progress (tool calls, file
+ * changes, turn boundaries, errors); the log file captures the full
+ * event stream for debugging.
  */
 
+import { Codex, type ThreadEvent, type ThreadItem } from "@openai/codex-sdk";
 import type { LogWriter, Runner, RunResult } from "../types.js";
 
-function extractError(stdout: string): string {
-	for (const raw of stdout.split("\n")) {
-		const line = raw.trim();
-		if (!line) continue;
+type CodexFactory = (...args: ConstructorParameters<typeof Codex>) => InstanceType<typeof Codex>;
+let createCodex: CodexFactory = (...args) => new Codex(...args);
 
-		let event: unknown;
-		try {
-			event = JSON.parse(line);
-		} catch {
-			continue;
-		}
-
-		if (typeof event !== "object" || event === null || Array.isArray(event)) {
-			continue;
-		}
-
-		const rec = event as Record<string, unknown>;
-		const eventType = rec.type;
-
-		if (eventType === "turn.failed") {
-			const nested = rec.error;
-			if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
-				const msg = (nested as Record<string, unknown>).message;
-				if (typeof msg === "string" && msg) return msg;
-			}
-		} else if (eventType === "error") {
-			const msg = rec.message;
-			if (typeof msg === "string" && msg) return msg;
-		}
-	}
-
-	return "codex exited with non-zero status";
+/** @internal Replace the Codex factory. Returns a restore function. */
+export function _setCodexFactory(fn: CodexFactory): () => void {
+	const prev = createCodex;
+	createCodex = fn;
+	return () => {
+		createCodex = prev;
+	};
 }
 
 export class CodexRunner implements Runner {
-	logEnvironment(_logger: LogWriter): void {
-		// No environment-specific config to log for Codex.
+	private logger: LogWriter;
+
+	constructor(logger: LogWriter) {
+		this.logger = logger;
 	}
 
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
 
-		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
+		let threadId: string | undefined;
+		let turns = 0;
+		let inputTokens = 0;
+		let outputTokens = 0;
+		let failed = false;
+		let completed = false;
+		let errorMessage: string | undefined;
+
 		try {
-			proc = Bun.spawn(["codex", "exec", "--full-auto", "--json", "--ephemeral", "-"], {
-				stdin: new Response(prompt),
-				stdout: "pipe",
-				stderr: "pipe",
+			const codex = createCodex();
+			const thread = codex.startThread({
+				approvalPolicy: "never",
+				sandboxMode: "danger-full-access",
 			});
-		} catch {
+
+			const { events } = await thread.runStreamed(prompt);
+
+			for await (const event of events) {
+				this.handleEvent(event);
+
+				switch (event.type) {
+					case "thread.started":
+						threadId = event.thread_id;
+						break;
+					case "turn.started":
+						turns++;
+						break;
+					case "turn.completed":
+						completed = true;
+						this.logger.log(`[codex] Turn ${turns} completed`);
+						inputTokens += event.usage.input_tokens;
+						outputTokens += event.usage.output_tokens;
+						break;
+					case "turn.failed":
+						failed = true;
+						errorMessage = event.error.message;
+						this.logger.log(`[codex] Error: ${errorMessage}`);
+						break;
+					case "error":
+						failed = true;
+						errorMessage = event.message;
+						this.logger.log(`[codex] Error: ${errorMessage}`);
+						break;
+					case "item.started":
+					case "item.completed":
+						this.logItem(event.type, event.item);
+						break;
+				}
+			}
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+
+			if (msg.includes("ENOENT") || msg.includes("not found") || msg.includes("spawn")) {
+				return { success: false, durationSeconds, error: "codex binary not found in PATH" };
+			}
+			return { success: false, durationSeconds, error: msg };
+		}
+
+		const durationSeconds = (performance.now() - start) / 1000;
+
+		const status = failed ? "failed" : completed ? "success" : "incomplete";
+		this.logger.logFile(
+			`[codex] Result: ${status}, turns=${turns}, input=${inputTokens}, output=${outputTokens}`,
+		);
+
+		if (failed) {
 			return {
 				success: false,
-				exitCode: 1,
-				durationSeconds: (performance.now() - start) / 1000,
-				error: "codex binary not found in PATH",
+				durationSeconds,
+				error: errorMessage ?? "codex run failed",
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId: threadId,
 			};
 		}
 
-		const exitCode = await proc.exited;
-		const durationSeconds = (performance.now() - start) / 1000;
-
-		if (exitCode === 0) {
-			return { success: true, exitCode: 0, durationSeconds };
+		if (!completed) {
+			return {
+				success: false,
+				durationSeconds,
+				error: "no terminal event received from Codex",
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId: threadId,
+			};
 		}
 
-		const stdout = await new Response(proc.stdout as ReadableStream).text();
-		const error = extractError(stdout);
+		return {
+			success: true,
+			durationSeconds,
+			turns,
+			inputTokens,
+			outputTokens,
+			sessionId: threadId,
+		};
+	}
+
+	private handleEvent(event: ThreadEvent): void {
+		this.logger.logFile(`[codex] ${event.type}: ${JSON.stringify(event)}`);
+	}
 
-		return { success: false, exitCode, durationSeconds, error };
+	private logItem(phase: "item.started" | "item.completed", item: ThreadItem): void {
+		switch (item.type) {
+			case "command_execution":
+				if (phase === "item.started") {
+					this.logger.log(`[codex] Bash: ${item.command.slice(0, 80)}`);
+				}
+				break;
+			case "file_change":
+				if (phase === "item.completed") {
+					for (const change of item.changes) {
+						this.logger.log(`[codex] Edit: ${change.path}`);
+					}
+				}
+				break;
+			case "reasoning":
+				this.logger.logFile(`[codex] reasoning: ${item.text}`);
+				break;
+			case "error":
+				this.logger.log(`[codex] Error: ${item.message}`);
+				break;
+		}
 	}
 }

package/src/runners/index.ts

@@ -2,20 +2,20 @@
  * Runner registry — maps runner names to their implementations.
  */
 
-import type { Runner } from "../types.js";
+import type { LogWriter, Runner } from "../types.js";
 import { ClaudeRunner } from "./claude.js";
 import { CodexRunner } from "./codex.js";
 
-const RUNNERS: Record<string, new () => Runner> = {
+const RUNNERS: Record<string, new (logger: LogWriter) => Runner> = {
 	claude: ClaudeRunner,
 	codex: CodexRunner,
 };
 
-export function getRunner(name: string): Runner {
+export function getRunner(name: string, logger: LogWriter): Runner {
 	const Cls = RUNNERS[name];
 	if (!Cls) {
 		const available = Object.keys(RUNNERS).sort().join(", ");
 		throw new Error(`Unknown runner '${name}'. Available runners: ${available}`);
 	}
-	return new Cls();
+	return new Cls(logger);
 }

package/src/skills/stonecut-issues/SKILL.md

@@ -12,7 +12,7 @@ You are breaking a PRD into issues as part of the Stonecut workflow. Each issue
 Determine where the PRD lives. Check these in order:
 
 1. **Conversation context** — If a PRD was created earlier in this conversation (via `/stonecut-prd` or otherwise), you already know where it is. State where you found it and confirm with the user.
-2. **Ask the user** — If no PRD is in context, ask: "Where is the PRD? Give me a local file path (e.g., `.stonecut/ASC-1/prd.md`) or a GitHub issue number."
+2. **Ask the user** — If no PRD is in context, ask: "Where is the PRD? Give me a local file path (`.stonecut/specs/<name>/prd.md`) or a GitHub issue number."
 
 If given a GitHub issue number, fetch it with `gh issue view <number>`.
 If given a local path, read the file.
@@ -63,7 +63,7 @@ Iterate until the user approves the breakdown.
 
 Default to **matching the PRD location**:
 
-- If the PRD is a **local file** (e.g., `.stonecut/ASC-1/prd.md`), default to creating issues in the same directory under `issues/` (e.g., `.stonecut/ASC-1/issues/01-short-title.md`).
+- If the PRD is a **local file**, default to creating issues under `.stonecut/specs/<name>/issues/`.
 - If the PRD is a **GitHub issue**, default to creating issues as GitHub issues using `gh issue create`.
 
 Confirm with the user before creating. If they want a different destination, respect that.
@@ -75,7 +75,7 @@ Confirm with the user before creating. If they want a different destination, res
 Create each issue as a markdown file in the issues directory. Use zero-padded numbering with a kebab-case descriptive suffix:
 
 ```
-.stonecut/<name>/issues/
+.stonecut/specs/<name>/issues/
   01-short-descriptive-title.md
   02-another-slice-title.md
   ...
@@ -88,7 +88,7 @@ Create issues in dependency order (blockers first). Use the local issue template
 
 ## Parent PRD
 
-See `.stonecut/<name>/prd.md`
+See `.stonecut/specs/<name>/prd.md`
 
 ## What to build
 

package/src/skills/stonecut-prd/SKILL.md

@@ -29,7 +29,7 @@ Check with the user that these modules match their expectations. Ask which modul
 
 Ask the user where to save the PRD:
 
-- **Local file** — Save as `.stonecut/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/<name>/` directory if it doesn't exist.
+- **Local file** — Save as `.stonecut/specs/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID, a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
 - **GitHub issue** — Create a GitHub issue using `gh issue create --label prd`. Before creating, ensure the `prd` label exists:
 
   ```bash
@@ -39,8 +39,6 @@ Ask the user where to save the PRD:
   fi
   ```
 
-If the project already has a `.stonecut/` directory, default to suggesting local. Otherwise, just ask.
-
 ### 6. Documentation impact check
 
 Before writing the PRD, ensure that documentation impact has been explicitly addressed. Based on everything you've learned from the interview and codebase exploration, analyze which user-facing documentation artifacts (README, CLI help text, docs/ content) would be affected by these changes.

package/src/skills/stonecut-review-architecture/SKILL.md

@@ -75,7 +75,7 @@ After comparing, give your own recommendation: which design you think is stronge
 
 Ask the user where to save the RFC:
 
-- **Local file** — Save as `.stonecut/<name>/rfc.md` in the project. Ask the user: "What should I name this spec?" Create the `.stonecut/<name>/` directory if it doesn't exist.
+- **Local file** — Save as `.stonecut/specs/<name>/rfc.md` in the project. Ask the user: "What should I name this spec?" Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
 - **GitHub issue** — Create a GitHub issue using `gh issue create --label rfc`. Before creating, ensure the `rfc` label exists:
 
   ```bash

package/src/sources/github.ts

@@ -5,20 +5,9 @@
  * structured as a stateless SourceProvider.
  */
 
+import { runSync } from "../spawn";
 import type { IssueData, PrdData, PrdSummary, SourceProvider } from "./types.js";
 
-function runSync(cmd: string[]): { exitCode: number; stdout: string; stderr: string } {
-	const proc = Bun.spawnSync(cmd, {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	return {
-		exitCode: proc.exitCode,
-		stdout: proc.stdout.toString(),
-		stderr: proc.stderr.toString(),
-	};
-}
-
 export class GitHubSourceProvider implements SourceProvider {
 	readonly owner: string;
 	readonly repo: string;

package/src/spawn.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared synchronous process wrapper used by git.ts and sources/github.ts.
+ *
+ * Single source of truth for Bun.spawnSync stdout/stderr conversion.
+ */
+
+/** Run a command synchronously, optionally in a specific working directory. */
+export function runSync(
+	cmd: string[],
+	cwd?: string,
+): { exitCode: number; stdout: string; stderr: string } {
+	const proc = Bun.spawnSync(cmd, {
+		stdout: "pipe",
+		stderr: "pipe",
+		...(cwd && { cwd }),
+	});
+	return {
+		exitCode: proc.exitCode,
+		stdout: proc.stdout.toString(),
+		stderr: proc.stderr.toString(),
+	};
+}

package/src/sync-back.ts

@@ -0,0 +1,88 @@
+/**
+ * Sync-back — notify external sources when issues or PRDs complete.
+ *
+ * syncBackIssue: read frontmatter from an issue file, resolve provider, call onIssueComplete.
+ * syncBackPrd: read frontmatter from a PRD file, resolve provider, call onPrdComplete.
+ *
+ * Failures are logged as warnings but never thrown — sync-back is best-effort.
+ */
+
+import { readFileSync } from "fs";
+import { parseFrontmatter } from "./frontmatter";
+import { getSourceProvider } from "./sources/index";
+import type { LogWriter } from "./types";
+
+/**
+ * Configuration for syncing issue/PRD completion back to an external source.
+ *
+ * When provided to runAfkLoop, the runner reads frontmatter from completed
+ * issue files. If a `source` field is present, the corresponding provider
+ * is resolved and notified of the completion.
+ */
+export interface SyncBackConfig<T> {
+	/** Return the file path for a completed issue, or undefined to skip sync-back. */
+	getIssuePath: (issue: T) => string | undefined;
+	/** Path to the PRD file, used for sync-back after all issues complete. */
+	prdPath?: string;
+	/** Read a file's contents. Injectable for testing; defaults to fs.readFileSync. */
+	readFile?: (path: string) => string;
+	/** Resolve a source provider by name. Injectable for testing; defaults to getSourceProvider. */
+	resolveProvider?: (name: string) => {
+		onIssueComplete(id: string): Promise<void>;
+		onPrdComplete(id: string): Promise<void>;
+	};
+}
+
+/**
+ * Sync a completed issue back to its external source.
+ *
+ * Reads frontmatter from the issue file. If `source` and `issue` fields
+ * are present, resolves the provider and calls onIssueComplete.
+ * Failures are logged as warnings but never thrown.
+ */
+export async function syncBackIssue(
+	filePath: string,
+	logger: LogWriter,
+	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
+	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
+): Promise<void> {
+	try {
+		const content = readFile(filePath);
+		const { meta } = parseFrontmatter(content);
+		if (!meta.source || !meta.issue) return;
+
+		const provider = resolveProvider!(meta.source);
+		await provider.onIssueComplete(meta.issue);
+		logger.log(`Synced issue #${meta.issue} back to ${meta.source}`);
+	} catch (err: unknown) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.log(`Warning: sync-back failed for issue at ${filePath}: ${message}`);
+	}
+}
+
+/**
+ * Sync PRD completion back to its external source.
+ *
+ * Reads frontmatter from the PRD file. If `source` and `issue` fields
+ * are present, resolves the provider and calls onPrdComplete.
+ * Failures are logged as warnings but never thrown.
+ */
+export async function syncBackPrd(
+	filePath: string,
+	logger: LogWriter,
+	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
+	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
+): Promise<void> {
+	try {
+		const content = readFile(filePath);
+		const { meta } = parseFrontmatter(content);
+		if (!meta.source || !meta.issue) return;
+
+		const provider = resolveProvider!(meta.source);
+		await provider.onPrdComplete(meta.issue);
+		logger.log(`Synced PRD #${meta.issue} back to ${meta.source}`);
+	} catch (err: unknown) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.log(`Warning: sync-back failed for PRD at ${filePath}: ${message}`);
+	}
+}