Fix event bus async error handling, clear pending messages on session switch, improve SDK docs

- event-bus.ts: await async handlers to catch errors properly
- agent-session.ts: clear _pendingNextTurnMessages on newSession/switchSession/branch
- sdk.ts: make eventBus first (required) param for discoverHooks/discoverCustomTools
- docs/sdk.md: document eventBus sharing pattern for hook/tool communication

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

@@ -865,6 +865,7 @@ export class AgentSession {
 		this.sessionManager.newSession(options);
 		this._steeringMessages = [];
 		this._followUpMessages = [];
+		this._pendingNextTurnMessages = [];
 		this._reconnectToAgent();
 
 		// Emit session_switch event with reason "new" to hooks
@@ -1653,6 +1654,7 @@ export class AgentSession {
 		await this.abort();
 		this._steeringMessages = [];
 		this._followUpMessages = [];
+		this._pendingNextTurnMessages = [];
 
 		// Set new session
 		this.sessionManager.setSessionFile(sessionPath);
@@ -1728,6 +1730,9 @@ export class AgentSession {
 			skipConversationRestore = result?.skipConversationRestore ?? false;
 		}
 
+		// Clear pending messages (bound to old session state)
+		this._pendingNextTurnMessages = [];
+
 		if (!selectedEntry.parentId) {
 			this.sessionManager.newSession();
 		} else {

packages/coding-agent/src/core/event-bus.ts

@@ -16,9 +16,9 @@ export function createEventBus(): EventBusController {
 			emitter.emit(channel, data);
 		},
 		on: (channel, handler) => {
-			const safeHandler = (data: unknown) => {
+			const safeHandler = async (data: unknown) => {
 				try {
-					handler(data);
+					await handler(data);
 				} catch (err) {
 					console.error(`Event handler error (${channel}):`, err);
 				}

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

@@ -203,14 +203,14 @@ export function discoverModels(authStorage: AuthStorage, agentDir: string = getD
 
 /**
  * Discover hooks from cwd and agentDir.
+ * @param eventBus - Shared event bus for pi.events communication. Pass to createAgentSession too.
  * @param cwd - Current working directory
  * @param agentDir - Agent configuration directory
- * @param eventBus - Optional shared event bus (creates isolated bus if not provided)
  */
 export async function discoverHooks(
+	eventBus: EventBus,
 	cwd?: string,
 	agentDir?: string,
-	eventBus?: EventBus,
 ): Promise<Array<{ path: string; factory: HookFactory }>> {
 	const resolvedCwd = cwd ?? process.cwd();
 	const resolvedAgentDir = agentDir ?? getDefaultAgentDir();
@@ -230,14 +230,14 @@ export async function discoverHooks(
 
 /**
  * Discover custom tools from cwd and agentDir.
+ * @param eventBus - Shared event bus for tool.events communication. Pass to createAgentSession too.
  * @param cwd - Current working directory
  * @param agentDir - Agent configuration directory
- * @param eventBus - Optional shared event bus (creates isolated bus if not provided)
  */
 export async function discoverCustomTools(
+	eventBus: EventBus,
 	cwd?: string,
 	agentDir?: string,
-	eventBus?: EventBus,
 ): Promise<Array<{ path: string; tool: CustomTool }>> {
 	const resolvedCwd = cwd ?? process.cwd();
 	const resolvedAgentDir = agentDir ?? getDefaultAgentDir();