pi-prompt-template-model 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-04-21
+
+### Added
+- Added first-class deterministic prompt-template execution for single prompt templates via `deterministic:` or shorthand `run` / `script` frontmatter. Templates can run one direct command or script before any optional LLM turn.
+- Added configurable deterministic-step handoff policies: `always`, `never`, `on-success`, and `on-failure`.
+- Added deterministic result cards that always show the executed command or script, resolved `cwd`, exit code, duration, and stdout/stderr previews.
+- Added deterministic-step `env` support plus `nonInteractive` control for deploy/release-style scripts that need explicit environment variables or want to disable the default non-interactive guardrail env bundle.
+- Added a visible deterministic completion message for `handoff: never`, so no-handoff runs still end with an explicit completion marker after the result card.
+
+### Changed
+- When a deterministic prompt hands off to the model, the extension now prepends a generated `[Deterministic step]` block with structured execution metadata and truncated stdout/stderr previews before the prompt body.
+- Deterministic stdout/stderr payloads are now capped before they are stored in message details, while preserving total line/character counts and truncation metadata for both the card UI and the LLM handoff block.
+
+### Fixed
+- Added regression coverage for deterministic loader parsing, relative script resolution, handoff gating, and the no-handoff fast path.
+- Deterministic timeouts now escalate from `SIGTERM` to `SIGKILL` if the child process does not exit within the post-timeout grace window.
+
 ## [0.7.3] - 2026-04-14
 
 ### Fixed

package/README.md

@@ -353,6 +353,128 @@ Within a compare lineup, use `task` for a full per-slot override and `taskSuffix
 
 When a compare prompt uses `bestOfN.worktree: true`, all worker slots must resolve to the same `cwd`. Mixed worker `cwd` values are only allowed when worktree isolation is off. Worktree isolation is for the worker phase only; `bestOfN.finalApplier` always applies on the real branch (`compareCwd`).
 
+## Deterministic Steps
+
+Prompt templates can run one deterministic command or script before any optional LLM turn. Use this when the first step should be direct code, not model latency.
+
+The flow is simple:
+
+1. Run one command or script.
+2. Always render a visible deterministic result card with the command, exit code, duration, and stdout/stderr previews.
+3. Optionally hand the structured result to the model as a `[Deterministic step]` preamble before the prompt body.
+4. If `handoff: never`, stop after the result card and a visible completion marker — no LLM turn happens.
+
+That handoff preamble is intentionally structured and uses stable field names like `status`, `executionKind`, `command`, `cwd`, `exitCode`, `signal`, `durationMs`, `timedOut`, `lineCount`, `charCount`, `truncated`, `omittedChars`, and `preview`.
+
+V1 scope is intentionally narrow: deterministic execution only works on single prompt templates. It does not combine with chain templates, delegated/subagent prompts, `parallel`, or loops. At runtime, deterministic prompts explicitly reject `--loop`, `--subagent`, and `--fork` in v1.
+
+### Authoring forms
+
+You can write deterministic steps as **top-level shorthand** or **nested under `deterministic:`**. Both are equivalent. Use shorthand for brevity, nested when you want everything grouped under one key.
+
+**Top-level shorthand** — put `run`, `script`, `handoff`, `timeout`, `cwd`, `env`, and `nonInteractive` directly in frontmatter:
+
+```markdown
+---
+run: git push origin HEAD:main
+handoff: on-failure
+timeout: 30000
+---
+If the push failed, explain why and suggest the next step.
+```
+
+You can also use `script:` as shorthand:
+
+```markdown
+---
+script: ./scripts/ship.sh
+handoff: always
+timeout: 15000
+---
+Summarize the script result.
+```
+
+**Nested form** — group everything under `deterministic:`:
+
+```markdown
+---
+model: claude-sonnet-4-20250514
+deterministic:
+  script:
+    path: ./scripts/ship.sh
+    args:
+      - --fast
+  handoff: always
+  timeout: 15000
+  cwd: ~/src/my-repo
+---
+Summarize the script result and call out anything risky.
+```
+
+**Structured command form** — when you need explicit args instead of a single shell string, use `deterministic.run.command` with `args`:
+
+```markdown
+---
+model: claude-sonnet-4-20250514
+deterministic:
+  run:
+    command: git
+    args: [status, --short]
+  handoff: always
+---
+Interpret the repo state.
+```
+
+Do not mix top-level shorthand with nested `deterministic:` in the same prompt. Pick one style.
+
+### Model requirement
+
+Deterministic prompts that hand off to the model (`handoff: always`, `on-success`, or `on-failure`) need a model to continue into. You can either:
+
+- Add a `model:` field explicitly
+- Omit `model:` and let the prompt inherit whatever model is currently active
+
+`handoff: never` prompts do not need a model field because they never reach the LLM.
+
+### Handoff values
+
+- `always` — always continue into the LLM after the deterministic card is emitted.
+- `never` — stop after the deterministic card and completion marker.
+- `on-success` — continue only when the command exits `0`.
+- `on-failure` — continue only when the command exits non-zero.
+
+Command descriptions in the slash-command picker show this feature as `deterministic-step:<handoff>`.
+
+### Timeout
+
+`timeout` is in milliseconds. When a timeout fires, the runner sends `SIGTERM` first. If the process still has not exited after a short grace window, it escalates to `SIGKILL`.
+
+### Script path resolution
+
+Relative script paths resolve from the prompt file's directory first, then fall back to the command invocation `cwd`. Absolute script paths also work.
+
+### Environment and non-interactive mode
+
+You can provide explicit environment variables and control the runner's non-interactive guardrails:
+
+```markdown
+---
+deterministic:
+  run: ./deploy.sh
+  handoff: never
+  nonInteractive: false
+  env:
+    SPECIAL_TOKEN: abc123
+    RETRIES: 2
+---
+```
+
+`nonInteractive` defaults to `true`. In that mode the runner keeps stdin ignored and adds a few guardrail environment defaults such as `CI=1`, `GIT_TERMINAL_PROMPT=0`, `PAGER=cat`, and `GIT_PAGER=cat`. Set `nonInteractive: false` when the command needs a more normal process environment and you explicitly want to opt out of those defaults. Explicit `env` values override the built-in defaults.
+
+### Output capping
+
+Large stdout/stderr streams are capped before they are stored in the conversation card payload. The card and the LLM handoff block both show the total character and line counts plus explicit truncation metadata when output was capped.
+
 ## Loop Execution
 
 Run a template multiple times with `--loop`:
@@ -672,3 +794,4 @@ $@
 - In chains, model-less steps inherit the chain-start model snapshot, not the previous step's model. This is intentional for deterministic behavior.
 - Delegated `subagent` prompts require [pi-subagents](https://github.com/nicobailon/pi-subagents/).
 - `run-prompt` must be explicitly enabled with `/prompt-tool on`.
+rompt-tool on`.

