aegis-bridge 0.1.0

package/dist/file-utils.js

@@ -0,0 +1,37 @@
+import { execFile } from 'node:child_process';
+import { chmod } from 'node:fs/promises';
+const PERMISSIONS_TIMEOUT_MS = 5_000;
+export function buildWindowsIcaclsArgs(filePath, account) {
+    return [filePath, '/inheritance:r', '/grant:r', `${account}:(R,W)`];
+}
+function runIcacls(filePath, account) {
+    const args = buildWindowsIcaclsArgs(filePath, account);
+    return new Promise((resolve, reject) => {
+        execFile('icacls', args, { timeout: PERMISSIONS_TIMEOUT_MS }, (error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+export async function secureFilePermissions(filePath, platform = process.platform) {
+    if (platform !== 'win32') {
+        await chmod(filePath, 0o600);
+        return;
+    }
+    const username = process.env.USERNAME;
+    if (!username) {
+        console.warn(`Windows permission hardening skipped for ${filePath}: USERNAME is not set`);
+        return;
+    }
+    const account = process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${username}` : username;
+    try {
+        await runIcacls(filePath, account);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        console.warn(`Windows permission hardening failed for ${filePath}: ${detail}`);
+    }
+}

package/dist/handshake.d.ts

@@ -0,0 +1,60 @@
+/**
+ * handshake.ts — Capability handshake schema and negotiation for Aegis/Claude Code.
+ *
+ * Issue #885: Defines a formal protocolVersion + capabilities negotiation so
+ * that clients and Aegis can agree on supported feature set before using
+ * advanced integration paths. Prevents version-drift breakage.
+ */
+/** Current protocol version advertised by this Aegis build. */
+export declare const AEGIS_PROTOCOL_VERSION = "1";
+/** Minimum protocol version this Aegis build still accepts. */
+export declare const AEGIS_MIN_PROTOCOL_VERSION = "1";
+/**
+ * All capabilities Aegis supports in this build.
+ * Capabilities are additive; absence means the feature is unavailable/disabled.
+ */
+export declare const AEGIS_CAPABILITIES: readonly ["session.create", "session.resume", "session.approve", "session.transcript", "session.transcript.cursor", "session.events.sse", "session.events.cursor", "session.screenshot", "hooks.pre_tool_use", "hooks.post_tool_use", "hooks.notification", "hooks.stop", "swarm", "metrics"];
+export type AegisCapability = (typeof AEGIS_CAPABILITIES)[number];
+/**
+ * Feature gates that client integrations should check before enabling
+ * behavior that depends on newer protocol/capability support.
+ */
+export declare const HANDSHAKE_FEATURE_REQUIREMENTS: {
+    readonly cursorReplay: readonly ["session.transcript.cursor"];
+    readonly transcriptRead: readonly ["session.transcript"];
+    readonly sseEvents: readonly ["session.events.sse"];
+    readonly permissionControl: readonly ["session.approve"];
+    readonly screenshots: readonly ["session.screenshot"];
+    readonly hookLifecycle: readonly ["hooks.pre_tool_use", "hooks.post_tool_use"];
+};
+export type HandshakeFeature = keyof typeof HANDSHAKE_FEATURE_REQUIREMENTS;
+export type HandshakeFallbackMode = 'none' | 'legacy-defaults' | 'incompatible-protocol' | 'invalid-protocol';
+/** Request body for POST /v1/handshake */
+export interface HandshakeRequest {
+    protocolVersion: string;
+    clientCapabilities?: string[];
+    clientVersion?: string;
+}
+/** Response shape for POST /v1/handshake */
+export interface HandshakeResponse {
+    protocolVersion: string;
+    serverCapabilities: AegisCapability[];
+    negotiatedCapabilities: AegisCapability[];
+    featureGates: Record<HandshakeFeature, boolean>;
+    fallbackMode: HandshakeFallbackMode;
+    warnings: string[];
+    compatible: boolean;
+}
+/** Compute boolean feature gates from a negotiated capability set. */
+export declare function computeFeatureGates(capabilities: readonly AegisCapability[]): Record<HandshakeFeature, boolean>;
+/** Helper for checking one feature gate directly from a handshake response. */
+export declare function isFeatureEnabled(response: HandshakeResponse, feature: HandshakeFeature): boolean;
+/**
+ * Negotiate capabilities between a client request and this Aegis build.
+ *
+ * Rules:
+ * - If client protocolVersion < AEGIS_MIN_PROTOCOL_VERSION → not compatible, add warning, return empty negotiatedCapabilities
+ * - If client protocolVersion > AEGIS_PROTOCOL_VERSION → compatible but add forward-compat warning
+ * - negotiatedCapabilities = intersection of server caps and clientCapabilities (or all server caps if client sends none)
+ */
+export declare function negotiate(req: HandshakeRequest): HandshakeResponse;

package/dist/handshake.js

@@ -0,0 +1,124 @@
+/**
+ * handshake.ts — Capability handshake schema and negotiation for Aegis/Claude Code.
+ *
+ * Issue #885: Defines a formal protocolVersion + capabilities negotiation so
+ * that clients and Aegis can agree on supported feature set before using
+ * advanced integration paths. Prevents version-drift breakage.
+ */
+/** Current protocol version advertised by this Aegis build. */
+export const AEGIS_PROTOCOL_VERSION = '1';
+/** Minimum protocol version this Aegis build still accepts. */
+export const AEGIS_MIN_PROTOCOL_VERSION = '1';
+/**
+ * All capabilities Aegis supports in this build.
+ * Capabilities are additive; absence means the feature is unavailable/disabled.
+ */
+export const AEGIS_CAPABILITIES = [
+    'session.create',
+    'session.resume',
+    'session.approve',
+    'session.transcript',
+    'session.transcript.cursor', // Issue #883: cursor-based replay
+    'session.events.sse',
+    'session.events.cursor',
+    'session.screenshot',
+    'hooks.pre_tool_use',
+    'hooks.post_tool_use',
+    'hooks.notification',
+    'hooks.stop',
+    'swarm',
+    'metrics',
+];
+/**
+ * Feature gates that client integrations should check before enabling
+ * behavior that depends on newer protocol/capability support.
+ */
+export const HANDSHAKE_FEATURE_REQUIREMENTS = {
+    cursorReplay: ['session.transcript.cursor'],
+    transcriptRead: ['session.transcript'],
+    sseEvents: ['session.events.sse'],
+    permissionControl: ['session.approve'],
+    screenshots: ['session.screenshot'],
+    hookLifecycle: ['hooks.pre_tool_use', 'hooks.post_tool_use'],
+};
+/** Compute boolean feature gates from a negotiated capability set. */
+export function computeFeatureGates(capabilities) {
+    const enabled = new Set(capabilities);
+    return Object.fromEntries(Object.entries(HANDSHAKE_FEATURE_REQUIREMENTS).map(([feature, required]) => [
+        feature,
+        required.every(capability => enabled.has(capability)),
+    ]));
+}
+/** Helper for checking one feature gate directly from a handshake response. */
+export function isFeatureEnabled(response, feature) {
+    return response.featureGates[feature] === true;
+}
+/**
+ * Negotiate capabilities between a client request and this Aegis build.
+ *
+ * Rules:
+ * - If client protocolVersion < AEGIS_MIN_PROTOCOL_VERSION → not compatible, add warning, return empty negotiatedCapabilities
+ * - If client protocolVersion > AEGIS_PROTOCOL_VERSION → compatible but add forward-compat warning
+ * - negotiatedCapabilities = intersection of server caps and clientCapabilities (or all server caps if client sends none)
+ */
+export function negotiate(req) {
+    const warnings = [];
+    const serverCapabilities = [...AEGIS_CAPABILITIES];
+    // Parse major version numbers for comparison
+    const clientMajor = parseInt(req.protocolVersion, 10);
+    const serverMajor = parseInt(AEGIS_PROTOCOL_VERSION, 10);
+    const minMajor = parseInt(AEGIS_MIN_PROTOCOL_VERSION, 10);
+    if (isNaN(clientMajor)) {
+        const negotiatedCapabilities = [];
+        return {
+            protocolVersion: AEGIS_PROTOCOL_VERSION,
+            serverCapabilities,
+            negotiatedCapabilities,
+            featureGates: computeFeatureGates(negotiatedCapabilities),
+            fallbackMode: 'invalid-protocol',
+            warnings: [`Unrecognized protocolVersion format: "${req.protocolVersion}". Expected integer string.`],
+            compatible: false,
+        };
+    }
+    if (clientMajor < minMajor) {
+        const negotiatedCapabilities = [];
+        return {
+            protocolVersion: AEGIS_PROTOCOL_VERSION,
+            serverCapabilities,
+            negotiatedCapabilities,
+            featureGates: computeFeatureGates(negotiatedCapabilities),
+            fallbackMode: 'incompatible-protocol',
+            warnings: [
+                `Client protocolVersion ${req.protocolVersion} is below minimum supported version ${AEGIS_MIN_PROTOCOL_VERSION}. Upgrade required.`,
+            ],
+            compatible: false,
+        };
+    }
+    if (clientMajor > serverMajor) {
+        warnings.push(`Client protocolVersion ${req.protocolVersion} is newer than server version ${AEGIS_PROTOCOL_VERSION}. Some client features may be unavailable.`);
+    }
+    // Intersect: client declares what it supports; server only enables what it also supports
+    let negotiatedCapabilities;
+    if (!req.clientCapabilities || req.clientCapabilities.length === 0) {
+        // Client omitted capabilities → default to full set for backward compatibility.
+        negotiatedCapabilities = serverCapabilities;
+        warnings.push('Client did not provide clientCapabilities; using legacy-default capability negotiation.');
+    }
+    else {
+        const serverSet = new Set(serverCapabilities);
+        const unknown = req.clientCapabilities.filter(c => !serverSet.has(c));
+        if (unknown.length > 0) {
+            warnings.push(`Unknown client capabilities ignored: ${unknown.join(', ')}`);
+        }
+        negotiatedCapabilities = req.clientCapabilities.filter((c) => serverSet.has(c));
+    }
+    return {
+        protocolVersion: AEGIS_PROTOCOL_VERSION,
+        serverCapabilities,
+        negotiatedCapabilities,
+        featureGates: computeFeatureGates(negotiatedCapabilities),
+        fallbackMode: req.clientCapabilities && req.clientCapabilities.length > 0 ? 'none' : 'legacy-defaults',
+        warnings,
+        compatible: true,
+    };
+}

package/dist/hook-settings.d.ts

@@ -0,0 +1,80 @@
+/**
+ * hook-settings.ts — Generate CC settings.json with HTTP hooks for Aegis.
+ *
+ * When Aegis creates a CC session, it writes a per-session settings file
+ * that configures HTTP hooks pointing to Aegis's hook receiver endpoint.
+ * The file is passed to CC via the `--settings` CLI flag.
+ *
+ * Only events that support `type: "http"` hooks are included:
+ *   Stop, PreToolUse, PostToolUse, PermissionRequest, TaskCompleted
+ *
+ * Events like Notification, SessionEnd, etc. only support `type: "command"`
+ * and are excluded.
+ *
+ * Issue #169: Phase 2 — Inject CC settings.json with HTTP hooks.
+ */
+/** Build a normalized path to .claude/settings.local.json for Unix and Windows workDirs. */
+export declare function buildProjectSettingsPath(workDir: string, platform?: NodeJS.Platform): string;
+/** CC hook events that support `type: "http"`.
+ *
+ * All CC hook events support HTTP hooks. We register the most useful ones
+ * for Aegis status detection and event forwarding.
+ *
+ * Excluded (low value for Aegis):
+ *   - InstructionsLoaded, ConfigChange (informational)
+ *   - WorktreeCreate, WorktreeRemove (worktree management)
+ *   - Elicitation, ElicitationResult (MCP-specific)
+ */
+declare const HTTP_HOOK_EVENTS: readonly ["Stop", "StopFailure", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionRequest", "TaskCompleted", "SessionStart", "SessionEnd", "UserPromptSubmit", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "FileChanged", "CwdChanged", "Notification", "TeammateIdle", "WorktreeCreate", "WorktreeRemove", "Elicitation", "ElicitationResult"];
+export { HTTP_HOOK_EVENTS };
+export type HttpHookEvent = typeof HTTP_HOOK_EVENTS[number];
+/** Shape of a single HTTP hook entry in CC settings.json. */
+interface HttpHookConfig {
+    type: 'http';
+    url: string;
+    headers?: Record<string, string>;
+}
+/** Shape of the `hooks` section in CC settings.json. */
+export interface HookSettings {
+    hooks: Record<string, Array<{
+        matcher?: string;
+        hooks: HttpHookConfig[];
+    }>>;
+}
+/**
+ * Generate the hooks section of a CC settings.json for a given session.
+ *
+ * @param baseUrl - Aegis base URL (e.g. "http://localhost:9100")
+ * @param sessionId - Aegis session ID (used as query param for routing)
+ * @param hookSecret - Per-session secret for hook URL authentication (Issue #629)
+ */
+export declare function generateHookSettings(baseUrl: string, sessionId: string, hookSecret?: string): HookSettings;
+/**
+ * Write hook settings to a temporary file and return its path.
+ *
+ * Issue #339: Reads .claude/settings.local.json from workDir and deep-merges
+ * hook settings into it, so CC gets both project settings (env vars, permissions,
+ * bypassPermissions) AND Aegis hooks in a single --settings file.
+ *
+ * @param baseUrl - Aegis base URL
+ * @param sessionId - Aegis session ID
+ * @param workDir - Project working directory (to read settings.local.json from)
+ * @returns Path to the temporary settings file
+ */
+export declare function writeHookSettingsFile(baseUrl: string, sessionId: string, hookSecret: string, workDir?: string): Promise<string>;
+/**
+ * Clean up a hook settings temp file.
+ *
+ * @param filePath - Path to the temporary settings file
+ */
+export declare function cleanupHookSettingsFile(filePath: string): Promise<void>;
+/**
+ * Issue #936: Clean stale session hooks from settings.local.json before writing new hooks.
+ *
+ * When sessions die, their hook URLs remain in settings.local.json.
+ * On restart, CC loads these dead hooks and crashes.
+ *
+ * @param workDir - Project working directory
+ * @param activeSessionIds - Set of currently active session IDs
+ */
+export declare function cleanupStaleSessionHooks(workDir: string, activeSessionIds: Set<string>): Promise<void>;

package/dist/hook-settings.js

@@ -0,0 +1,272 @@
+/**
+ * hook-settings.ts — Generate CC settings.json with HTTP hooks for Aegis.
+ *
+ * When Aegis creates a CC session, it writes a per-session settings file
+ * that configures HTTP hooks pointing to Aegis's hook receiver endpoint.
+ * The file is passed to CC via the `--settings` CLI flag.
+ *
+ * Only events that support `type: "http"` hooks are included:
+ *   Stop, PreToolUse, PostToolUse, PermissionRequest, TaskCompleted
+ *
+ * Events like Notification, SessionEnd, etc. only support `type: "command"`
+ * and are excluded.
+ *
+ * Issue #169: Phase 2 — Inject CC settings.json with HTTP hooks.
+ */
+import { readFile, writeFile, unlink, mkdir, rmdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { ccSettingsSchema, containsTraversalSegment } from './validation.js';
+import { secureFilePermissions } from './file-utils.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseSettingsWithFallback(raw) {
+    // Windows editors may write UTF-8 BOM; strip it so JSON.parse does not fail.
+    const json = JSON.parse(raw.replace(/^\uFEFF/, ''));
+    if (!isRecord(json))
+        return undefined;
+    const parsed = ccSettingsSchema.safeParse(json);
+    if (parsed.success)
+        return parsed.data;
+    // Preserve unknown/extra fields (including env vars) even when schema validation fails.
+    return json;
+}
+function normalizeHookBaseUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        if (url.hostname === '0.0.0.0' || url.hostname === '::' || url.hostname === '[::]') {
+            url.hostname = '127.0.0.1';
+        }
+        return url.origin;
+    }
+    catch {
+        return baseUrl.replace('0.0.0.0', '127.0.0.1');
+    }
+}
+/** Build a normalized path to .claude/settings.local.json for Unix and Windows workDirs. */
+export function buildProjectSettingsPath(workDir, platform = process.platform) {
+    let normalizedWorkDir = platform === 'win32'
+        ? workDir.replace(/\//g, '\\')
+        : workDir.replace(/\\/g, '/');
+    // On Linux, resolve() prepends CWD to Windows paths like "D:\Users\dev"
+    // because Linux doesn't understand Windows drive letters. Only resolve
+    // paths that are NOT already absolute on the target platform.
+    const isWinAbs = /^[A-Za-z]:\\/.test(normalizedWorkDir);
+    const isUnixAbs = /^\//.test(normalizedWorkDir);
+    const alreadyAbs = (platform === 'win32' && isWinAbs) || isUnixAbs;
+    if (!alreadyAbs)
+        normalizedWorkDir = resolve(normalizedWorkDir);
+    // Normalize separators to match the target platform.
+    const result = join(normalizedWorkDir, '.claude', 'settings.local.json');
+    return platform === 'win32' ? result.replace(/\//g, '\\') : result;
+}
+/**
+ * Validate a workDir path for use in hook settings resolution.
+ * Defense-in-depth against path traversal: rejects paths containing ".." segments
+ * or that resolve outside the provided workDir.
+ *
+ * @returns Sanitized absolute path, or undefined if validation fails.
+ */
+function validateWorkDirPath(workDir) {
+    if (containsTraversalSegment(workDir))
+        return undefined;
+    return resolve(workDir);
+}
+/** CC hook events that support `type: "http"`.
+ *
+ * All CC hook events support HTTP hooks. We register the most useful ones
+ * for Aegis status detection and event forwarding.
+ *
+ * Excluded (low value for Aegis):
+ *   - InstructionsLoaded, ConfigChange (informational)
+ *   - WorktreeCreate, WorktreeRemove (worktree management)
+ *   - Elicitation, ElicitationResult (MCP-specific)
+ */
+const HTTP_HOOK_EVENTS = [
+    // Status detection (highest value)
+    'Stop',
+    'StopFailure',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'PermissionRequest',
+    'TaskCompleted',
+    // Session lifecycle
+    'SessionStart',
+    'SessionEnd',
+    'UserPromptSubmit',
+    // Subagent tracking
+    'SubagentStart',
+    'SubagentStop',
+    // Context management
+    'PreCompact',
+    'PostCompact',
+    // File & directory changes
+    'FileChanged',
+    'CwdChanged',
+    // Notifications
+    'Notification',
+    'TeammateIdle',
+    // Worktree management (only Create/Remove — *Failed variants don't exist in CC, see #1002)
+    'WorktreeCreate',
+    'WorktreeRemove',
+    // Elicitation
+    'Elicitation',
+    'ElicitationResult',
+];
+export { HTTP_HOOK_EVENTS };
+/**
+ * Generate the hooks section of a CC settings.json for a given session.
+ *
+ * @param baseUrl - Aegis base URL (e.g. "http://localhost:9100")
+ * @param sessionId - Aegis session ID (used as query param for routing)
+ * @param hookSecret - Per-session secret for hook URL authentication (Issue #629)
+ */
+export function generateHookSettings(baseUrl, sessionId, hookSecret) {
+    const hooks = {};
+    const callbackBaseUrl = normalizeHookBaseUrl(baseUrl);
+    for (const event of HTTP_HOOK_EVENTS) {
+        const hookConfig = {
+            type: 'http',
+            url: `${callbackBaseUrl}/v1/hooks/${event}?sessionId=${sessionId}`,
+        };
+        if (hookSecret) {
+            hookConfig.headers = { 'X-Hook-Secret': hookSecret };
+        }
+        hooks[event] = [
+            {
+                hooks: [hookConfig],
+            },
+        ];
+    }
+    return { hooks };
+}
+/**
+ * Write hook settings to a temporary file and return its path.
+ *
+ * Issue #339: Reads .claude/settings.local.json from workDir and deep-merges
+ * hook settings into it, so CC gets both project settings (env vars, permissions,
+ * bypassPermissions) AND Aegis hooks in a single --settings file.
+ *
+ * @param baseUrl - Aegis base URL
+ * @param sessionId - Aegis session ID
+ * @param workDir - Project working directory (to read settings.local.json from)
+ * @returns Path to the temporary settings file
+ */
+export async function writeHookSettingsFile(baseUrl, sessionId, hookSecret, workDir) {
+    const hookSettings = generateHookSettings(baseUrl, sessionId, hookSecret);
+    // Issue #339: Read project's settings.local.json and merge hooks into it.
+    // This ensures CC gets env vars, permissions, and bypassPermissions alongside hooks.
+    // Issue #847: Validate workDir path to prevent traversal attacks.
+    let merged = {};
+    const safeWorkDir = workDir ? validateWorkDirPath(workDir) : undefined;
+    if (safeWorkDir) {
+        const projectSettingsPath = buildProjectSettingsPath(safeWorkDir);
+        if (existsSync(projectSettingsPath)) {
+            try {
+                const raw = await readFile(projectSettingsPath, 'utf-8');
+                merged = parseSettingsWithFallback(raw) ?? {};
+            }
+            catch {
+                // Malformed settings file — use empty base, hooks will still work
+            }
+        }
+    }
+    // Deep-merge: project settings as base, hooks merged by event key so both
+    // project-level and Aegis hooks coexist (Issue #635).
+    const existingHooks = merged.hooks ?? {};
+    const mergedHooks = { ...existingHooks };
+    for (const [event, entries] of Object.entries(hookSettings.hooks)) {
+        mergedHooks[event] = [...(existingHooks[event] ?? []), ...entries];
+    }
+    const combined = { ...merged, hooks: mergedHooks };
+    // Issue #931: Always inject MCP_CONNECTION_NONBLOCKING so CC does not block
+    // on MCP server connections when launched via Aegis orchestration.
+    (combined.env = (combined.env || {}));
+    (combined.env || {})["MCP_CONNECTION_NONBLOCKING"] = "true";
+    // Issue #648: Use unpredictable directory name and restrictive permissions
+    // to prevent symlink attacks and information disclosure in /tmp.
+    const suffix = randomBytes(4).toString('hex');
+    const settingsDir = join(tmpdir(), `aegis-hooks-${suffix}`);
+    await mkdir(settingsDir, { recursive: true, mode: 0o700 });
+    const filePath = join(settingsDir, `hooks-${sessionId}.json`);
+    await writeFile(filePath, JSON.stringify(combined, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    await secureFilePermissions(filePath);
+    return filePath;
+}
+/**
+ * Clean up a hook settings temp file.
+ *
+ * @param filePath - Path to the temporary settings file
+ */
+export async function cleanupHookSettingsFile(filePath) {
+    try {
+        if (existsSync(filePath)) {
+            await unlink(filePath);
+            // Issue #648: Also remove the randomized parent directory
+            const parentDir = join(filePath, '..');
+            await rmdir(parentDir).catch(() => {
+                // Non-fatal: directory may not be empty or already removed
+            });
+        }
+    }
+    catch {
+        // Non-fatal: temp file cleanup failed
+    }
+}
+/**
+ * Issue #936: Clean stale session hooks from settings.local.json before writing new hooks.
+ *
+ * When sessions die, their hook URLs remain in settings.local.json.
+ * On restart, CC loads these dead hooks and crashes.
+ *
+ * @param workDir - Project working directory
+ * @param activeSessionIds - Set of currently active session IDs
+ */
+export async function cleanupStaleSessionHooks(workDir, activeSessionIds) {
+    const safeWorkDir = workDir ? validateWorkDirPath(workDir) : undefined;
+    if (!safeWorkDir)
+        return;
+    const projectSettingsPath = buildProjectSettingsPath(safeWorkDir);
+    if (!existsSync(projectSettingsPath))
+        return;
+    try {
+        const raw = await readFile(projectSettingsPath, 'utf-8');
+        const parsed = ccSettingsSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success)
+            return;
+        const settings = parsed.data;
+        const hooks = settings.hooks;
+        if (!hooks)
+            return;
+        let changed = false;
+        for (const [event, eventHooks] of Object.entries(hooks)) {
+            const filtered = eventHooks.filter(entry => {
+                const httpHook = entry.hooks?.find(h => h.type === 'http');
+                if (!httpHook)
+                    return true;
+                const url = httpHook.url;
+                const match = url.match(/[?&]sessionId=([^&]+)/);
+                if (!match)
+                    return true;
+                const sessionId = match[1];
+                if (!activeSessionIds.has(sessionId)) {
+                    changed = true;
+                    return false;
+                }
+                return true;
+            });
+            hooks[event] = filtered;
+        }
+        if (changed) {
+            await writeFile(projectSettingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+            await secureFilePermissions(projectSettingsPath);
+        }
+    }
+    catch {
+        // Non-fatal: cleanup failed
+    }
+}

package/dist/hook.d.ts

@@ -0,0 +1,19 @@
+#!/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 }]
+ *     }]
+ *   }
+ * }
+ */
+/** Build a shell-safe command string that invokes hook.js with an explicit Node executable. */
+export declare function buildHookCommand(scriptPath: string, nodeExecutable?: string, platform?: NodeJS.Platform): string;