feat(hooks): fire remaining lifecycle events; harden session save + child env

Wires the four declared-but-not-firing hook events through HookManager
so user-defined hooks see the full lifecycle:

  UserPromptSubmit  via bundle.submitUserPrompt, called from App.tsx /
                    headless run / plan-mode approve / /redo. Exit-code-2
                    veto bubbles back as { submitted: false, reason }.
  SessionStart      once per createAgent — lets hooks pre-seed context.
  Stop              fires on agent_end with the final assistant text —
                    "ping my phone when this finishes" style hooks.
  PostEdit          fires from afterToolCall for write-family tools so
                    formatters / linters / commit-on-save can target
                    edits specifically.

Also fixes two audit-flagged silent-failure / mutation bugs:

  - Session save errors now surface to stderr instead of vanishing, so a
    full disk no longer loses work without warning. Adds a workDir-
    exists check on load so a deleted/moved project refuses to resume
    instead of re-anchoring the session to a bogus path.
  - child_process spawns in hooks/runner.ts + tools/shell.ts now clone
    process.env instead of passing the reference, so a tool / hook that
    does `export FOO=bar` can't leak into every subsequent spawn.

Author: halfaipg

src/agent/agent.ts

@@ -98,6 +98,12 @@ export interface AgentBundle {
 	hooks: HookManager;
 	diagnostics: DiagnosticsEngine;
 	subscribe: (listener: (event: AgentEvent) => void) => () => void;
+	/**
+	 * User-initiated prompt — fires UserPromptSubmit hooks; honors exit-code-2
+	 * veto. Callers that originate prompts from real user input should use
+	 * this instead of `agent.prompt()` directly.
+	 */
+	submitUserPrompt: (text: string) => Promise<{ submitted: boolean; reason?: string }>;
 	/**
 	 * Set when `--resume` actually loaded a prior session, with its
 	 * timestamp + message count so the welcome banner can say
@@ -279,6 +285,18 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 				signal,
 			);
 
+			// PostEdit fires for write-family tools so hooks can run formatters
+			// / linters / commit-on-save scripts targeted specifically at file
+			// mutations (instead of having to filter inside a generic
+			// PostToolUse handler).
+			if (filePath && WRITE_TOOL_NAMES.has(ctx.toolCall.name)) {
+				await hooks.dispatch(
+					"PostEdit",
+					{ event: "PostEdit", toolName: ctx.toolCall.name, toolArgs: ctx.args, filePath, workingDir: cwd },
+					signal,
+				);
+			}
+
 			// After a write/edit tool, run language checkers on the affected file
 			// and steer the result into the next turn. Fire-and-forget so the
 			// tool result return isn't blocked by a 15s checker run.
@@ -340,11 +358,52 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 				},
 			});
-		} catch {
-			// Persistence is best-effort — don't crash the agent over a write failure.
+		} catch (err) {
+			// Persistence is best-effort — never crash the agent over a write
+			// failure. But silent failure used to mean the user lost work to
+			// a full disk with no warning, so surface to stderr so support is
+			// possible. Visible to anyone watching the terminal; the agent
+			// keeps running.
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[session] save failed (${sessions.filePath}): ${msg}\n`);
 		}
+
+		// Stop fires once the agent settles after a turn — useful for "ping
+		// my phone when the long task finishes" style hooks. Fire-and-forget
+		// so a misconfigured hook can't gate the agent_end notification.
+		const finalMessage = lastAssistantText(event.messages);
+		void hooks.dispatch("Stop", { event: "Stop", workingDir: cwd, finalMessage }).catch(() => undefined);
 	});
 
+	// SessionStart fires once per createAgent. Lets hooks pre-seed context
+	// (e.g. "add project status to memory") before any user prompt lands.
+	// Fire-and-forget because nothing else is waiting on it.
+	void hooks.dispatch("SessionStart", { event: "SessionStart", workingDir: cwd }).catch(() => undefined);
+
+	/**
+	 * Submit a user-initiated prompt — fires UserPromptSubmit through the
+	 * hook chain first so audit / lint hooks can veto with exit code 2.
+	 * Subagent prompts (dispatch-agent) skip this and call agent.prompt
+	 * directly because they aren't user-initiated.
+	 *
+	 * Returns `{ submitted: false, reason }` when a sync hook blocked the
+	 * submit, otherwise resolves to `{ submitted: true }` after the agent
+	 * accepted the prompt. The agent's own turn lifecycle still emits
+	 * events on bundle.subscribe.
+	 */
+	const submitUserPrompt = async (text: string): Promise<{ submitted: boolean; reason?: string }> => {
+		const outcome = await hooks.dispatch("UserPromptSubmit", {
+			event: "UserPromptSubmit",
+			workingDir: cwd,
+			userPrompt: text,
+		});
+		if (outcome.blocked) {
+			return { submitted: false, reason: outcome.reason };
+		}
+		void agent.prompt(text).catch(() => undefined);
+		return { submitted: true };
+	};
+
 	void agentRef;
 	return {
 		agent,
@@ -362,8 +421,27 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 		hooks,
 		diagnostics,
 		subscribe,
+		submitUserPrompt,
 		resumedFrom: resumed ? { updatedAt: resumed.updatedAt, messageCount: resumed.messages.length } : undefined,
 		resumedMessages: opts.initialMessages ?? resumed?.messages ?? [],
 		backgroundShells: toolContext.backgroundShells,
 	};
 }
