@promptbook/cli 0.114.0-42 → 0.114.0-47

package/esm/src/cli/cli-commands/coder/planning/runPlanningHarness.d.ts

@@ -0,0 +1,30 @@
+import type { Usage } from '../../../../execution/Usage';
+import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
+/**
+ * Parameters for one tool-restricted inference. Repository reads and PRD writes are host operations.
+ * @private internal type of `coder plan`
+ */
+export type PlanningHarnessOptions = NormalizedPromptRunnerSelectionCliOptions & {
+    readonly workspacePath: string;
+    readonly prompt: string;
+    readonly signal: AbortSignal;
+    /** Reports available usage from this inference once, including turns whose final answer is malformed. */
+    readonly onUsage?: (usage: Usage) => void;
+};
+/**
+ * Rejects harnesses without a planning execution policy before any Git sync or process launch.
+ * @private internal utility of `coder plan`
+ */
+export declare function assertPlanningHarnessSupported(harness: string | undefined): void;
+/**
+ * Constructs a fail-closed Codex invocation. User config, rules, project config discovery, native shell,
+ * connectors, hooks and delegation cannot expand the planning tool set. Read-only sandboxing also denies patches.
+ * Older Codex versions that do not support these switches fail instead of using the implementation runner.
+ * @private internal utility of `coder plan`
+ */
+export declare function buildPlanningHarnessArguments(options: PlanningHarnessOptions): string[];
+/**
+ * Runs a bounded inference with no shell interpolation and consumes only its final JSON answer.
+ * @private internal utility of `coder plan`
+ */
+export declare function runPlanningHarness(options: PlanningHarnessOptions): Promise<string>;

package/esm/src/cli/cli-commands/coder/planning/runPlanningHarness.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/coder/planning/runPlanningSession.d.ts

@@ -0,0 +1,21 @@
+import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
+import { runPlanningHarness } from './runPlanningHarness';
+/**
+ * Terminal interface also used by deterministic conversation fixtures.
+ * @private internal type of `coder plan`
+ */
+export type PlanningSessionIo = {
+    readonly readMessage: () => Promise<string | undefined>;
+    readonly write: (message: string) => void;
+    readonly signal: AbortSignal;
+};
+/**
+ * Runs one multi-topic planning conversation; only explicit save commands cross the PRD write boundary.
+ * @private internal utility of `coder plan`
+ */
+export declare function runPlanningSession(options: NormalizedPromptRunnerSelectionCliOptions & {
+    readonly projectPath: string;
+    readonly agent?: string;
+    readonly template?: string;
+    readonly preexistingChangedPaths?: ReadonlySet<string>;
+}, io: PlanningSessionIo, harness?: typeof runPlanningHarness): Promise<ReadonlyMap<string, string>>;

package/esm/src/cli/cli-commands/coder/planning/runPlanningSession.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/coder/planning/savePlanningChanges.d.ts

@@ -0,0 +1,7 @@
+import type { PlanningChange } from './preparePlanningChanges';
+/**
+ * Validates the entire batch before writing, stages outside the queue, then atomically replaces each file.
+ * The synchronous commit region cannot be interrupted by a SIGINT callback halfway through a save.
+ * @private internal execution boundary of `coder plan`
+ */
+export declare function savePlanningChanges(projectPath: string, workspacePath: string, changes: ReadonlyArray<PlanningChange>, isDraft: boolean): string[];

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

@@ -1,7 +1,8 @@
+import type { WorkspaceRepositoryContext } from '../common/workspaceRepository';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
 /**
  * Prints a readable summary of what was initialized for the user.
  *
  * @private function of `coder init` command
  */
-export declare function printInitializationSummary(summary: CoderInitializationSummary): void;
+export declare function printInitializationSummary(summary: CoderInitializationSummary, workspace?: WorkspaceRepositoryContext): void;

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

@@ -0,0 +1,13 @@
+/**
+ * Project-relative location of the offline guide, reserved from prompt discovery.
+ *
+ * @private internal constant of `coder init`
+ */
+export declare const PROMPTS_README_FILE_PATH: string;
+/**
+ * Maintained project-independent guide, bundled as text in the published CLI.
+ * Keep examples executable against the parser and command registry in the accompanying tests.
+ *
+ * @private internal template of `coder init`
+ */
+export declare const PROMPTS_README_TEMPLATE: string;

