@hyperdrive.bot/bmad-workflow 1.0.25 → 1.0.27

package/dist/commands/workflow.js

@@ -1,6 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { execSync } from 'node:child_process';
-import { basename } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { parseDuration } from '../utils/duration.js';
 import { AssetResolver } from '../services/file-system/asset-resolver.js';
 import { mergeExecutionConfig } from '../utils/config-merge.js';
@@ -8,7 +9,12 @@ import { createAgentRunner, isProviderSupported } from '../services/agents/agent
 import { getRegisteredScannerNames } from '../services/review/scanner-factory.js';
 import { Severity } from '../services/review/types.js';
 import { FileManager } from '../services/file-system/file-manager.js';
+import { GlobMatcher } from '../services/file-system/glob-matcher.js';
 import { PathResolver } from '../services/file-system/path-resolver.js';
+import { GitOps } from '../services/git/git-ops.js';
+import { PushConflictHandler } from '../services/git/push-conflict-handler.js';
+import { GitBackedLockService } from '../services/lock/git-backed-lock-service.js';
+import { LockService } from '../services/lock/lock-service.js';
 import { BatchProcessor } from '../services/orchestration/batch-processor.js';
 import { InputDetector } from '../services/orchestration/input-detector.js';
 import { StoryTypeDetector } from '../services/orchestration/story-type-detector.js';