+
+/** Extract the trailing assistant text content from an array of messages. */
+function lastAssistantText(messages: AgentMessage[]): string | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m.role !== "assistant") continue;
+		if (typeof m.content === "string") return m.content || undefined;
+		if (Array.isArray(m.content)) {
+			const text = m.content
+				.filter((b): b is { type: "text"; text: string } => (b as { type: string }).type === "text")
+				.map((b) => b.text)
+				.join("");
+			return text || undefined;
+		}
+		return undefined;
+	}
+	return undefined;
+}

src/commands/builtins.ts

@@ -686,7 +686,12 @@ const redo: Command = {
 			return { handled: true };
 		}
 		ctx.emit(`(redo) ${text.slice(0, 80)}${text.length > 80 ? "…" : ""}`);
-		void ctx.bundle.agent.prompt(text).catch(() => undefined);
+		// Route through the bundle helper so UserPromptSubmit hooks fire on
+		// /redo too — a hook that rejects secrets shouldn't be bypassed just
+		// because the same prompt is being re-issued.
+		void ctx.bundle.submitUserPrompt(text).then((result) => {
+			if (!result.submitted && result.reason) ctx.emit(`Prompt blocked by hook: ${result.reason}`);
+		});
 		return { handled: true };
 	},
 };

src/headless/run.ts

