@namzu/sdk 0.1.4 → 0.1.5-rc.1

package/src/constants/agent/index.ts

@@ -1,4 +1,4 @@
-import type { AgentCapabilities } from '../../types/agent/index.js'
+import type { AgentCapabilities } from '../../types/agent/base.js'
 import type { AgentManagerConfig } from '../../types/agent/task.js'
 
 export const MAX_RECENT_ACTIVITIES = 5

package/src/gateway/local.ts

@@ -1,13 +1,15 @@
-import type { AgentManager } from '../manager/agent/lifecycle.js'
 import type { AgentInput } from '../types/agent/base.js'
 import type { CreateTaskOptions, TaskGateway, TaskHandle } from '../types/agent/gateway.js'
+import type { AgentManagerContract } from '../types/agent/manager.js'
 import type { AgentTaskContext } from '../types/agent/task.js'
 import type { TaskId } from '../types/ids/index.js'
 import { createUserMessage } from '../types/message/index.js'
 import type { RunEventListener } from '../types/run/events.js'
+import { toErrorMessage } from '../utils/error.js'
+import { getRootLogger } from '../utils/logger.js'
 
 export class LocalTaskGateway implements TaskGateway {
-	private agentManager: AgentManager
+	private agentManager: AgentManagerContract
 	private taskContext: AgentTaskContext
 	private listener: RunEventListener | undefined
 	private trackedTaskIds: Set<TaskId> = new Set()
@@ -17,7 +19,7 @@ export class LocalTaskGateway implements TaskGateway {
 	private completionListeners: Set<(handle: TaskHandle) => void> = new Set()
 
 	constructor(
-		agentManager: AgentManager,
+		agentManager: AgentManagerContract,
 		taskContext: AgentTaskContext,
 		listener?: RunEventListener,
 		parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides'>,
@@ -56,7 +58,14 @@ export class LocalTaskGateway implements TaskGateway {
 					}
 				}
 			})
-			.catch(() => {})
+			.catch((err) => {
+				getRootLogger()
+					.child({ component: 'LocalTaskGateway' })
+					.error('Task completion tracking failed', {
+						taskId: task.taskId,
+						error: toErrorMessage(err),
+					})
+			})
 
 		return toHandle(task)
 	}

package/src/index.ts

@@ -43,6 +43,8 @@ export * from './types/advisory/index.js'
 export * from './types/memory/index.js'
 export * from './types/plugin/index.js'
 export * from './types/sandbox/index.js'
