Replace custom tool dispose() with shutdown session event

Breaking change: CustomAgentTool.dispose() removed. Use onSession with
reason 'shutdown' instead for cleanup.

- Add 'shutdown' to SessionEvent.reason for custom tools
- Remove dispose() method from CustomAgentTool interface
- Make emitToolSessionEvent() public on AgentSession
- Emit shutdown event to tools in InteractiveMode.shutdown()
- Update custom-tools.md with new API and examples

packages/coding-agent/src/core/agent-session.ts

@@ -698,7 +698,7 @@ export class AgentSession {
 		}
 
 		// Emit session event to custom tools
-		await this._emitToolSessionEvent("new", previousSessionFile);
+		await this.emitToolSessionEvent("new", previousSessionFile);
 		return true;
 	}
 
@@ -1473,7 +1473,7 @@ export class AgentSession {
 		}
 
 		// Emit session event to custom tools
-		await this._emitToolSessionEvent("switch", previousSessionFile);
+		await this.emitToolSessionEvent("switch", previousSessionFile);
 
 		this.agent.replaceMessages(sessionContext.messages);
 
@@ -1550,7 +1550,7 @@ export class AgentSession {
 		}
 
 		// Emit session event to custom tools (with reason "branch")
-		await this._emitToolSessionEvent("branch", previousSessionFile);
+		await this.emitToolSessionEvent("branch", previousSessionFile);
 
 		if (!skipConversationRestore) {
 			this.agent.replaceMessages(sessionContext.messages);
@@ -1720,7 +1720,7 @@ export class AgentSession {
 		}
 
 		// Emit to custom tools
-		await this._emitToolSessionEvent("tree", this.sessionFile);
+		await this.emitToolSessionEvent("tree", this.sessionFile);
 
 		this._branchSummaryAbortController = undefined;
 		return { editorText, cancelled: false, summaryEntry };
@@ -1875,11 +1875,11 @@ export class AgentSession {
 
 	/**
 	 * Emit session event to all custom tools.
-	 * Called on session switch, branch, and clear.
+	 * Called on session switch, branch, tree navigation, and shutdown.
 	 */
-	private async _emitToolSessionEvent(
+	async emitToolSessionEvent(
 		reason: ToolSessionEvent["reason"],
-		previousSessionFile: string | undefined,
+		previousSessionFile?: string | undefined,
 	): Promise<void> {
 		const event: ToolSessionEvent = {
 			entries: this.sessionManager.getEntries(),

packages/coding-agent/src/core/custom-tools/types.ts

@@ -40,10 +40,10 @@ export interface SessionEvent {
 	entries: SessionEntry[];
 	/** Current session file path, or undefined in --no-session mode */
 	sessionFile: string | undefined;
-	/** Previous session file path, or undefined for "start" and "new" */
+	/** Previous session file path, or undefined for "start", "new", and "shutdown" */
 	previousSessionFile: string | undefined;
 	/** Reason for the session event */
-	reason: "start" | "switch" | "branch" | "new" | "tree";
+	reason: "start" | "switch" | "branch" | "new" | "tree" | "shutdown";
 }
 
 /** Rendering options passed to renderResult */
@@ -85,14 +85,12 @@ export interface RenderResultOptions {
  */
 export interface CustomAgentTool<TParams extends TSchema = TSchema, TDetails = any>
 	extends AgentTool<TParams, TDetails> {
-	/** Called on session start/switch/branch/clear - use to reconstruct state from entries */
+	/** Called on session lifecycle events - use to reconstruct state or cleanup resources */
 	onSession?: (event: SessionEvent) => void | Promise<void>;
 	/** Custom rendering for tool call display - return a Component */
 	renderCall?: (args: Static<TParams>, theme: Theme) => Component;
 	/** Custom rendering for tool result display - return a Component */
 	renderResult?: (result: AgentToolResult<TDetails>, options: RenderResultOptions, theme: Theme) => Component;
-	/** Called when session ends - cleanup resources */
-	dispose?: () => Promise<void> | void;
 }
 
 /** Factory function that creates a custom tool or array of tools */

packages/coding-agent/src/modes/interactive/interactive-mode.ts

@@ -1239,7 +1239,7 @@ export class InteractiveMode {
 
 	/**
 	 * Gracefully shutdown the agent.
-	 * Emits shutdown event to hooks, then exits.
+	 * Emits shutdown event to hooks and tools, then exits.
 	 */
 	private async shutdown(): Promise<void> {
 		// Emit shutdown event to hooks
@@ -1250,6 +1250,9 @@ export class InteractiveMode {
 			});
 		}
 
+		// Emit shutdown event to custom tools
+		await this.session.emitToolSessionEvent("shutdown");
+
 		this.stop();
 		process.exit(0);
 	}