@@ -97,7 +97,15 @@ export async function runHeadless(opts: HeadlessOptions): Promise<number> {
 	}
 
 	try {
-		await bundle.agent.prompt(opts.prompt);
+		// Route through the bundle helper so UserPromptSubmit hooks fire on
+		// headless runs too (CI scripts, scheduled jobs). A hook veto exits
+		// with code 1 and the reason printed to stderr.
+		const submitResult = await bundle.submitUserPrompt(opts.prompt);
+		if (!submitResult.submitted) {
+			errored = true;
+			errorMessage = submitResult.reason ?? "Prompt blocked by hook.";
+			err(`prompt blocked: ${errorMessage}\n`);
+		}
 	} catch (e) {
 		errored = true;
 		errorMessage = e instanceof Error ? e.message : String(e);

src/hooks/runner.ts

@@ -24,7 +24,10 @@ export function runHook(config: HookConfig, context: HookEventContext, signal?:
 			child = spawn(config.command, {
 				shell: true,
 				cwd: context.workingDir,
-				env: process.env,
+				// Clone instead of passing process.env directly — a hook that
+				// does `export FOO=bar` would otherwise mutate the agent's
+				// own environment for every subsequent spawn.
+				env: { ...process.env },
 				stdio: ["pipe", "pipe", "pipe"],
 			});
 		} catch (err) {

src/hooks/types.ts

@@ -54,6 +54,14 @@ export interface HookEventContext {
 	subagentPrompt?: string;
 	/** SubagentStop only — was the subagent run successful? */
 	subagentSuccess?: boolean;
+
+	// UserPromptSubmit-specific:
+	/** UserPromptSubmit — the raw text the user submitted. Hooks can reject with exit 2. */
+	userPrompt?: string;
+
+	// Stop-specific:
+	/** Stop — the agent's final message text (last assistant message), if any. */
+	finalMessage?: string;
 }
 
 export interface HookResult {

src/plan/run-flow.ts

@@ -62,9 +62,15 @@ export async function runPlanFlow(
 			if (choice === "Yes — run it") {
 				const finalPrompt = buildAgentPrompt(originalPrompt, plan, qaHistory);
 				const withEnv = envReminderForFirstTurn ? `${envReminderForFirstTurn}\n\n${finalPrompt}` : finalPrompt;
-				bundle.agent.prompt(withEnv).catch((err: unknown) => {
-					onError(err instanceof Error ? err.message : String(err));
-				});
+				// Plan-mode "approve" is a user decision, so the final prompt
+				// goes through the UserPromptSubmit hook surface like any
+				// other user-initiated submit.
+				bundle
+					.submitUserPrompt(withEnv)
+					.then((result) => {
+						if (!result.submitted && result.reason) onError(`Hook blocked plan: ${result.reason}`);
+					})
+					.catch((err: unknown) => onError(err instanceof Error ? err.message : String(err)));
 				return;
 			}
 			if (choice === "Cancel") {

src/sessions/store.ts

@@ -71,6 +71,15 @@ export class SessionStore {
 
 		if (parsed.formatVersion !== SESSION_FORMAT_VERSION) return null;
 		if (parsed.workDir !== this.cwd) return null;
+		// If the project directory the session belongs to has been deleted /
+		// renamed since the save, refuse to resume rather than re-anchoring
+		// the session to a now-invalid path. The file stays on disk so a
+		// future fix can migrate it intentionally.
+		try {
+			if (!statSync(parsed.workDir).isDirectory()) return null;
+		} catch {
+			return null;
+		}
 		if (parsed.modelId !== modelId) return null;
 		if (Date.now() - parsed.updatedAt > this.maxAgeMs) {
 			this.clear();

src/tools/shell.ts

@@ -111,7 +111,10 @@ export function createShell(ctx: ToolContext): AgentTool<typeof Params, ShellDet
 			const child: ChildProcess = spawn(params.command, {
 				shell: true,
 				cwd,
-				env: process.env,
+				// Clone instead of passing process.env directly — a shell
+				// command that does `export FOO=bar` would otherwise leak
+				// into the agent's own environment for every subsequent spawn.
+				env: { ...process.env },
 				stdio: ["ignore", "pipe", "pipe"],
 				detached: process.platform !== "win32",
 			});

src/ui/App.tsx

@@ -311,9 +311,20 @@ function ChatApp({ initialBundle, onExit }: ChatAppProps) {
 		const promptText = shouldInjectEnv(state.messages)
 			? `${buildEnvironmentReminder(bundle.toolContext.cwd)}\n\n${augmentedText}`
 			: augmentedText;
-		bundle.agent.prompt(promptText).catch((err: unknown) => {
-			dispatch({ type: "error", message: err instanceof Error ? err.message : String(err) });
-		});
+		// Use the bundle's user-prompt helper so a UserPromptSubmit hook
+		// can veto the submit (e.g. project policy blocking secrets in
+		// prompts). A blocked submit surfaces the hook's stderr as a
+		// status line; we never silently swallow it.
+		bundle
+			.submitUserPrompt(promptText)
+			.then((result) => {
+				if (!result.submitted && result.reason) {
+					appendStatus(`Prompt blocked by hook: ${result.reason}`);
+				}
+			})
+			.catch((err: unknown) => {
+				dispatch({ type: "error", message: err instanceof Error ? err.message : String(err) });
+			});
 	};
 
 	handleSubmitRef.current = handleSubmit;