package/deterministic-renderer.ts

@@ -0,0 +1,136 @@
+import type { MessageRenderOptions, Theme } from "@mariozechner/pi-coding-agent";
+import { Box, Container, Spacer, Text } from "@mariozechner/pi-tui";
+import { formatDeterministicExecution, type DeterministicExecutionResult } from "./deterministic-step.js";
+
+interface DeterministicMessage {
+	content?: unknown;
+	details?: DeterministicExecutionResult;
+}
+
+interface DeterministicCompletionMessage {
+	content?: unknown;
+	details?: {
+		promptName: string;
+		exitCode: number;
+		timedOut: boolean;
+		status: "succeeded" | "failed";
+	};
+}
+
+const PREVIEW_LINES = 8;
+
+function formatDuration(durationMs: number): string {
+	if (durationMs < 1_000) return `${durationMs}ms`;
+	if (durationMs < 10_000) return `${(durationMs / 1_000).toFixed(1)}s`;
+	return `${Math.round(durationMs / 1_000)}s`;
+}
+
+function buildCapturedOutputLabel(
+	label: string,
+	meta: { totalChars: number; totalLines: number; truncated: boolean },
+): string {
+	if (meta.totalChars === 0) return `${label} · empty`;
+	const lineCount = meta.totalLines;
+	const charCount = meta.totalChars.toLocaleString();
+	const truncated = meta.truncated ? " · capped" : "";
+	return `${label} · ${lineCount} line${lineCount === 1 ? "" : "s"} · ${charCount} chars${truncated}`;
+}
+
+function renderOutputSection(
+	box: Box,
+	label: string,
+	value: string,
+	meta: { totalChars: number; totalLines: number; truncated: boolean },
+	options: MessageRenderOptions,
+	theme: Theme,
+) {
+	box.addChild(new Text(theme.fg("toolTitle", buildCapturedOutputLabel(label, meta)), 0, 0));
+	if (!value) {
+		box.addChild(new Text(theme.fg("dim", "(empty)"), 0, 0));
+		return;
+	}
+	const lines = value.split("\n");
+	if (options.expanded || lines.length <= PREVIEW_LINES) {
+		box.addChild(new Text(theme.fg("toolOutput", value), 0, 0));
+		if (meta.truncated) {
+			box.addChild(new Text(theme.fg("warning", `\n... (stored preview capped, ${Math.max(0, meta.totalChars - value.length)} more chars hidden)`), 0, 0));
+		}
+		return;
+	}
+	box.addChild(new Text(theme.fg("toolOutput", lines.slice(0, PREVIEW_LINES).join("\n")), 0, 0));
+	box.addChild(new Text(theme.fg("warning", `\n... (${lines.length - PREVIEW_LINES} more lines hidden — Ctrl+O to expand)`), 0, 0));
+	if (meta.truncated) {
+		box.addChild(new Text(theme.fg("warning", `\n... (stored preview capped, ${Math.max(0, meta.totalChars - value.length)} more chars hidden)`), 0, 0));
+	}
+}
+
+export function renderDeterministicResult(message: DeterministicMessage, options: MessageRenderOptions, theme: Theme) {
+	const details = message.details;
+	const container = new Container();
+	container.addChild(new Spacer(1));
+	if (!details) {
+		container.addChild(new Text(theme.fg("warning", "Deterministic step message is missing details."), 0, 0));
+		return container;
+	}
+
+	const failed = details.exitCode !== 0;
+	const box = new Box(1, 1, (text: string) => theme.bg(failed ? "toolPendingBg" : "toolSuccessBg", text));
+	const icon = theme.fg(failed ? "error" : "success", failed ? "fail" : "ok");
+	const status = failed ? "failed" : "succeeded";
+	const title = formatDeterministicExecution(details.execution, details.resolvedScriptPath);
+	box.addChild(new Text(`${icon} ${theme.fg("toolTitle", theme.bold("deterministic"))} | ${status} · exit ${details.exitCode} · ${formatDuration(details.durationMs)}`, 0, 0));
+	box.addChild(new Spacer(1));
+	box.addChild(new Text(theme.fg("dim", `command: ${title}`), 0, 0));
+	if (details.resolvedScriptPath) {
+		box.addChild(new Text(theme.fg("dim", `script: ${details.resolvedScriptPath}`), 0, 0));
+	}
+	box.addChild(new Text(theme.fg("dim", `cwd: ${details.cwd}`), 0, 0));
+	if (details.signal) {
+		box.addChild(new Text(theme.fg("dim", `signal: ${details.signal}`), 0, 0));
+	}
+	if (details.timedOut) {
+		box.addChild(new Text(theme.fg("error", "timeout reached before the process exited"), 0, 0));
+	}
+	box.addChild(new Text(theme.fg("dim", `nonInteractive: ${details.nonInteractive ? "true" : "false"}`), 0, 0));
+	box.addChild(new Spacer(1));
+	renderOutputSection(box, "stdout", details.stdout, {
+		totalChars: details.stdoutTotalChars,
+		totalLines: details.stdoutTotalLines,
+		truncated: details.stdoutTruncated,
+	}, options, theme);
+	box.addChild(new Spacer(1));
+	renderOutputSection(box, "stderr", details.stderr, {
+		totalChars: details.stderrTotalChars,
+		totalLines: details.stderrTotalLines,
+		truncated: details.stderrTruncated,
+	}, options, theme);
+	container.addChild(box);
+	return container;
+}
+
+export function renderDeterministicCompletion(
+	message: DeterministicCompletionMessage,
+	_options: MessageRenderOptions,
+	theme: Theme,
+) {
+	const details = message.details;
+	const container = new Container();
+	container.addChild(new Spacer(1));
+	if (!details) {
+		container.addChild(new Text(theme.fg("warning", "Deterministic completion message is missing details."), 0, 0));
+		return container;
+	}
+
+	const failed = details.status === "failed";
+	const box = new Box(1, 1, (text: string) => theme.bg(failed ? "toolPendingBg" : "toolSuccessBg", text));
+	const icon = theme.fg(failed ? "error" : "success", failed ? "fail" : "ok");
+	box.addChild(new Text(`${icon} ${theme.fg("toolTitle", theme.bold("deterministic complete"))} | ${details.status} · exit ${details.exitCode}`, 0, 0));
+	box.addChild(new Spacer(1));
+	box.addChild(new Text(theme.fg("dim", `prompt: ${details.promptName}`), 0, 0));
+	box.addChild(new Text(theme.fg("dim", "model handoff: skipped"), 0, 0));
+	if (details.timedOut) {
+		box.addChild(new Text(theme.fg("error", "the command hit its timeout before completion"), 0, 0));
+	}
+	container.addChild(box);
+	return container;
+}

