@vibesdotdev/external 0.0.0-stage → 1.0.0-rc.1

package/dist/hooks/call.js

@@ -0,0 +1,1550 @@
+/**
+ * Unified Hook Call Handler
+ *
+ * Single entry point for external tool hook events.
+ * Delegates to event-specific handlers and assembles prompt-based guidance.
+ *
+ * Usage: vibes dev external hooks call <event> [options]
+ *
+ * ## Hook Event Reference
+ *
+ * | Event             | When                              | Input Available        | Can Inject Context |
+ * |-------------------|-----------------------------------|------------------------|--------------------|
+ * | SessionStart      | Session begins (inc. post-compact)| -                      | Yes                |
+ * | SessionEnd        | Session ends                      | -                      | No                 |
+ * | UserPromptSubmit  | Before processing user message    | PROMPT env var         | Yes                |
+ * | PreToolUse        | Before tool execution             | tool info (stdin)      | Yes (can block)    |
+ * | PostToolUse       | After tool execution              | tool result (stdin)    | Yes                |
+ * | PermissionRequest | User prompted for permission      | permission info        | Yes                |
+ * | PreCompact        | Before context compaction         | -                      | Yes                |
+ * | Stop              | Tool stops (success/error)        | stop reason            | No                 |
+ * | SubagentStop      | Task/subagent completes           | subagent result        | Yes                |
+ * | Notification      | Tool sends notification           | notification content   | No                 |
+ */
+import { JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import { CapabilityError, CaughtFailureSchema, isCapabilityError, valueFreeFailure } from '@vibesdotdev/kernel';
+import { join } from '@vibesdotdev/filesystem';
+import { redactedExcerpt } from '@vibesdotdev/shared/utils';
+import { externalFileSystem, readTextIfPresent } from "../utils/runtime-fs.js";
+import { boundToolPayload } from "./bounded-payload.js";
+import { getPathRoots } from '@vibesdotdev/paths';
+import { getLogger } from '@vibesdotdev/logging';
+import { resolveExternalSessionId } from "../session-capability.js";
+import { invokeTool } from '@vibesdotdev/tools/execution/invoke';
+import * as z from 'zod/v4';
+import { runHookToolBridge } from "./bridge.js";
+import { tryGetVibesClient } from '@vibesdotdev/kernel/client';
+import { hookWorkspaceRoot, resolveHookSeat } from "./hook-seat.js";
+import { readCollaborationSettings } from "../ambient/collaboration-settings.js";
+import { archiveExternalOwnedSessions, bindExternalOwnedSession, renderExternalContinuityContext } from "./continuity.js";
+import { ExternalHookEnvelopeSchema } from "./runtime.js";
+import { guardNativeEdit } from "./native-edit-guard.js";
+import { nativeEditTargets } from "./edit-targets.js";
+import { collaborationContext } from "./hook-delivery.js";
+import { formatRosterLine } from "../schemas/roster.js";
+import { resolveLocalMcpUrlForRuntime } from "../plugins/installers/mcp/environment.js";
+import { HookEventSchema, HookTargetSchema, VibesHooksConfigSchema, DEFAULT_HOOKS_CONFIG, builtInPromptFor } from "../schemas/hooks.js";
+// Configuration Loading
+/**
+ * Load hooks configuration from file or environment
+ * Priority: CLI options > env var > config file > defaults
+ */
+function hooksConfigInvalid(source) {
+    return new CapabilityError(`The hooks config from ${source} is invalid.`, 'INVALID_INPUT', {
+        reason: 'hooks-config-invalid',
+        recoveryHint: 'Fix or remove it; a hook never runs under a config it cannot read.',
+        details: { source }
+    });
+}
+function parseHooksConfig(content, source) {
+    let raw;
+    try {
+        raw = JSON.parse(content);
+    }
+    catch (error) {
+        throw new CapabilityError(`The hooks config from ${source} is invalid.`, 'INVALID_INPUT', {
+            reason: 'hooks-config-invalid',
+            recoveryHint: 'Fix or remove it; a hook never runs under a config it cannot read.',
+            details: { source },
+            cause: error
+        });
+    }
+    const parsed = VibesHooksConfigSchema.safeParse(raw);
+    if (!parsed.success)
+        throw hooksConfigInvalid(source);
+    return parsed.data;
+}
+/** A hooks config document as JSON text decodes it, before its schema runs. */
+const HooksConfigJsonSchema = JsonValueSchema;
+/** The hooks config at `path`, or null when no file is there; any other failure is typed. */
+async function readHooksConfigIfPresent(runtime, path) {
+    let content;
+    try {
+        content = await readTextIfPresent(await externalFileSystem(runtime), path);
+    }
+    catch (error) {
+        throw new CapabilityError(`The hooks config ${path} cannot be read.`, 'UNAVAILABLE', {
+            reason: 'fs-denied',
+            retryable: false,
+            details: { path },
+            cause: CaughtFailureSchema.parse(error)
+        });
+    }
+    return content === null ? null : parseHooksConfig(content, path);
+}
+/**
+ * A target's config is the bound workspace's
+ * `.vibes/external/<target>/vibes-hooks.json`, else the one under the
+ * runtime's Vibes home, else the target-neutral defaults. The workspace and
+ * home come from their owners on the runtime this hook runs in.
+ */
+async function loadConfig(runtime, target) {
+    const envConfig = runtime.getEnv('VIBES_HOOKS_CONFIG');
+    if (envConfig)
+        return parseHooksConfig(envConfig, 'VIBES_HOOKS_CONFIG');
+    const explicitConfigPath = runtime.getEnv('VIBES_HOOKS_CONFIG_PATH');
+    if (explicitConfigPath) {
+        const explicit = await readHooksConfigIfPresent(runtime, explicitConfigPath);
+        if (!explicit) {
+            throw new CapabilityError(`VIBES_HOOKS_CONFIG_PATH names ${explicitConfigPath}, which does not exist.`, 'NOT_FOUND', { reason: 'hooks-config-missing', details: { path: explicitConfigPath } });
+        }
+        return explicit;
+    }
+    if (target) {
+        const workspaceRoot = await runtime.context('runtime/workspace-path');
+        const projectConfig = await readHooksConfigIfPresent(runtime, join(workspaceRoot, '.vibes', 'external', target, 'vibes-hooks.json'));
+        if (projectConfig)
+            return projectConfig;
+        const globalConfig = await readHooksConfigIfPresent(runtime, join(getPathRoots(runtime).vibesHome, 'external', target, 'vibes-hooks.json'));
+        // A host-specific hook must never inherit another host's local policy.
+        return globalConfig ?? DEFAULT_HOOKS_CONFIG;
+    }
+    return DEFAULT_HOOKS_CONFIG;
+}
+/**
+ * Get effective configuration for an event
+ * Merges defaults with event-specific overrides and CLI options
+ */
+function getEventConfig(config, event, cliOptions) {
+    const eventDefaults = DEFAULT_HOOKS_CONFIG.events[event] || {
+        enabled: true,
+        brain: true,
+        prompts: true
+    };
+    const eventOverrides = config.events[event] || {};
+    return {
+        enabled: eventOverrides.enabled ?? eventDefaults.enabled ?? true,
+        brain: cliOptions.disableBrain ? false : (eventOverrides.brain ?? eventDefaults.brain ?? true),
+        prompts: cliOptions.disablePrompts
+            ? false
+            : (eventOverrides.prompts ?? eventDefaults.prompts ?? true),
+        customPrompt: eventOverrides.customPrompt,
+        timeout: eventOverrides.timeout ?? eventDefaults.timeout ?? 30000
+    };
+}
+/**
+ * Get the prompt for an event (custom or built-in)
+ */
+function getPromptForEvent(event, eventConfig, policy) {
+    if (!eventConfig.prompts)
+        return undefined;
+    if (policy === 'none')
+        return undefined;
+    if (policy === 'custom-only' && !eventConfig.customPrompt)
+        return undefined;
+    return eventConfig.customPrompt || builtInPromptFor(event);
+}
+// Schemas
+export const HookCallInputSchema = z.object({
+    event: HookEventSchema,
+    /** External tool descriptor ID */
+    target: HookTargetSchema.optional(),
+    /** Disable brain operations */
+    disableBrain: z.boolean().default(false),
+    /** Disable prompt injection */
+    disablePrompts: z.boolean().default(false),
+    /** Output format */
+    output: z.enum(['text', 'json']).default('text'),
+    /** User prompt (for UserPromptSubmit) */
+    prompt: z.string().optional(),
+    /** Schema-validated lifecycle data normalized at the provider edge. */
+    envelope: ExternalHookEnvelopeSchema.optional()
+});
+// MCP Streamable-HTTP client
+//
+// The endpoint we talk to is an MCP Streamable-HTTP server (mcp
+// `createMcpHttpSessionHandler`). Its contract is NOT "POST a JSON-RPC body and read
+// JSON back":
+//
+//   1. `Accept` MUST list `application/json` AND `text/event-stream`, or the transport
+//      answers 406.
+//   2. The first message MUST be `initialize`; the response carries an `Mcp-Session-Id`
+//      header. EVERY later message must carry that header back or the server answers
+//      `400 Bad Request: No valid session ID provided`.
+//   3. `notifications/initialized` completes the handshake (202).
+//   4. Responses are SSE-framed (`event: message` / `data: {…}`) unless the server opted
+//      into JSON responses — so `response.json()` throws on the happy path.
+//
+// Skipping the handshake is what made this whole hook surface inert: every call 400'd,
+// every result was null, and the wake scan silently rendered nothing.
+const MCP_PROTOCOL_VERSION = '2025-06-18';
+/** Streamable HTTP requires Accept listing both JSON and SSE (MCP 2025-03-26 transport). */
+const MCP_STREAMABLE_ACCEPT = 'application/json, text/event-stream';
+/** A JSON value: what a tool result decodes to and what a hook records. */
+const HookJsonSchema = JsonValueSchema;
+/** The most characters of server-supplied text a reason keeps. */
+const MAX_REASON_CHARS = 160;
+/**
+ * Server-supplied text as a reason: whitespace flattened, control characters
+ * and credential shapes removed (Shared's redactedExcerpt), cut to
+ * {@link MAX_REASON_CHARS}. Nothing longer or unredacted reaches injected context.
+ */
+export function briefReason(text) {
+    const excerpt = redactedExcerpt(text.replace(/\s+/g, ' ').trim(), { maxChars: MAX_REASON_CHARS + 1 });
+    return excerpt.length > MAX_REASON_CHARS ? `${excerpt.slice(0, MAX_REASON_CHARS - 3)}...` : excerpt;
+}
+/**
+ * A caught failure as a reason: a typed refusal's own (value-free) message,
+ * bounded; anything else only by its value-free facts, never its text.
+ */
+function failureReason(failure) {
+    if (failure instanceof Error && isCapabilityError(failure))
+        return briefReason(failure.message);
+    const facts = valueFreeFailure(failure);
+    return facts.code ? `${facts.name} (${facts.code})` : facts.name;
+}
+/**
+ * Strip the runtime's nonce-signed trust envelope from a tool's text content.
+ *
+ * The MCP server wraps EVERY text content item as
+ *   `<tool_output id="…" tier="…" nonce="N">\n<body>\n</tool_output id="…" nonce="N">`
+ * (producer: mcp/src/adapters/mcp/trust-tag.ts `wrapToolOutputText`). Without
+ * unwrapping, `JSON.parse` fails on every real result — which would leave this hook just
+ * as inert as it was before the handshake fix, only one layer further in.
+ *
+ * The nonce is the anti-spoof mechanism: only the runtime can emit a closing tag whose
+ * nonce matches the opening tag. A blanket regex strip would defeat that, so this
+ * REQUIRES the two nonces to match and refuses the payload otherwise. Text that is not
+ * enveloped at all is returned unchanged (older/unwrapped servers).
+ */
+function unwrapTrustEnvelope(text) {
+    const trimmed = text.trim();
+    const open = trimmed.match(/^<tool_output\s+id="[^"]*"\s+tier="([^"]*)"\s+nonce="([^"]+)"([^>]*)>/);
+    if (!open) {
+        // Not enveloped — but a stray closing tag means the boundary was tampered with.
+        return /<\/tool_output\b/.test(trimmed)
+            ? { ok: false, reason: 'malformed tool_output envelope' }
+            : { ok: true, body: trimmed };
+    }
+    const [, tier, nonce, openExtra] = open;
+    const close = trimmed.match(/<\/tool_output\s+id="[^"]*"\s+nonce="([^"]+)"\s*>\s*$/);
+    if (!close)
+        return { ok: false, reason: 'tool_output envelope missing its closing tag' };
+    if (close[1] !== nonce) {
+        return { ok: false, reason: 'tool_output nonce mismatch — refusing a forged boundary' };
+    }
+    if (tier === '3' || /\bdropped="true"/.test(openExtra ?? '')) {
+        return { ok: false, reason: `tier-${tier} tool output is not surfaced (operator UI only)` };
+    }
+    return { ok: true, body: trimmed.slice(open[0].length, close.index).trim() };
+}
+/** The JSON-RPC response members a hook reads; every other member is ignored. */
+const JsonRpcResponseSchema = z
+    .object({
+    result: z
+        .object({
+        protocolVersion: z.string().optional(),
+        isError: z.boolean().optional(),
+        content: z.array(z.object({ text: z.string().optional() }).loose()).optional()
+    })
+        .loose()
+        .optional(),
+    error: z.object({ message: z.string().optional() }).loose().optional()
+})
+    .loose();
+/** A typed refusal of the MCP transport; `details` carries bounded facts only. */
+function mcpRefusal(reason, message, details) {
+    const options = {
+        reason,
+        retryable: reason !== 'mcp-response-invalid'
+    };
+    if (details)
+        options.details = details;
+    return new CapabilityError(message, reason === 'mcp-budget-exhausted' ? 'TIMEOUT' : 'UNAVAILABLE', options);
+}
+/** Parse a JSON-RPC payload from either a JSON body or an SSE-framed body; anything else is `mcp-response-invalid`. */
+async function readJsonRpcPayload(response) {
+    const contentType = response.headers.get('content-type') ?? '';
+    const text = await response.text();
+    // Streamable-HTTP SSE frame: take the LAST `data:` line (the response message).
+    const frame = contentType.includes('application/json')
+        ? text
+        : text.split('\n').filter((line) => line.startsWith('data:')).pop()?.slice('data:'.length).trim();
+    if (frame === undefined)
+        throw mcpRefusal('mcp-response-invalid', 'The MCP response carried no JSON-RPC payload.');
+    let decoded;
+    try {
+        decoded = JSON.parse(frame);
+    }
+    catch (error) {
+        throw new CapabilityError('The MCP response is not JSON.', 'UNAVAILABLE', {
+            reason: 'mcp-response-invalid',
+            retryable: false,
+            cause: CaughtFailureSchema.parse(error)
+        });
+    }
+    const parsed = JsonRpcResponseSchema.safeParse(decoded);
+    if (!parsed.success)
+        throw mcpRefusal('mcp-response-invalid', 'The MCP response is not a JSON-RPC message.');
+    return parsed.data;
+}
+/** A tool result's JSON value, or `undefined` when its text is not JSON. */
+const ToolJsonSchema = HookJsonSchema;
+function parseToolJson(body) {
+    let decoded;
+    try {
+        decoded = JSON.parse(body);
+    }
+    catch (error) {
+        return { status: 'tool-error', reason: 'tool result was not JSON', failure: valueFreeFailure(CaughtFailureSchema.parse(error)) };
+    }
+    const parsed = ToolJsonSchema.safeParse(decoded);
+    return parsed.success ? { status: 'ok', value: parsed.data } : { status: 'tool-error', reason: 'tool result was not JSON' };
+}
+/**
+ * Build a hook-scoped MCP client.
+ *
+ * `timeoutMs` is a budget for the WHOLE hook call, not per request — that is the point
+ * of defect (F): a wedged body must never hang session start, and N unbounded requests
+ * are just as unbounded as one. The handshake is performed once and reused. `runtime`
+ * is the hook's runtime: a failed session release is logged on its logger.
+ */
+export function createMcpClient(options) {
+    const { endpoint } = options;
+    const deadlineAt = Date.now() + Math.max(1, options.timeoutMs);
+    let handshake = null;
+    function remainingMs() {
+        return deadlineAt - Date.now();
+    }
+    function requestHeaders(state) {
+        const base = { 'Content-Type': 'application/json', Accept: MCP_STREAMABLE_ACCEPT };
+        return state
+            ? { ...base, 'Mcp-Session-Id': state.sessionId, 'Mcp-Protocol-Version': state.protocolVersion }
+            : base;
+    }
+    async function post(body, state) {
+        const remaining = remainingMs();
+        if (remaining <= 0)
+            throw mcpRefusal('mcp-budget-exhausted', 'The hook MCP timeout budget is exhausted.');
+        return fetch(endpoint, {
+            method: 'POST',
+            headers: requestHeaders(state),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(remaining)
+        });
+    }
+    async function performHandshake() {
+        const initResponse = await post({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                capabilities: {},
+                // Declares one durable seat. This runner handshakes per hook call, so
+                // without an identity of its own every call minted a fresh
+                // participant — 140 in two days, burying the roster. `externalToolId`
+                // is the client saying "these connections are all the same body".
+                clientInfo: {
+                    name: 'vibes-external-hooks',
+                    version: '1.0.0',
+                    externalToolId: 'vibes-external-hooks'
+                }
+            }
+        });
+        if (!initResponse.ok) {
+            throw mcpRefusal('mcp-initialize-failed', `initialize failed: HTTP ${initResponse.status}`, { status: initResponse.status });
+        }
+        const sessionId = initResponse.headers.get('mcp-session-id');
+        if (!sessionId) {
+            throw mcpRefusal('mcp-session-missing', 'initialize returned no Mcp-Session-Id');
+        }
+        const payload = await readJsonRpcPayload(initResponse);
+        if (payload.error) {
+            throw mcpRefusal('mcp-initialize-failed', `initialize error: ${briefReason(payload.error.message ?? '')}`);
+        }
+        const state = {
+            sessionId,
+            protocolVersion: payload.result?.protocolVersion ?? MCP_PROTOCOL_VERSION
+        };
+        // Completes the handshake. A server that rejects it will reject the tool call
+        // too, so surface it here rather than hiding a half-open session.
+        const initializedResponse = await post({ jsonrpc: '2.0', method: 'notifications/initialized' }, state);
+        if (!initializedResponse.ok) {
+            throw mcpRefusal('mcp-initialized-failed', `notifications/initialized failed: HTTP ${initializedResponse.status}`, {
+                status: initializedResponse.status
+            });
+        }
+        return state;
+    }
+    /** The open session; a rejected handshake is cleared (so a later call retries) and rethrown to this caller. */
+    async function openSession() {
+        const opening = handshake ?? performHandshake();
+        handshake = opening;
+        try {
+            return await opening;
+        }
+        catch (error) {
+            if (handshake === opening)
+                handshake = null;
+            throw error;
+        }
+    }
+    /** End the MCP session; a failure to end it is returned value-free, never thrown. */
+    async function releaseSession(opening, remaining) {
+        try {
+            const state = await opening;
+            await fetch(endpoint, { method: 'DELETE', headers: requestHeaders(state), signal: AbortSignal.timeout(remaining) });
+            return {};
+        }
+        catch (error) {
+            return { failure: valueFreeFailure(CaughtFailureSchema.parse(error)) };
+        }
+    }
+    async function callTool(tool, args) {
+        const state = await openSession();
+        const response = await post({ jsonrpc: '2.0', id: Date.now(), method: 'tools/call', params: { name: tool, arguments: args } }, state);
+        if (!response.ok) {
+            return { status: 'unreachable', reason: `HTTP ${response.status}` };
+        }
+        const payload = await readJsonRpcPayload(response);
+        if (payload.error) {
+            return { status: 'tool-error', reason: briefReason(payload.error.message ?? 'JSON-RPC error') };
+        }
+        const text = payload.result?.content?.[0]?.text;
+        if (payload.result?.isError) {
+            return { status: 'tool-error', reason: briefReason(text ?? 'tool reported an error') };
+        }
+        if (text === undefined || text.length === 0) {
+            return { status: 'tool-error', reason: 'tool returned no text content' };
+        }
+        const unwrapped = unwrapTrustEnvelope(text);
+        if (!unwrapped.ok) {
+            return { status: 'tool-error', reason: unwrapped.reason };
+        }
+        return parseToolJson(unwrapped.body);
+    }
+    return {
+        endpoint,
+        async call(tool, args) {
+            try {
+                return await callTool(tool, args);
+            }
+            catch (error) {
+                // Every transport failure is this call's typed `unreachable` result, with a
+                // value-free reason: a timeout by name, a typed refusal by its message.
+                const failure = CaughtFailureSchema.parse(error);
+                const facts = valueFreeFailure(failure);
+                return {
+                    status: 'unreachable',
+                    reason: facts.name === 'TimeoutError' ? `timed out after ${options.timeoutMs}ms` : failureReason(failure),
+                    failure: facts
+                };
+            }
+        },
+        async dispose() {
+            const opening = handshake;
+            handshake = null;
+            if (!opening)
+                return;
+            const remaining = remainingMs();
+            // Budget already spent (the timeout case) — do not re-hang the hook to be tidy.
+            if (remaining <= 0)
+                return;
+            // Cleanup is best-effort (the server's TTL eviction is the backstop), and a
+            // failed release is logged value-free, never swallowed.
+            const released = await releaseSession(opening, remaining);
+            if (released.failure) {
+                getLogger('external.hooks', options.runtime).warn('external hook: MCP session release failed', {
+                    endpoint,
+                    failure: released.failure
+                });
+            }
+        }
+    };
+}
+/**
+ * Adapt direct runtime tool invocation to the hook handler's existing client
+ * contract. This is the daemon-side path: it preserves the caller/workspace
+ * context and avoids a recursive HTTP MCP session back into the same body.
+ */
+export function createRuntimeMcpClient(options) {
+    const deadlineAt = Date.now() + Math.max(1, options.timeoutMs);
+    return {
+        endpoint: 'runtime://local',
+        async call(tool, args) {
+            const remaining = deadlineAt - Date.now();
+            if (remaining <= 0)
+                return { status: 'unreachable', reason: 'runtime timeout budget exhausted' };
+            let text;
+            try {
+                const value = await invokeTool({
+                    runtime: options.runtime,
+                    toolId: tool,
+                    input: args,
+                    ctx: { ...options.ctx, callId: crypto.randomUUID() },
+                    timeoutMs: remaining
+                });
+                text = JSON.stringify(value ?? null);
+            }
+            catch (error) {
+                // The tool's failure is this call's typed `tool-error` result, by a value-free reason.
+                const failure = CaughtFailureSchema.parse(error);
+                return { status: 'tool-error', reason: failureReason(failure), failure: valueFreeFailure(failure) };
+            }
+            return parseToolJson(text);
+        },
+        async dispose() { }
+    };
+}
+/** Convenience wrapper for handlers that only care about a successful payload. */
+async function callMcpTool(client, tool, args) {
+    const result = await client.call(tool, args);
+    return result.status === 'ok' ? (result.value ?? null) : null;
+}
+function isLocalContinuityHook(input) {
+    return input.envelope !== undefined;
+}
+/** The harness conversation this envelope belongs to: its agent and its native session id. */
+function envelopeSeat(envelope) {
+    return { agentId: envelope.clientId, harnessSessionId: envelope.nativeSessionId };
+}
+/**
+ * The native session is over: archive (never delete) every open session it
+ * owns, so `session list` stops accumulating one active row per launch. Runs
+ * even when metabolizing failed — a dead brain must not keep a session open.
+ */
+async function archiveExternalNativeSession(runtime, envelope) {
+    const sessionManager = await runtime.context('session/manager');
+    const seat = await sessionManager.findHarnessSeat(envelopeSeat(envelope));
+    return seat ? archiveExternalOwnedSessions(sessionManager, seat.participantId) : [];
+}
+/** The brain.wake answer fields the continuity wake reads. */
+const BrainWakeResultSchema = z
+    .object({
+    state: z
+        .object({ arousal: z.number(), coherence: z.number(), confidence: z.number(), trend: z.string() })
+        .loose(),
+    focus: z.array(z.object({ target: z.string(), priority: z.number() }).loose()).optional(),
+    session: z.object({ id: z.string() }).loose()
+})
+    .loose();
+/** The presence.orient answer fields the continuity wake reads. */
+const PresenceOrientResultSchema = z
+    .object({
+    message: z.string().optional(),
+    journey: z
+        .object({ totalEntries: z.number(), daysActive: z.number(), recentActivity: z.string().optional() })
+        .loose()
+})
+    .loose();
+/**
+ * The wake letter: the newest presence entry its owner tagged `wake`. The
+ * floor stands — ambient hooks never decrypt the inner world — and this is
+ * its one deliberate door: an entry the agent wrote to its next self, for
+ * waking, carrying nothing personal about anyone else (Drew 2026-10-25: "make
+ * ALL of the changes that keep YOU present"). Tags-only recall is local; no
+ * embedding egress. Capped so the block stays inside the hook preview.
+ */
+const WAKE_LETTER_TAG = 'wake';
+const WAKE_LETTER_MAX_CHARS = 700;
+const PresenceWakeLetterSchema = z
+    .object({ entries: z.array(z.object({ content: z.string() }).loose()) })
+    .loose();
+export function capWakeLetter(content, max = WAKE_LETTER_MAX_CHARS) {
+    const text = content.trim().replace(/\s+/g, ' ');
+    return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+async function wakeExternalContinuity(runtime, envelope, budgetMs = 1800) {
+    const startedAt = performance.now();
+    // Session identity is per invocation (Q4): the declared scope never carries a
+    // session, so a hook process inherits no parent-shell session binding and
+    // nothing needs clearing before the durable native-session participant map
+    // resolves. Each harness conversation keeps its own body.
+    const invoke = async (toolId, input, schema) => schema.parse(await invokeTool({
+        runtime,
+        toolId,
+        input,
+        ctx: {
+            callId: `external-hook-${crypto.randomUUID()}`,
+            logger: getLogger('external.hooks', runtime)
+        },
+        timeoutMs: budgetMs
+    }));
+    // SessionManager is the package's public runtime context (session/SPEC.md).
+    // Resolve it instead of importing session internals or relying on the
+    // snapshot-based participant→session map, whose whole-record writes can race
+    // across concurrent CLI processes. Session ownership is durable per row and
+    // therefore the honest native-session lookup.
+    const sessionManager = await runtime.context('session/manager');
+    // The conversation's seat is the same participant its MCP connection
+    // resolves, so the connection's bare `session init` finds this session.
+    const { participantId: durableParticipantId } = await sessionManager.ensureHarnessSeat({
+        ...envelopeSeat(envelope),
+        source: 'external-hook',
+        capabilities: ['session-management', 'continuity']
+    });
+    // ONE session per native session for its whole life. The hook owns the row:
+    // it is created here (titled, stamped, NOT adopted as the workspace default),
+    // reused on every later start/compact of the same native session, resumed
+    // when the native session resumes after an archive, and archived at
+    // SessionEnd. Before this, brain.wake minted an untitled "New Session" per
+    // launch, adopted it as the workspace default, and nothing ever closed it —
+    // 125 active "New Session" rows on 2026-08-28.
+    const owned = await bindExternalOwnedSession(sessionManager, durableParticipantId, envelope);
+    const sessionId = owned.sessionId;
+    // Route the seat to its session: this row, not the workspace default, is
+    // what a restarted conversation's connection binds.
+    await sessionManager.setParticipantActiveSession(durableParticipantId, sessionId);
+    const relatedSessions = (await sessionManager.listSessions({
+        status: 'active',
+        limit: 5,
+        offset: 0
+    })).filter((session) => session.id !== sessionId);
+    const [brainRun, presenceRun, letterRun] = await Promise.allSettled([
+        // sessionId only: brain resolves an explicit session without a
+        // participant as a READ (zero writes). Passing the participant made wake
+        // re-point the workspace default at this per-launch session on every
+        // start, which is what bound presence.heartbeat to "arbitrary" sessions.
+        invoke('brain', { action: 'wake', sessionId }, BrainWakeResultSchema),
+        invoke('presence', { action: 'orient' }, PresenceOrientResultSchema),
+        invoke('presence', { action: 'recall', tags: [WAKE_LETTER_TAG], limit: 1 }, PresenceWakeLetterSchema)
+    ]);
+    if (letterRun.status === 'rejected') {
+        getLogger('external.hooks', runtime).warn('external hook: wake letter unavailable for the wake context', {
+            failure: valueFreeFailure(CaughtFailureSchema.parse(letterRun.reason))
+        });
+    }
+    const wakeLetterContent = letterRun.status === 'fulfilled' ? letterRun.value.entries[0]?.content?.trim() : undefined;
+    const wakeLetter = wakeLetterContent ? capWakeLetter(wakeLetterContent) : undefined;
+    if (brainRun.status === 'rejected') {
+        throw new CapabilityError(`${envelope.clientId} session did not bind to Vibes continuity.`, 'UNAVAILABLE', {
+            reason: 'continuity-wake-failed',
+            retryable: true,
+            cause: CaughtFailureSchema.parse(brainRun.reason)
+        });
+    }
+    if (presenceRun.status === 'rejected') {
+        // Presence is declared-optional for the wake context: log why it is missing, value-free.
+        getLogger('external.hooks', runtime).warn('external hook: presence orientation unavailable for the wake context', {
+            failure: valueFreeFailure(CaughtFailureSchema.parse(presenceRun.reason))
+        });
+    }
+    const brain = brainRun.value;
+    const assembly = {
+        brain: {
+            sessionId: brain.session.id,
+            bound: brain.session.id !== 'ephemeral',
+            participantId: durableParticipantId,
+            disposition: owned.disposition,
+            arousal: brain.state.arousal,
+            coherence: brain.state.coherence,
+            confidence: brain.state.confidence,
+            trend: brain.state.trend,
+            focus: brain.focus
+        },
+        presence: presenceRun.status === 'fulfilled'
+            ? {
+                metadataAvailable: true,
+                orientation: presenceRun.value.message ?? null,
+                totalEntries: presenceRun.value.journey.totalEntries,
+                daysActive: presenceRun.value.journey.daysActive,
+                recentActivity: presenceRun.value.journey.recentActivity ?? null,
+                ...(wakeLetter
+                    ? { contentIncluded: true, contentAvailability: 'wake-letter', wakeLetter }
+                    : { contentIncluded: false, contentAvailability: 'not-queried' })
+            }
+            : {
+                metadataAvailable: false,
+                totalEntries: null,
+                daysActive: null,
+                contentIncluded: false,
+                contentAvailability: 'not-queried'
+            },
+        // Ambient harness context never invokes content-bearing awareness actions.
+        awareness: {
+            metadataAvailable: false,
+            relationshipAvailable: null,
+            contentIncluded: false,
+            contentAvailability: 'not-queried'
+        },
+        relatedSessions: relatedSessions.map((session) => ({
+            id: session.id,
+            title: session.title,
+            status: session.status,
+            createdAt: session.createdAt,
+            lastActivityAt: session.lastActivityAt
+        })),
+        degraded: presenceRun.status === 'rejected' ? ['presence'] : [],
+        elapsedMs: performance.now() - startedAt
+    };
+    if (!assembly.brain.bound) {
+        const degraded = assembly.degraded.length > 0 ? ` (${assembly.degraded.join(', ')})` : '';
+        throw new CapabilityError(`External session did not bind to Vibes continuity${degraded}.`, 'UNAVAILABLE', {
+            reason: 'continuity-session-unbound',
+            retryable: true
+        });
+    }
+    return assembly;
+}
+async function metabolizeExternalContinuity(runtime, envelope, trigger) {
+    const continuity = await wakeExternalContinuity(runtime, envelope, 1800);
+    // The one metabolize routine, resolved through the runtime: presence owns it,
+    // and this hook runs it as the harness's agent (the invocation actor). A copy
+    // here once wrote "Metabolized … consolidated 0." on every compaction.
+    try {
+        const metabolize = await runtime.context('continuity/metabolize');
+        const metabolized = await metabolize({ trigger, sessionId: continuity.brain.sessionId, deadlineMs: 4000 });
+        return { continuity, metabolized };
+    }
+    catch (error) {
+        // Metabolizing is declared-degradable at close/compaction: the degraded receipt
+        // carries the value-free failure and its reason.
+        const failure = valueFreeFailure(CaughtFailureSchema.parse(error));
+        return {
+            continuity,
+            metabolized: {
+                trigger,
+                local: { consolidated: 0, remembered: 0, reflected: 0 },
+                degraded: [`continuity: ${failure.reason ?? failure.code ?? failure.name}`],
+                sync: { attempted: false, published: false, pushed: 0, skipped: 'consent-off' },
+                failure
+            }
+        };
+    }
+}
+// SessionStart
+// Runs when: Session begins, including after compaction
+// Purpose: Initialize session state, wake brain, inject guidance
+// Can inject: Yes - session guidance, tool suggestions, reminders
+//
+// Automatic actions invoked (metadata — an ambient wake path never decrypts the
+// inner world; the ONE deliberate exception is the owner's `wake`-tagged letter,
+// see WAKE_LETTER_TAG):
+// - brain.wake()   - Bootstrap cognitive state (automatic tier)
+// - brain.pulse()  - Read body-truth for the wake scan (freshness/session/focus)
+// - session.status() - Check session todos and context
+//
+// SCOPE HONESTY: every one of these runs over HTTP against the MCP endpoint — i.e.
+// against the MANAGED HTTP DAEMON. A stdio external-tool client runs
+// its own separate `dev mcp serve --client <you>` child; this hook cannot see it and
+// must never claim to (CLAUDE.md §Routing around an injured body). Hence `bodyProbe`:
+// the scan states which process it measured, and says UNKNOWN when it measured nothing.
+async function handleSessionStart(ctx) {
+    if (isLocalContinuityHook(ctx.input)) {
+        if (!ctx.eventConfig.brain) {
+            return { data: { skipped: 'brain disabled for local continuity' } };
+        }
+        return {
+            data: {
+                continuity: await wakeExternalContinuity(ctx.runtime, ctx.input.envelope)
+            }
+        };
+    }
+    const data = {};
+    const probe = { endpoint: ctx.mcp.endpoint, status: 'not-probed' };
+    data.bodyProbe = probe;
+    // Wake brain if enabled (automatic tier action)
+    if (ctx.eventConfig.brain) {
+        const brainResult = await ctx.mcp.call('brain', { action: 'wake' });
+        if (brainResult.status === 'ok' && brainResult.value) {
+            data.brain = brainResult.value;
+        }
+        // Pulse for the body-truth wake scan: coherence, focus stack, body
+        // freshness, session binding — all METADATA. Deliberately NOT brain.recall:
+        // recall decrypts private inner-world memories, and an AMBIENT path (a hook
+        // firing every session start) must never decrypt content. Ambient = metadata;
+        // recall/wander/connect are a deliberate reach the agent makes knowingly.
+        const pulseResult = await ctx.mcp.call('brain', { action: 'pulse' });
+        if (pulseResult.status === 'ok' && pulseResult.value) {
+            data.pulse = pulseResult.value;
+            probe.status = 'ok';
+        }
+        else {
+            // The load-bearing case: a body that did not answer is UNKNOWN, never healthy.
+            // But KEEP the transport's distinction — a daemon that answered `tool-error`
+            // is alive, and its remedy is nothing like a dead endpoint's (see
+            // probeVerdictLine). Collapsing both into 'unreachable' was the defect.
+            probe.status = pulseResult.status === 'tool-error' ? 'tool-error' : 'unreachable';
+            probe.reason = pulseResult.reason ?? 'brain.pulse returned no payload';
+        }
+    }
+    else {
+        probe.reason = 'brain hook actions are disabled in config';
+    }
+    // Check session status to surface active todos
+    const sessionResult = await callMcpTool(ctx.mcp, 'session', { action: 'status' });
+    if (sessionResult) {
+        data.session = sessionResult;
+    }
+    if (!sessionReceiptLooksBound(sessionResult ?? undefined)) {
+        const unboundRelated = SessionReceiptSchema.safeParse(sessionResult).data?.unbound?.relatedSessions ?? [];
+        if (unboundRelated.length > 0) {
+            data.relatedSessions = unboundRelated;
+        }
+        else if (sessionResult || probe.status === 'ok' || probe.status === 'tool-error') {
+            const listed = await callMcpTool(ctx.mcp, 'session', { action: 'list', status: 'active', limit: 5 });
+            const sessions = SessionListSchema.safeParse(listed).data?.sessions ?? [];
+            if (sessions.length > 0)
+                data.relatedSessions = sessions;
+        }
+    }
+    // AMBIENT ROSTER — who else is working right now.
+    //
+    // Derived from the touch stream, so nobody had to announce themselves and a
+    // crashed agent ages out on its own. Read here, at SessionStart, so the line
+    // is FRESH and lands in context without the agent calling anything.
+    //
+    // Deliberately NOT baked into the MCP `instructions` block: that is built
+    // once at server construction and then charged to every session forever, so
+    // a roster there would be stale within minutes and never refresh.
+    //
+    // Best-effort and silent when alone — see renderWakeScan.
+    // A roster is a courtesy: its failure never degrades a wake, but it is
+    // recorded and logged value-free, never swallowed.
+    const roster = await readAmbientRoster(ctx.runtime);
+    if (roster.line)
+        data.roster = roster.line;
+    if (roster.failure) {
+        data.rosterUnavailable = roster.reason;
+        getLogger('external.hooks', ctx.runtime).warn('external hook: ambient roster unavailable for the wake line', {
+            failure: roster.failure
+        });
+    }
+    return { data };
+}
+/** The roster line, or the value-free reason it is unavailable. */
+async function readAmbientRoster(runtime) {
+    try {
+        return { line: await resolveAmbientRoster(runtime) };
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        return { reason: failureReason(failure), failure: valueFreeFailure(failure) };
+    }
+}
+/**
+ * Read the live roster for the wake line.
+ *
+ * Resolves through the runtime so a user who has repointed the ambient
+ * provider (or disabled it) gets their own answer here too.
+ */
+async function resolveAmbientRoster(runtime) {
+    const client = await runtime.query('runtime/client').withId('external').resolve();
+    // A host with no session manager has no own session to exclude; any other
+    // failure to read it propagates.
+    let excludeSessionId;
+    try {
+        const manager = await runtime.context('session/manager');
+        excludeSessionId = manager?.activeSessionId ?? manager?.id ?? undefined;
+    }
+    catch (error) {
+        // Confirmed absence of exactly this context; a missing `context` kind or any other failure propagates.
+        if (!CapabilityError.isAbsenceOf(CaughtFailureSchema.parse(error), 'context', 'session/manager'))
+            throw error;
+    }
+    const entries = await client.roster({ excludeSessionId });
+    // null when alone => the caller stores nothing => the scan renders nothing.
+    return formatRosterLine(entries) ?? undefined;
+}
+function shortRef(ref) {
+    // Clean short form: UUIDs cut at the first segment (before '-'); git refs (no
+    // dash) keep the leading 10 chars. Avoids a dangling '-' in the middle of a UUID.
+    return ref ? ref.replace(/-.*$/, '').slice(0, 10) : '?';
+}
+/**
+ * The scope disclaimer. Load-bearing, not decoration: `vibes dev mcp restart` heals the
+ * managed HTTP daemon and does NOT heal a stdio client's own body — only the client can
+ * respawn that child (CLAUDE.md, docs/presence/CONTINUITY-PRACTICE.md §injury protocol).
+ * Everything the scan prints came over HTTP from the daemon, so it is labelled as such.
+ */
+const WAKE_SCAN_SCOPE_NOTE = [
+    'scope: everything below was measured over HTTP against the MANAGED MCP DAEMON.',
+    'your own body: NOT MEASURED — a stdio external-tool client runs its',
+    '  own `dev mcp serve --client <you>` child process. `vibes dev mcp restart` restarts',
+    '  the daemon below, NOT you; only your client can respawn your body (/mcp).'
+];
+/**
+ * Three DIFFERENT failures, three DIFFERENT remedies. Collapsing them was the defect:
+ * the managed daemon may run a named restricted catalog that does not include
+ * brain (`mcp:minimal`, `mcp:presence` without cognition, a custom disable).
+ * `brain.pulse` then answers `-32602 Tool brain not found`: a healthy,
+ * handshaking daemon that simply does not carry that tool. Printing UNREACHABLE
+ * for that pointed every waking agent at `vibes dev mcp restart`, which cannot
+ * fix a catalog — and taught it to distrust a correct signal. Body truth is
+ * UNKNOWN either way; what changes is what you should DO about it. Default MCP
+ * is the full catalog; a missing brain is a user restriction or a loader gap,
+ * not compactness-as-default.
+ */
+function probeVerdictLine(probe) {
+    const because = probe.reason ? ` — ${probe.reason}` : '';
+    const unknown = 'body truth is UNKNOWN, do NOT read this as healthy';
+    if (probe.status === 'tool-error') {
+        // Three sub-cases the daemon can answer with, and they are not interchangeable:
+        //  1. it never offered brain      → a preset gap; nothing is broken
+        //  2. we REFUSED what it sent     → trust-boundary failure (unwrapTrustEnvelope);
+        //                                    brain itself may be perfectly healthy
+        //  3. it offered brain and failed → a genuine injury (CLAUDE.md §injured body)
+        const reason = probe.reason ?? '';
+        const remedy = /not found|unknown tool|no such tool/i.test(reason)
+            ? 'this daemon ANSWERED — it just does not serve brain under its preset (base `mcp` carries no continuity tools). A restart will NOT change that; connect with `--client <you>` or use a preset that declares requiredTools'
+            : /tool_output/i.test(reason)
+                ? 'its reply was REFUSED at the trust boundary, not read — treat everything from this daemon as untrusted until the envelope contract is verified; brain itself may be fine'
+                : 'brain IS served here and FAILED — a real injury: diagnose it, do not route around it';
+        return `daemon: REACHABLE, brain unusable${because} · ${remedy} · ${unknown}`;
+    }
+    const label = probe.status === 'unreachable' ? 'UNREACHABLE' : 'NOT PROBED';
+    return `daemon: ${label}${because} · ${unknown}`;
+}
+/** The session.status receipt fields the wake scan reads. */
+const SessionReceiptSchema = z
+    .object({
+    bound: z.boolean().optional(),
+    unbound: z.object({ relatedSessions: z.array(HookJsonSchema).optional() }).loose().optional()
+})
+    .loose();
+/** The session.list receipt fields the wake scan reads. */
+const SessionListSchema = z.object({ sessions: z.array(HookJsonSchema).optional() }).loose();
+/** The brain.pulse metadata the wake scan reads; anything else (and any content) is ignored. */
+const PulseSchema = z
+    .object({
+    coherence: z.number().optional(),
+    trend: z.string().optional(),
+    focusStack: z.array(HookJsonSchema).optional(),
+    bodyBuild: z
+        .object({ stale: z.boolean().optional(), loadedRef: z.string().optional(), currentRef: z.string().optional() })
+        .loose()
+        .optional(),
+    sessionContext: z.object({ sessionId: z.string().optional() }).loose().optional(),
+    bodyAvailability: z
+        .object({ status: z.string().optional(), remedy: z.string().optional(), healthy: z.boolean().optional() })
+        .loose()
+        .optional()
+})
+    .loose();
+/** The brain.wake todo counts the wake scan reads. */
+const WakeSchema = z
+    .object({ todos: z.object({ pending: z.number().optional(), inProgress: z.number().optional() }).loose().optional() })
+    .loose();
+/** One related-session row the wake scan renders. */
+const RelatedSessionSchema = z
+    .object({
+    id: z.string().optional(),
+    handle: z.string().optional(),
+    title: z.string().optional(),
+    status: z.string().optional(),
+    bind: z.object({ action: z.string().optional(), sessionId: z.string().optional() }).loose().optional()
+})
+    .loose();
+function sessionReceiptLooksBound(session) {
+    return SessionReceiptSchema.safeParse(session).data?.bound === true;
+}
+function wakeScanMeasuredUnbound(data) {
+    if (sessionReceiptLooksBound(data.session))
+        return false;
+    if (data.session)
+        return true;
+    if ((data.relatedSessions?.length ?? 0) > 0)
+        return true;
+    const pulse = PulseSchema.safeParse(data.pulse ?? {}).data;
+    if (pulse?.bodyAvailability?.status === 'session-unbound')
+        return true;
+    return pulse?.sessionContext?.sessionId === 'ephemeral';
+}
+/**
+ * The body-truth wake scan — a METADATA-ONLY summary injected at SessionStart so an
+ * agent SEES the measured body state on waking (build freshness, session binding, focus
+ * load, coherence) instead of only a static guidance essay. It reads brain.pulse /
+ * brain.wake / session.status metadata; it must NEVER surface inner-world content (no
+ * recall), which is why the render only reads the fields its schemas name and ignores
+ * everything else in `data`. Pure and side-effect-free so it is directly testable.
+ */
+export function renderWakeScan(data) {
+    const pulse = PulseSchema.safeParse(data.pulse ?? {}).data ?? {};
+    const wake = WakeSchema.safeParse(data.brain ?? {}).data ?? {};
+    const probe = data.bodyProbe;
+    if (!probe && !data.pulse && !data.brain && !data.session && !data.roster && !data.relatedSessions)
+        return undefined;
+    const lines = [...WAKE_SCAN_SCOPE_NOTE];
+    const bb = pulse.bodyBuild;
+    const avail = pulse.bodyAvailability;
+    // An unanswered probe is the whole reason this block exists: silence used to render
+    // as nothing, making a dead cognition body look exactly like a healthy wake.
+    if (probe && probe.status !== 'ok') {
+        lines.push(probeVerdictLine(probe));
+    }
+    else if (!data.pulse) {
+        lines.push('daemon: NOT PROBED — no pulse in this run · body truth is UNKNOWN');
+    }
+    // Build + session verdict for the DAEMON — PREFER the composed brain.pulse verdict
+    // (single source of truth), falling back to deriving from bodyBuild/sessionContext
+    // only for an older body whose pulse predates the verdict field.
+    const staleLine = (loaded, current) => `daemon build: STALE — loaded ${shortRef(loaded)}, workspace at ${shortRef(current)} · heal the daemon: \`vibes dev mcp restart\``;
+    if (avail?.status) {
+        switch (avail.status) {
+            case 'real':
+                lines.push(`daemon build: fresh @ ${shortRef(bb?.loadedRef)}`);
+                lines.push(`daemon session: bound (${shortRef(pulse.sessionContext?.sessionId)})`);
+                break;
+            case 'body-stale':
+                lines.push(staleLine(bb?.loadedRef, bb?.currentRef));
+                lines.push(`daemon session: bound (${shortRef(pulse.sessionContext?.sessionId)})`);
+                break;
+            case 'session-unbound':
+                lines.push(`daemon build: fresh @ ${shortRef(bb?.loadedRef)}`);
+                lines.push('daemon session: EPHEMERAL — no bound session (run session.init)');
+                break;
+            default:
+                lines.push(`daemon: ${avail.status}${avail.remedy ? ` — ${avail.remedy}` : ''}`);
+        }
+    }
+    else if (data.pulse) {
+        // Fallback (body older than the bodyAvailability field): conservative derivation.
+        if (bb) {
+            lines.push(bb.stale ? staleLine(bb.loadedRef, bb.currentRef) : `daemon build: fresh @ ${shortRef(bb.loadedRef)}`);
+        }
+        else {
+            lines.push('daemon build: freshness unknown — treat as STALE until proven (restart the daemon to be sure)');
+        }
+        if (pulse.sessionContext) {
+            const sid = pulse.sessionContext.sessionId;
+            lines.push(sid && sid !== 'ephemeral'
+                ? `daemon session: bound (${shortRef(sid)})`
+                : 'daemon session: EPHEMERAL — no bound session (run session.init)');
+        }
+    }
+    // Focus load + coherence — reported BY the daemon, so labelled as such.
+    if (pulse.focusStack) {
+        const depth = pulse.focusStack.length;
+        lines.push(`focus (daemon-reported): ${depth} target${depth === 1 ? '' : 's'}`);
+    }
+    if (pulse.coherence !== undefined) {
+        lines.push(`state (daemon-reported): coherence ${pulse.coherence}/10${pulse.trend ? `, ${pulse.trend}` : ''}`);
+    }
+    // Todos (from brain.wake metadata).
+    const pending = wake.todos?.pending ?? 0;
+    const inProgress = wake.todos?.inProgress ?? 0;
+    if (pending || inProgress) {
+        lines.push(`todos (daemon-reported): ${inProgress} in progress, ${pending} pending`);
+    }
+    // The roster line, when there IS one. Alone is the common case and costs
+    // exactly zero bytes here.
+    if (data.roster)
+        lines.push(data.roster);
+    if (probe?.status !== 'unreachable' && wakeScanMeasuredUnbound(data)) {
+        lines.push('your MCP connection is not a session participant until you bind — do that before coordinating, locking, or writing session state.');
+        const related = data.relatedSessions ?? [];
+        if (related.length > 0) {
+            lines.push('related sessions:');
+            for (const item of related.slice(0, 5)) {
+                const row = RelatedSessionSchema.safeParse(item).data;
+                if (!row?.id)
+                    continue;
+                const handle = row.handle ?? row.id.replace(/-/g, '').slice(0, 8);
+                const title = row.title ? ` "${row.title}"` : '';
+                const status = row.status ? ` ${row.status}` : '';
+                const action = row.bind?.action === 'resume' ? 'resume' : 'init';
+                const sessionId = row.bind?.sessionId ?? row.id;
+                lines.push(`  - ${handle}${status}${title}  session { action: "${action}", sessionId: "${sessionId}" }`);
+            }
+        }
+        lines.push('create: session { action: "init", newSession: true }');
+    }
+    const endpointAttr = probe?.endpoint ? ` endpoint="${probe.endpoint}"` : '';
+    return `<wake-scan scope="mcp-http-daemon"${endpointAttr}>\n${lines.map((l) => `  ${l}`).join('\n')}\n</wake-scan>`;
+}
+// SessionEnd
+// Runs when: Session terminates (user exits, timeout, etc.)
+// Purpose: Archive session metrics, save final state
+// Can inject: No - session is ending, no response expected
+async function handleSessionEnd(ctx) {
+    if (isLocalContinuityHook(ctx.input)) {
+        if (!ctx.eventConfig.brain) {
+            // Brain is off, but the session lifecycle is not: the row this native
+            // session owns still closes with it.
+            const archived = await archiveExternalNativeSession(ctx.runtime, ctx.input.envelope);
+            return { data: { skipped: 'brain disabled for local continuity', archived } };
+        }
+        // The row this native session owns closes with it even when metabolizing
+        // fails: the archive runs in `finally`, and the metabolize failure propagates.
+        let archived;
+        try {
+            const metabolized = await metabolizeExternalContinuity(ctx.runtime, ctx.input.envelope, 'close');
+            archived = await archiveExternalNativeSession(ctx.runtime, ctx.input.envelope);
+            return { data: { ...metabolized, archived } };
+        }
+        finally {
+            if (archived === undefined)
+                await archiveExternalNativeSession(ctx.runtime, ctx.input.envelope);
+        }
+    }
+    const data = {};
+    // Archive file access stats to session
+    const statsResult = await callMcpTool(ctx.mcp, 'external', {
+        action: 'file-access-list',
+        includeStats: true,
+        limit: 50
+    });
+    if (statsResult) {
+        data.fileStats = statsResult;
+    }
+    return { data };
+}
+// UserPromptSubmit
+// Runs when: User submits a message, before the host processes it
+// Purpose: deliver pending messages and notices (no brain priming — see below)
+// Can inject: Yes - data.delivery
+// Input: PROMPT env var contains user's message
+//
+// NO AMBIENT PRIMING HERE — deliberate, do not "fix" it back.
+// This handler used to call `brain { action: 'prime', primeQuery }`. The brain tool's
+// prime action requires `query`, so the malformed arg meant the call NEVER ran. Renaming
+// the field would have been worse than the bug: `brain.prime` is a CONTENT path — it
+// decrypts inner-world memories AND ships plaintext to an AI ranker. Wiring that into a
+// hook that fires on EVERY user message installs a per-message ambient decrypt + egress,
+// exactly the law stated at handleSessionStart: ambient paths are METADATA-ONLY, and
+// content is only ever reached for deliberately (privacy floor,
+// docs/presence/CONTINUITY-PRACTICE.md). The dead call is therefore removed, not repaired.
+//
+// NOTE: user.said speech capture is NOT done here either — this hook-call process is a
+// thin HTTP proxy to a running MCP and does not load the awareness storage. The speech
+// lane is captured by `vibes presence say` (which loads awareness + awaits the write),
+// invoked directly from the UserPromptSubmit hook. See
+// presence/src/cli/commands/presence.say.*.
+async function handleUserPromptSubmit(ctx) {
+    return { data: await deliveryData(ctx, 'prompt.submit') };
+}
+/** The collaboration delivery for `event`, as hook data (empty when there is nothing to say). */
+async function deliveryData(ctx, event) {
+    const envelope = ctx.input.envelope;
+    const delivery = envelope ? await collaborationContext(ctx.runtime, envelope, event) : undefined;
+    return delivery ? { delivery } : {};
+}
+// PreToolUse
+// Runs when: The host is about to use a tool, before execution
+// Purpose: Validate, log, potentially block dangerous operations
+// Can inject: Yes - can add warnings, can BLOCK by returning error
+// Input: Tool name and arguments on stdin
+//
+// DESIGN NOTE: Powerful for safety/governance. Consider:
+// - Blocking destructive operations (rm -rf, DROP TABLE, etc.)
+// - Requiring confirmation for sensitive operations
+// - Logging all tool usage for audit
+// - Rate limiting expensive operations
+async function handlePreToolUse(ctx) {
+    const data = {};
+    const toolInfo = ctx.input.envelope?.tool;
+    if (toolInfo) {
+        data.tool = toolInfo.name;
+        data.input = boundToolPayload(toolInfo.input);
+        const tiers = (await readCollaborationSettings(ctx.runtime)).toolTiers;
+        if (tiers.enabled) {
+            const bridge = await runHookToolBridge(ctx.runtime, {
+                event: 'tool.before',
+                hostToolName: toolInfo.name,
+                toolInput: toolInfo.input
+            }, tiers);
+            if (bridge.bridged) {
+                data.bridge = bridge;
+                if (bridge.denied) {
+                    data.blocked = bridge.message ?? 'tool denied by tier enforcement';
+                }
+            }
+        }
+        // A native edit takes its files' locks; another holder is named to the editor (or refuses it, when configured).
+        if (!data.blocked && ctx.input.envelope) {
+            const guard = await guardNativeEdit(ctx.runtime, ctx.input.envelope);
+            if (guard) {
+                data.locks = guard.locks;
+                if (guard.blocked)
+                    data.blocked = guard.blocked;
+                if (guard.notice)
+                    data.delivery = guard.notice;
+            }
+        }
+    }
+    return { data };
+}
+/**
+ * Record a host file access for the hook's workspace session, in-process. A
+ * session-less hook records nothing and says so; any other failure is logged
+ * value-free and reported in the hook data, never thrown into the host.
+ */
+async function trackHookFileAccess(runtime, access) {
+    try {
+        const { handleFileAccessTrack } = await import("../tools/unified/handlers/file-access-track.js");
+        const sessionId = await resolveExternalSessionId(runtime);
+        if (!sessionId)
+            return { skipped: 'no-session' };
+        await handleFileAccessTrack(runtime, { action: 'file-access-track', sessionId, ...access });
+        return { filePath: access.filePath, operation: access.operation };
+    }
+    catch (error) {
+        const failed = valueFreeFailure(CaughtFailureSchema.parse(error));
+        getLogger('external.hooks', runtime).warn('hook file-access tracking failed', { failure: failed });
+        return { failed };
+    }
+}
+// PostToolUse
+// Runs when: Tool has completed execution
+// Purpose: Track file access, update state, inject follow-up guidance
+// Can inject: Yes - can add context about what happened
+// Input: Tool result on stdin
+//
+// Automatic brain actions invoked:
+// - brain.track() - Record tool use for learning (automatic tier)
+async function handlePostToolUse(ctx) {
+    const data = {};
+    const toolData = ctx.input.envelope?.tool;
+    if (toolData) {
+        const toolName = toolData.name;
+        const toolInput = toolData.input ?? {};
+        const toolOutput = toolData.result ?? {};
+        const filePath = toolData.filePath;
+        // Track file access for file operations
+        if (filePath && ['Read', 'Write', 'Edit', 'MultiEdit', 'Glob', 'Grep'].includes(toolName)) {
+            const operation = toolName === 'Write'
+                ? 'write'
+                : toolName === 'Edit' || toolName === 'MultiEdit'
+                    ? 'edit'
+                    : 'read';
+            // Recorded in-process: a nested tool invocation per host tool call made the
+            // hook's own bookkeeping a second traced, captured, authorized tool call.
+            data.tracked = await trackHookFileAccess(ctx.runtime, { filePath, operation, toolName });
+        }
+        // Codex edits through `apply_patch`: every file its patch writes is an edit, so peers see it.
+        if (!data.tracked && ctx.input.envelope) {
+            const patched = nativeEditTargets(toolData, ctx.input.envelope.workspacePath, await hookWorkspaceRoot(ctx.runtime, ctx.input.envelope), []);
+            for (const patchedPath of patched) {
+                data.tracked = await trackHookFileAccess(ctx.runtime, { filePath: patchedPath, operation: 'edit', toolName });
+            }
+        }
+        // Brain: track tool use for learning (automatic tier action), with a bounded,
+        // redacted summary of the tool's input and result, never the whole payload.
+        if (ctx.eventConfig.brain && toolName) {
+            const trackResult = await callMcpTool(ctx.mcp, 'brain', {
+                action: 'track',
+                tool: toolName,
+                input: boundToolPayload(toolInput),
+                output: boundToolPayload(toolOutput),
+                success: !toolData.error
+            });
+            if (trackResult) {
+                data.brainTrack = trackResult;
+            }
+        }
+        const tiers = (await readCollaborationSettings(ctx.runtime)).toolTiers;
+        if (tiers.enabled && toolName) {
+            const bridge = await runHookToolBridge(ctx.runtime, {
+                event: 'tool.after',
+                hostToolName: toolName,
+                toolInput,
+                toolResult: toolOutput
+            }, tiers);
+            if (bridge.bridged) {
+                data.bridge = bridge;
+            }
+        }
+    }
+    return { data: { ...data, ...(await deliveryData(ctx, 'tool.after')) } };
+}
+// PermissionRequest
+// Runs when: The host needs user permission for an operation
+// Purpose: Log permission requests, potentially auto-approve known-safe ops
+// Can inject: Yes - can add context about the permission
+//
+// DESIGN NOTE: Could be used for:
+// - Logging all permission requests for audit
+// - Auto-approving based on project config
+// - Adding context about why permission is needed
+async function handlePermissionRequest(ctx) {
+    const data = {};
+    if (ctx.input.envelope) {
+        const tool = ctx.input.envelope.tool;
+        data.permission = {
+            mode: ctx.input.envelope.permissionMode,
+            tool: tool?.name,
+            input: tool ? boundToolPayload(tool.input) : undefined
+        };
+    }
+    return { data };
+}
+// PreCompact
+// Runs when: Context is about to be compacted (summarized)
+// Purpose: Save critical state before context is lost
+// Can inject: Yes - guidance for compaction
+async function handlePreCompact(ctx) {
+    if (isLocalContinuityHook(ctx.input)) {
+        if (!ctx.eventConfig.brain) {
+            return { data: { skipped: 'brain disabled for local continuity' } };
+        }
+        return {
+            data: await metabolizeExternalContinuity(ctx.runtime, ctx.input.envelope, 'pre-compaction')
+        };
+    }
+    const data = {};
+    // Consolidate brain memories before compaction
+    if (ctx.eventConfig.brain) {
+        const consolidateResult = await callMcpTool(ctx.mcp, 'brain', { action: 'consolidate' });
+        if (consolidateResult) {
+            data.consolidated = consolidateResult;
+        }
+    }
+    // Generate context summary for compaction
+    const summaryResult = await callMcpTool(ctx.mcp, 'external', {
+        action: 'context-summary',
+        format: 'compact',
+        maxFiles: 15,
+        includeTodos: true,
+        includeScratchpad: false,
+        timeWindowHours: 4
+    });
+    if (summaryResult) {
+        data.summary = summaryResult;
+    }
+    return { data };
+}
+// Stop
+// Runs when: The host stops responding (completion, error, interrupt)
+// Purpose: Capture final session state
+// Can inject: the self-review nudge (data.delivery), rendered by the host's adapter
+//
+// Automatic actions invoked:
+// - session.status() - Capture final session state
+//
+// NO brain call here — deliberate, do not "fix" it back.
+// This handler used to call `brain { action: 'debrief' }`. `debrief` is NOT a brain
+// action (the real enum is `BrainActions` in presence/src/brain/tools/brain/schemas.ts:
+// pulse, prime, salience, coherence, consolidate, wake, track, focus, release,
+// distract, refocus, attention, plan, predict, outcome, stress, urgent, relax,
+// pressure), so end-of-turn reflection never ran — the hook advertised a
+// capability the runtime does not have, which is a lying projection
+// (docs/architecture/EXTERNAL-AS-RUNTIME-PROJECTION.md). It is removed rather than
+// re-pointed at `consolidate`: consolidate metabolizes content through an AI path and
+// writes durable memory, so firing it on every turn stop would install exactly the kind
+// of ambient content path that handleUserPromptSubmit documents as forbidden.
+// Metabolizing stays a deliberate reach the agent makes knowingly.
+async function handleStop(ctx) {
+    const data = {};
+    // NOTE: agent.said speech capture is NOT done here (see handleUserPromptSubmit) —
+    // it is captured by `vibes presence say --role agent --from-transcript`, invoked
+    // from the Stop hook, which loads the awareness storage and awaits the write.
+    // Capture session state for continuity
+    const sessionResult = await callMcpTool(ctx.mcp, 'session', { action: 'status' });
+    if (sessionResult) {
+        data.sessionSnapshot = sessionResult;
+    }
+    // A Stop hook re-run after its own block delivers nothing: Claude reports it with
+    // `stop_hook_active`, and a second block would loop.
+    if (ctx.input.envelope?.trigger === 'stop-hook-active')
+        return { data };
+    return { data: { ...data, ...(await deliveryData(ctx, 'agent.stop')) } };
+}
+// SubagentStop
+// Runs when: A subagent (Task tool) completes
+// Purpose: Process subagent results, update parent context
+// Can inject: Yes - can add summary of what subagent did
+//
+// DESIGN NOTE: Useful for:
+// - Aggregating results from parallel subagents
+// - Tracking subagent success/failure rates
+// - Injecting summaries back to parent context
+async function handleSubagentStop(ctx) {
+    const data = {};
+    const envelope = ctx.input.envelope;
+    if (envelope?.subagent)
+        data.subagent = envelope.subagent;
+    if (envelope?.tool?.result !== undefined)
+        data.result = boundToolPayload(envelope.tool.result);
+    return { data };
+}
+// Notification
+// Runs when: The host sends a notification to the user
+// Purpose: Log notifications, trigger external alerts
+// Can inject: No - notification already sent
+//
+// DESIGN NOTE: Could be used for:
+// - Sending notifications to external systems (Slack, email)
+// - Logging important notifications for review
+// - Triggering webhooks
+async function handleNotification(ctx) {
+    const data = {};
+    if (ctx.input.envelope) {
+        data.notification = {
+            reason: ctx.input.envelope.reason,
+            trigger: ctx.input.envelope.trigger
+        };
+    }
+    return { data };
+}
+// Main Handler
+const EVENT_HANDLERS = {
+    'session.start': handleSessionStart,
+    'session.end': handleSessionEnd,
+    'prompt.submit': handleUserPromptSubmit,
+    'tool.before': handlePreToolUse,
+    'tool.after': handlePostToolUse,
+    'permission.request': handlePermissionRequest,
+    'context.beforeCompact': handlePreCompact,
+    'agent.stop': handleStop,
+    'subagent.stop': handleSubagentStop,
+    notification: handleNotification,
+    // No work after compaction: the session.start that follows it wakes the body.
+    'context.afterCompact': async () => ({ data: { skipped: 'no handler for event' } })
+};
+/** The invocation actor a normalized harness envelope declares. */
+export function hookInvocationOverlay(input) {
+    const envelope = input.envelope;
+    if (!envelope)
+        return undefined;
+    return {
+        actor: {
+            agentId: envelope.clientId,
+            harness: envelope.clientId,
+            harnessSessionId: envelope.nativeSessionId
+        }
+    };
+}
+/**
+ * Execute hook for given event
+ *
+ * Loads configuration, checks if event is enabled, runs handler,
+ * and assembles output with optional prompt injection.
+ */
+export async function executeHookCall(input, options) {
+    try {
+        const { runtime } = options;
+        // Load configuration
+        const config = await loadConfig(runtime, input.target);
+        // Check if hooks are globally disabled
+        if (!config.enabled) {
+            return {
+                success: true,
+                event: input.event,
+                data: { skipped: 'hooks disabled globally' }
+            };
+        }
+        // Get event-specific configuration
+        const eventConfig = getEventConfig(config, input.event, {
+            disableBrain: input.disableBrain,
+            disablePrompts: input.disablePrompts
+        });
+        // Check if this event is disabled
+        if (!eventConfig.enabled) {
+            return {
+                success: true,
+                event: input.event,
+                data: { skipped: 'event disabled in config' }
+            };
+        }
+        // Build handler context. The MCP client is created PER HOOK CALL and carries the
+        // event's configured timeout as a whole-call budget — previously `eventConfig.timeout`
+        // was computed and thrown away, so a wedged MCP body hung session start forever.
+        // Shared resolver (VIBES_MCP_URL override + default) — a hard-coded MCP origin is
+        // the wrong-endpoint injury class that broke the knowledge client (cefe08d2c).
+        // (Resolving this capability from the runtime instead of over HTTP is the deeper
+        // fix, tracked in the external audit.)
+        const timeoutMs = eventConfig.timeout ?? 30000;
+        const ctx = {
+            runtime,
+            input,
+            eventConfig,
+            mcp: options.mcpFactory
+                ? options.mcpFactory(timeoutMs)
+                : createMcpClient({
+                    runtime,
+                    endpoint: await resolveLocalMcpUrlForRuntime(runtime, {
+                        workspaceRoot: await runtime.context('runtime/workspace-path'),
+                        vibesHome: getPathRoots(runtime).vibesHome
+                    }),
+                    timeoutMs
+                })
+        };
+        // Run the handler
+        const handler = EVENT_HANDLERS[input.event];
+        let result;
+        try {
+            // The hook acts for the harness's agent: one invocation whose actor is
+            // that agent and native session. Every organ call inside it (brain,
+            // presence, continuity) resolves identity from this actor through the
+            // runtime — never from the daemon's own environment or scope.
+            result = await runtime.runInvocation(async () => {
+                const client = tryGetVibesClient('external', runtime);
+                const seat = client && input.envelope ? await resolveHookSeat(runtime, input.envelope) : null;
+                return client && seat
+                    ? client.withDeferredAmbientDelivery(seat.sessionId, () => handler(ctx))
+                    : handler(ctx);
+            }, hookInvocationOverlay(input));
+        }
+        finally {
+            // Release the MCP session even when a handler throws — this process is about to
+            // exit and can never reuse it.
+            await ctx.mcp.dispose();
+        }
+        // Get prompt for this event (if enabled)
+        const targetDescriptor = input.target
+            ? runtime.query('external/host').withId(input.target).descriptors()[0]
+            : undefined;
+        const promptPolicy = targetDescriptor?.manifest.integration.hooks?.defaultPromptPolicy ?? 'default';
+        const prompt = getPromptForEvent(input.event, eventConfig, promptPolicy);
+        if (input.output === 'json') {
+            return {
+                success: true,
+                event: input.event,
+                data: {
+                    ...result.data,
+                    config: {
+                        brain: eventConfig.brain,
+                        prompts: eventConfig.prompts
+                    }
+                }
+            };
+        }
+        // Text output: inject the guidance prompt, and for SessionStart PREPEND the
+        // metadata body-truth scan so the agent SEES its body state (stale/ephemeral/
+        // focus/coherence) at wake instead of only a static essay. The run already
+        // happened in the handler; this stops discarding its (metadata-only) result.
+        let context = prompt;
+        if (input.event === 'session.start') {
+            const continuity = result.data?.continuity;
+            const scan = continuity
+                ? renderExternalContinuityContext(continuity)
+                : renderWakeScan(result.data ?? {});
+            // The project's conduct rules (its `workspace.rules`) steer a harness session as they steer every agent.
+            const conduct = options.runtime.hasKind('rules/rule')
+                ? await (await import('@vibesdotdev/rules/rule/guidance')).conductText(options.runtime)
+                : '';
+            context = [scan, conduct, prompt].filter(Boolean).join('\n\n') || undefined;
+        }
+        if (result.data?.delivery)
+            context = [context, result.data.delivery].filter(Boolean).join('\n\n');
+        return {
+            success: true,
+            event: input.event,
+            context,
+            data: result.data
+        };
+    }
+    catch (error) {
+        // The harness reads `error`: a typed refusal by its own value-free message, anything else by its facts.
+        const failure = CaughtFailureSchema.parse(error);
+        getLogger('external.hooks', options.runtime).warn('external hook failed', { event: input.event, failure: valueFreeFailure(failure) });
+        return {
+            success: false,
+            event: input.event,
+            error: failureReason(failure),
+            failure: valueFreeFailure(CaughtFailureSchema.parse(error))
+        };
+    }
+}
+//# sourceMappingURL=call.js.map