@promptbook/cli 0.114.0-19 → 0.114.0-20

package/esm/scripts/run-codex-prompts/common/CoderRunControlFeedback.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Terminal control key of `ptbk coder run` which the user can press during a run.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlKey = 'P' | 'S' | 'X';
+/**
+ * Meaning of one control answer, which decides how it is colored in the terminal.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedbackTone = 'success' | 'info' | 'warning';
+/**
+ * Answer of the runner to one pressed control key.
+ *
+ * Every single key press produces one of these, including presses which change nothing, so the user
+ * always sees that the key was received.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedback = {
+    /**
+     * Control key the answer belongs to.
+     */
+    readonly controlKey: CoderRunControlKey;
+    /**
+     * Human-readable description of what the key press did.
+     */
+    readonly message: string;
+    /**
+     * Meaning of the answer, used to color it.
+     */
+    readonly tone: CoderRunControlFeedbackTone;
+};
+/**
+ * One control answer together with how many times the very same answer was repeated in a row.
+ *
+ * Pressing one control twice can produce the identical answer, so the repeat count is what makes the
+ * second press change the rendered frame as well.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedbackNotice = CoderRunControlFeedback & {
+    /**
+     * How many times this exact answer was given in a row, starting at `1`.
+     */
+    readonly repeatCount: number;
+};
+/**
+ * How long one control answer stays visible in the rich terminal UI.
+ *
+ * @private internal constant of `ptbk coder` terminal controls
+ */
+export declare const CODER_RUN_CONTROL_FEEDBACK_DURATION_MS = 5000;

package/esm/scripts/run-codex-prompts/common/applyCoderRunControlKey.d.ts

@@ -0,0 +1,14 @@
+import type { CoderRunControlFeedback } from './CoderRunControlFeedback';
+/**
+ * Applies the terminal control bound to one pressed key and describes what that key press did.
+ *
+ * This is the single place where the `P`, `S` and `X` keys are turned into runner actions, so the
+ * plain console listener and the rich terminal UI always perform the same action and always answer
+ * the user, even when the pressed control changed nothing.
+ *
+ * @param keyName Name of the pressed key as reported by the `keypress` event.
+ * @returns The answer shown to the user, or `undefined` when the key is not a control key.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function applyCoderRunControlKey(keyName: string | undefined): CoderRunControlFeedback | undefined;

package/esm/scripts/run-codex-prompts/common/buildCoderRunControlKeyBadge.d.ts

@@ -0,0 +1,7 @@
+import type { CoderRunControlKey } from './CoderRunControlFeedback';
+/**
+ * Builds the colored badge of one control key, for example ` S `.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function buildCoderRunControlKeyBadge(controlKey: CoderRunControlKey): string;

package/esm/scripts/run-codex-prompts/common/formatCoderRunControlFeedback.d.ts

@@ -0,0 +1,13 @@
+import type { CoderRunControlFeedback } from './CoderRunControlFeedback';
+/**
+ * Formats one control answer as a single colored terminal line.
+ *
+ * The same line is printed by the plain console listener and rendered inside the `Controls` box of the
+ * rich terminal UI, so both modes answer a pressed control key identically.
+ *
+ * @param feedback Answer of the runner to the pressed control key.
+ * @param repeatCount How many times this exact answer was given in a row, rendered from the second time on.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function formatCoderRunControlFeedback(feedback: CoderRunControlFeedback, repeatCount?: number): string;

package/esm/scripts/run-codex-prompts/common/listenForCoderRunControls.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Listens for the terminal control keys while the plain console output is used.
+ *
+ * Every recognized key press is answered with one printed line, because the plain mode has no frame
+ * which could show the new state on its own. The rich terminal UI installs its own listener in
+ * [`renderCoderRunUi`](../ui/renderCoderRunUi.ts) and shares the very same key handling through
+ * [`applyCoderRunControlKey`](./applyCoderRunControlKey.ts).
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function listenForCoderRunControls(): void;
+/**
+ * Backwards-compatible alias for the shared terminal controls listener.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function listenForPause(): void;

package/esm/scripts/run-codex-prompts/common/waitForPause.d.ts

@@ -54,14 +54,6 @@ export declare function waitForSkippableMilliseconds(waitToken: CoderRunSkippabl
  * Restores all shared terminal controls to their default state.
  */
 export declare function resetCoderRunControls(): void;
