praxis-agent 0.24.0 → 0.24.1

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

@@ -161,6 +161,7 @@ export interface RewindPoint {
     fileRestoreAvailable: boolean;
 }
 export declare function workflowTokenTarget(prompt: string): number | null;
+export type HookSessionEndReason = 'clear' | 'resume' | 'other';
 export declare class ClaudeSessionService {
     private readonly options;
     private readonly schema;
@@ -182,6 +183,7 @@ export declare class ClaudeSessionService {
     private activeCostSessionId;
     private closeCostSavePromise;
     private readonly sessionMemoryControllers;
+    private readonly hookLifecycle;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
     nextScheduledPrompt(signal?: AbortSignal): Promise<ScheduledPrompt | null>;
@@ -198,6 +200,7 @@ export declare class ClaudeSessionService {
     stopTask(sessionId: string, taskId: string): Promise<void>;
     private applyPermissionUpdates;
     close(): Promise<void>;
+    transitionHookSession(sessionId: string, reason: Exclude<HookSessionEndReason, 'other'>): Promise<void>;
     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

@@ -319,6 +319,116 @@ function validSessionName(value) {
         ? name.toLocaleLowerCase()
         : null;
 }
+const SESSION_END_HOOK_TIMEOUT_MS = 15_000;
+class HookLifecycle {
+    hooks;
+    eventSink;
+    sessions = new Map();
+    pendingSource;
+    constructor(hooks, eventSink) {
+        this.hooks = hooks;
+        this.eventSink = eventSink;
+    }
+    async start(sessionId, input, fallbackSource, signal) {
+        let state = this.sessions.get(sessionId);
+        if (state?.started)
+            return undefined;
+        if (state?.starting)
+            return state.starting;
+        state = {
+            input,
+            started: false,
+            starting: undefined,
+            ending: undefined,
+        };
+        this.sessions.set(sessionId, state);
+        const source = this.pendingSource ?? fallbackSource;
+        this.pendingSource = undefined;
+        state.starting = this.hooks?.run({ ...input, hook_event_name: 'SessionStart', source }, source, signal);
+        try {
+            const outcome = await state.starting;
+            state.started = true;
+            return outcome;
+        }
+        catch (error) {
+            this.sessions.delete(sessionId);
+            throw error;
+        }
+        finally {
+            state.starting = undefined;
+        }
+    }
+    async refresh(sessionId, input, signal) {
+        const state = this.sessions.get(sessionId);
+        if (state)
+            state.input = input;
+        return this.hooks?.run({ ...input, hook_event_name: 'SessionStart', source: 'compact' }, 'compact', signal);
+    }
+    async transition(sessionId, reason) {
+        await this.end(sessionId, reason);
+        this.pendingSource = reason;
+    }
+    async end(sessionId, reason) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return;
+        if (state.starting)
+            await state.starting;
+        if (!state.started)
+            return;
+        if (state.ending)
+            return state.ending;
+        state.ending = this.runEnd(state.input, reason).finally(() => {
+            this.sessions.delete(sessionId);
+        });
+        await state.ending;
+    }
+    async close() {
+        await Promise.all([...this.sessions.keys()].map((sessionId) => this.end(sessionId, 'other')));
+    }
+    async runEnd(input, reason) {
+        if (!this.hooks)
+            return;
+        const controller = new AbortController();
+        let timer;
+        try {
+            const timeout = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`timed out after ${SESSION_END_HOOK_TIMEOUT_MS}ms`));
+                }, SESSION_END_HOOK_TIMEOUT_MS);
+            });
+            const outcome = await Promise.race([
+                this.hooks.run({ ...input, hook_event_name: 'SessionEnd', reason }, reason, controller.signal),
+                timeout,
+            ]);
+            for (const execution of outcome.executions) {
+                if (execution.exitCode === 0)
+                    continue;
+                const detail = execution.stderr.trim() ||
+                    execution.stdout.trim() ||
+                    `exit code ${execution.exitCode}`;
+                this.warn(detail);
+            }
+            if (outcome.blockedReason && outcome.executions.at(-1)?.exitCode === 0) {
+                this.warn(outcome.blockedReason);
+            }
+        }
+        catch (error) {
+            this.warn(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    warn(detail) {
+        this.eventSink?.({
+            type: 'warning',
+            message: `SessionEnd hook failed: ${detail}`,
+        });
+    }
+}
 export class ClaudeSessionService {
     options;
     schema;
@@ -340,9 +450,11 @@ export class ClaudeSessionService {
     activeCostSessionId;
     closeCostSavePromise;
     sessionMemoryControllers = new Map();
+    hookLifecycle;
     runtimeCwd;
     constructor(options) {
         this.options = options;
+        this.hookLifecycle = new HookLifecycle(options.hooks, options.eventSink);
         this.runtimeCwd = options.workspace?.cwd() ?? options.cwd;
         this.schema = selectClaudeSchemaAdapter(options.claudeVersion);
         this.scheduledPrompts =
@@ -481,6 +593,7 @@ export class ClaudeSessionService {
         }
     }
     async close() {
+        await this.hookLifecycle.close();
         this.scheduledPrompts?.close();
         await Promise.all([...this.hostedSubagents].map((executor) => executor.close()));
         await Promise.resolve();
@@ -494,6 +607,9 @@ export class ClaudeSessionService {
         this.mcpClosePromise ??= this.options.mcp?.close?.() ?? Promise.resolve();
         await this.mcpClosePromise;
     }
+    async transitionHookSession(sessionId, reason) {
+        await this.hookLifecycle.transition(sessionId, reason);
+    }
     createHostedToolRegistry(sessionId) {
         const baseTools = this.options.tools;
         if (!baseTools)
@@ -2243,17 +2359,11 @@ export class ClaudeSessionService {
                     }
                 },
             };
+            let turnCompleted = false;
             try {
-                if (this.options.hooks) {
-                    const outcome = await this.options.hooks.run({
-                        ...hookSession,
-                        hook_event_name: 'SessionStart',
-                        source: requireExisting ? 'resume' : 'startup',
-                    }, requireExisting ? 'resume' : 'startup', signal);
+                const outcome = await this.hookLifecycle.start(sessionId, hookSession, requireExisting ? 'resume' : 'startup', signal);
+                if (outcome) {
                     await recordHookOutcome(outcome, pendingRecoveryToolCallIds.size > 0);
-                    if (outcome.blockedReason) {
-                        throw new Error(`SessionStart hook error: ${outcome.blockedReason}`);
-                    }
                 }
                 const approveRecovery = this.options.approveRecovery;
                 const recoveryRequest = {
@@ -2620,15 +2730,9 @@ export class ClaudeSessionService {
                     // runtime-only context so the next request retains current
                     // instructions, plan state, session memory, and hook context.
                     if (this.options.hooks) {
-                        const outcome = await this.options.hooks.run({
-                            ...hookSession,
-                            hook_event_name: 'SessionStart',
-                            source: 'compact',
-                        }, 'compact', signal);
-                        await recordHookOutcome(outcome);
-                        if (outcome.blockedReason) {
-                            throw new Error(`SessionStart hook error: ${outcome.blockedReason}`);
-                        }
+                        const outcome = await this.hookLifecycle.refresh(sessionId, hookSession, signal);
+                        if (outcome)
+                            await recordHookOutcome(outcome);
                     }
                     await refreshRuntimeContext();
                     this.options.eventSink?.({
@@ -3057,6 +3161,7 @@ export class ClaudeSessionService {
                         });
                     }
                 }
+                turnCompleted = true;
                 return {
                     sessionId,
                     text: structuredCapture && structuredCapture.calls === 1
@@ -3074,35 +3179,8 @@ export class ClaudeSessionService {
                 };
             }
             finally {
-                try {
-                    const outcome = await this.options.hooks?.run({
-                        ...hookSession,
-                        hook_event_name: 'SessionEnd',
-                        reason: 'other',
-                    }, 'other');
-                    const failedExecutions = outcome?.executions.filter((execution) => execution.exitCode !== 0) ?? [];
-                    for (const execution of failedExecutions) {
-                        const detail = execution.stderr.trim() ||
-                            execution.stdout.trim() ||
-                            `exit code ${execution.exitCode}`;
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `SessionEnd hook failed: ${detail}`,
-                        });
-                    }
-                    if (outcome?.blockedReason &&
-                        outcome.executions.at(-1)?.exitCode === 0) {
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `SessionEnd hook failed: ${outcome.blockedReason}`,
-                        });
-                    }
-                }
-                catch (error) {
-                    this.options.eventSink?.({
-                        type: 'warning',
-                        message: `SessionEnd hook failed: ${error instanceof Error ? error.message : String(error)}`,
-                    });
+                if (!turnCompleted) {
+                    await this.hookLifecycle.end(sessionId, 'other');
                 }
             }
         });

package/dist/cli/interactive.d.ts

@@ -72,6 +72,7 @@ interface InteractiveSessionCommands {
         id: string;
         prompt: string;
     } | null>;
+    transitionHookSession?(sessionId: string, reason: 'clear' | 'resume'): Promise<void>;
     close?(): Promise<void>;
 }
 export interface InteractiveServiceFactory {

package/dist/cli/interactive.js

@@ -3435,9 +3435,16 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
         if (selectingSession) {
             if (key.escape || value === '\u001B') {
                 if (pickerIncludesNewSessionRef.current && allowNewSession) {
-                    setSessionId(null);
-                    setPendingFork(false);
                     setSelectingSession(false);
+                    const previousSessionId = sessionIdRef.current;
+                    void (async () => {
+                        if (previousSessionId) {
+                            const commands = await service();
+                            await commands.transitionHookSession?.(previousSessionId, 'clear');
+                        }
+                        openSession(null);
+                        setPendingFork(false);
+                    })().catch(warn);
                 }
                 else if (allowNewSession) {
                     setSelectingSession(false);
@@ -3462,10 +3469,18 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 const selected = filterSessionChoices(currentPickerChoices, sessionSearchRef.current)[selectedIndexRef.current];
                 if (selected === undefined)
                     return;
-                openSession(selected?.sessionId ?? null);
-                if (!selected)
-                    setPendingFork(false);
                 setSelectingSession(false);
+                const nextSessionId = selected?.sessionId ?? null;
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId && previousSessionId !== nextSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, nextSessionId === null ? 'clear' : 'resume');
+                    }
+                    openSession(nextSessionId);
+                    if (!selected)
+                        setPendingFork(false);
+                })().catch(warn);
             }
             else if (key.backspace || key.delete) {
                 sessionSearchRef.current = sessionSearchRef.current.slice(0, -1);
@@ -5220,28 +5235,40 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 updateMenu({ kind: 'help', tabIndex: 0, selectedIndex: 0 });
             }
             else if (prompt === '/new') {
-                statusLineSessionId.current = randomUUID();
-                setSessionId(null);
-                setSessionColor(undefined);
-                setPendingFork(false);
-                append({ kind: 'notice', text: 'Started a new session.' });
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, 'clear');
+                    }
+                    statusLineSessionId.current = randomUUID();
+                    openSession(null);
+                    setPendingFork(false);
+                    append({ kind: 'notice', text: 'Started a new session.' });
+                })().catch(warn);
             }
             else if (prompt === '/clear') {
-                statusLineSessionId.current = randomUUID();
-                setSessionId(null);
-                setSessionColor(undefined);
-                setPendingFork(false);
-                setHistory([]);
-                setUsage(undefined);
-                setCostUsd(undefined);
-                streamingFrameRef.current?.resetText();
-                streamingFrameRef.current?.resetThinking();
-                streamingFrameRef.current?.flush();
-                setThinkingExpanded(false);
-                setStatus('ready');
-                inputHistoryRef.current = [];
-                inputHistoryIndexRef.current = null;
-                inputHistoryDraftRef.current = '';
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, 'clear');
+                    }
+                    statusLineSessionId.current = randomUUID();
+                    openSession(null);
+                    setPendingFork(false);
+                    setHistory([]);
+                    setUsage(undefined);
+                    setCostUsd(undefined);
+                    streamingFrameRef.current?.resetText();
+                    streamingFrameRef.current?.resetThinking();
+                    streamingFrameRef.current?.flush();
+                    setThinkingExpanded(false);
+                    setStatus('ready');
+                    inputHistoryRef.current = [];
+                    inputHistoryIndexRef.current = null;
+                    inputHistoryDraftRef.current = '';
+                })().catch(warn);
             }
             else if (prompt === '/model') {
                 updateMenu({ kind: 'model', selectedIndex: 0 });

package/dist/cli-runtime.js

@@ -1577,6 +1577,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             rename: (sessionId, name) => service.rename(sessionId, name),
             sessionNameSuggestion: (sessionId, signal) => service.sessionNameSuggestion(sessionId, signal),
             nextScheduledPrompt: (signal) => service.nextScheduledPrompt(signal),
+            transitionHookSession: (sessionId, reason) => service.transitionHookSession(sessionId, reason),
             close: async () => {
                 let failure;
                 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",