@@ -102,6 +108,11 @@ export default class Workflow extends Command {
         model: Flags.string({
             description: 'Model to use for AI provider. Format varies by provider: Claude (claude-opus-4-5-20251101), Gemini (gemini-2.5-pro), OpenCode (anthropic/claude-3-5-sonnet)',
         }),
+        'session-name': Flags.string({
+            char: 'n',
+            description: 'Session display name template. Supports {prefix}, {phase}, {story} placeholders. ' +
+                'Auto-generated from input filename if not provided.',
+        }),
         prefix: Flags.string({
             default: '',
             description: 'Filename prefix for generated files and session directory name',
@@ -170,6 +181,10 @@ export default class Workflow extends Command {
             default: false,
             description: 'Skip epic creation phase',
         }),
+        'skip-locking': Flags.boolean({
+            default: false,
+            description: 'Disable story locking (for single-agent runs)',
+        }),
         'skip-stories': Flags.boolean({
             default: false,
             description: 'Skip story creation phase',
@@ -197,6 +212,16 @@ export default class Workflow extends Command {
             default: 5000,
             description: 'Backoff delay between retries in milliseconds',
         }),
+        'use-channels': Flags.boolean({
+            default: false,
+            description: 'Use Channel transport for agent communication (requires pre-started Channel agents)',
+            helpGroup: 'Channel Transport',
+        }),
+        stream: Flags.boolean({
+            default: false,
+            description: 'Stream full Claude output to stdout in real-time (verbose passthrough of everything Claude does)',
+            helpGroup: 'Output',
+        }),
         verbose: Flags.boolean({
             char: 'v',
             default: false,
@@ -234,6 +259,8 @@ export default class Workflow extends Command {
                     this.error('--cwd and --worktree are mutually exclusive. --worktree sets cwd automatically.', { exit: 1 });
                 }
                 const entities = flags['gut-entities'].split(',').map((e) => e.trim()).filter(Boolean);
+                // Preflight: validate gut entities exist before attempting worktree creation
+                this.validateGutEntities(entities);
                 const branchSlug = `workflow/${basename(inputPath, '.md').replace(/^PRD-/, '').toLowerCase()}-${Date.now()}`;
                 const installFlag = flags['worktree-install'] ? '--install' : '';
                 this.log(colors.info(`Creating isolated worktree: ${branchSlug}`));
@@ -296,8 +323,8 @@ export default class Workflow extends Command {
             if (!isProviderSupported(merged.provider)) {
                 this.error(`Unsupported provider: ${merged.provider}. Use 'claude', 'gemini', or 'opencode'.`, { exit: 1 });
             }
-            // Initialize services with parallel concurrency and provider
-            await this.initializeServices(merged.parallel, merged.provider, flags.verbose);
+            // Initialize services with parallel concurrency, provider, and locking
+            await this.initializeServices(merged.parallel, merged.provider, flags.verbose, !flags['skip-locking']);
             // Register signal handlers
             this.registerSignalHandlers();
             // Initialize session scaffolder and create session structure
@@ -343,6 +370,7 @@ export default class Workflow extends Command {
                 dryRun: flags['dry-run'],
                 epicInterval: merged.epicInterval,
                 input: args.input,
+                lockingEnabled: !flags['skip-locking'],
                 maxRetries: merged.maxRetries,
                 mcp: flags.mcp || undefined,
                 mcpPhases: flags['mcp-phases'] ? flags['mcp-phases'].split(',').map((s) => s.trim()) : undefined,
@@ -369,6 +397,10 @@ export default class Workflow extends Command {
                 skipStories: flags['skip-stories'],
                 storyInterval: merged.storyInterval,
                 timeout: merged.timeout,
+                sessionName: flags['session-name'],
+                inputPath: args.input,
+                stream: flags.stream,
+                useChannels: flags['use-channels'],
                 verbose: flags.verbose,
             };
             // Validate --mcp-phases when --mcp is enabled
@@ -898,7 +930,7 @@ export default class Workflow extends Command {
      * @param verbose - Enable verbose output mode
      * @private
      */
-    async initializeServices(maxConcurrency = 3, provider = 'claude', verbose = false) {
+    async initializeServices(maxConcurrency = 3, provider = 'claude', verbose = false, lockingEnabled = false) {
         // Create logger — suppress INFO logs in non-verbose mode to keep terminal clean
         this.logger = createLogger({ level: verbose ? 'info' : 'warn', namespace: 'commands:workflow' });
         this.logger.info({ provider }, 'Initializing services with AI provider');
@@ -923,6 +955,16 @@ export default class Workflow extends Command {
             nonTTY: !process.stdout.isTTY,
             verbose,
         });
+        // Conditionally instantiate lock service for multi-session coordination
+        let lockService;
+        if (lockingEnabled) {
+            const globMatcher = new GlobMatcher(fileManager, this.logger);
+            const gitOps = new GitOps();
+            const conflictHandler = new PushConflictHandler(gitOps);
+            const lockSvc = new LockService(fileManager, globMatcher, this.logger);
+            lockService = new GitBackedLockService(lockSvc, gitOps, conflictHandler);
+            this.logger.info('GitBackedLockService instantiated for multi-session coordination');
+        }
         // Merge scaffolder callbacks with reporter callbacks for dual-channel output (AC: #1)
         const callbacks = this.mergeCallbacks(this.createScaffolderCallbacks(), this.reporter.getCallbacks());
         // Create orchestrator with merged callbacks
@@ -933,6 +975,7 @@ export default class Workflow extends Command {
             epicParser,
             fileManager,
             inputDetector,
+            lockService,
             logger: this.logger,
             pathResolver,
             prdParser,
@@ -975,4 +1018,77 @@ export default class Workflow extends Command {
             this.log('\n' + colors.warning('⚠️  Cancellation requested... completing current operation'));
         });
     }
+    /**
+     * Validate that all requested gut entities exist before attempting worktree creation.
+     * Reads .gut/config.json directly for fast validation without subprocess overhead.
+     * Fails fast with clear error message listing valid entities and fuzzy suggestions.
+     */
+    validateGutEntities(entityNames) {
+        const gutConfigPath = join(process.cwd(), '.gut', 'config.json');
+        if (!existsSync(gutConfigPath)) {
+            this.error('gut is not initialized in this workspace. Run \'gut init\' first.', { exit: 1 });
+        }
+        let allEntities;
+        try {
+            const content = readFileSync(gutConfigPath, 'utf8');
+            const config = JSON.parse(content);
+            allEntities = config.entities || [];
+        }
+        catch {
+            this.error('Failed to read .gut/config.json. Ensure the file is valid JSON.', { exit: 1 });
+        }
+        const entityMap = new Map(allEntities.map((e) => [e.name, e]));
+        const invalidEntities = entityNames.filter((name) => !entityMap.has(name));
+        if (invalidEntities.length > 0) {
+            // Entity name doesn't exist in config — show suggestions and bail
+            this.showEntityError(invalidEntities, allEntities);
+        }
+        // Entity names are valid — now check if paths actually exist (uncloned submodules, missing repos)
+        const uninitializedEntities = [];
+        for (const name of entityNames) {
+            const entity = entityMap.get(name);
+            const entityPath = join(process.cwd(), entity.path);
+            const hasContent = existsSync(join(entityPath, 'package.json')) ||
+                existsSync(join(entityPath, '.git')) ||
+                existsSync(join(entityPath, 'Cargo.toml')) ||
+                existsSync(join(entityPath, 'go.mod'));
+            if (!hasContent) {
+                uninitializedEntities.push({ name, path: entity.path });
+            }
+        }
+        if (uninitializedEntities.length > 0) {
+            const details = uninitializedEntities
+                .map((e) => `  • ${e.name} @ ${e.path}`)
+                .join('\n');
+            this.error(`These gut entities are registered but their paths are empty or uninitialized:\n${details}\n\n` +
+                'This usually means the git submodule was not cloned. Try:\n' +
+                uninitializedEntities.map((e) => `  git submodule update --init ${e.path}`).join('\n') +
+                '\n\nOr clone via gut:\n' +
+                uninitializedEntities.map((e) => `  gut entity clone ${e.name}`).join('\n'), { exit: 1 });
+        }
+        this.log(colors.info(`Preflight: all ${entityNames.length} gut entities validated ✓`));
+    }
+    showEntityError(invalidEntities, allEntities) {
+        // Build helpful error with suggestions
+        const suggestions = allEntities
+            .filter((e) => invalidEntities.some((invalid) => e.name.includes(invalid) ||
+            invalid.includes(e.name) ||
+            invalid.split('-').some((part) => part.length > 2 && e.name.includes(part))))
+            .map((e) => e.name)
+            .slice(0, 5);
+        let msg = `Invalid --gut-entities: ${invalidEntities.join(', ')}\n\n`;
+        msg += `Available entities (${allEntities.length} total):\n`;
+        msg += allEntities
+            .slice(0, 15)
+            .map((e) => `  • ${e.name} (${e.type}) @ ${e.path}`)
+            .join('\n');
+        if (allEntities.length > 15) {
+            msg += `\n  ... and ${allEntities.length - 15} more (run 'gut entity list' to see all)`;
+        }
+        if (suggestions.length > 0) {
+            msg += `\n\nDid you mean: ${suggestions.join(', ')}?`;
+        }
+        msg += '\n\nTo add a missing entity: gut entity add <name> <type> -p <path>';
+        this.error(msg, { exit: 1 });
+    }
 }

package/dist/models/agent-options.d.ts

@@ -15,6 +15,17 @@ export type OnPromptCallback = (prompt: string, options: AgentOptionsWithoutProm
  * Callback invoked when a response is received from Claude
  */
 export type OnResponseCallback = (result: AgentResult) => Promise<void> | void;
+/**
+ * Callback invoked for each meaningful stream event during agent execution.
+ * Only fired when the provider supports streaming (Claude with stream-json).
+ * Receives a human-readable summary of what the agent is doing.
+ */
+export type OnStreamCallback = (summary: string) => void;
+/**
+ * Callback invoked for every raw stream-json line (verbose mode).
+ * Receives the parsed assistant text or tool_result output verbatim.
+ */
+export type OnStreamVerboseCallback = (text: string) => void;
 /**
  * Options for executing a Claude AI agent
  */
@@ -46,6 +57,17 @@ export interface AgentOptions {
      * Callback invoked when response is received (for logging)
      */
     onResponse?: OnResponseCallback;
+    /**
+     * Callback invoked for each meaningful stream event during execution.
+     * Receives a human-readable summary like "🔧 Edit: src/foo.ts" or "💬 Running tests..."
+     * Only works with Claude provider (stream-json output mode).
+     */
+    onStream?: OnStreamCallback;
+    /**
+     * Callback invoked with full raw text from every assistant message and tool result.
+     * Used for verbose/passthrough mode where the caller wants to see everything Claude outputs.
+     */
+    onStreamVerbose?: OnStreamVerboseCallback;
     /**
      * The prompt to execute with the agent
      */
@@ -63,4 +85,15 @@ export interface AgentOptions {
      * Timeout in milliseconds (default: 1800000ms = 30 minutes)
      */
     timeout?: number;
+    /**
+     * Phase name context (used by Channel transport for callback reporting)
+     */
+    phaseName?: string;
+    /**
+     * Session display name passed to Claude via --name flag
+     *
+     * When set, the spawned Claude session gets this name, making it
+     * visible in /resume and terminal title. Claude-only feature.
+     */
+    sessionName?: string;
 }

package/dist/models/agent-result.d.ts

@@ -1,5 +1,9 @@
 /**
- * Result of executing a Claude AI agent
+ * Transport mechanism used to execute the agent
+ */
+export type TransportType = 'subprocess' | 'channel';
+/**
+ * Result of executing an AI agent
  */
 export interface AgentResult {
     /**
@@ -26,4 +30,9 @@ export interface AgentResult {
      * Whether the agent execution was successful
      */
     success: boolean;
+    /**
+     * Transport mechanism used to execute the agent.
+     * Optional for backward compatibility — defaults to 'subprocess' when omitted.
+     */
+    transport?: TransportType;
 }

package/dist/models/dispatch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dispatch Result Model
+ *
+ * Represents the outcome of a lock-aware story dispatch operation.
+ * Used by LockedStoryDispatcher to communicate whether a story was
+ * processed, skipped (locked), or failed.
+ */
+/**
+ * Result of dispatching a story through the lock-aware dispatcher
+ */
+export interface DispatchResult {
+    /** Outcome of the dispatch operation */
+    status: 'failed' | 'processed' | 'skipped';
+    /** Human-readable reason (populated for skipped/failed) */
+    reason?: string;
+}

package/dist/models/dispatch.js

@@ -0,0 +1,8 @@
+/**
+ * Dispatch Result Model
+ *
+ * Represents the outcome of a lock-aware story dispatch operation.
+ * Used by LockedStoryDispatcher to communicate whether a story was
+ * processed, skipped (locked), or failed.
+ */
+export {};

package/dist/models/index.d.ts

@@ -3,9 +3,12 @@
  */
 export * from './agent-options.js';
 export * from './agent-result.js';
+export * from './dispatch.js';
 export * from './phase-result.js';
 export * from './provider.js';
 export * from './story.js';
 export * from './workflow-callbacks.js';
 export * from './workflow-config.js';
 export * from './workflow-result.js';
+export type { SessionConfig, SessionHandle } from '../services/agents/channel-session-manager.js';
+export { SessionStartTimeoutError } from '../services/agents/channel-session-manager.js';

package/dist/models/index.js

@@ -3,9 +3,11 @@
  */
 export * from './agent-options.js';
 export * from './agent-result.js';
+export * from './dispatch.js';
 export * from './phase-result.js';
 export * from './provider.js';
 export * from './story.js';
 export * from './workflow-callbacks.js';
 export * from './workflow-config.js';
 export * from './workflow-result.js';
+export { SessionStartTimeoutError } from '../services/agents/channel-session-manager.js';

package/dist/models/lock.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Lock File Model
+ *
+ * Defines the structure and validation schema for story lock files.
+ * Lock files prevent concurrent agent sessions from modifying the same story.
+ */
+import { z } from 'zod';
+import { BaseError } from '../utils/errors.js';
+/**
+ * Lock file content interface
+ *
+ * Represents the JSON structure stored in `.lock` files alongside story files.
+ */
+export interface LockFileContent {
+    /** The unique session ID of the agent */
+    agent_session_id: string;
+    /** The agent name that acquired the lock */
+    agent_name: string;
+    /** ISO 8601 timestamp when the lock was acquired */
+    started_at: string;
+    /** The git branch the agent is working on */
+    branch: string;
+    /** Path to the story file being locked */
+    story_file: string;
+}
+/**
+ * Zod schema for runtime validation of lock file content
+ *
+ * Validates all 5 fields with strict typing:
+ * - agent_session_id must be a valid UUID
+ * - started_at must be a valid ISO 8601 datetime
+ * - All other string fields must be non-empty
+ * - Unknown keys are rejected (.strict())
+ */
+export declare const lockFileSchema: z.ZodObject<{
+    agent_session_id: z.ZodString;
+    agent_name: z.ZodString;
+    started_at: z.ZodString;
+    branch: z.ZodString;
+    story_file: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Lock conflict error for story locking failures
+ *
+ * Used when an agent attempts to acquire a lock on a story that is already locked
+ * by another agent session.
+ */
+/**
+ * Push rejected error for lock acquire failures
+ *
+ * Used when a git push is rejected during lock acquisition (non-fast-forward
+ * after retry exhaustion, network errors, etc.).
+ */
+export declare class PushRejectedError extends BaseError {
+    /**
+     * Create a new PushRejectedError
+     *
+     * @param params - Object with storyFile and reason
+     * @example
+     * throw new PushRejectedError({ storyFile: 'docs/stories/STORY-1.001.md', reason: 'non-fast-forward' })
+     */
+    constructor({ storyFile, reason }: {
+        storyFile: string;
+        reason: string;
+    });
+}
+export declare class LockConflictError extends BaseError {
+    /**
+     * The existing lock content that caused the conflict
+     */
+    readonly lockContent: LockFileContent;
+    /**
+     * Create a new LockConflictError
+     *
+     * @param lockContent - The existing lock file content causing the conflict
+     * @example
+     * throw new LockConflictError(existingLock)
+     */
+    constructor(lockContent: LockFileContent);
+}

package/dist/models/lock.js

@@ -0,0 +1,69 @@
+/**
+ * Lock File Model
+ *
+ * Defines the structure and validation schema for story lock files.
+ * Lock files prevent concurrent agent sessions from modifying the same story.
+ */
+import { z } from 'zod';
+import { BaseError, ERR_LOCK } from '../utils/errors.js';
+/**
+ * Zod schema for runtime validation of lock file content
+ *
+ * Validates all 5 fields with strict typing:
+ * - agent_session_id must be a valid UUID
+ * - started_at must be a valid ISO 8601 datetime
+ * - All other string fields must be non-empty
+ * - Unknown keys are rejected (.strict())
+ */
+export const lockFileSchema = z.object({
+    agent_session_id: z.string().uuid(),
+    agent_name: z.string().min(1),
+    started_at: z.string().datetime(),
+    branch: z.string().min(1),
+    story_file: z.string().min(1),
+}).strict();
+/**
+ * Lock conflict error for story locking failures
+ *
+ * Used when an agent attempts to acquire a lock on a story that is already locked
+ * by another agent session.
+ */
+/**
+ * Push rejected error for lock acquire failures
+ *
+ * Used when a git push is rejected during lock acquisition (non-fast-forward
+ * after retry exhaustion, network errors, etc.).
+ */
+export class PushRejectedError extends BaseError {
+    /**
+     * Create a new PushRejectedError
+     *
+     * @param params - Object with storyFile and reason
+     * @example
+     * throw new PushRejectedError({ storyFile: 'docs/stories/STORY-1.001.md', reason: 'non-fast-forward' })
+     */
+    constructor({ storyFile, reason }) {
+        super(`Push rejected while acquiring lock for "${storyFile}": ${reason}`, ERR_LOCK, { reason, story_file: storyFile }, 'A git push was rejected during lock acquisition. This may indicate a concurrent operation or network issue.');
+    }
+}
+export class LockConflictError extends BaseError {
+    /**
+     * The existing lock content that caused the conflict
+     */
+    lockContent;
+    /**
+     * Create a new LockConflictError
+     *
+     * @param lockContent - The existing lock file content causing the conflict
+     * @example
+     * throw new LockConflictError(existingLock)
+     */
+    constructor(lockContent) {
+        super(`Story "${lockContent.story_file}" is locked by agent "${lockContent.agent_name}" (session: ${lockContent.agent_session_id})`, ERR_LOCK, {
+            agent_name: lockContent.agent_name,
+            story_file: lockContent.story_file,
+            session_id: lockContent.agent_session_id,
+        }, `Wait for agent "${lockContent.agent_name}" to finish or release the lock manually.`);
+        this.lockContent = lockContent;
+    }
+}

package/dist/models/phase-result.d.ts

@@ -37,6 +37,14 @@ export interface PhaseResult {
      * @default false
      */
     skipped: boolean;
+    /**
+     * Count of stories skipped due to lock conflicts
+     *
+     * Only populated when lockingEnabled is true and another session
+     * held the lock on a story at dispatch time.
+     * @default 0
+     */
+    skippedCount?: number;
     /**
      * Count of successful operations in this phase
      *

package/dist/models/provider.js

@@ -7,7 +7,7 @@
 export const PROVIDER_CONFIGS = {
     claude: {
         command: 'claude',
-        flags: ['--dangerously-skip-permissions', '--print'],
+        flags: ['--dangerously-skip-permissions', '-p', '--output-format', 'stream-json', '--verbose'],
         modelFlag: '--model',
         supportsFileReferences: true,
     },

package/dist/models/workflow-callbacks.d.ts

@@ -98,6 +98,27 @@ export interface LayerContext {
      */
     failureCount?: number;
 }
+/**
+ * Reason why the factory fell back from Channel transport to subprocess.
+ */
+export type ChannelFallbackReason = 'not_discovered' | 'connection_refused' | 'timeout' | 'health_check_failed';
+/**
+ * Context for Channel connect/disconnect lifecycle events.
+ */
+export interface ChannelContext {
+    sessionId: string;
+    port: number;
+    agentType: string;
+    phaseName: string;
+}
+/**
+ * Context for Channel fallback events (Channel → subprocess).
+ */
+export interface ChannelFallbackContext {
+    agentType: string;
+    reason: ChannelFallbackReason;
+    phaseName: string;
+}
 /**
  * Context for spawn (agent execution) lifecycle events
  *
@@ -160,6 +181,10 @@ export interface SpawnContext {
      * Worker ID for pipelined execution
      */
     workerId?: number;
+    /**
+     * Transport mechanism used: 'subprocess' (claude -p) or 'channel' (persistent session)
+     */
+    transport?: 'subprocess' | 'channel';
     /**
      * Additional metadata
      */
@@ -248,4 +273,16 @@ export interface WorkflowCallbacks {
      * Called when an error occurs
      */
     onError?: (context: ErrorContext) => void;
+    /**
+     * Called when a Channel agent connection is established (first successful envelope exchange)
+     */
+    onChannelConnect?: (context: ChannelContext) => void;
+    /**
+     * Called when a Channel agent connection is terminated
+     */
+    onChannelDisconnect?: (context: ChannelContext) => void;
+    /**
+     * Called when the factory falls back from Channel transport to subprocess
+     */
+    onChannelFallback?: (context: ChannelFallbackContext) => void;
 }

package/dist/models/workflow-config.d.ts

@@ -70,6 +70,14 @@ export interface WorkflowConfig {
      * @default 3
      */
     parallel: number;
+    /**
+     * Enable git-backed story locking for multi-session coordination
+     *
+     * When true, stories are locked before processing and unlocked after completion,
+     * preventing parallel sessions from working the same story simultaneously.
+     * @default false
+     */
+    lockingEnabled?: boolean;
     /**
      * Enable pipelined workflow execution
      *
@@ -255,6 +263,40 @@ export interface WorkflowConfig {
      * @default 5000 (5 seconds)
      */
     retryBackoffMs?: number;
+    /**
+     * Enable Channel transport for agent execution
+     *
+     * When true, the AgentRunnerFactory discovers Channel-capable agents
+     * via listAgents() and returns a ChannelAgentRunner when a match is found.
+     * Falls back to subprocess runner when no Channel agent is discovered.
+     * @default false
+     */
+    useChannels?: boolean;
+    /**
+     * Timeout for Channel agent requests in milliseconds
+     *
+     * Applied to ChannelAgentRunner HTTP requests when useChannels is true.
+     * @default 300_000 (5 minutes)
+     */
+    channelTimeout?: number;
+    /**
+     * Session display name template for spawned Claude sessions
+     *
+     * When set, each spawned Claude subprocess gets a named session
+     * visible in /resume and terminal title. Supports placeholders:
+     * - {story} — replaced with story number (e.g., "1.001")
+     * - {phase} — replaced with phase name (e.g., "dev", "epic", "story")
+     * - {prefix} — replaced with the derived prefix from inputPath
+     */
+    sessionName?: string;
+    /**
+     * Original input file path — used for auto-generating session names
+     *
+     * When set, resolveSessionName() derives a compact prefix from this path
+     * and auto-generates session names when no explicit --session-name is given.
+     * Absent for programmatic callers that don't supply a file path.
+     */
+    inputPath?: string;
     /**
      * Detailed output mode
      *
@@ -262,4 +304,12 @@ export interface WorkflowConfig {
      * @default false
      */
     verbose: boolean;
+    /**
+     * Stream full Claude output to stdout in real-time
+     *
+     * When true, raw assistant text from Claude's stream-json output is
+     * piped directly to stdout so callers can see exactly what's happening.
+     * @default false
+     */
+    stream?: boolean;
 }