-/**
- * Listens for the terminal control keys.
- */
-export declare function listenForCoderRunControls(): void;
-/**
- * Backwards-compatible alias for the shared terminal controls listener.
- */
-export declare function listenForPause(): void;
 /**
  * If the execution is paused, it will wait until it is resumed.
  *

package/esm/scripts/run-codex-prompts/common/waitForSkippableWorldTimeDeadline.d.ts

@@ -0,0 +1,15 @@
+import { type WorldTimeDeadlineTick } from './waitUntilWorldTimeDeadline';
+/**
+ * Waits until one wall-clock deadline has passed, or until the user skips the wait with the `S` control.
+ *
+ * This is the single way `ptbk coder` waits for a deadline the user is allowed to cut short, so every
+ * wait which shows the `S  Skip current waiting` control really reacts to it: the pacing waits between
+ * prompts, the cool-down after an error, the harness session-limit waits and the server keep-alive poll.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function waitForSkippableWorldTimeDeadline(options: {
+    readonly deadlineTimeMs: number;
+    readonly pollIntervalMs: number;
+    readonly onTick?: WorldTimeDeadlineTick;
+}): Promise<void>;

package/esm/scripts/run-codex-prompts/prompts/buildPromptLabel.d.ts

@@ -0,0 +1,6 @@
+import type { PromptFile } from './types/PromptFile';
+import type { PromptSection } from './types/PromptSection';
+/**
+ * Builds a label that identifies the prompt section by index.
+ */
+export declare function buildPromptLabel(file: PromptFile, section: PromptSection): string;

package/esm/scripts/run-codex-prompts/prompts/buildPromptStatusDetails.d.ts