package/esm/src/cli/cli-commands/coder/promptsReadmeTemplate.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,8 @@
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+/**
+ * Reads a project-owned Book before initialization, refusing unsafe edits while preserving its original bytes.
+ * Unknown commitments remain supported, as in the normal Book parser.
+ *
+ * @private internal utility of `coder init`
+ */
+export declare function readCoderAgentBook(filePath: string): Promise<string_book>;

package/esm/src/cli/cli-commands/coder/workspacePreflight.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -6,6 +6,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * The coder command provides utilities for automated coding:
  * - init: Initialize coder configuration in current project
  * - add: Add one ready-to-run prompt file to the queue
+ * - plan: Discuss features with Planner and author reviewed PRDs
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
  * - list: List ready prompts in priority order without running them

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

@@ -19,6 +19,8 @@ export type LocalAgentBook = {
 export declare class LocalAgentBookCollection {
     private readonly agentDirectoryPath;
     private readonly currentWorkingDirectory;
+    private readonly isInitializationAllowed;
+    private readonly signal?;
     private readonly booksByUrl;
     private readonly booksByName;
     /** Stable default ancestor selected from the initial repository scan. */
@@ -26,7 +28,7 @@ export declare class LocalAgentBookCollection {
     /** Files initialized by this collection, for the coder's normal commit handling. */
     readonly createdAgentBookPaths: string[];
     /** Creates a collection rooted at the primary book's directory. */
-    constructor(agentDirectoryPath: string, currentWorkingDirectory: string);
+    constructor(agentDirectoryPath: string, currentWorkingDirectory: string, isInitializationAllowed?: boolean, signal?: AbortSignal | undefined);
     /** Discovers nested books, including the hidden `.core` directory. */
     initialize(): Promise<void>;
     /** Identifies the default ancestor without creating an unused book for FROM null/void. */
@@ -38,7 +40,7 @@ export declare class LocalAgentBookCollection {
     /** Reads a local book once, canonicalizing symlinks so aliases cannot bypass cycle detection. */
     readBook(filePath: string): Promise<LocalAgentBook>;
     /** Loads a referenced remote book, while keeping local identifiers entirely inside the collection. */
-    getBook(url: string): Promise<LocalAgentBook>;
+    getBook(url: string, signal?: AbortSignal | undefined): Promise<LocalAgentBook>;
     /** Adds a book under its normalized first-line name and preserves the display name for TEAM. */
     private registerBook;
     /** Walks real directories in deterministic order without following directory symlink loops. */

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

@@ -21,7 +21,7 @@ export declare const CODER_GIT_SYNC_DESCRIPTION: string;
  * Registers the shared `--commit`, `--auto-push` and `--auto-pull` flags on a `ptbk coder` command.
  *
  * Note: Unlike `ptbk coder run`, which commits by default and opts out through `--no-commit`,
- *       these commands never touch git unless the flags are used explicitly.
+ *       these commands only mutate Git when the flags are used explicitly. Workspace detection always runs.
  *
  * @private internal utility of `promptbookCli`
  */

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

@@ -6,8 +6,12 @@ import type { string_book } from '../../../book-2.0/agent-source/string_book';
  * @private internal type of CLI agent resolution
  */
 export type ResolvedLocalAgentSource = {
+    /** Canonical identity used to bound recursive TEAM consultations. */
+    readonly agentUrl: string;
     readonly agentSource: string_book;
     readonly agentReferenceResolver: AgentReferenceResolver;
+    /** Resolves another Book in this collection, retaining its own inheritance and reference locations. */
+    readonly resolveAgentSource: (url: string, signal?: AbortSignal) => Promise<ResolvedLocalAgentSource>;
     /** Newly created books which the coder may include in its initialization commit. */
     readonly createdAgentBookPaths: ReadonlyArray<string>;
 };
@@ -16,4 +20,7 @@ export type ResolvedLocalAgentSource = {
  *
  * @private internal utility of CLI agent resolution
  */
-export declare function resolveLocalAgentSource(agentBookPath: string, currentWorkingDirectory: string): Promise<ResolvedLocalAgentSource>;
+export declare function resolveLocalAgentSource(agentBookPath: string, currentWorkingDirectory: string, options?: {
+    readonly isInitializationAllowed?: boolean;
+    readonly signal?: AbortSignal;
+}): Promise<ResolvedLocalAgentSource>;

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

@@ -0,0 +1,6 @@
+import type { RunOptions } from '../../../../scripts/run-codex-prompts/cli/RunOptions';
+/**
+ * Validates cross-flag constraints before workspace setup or the run starts.
+ * @private shared validation for Coder execution commands
+ */
+export declare function validateCoderRunOptions(options: RunOptions): void;

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

@@ -0,0 +1,36 @@
+import type { NormalizedQuestionsCliOptions } from './questionsCliOptions';
+/**
+ * Resolved project directory and its enclosing working tree. Project artifacts belong to `projectPath`;
+ * Git paths and synchronization belong to `repositoryRoot`, which may be an enclosing monorepo.
+ *
+ * @private shared workspace context for Coder and workspace server commands
+ */
+export type WorkspaceRepositoryContext = {
+    readonly projectPath: string;
+    readonly repositoryRoot?: string;
+    readonly gitDirectory?: string;
+    readonly repositoryStatus: 'missing' | 'reused' | 'initialized';
+};
+/**
+ * Command policy is separate from discovery: previews never initialize; explicit init needs no confirmation.
+ *
+ * @private shared workspace policy for Coder and workspace server commands
+ */
+export type WorkspaceRepositoryPolicy = 'initialize' | 'mutate' | 'read-only';
+/**
+ * Resolves the requested project once and discovers Git using Git itself, without requiring `HEAD`.
+ * Broken metadata, bare repositories, ownership errors and unavailable Git are failures, not missing repositories.
+ *
+ * @private shared workspace discovery for CLI commands
+ */
+export declare function $resolveWorkspaceRepository(projectDirectory?: string): Promise<WorkspaceRepositoryContext>;
+/**
+ * Checks the shared prerequisite before any project writes, Git synchronization, installation or startup.
+ * Only an affirmative interactive answer or an explicit initializer authorizes `git init`.
+ *
+ * @private shared workspace preflight for Coder and workspace server commands
+ */
+export declare function $preflightWorkspaceRepository(options: {
+    readonly projectDirectory?: string;
+    readonly policy: WorkspaceRepositoryPolicy;
+} & Partial<NormalizedQuestionsCliOptions>): Promise<WorkspaceRepositoryContext>;

package/esm/src/cli/cli-commands/common/workspaceRepository.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+/**
+ * Shared explanation of the workspace prerequisite, independent of commit and synchronization settings.
+ * @private internal CLI help text
+ */
+export declare const WORKSPACE_REPOSITORY_DESCRIPTION: string;
+/**
+ * Adds shared Git help and the questions switch to every workspace command without duplicating existing options.
+ * @private internal registration helper for workspace CLI commands
+ */
+export declare function addWorkspaceRepositoryOptions(command: Command): void;

package/esm/src/commitments/TEAM/TEAM.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/conversion/archive/loadJsZipModule.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Loads the ZIP archive library (`jszip`) on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `loadArchive` and `saveArchive`
+ */
+export declare const loadJsZipModule: () => Promise<{
+    default: typeof import('jszip');
+}>;

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-40`).
+ * It follows semantic versioning (e.g., `0.114.0-47`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-42",
+    "version": "0.114.0-47",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -124,9 +124,11 @@
         "socket.io": "4.8.3",
         "socket.io-client": "4.8.3",
         "spacetrim": "0.11.60",
+        "string-width": "4.2.3",
         "swagger-ui-express": "5.0.1",
         "userhome": "1.0.1",
         "waitasecond": "1.11.164",
+        "zod": "4.3.6",
         "typescript": "5.2.2",
         "ts-node": "10.9.2",
         "next": "15.5.25",
@@ -181,8 +183,7 @@
         "y-protocols": "1.0.7",
         "y-websocket": "3.0.0",
         "yjs": "13.6.30",
-        "zeptomail": "7.0.2",
-        "zod": "4.3.6"
+        "zeptomail": "7.0.2"
     },
     "bin": {
         "promptbook": "bin/promptbook-cli.js",

package/src/book-2.0/agent-source/CreateAgentModelRequirementsOptions.ts

@@ -8,6 +8,8 @@ import type { TeammateProfileResolver } from './TeammateProfileResolver';
  * @public exported from `@promptbook/core`
  */
 export type CreateAgentModelRequirementsOptions = {
+    /** A host supplying its own scoped TEAM runtime only needs the tool definitions, not global executors. */
+    readonly isTeamToolRegistrationDisabled?: boolean;
     /**
      * Resolver that transforms compact agent references (FROM, IMPORT, TEAM) into concrete URLs.
      */

package/src/book-2.0/agent-source/createAgentModelRequirementsWithCommitments/applyCommitmentsToAgentModelRequirements.ts

@@ -157,9 +157,14 @@ async function preResolveTeammateProfilesForTeamCommitment(
                 continue;
             }
 
-            const profile = await profileResolver.resolveTeammateProfile(teammate.url);
-            if (profile) {
-                preResolvedTeammateProfiles[teammate.url] = profile;
+            try {
+                const profile = await profileResolver.resolveTeammateProfile(teammate.url);
+                if (profile) {
+                    preResolvedTeammateProfiles[teammate.url] = profile;
+                }
+            } catch (error) {
+                // One inaccessible adviser must not erase the names and roles of other callable teammates.
+                console.warn(`Failed to resolve TEAM profile for ${teammate.url}:`, error);
             }
         }
 

package/src/book-2.0/agent-source/createAgentModelRequirementsWithCommitments.ts

@@ -31,6 +31,12 @@ export async function createAgentModelRequirementsWithCommitments(
     const filteredCommitments = filterCommitmentsForAgentModelRequirements(parseResult.commitments);
 
     let requirements = createInitialAgentModelRequirements(parseResult.agentName, modelName);
+    if (options?.isTeamToolRegistrationDisabled) {
+        requirements = {
+            ...requirements,
+            _metadata: { ...requirements._metadata, isTeamToolRegistrationDisabled: true },
+        };
+    }
     requirements = await applyCommitmentsToAgentModelRequirements(requirements, filteredCommitments, options);
     requirements = await augmentAgentModelRequirementsFromSource(requirements, parseResult, agentSource);
     requirements = await materializeInlineKnowledgeSources(requirements, options?.inlineKnowledgeSourceUploader);

package/src/cli/$initializePromptbookCliProgram.ts

@@ -6,6 +6,7 @@ import { $initializeAgentCommand } from './cli-commands/agent';
 import { $initializeAgentFolderCommand } from './cli-commands/agent-folder';
 import { $initializeAgentsServerCommand } from './cli-commands/agents-server';
 import { $initializeCoderCommand } from './cli-commands/coder';
+import { $initializeCoderInitCommand } from './cli-commands/coder/init';
 import { $initializeHelloCommand } from './cli-commands/hello';
 import { $initializeListModelsCommand } from './cli-commands/list-models';
 import { $initializeListScrapersCommand } from './cli-commands/list-scrapers';
@@ -58,6 +59,7 @@ export function $initializePromptbookCliProgram(program: Command): void {
 
     // Commands are listed in registration order. Keep `coder` first and hide deprecated commands below.
     $initializeCoderCommand(program);
+    $initializeCoderInitCommand(program);
     $initializeAgentCommand(program);
     $initializeAgentFolderCommand(program);
     $initializeAgentsServerCommand(program);

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

@@ -16,6 +16,8 @@ import {
     CODER_GIT_SYNC_DESCRIPTION,
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import {
     addQuestionsOption,
@@ -99,6 +101,8 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
     addCoderGitSyncOptions(command);
     addQuestionsOption(command);
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (descriptionArgument: string | undefined, cliOptions) => {
             const { priority, template: templateOption } = cliOptions as {
@@ -108,7 +112,8 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
 
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
-            const projectPath = process.cwd();
+            const workspace = await $preflightWorkspaceRepository({ policy: 'mutate', ...questionsOptions });
+            const { projectPath } = workspace;
 
             const description = await resolveCoderPromptDescription(descriptionArgument, questionsOptions);
 
@@ -117,7 +122,7 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, workspace });
 
             const { /* filePath,*/ emojiTag } = await addCoderPrompt({
                 projectPath,
@@ -167,6 +172,34 @@ export async function addCoderPrompt({
     readonly priority: number;
     readonly templateOption?: string;
 }): Promise<AddCoderPromptResult> {
+    mkdirSync(join(projectPath, PROMPTS_DIRECTORY_PATH), { recursive: true });
+    const prepared = await prepareCoderPrompt({ projectPath, description, priority, templateOption });
+    writeFileSync(join(projectPath, prepared.filePath), prepared.content, { encoding: 'utf-8', flag: 'wx' });
+    console.info(colors.green(`✓ Added prompt ${prepared.emojiTag} in ${prepared.filePath}`));
+    return { filePath: prepared.filePath, emojiTag: prepared.emojiTag };
+}
+
+/**
+ * Prepares a numbered, emoji-tagged prompt for preview without writing the prompt file.
+ * The offset reserves consecutive identities when a planning turn proposes several files.
+ *
+ * @private internal utility shared by `coder add` and `coder plan`
+ */
+export async function prepareCoderPrompt({
+    projectPath,
+    description,
+    priority,
+    templateOption,
+    numberOffset = 0,
+    reservedEmojiTag,
+}: {
+    readonly projectPath: string;
+    readonly description: string;
+    readonly priority: number;
+    readonly templateOption?: string;
+    readonly numberOffset?: number;
+    readonly reservedEmojiTag?: string;
+}): Promise<AddCoderPromptResult & { readonly content: string }> {
     const normalizedDescription = description.trim();
     if (normalizedDescription === '') {
         throw new ParseError(
@@ -188,7 +221,6 @@ export async function addCoderPrompt({
     );
 
     const promptsDirectory = join(projectPath, PROMPTS_DIRECTORY_PATH);
-    mkdirSync(promptsDirectory, { recursive: true });
 
     const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
 
@@ -198,9 +230,9 @@ export async function addCoderPrompt({
         ignoreGlobs: ['**/node_modules/**'],
     });
 
-    const { selectedEmojis } = await getFreshPromptEmojiTags({ count: 1, rootDir: projectPath });
-    const emoji = selectedEmojis[0]!;
-    const emojiTag = formatPromptEmojiTag(emoji);
+    const emojiTag =
+        reservedEmojiTag ||
+        formatPromptEmojiTag((await getFreshPromptEmojiTags({ count: 1, rootDir: projectPath })).selectedEmojis[0]!);
 
     const [firstDescriptionLine, ...remainingDescriptionLines] = normalizedDescription.split('\n');
     const title = (firstDescriptionLine ?? '').trim();
@@ -216,15 +248,13 @@ export async function addCoderPrompt({
     });
 
     const slug = buildAddPromptSlug(promptTemplate.slugPrefix, title);
-    const filename = buildPromptFilename(promptNumbering.datePrefix, promptNumbering.startNumber, slug);
+    const filename = buildPromptFilename(
+        promptNumbering.datePrefix,
+        promptNumbering.startNumber + numberOffset * promptNumbering.step,
+        slug,
+    );
     const filePath = join(PROMPTS_DIRECTORY_PATH, filename);
-    const absoluteFilePath = join(projectPath, filePath);
-
-    writeFileSync(absoluteFilePath, `${section}\n`, 'utf-8');
-
-    console.info(colors.green(`✓ Added prompt ${emojiTag} in ${filePath}`));
-
-    return { filePath, emojiTag };
+    return { filePath, emojiTag, content: `${section}\n` };
 }
 
 /**

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

@@ -1,6 +1,7 @@
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
+import { CODER_DEFAULT_AGENT_BOOK_PATHS, type CoderAgentRole } from './coderAgentRole';
 
 /**
  * Commander option bag for an optional Book agent used by coder commands.
@@ -17,15 +18,20 @@ export type CoderAgentCliOptions = {
  * @private internal utility of `ptbk coder`
  */
 export const CODER_AGENT_OPTION_DESCRIPTION =
-    'Path to a .book file used to personalize coding prompts and select agent-specific tasks';
+    'Book agent providing persona, instructions, identity and task routing; --harness selects the coding tool and --model selects its model';
 
 /**
  * Registers the shared `--agent` option for coder commands.
  *
  * @private internal utility of `ptbk coder`
  */
-export function addCoderAgentOption(command: Program): void {
-    command.option('--agent <agent-book-path>', CODER_AGENT_OPTION_DESCRIPTION);
+export function addCoderAgentOption(command: Program, defaultRole?: CoderAgentRole): void {
+    const defaultDescription = defaultRole
+        ? `Defaults to the project's ${defaultRole === 'developer' ? 'Developer' : 'Planner'} (${
+              CODER_DEFAULT_AGENT_BOOK_PATHS[defaultRole]
+          }); --agent overrides this Book`
+        : 'No default Book filter; omitting --agent includes tasks for all agents';
+    command.option('--agent <agent-book-path>', `${CODER_AGENT_OPTION_DESCRIPTION}. ${defaultDescription}`);
 }
 
 // Note: [🟡] Code for CLI coder agent options should never be published outside of `@promptbook/cli`