+export * from './types/structured-output/index.js'
+export * from './types/invocation/index.js'
 
 export {
 	AdvisorRegistry,
@@ -106,8 +108,10 @@ export {
 	RouterAgent,
 	SupervisorAgent,
 	defineAgent,
+	InvocationLock,
+	ConcurrentInvocationError,
 } from './agents/index.js'
-export type { DefineAgentOptions } from './agents/index.js'
+export type { DefineAgentOptions, ConcurrencyMode, Disposable } from './agents/index.js'
 
 export { InMemoryStore } from './store/InMemoryStore.js'
 export type { Identifiable, Timestamped } from './store/InMemoryStore.js'
@@ -184,9 +188,16 @@ export type { ToolExecutionResult } from './registry/tool/execute.js'
 export { getBuiltinTools } from './tools/builtins/index.js'
 export { ReadFileTool } from './tools/builtins/read-file.js'
 export { WriteFileTool } from './tools/builtins/write-file.js'
+export { EditTool } from './tools/builtins/edit.js'
 export { BashTool } from './tools/builtins/bash.js'
 export { GlobTool } from './tools/builtins/glob.js'
+export { GrepTool } from './tools/builtins/grep.js'
+export { LsTool } from './tools/builtins/ls.js'
 export { SearchToolsTool } from './tools/builtins/search-tools.js'
+export {
+	createStructuredOutputTool,
+	STRUCTURED_OUTPUT_TOOL_NAME,
+} from './tools/builtins/structuredOutput.js'
 
 export {
 	TextChunker,
@@ -280,6 +291,23 @@ export {
 } from './bridge/sse/index.js'
 export type { MappedStreamEvent } from './bridge/sse/index.js'
 
+export {
+	AgentBus,
+	CircuitBreaker,
+	FileLockManager,
+	EditOwnershipTracker,
+} from './bus/index.js'
+export type { AgentBusConfig } from './bus/index.js'
+
+export { VerificationGate, evaluateRule } from './verification/index.js'
+export type { ToolCallContext } from './verification/index.js'
+
+export { buildCoordinatorTools } from './tools/coordinator/index.js'
+export type { CoordinatorToolsOptions, TaskLaunchedCallback } from './tools/coordinator/index.js'
+
+export { checkLimitsDetailed, buildLimitConfig } from './run/LimitChecker.js'
+export type { LimitCheckerState, LimitCheckResult } from './run/LimitChecker.js'
+
 export { InMemoryCredentialVault } from './vault/index.js'
 
 export {
@@ -301,6 +329,13 @@ export {
 	extractFromUserMessage,
 	extractFromAssistantMessage,
 	buildVerifiedSummary,
+	findDanglingMessages,
+	removeDanglingMessages,
+	findSafeTrimIndex,
+	NullManager,
+	SlidingWindowManager,
+	StructuredCompactionManager,
+	createConversationManager,
 } from './compaction/index.js'
 export type {
 	WorkingState,
@@ -309,4 +344,6 @@ export type {
 	FileAction,
 	ToolResultSlot,
 	CompactionStrategy,
+	DanglingResult,
+	ConversationManager,
 } from './compaction/index.js'

package/src/manager/agent/lifecycle.ts

@@ -1,3 +1,5 @@
+import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
+import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import type { AgentRegistry } from '../../registry/agent/definitions.js'
 import type { BaseAgentConfig, BaseAgentResult } from '../../types/agent/base.js'
 import type {
@@ -11,8 +13,7 @@ import type {
 	AgentTaskState,
 	SendMessageOptions,
 } from '../../types/agent/task.js'
-import { AGENT_MANAGER_DEFAULTS, isTerminalAgentTaskState } from '../../types/agent/task.js'
-import { EMPTY_TOKEN_USAGE } from '../../types/common/index.js'
+import { isTerminalAgentTaskState } from '../../types/agent/task.js'
 import type { RunId, TaskId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
 import { createChildAbortController } from '../../utils/abort.js'

package/src/manager/run/persistence.ts

@@ -1,15 +1,10 @@
+import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { RunDiskStore } from '../../store/run/disk.js'
-import {
-	type CostInfo,
-	EMPTY_TOKEN_USAGE,
-	type TokenUsage,
-	accumulateTokenUsage,
-} from '../../types/common/index.js'
+import { type CostInfo, type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { AssistantMessage, Message } from '../../types/message/index.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
-import type { AgentRun, StopReason } from '../../types/run/index.js'
-import type { RunPersistenceConfig } from '../../types/run/index.js'
+import type { AgentRun, RunPersistenceConfig, StopReason } from '../../types/run/index.js'
 import { type ModelPricing, ZERO_COST, accumulateCost } from '../../utils/cost.js'
 import { generateEmergencySaveId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'

package/src/plugin/__tests__/lifecycle.test.ts

@@ -0,0 +1,430 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { PluginRegistry } from '../../registry/plugin/index.js'
+import type { PluginId, RunId } from '../../types/ids/index.js'
+import type { PluginHookContext, PluginHookResult } from '../../types/plugin/index.js'
+import type { ToolRegistryContract } from '../../types/tool/index.js'
+import type { Logger } from '../../utils/logger.js'
+import { PluginLifecycleManager } from '../lifecycle.js'
+
+describe('PluginLifecycleManager', () => {
+	let manager: PluginLifecycleManager
+	let pluginRegistry: PluginRegistry
+	let toolRegistry: ToolRegistryContract
+	let logger: Logger
+
+	const mockRunId = 'run_test' as RunId
+	const mockPluginId = 'plugin_test' as PluginId
+
+	beforeEach(() => {
+		// Create mock registries and logger
+		pluginRegistry = {
+			register: vi.fn(),
+			unregister: vi.fn(),
+			getOrThrow: vi.fn(),
+			findByName: vi.fn(),
+			getAll: vi.fn(() => []),
+		} as any
+
+		toolRegistry = {
+			register: vi.fn(),
+			unregister: vi.fn(),
+			execute: vi.fn(),
+			getAll: vi.fn(() => []),
+		} as any
+
+		logger = {
+			child: vi.fn(() => ({
+				info: vi.fn(),
+				warn: vi.fn(),
+				error: vi.fn(),
+				debug: vi.fn(),
+			})),
+			info: vi.fn(),
+			warn: vi.fn(),
+			error: vi.fn(),
+			debug: vi.fn(),
+		} as any
+
+		manager = new PluginLifecycleManager({
+			pluginRegistry,
+			toolRegistry,
+			log: logger,
+			hookTimeoutMs: 5000,
+		})
+	})
+
+	describe('executeHooks', () => {
+		it('should return empty array when no hooks registered', async () => {
+			const results = await manager.executeHooks('run_start', { runId: mockRunId })
+			expect(results).toEqual([])
+		})
+
+		it('should execute all registered hooks for an event', async () => {
+			const hook1Handler = vi.fn(async (): Promise<PluginHookResult> => ({ action: 'continue' }))
+			const hook2Handler = vi.fn(async (): Promise<PluginHookResult> => ({ action: 'continue' }))
+
+			// Register hooks manually
+			manager['hookHandlers'].set('run_start', [
+				{ pluginId: 'plugin_1' as PluginId, handler: hook1Handler },
+				{ pluginId: 'plugin_2' as PluginId, handler: hook2Handler },
+			])
+
+			const results = await manager.executeHooks('run_start', { runId: mockRunId })
+
+			expect(results).toHaveLength(2)
+			expect(hook1Handler).toHaveBeenCalled()
+			expect(hook2Handler).toHaveBeenCalled()
+		})
+
+		it('should handle hook timeout', async () => {
+			const slowHandler = vi.fn(
+				() =>
+					new Promise<PluginHookResult>((resolve) => {
+						setTimeout(() => resolve({ action: 'continue' }), 10000)
+					}),
+			)
+
+			manager['hookHandlers'].set('run_start', [{ pluginId: mockPluginId, handler: slowHandler }])
+
+			const managerWithShortTimeout = new PluginLifecycleManager({
+				pluginRegistry,
+				toolRegistry,
+				log: logger,
+				hookTimeoutMs: 10, // Very short timeout
+			})
+
+			managerWithShortTimeout['hookHandlers'].set('run_start', [
+				{ pluginId: mockPluginId, handler: slowHandler },
+			])
+
+			const results = await managerWithShortTimeout.executeHooks('run_start', {
+				runId: mockRunId,
+			})
+
+			expect(results).toHaveLength(1)
+			expect(results[0]?.action).toBe('error')
+			if (results[0]?.action === 'error') {
+				expect(results[0].message).toContain('timeout')
+			}
+		})
+
+		describe('Hook ordering semantics', () => {
+			it('should execute pre_* hooks in registration order (first registered first)', async () => {
+				const executionOrder: string[] = []
+
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook1')
+					return { action: 'continue' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook2')
+					return { action: 'continue' }
+				})
+
+				const handler3 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook3')
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('pre_tool_use', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+					{ pluginId: 'plugin_3' as PluginId, handler: handler3 },
+				])
+
+				await manager.executeHooks('pre_tool_use', { runId: mockRunId })
+
+				expect(executionOrder).toEqual(['hook1', 'hook2', 'hook3'])
+			})
+
+			it('should execute post_* hooks in reverse registration order (last registered first)', async () => {
+				const executionOrder: string[] = []
+
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook1')
+					return { action: 'continue' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook2')
+					return { action: 'continue' }
+				})
+
+				const handler3 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook3')
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('post_tool_use', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+					{ pluginId: 'plugin_3' as PluginId, handler: handler3 },
+				])
+
+				await manager.executeHooks('post_tool_use', { runId: mockRunId })
+
+				// Reverse order: hook3 -> hook2 -> hook1
+				expect(executionOrder).toEqual(['hook3', 'hook2', 'hook1'])
+			})
+
+			it('should execute non-pre/post hooks in registration order', async () => {
+				const executionOrder: string[] = []
+
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook1')
+					return { action: 'continue' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					executionOrder.push('hook2')
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('run_start', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+				])
+
+				await manager.executeHooks('run_start', { runId: mockRunId })
+
+				expect(executionOrder).toEqual(['hook1', 'hook2'])
+			})
+		})
+
+		describe('Flow control: action priority', () => {
+			it('should short-circuit on error action', async () => {
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'error', message: 'Hook failed' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('run_start', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+				])
+
+				const results = await manager.executeHooks('run_start', { runId: mockRunId })
+
+				expect(results).toHaveLength(1)
+				expect(results[0]?.action).toBe('error')
+				expect(handler2).not.toHaveBeenCalled()
+			})
+
+			it('should short-circuit on skip action', async () => {
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'skip', reason: 'Condition not met' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('pre_tool_use', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+				])
+
+				const results = await manager.executeHooks('pre_tool_use', { runId: mockRunId })
+
+				expect(results).toHaveLength(1)
+				expect(results[0]?.action).toBe('skip')
+				expect(handler2).not.toHaveBeenCalled()
+			})
+
+			it('should short-circuit and return resume action', async () => {
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'resume', input: 'new_input_value' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('pre_llm_call', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+				])
+
+				const results = await manager.executeHooks('pre_llm_call', { runId: mockRunId })
+
+				expect(results).toHaveLength(1)
+				expect(results[0]?.action).toBe('resume')
+				if (results[0]?.action === 'resume') {
+					expect(results[0].input).toBe('new_input_value')
+				}
+				expect(handler2).not.toHaveBeenCalled()
+			})
+
+			it('should short-circuit and return retry action', async () => {
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'retry' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				// Use pre_* hook for forward execution order (plugin_1 runs first and short-circuits).
+				// post_* hooks run in reverse order for cleanup semantics.
+				manager['hookHandlers'].set('pre_llm_call', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+				])
+
+				const results = await manager.executeHooks('pre_llm_call', { runId: mockRunId })
+
+				expect(results).toHaveLength(1)
+				expect(results[0]?.action).toBe('retry')
+				expect(handler2).not.toHaveBeenCalled()
+			})
+
+			it('should continue executing on modify action', async () => {
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'modify', input: { updated: true } }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('pre_tool_use', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+				])
+
+				const results = await manager.executeHooks('pre_tool_use', { runId: mockRunId })
+
+				expect(results).toHaveLength(2)
+				expect(results[0]?.action).toBe('modify')
+				expect(results[1]?.action).toBe('continue')
+				expect(handler2).toHaveBeenCalled()
+			})
+
+			it('should continue executing on continue action', async () => {
+				const handler1 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				const handler2 = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('iteration_start', [
+					{ pluginId: 'plugin_1' as PluginId, handler: handler1 },
+					{ pluginId: 'plugin_2' as PluginId, handler: handler2 },
+				])
+
+				const results = await manager.executeHooks('iteration_start', { runId: mockRunId })
+
+				expect(results).toHaveLength(2)
+				expect(handler1).toHaveBeenCalled()
+				expect(handler2).toHaveBeenCalled()
+			})
+		})
+
+		describe('Hook context', () => {
+			it('should pass correct context to hook handler', async () => {
+				let capturedContext: PluginHookContext | null = null
+
+				const handler = vi.fn(async (ctx: PluginHookContext): Promise<PluginHookResult> => {
+					capturedContext = ctx
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('pre_tool_use', [{ pluginId: mockPluginId, handler }])
+
+				const contextData = {
+					runId: mockRunId,
+					toolName: 'test_tool',
+					toolInput: { key: 'value' },
+				}
+
+				await manager.executeHooks('pre_tool_use', contextData)
+
+				expect(capturedContext).not.toBeNull()
+				const ctx = capturedContext as unknown as PluginHookContext
+				expect(ctx.runId).toBe(mockRunId)
+				expect(ctx.pluginId).toBe(mockPluginId)
+				expect(ctx.event).toBe('pre_tool_use')
+				expect(ctx.toolName).toBe('test_tool')
+				expect(ctx.toolInput).toEqual({ key: 'value' })
+			})
+
+			it('should include iteration number in context when provided', async () => {
+				let capturedContext: PluginHookContext | null = null
+
+				const handler = vi.fn(async (ctx: PluginHookContext): Promise<PluginHookResult> => {
+					capturedContext = ctx
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('iteration_end', [{ pluginId: mockPluginId, handler }])
+
+				await manager.executeHooks('iteration_end', {
+					runId: mockRunId,
+					iteration: 5,
+				})
+
+				const ctx = capturedContext as unknown as PluginHookContext
+				expect(ctx.iteration).toBe(5)
+			})
+		})
+
+		describe('Hook execution logging', () => {
+			it('should emit hook_executed event with correct metadata', async () => {
+				const events: any[] = []
+				manager.on((evt) => events.push(evt))
+
+				const handler = vi.fn(async (): Promise<PluginHookResult> => {
+					return { action: 'continue' }
+				})
+
+				manager['hookHandlers'].set('run_start', [{ pluginId: mockPluginId, handler }])
+
+				await manager.executeHooks('run_start', { runId: mockRunId })
+
+				const hookExecutedEvents = events.filter((evt) => evt.type === 'plugin_hook_executed')
+				expect(hookExecutedEvents).toHaveLength(1)
+
+				const event = hookExecutedEvents[0]
+				expect(event?.pluginId).toBe(mockPluginId)
+				expect(event?.hookEvent).toBe('run_start')
+				expect(typeof event?.durationMs).toBe('number')
+				expect(event?.durationMs).toBeGreaterThanOrEqual(0)
+			})
+		})
+
+		describe('Exception handling', () => {
+			it('should catch thrown exceptions and return error action', async () => {
+				const handler = vi.fn(async (): Promise<PluginHookResult> => {
+					throw new Error('Handler crashed')
+				})
+
+				manager['hookHandlers'].set('run_start', [{ pluginId: mockPluginId, handler }])
+
+				const results = await manager.executeHooks('run_start', { runId: mockRunId })
+
+				expect(results).toHaveLength(1)
+				expect(results[0]?.action).toBe('error')
+				if (results[0]?.action === 'error') {
+					expect(results[0].message).toContain('Handler crashed')
+				}
+			})
+
+			it('should not throw when handler throws', async () => {
+				const handler = vi.fn(async (): Promise<PluginHookResult> => {
+					throw new Error('Handler failed')
+				})
+
+				manager['hookHandlers'].set('run_start', [{ pluginId: mockPluginId, handler }])
+
+				const executePromise = manager.executeHooks('run_start', { runId: mockRunId })
+				await expect(executePromise).resolves.not.toThrow()
+			})
+		})
+	})
+})

package/src/plugin/lifecycle.ts

@@ -2,7 +2,6 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { HOOK_TIMEOUT_MS, PLUGIN_NAMESPACE_SEPARATOR } from '../constants/plugin/index.js'
 import type { PluginRegistry } from '../registry/plugin/index.js'
-import type { ToolRegistry } from '../registry/tool/execute.js'
 import type { PluginId } from '../types/ids/index.js'
 import type {
 	PluginDefinition,
@@ -14,7 +13,7 @@ import type {
 	PluginLifecycleEvent,
 	PluginScope,
 } from '../types/plugin/index.js'
-import type { ToolDefinition } from '../types/tool/index.js'
+import type { ToolDefinition, ToolRegistryContract } from '../types/tool/index.js'
 import { toErrorMessage } from '../utils/error.js'
 import { generatePluginId } from '../utils/id.js'
 import type { Logger } from '../utils/logger.js'
@@ -22,14 +21,14 @@ import { loadPluginManifest } from './loader.js'
 
 export interface PluginLifecycleManagerConfig {
 	pluginRegistry: PluginRegistry
-	toolRegistry: ToolRegistry
+	toolRegistry: ToolRegistryContract
 	log: Logger
 	hookTimeoutMs?: number
 }
 
 export class PluginLifecycleManager {
 	private pluginRegistry: PluginRegistry
-	private toolRegistry: ToolRegistry
+	private toolRegistry: ToolRegistryContract
 	private listeners: PluginEventListener[] = []
 	private hookHandlers: Map<
 		PluginHookEvent,
@@ -257,7 +256,25 @@ export class PluginLifecycleManager {
 
 		const results: PluginHookResult[] = []
 
-		for (const { pluginId, handler } of handlers) {
+		// Determine execution order: post_* hooks run backward (for cleanup semantics)
+		const isPost = event.startsWith('post_')
+
+		// For post_* hooks, we need to process in reverse order (last registered runs first)
+		const indicesToProcess: number[] = []
+		if (isPost) {
+			for (let i = handlers.length - 1; i >= 0; i--) {
+				indicesToProcess.push(i)
+			}
+		} else {
+			for (let i = 0; i < handlers.length; i++) {
+				indicesToProcess.push(i)
+			}
+		}
+
+		for (const idx of indicesToProcess) {
+			const hookEntry = handlers[idx]
+			if (!hookEntry) continue
+			const { pluginId, handler: handlerFn } = hookEntry
 			const hookContext: PluginHookContext = {
 				...context,
 				pluginId,
@@ -269,7 +286,7 @@ export class PluginLifecycleManager {
 
 			try {
 				result = await Promise.race([
-					handler(hookContext),
+					handlerFn(hookContext),
 					new Promise<PluginHookResult>((_, reject) =>
 						setTimeout(() => reject(new Error('Hook timeout')), this.hookTimeoutMs),
 					),
@@ -289,6 +306,15 @@ export class PluginLifecycleManager {
 			})
 
 			results.push(result)
+
+			// Handle flow control: check priority order: error > skip > retry > resume > modify > continue
+			// Short-circuit on error or skip; return immediately on resume or retry
+			if (result.action === 'error' || result.action === 'skip') {
+				break
+			}
+			if (result.action === 'resume' || result.action === 'retry') {
+				break
+			}
 		}
 
 		return results