@@ -21,6 +21,13 @@ export type BuildPromptStatusDetailsOptions = {
      * Model the harness runs the prompt with.
      */
     readonly modelName: string | undefined;
+    /**
+     * Harness which left the prompt in the middle of its implementation, when another harness took the work over.
+     *
+     * Present only for a prompt resumed through `--git-changes continue`, so a status line always names both the
+     * harness which started the work and the one which is finishing it.
+     */
+    readonly startedByRunnerSignature?: string;
     /**
      * How many coding attempts the prompt has taken so far.
      */

package/esm/scripts/run-codex-prompts/prompts/listPromptsByStatus.d.ts

@@ -0,0 +1,7 @@
+import type { PromptFile } from './types/PromptFile';
+import type { PromptSelection } from './types/PromptSelection';
+import type { PromptStatus } from './types/PromptStatus';
+/**
+ * Lists prompts in one checklist status across all files.
+ */
+export declare function listPromptsByStatus(files: PromptFile[], status: PromptStatus): PromptSelection[];

package/esm/scripts/run-codex-prompts/prompts/markPromptDone.d.ts

@@ -1,9 +1,20 @@
-import type { CodexLoginMethod } from '../../../src/book-3.0/codexLoginMethod';
-import type { ThinkingLevel } from '../../../src/cli/cli-commands/coder/ThinkingLevel';
-import type { CoderRunStep } from '../common/CoderRunStep';
+import { type BuildPromptStatusDetailsOptions } from './buildPromptStatusDetails';
 import type { PromptFile } from './types/PromptFile';
 import type { PromptSection } from './types/PromptSection';
+/**
+ * Input for marking one prompt section as implemented, verified and committed.
+ */
+export type MarkPromptDoneOptions = BuildPromptStatusDetailsOptions & {
+    /**
+     * Prompt file the marked section belongs to.
+     */
+    readonly file: PromptFile;
+    /**
+     * Section which has just been finished.
+     */
+    readonly section: PromptSection;
+};
 /**
  * Marks a prompt section as done and records the per-step usage pricing and runner details.
  */
-export declare function markPromptDone(file: PromptFile, section: PromptSection, steps: ReadonlyArray<CoderRunStep>, runnerName: string | undefined, modelName: string | undefined, attemptCount?: number, loginMethod?: CodexLoginMethod, thinkingLevel?: ThinkingLevel): void;
+export declare function markPromptDone(options: MarkPromptDoneOptions): void;

package/esm/scripts/run-codex-prompts/prompts/markPromptFailed.d.ts

@@ -1,7 +1,40 @@
 import moment from 'moment';
 import type { PromptFile } from './types/PromptFile';
 import type { PromptSection } from './types/PromptSection';
+/**
+ * Input for marking one prompt section as failed.
+ */
+export type MarkPromptFailedOptions = {
+    /**
+     * Prompt file the marked section belongs to.
+     */
+    readonly file: PromptFile;
+    /**
+     * Section which could not be implemented.
+     */
+    readonly section: PromptSection;
+    /**
+     * Harness which ran the prompt.
+     */
+    readonly runnerName: string | undefined;
+    /**
+     * Model the harness ran the prompt with.
+     */
+    readonly modelName: string | undefined;
+    /**
+     * Harness which left the prompt in the middle of its implementation, when another harness took the work over.
+     */
+    readonly startedByRunnerSignature?: string;
+    /**
+     * Moment the failed prompt round started, used to report how long the attempt took.
+     */
+    readonly promptExecutionStartedDate: moment.Moment;
+    /**
+     * How many coding attempts the prompt has taken before it was given up on.
+     */
+    readonly attemptCount: number;
+};
 /**
  * Marks a prompt section as failed and records runner details.
  */
-export declare function markPromptFailed(file: PromptFile, section: PromptSection, runnerName: string | undefined, modelName: string | undefined, promptExecutionStartedDate: moment.Moment, attemptCount?: number): void;
+export declare function markPromptFailed(options: MarkPromptFailedOptions): void;

package/esm/scripts/run-codex-prompts/prompts/promptRunnerAttribution.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Formats who worked on one prompt for its status line.
+ *
+ * Produces `` by Claude Code `claude-opus-5` `` for a prompt implemented by a single harness and
+ * `` by Claude Code `claude-opus-5`, started by OpenAI Codex `gpt-5.6-luna` `` for a prompt which one
+ * harness started and another one continued through `--git-changes continue`.
+ */
+export declare function formatPromptRunnerAttribution(options: {
+    /**
+     * Harness which runs the prompt right now, already formatted as a runner signature.
+     */
+    readonly currentRunnerSignature: string;
+    /**
+     * Harness which left the prompt in the middle of its implementation, when the work was taken over.
+     */
+    readonly startedByRunnerSignature?: string;
+}): string;
+/**
+ * Reads which harness started the work recorded on one prompt status line.
+ *
+ * A line written by a single harness names that harness, and a line of a prompt which was already taken
+ * over keeps naming the harness which started it, so the original author survives any number of takeovers.
+ */
+export declare function parsePromptStartedByRunnerSignature(statusLine: string): string | undefined;

package/esm/scripts/run-codex-prompts/prompts/resolveInterruptedPrompt.d.ts

@@ -0,0 +1,9 @@
+import type { PromptFile } from './types/PromptFile';
+import type { PromptSelection } from './types/PromptSelection';
+/**
+ * Resolves the one prompt which `--git-changes continue` resumes.
+ *
+ * A coder which was killed or crashed leaves exactly one prompt behind in the in-progress `[^]` status,
+ * so anything else means the working tree changes cannot be attributed to a single interrupted prompt.
+ */
+export declare function resolveInterruptedPrompt(files: PromptFile[]): PromptSelection;

package/esm/scripts/run-codex-prompts/ui/CoderRunUiState.d.ts

@@ -2,6 +2,7 @@
 import { EventEmitter } from 'events';
 import moment from 'moment';
 import { type CoderRunProgressSnapshot } from '../common/buildCoderRunProgressSnapshot';
+import type { CoderRunControlFeedback, CoderRunControlFeedbackNotice } from '../common/CoderRunControlFeedback';
 import type { PriorityFilter } from '../prompts/priorityFilter';
 import type { PromptStats } from '../prompts/types/PromptStats';
 import type { CoderRunAgentVisual } from './buildCoderRunAgentVisual';
@@ -59,6 +60,7 @@ export declare class CoderRunUiState extends EventEmitter {
     phase: CoderRunPhase;
     statusMessage: string;
     errors: string[];
+    controlFeedback: CoderRunControlFeedbackNotice | undefined;
     private stats;
     private readonly timer;
     private initialDone;
@@ -77,7 +79,7 @@ export declare class CoderRunUiState extends EventEmitter {
      */
     setConfig(config: CoderRunConfig): void;
     /**
-     * Replaces the ASCII-art agent visual renderer shown instead of the default brand banner.
+     * Replaces the ASCII-art agent visual renderer shown above the dashboard boxes.
      */
     setAgentVisual(agentVisual: CoderRunAgentVisual | undefined): void;
     /**
@@ -146,9 +148,21 @@ export declare class CoderRunUiState extends EventEmitter {
      * Sets or clears the Enter-key action label shown in the controls panel.
      */
     setPendingEnterLabel(pendingEnterLabel: string | undefined): void;
+    /**
+     * Shows the answer of the runner to one pressed control key, or clears the currently shown one.
+     *
+     * Pressing one control twice in a row can produce the very same answer, for example when there is
+     * nothing to skip. The repeat count is therefore tracked here, so that even such a press changes the
+     * rendered frame and the user always sees that the key arrived.
+     */
+    setControlFeedback(controlFeedback: CoderRunControlFeedback | undefined): void;
     /**
      * Appends an error message to the error list shown in the UI.
      */
     addError(errorMessage: string): void;
+    /**
+     * Counts how many times the shown answer repeats the previously shown one.
+     */
+    private countControlFeedbackRepeat;
     private emitChange;
 }

package/esm/scripts/run-codex-prompts/ui/buildCoderRunAgentVisual.d.ts

@@ -33,7 +33,7 @@ export type CoderRunAgentVisual = TerminalAgentAvatarVisual;
  * visuals are rendered through the shared canvas avatar pipeline into terminal ASCII art, using a
  * transparent horizontal canvas instead of the website's framed 1:1 surface.
  *
- * The visual is decorative, so any failure returns `null` and the caller keeps the default brand banner.
+ * The visual is decorative, so any failure returns `null` and the caller renders no header visual at all.
  *
  * @param agentSource Source of the `--agent` book file.
  * @returns ANSI-colored ASCII-art renderer or `null` when the visual cannot be rendered.

package/esm/scripts/run-codex-prompts/ui/buildCoderRunUiFrame.d.ts

@@ -1,3 +1,4 @@
+import type { CoderRunControlFeedbackNotice } from '../common/CoderRunControlFeedback';
 import type { CoderRunPauseState } from '../common/waitForPause';
 import type { CoderRunConfig, CoderRunPhase, CoderRunProgressSnapshot } from './CoderRunUiState';
 import type { CoderRunAgentVisual } from './buildCoderRunAgentVisual';
@@ -14,7 +15,7 @@ export type BuildCoderRunUiFrameOptions = {
     readonly animationTimeMs: number;
     readonly spinner: string;
     /**
-     * ANSI ASCII-art renderer of the `--agent` avatar visual shown instead of the default brand banner.
+     * ANSI ASCII-art renderer of the `--agent` avatar visual shown above the dashboard boxes.
      */
     readonly agentVisual?: CoderRunAgentVisual;
     /**
@@ -40,6 +41,10 @@ export type BuildCoderRunUiFrameOptions = {
     readonly agentOutputLines: readonly string[];
     readonly errors: readonly string[];
     readonly progress: CoderRunProgressSnapshot;
+    /**
+     * Answer of the runner to the control key which was pressed last, shown in the `Controls` box.
+     */
+    readonly controlFeedback?: CoderRunControlFeedbackNotice;
 };
 /**
  * Structured row rendered in the agent-run `Agents` table.

package/esm/scripts/run-codex-prompts/ui/buildRunUiFrameShared.d.ts

@@ -1,3 +1,4 @@
+import type { CoderRunControlFeedbackNotice } from '../common/CoderRunControlFeedback';
 import type { CoderRunPauseState } from '../common/waitForPause';
 import type { CoderRunPhase } from './CoderRunUiState';
 /**
@@ -73,3 +74,13 @@ export declare function buildCoderRunControlPills(options: {
     readonly isEndAfterCurrentPromptRequested: boolean;
     readonly sessionTotal: number;
 }): readonly string[];
+/**
+ * Builds the body of the `Controls` box.
+ *
+ * The pills are always shown, and right after a control key was pressed the answer of the runner to
+ * that key is shown underneath, so no key press ever leaves the frame unchanged.
+ */
+export declare function buildControlsBoxLines(options: {
+    readonly controlPills: readonly string[];
+    readonly controlFeedback: CoderRunControlFeedbackNotice | undefined;
+}): readonly string[];

package/esm/src/cli/cli-commands/coder/GitChangesMode.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Supported values of the `--git-changes` option, which decides what happens with a dirty working tree.
+ *
+ * - `fail` — refuse to start while the working tree has uncommitted changes
+ * - `ignore` — start anyway and leave the uncommitted changes where they are
+ * - `continue` — resume the single prompt which was left in the middle of its implementation
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const GIT_CHANGES_MODE_VALUES: readonly ["fail", "ignore", "continue"];
+/**
+ * Behavior requested for a working tree which has uncommitted changes.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export type GitChangesMode = (typeof GIT_CHANGES_MODE_VALUES)[number];
+/**
+ * Mode applied when `--git-changes` is not used at all.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const DEFAULT_GIT_CHANGES_MODE: GitChangesMode;
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare function isGitChangesMode(value: string): value is GitChangesMode;

package/esm/src/cli/cli-commands/common/promptRunnerCliOptions.d.ts

@@ -1,5 +1,6 @@
 import { Command as Program } from 'commander';
 import { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from '../../../book-3.0/cliAgentEnv';
+import type { GitChangesMode } from '../coder/GitChangesMode';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 /**
@@ -25,7 +26,7 @@ export type PromptRunnerCliOptions = {
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly commit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -48,7 +49,7 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly noCommit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -78,6 +79,12 @@ export declare const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = "Select runner:
  * @private internal utility of `promptbookCli`
  */
 export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
+/**
+ * Commander description for the `--git-changes` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const GIT_CHANGES_OPTION_DESCRIPTION: string;
 /**
  * Registers runner selection flags on a command.
  *

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-18`).
+ * It follows semantic versioning (e.g., `0.114.0-19`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-19",
+    "version": "0.114.0-20",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/cli/cli-commands/agents-server/startAgentsServer/createLocalAgentRunOptions.ts

@@ -17,7 +17,7 @@ export function createLocalAgentRunOptions(
         noUi: options.noUi,
         thinkingLevel: options.thinkingLevel,
         noCommit: true,
-        ignoreGitChanges: true,
+        gitChanges: 'ignore',
         normalizeLineEndings: false,
         allowCredits: options.allowCredits,
         autoPush: false,

package/src/cli/cli-commands/coder/GitChangesMode.ts

@@ -0,0 +1,35 @@
+/**
+ * Supported values of the `--git-changes` option, which decides what happens with a dirty working tree.
+ *
+ * - `fail` — refuse to start while the working tree has uncommitted changes
+ * - `ignore` — start anyway and leave the uncommitted changes where they are
+ * - `continue` — resume the single prompt which was left in the middle of its implementation
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export const GIT_CHANGES_MODE_VALUES = ['fail', 'ignore', 'continue'] as const;
+
+/**
+ * Behavior requested for a working tree which has uncommitted changes.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export type GitChangesMode = (typeof GIT_CHANGES_MODE_VALUES)[number];
+
+/**
+ * Mode applied when `--git-changes` is not used at all.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export const DEFAULT_GIT_CHANGES_MODE: GitChangesMode = 'fail';
+
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export function isGitChangesMode(value: string): value is GitChangesMode {
+    return GIT_CHANGES_MODE_VALUES.includes(value as GitChangesMode);
+}
+
+// Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/coder/run.ts

@@ -48,6 +48,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
             - Commits only the prompt file and the files the coding agent has changed, leaving unrelated changes alone
+            - Refuses to start on a dirty working tree unless --git-changes says what should happen with the changes
+            - Optional --git-changes continue resumes the single prompt an interrupted coder left in the [^] status
             - Optional post-commit git push with explicit --auto-push opt-in
             - Optional pre-prompt git pull with explicit --auto-pull opt-in
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
@@ -234,7 +236,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

package/src/cli/cli-commands/coder/server.ts

@@ -199,7 +199,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

package/src/cli/cli-commands/common/promptRunnerCliOptions.ts

@@ -10,6 +10,8 @@ import {
     PTBK_MODEL_ENV,
     PTBK_THINKING_LEVEL_ENV,
 } from '../../../book-3.0/cliAgentEnv';
+import type { GitChangesMode } from '../coder/GitChangesMode';
+import { DEFAULT_GIT_CHANGES_MODE, GIT_CHANGES_MODE_VALUES } from '../coder/GitChangesMode';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
 
@@ -40,7 +42,7 @@ export type PromptRunnerCliOptions = {
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly commit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -68,7 +70,7 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly noCommit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -120,6 +122,18 @@ export const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim(`
     Gemini examples: gemini-3-flash-preview, default
 `);
 
+/**
+ * Commander description for the `--git-changes` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const GIT_CHANGES_OPTION_DESCRIPTION = spaceTrim(`
+    Decide what happens when the working tree has uncommitted changes before a prompt starts:
+    - fail: refuse to start and ask for a commit or a stash (the default)
+    - ignore: start anyway and leave the uncommitted changes where they are
+    - continue: resume the single prompt which was left in the middle of its implementation
+`);
+
 /**
  * Registers runner selection flags on a command.
  *
@@ -165,7 +179,11 @@ export function addPromptRunnerRuntimeOptions(command: Program): void {
 export function addPromptRunnerExecutionOptions(command: Program): void {
     addPromptRunnerRuntimeOptions(command);
     command.option('--no-commit', 'Leave successful changes in the working directory instead of creating git commits');
-    command.option('--ignore-git-changes', 'Skip clean working tree check before running prompts', false);
+    command.addOption(
+        new Option('--git-changes <mode>', GIT_CHANGES_OPTION_DESCRIPTION)
+            .choices([...GIT_CHANGES_MODE_VALUES])
+            .default(DEFAULT_GIT_CHANGES_MODE),
+    );
     command.option(
         '--no-normalize-line-endings',
         'Disable automatic LF normalization for files changed in each coding round',
@@ -190,7 +208,7 @@ export function normalizePromptRunnerCliOptions(
     return {
         ...selectionOptions,
         noCommit: !cliOptions.commit,
-        ignoreGitChanges: cliOptions.ignoreGitChanges,
+        gitChanges: cliOptions.gitChanges ?? DEFAULT_GIT_CHANGES_MODE,
         normalizeLineEndings: cliOptions.normalizeLineEndings,
         autoPush: cliOptions.autoPush,
         autoPull: cliOptions.autoPull,