praxis-agent 0.31.0 → 0.32.0

package/dist/application/session-service.d.ts

@@ -188,6 +188,7 @@ export declare class ClaudeSessionService {
     private readonly hostedSubagentsByRegistry;
     private readonly backgroundNotificationWrites;
     private readonly downloadedFileResourceSessions;
+    private readonly detachedHookRuns;
     private activeProvider;
     private mcpClosePromise;
     private readonly sessionCostTrackers;
@@ -196,6 +197,7 @@ export declare class ClaudeSessionService {
     private readonly sessionMemoryControllers;
     private resolvedSessionMemoryProvider;
     private readonly hookLifecycle;
+    private readonly fileChangeWatcher;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
     nextScheduledPrompt(signal?: AbortSignal): Promise<ScheduledPrompt | null>;
@@ -214,6 +216,23 @@ export declare class ClaudeSessionService {
     close(): Promise<void>;
     transitionHookSession(sessionId: string, reason: Exclude<HookSessionEndReason, 'other'>): Promise<void>;
     reloadContextResources(sessionId: string): void;
+    notify(sessionId: string | undefined, message: string, notificationType: string, title?: string, signal?: AbortSignal): Promise<void>;
+    notifyDetached(sessionId: string | undefined, message: string, notificationType: string, title?: string): void;
+    private drainDetachedHookRuns;
+    instructionsLoaded(sessionId: string, resources: readonly {
+        path: string;
+        scope: 'local' | 'project' | 'user';
+        importedFrom?: string;
+    }[], reason: 'session_start' | 'compact' | 'resource_reload'): Promise<void>;
+    instructionLoaded(sessionId: string, resource: {
+        path: string;
+        memoryType: 'User' | 'Project' | 'Local' | 'Managed';
+        globs?: readonly string[];
+        triggerFilePath?: string;
+        parentFilePath?: string;
+    }, loadReason: 'session_start' | 'nested_traversal' | 'path_glob_match' | 'include' | 'compact'): Promise<void>;
+    private runAdvisoryHook;
+    private cwdChanged;
     createHostedToolRegistry(sessionId: string): ToolRegistry;
     run(prompt: string, signal?: AbortSignal, sessionId?: string, name?: string, images?: readonly ModelImage[], documents?: readonly ModelDocument[]): Promise<SessionRunResult>;
     runShell(command: string, signal?: AbortSignal, sessionId?: string, name?: string): Promise<SessionRunResult>;

package/dist/application/session-service.js

@@ -16,13 +16,14 @@ import { getClaudeAgentSetting, getClaudeLastPrompt, projectClaudeDisplayTranscr
 import { selectClaudeSchemaAdapter, } from '../compatibility/claude/schema.js';
 import { findUnresolvedClaudeToolCalls, getClaudeContentBlocks, } from '../compatibility/claude/tool-links.js';
 import { createClaudeAgentSettingEntry, createClaudeHookAttachmentEntries, createClaudeLastPromptEntry, createClaudeRuleAttachmentEntry, translateProviderEvents, } from '../compatibility/claude/translation.js';
-import { AgentRunCancelledError, AgentRuntime, } from '../core/runtime.js';
+import { AgentRunCancelledError, AgentRuntime, ModelProviderError, } from '../core/runtime.js';
 import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
 import { BackgroundTaskRuntime, } from './background-task-runtime.js';
 import { usageCostUsd } from '../core/usage.js';
 import { ContextBudget, ContextRecoveryPlanner, contextRecoveryMadeProgress, estimateModelRequestTokens, isPromptTooLongError, } from '../core/context-budget.js';
 import { injectFirstUserMessageContext, } from '../core/context.js';
 import { ClaudeHookToolCoordinator } from '../hooks/claude-hook-tools.js';
+import { ClaudeFileChangeWatcher } from '../hooks/claude-file-change-watcher.js';
 import { ClaudeTranscriptStore, } from '../persistence/claude-transcript-store.js';
 import { InMemoryTranscriptStore } from '../persistence/in-memory-transcript-store.js';
 import { ModelCompactor } from './model-compactor.js';
@@ -481,6 +482,34 @@ function projectMemoryMessages(entries) {
             : []);
     });
 }
+function successfulHookOutput(outcome) {
+    return (outcome?.executions ?? []).flatMap((execution) => {
+        const output = execution.stdout.trim();
+        return execution.exitCode === 0 && output.length > 0 ? [output] : [];
+    });
+}
+function claudeStopFailureError(kind) {
+    switch (kind) {
+        case 'authentication_failed':
+        case 'billing_error':
+        case 'rate_limit':
+        case 'invalid_request':
+        case 'server_error':
+        case 'max_output_tokens':
+            return kind;
+        case 'prompt_too_long':
+            return 'invalid_request';
+        case 'timeout':
+        case 'overloaded':
+        case 'api_error':
+        case 'transport_error':
+            return 'server_error';
+        case 'cancelled':
+        case 'unknown':
+        case undefined:
+            return 'unknown';
+    }
+}
 const SESSION_END_HOOK_TIMEOUT_MS = 15_000;
 class HookLifecycle {
     hooks;
@@ -606,6 +635,7 @@ export class ClaudeSessionService {
     hostedSubagentsByRegistry = new WeakMap();
     backgroundNotificationWrites = new Map();
     downloadedFileResourceSessions = new Set();
+    detachedHookRuns = new Map();
     activeProvider;
     mcpClosePromise;
     sessionCostTrackers = new Map();
@@ -614,11 +644,26 @@ export class ClaudeSessionService {
     sessionMemoryControllers = new Map();
     resolvedSessionMemoryProvider;
     hookLifecycle;
+    fileChangeWatcher;
     runtimeCwd;
     constructor(options) {
         this.options = options;
         this.hookLifecycle = new HookLifecycle(options.hooks, options.eventSink);
         this.runtimeCwd = options.workspace?.cwd() ?? options.cwd;
+        this.fileChangeWatcher = options.hooks
+            ? new ClaudeFileChangeWatcher({
+                cwd: this.runtimeCwd,
+                staticPaths: options.hooks.fileChangedWatchPaths(this.runtimeCwd),
+                onFileChanged: async (filePath, event, signal) => {
+                    const sessionId = this.activeCostSessionId;
+                    if (!sessionId)
+                        return undefined;
+                    const outcome = await this.runAdvisoryHook(sessionId, 'FileChanged', { file_path: filePath, event }, undefined, signal);
+                    return outcome?.watchPaths;
+                },
+                warn: (message) => options.eventSink?.({ type: 'warning', message }),
+            })
+            : null;
         this.schema = selectClaudeSchemaAdapter(options.claudeVersion);
         this.scheduledPrompts =
             options.tools && (options.scheduledToolNames?.length ?? 0) > 0
@@ -756,7 +801,10 @@ export class ClaudeSessionService {
         }
     }
     async close() {
+        await this.fileChangeWatcher?.close(5_000);
         await this.hookLifecycle.close();
+        await this.drainDetachedHookRuns(5_000);
+        await this.options.hooks?.drainAsync(5_000);
         this.scheduledPrompts?.close();
         await this.options.projectMemoryExtraction?.close(5_000);
         await Promise.all([...this.hostedSubagents].map((executor) => executor.close()));
@@ -788,6 +836,119 @@ export class ClaudeSessionService {
             reason: 'resource-reload',
         });
     }
+    async notify(sessionId, message, notificationType, title, signal) {
+        const targetSessionId = sessionId ?? this.activeCostSessionId;
+        if (!targetSessionId)
+            return;
+        await this.runAdvisoryHook(targetSessionId, 'Notification', {
+            message,
+            notification_type: notificationType,
+            ...(title === undefined ? {} : { title }),
+        }, notificationType, signal);
+    }
+    notifyDetached(sessionId, message, notificationType, title) {
+        const controller = new AbortController();
+        const pending = this.notify(sessionId, message, notificationType, title, controller.signal);
+        this.detachedHookRuns.set(pending, controller);
+        void pending.finally(() => this.detachedHookRuns.delete(pending));
+    }
+    async drainDetachedHookRuns(timeoutMs) {
+        const pending = [...this.detachedHookRuns.keys()];
+        if (pending.length === 0)
+            return;
+        let timer;
+        try {
+            if ((await Promise.race([
+                Promise.allSettled(pending).then(() => 'settled'),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve('timeout'), timeoutMs);
+                }),
+            ])) === 'timeout') {
+                for (const controller of this.detachedHookRuns.values()) {
+                    controller.abort();
+                }
+                this.detachedHookRuns.clear();
+                await Promise.resolve();
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async instructionsLoaded(sessionId, resources, reason) {
+        if (reason === 'resource_reload')
+            return;
+        for (const resource of resources) {
+            const loadReason = resource.importedFrom
+                ? 'include'
+                : reason === 'compact'
+                    ? 'compact'
+                    : 'session_start';
+            await this.instructionLoaded(sessionId, {
+                path: resource.path,
+                memoryType: resource.scope === 'user'
+                    ? 'User'
+                    : resource.scope === 'local'
+                        ? 'Local'
+                        : 'Project',
+                ...(resource.importedFrom === undefined
+                    ? {}
+                    : { parentFilePath: resource.importedFrom }),
+            }, loadReason);
+        }
+    }
+    async instructionLoaded(sessionId, resource, loadReason) {
+        await this.runAdvisoryHook(sessionId, 'InstructionsLoaded', {
+            file_path: resource.path,
+            memory_type: resource.memoryType,
+            load_reason: loadReason,
+            ...(resource.globs === undefined ? {} : { globs: resource.globs }),
+            ...(resource.triggerFilePath === undefined
+                ? {}
+                : { trigger_file_path: resource.triggerFilePath }),
+            ...(resource.parentFilePath === undefined
+                ? {}
+                : { parent_file_path: resource.parentFilePath }),
+        }, loadReason);
+    }
+    async runAdvisoryHook(sessionId, event, fields, matcher, signal) {
+        if (!this.options.hooks)
+            return undefined;
+        try {
+            const outcome = await this.options.hooks.run({
+                session_id: sessionId,
+                transcript_path: this.paths(sessionId).sessionFile,
+                cwd: this.activeCwd(),
+                permission_mode: 'default',
+                hook_event_name: event,
+                ...fields,
+            }, matcher, signal);
+            for (const message of outcome.systemMessages ?? []) {
+                this.options.eventSink?.({
+                    type: 'user-message',
+                    message,
+                    status: 'proactive',
+                });
+            }
+            return outcome;
+        }
+        catch (error) {
+            this.options.eventSink?.({
+                type: 'warning',
+                message: `${event} hook failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            return undefined;
+        }
+    }
+    async cwdChanged(sessionId, previousCwd, cwd) {
+        await this.options.hooks?.clearCwdEnvironment(sessionId);
+        const outcome = await this.runAdvisoryHook(sessionId, 'CwdChanged', {
+            old_cwd: previousCwd,
+            new_cwd: cwd,
+        });
+        this.fileChangeWatcher?.updateForCwd(cwd, this.options.hooks?.fileChangedWatchPaths(cwd) ?? [], outcome?.watchPaths ?? []);
+    }
     createHostedToolRegistry(sessionId) {
         const baseTools = this.options.tools;
         if (!baseTools)
@@ -1451,6 +1612,7 @@ export class ClaudeSessionService {
                 lifecycleId: sessionId,
                 reason: 'cwd',
             });
+            await this.cwdChanged(sessionId, previousCwd, cwd);
             return cwd;
         }
         this.runtimeCwd = cwd;
@@ -1462,6 +1624,7 @@ export class ClaudeSessionService {
                 lifecycleId: sessionId,
                 reason: 'cwd',
             });
+            await this.cwdChanged(sessionId, previousCwd, cwd);
         }
         return cwd;
     }
@@ -1710,6 +1873,14 @@ export class ClaudeSessionService {
             if (findUnresolvedClaudeToolCalls(snapshot.entries).length > 0) {
                 throw new Error('Cannot compact a Claude session with unresolved tool calls');
             }
+            const preCompact = await this.runAdvisoryHook(sessionId, 'PreCompact', {
+                trigger: 'manual',
+                custom_instructions: selection?.context ?? null,
+            }, 'manual', signal);
+            messages.push(...successfulHookOutput(preCompact).map((content) => ({
+                role: 'user',
+                content: `Additional summarization context: ${content}`,
+            })));
             this.options.eventSink?.({ type: 'state', state: 'compacting' });
             const contextWindowTokens = this.contextBudget(provider)?.contextWindowTokens ??
                 provider.capabilities.contextWindowTokens ??
@@ -1812,6 +1983,7 @@ export class ClaudeSessionService {
                 preTokens,
                 uuid: boundaryUuid,
             });
+            await this.runAdvisoryHook(sessionId, 'PostCompact', { trigger: 'manual', compact_summary: summary }, 'manual', signal);
             if (meteringTurnInput !== undefined) {
                 const tracker = this.sessionCostTrackers.get(sessionId);
                 if (!tracker) {
@@ -2258,6 +2430,42 @@ export class ClaudeSessionService {
                         ? { eventSink: this.options.eventSink }
                         : {}),
                     enabledTools: taskToolNames,
+                    ...(this.options.hooks
+                        ? {
+                            taskHooks: {
+                                created: async (task, taskSignal) => {
+                                    const outcome = await this.options.hooks?.run({
+                                        ...hookSession,
+                                        hook_event_name: 'TaskCreated',
+                                        task_id: task.id,
+                                        task_subject: task.subject,
+                                        task_description: task.description,
+                                    }, undefined, taskSignal);
+                                    if (!outcome)
+                                        return;
+                                    await recordHookOutcome(outcome);
+                                    if (outcome.blockedReason) {
+                                        throw new Error(`TaskCreated hook error: ${outcome.blockedReason}`);
+                                    }
+                                },
+                                completed: async (task, taskSignal) => {
+                                    const outcome = await this.options.hooks?.run({
+                                        ...hookSession,
+                                        hook_event_name: 'TaskCompleted',
+                                        task_id: task.id,
+                                        task_subject: task.subject,
+                                        task_description: task.description,
+                                    }, undefined, taskSignal);
+                                    if (!outcome)
+                                        return;
+                                    await recordHookOutcome(outcome);
+                                    if (outcome.blockedReason) {
+                                        throw new Error(`TaskCompleted hook error: ${outcome.blockedReason}`);
+                                    }
+                                },
+                            },
+                        }
+                        : {}),
                 })
                 : null;
             const scheduledTools = this.scheduledPrompts &&
@@ -2456,6 +2664,11 @@ export class ClaudeSessionService {
                     hooks: this.options.hooks,
                     session: hookSession,
                     recordOutcome: recordHookOutcome,
+                    ...(this.options.eventSink
+                        ? {
+                            warn: (message) => this.options.eventSink?.({ type: 'warning', message }),
+                        }
+                        : {}),
                     deferPreToolUseOutcome: (call) => pendingRecoveryToolCallIds.has(call.id),
                 })
                 : null;
@@ -2606,6 +2819,19 @@ export class ClaudeSessionService {
                                 tail: attachmentTail,
                             };
                             attachedRulePaths.add(rule.path);
+                            await this.instructionLoaded(sessionId, {
+                                path: rule.path,
+                                memoryType: rule.scope === 'user'
+                                    ? 'User'
+                                    : rule.scope === 'local'
+                                        ? 'Local'
+                                        : 'Project',
+                                globs: rule.globs,
+                                triggerFilePath: filePath,
+                                ...(rule.importedFrom === undefined
+                                    ? {}
+                                    : { parentFilePath: rule.importedFrom }),
+                            }, 'path_glob_match');
                         }
                     }
                 },
@@ -2892,6 +3118,7 @@ export class ClaudeSessionService {
                     if (findUnresolvedClaudeToolCalls(snapshot.entries).length > 0) {
                         throw new Error('Cannot compact a Claude session with unresolved tool calls');
                     }
+                    const preCompact = await this.runAdvisoryHook(sessionId, 'PreCompact', { trigger: 'auto', custom_instructions: null }, 'auto', signal);
                     const memorySelection = sessionMemory
                         ? await this.selectMemoryPreservedCompact(sessionId, selectClaudeActiveTranscript(snapshot.entries))
                         : null;
@@ -2901,6 +3128,10 @@ export class ClaudeSessionService {
                             ...projectClaudeModelMessages(memorySelection.compactedEntries),
                         ]
                         : historyMessages;
+                    compactorMessages.push(...successfulHookOutput(preCompact).map((content) => ({
+                        role: 'user',
+                        content: `Additional summarization context: ${content}`,
+                    })));
                     if (memorySelection) {
                         logicalParentUuid = memorySelection.logicalParentUuid;
                     }
@@ -3071,6 +3302,7 @@ export class ClaudeSessionService {
                         entries: [...snapshot.entries, ...entries],
                         tail: appendResult.tail,
                     };
+                    await this.runAdvisoryHook(sessionId, 'PostCompact', { trigger: 'auto', compact_summary: compacted.summary }, 'auto', signal);
                     // The boundary is durable: mirror Claude's full-compact behavior by
                     // rerunning SessionStart with source compact and refreshing the
                     // runtime-only context so the next request retains current
@@ -3181,6 +3413,7 @@ export class ClaudeSessionService {
                     try {
                         shellResult = await runtime.executeDirectToolCall(call, {
                             cwd: this.activeCwd(),
+                            sessionId,
                             toolResultDirectory,
                             messages: projectClaudeModelMessages(snapshot.entries),
                             observer: {
@@ -3252,6 +3485,7 @@ export class ClaudeSessionService {
                 }
                 let stopHookActive = false;
                 const runtimeRequest = {
+                    sessionId,
                     messages: [
                         ...contextMessages,
                         ...injectTurnContext(projectClaudeModelMessages(snapshot.entries)),
@@ -3387,70 +3621,86 @@ export class ClaudeSessionService {
                 };
                 let result;
                 try {
-                    result = await attemptMainTurn();
-                }
-                catch (error) {
-                    if (!budget || !isPromptTooLongError(error))
-                        throw error;
-                    if (recoveryPlanner.reactiveRetriesRemaining === 0) {
-                        surfaceExhaustedRecovery(error);
-                        throw error;
-                    }
-                    const beforeRecovery = budget.evaluate(runtimeRequest.messages, definitions);
-                    try {
-                        await compactIfNeeded([], currentTurnUserMessages ?? [], {
-                            promptTooLong: true,
-                        });
-                    }
-                    catch (compactionError) {
-                        if (signal?.aborted ||
-                            compactionError instanceof AgentRunCancelledError) {
-                            throw new AgentRunCancelledError();
-                        }
-                        // Compaction could not free the provider-bounded context; surface
-                        // the original prompt-too-long error rather than the compaction
-                        // failure.
-                        surfaceExhaustedRecovery(error);
-                        throw error;
-                    }
-                    // The single reactive retry must use the compacted transcript, not
-                    // the stale request copy captured before the compact boundary.
-                    runtimeRequest.messages = [
-                        ...contextMessages,
-                        ...injectTurnContext([
-                            ...projectClaudeModelMessages(snapshot.entries),
-                            ...projectMemoryRecallMessages,
-                        ]),
-                    ];
-                    if (stableSystemMessageCount === undefined) {
-                        delete runtimeRequest.stableSystemMessageCount;
-                    }
-                    else {
-                        runtimeRequest.stableSystemMessageCount = stableSystemMessageCount;
-                    }
-                    const afterRecovery = budget.evaluate(runtimeRequest.messages, definitions);
-                    if (recoveryPlanner.consumeReactiveRetry({
-                        beforeOccupancyTokens: beforeRecovery.occupancyTokens,
-                        afterOccupancyTokens: afterRecovery.occupancyTokens,
-                    }) !== 'reactive-retry') {
-                        surfaceExhaustedRecovery(error);
-                        throw error;
-                    }
-                    runtimeRequest.deferFailureKinds = true;
                     try {
                         result = await attemptMainTurn();
                     }
-                    catch (retryError) {
-                        // Exactly one reactive retry is consumed; fail deterministically
-                        // and surface the original prompt-too-long error.
-                        recoveryPlanner.recordFailure();
-                        if (signal?.aborted ||
-                            retryError instanceof AgentRunCancelledError) {
-                            throw new AgentRunCancelledError();
+                    catch (error) {
+                        if (!budget || !isPromptTooLongError(error))
+                            throw error;
+                        if (recoveryPlanner.reactiveRetriesRemaining === 0) {
+                            surfaceExhaustedRecovery(error);
+                            throw error;
                         }
-                        surfaceExhaustedRecovery(error);
-                        throw error;
+                        const beforeRecovery = budget.evaluate(runtimeRequest.messages, definitions);
+                        try {
+                            await compactIfNeeded([], currentTurnUserMessages ?? [], {
+                                promptTooLong: true,
+                            });
+                        }
+                        catch (compactionError) {
+                            if (signal?.aborted ||
+                                compactionError instanceof AgentRunCancelledError) {
+                                throw new AgentRunCancelledError();
+                            }
+                            // Compaction could not free the provider-bounded context; surface
+                            // the original prompt-too-long error rather than the compaction
+                            // failure.
+                            surfaceExhaustedRecovery(error);
+                            throw error;
+                        }
+                        // The single reactive retry must use the compacted transcript, not
+                        // the stale request copy captured before the compact boundary.
+                        runtimeRequest.messages = [
+                            ...contextMessages,
+                            ...injectTurnContext([
+                                ...projectClaudeModelMessages(snapshot.entries),
+                                ...projectMemoryRecallMessages,
+                            ]),
+                        ];
+                        if (stableSystemMessageCount === undefined) {
+                            delete runtimeRequest.stableSystemMessageCount;
+                        }
+                        else {
+                            runtimeRequest.stableSystemMessageCount = stableSystemMessageCount;
+                        }
+                        const afterRecovery = budget.evaluate(runtimeRequest.messages, definitions);
+                        if (recoveryPlanner.consumeReactiveRetry({
+                            beforeOccupancyTokens: beforeRecovery.occupancyTokens,
+                            afterOccupancyTokens: afterRecovery.occupancyTokens,
+                        }) !== 'reactive-retry') {
+                            surfaceExhaustedRecovery(error);
+                            throw error;
+                        }
+                        runtimeRequest.deferFailureKinds = true;
+                        try {
+                            result = await attemptMainTurn();
+                        }
+                        catch (retryError) {
+                            // Exactly one reactive retry is consumed; fail deterministically
+                            // and surface the original prompt-too-long error.
+                            recoveryPlanner.recordFailure();
+                            if (signal?.aborted ||
+                                retryError instanceof AgentRunCancelledError) {
+                                throw new AgentRunCancelledError();
+                            }
+                            surfaceExhaustedRecovery(error);
+                            throw error;
+                        }
+                    }
+                }
+                catch (error) {
+                    if (!signal?.aborted &&
+                        !(error instanceof AgentRunCancelledError) &&
+                        !(error instanceof ModelProviderError && error.kind === 'cancelled')) {
+                        const failureKind = error instanceof ModelProviderError
+                            ? claudeStopFailureError(error.kind)
+                            : 'unknown';
+                        await this.runAdvisoryHook(sessionId, 'StopFailure', {
+                            error: failureKind,
+                            error_details: error instanceof Error ? error.message : String(error),
+                        }, failureKind, signal);
                     }
+                    throw error;
                 }
                 recoveryPlanner.recordSuccess();
                 const mainModel = provider.model !== undefined && provider.model.trim() !== ''

package/dist/application/subagent-service.js

@@ -1318,6 +1318,11 @@ export class ClaudeSubagentExecutor {
                 hooks: scopedHooks,
                 session: hookSession,
                 recordOutcome: recordHookOutcome,
+                ...(this.options.eventSink
+                    ? {
+                        warn: (message) => this.options.eventSink?.({ type: 'warning', message }),
+                    }
+                    : {}),
             })
             : agentTools;
         const runtimePermissions = scopedHooks
@@ -1515,6 +1520,7 @@ export class ClaudeSubagentExecutor {
             const configuredEffort = typeof customAgent?.effort === 'string' ? customAgent.effort : undefined;
             const effectiveEffort = options.effort ?? configuredEffort;
             const result = await runtime.run({
+                sessionId: String(options.root.sessionId),
                 messages: await assembleMessages(),
                 collectMetrics: true,
                 reloadMessages: assembleMessages,

package/dist/cli/interactive.d.ts

@@ -42,6 +42,7 @@ interface InteractiveSessionCommands {
     rewindFiles?(sessionId: string, userMessageId: string): Promise<void>;
     rewindPoints?(sessionId: string): Promise<RewindPoint[]>;
     changeCwd?(sessionId: string | undefined, cwd: string): Promise<string>;
+    notify?(sessionId: string | undefined, message: string, notificationType: string, title?: string): void;
     recordCdUsage?(sessionId: string): Promise<void>;
     approveRecentlyDenied?(sessionId: string, display: string): Promise<void>;
     retryRecentlyDenied?(sessionId: string, display: string, signal?: AbortSignal): Promise<SessionRunResult>;
@@ -189,11 +190,12 @@ interface InteractiveAppProps {
     runtimeSettings?: PraxisRuntimeSettings;
     runtimeSettingsTarget?: ConfigSettingsTarget;
     notificationWriter?: TuiNotificationWriter;
+    notificationDelayMs?: number;
     elicitationUrlOpener?: (url: string) => void | Promise<void>;
     releaseNotesLoader?: (configRoot: string) => Promise<string>;
     settingSources?: readonly ClaudeResourceScope[];
 }
-export declare function InteractiveApp({ dataPlane, configRoot: suppliedConfigRoot, statePath: suppliedStatePath, factory, initialSessions, initialPrompt, initialHistory, initialSessionColor, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader, allowNewSession, resume, display, terminalWidth, slashCommands, agents, allowDangerouslySkipPermissions, additionalDirectories, diffLoader, doctorLoader, fileLoader, externalEditor, keybindingsConfigRoot, keybindingsFile, keybindingsLoader, keybindingsEditor, memoryFilesLoader, memoryEditor, memoryFolderOpener, suspendProcess, clipboardReader, clipboardWriter, sideQuestionClipboardWriter, exportWriter, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver, workspaceDirectoryCompleter, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener, releaseNotesLoader, settingSources, }: InteractiveAppProps): import("react").JSX.Element;
+export declare function InteractiveApp({ dataPlane, configRoot: suppliedConfigRoot, statePath: suppliedStatePath, factory, initialSessions, initialPrompt, initialHistory, initialSessionColor, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader, allowNewSession, resume, display, terminalWidth, slashCommands, agents, allowDangerouslySkipPermissions, additionalDirectories, diffLoader, doctorLoader, fileLoader, externalEditor, keybindingsConfigRoot, keybindingsFile, keybindingsLoader, keybindingsEditor, memoryFilesLoader, memoryEditor, memoryFolderOpener, suspendProcess, clipboardReader, clipboardWriter, sideQuestionClipboardWriter, exportWriter, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver, workspaceDirectoryCompleter, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, notificationDelayMs, elicitationUrlOpener, releaseNotesLoader, settingSources, }: InteractiveAppProps): import("react").JSX.Element;
 export declare function runInteractive(options: {
     dataPlane?: DataPlane;
     configRoot?: string;

package/dist/cli/interactive.js

@@ -267,7 +267,7 @@ const HIDDEN_TUI_SLASH_COMMANDS = new Set([
     'update',
     'usage',
 ]);
-export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: suppliedConfigRoot, statePath: suppliedStatePath, factory, initialSessions, initialPrompt, initialHistory = [], initialSessionColor, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader = false, allowNewSession = true, resume, display = { version: 'dev', cwd: process.cwd() }, terminalWidth, slashCommands = EMPTY_SLASH_COMMANDS, agents = EMPTY_AGENTS, allowDangerouslySkipPermissions = false, additionalDirectories = [], diffLoader, doctorLoader, fileLoader, externalEditor = editTuiPrompt, keybindingsConfigRoot, keybindingsFile = ensureTuiKeybindingsFile, keybindingsLoader = loadTuiKeybindings, keybindingsEditor = openTuiEditorFile, memoryFilesLoader, memoryEditor = openTuiEditorFile, memoryFolderOpener = openTuiMemoryFolder, suspendProcess = suspendTuiProcess, clipboardReader = readTuiClipboard, clipboardWriter = writeTuiClipboard, sideQuestionClipboardWriter = writeTuiOsc52Clipboard, exportWriter = writeConversationExport, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver = resolveTuiWorkspaceDirectory, workspaceDirectoryCompleter = completeTuiWorkspaceDirectory, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, elicitationUrlOpener = openTuiUrl, releaseNotesLoader = (configRoot) => loadClaudeReleaseNotes({ configRoot }), settingSources, }) {
+export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: suppliedConfigRoot, statePath: suppliedStatePath, factory, initialSessions, initialPrompt, initialHistory = [], initialSessionColor, signal, onCancel, onTurnChange, onCleanup, onRendererChange, onBackground, axScreenReader = false, allowNewSession = true, resume, display = { version: 'dev', cwd: process.cwd() }, terminalWidth, slashCommands = EMPTY_SLASH_COMMANDS, agents = EMPTY_AGENTS, allowDangerouslySkipPermissions = false, additionalDirectories = [], diffLoader, doctorLoader, fileLoader, externalEditor = editTuiPrompt, keybindingsConfigRoot, keybindingsFile = ensureTuiKeybindingsFile, keybindingsLoader = loadTuiKeybindings, keybindingsEditor = openTuiEditorFile, memoryFilesLoader, memoryEditor = openTuiEditorFile, memoryFolderOpener = openTuiMemoryFolder, suspendProcess = suspendTuiProcess, clipboardReader = readTuiClipboard, clipboardWriter = writeTuiClipboard, sideQuestionClipboardWriter = writeTuiOsc52Clipboard, exportWriter = writeConversationExport, permissionRuleStore, sandboxStore: suppliedSandboxStore, recentlyDeniedStore: suppliedRecentlyDeniedStore, terminalSetup: terminalSetupOverride, themeStore, initialThemeSettings, initialThemeLoadError, workspaceDirectoryResolver = resolveTuiWorkspaceDirectory, workspaceDirectoryCompleter = completeTuiWorkspaceDirectory, runtimeSettings: suppliedRuntimeSettings, runtimeSettingsTarget, notificationWriter, notificationDelayMs = 6_000, elicitationUrlOpener = openTuiUrl, releaseNotesLoader = (configRoot) => loadClaudeReleaseNotes({ configRoot }), settingSources, }) {
     const { exit, suspendTerminal, waitUntilRenderFlush } = useApp();
     const width = useTerminalWidth(terminalWidth);
     const rows = useTerminalRows();
@@ -1319,6 +1319,7 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                     kind: 'notice',
                     text: `MCP elicitation completed · ${event.mcpServerName}`,
                 });
+                serviceRef.current?.notify?.(sessionIdRef.current ?? undefined, `MCP elicitation completed · ${event.mcpServerName}`, 'elicitation_complete', 'Praxis');
                 if (elicitationUrlWaitingRef.current?.request.serverName ===
                     event.mcpServerName &&
                     elicitationUrlWaitingRef.current.request.elicitationId ===
@@ -1364,6 +1365,11 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
             : null;
         const editableRule = projected?.options.find((option) => option.editableRule)?.editableRule;
         let settled = false;
+        const notificationTimer = setTimeout(() => {
+            if (settled)
+                return;
+            serviceRef.current?.notify?.(sessionIdRef.current ?? undefined, `Approval required for ${call.name}`, 'permission_prompt', 'Praxis');
+        }, notificationDelayMs);
         const pending = {
             kind,
             call,
@@ -1372,6 +1378,7 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 if (settled)
                     return;
                 settled = true;
+                clearTimeout(notificationTimer);
                 if (permissionRef.current === pending)
                     permissionRef.current = null;
                 setPermission((current) => (current === pending ? null : current));
@@ -1388,12 +1395,20 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
     const approveTool = (call, _originalCall, decision) => requestApproval(call, 'tool', decision);
     const requestElicitation = (request) => new Promise((resolveResult) => {
         let settled = false;
+        const notificationTimer = setTimeout(() => {
+            if (settled)
+                return;
+            serviceRef.current?.notify?.(sessionIdRef.current ?? undefined, 'Praxis needs your input', request.mode === 'url'
+                ? 'elicitation_url_dialog'
+                : 'elicitation_dialog', 'Praxis');
+        }, notificationDelayMs);
         const pending = {
             request,
             resolve: (result, options) => {
                 if (settled)
                     return;
                 settled = true;
+                clearTimeout(notificationTimer);
                 if (elicitationRef.current === pending)
                     elicitationRef.current = null;
                 if (!options?.keepUrlDialog) {