aegis-bridge 0.1.0

package/dist/hook.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * hook.ts — Claude Code SessionStart hook for Aegis.
+ *
+ * Writes session_id → window_id mapping to ~/.aegis/session_map.json.
+ * Falls back to ~/.manus/ for backward compatibility.
+ * Called by CC's hook system, reads payload from stdin.
+ *
+ * Install: add to ~/.claude/settings.json:
+ * {
+ *   "hooks": {
+ *     "SessionStart": [{
+ *       "hooks": [{ "type": "command", "command": "node /path/to/dist/hook.js", "timeout": 5 }]
+ *     }]
+ *   }
+ * }
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { stopSignalsSchema, sessionMapSchema, stopPayloadSchema } from './validation.js';
+import { safeJsonParse, safeJsonParseSchema } from './safe-json.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Use ~/.aegis if it exists, fall back to ~/.manus for backward compat
+const AEGIS_DIR = join(homedir(), '.aegis');
+const MANUS_DIR = join(homedir(), '.manus');
+const BRIDGE_DIR = existsSync(AEGIS_DIR) ? AEGIS_DIR : MANUS_DIR;
+const MAP_FILE = join(BRIDGE_DIR, 'session_map.json');
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const TMUX_PANE_RE = /^%\d+$/;
+const DEFAULT_POINTER_TTL_MS = 24 * 60 * 60 * 1000;
+function normalizeCommandPath(pathValue, platform = process.platform) {
+    return platform === 'win32' ? pathValue.replace(/\//g, '\\') : pathValue.replace(/\\/g, '/');
+}
+function quoteCommandPath(pathValue, platform = process.platform) {
+    const normalized = normalizeCommandPath(pathValue, platform);
+    return `"${normalized.replace(/"/g, '\\"')}"`;
+}
+/** Build a shell-safe command string that invokes hook.js with an explicit Node executable. */
+export function buildHookCommand(scriptPath, nodeExecutable = process.execPath, platform = process.platform) {
+    return `${quoteCommandPath(nodeExecutable, platform)} ${quoteCommandPath(scriptPath, platform)}`;
+}
+function getPointerTtlMs() {
+    const raw = process.env.AEGIS_CONTINUATION_POINTER_TTL_MS ?? process.env.MANUS_CONTINUATION_POINTER_TTL_MS;
+    const parsed = raw ? Number(raw) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_POINTER_TTL_MS;
+}
+/** Handle Stop/StopFailure events.
+ *  Writes a signal file that the Aegis monitor can detect.
+ *  Issue #15: StopFailure fires on API errors (rate limit, auth failure).
+ */
+function handleStopEvent(sessionId, event, payload) {
+    const signalFile = join(BRIDGE_DIR, 'stop_signals.json');
+    let signals = {};
+    if (existsSync(signalFile)) {
+        const parsed = safeJsonParseSchema(readFileSync(signalFile, 'utf-8'), stopSignalsSchema, 'stop_signals.json');
+        if (parsed.ok) {
+            signals = parsed.data;
+        }
+        else {
+            console.warn(`${parsed.error}; starting fresh`);
+        }
+    }
+    const p = stopPayloadSchema.safeParse(payload);
+    const pd = p.success ? p.data : {};
+    signals[sessionId] = {
+        event,
+        timestamp: Date.now(),
+        // StopFailure may include error info in the payload
+        error: pd.error ?? pd.message ?? null,
+        error_details: pd.error_details ?? null,
+        last_assistant_message: pd.last_assistant_message ?? null,
+        agent_id: pd.agent_id ?? null,
+        stop_reason: pd.stop_reason ?? null,
+    };
+    // Atomic write: write to temp file then rename (prevents partial writes on crash)
+    const tmpSignalFile = signalFile + '.tmp';
+    writeFileSync(tmpSignalFile, JSON.stringify(signals, null, 2));
+    renameSync(tmpSignalFile, signalFile);
+    console.error(`Aegis hook: ${event} for session ${sessionId.slice(0, 8)}...`);
+}
+function main() {
+    // Check for --install flag
+    if (process.argv.includes('--install')) {
+        install();
+        return;
+    }
+    // Read payload from stdin
+    let payload;
+    try {
+        const input = readFileSync(0, 'utf-8'); // stdin = fd 0
+        const parsed = safeJsonParse(input, 'Hook stdin payload');
+        if (!parsed.ok || typeof parsed.data !== 'object' || parsed.data === null || Array.isArray(parsed.data)) {
+            process.exit(0);
+        }
+        payload = parsed.data;
+    }
+    catch { /* malformed or empty stdin — nothing to do */
+        process.exit(0);
+    }
+    const sessionId = payload.session_id || '';
+    const cwd = payload.cwd || '';
+    const event = payload.hook_event_name || '';
+    if (!sessionId) {
+        process.exit(0);
+    }
+    // Handle Stop and StopFailure events — write signal file for monitor
+    if (event === 'Stop' || event === 'StopFailure') {
+        handleStopEvent(sessionId, event, payload);
+        process.exit(0);
+    }
+    if (event !== 'SessionStart') {
+        process.exit(0);
+    }
+    if (!UUID_RE.test(sessionId)) {
+        console.error(`Invalid session_id: ${sessionId}`);
+        process.exit(0);
+    }
+    // Get tmux window info
+    const tmuxPane = process.env.TMUX_PANE;
+    if (!tmuxPane) {
+        console.error('TMUX_PANE not set');
+        process.exit(0);
+    }
+    if (!TMUX_PANE_RE.test(tmuxPane)) {
+        console.error(`Invalid TMUX_PANE: ${tmuxPane}`);
+        process.exit(0);
+    }
+    let tmuxInfo;
+    try {
+        tmuxInfo = execFileSync('tmux', ['display-message', '-t', tmuxPane, '-p', '#{session_name}:#{window_id}:#{window_name}'], { encoding: 'utf-8' }).trim();
+    }
+    catch { /* tmux not running or pane not found */
+        console.error('Failed to get tmux info');
+        process.exit(0);
+    }
+    const parts = tmuxInfo.split(':');
+    if (parts.length < 3) {
+        process.exit(0);
+    }
+    const [sessionName, windowId, windowName] = parts;
+    const key = `${sessionName}:${windowId}`;
+    // Read-modify-write session_map
+    mkdirSync(BRIDGE_DIR, { recursive: true });
+    let sessionMap = {};
+    if (existsSync(MAP_FILE)) {
+        const parsed = safeJsonParseSchema(readFileSync(MAP_FILE, 'utf-8'), sessionMapSchema, 'session_map.json');
+        if (parsed.ok) {
+            sessionMap = parsed.data;
+        }
+        else {
+            console.warn(`${parsed.error}; starting fresh`);
+        }
+    }
+    const writtenAt = Date.now();
+    sessionMap[key] = {
+        session_id: sessionId,
+        cwd,
+        window_name: windowName || '',
+        transcript_path: payload.transcript_path || null,
+        permission_mode: payload.permission_mode || null,
+        agent_id: payload.agent_id || null,
+        source: payload.source || null,
+        agent_type: payload.agent_type || null,
+        model: payload.model || null,
+        written_at: writtenAt,
+        schema_version: 1,
+        expires_at: writtenAt + getPointerTtlMs(),
+    };
+    // Atomic write: write to temp file then rename (prevents race-condition data loss)
+    const tmpMapFile = MAP_FILE + '.tmp';
+    writeFileSync(tmpMapFile, JSON.stringify(sessionMap, null, 2));
+    renameSync(tmpMapFile, MAP_FILE);
+    console.error(`Aegis hook: mapped ${key} -> ${sessionId}`);
+}
+function install() {
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        const parsed = safeJsonParse(readFileSync(settingsPath, 'utf-8'), settingsPath);
+        if (!parsed.ok || typeof parsed.data !== 'object' || parsed.data === null || Array.isArray(parsed.data)) {
+            console.error(`Failed to read ${settingsPath}`);
+            process.exit(1);
+        }
+        settings = parsed.data;
+    }
+    const hookCommand = buildHookCommand(join(__dirname, 'hook.js'));
+    const hooks = (settings.hooks || {});
+    const sessionStart = (hooks.SessionStart || []);
+    // Check if already installed
+    const isInstalled = sessionStart.some(entry => entry.hooks?.some(h => h.command?.includes('aegis') || h.command?.includes('manus') || h.command?.includes('hook.js')));
+    if (isInstalled) {
+        console.log('Aegis hook already installed');
+        return;
+    }
+    sessionStart.push({
+        hooks: [{ type: 'command', command: hookCommand, timeout: 5 }]
+    });
+    hooks.SessionStart = sessionStart;
+    // Issue #15: Also register Stop and StopFailure hooks
+    const hookEntry = { hooks: [{ type: 'command', command: hookCommand, timeout: 5 }] };
+    for (const event of ['Stop', 'StopFailure']) {
+        const existing = (hooks[event] || []);
+        const alreadyInstalled = existing.some(entry => entry.hooks?.some(h => h.command?.includes('aegis') || h.command?.includes('manus') || h.command?.includes('hook.js')));
+        if (!alreadyInstalled) {
+            existing.push({ ...hookEntry });
+            hooks[event] = existing;
+        }
+    }
+    settings.hooks = hooks;
+    mkdirSync(join(homedir(), '.claude'), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`Aegis hook installed in ${settingsPath}`);
+}
+const isDirectExecution = (() => {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return resolve(argv1) === resolve(__filename);
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectExecution) {
+    main();
+}

package/dist/hooks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * hooks.ts — HTTP hook receiver for Claude Code hook events.
+ *
+ * Claude Code supports type: "http" hooks that POST JSON events to a URL.
+ * This module provides a route handler that receives these events and
+ * forwards them to SSE subscribers.
+ *
+ * Hook URL pattern: POST /v1/hooks/{eventName}?sessionId={id}
+ * Session identification: X-Session-Id header or sessionId query param.
+ *
+ * Decision events (PreToolUse, PermissionRequest) return a response body
+ * that CC uses to approve/reject tool calls.
+ *
+ * Issue #169: Phase 1 — HTTP hooks infrastructure.
+ * Issue #169: Phase 3 — Hook-driven status detection.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { SessionManager } from './session.js';
+import type { SessionEventBus } from './events.js';
+import type { MetricsCollector } from './metrics.js';
+export interface HookRouteDeps {
+    sessions: SessionManager;
+    eventBus: SessionEventBus;
+    metrics?: MetricsCollector;
+}
+/**
+ * Register the hooks endpoint on the Fastify app.
+ *
+ * This MUST be called before auth middleware is set up, OR the /v1/hooks
+ * path must be added to the auth skip list in setupAuth().
+ */
+export declare function registerHookRoutes(app: FastifyInstance, deps: HookRouteDeps): void;

package/dist/hooks.js

@@ -0,0 +1,364 @@
+/**
+ * hooks.ts — HTTP hook receiver for Claude Code hook events.
+ *
+ * Claude Code supports type: "http" hooks that POST JSON events to a URL.
+ * This module provides a route handler that receives these events and
+ * forwards them to SSE subscribers.
+ *
+ * Hook URL pattern: POST /v1/hooks/{eventName}?sessionId={id}
+ * Session identification: X-Session-Id header or sessionId query param.
+ *
+ * Decision events (PreToolUse, PermissionRequest) return a response body
+ * that CC uses to approve/reject tool calls.
+ *
+ * Issue #169: Phase 1 — HTTP hooks infrastructure.
+ * Issue #169: Phase 3 — Hook-driven status detection.
+ */
+import { isValidUUID, hookBodySchema, parseIntSafe } from './validation.js';
+import { evaluatePermissionProfile } from './permission-evaluator.js';
+/** CC hook events that require a decision response. */
+const DECISION_EVENTS = new Set(['PreToolUse', 'PermissionRequest']);
+/** Permission modes that should be auto-approved via hook response. */
+const AUTO_APPROVE_MODES = new Set(['bypassPermissions', 'dontAsk', 'acceptEdits', 'plan', 'auto']);
+/** Default timeout for waiting on client permission decision (ms). */
+const PERMISSION_TIMEOUT_MS = 10_000;
+/** Default timeout for waiting on external answer to AskUserQuestion (ms). */
+const ANSWER_TIMEOUT_MS = parseIntSafe(process.env.ANSWER_TIMEOUT_MS, 30_000);
+/** Valid permission_mode values accepted by Claude Code. */
+const VALID_PERMISSION_MODES = new Set(['default', 'plan', 'bypassPermissions']);
+/** Valid CC hook event names (allow any for extensibility, but these are known). */
+const KNOWN_HOOK_EVENTS = new Set([
+    'Stop',
+    'StopFailure',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Notification',
+    'PermissionRequest',
+    'SessionStart',
+    'SessionEnd',
+    'SubagentStart',
+    'SubagentStop',
+    'TaskCompleted',
+    'TeammateIdle',
+    'PreCompact',
+    'PostCompact',
+    'UserPromptSubmit',
+    'WorktreeCreate',
+    'WorktreeRemove',
+    'Elicitation',
+    'ElicitationResult',
+    'FileChanged',
+    'CwdChanged',
+    // Issue #703 Phase 1: additional lifecycle events
+    'PermissionDenied',
+    'TaskCreated',
+    'Setup',
+    'ConfigChange',
+    'InstructionsLoaded',
+]);
+/** Hook events that are informational (logged + forwarded to SSE, no status change). */
+const INFORMATIONAL_EVENTS = new Set([
+    'Notification',
+    'FileChanged',
+    'CwdChanged',
+    // Issue #703 Phase 1: informational lifecycle events
+    'Setup',
+    'ConfigChange',
+    'InstructionsLoaded',
+    'PermissionDenied',
+]);
+/** Map hook event names to the UIState they imply. */
+function hookToUIState(eventName) {
+    switch (eventName) {
+        case 'Stop':
+        case 'TaskCompleted':
+        case 'SessionEnd':
+        case 'PostCompact': return 'idle';
+        case 'StopFailure':
+        case 'PostToolUseFailure': return 'error';
+        case 'PreToolUse':
+        case 'PostToolUse':
+        case 'SubagentStart':
+        case 'UserPromptSubmit':
+        case 'Elicitation':
+        case 'ElicitationResult':
+        case 'WorktreeCreate':
+        case 'WorktreeRemove': return 'working';
+        case 'PreCompact': return 'compacting';
+        case 'PermissionRequest': return 'permission_prompt';
+        case 'TeammateIdle': return 'idle';
+        // Issue #703 Phase 1
+        case 'TaskCreated': return 'working';
+        default: return null;
+    }
+}
+/** Extract question text from AskUserQuestion tool_input. */
+function extractQuestionText(toolInput) {
+    if (!toolInput)
+        return '';
+    const questions = toolInput.questions;
+    if (!questions || !Array.isArray(questions) || questions.length === 0)
+        return '';
+    const first = questions[0];
+    return first?.question || '';
+}
+/**
+ * Register the hooks endpoint on the Fastify app.
+ *
+ * This MUST be called before auth middleware is set up, OR the /v1/hooks
+ * path must be added to the auth skip list in setupAuth().
+ */
+export function registerHookRoutes(app, deps) {
+    app.post('/v1/hooks/:eventName', async (req, reply) => {
+        const { eventName } = req.params;
+        // Issue #349: Validate event name against known list to prevent injection
+        if (!KNOWN_HOOK_EVENTS.has(eventName)) {
+            return reply.status(400).send({ error: `Unknown hook event: ${eventName}` });
+        }
+        const sessionId = req.headers['x-session-id'] || req.query.sessionId;
+        if (!sessionId) {
+            return reply.status(400).send({ error: 'Missing session ID — provide X-Session-Id header or sessionId query param' });
+        }
+        // Issue #580: Reject non-UUID session IDs before getSession lookup.
+        if (!isValidUUID(sessionId)) {
+            return reply.status(400).send({ error: 'Invalid session ID — must be a UUID' });
+        }
+        const session = deps.sessions.getSession(sessionId);
+        if (!session) {
+            return reply.status(404).send({ error: `Session ${sessionId} not found` });
+        }
+        // Issue #629/#1131: Validate hook secret from X-Hook-Secret header (query param fallback)
+        const hookSecret = req.headers['x-hook-secret']
+            || req.query?.secret;
+        if (session.hookSecret && hookSecret !== session.hookSecret) {
+            return reply.status(401).send({ error: 'Unauthorized — invalid hook secret' });
+        }
+        // Issue #665: Validate hook body with Zod instead of unsafe casts
+        const parseResult = hookBodySchema.safeParse(req.body);
+        if (!parseResult.success) {
+            return reply.status(400).send({ error: `Invalid hook body: ${parseResult.error.message}` });
+        }
+        const hookBody = parseResult.data;
+        // Issue #88: Track active subagents
+        if (eventName === 'SubagentStart') {
+            const agentName = hookBody.agent_name || hookBody.tool_input?.command || 'unknown';
+            deps.sessions.addSubagent(sessionId, agentName);
+            deps.eventBus.emit(sessionId, {
+                event: 'subagent_start',
+                sessionId,
+                timestamp: new Date().toISOString(),
+                data: { agentName },
+            });
+        }
+        else if (eventName === 'SubagentStop') {
+            const agentName = hookBody.agent_name || 'unknown';
+            deps.sessions.removeSubagent(sessionId, agentName);
+            deps.eventBus.emit(sessionId, {
+                event: 'subagent_stop',
+                sessionId,
+                timestamp: new Date().toISOString(),
+                data: { agentName },
+            });
+        }
+        // Issue #703 Phase 1: PermissionDenied — emit denied event for dashboard/agents
+        if (eventName === 'PermissionDenied') {
+            deps.eventBus.emit(sessionId, {
+                event: 'permission_denied',
+                sessionId,
+                timestamp: new Date().toISOString(),
+                data: {
+                    toolName: hookBody.tool_name || '',
+                    reason: hookBody.reason || '',
+                },
+            });
+        }
+        // Issue #89 L26: WorktreeCreate/Remove hooks — informational tracking only
+        if (eventName === 'WorktreeCreate' || eventName === 'WorktreeRemove') {
+            console.log(`Hooks: ${eventName} for session ${sessionId}`);
+        }
+        // Informational events — log and forward to SSE (already forwarded below via emitHook)
+        if (INFORMATIONAL_EVENTS.has(eventName)) {
+            console.log(`Hooks: ${eventName} for session ${sessionId}`);
+        }
+        // PreCompact/PostCompact — update activity timestamp
+        if (eventName === 'PreCompact' || eventName === 'PostCompact') {
+            session.lastActivity = Date.now();
+        }
+        // Forward the validated hook event to SSE subscribers
+        deps.eventBus.emitHook(sessionId, eventName, hookBody);
+        // Issue #89 L25: Capture model field from hook payload for dashboard display
+        if (hookBody.model) {
+            deps.sessions.updateSessionModel(sessionId, hookBody.model);
+        }
+        // Issue #89 L24: Validate permission_mode from PermissionRequest hook
+        if (eventName === 'PermissionRequest') {
+            const rawMode = hookBody.permission_mode;
+            if (rawMode !== undefined && !VALID_PERMISSION_MODES.has(rawMode)) {
+                console.warn(`Hooks: invalid permission_mode "${rawMode}" from PermissionRequest, using "default"`);
+                hookBody.permission_mode = 'default';
+            }
+        }
+        // Issue #169 Phase 3: Update session status from hook event
+        // Issue #87: Extract timestamp from hook payload for latency calculation
+        const hookReceivedAt = Date.now();
+        const hookEventTimestamp = hookBody.timestamp
+            ? new Date(hookBody.timestamp).getTime()
+            : undefined;
+        // Issue #87: Record hook latency if we have a timestamp from the payload
+        if (hookEventTimestamp && deps.metrics) {
+            const latency = hookReceivedAt - hookEventTimestamp;
+            if (latency >= 0) {
+                deps.metrics.recordHookLatency(sessionId, latency);
+            }
+        }
+        const prevStatus = deps.sessions.updateStatusFromHook(sessionId, eventName, hookEventTimestamp);
+        const newStatus = hookToUIState(eventName);
+        // Emit SSE status event only when the hook implies a state change
+        if (newStatus && prevStatus !== newStatus) {
+            switch (eventName) {
+                case 'Stop': {
+                    // Issue #812: Check if CC is waiting for user input (text-only last assistant message)
+                    const waiting = await deps.sessions.detectWaitingForInput(sessionId);
+                    if (waiting) {
+                        const session = deps.sessions.getSession(sessionId);
+                        if (session)
+                            session.status = 'waiting_for_input';
+                        deps.eventBus.emitStatus(sessionId, 'waiting_for_input', 'Claude finished, waiting for input (hook: Stop)');
+                    }
+                    else {
+                        deps.eventBus.emitStatus(sessionId, 'idle', 'Claude finished (hook: Stop)');
+                    }
+                    break;
+                }
+                case 'PreToolUse':
+                case 'PostToolUse':
+                    deps.eventBus.emitStatus(sessionId, 'working', 'Claude is working (hook: tool use)');
+                    break;
+                case 'PreCompact':
+                    deps.eventBus.emitStatus(sessionId, 'compacting', 'Claude is compacting context (hook: PreCompact)');
+                    break;
+                case 'PostCompact':
+                    deps.eventBus.emitStatus(sessionId, 'idle', 'Compaction complete (hook: PostCompact)');
+                    break;
+                case 'Elicitation':
+                    deps.eventBus.emitStatus(sessionId, 'working', 'Claude is performing MCP elicitation (hook: Elicitation)');
+                    break;
+                case 'ElicitationResult':
+                    deps.eventBus.emitStatus(sessionId, 'working', 'Elicitation result received (hook: ElicitationResult)');
+                    break;
+                case 'WorktreeCreate':
+                    deps.eventBus.emitStatus(sessionId, 'working', `Worktree created: ${hookBody.worktree_path || 'unknown'} (hook: WorktreeCreate)`);
+                    break;
+                case 'WorktreeRemove':
+                    deps.eventBus.emitStatus(sessionId, 'idle', `Worktree removed: ${hookBody.worktree_path || 'unknown'} (hook: WorktreeRemove)`);
+                    break;
+                case 'PermissionRequest':
+                    deps.eventBus.emitApproval(sessionId, hookBody.permission_prompt || 'Permission requested (hook)');
+                    break;
+            }
+        }
+        // Decision events need a response body that CC uses
+        // Format: { hookSpecificOutput: { hookEventName, permissionDecision, reason? } }
+        if (DECISION_EVENTS.has(eventName)) {
+            const toolName = hookBody.tool_name || '';
+            const permissionPrompt = hookBody.permission_prompt || '';
+            if (eventName === 'PreToolUse') {
+                // Issue #336: Intercept AskUserQuestion for headless question answering
+                if (toolName === 'AskUserQuestion') {
+                    const toolInput = hookBody.tool_input;
+                    const toolUseId = hookBody.tool_use_id || '';
+                    const questionText = extractQuestionText(toolInput);
+                    // Emit ask_question SSE event for external clients
+                    deps.eventBus.emit(sessionId, {
+                        event: 'status',
+                        sessionId,
+                        timestamp: new Date().toISOString(),
+                        data: { status: 'ask_question', questionId: toolUseId, question: questionText },
+                    });
+                    console.log(`Hooks: AskUserQuestion for session ${sessionId} — waiting for answer (timeout: ${ANSWER_TIMEOUT_MS}ms)`);
+                    const answer = await deps.sessions.waitForAnswer(sessionId, toolUseId, questionText, ANSWER_TIMEOUT_MS);
+                    if (answer !== null) {
+                        console.log(`Hooks: AskUserQuestion answered for session ${sessionId}`);
+                        return reply.status(200).send({
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                permissionDecision: 'allow',
+                                updatedInput: { answer },
+                            },
+                        });
+                    }
+                    // Timeout: allow without answer (CC shows question to user in terminal)
+                    console.log(`Hooks: AskUserQuestion timeout for session ${sessionId} — allowing without answer`);
+                }
+                if (session.permissionProfile) {
+                    const evaluation = evaluatePermissionProfile(session.permissionProfile, {
+                        toolName,
+                        toolInput: hookBody.tool_input,
+                    });
+                    if (evaluation.behavior === 'deny') {
+                        deps.eventBus.emit(sessionId, {
+                            event: 'permission_denied',
+                            sessionId,
+                            timestamp: new Date().toISOString(),
+                            data: { toolName, reason: evaluation.reason },
+                        });
+                        return reply.status(200).send({
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                permissionDecision: 'deny',
+                                reason: evaluation.reason,
+                            },
+                        });
+                    }
+                    if (evaluation.behavior === 'ask') {
+                        deps.eventBus.emitApproval(sessionId, `Permission profile requires approval for ${toolName}`);
+                        const decision = await deps.sessions.waitForPermissionDecision(sessionId, PERMISSION_TIMEOUT_MS, toolName, evaluation.reason);
+                        return reply.status(200).send({
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                permissionDecision: decision,
+                            },
+                        });
+                    }
+                }
+                // Default: allow without modification
+                return reply.status(200).send({
+                    hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'allow',
+                    },
+                });
+            }
+            if (eventName === 'PermissionRequest') {
+                // Issue #284: Hook-based permission approval.
+                // Auto-approve modes respond immediately; others wait for client.
+                const permMode = session.permissionMode || 'default';
+                if (AUTO_APPROVE_MODES.has(permMode)) {
+                    console.log(`Hooks: auto-approving PermissionRequest for session ${sessionId} (mode: ${permMode})`);
+                    return reply.status(200).send({
+                        hookSpecificOutput: {
+                            hookEventName: 'PermissionRequest',
+                            permissionDecision: 'allow',
+                        },
+                    });
+                }
+                // Non-auto-approve: wait for client to approve/reject via API.
+                // Store pending permission and block until resolved or timeout.
+                console.log(`Hooks: waiting for client permission decision for session ${sessionId}`);
+                const decision = await deps.sessions.waitForPermissionDecision(sessionId, PERMISSION_TIMEOUT_MS, toolName, permissionPrompt);
+                const decisionLabel = decision === 'allow' ? 'approved' : 'rejected';
+                console.log(`Hooks: PermissionRequest for session ${sessionId} — ${decisionLabel} by client`);
+                return reply.status(200).send({
+                    hookSpecificOutput: {
+                        hookEventName: 'PermissionRequest',
+                        permissionDecision: decision,
+                    },
+                });
+            }
+            return reply.status(200).send({ ok: true });
+        }
+        // Non-decision events: simple acknowledgement
+        return reply.status(200).send({ ok: true });
+    });
+}