package/deterministic-step.ts

@@ -0,0 +1,309 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import type { PromptWithModel, DeterministicStep, DeterministicExecution, DeterministicEnv } from "./prompt-loader.js";
+
+export const PROMPT_TEMPLATE_DETERMINISTIC_MESSAGE_TYPE = "prompt-template-deterministic";
+export const PROMPT_TEMPLATE_DETERMINISTIC_COMPLETION_MESSAGE_TYPE = "prompt-template-deterministic-complete";
+
+const DEFAULT_MAX_CAPTURE_STDOUT_CHARS = 16_000;
+const DEFAULT_MAX_CAPTURE_STDERR_CHARS = 16_000;
+const DEFAULT_TIMEOUT_KILL_AFTER_MS = 1_000;
+
+interface CapturedOutput {
+	text: string;
+	totalChars: number;
+	totalNewlines: number;
+	trailingNewlineRun: number;
+	sawNonNewline: boolean;
+	truncated: boolean;
+	maxChars: number;
+}
+
+export interface DeterministicExecutionResult {
+	execution: DeterministicExecution;
+	cwd: string;
+	nonInteractive: boolean;
+	resolvedScriptPath?: string;
+	exitCode: number;
+	signal?: NodeJS.Signals;
+	stdout: string;
+	stdoutTotalChars: number;
+	stdoutTotalLines: number;
+	stdoutTruncated: boolean;
+	stderr: string;
+	stderrTotalChars: number;
+	stderrTotalLines: number;
+	stderrTruncated: boolean;
+	durationMs: number;
+	timedOut: boolean;
+}
+
+export interface DeterministicPreambleOptions {
+	maxStdoutChars?: number;
+	maxStderrChars?: number;
+}
+
+function createCapturedOutput(maxChars: number): CapturedOutput {
+	return {
+		text: "",
+		totalChars: 0,
+		totalNewlines: 0,
+		trailingNewlineRun: 0,
+		sawNonNewline: false,
+		truncated: false,
+		maxChars,
+	};
+}
+
+function appendCapturedOutput(output: CapturedOutput, chunk: string): void {
+	if (!chunk) return;
+	output.totalChars += chunk.length;
+	const newlines = chunk.match(/\n/g)?.length ?? 0;
+	output.totalNewlines += newlines;
+	if (/[^\n]/.test(chunk)) output.sawNonNewline = true;
+	const trailingRun = chunk.match(/\n+$/)?.[0].length ?? 0;
+	if (trailingRun === 0) {
+		output.trailingNewlineRun = 0;
+	} else if (trailingRun === chunk.length) {
+		output.trailingNewlineRun += trailingRun;
+	} else {
+		output.trailingNewlineRun = trailingRun;
+	}
+
+	if (output.text.length < output.maxChars) {
+		const remaining = output.maxChars - output.text.length;
+		output.text += chunk.slice(0, remaining);
+	}
+	if (output.totalChars > output.maxChars) output.truncated = true;
+}
+
+function capturedLineCount(output: Pick<CapturedOutput, "totalChars" | "sawNonNewline" | "totalNewlines" | "trailingNewlineRun">): number {
+	if (output.totalChars === 0) return 0;
+	if (!output.sawNonNewline) return 1;
+	return output.totalNewlines - output.trailingNewlineRun + 1;
+}
+
+function countLines(value: string): number {
+	if (!value) return 0;
+	const normalized = value.replace(/\n+$/g, "");
+	if (!normalized) return 1;
+	return normalized.split("\n").length;
+}
+
+function buildTextPreview(label: string, value: string, totalChars: number, maxChars: number): { text: string; truncated: boolean; omittedChars: number } {
+	const shownChars = Math.min(value.length, maxChars);
+	const preview = value.slice(0, shownChars);
+	const omittedChars = Math.max(0, totalChars - shownChars);
+	if (omittedChars === 0) {
+		return { text: preview, truncated: false, omittedChars: 0 };
+	}
+	return {
+		text: `${preview}\n...[${label} truncated, ${omittedChars} more chars omitted]`,
+		truncated: true,
+		omittedChars,
+	};
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+export function formatDeterministicExecution(execution: DeterministicExecution, resolvedScriptPath?: string): string {
+	switch (execution.kind) {
+		case "run":
+			return execution.command;
+		case "command": {
+			const parts = [execution.command, ...execution.args].map((part) => shellQuote(part));
+			return execution.shell ? `${parts.join(" ")} (shell)` : parts.join(" ");
+		}
+		case "script": {
+			const scriptPath = resolvedScriptPath ?? execution.path;
+			const parts = [scriptPath, ...execution.args].map((part) => shellQuote(part));
+			return parts.join(" ");
+		}
+	}
+}
+
+export function shouldHandoffToLlm(step: DeterministicStep, result: Pick<DeterministicExecutionResult, "exitCode">): boolean {
+	switch (step.handoff) {
+		case "always": return true;
+		case "never": return false;
+		case "on-success": return result.exitCode === 0;
+		case "on-failure": return result.exitCode !== 0;
+	}
+}
+
+function buildOutputPreambleSectionFromResult(
+	label: "stdout" | "stderr",
+	value: string,
+	meta: { totalChars: number; totalLines: number },
+	maxChars: number,
+): string[] {
+	const preview = buildTextPreview(label, value, meta.totalChars, maxChars);
+	return [
+		`[${label}]`,
+		`lineCount: ${meta.totalLines}`,
+		`charCount: ${meta.totalChars}`,
+		`truncated: ${preview.truncated ? "true" : "false"}`,
+		preview.truncated ? `omittedChars: ${preview.omittedChars}` : undefined,
+		"preview:",
+		preview.text || "(empty)",
+	];
+}
+
+export function buildDeterministicPreamble(
+	result: DeterministicExecutionResult,
+	options: DeterministicPreambleOptions = {},
+): string {
+	const maxStdoutChars = options.maxStdoutChars ?? 8_000;
+	const maxStderrChars = options.maxStderrChars ?? 4_000;
+	const command = formatDeterministicExecution(result.execution, result.resolvedScriptPath);
+	return [
+		"[Deterministic step]",
+		`status: ${result.exitCode === 0 ? "succeeded" : "failed"}`,
+		`executionKind: ${result.execution.kind}`,
+		`command: ${command.includes("\n") ? JSON.stringify(command) : command}`,
+		result.resolvedScriptPath ? `resolvedScript: ${result.resolvedScriptPath}` : undefined,
+		`cwd: ${result.cwd}`,
+		`nonInteractive: ${result.nonInteractive ? "true" : "false"}`,
+		`exitCode: ${result.exitCode}`,
+		result.signal ? `signal: ${result.signal}` : undefined,
+		`durationMs: ${result.durationMs}`,
+		`timedOut: ${result.timedOut ? "true" : "false"}`,
+		"",
+		...buildOutputPreambleSectionFromResult("stdout", result.stdout, {
+			totalChars: result.stdoutTotalChars,
+			totalLines: result.stdoutTotalLines,
+		}, maxStdoutChars),
+		"",
+		...buildOutputPreambleSectionFromResult("stderr", result.stderr, {
+			totalChars: result.stderrTotalChars,
+			totalLines: result.stderrTotalLines,
+		}, maxStderrChars),
+	].filter((line): line is string => line !== undefined).join("\n");
+}
+
+function resolveScriptPath(prompt: Pick<PromptWithModel, "filePath">, cwd: string, execution: Extract<DeterministicExecution, { kind: "script" }>): string {
+	if (isAbsolute(execution.path)) return execution.path;
+	const promptRelative = resolve(dirname(prompt.filePath), execution.path);
+	if (existsSync(promptRelative)) return promptRelative;
+	return resolve(cwd, execution.path);
+}
+
+function buildDeterministicEnv(step: Pick<DeterministicStep, "env" | "nonInteractive">): NodeJS.ProcessEnv {
+	const nonInteractiveDefaults: DeterministicEnv = step.nonInteractive
+		? {
+			CI: "1",
+			GIT_TERMINAL_PROMPT: "0",
+			PAGER: "cat",
+			GIT_PAGER: "cat",
+		}
+		: {};
+	return {
+		...process.env,
+		...nonInteractiveDefaults,
+		...(step.env ?? {}),
+	};
+}
+
+function spawnProcess(command: string, args: string[], options: { cwd: string; shell?: boolean; env: NodeJS.ProcessEnv }) {
+	return spawn(command, args, {
+		cwd: options.cwd,
+		shell: options.shell ?? false,
+		env: options.env,
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+}
+
+export async function runDeterministicStep(
+	prompt: Pick<PromptWithModel, "filePath">,
+	step: DeterministicStep,
+	cwd: string,
+): Promise<DeterministicExecutionResult> {
+	const startedAt = Date.now();
+	const execution = step.execution;
+	const resolvedCwd = step.cwd ?? cwd;
+	const env = buildDeterministicEnv(step);
+	const resolvedScriptPath = execution.kind === "script"
+		? resolveScriptPath(prompt, resolvedCwd, execution)
+		: undefined;
+	const child = execution.kind === "run"
+		? spawnProcess("/bin/bash", ["-lc", execution.command], { cwd: resolvedCwd, env })
+		: execution.kind === "command"
+			? spawnProcess(execution.command, execution.args, { cwd: resolvedCwd, shell: execution.shell, env })
+			: spawnProcess(resolvedScriptPath!, execution.args, { cwd: resolvedCwd, env });
+
+	const stdout = createCapturedOutput(DEFAULT_MAX_CAPTURE_STDOUT_CHARS);
+	const stderr = createCapturedOutput(DEFAULT_MAX_CAPTURE_STDERR_CHARS);
+	let timedOut = false;
+	let timeoutKillHandle: NodeJS.Timeout | undefined;
+
+	child.stdout.on("data", (chunk) => {
+		appendCapturedOutput(stdout, chunk.toString());
+	});
+	child.stderr.on("data", (chunk) => {
+		appendCapturedOutput(stderr, chunk.toString());
+	});
+
+	const timeoutHandle = step.timeoutMs
+		? setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+			timeoutKillHandle = setTimeout(() => {
+				child.kill("SIGKILL");
+			}, DEFAULT_TIMEOUT_KILL_AFTER_MS);
+		}, step.timeoutMs)
+		: undefined;
+
+	return await new Promise((resolveResult) => {
+		let settled = false;
+		child.on("error", (error) => {
+			if (settled) return;
+			settled = true;
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			if (timeoutKillHandle) clearTimeout(timeoutKillHandle);
+			resolveResult({
+				execution,
+				cwd: resolvedCwd,
+				nonInteractive: step.nonInteractive,
+				resolvedScriptPath,
+				exitCode: 1,
+				stdout: stdout.text,
+				stdoutTotalChars: stdout.totalChars,
+				stdoutTotalLines: capturedLineCount(stdout),
+				stdoutTruncated: stdout.truncated,
+				stderr: stderr.text ? `${stderr.text}\n${error.message}` : error.message,
+				stderrTotalChars: stderr.totalChars + (stderr.text ? error.message.length + 1 : error.message.length),
+				stderrTotalLines: countLines(stderr.text ? `${stderr.text}\n${error.message}` : error.message),
+				stderrTruncated: stderr.truncated,
+				durationMs: Date.now() - startedAt,
+				timedOut,
+			});
+		});
+		child.on("close", (exitCode, signal) => {
+			if (settled) return;
+			settled = true;
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			if (timeoutKillHandle) clearTimeout(timeoutKillHandle);
+			resolveResult({
+				execution,
+				cwd: resolvedCwd,
+				nonInteractive: step.nonInteractive,
+				resolvedScriptPath,
+				exitCode: exitCode ?? (timedOut ? 124 : 1),
+				signal: signal ?? undefined,
+				stdout: stdout.text,
+				stdoutTotalChars: stdout.totalChars,
+				stdoutTotalLines: capturedLineCount(stdout),
+				stdoutTruncated: stdout.truncated,
+				stderr: stderr.text,
+				stderrTotalChars: stderr.totalChars,
+				stderrTotalLines: capturedLineCount(stderr),
+				stderrTruncated: stderr.truncated,
+				durationMs: Date.now() - startedAt,
+				timedOut,
+			});
+		});
+	});
+}

package/index.ts

@@ -34,6 +34,14 @@ import { createToolManager } from "./tool-manager.js";
 import { executeSubagentPromptStep, type DelegatedPromptParallelResult } from "./subagent-step.js";
 import { DEFAULT_SUBAGENT_NAME, PROMPT_TEMPLATE_SUBAGENT_MESSAGE_TYPE } from "./subagent-runtime.js";
 import { renderDelegatedSubagentResult } from "./subagent-renderer.js";
+import {
+	PROMPT_TEMPLATE_DETERMINISTIC_COMPLETION_MESSAGE_TYPE,
+	PROMPT_TEMPLATE_DETERMINISTIC_MESSAGE_TYPE,
+	buildDeterministicPreamble,
+	runDeterministicStep,
+	shouldHandoffToLlm,
+} from "./deterministic-step.js";
+import { renderDeterministicCompletion, renderDeterministicResult } from "./deterministic-renderer.js";
 
 interface LoopState {
 	currentIteration: number;
@@ -125,6 +133,8 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 
 	pi.registerMessageRenderer<SkillLoadedDetails>("skill-loaded", renderSkillLoaded);
 	pi.registerMessageRenderer(PROMPT_TEMPLATE_SUBAGENT_MESSAGE_TYPE, renderDelegatedSubagentResult);
+	pi.registerMessageRenderer(PROMPT_TEMPLATE_DETERMINISTIC_MESSAGE_TYPE, renderDeterministicResult);
+	pi.registerMessageRenderer(PROMPT_TEMPLATE_DETERMINISTIC_COMPLETION_MESSAGE_TYPE, renderDeterministicCompletion);
 
 	function registerPromptCommand(name: string) {
 		pi.registerCommand(name, {
@@ -248,6 +258,40 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		taskPreamble?: string,
 		loopContext?: string,
 	): Promise<PromptStepResult | "aborted"> {
+		let deterministicPreamble: string | undefined;
+		if (prompt.deterministic) {
+			try {
+				const deterministicResult = await runDeterministicStep(prompt, prompt.deterministic, ctx.cwd);
+				const deterministicPreambleText = buildDeterministicPreamble(deterministicResult);
+				pi.sendMessage({
+					customType: PROMPT_TEMPLATE_DETERMINISTIC_MESSAGE_TYPE,
+					content: deterministicPreambleText,
+					display: true,
+					details: deterministicResult,
+				});
+				if (!shouldHandoffToLlm(prompt.deterministic, deterministicResult)) {
+					pi.sendMessage({
+						customType: PROMPT_TEMPLATE_DETERMINISTIC_COMPLETION_MESSAGE_TYPE,
+						content: `[Deterministic complete: ${prompt.name}]`,
+						display: true,
+						details: {
+							promptName: prompt.name,
+							exitCode: deterministicResult.exitCode,
+							timedOut: deterministicResult.timedOut,
+							status: deterministicResult.exitCode === 0 ? "succeeded" : "failed",
+						},
+					});
+					return { changed: false };
+				}
+				deterministicPreamble = deterministicPreambleText;
+			} catch (error) {
+				notify(ctx, `Deterministic step failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+				return "aborted";
+			}
+		}
+
+		const combinedTaskPreamble = [taskPreamble, deterministicPreamble].filter(Boolean).join("\n\n");
+
 		if (shouldDelegatePrompt(prompt, override)) {
 			try {
 				const delegated =
@@ -259,7 +303,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 							override,
 							signal: ctx.signal,
 							inheritedModel,
-							taskPreamble,
+							taskPreamble: combinedTaskPreamble || undefined,
 							parallel: Array.from({ length: prompt.parallel }, (_, index) => ({
 								prompt,
 								args,
@@ -276,7 +320,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 							override,
 							signal: ctx.signal,
 							inheritedModel,
-							taskPreamble,
+							taskPreamble: combinedTaskPreamble || undefined,
 						});
 				if (!delegated) {
 					notify(ctx, `Prompt \`${prompt.name}\` is not configured for delegated execution.`, "error");
@@ -327,7 +371,10 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		pendingSkillMessage = skillResolution.kind === "ready" ? skillResolution.message : undefined;
 
 		const startId = ctx.sessionManager.getLeafId();
-		const content = loopContext ? `[${loopContext}]\n\n${prepared.content}` : prepared.content;
+		const effectiveContent = combinedTaskPreamble
+			? `${combinedTaskPreamble}\n\n${prepared.content}`
+			: prepared.content;
+		const content = loopContext ? `[${loopContext}]\n\n${effectiveContent}` : effectiveContent;
 		pi.sendUserMessage(content);
 		await waitForTurnStart(ctx);
 		await ctx.waitForIdle();
@@ -1393,6 +1440,16 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			return;
 		}
 		const argsWithoutSubagent = subagent.args;
+		if (prompt.deterministic) {
+			if (subagent.override || subagent.fork) {
+				notify(ctx, `Deterministic prompts do not support runtime --subagent/--fork in v1`, "error");
+				return;
+			}
+			if (extractLoopCount(argsWithoutSubagent)) {
+				notify(ctx, `Deterministic prompts do not support runtime --loop in v1`, "error");
+				return;
+			}
+		}
 
 		const hasCompareLineup = prompt.workers !== undefined || prompt.reviewers !== undefined || prompt.finalApplier !== undefined;
 		if (hasCompareLineup) {
@@ -1482,7 +1539,14 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			return;
 		}
 
-		const effectivePrompt = { ...prompt, ...(runtimeCwd ? { cwd: runtimeCwd } : {}), ...promptOverrides };
+		const effectivePrompt = {
+			...prompt,
+			...(runtimeCwd ? {
+				cwd: runtimeCwd,
+				...(prompt.deterministic ? { deterministic: { ...prompt.deterministic, cwd: runtimeCwd } } : {}),
+			} : {}),
+			...promptOverrides,
+		};
 		const savedModel = getCurrentModel(ctx);
 		const savedThinking = pi.getThinkingLevel();
 		const stepResult = await executePromptStep(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-prompt-template-model",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "type": "module",
   "description": "Prompt template model selector extension for pi coding agent",
   "author": "Nico Bailon",
@@ -30,6 +30,8 @@
     "notifications.ts",
     "prompt-execution.ts",
     "prompt-loader.ts",
+    "deterministic-step.ts",
+    "deterministic-renderer.ts",
     "subagent-renderer.ts",
     "subagent-runtime.ts",
     "subagent-step.ts",

package/prompt-loader.ts

@@ -41,6 +41,24 @@ export interface DelegationLineupSlot {
 	count?: number;
 }
 
+export type DeterministicHandoff = "always" | "never" | "on-success" | "on-failure";
+
+export type DeterministicExecution =
+	| { kind: "run"; command: string }
+	| { kind: "command"; command: string; args: string[]; shell: boolean }
+	| { kind: "script"; path: string; args: string[] };
+
+export type DeterministicEnv = Record<string, string>;
+
+export interface DeterministicStep {
+	execution: DeterministicExecution;
+	handoff: DeterministicHandoff;
+	nonInteractive: boolean;
+	timeoutMs?: number;
+	cwd?: string;
+	env?: DeterministicEnv;
+}
+
 export interface PromptWithModel {
 	name: string;
 	description: string;
@@ -58,6 +76,7 @@ export interface PromptWithModel {
 	converge?: boolean;
 	parallel?: number;
 	worktree?: boolean;
+	deterministic?: DeterministicStep;
 	subagent?: true | string;
 	inheritContext?: boolean;
 	cwd?: string;
@@ -348,6 +367,378 @@ function normalizeParallel(
 	return undefined;
 }
 
+function normalizeStringArrayField(
+	field: string,
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): string[] | undefined {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) {
+		diagnostics.push(
+			createDiagnostic(
+				`invalid-${field}`,
+				filePath,
+				source,
+				`Ignoring invalid ${field} value in ${filePath}: expected an array of strings.`,
+			),
+		);
+		return undefined;
+	}
+
+	const args: string[] = [];
+	for (const entry of value) {
+		if (typeof entry !== "string") {
+			diagnostics.push(
+				createDiagnostic(
+					`invalid-${field}`,
+					filePath,
+					source,
+					`Ignoring invalid ${field} value in ${filePath}: expected an array of strings.`,
+				),
+			);
+			return undefined;
+		}
+		args.push(entry);
+	}
+	return args;
+}
+
+function normalizeDeterministicHandoff(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): DeterministicHandoff {
+	if (value === undefined) return "always";
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "always" || normalized === "never" || normalized === "on-success" || normalized === "on-failure") {
+			return normalized;
+		}
+	}
+
+	diagnostics.push(
+		createDiagnostic(
+			"invalid-deterministic-handoff",
+			filePath,
+			source,
+			`Using default deterministic handoff=always for ${filePath}: expected "always", "never", "on-success", or "on-failure".`,
+		),
+	);
+	return "always";
+}
+
+function normalizeTimeoutMs(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): number | undefined {
+	if (value === undefined) return undefined;
+	let timeoutMs: number | undefined;
+	if (typeof value === "number") timeoutMs = value;
+	if (typeof value === "string" && /^\d+$/.test(value.trim())) timeoutMs = parseInt(value.trim(), 10);
+	if (timeoutMs !== undefined && Number.isInteger(timeoutMs) && timeoutMs >= 1) return timeoutMs;
+
+	diagnostics.push(
+		createDiagnostic(
+			"invalid-deterministic-timeout",
+			filePath,
+			source,
+			`Ignoring invalid deterministic timeout in ${filePath}: expected an integer greater than or equal to 1 (milliseconds).`,
+		),
+	);
+	return undefined;
+}
+
+function normalizeDeterministicEnv(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): DeterministicEnv | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-env",
+				filePath,
+				source,
+				`Ignoring invalid deterministic env in ${filePath}: expected an object with string/number/boolean values.`,
+			),
+		);
+		return undefined;
+	}
+
+	const env: DeterministicEnv = {};
+	for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+		if (!key.trim()) {
+			diagnostics.push(
+				createDiagnostic(
+					"invalid-deterministic-env",
+					filePath,
+					source,
+					`Ignoring invalid deterministic env in ${filePath}: env keys must be non-empty strings.`,
+				),
+			);
+			return undefined;
+		}
+		if (typeof raw !== "string" && typeof raw !== "number" && typeof raw !== "boolean") {
+			diagnostics.push(
+				createDiagnostic(
+					"invalid-deterministic-env",
+					filePath,
+					source,
+					`Ignoring invalid deterministic env in ${filePath}: env value for ${JSON.stringify(key)} must be a string, number, or boolean.`,
+				),
+			);
+			return undefined;
+		}
+		env[key] = String(raw);
+	}
+
+	return Object.keys(env).length > 0 ? env : undefined;
+}
+
+function normalizeDeterministicNonInteractive(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): boolean {
+	if (value === undefined) return true;
+	if (typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true") return true;
+		if (normalized === "false") return false;
+	}
+
+	diagnostics.push(
+		createDiagnostic(
+			"invalid-deterministic-non-interactive",
+			filePath,
+			source,
+			`Using default deterministic nonInteractive=true for ${filePath}: expected true or false.`,
+		),
+	);
+	return true;
+}
+
+function normalizeDeterministicRunValue(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): DeterministicExecution | undefined {
+	if (typeof value === "string") {
+		const command = value.trim();
+		if (command) return { kind: "run", command };
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-run",
+				filePath,
+				source,
+				`Ignoring invalid deterministic run value in ${filePath}: expected a non-empty string or an object with command/args.`,
+			),
+		);
+		return undefined;
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-run",
+				filePath,
+				source,
+				`Ignoring invalid deterministic run value in ${filePath}: expected a non-empty string or an object with command/args.`,
+			),
+		);
+		return undefined;
+	}
+
+	const record = value as Record<string, unknown>;
+	const command = normalizeStringField("deterministic.run.command", record.command, filePath, source, diagnostics);
+	if (!command) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-run",
+				filePath,
+				source,
+				`Ignoring invalid deterministic run value in ${filePath}: expected object field "command" to be a non-empty string.`,
+			),
+		);
+		return undefined;
+	}
+	const args = normalizeStringArrayField("deterministic.run.args", record.args, filePath, source, diagnostics);
+	if (!args) return undefined;
+	let shell = false;
+	if (record.shell !== undefined) {
+		if (typeof record.shell === "boolean") {
+			shell = record.shell;
+		} else {
+			diagnostics.push(
+				createDiagnostic(
+					"invalid-deterministic-run",
+					filePath,
+					source,
+					`Ignoring invalid deterministic run value in ${filePath}: object field "shell" must be true or false.`,
+				),
+			);
+			return undefined;
+		}
+	}
+	return { kind: "command", command, args, shell };
+}
+
+function normalizeDeterministicScriptValue(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): DeterministicExecution | undefined {
+	if (typeof value === "string") {
+		const path = value.trim();
+		if (path) return { kind: "script", path, args: [] };
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-script",
+				filePath,
+				source,
+				`Ignoring invalid deterministic script value in ${filePath}: expected a non-empty string or an object with path/args.`,
+			),
+		);
+		return undefined;
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-script",
+				filePath,
+				source,
+				`Ignoring invalid deterministic script value in ${filePath}: expected a non-empty string or an object with path/args.`,
+			),
+		);
+		return undefined;
+	}
+
+	const record = value as Record<string, unknown>;
+	const path = normalizeStringField("deterministic.script.path", record.path, filePath, source, diagnostics);
+	if (!path) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-script",
+				filePath,
+				source,
+				`Ignoring invalid deterministic script value in ${filePath}: expected object field "path" to be a non-empty string.`,
+			),
+		);
+		return undefined;
+	}
+	const args = normalizeStringArrayField("deterministic.script.args", record.args, filePath, source, diagnostics);
+	if (!args) return undefined;
+	return { kind: "script", path, args };
+}
+
+function normalizeDeterministic(
+	frontmatter: Record<string, unknown>,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): DeterministicStep | undefined {
+	const hasNested = Object.hasOwn(frontmatter, "deterministic");
+	const hasRun = Object.hasOwn(frontmatter, "run");
+	const hasScript = Object.hasOwn(frontmatter, "script");
+	const hasHandoff = Object.hasOwn(frontmatter, "handoff");
+	const hasTimeout = Object.hasOwn(frontmatter, "timeout");
+	const hasEnv = Object.hasOwn(frontmatter, "env");
+	const hasNonInteractive = Object.hasOwn(frontmatter, "nonInteractive");
+	if (!hasNested && !hasRun && !hasScript && !hasHandoff && !hasTimeout && !hasEnv && !hasNonInteractive) return undefined;
+
+	if (hasNested && (hasRun || hasScript || hasHandoff || hasTimeout || hasEnv || hasNonInteractive)) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic-mixed-shorthand",
+				filePath,
+				source,
+				`Ignoring top-level deterministic shorthand in ${filePath}: use either "deterministic" or top-level run/script/handoff/timeout/env/nonInteractive, not both.`,
+			),
+		);
+	}
+
+	let record: Record<string, unknown>;
+	if (hasNested) {
+		const raw = frontmatter.deterministic;
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+			diagnostics.push(
+				createDiagnostic(
+					"invalid-deterministic",
+					filePath,
+					source,
+					`Ignoring invalid deterministic config in ${filePath}: frontmatter field "deterministic" must be an object.`,
+				),
+			);
+			return undefined;
+		}
+		record = raw as Record<string, unknown>;
+	} else {
+		record = {
+			run: frontmatter.run,
+			script: frontmatter.script,
+			handoff: frontmatter.handoff,
+			timeout: frontmatter.timeout,
+			env: frontmatter.env,
+			nonInteractive: frontmatter.nonInteractive,
+		};
+	}
+
+	const runValue = Object.hasOwn(record, "run") ? record.run : undefined;
+	const scriptValue = Object.hasOwn(record, "script") ? record.script : undefined;
+	if (runValue !== undefined && scriptValue !== undefined) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic",
+				filePath,
+				source,
+				`Ignoring deterministic config in ${filePath}: "run" and "script" cannot be declared together.`,
+			),
+		);
+		return undefined;
+	}
+
+	const execution = runValue !== undefined
+		? normalizeDeterministicRunValue(runValue, filePath, source, diagnostics)
+		: scriptValue !== undefined
+			? normalizeDeterministicScriptValue(scriptValue, filePath, source, diagnostics)
+			: undefined;
+	if (!execution) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-deterministic",
+				filePath,
+				source,
+				`Ignoring deterministic config in ${filePath}: expected either "run" or "script".`,
+			),
+		);
+		return undefined;
+	}
+
+	const handoff = normalizeDeterministicHandoff(record.handoff, filePath, source, diagnostics);
+	const timeoutMs = normalizeTimeoutMs(record.timeout, filePath, source, diagnostics);
+	const cwd = normalizeCwd(record.cwd, filePath, source, diagnostics);
+	const env = normalizeDeterministicEnv(record.env, filePath, source, diagnostics);
+	const nonInteractive = normalizeDeterministicNonInteractive(record.nonInteractive, filePath, source, diagnostics);
+	return {
+		execution,
+		handoff,
+		nonInteractive,
+		...(timeoutMs !== undefined ? { timeoutMs } : {}),
+		...(cwd ? { cwd } : {}),
+		...(env ? { env } : {}),
+	};
+}
+
 function normalizeLineupSlot(
 	value: unknown,
 	field: "workers" | "reviewers" | "finalApplier",
@@ -1033,6 +1424,7 @@ function loadPromptsWithModelFromDir(
 				const parallel = normalizeParallel(frontmatter.parallel, fullPath, source, diagnostics);
 				const hasBestOfN = Object.hasOwn(frontmatter, "bestOfN");
 				const bestOfN = normalizeBestOfN(frontmatter.bestOfN, fullPath, source, diagnostics);
+				let deterministic = normalizeDeterministic(frontmatter, fullPath, source, diagnostics);
 				const hasLegacyWorkers = Object.hasOwn(frontmatter, "workers");
 				const hasLegacyReviewers = Object.hasOwn(frontmatter, "reviewers");
 				const hasLegacyFinalApplier = Object.hasOwn(frontmatter, "finalApplier");
@@ -1073,6 +1465,17 @@ function loadPromptsWithModelFromDir(
 					);
 					subagent = undefined;
 				}
+				if (chain && deterministic !== undefined) {
+					diagnostics.push(
+						createDiagnostic(
+							"invalid-deterministic-chain",
+							fullPath,
+							source,
+							`Ignoring deterministic config in ${fullPath}: frontmatter field "deterministic" cannot be combined with "chain".`,
+						),
+					);
+					deterministic = undefined;
+				}
 				if (chain && (safeWorkers !== undefined || safeReviewers !== undefined || safeFinalApplier !== undefined)) {
 					diagnostics.push(
 						createDiagnostic(
@@ -1099,6 +1502,17 @@ function loadPromptsWithModelFromDir(
 					safeReviewers = undefined;
 					safeFinalApplier = undefined;
 				}
+				if (subagent !== undefined && deterministic !== undefined) {
+					diagnostics.push(
+						createDiagnostic(
+							"invalid-deterministic-subagent",
+							fullPath,
+							source,
+							`Ignoring deterministic config in ${fullPath}: frontmatter field "deterministic" cannot be combined with "subagent".`,
+						),
+					);
+					deterministic = undefined;
+				}
 				if (subagent === undefined && inheritContext) {
 					diagnostics.push(
 						createDiagnostic(
@@ -1145,6 +1559,17 @@ function loadPromptsWithModelFromDir(
 					safeReviewers = undefined;
 					safeFinalApplier = undefined;
 				}
+				if (safeParallel !== undefined && deterministic !== undefined) {
+					diagnostics.push(
+						createDiagnostic(
+							"invalid-deterministic-parallel",
+							fullPath,
+							source,
+							`Ignoring deterministic config in ${fullPath}: frontmatter field "deterministic" cannot be combined with "parallel".`,
+						),
+					);
+					deterministic = undefined;
+				}
 				const hasLineup = safeWorkers !== undefined || safeReviewers !== undefined || safeFinalApplier !== undefined;
 				if (!hasBestOfN && hasLegacyCompareFields) {
 					diagnostics.push(
@@ -1169,14 +1594,18 @@ function loadPromptsWithModelFromDir(
 					continue;
 				}
 				if (!chain && subagent === undefined && !hasLineup && cwd) {
-					diagnostics.push(
-						createDiagnostic(
-							"invalid-cwd",
-							fullPath,
-							source,
-							`Ignoring cwd in ${fullPath}: frontmatter field "cwd" requires "subagent", "chain", or compare lineups ("workers"/"reviewers"/"finalApplier").`,
-						),
-					);
+					if (deterministic) {
+						deterministic = { ...deterministic, ...(deterministic.cwd ? {} : { cwd }) };
+					} else {
+						diagnostics.push(
+							createDiagnostic(
+								"invalid-cwd",
+								fullPath,
+								source,
+								`Ignoring cwd in ${fullPath}: frontmatter field "cwd" requires "subagent", "chain", or compare lineups ("workers"/"reviewers"/"finalApplier").`,
+							),
+						);
+					}
 				}
 				const hasModelField = Object.hasOwn(frontmatter, "model");
 				const parsedModels = chain ? [] : normalizeModelSpecs(frontmatter.model, fullPath, source, diagnostics);
@@ -1214,6 +1643,17 @@ function loadPromptsWithModelFromDir(
 				const fresh = normalizeFresh(frontmatter.fresh, fullPath, source, diagnostics);
 				const loop = normalizeLoop(frontmatter.loop, fullPath, source, diagnostics);
 				const converge = normalizeConverge(frontmatter.converge, fullPath, source, diagnostics);
+				if (loop !== undefined && deterministic !== undefined) {
+					diagnostics.push(
+						createDiagnostic(
+							"invalid-deterministic-loop",
+							fullPath,
+							source,
+							`Ignoring deterministic config in ${fullPath}: frontmatter field "deterministic" cannot be combined with "loop" in v1.`,
+						),
+					);
+					deterministic = undefined;
+				}
 				const worktreeInput = hasBestOfN ? bestOfN?.worktree : frontmatter.worktree;
 				const worktree = normalizeWorktree(worktreeInput, fullPath, source, diagnostics);
 				let safeWorktree: boolean | undefined;
@@ -1256,6 +1696,7 @@ function loadPromptsWithModelFromDir(
 					loop !== undefined ||
 					converge === false ||
 					safeParallel !== undefined ||
+					deterministic !== undefined ||
 					hasLineup ||
 					safeWorktree === true ||
 					subagent !== undefined ||
@@ -1282,6 +1723,7 @@ function loadPromptsWithModelFromDir(
 					converge: converge === false ? false : undefined,
 					parallel: safeParallel,
 					worktree: safeWorktree,
+					deterministic,
 					subagent,
 					inheritContext: safeInheritContext || undefined,
 					cwd: safeCwd || undefined,
@@ -1381,6 +1823,7 @@ export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 	const loopLabel = prompt.loop !== undefined ? ` loop:${prompt.loop === null ? "unlimited" : prompt.loop}` : "";
 	const subagentLabel = prompt.subagent ? ` subagent:${prompt.subagent === true ? "delegate" : prompt.subagent}` : "";
 	const parallelLabel = prompt.parallel !== undefined ? ` parallel:${prompt.parallel}` : "";
+	const deterministicLabel = prompt.deterministic ? ` deterministic-step:${prompt.deterministic.handoff}` : "";
 	const workersLabel = prompt.workers ? ` workers:${effectiveLineupCount(prompt.workers)}` : "";
 	const reviewersLabel = prompt.reviewers ? ` reviewers:${effectiveLineupCount(prompt.reviewers)}` : "";
 	const finalApplierLabel = prompt.finalApplier ? " final-applier" : "";
@@ -1388,7 +1831,7 @@ export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 	const inheritContextLabel = prompt.inheritContext ? " fork" : "";
 	const worktreeLabel = prompt.worktree ? " worktree" : "";
 	const details =
-		`[${modelLabel}${rotateLabel}${thinkingLabel}${skillLabel}${loopLabel}${subagentLabel}${parallelLabel}${workersLabel}${reviewersLabel}${finalApplierLabel}${cwdLabel}${inheritContextLabel}${worktreeLabel}] ${sourceLabel}`;
+		`[${modelLabel}${rotateLabel}${thinkingLabel}${skillLabel}${loopLabel}${subagentLabel}${parallelLabel}${deterministicLabel}${workersLabel}${reviewersLabel}${finalApplierLabel}${cwdLabel}${inheritContextLabel}${worktreeLabel}] ${sourceLabel}`;
 	return prompt.description ? `${prompt.description} ${details}` : details;
 }