clementine-agent 1.18.100 → 1.18.102

package/dist/agent/hook-session-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * PRD §6 Phase 4d / 1.18.101 — Path B (hook side-channel) session registry.
+ *
+ * The Claude Agent SDK's hook mechanism (PreToolUse, PostToolUse, SubagentStart,
+ * SubagentStop, Stop, Notification, etc.) lets command-type hooks defined in
+ * `.claude/settings.json` POST event JSON to an external endpoint. Path B is
+ * how the dashboard receives those events and merges them into the per-run
+ * event log so the Run detail viewer + Latency dashboard see real per-tool
+ * durations (not the path A heuristic).
+ *
+ * The challenge: hook events arrive with the SDK `session_id`, but the
+ * dashboard's RunEvent rows key off the dashboard-assigned `runId` UUID. This
+ * registry bridges the two — `runAgent` registers a `(sessionId, runId,
+ * eventLog)` tuple on the SystemMessage init, the hook ingest endpoint looks
+ * up by sessionId, and the entry clears on session_end so memory doesn't leak.
+ *
+ * Design notes:
+ * - In-memory only (Map). Reboot clears all sessions; that's correct because
+ *   any in-flight runs are abandoned by the daemon restart sweep anyway.
+ * - Multiple concurrent runs are supported (one entry per active SDK session).
+ * - Best-effort: if a hook arrives after session_end (race), we silently drop
+ *   the event rather than replay onto a closed run. The dashboard's run
+ *   detail can show a "stale hook event" diagnostic if this becomes common.
+ */
+import type { EventLog } from '../gateway/event-log.js';
+export interface HookSessionEntry {
+    /** Dashboard-assigned UUID linking back to CronRunEntry.id. */
+    runId: string;
+    /** EventLog instance owning the run's JSONL file. Reused so path B writes
+     *  go to the same file as path A live events. */
+    eventLog: EventLog;
+    /** Wall-clock when the registration happened. Used for janitor cleanup
+     *  if a session_end never fires (SDK crash / network blip). */
+    registeredAt: number;
+    /** Atomic counter used so path B writes get monotonically increasing seqs
+     *  even when interleaved with path A. The registry hands out seq numbers
+     *  via `nextSeq()` below; path A uses its own closure-local counter and
+     *  the EventLog dedupes on disk via append-only ordering. */
+    seqCounter: number;
+}
+export declare function registerRunSession(sessionId: string, runId: string, eventLog: EventLog, seqStart?: number): void;
+export declare function unregisterRunSession(sessionId: string): void;
+export declare function getRunSession(sessionId: string): HookSessionEntry | null;
+/** Hand out the next monotonic seq for path B writes on this session. The
+ *  caller is responsible for actually appending the event; this function
+ *  just bumps the counter and returns the prior value so writes are stable
+ *  under concurrent calls. */
+export declare function nextSeqForSession(sessionId: string): number | null;
+/** Best-effort sweep — call from a periodic timer or before each lookup
+ *  to keep stale entries from accumulating. Currently called from the
+ *  ingest endpoint on every POST so we don't need a dedicated timer. */
+export declare function sweepStaleSessions(): number;
+/** Test-only: snapshot of the live map size + age distribution. Useful for
+ *  janitor diagnostics in the dashboard. */
+export declare function getRegistryStats(): {
+    count: number;
+    oldestAgeMs: number | null;
+};
+/** Test-only: clear the registry between tests. Never call from production. */
+export declare function _resetRegistryForTests(): void;
+//# sourceMappingURL=hook-session-registry.d.ts.map

package/dist/agent/hook-session-registry.js

@@ -0,0 +1,92 @@
+/**
+ * PRD §6 Phase 4d / 1.18.101 — Path B (hook side-channel) session registry.
+ *
+ * The Claude Agent SDK's hook mechanism (PreToolUse, PostToolUse, SubagentStart,
+ * SubagentStop, Stop, Notification, etc.) lets command-type hooks defined in
+ * `.claude/settings.json` POST event JSON to an external endpoint. Path B is
+ * how the dashboard receives those events and merges them into the per-run
+ * event log so the Run detail viewer + Latency dashboard see real per-tool
+ * durations (not the path A heuristic).
+ *
+ * The challenge: hook events arrive with the SDK `session_id`, but the
+ * dashboard's RunEvent rows key off the dashboard-assigned `runId` UUID. This
+ * registry bridges the two — `runAgent` registers a `(sessionId, runId,
+ * eventLog)` tuple on the SystemMessage init, the hook ingest endpoint looks
+ * up by sessionId, and the entry clears on session_end so memory doesn't leak.
+ *
+ * Design notes:
+ * - In-memory only (Map). Reboot clears all sessions; that's correct because
+ *   any in-flight runs are abandoned by the daemon restart sweep anyway.
+ * - Multiple concurrent runs are supported (one entry per active SDK session).
+ * - Best-effort: if a hook arrives after session_end (race), we silently drop
+ *   the event rather than replay onto a closed run. The dashboard's run
+ *   detail can show a "stale hook event" diagnostic if this becomes common.
+ */
+const sessions = new Map();
+/** Janitor sweep: clear sessions that have been registered for more than this
+ *  many ms without a session_end. Keeps the map bounded if the daemon stays
+ *  up but a run dies in a way that bypasses our session_end handler. */
+const STALE_SESSION_MS = 6 * 60 * 60 * 1000; // 6h — matches longest cron wall cap
+export function registerRunSession(sessionId, runId, eventLog, seqStart = 0) {
+    if (!sessionId || !runId)
+        return;
+    sessions.set(sessionId, { runId, eventLog, registeredAt: Date.now(), seqCounter: seqStart });
+}
+export function unregisterRunSession(sessionId) {
+    if (!sessionId)
+        return;
+    sessions.delete(sessionId);
+}
+export function getRunSession(sessionId) {
+    return sessions.get(sessionId) ?? null;
+}
+/** Hand out the next monotonic seq for path B writes on this session. The
+ *  caller is responsible for actually appending the event; this function
+ *  just bumps the counter and returns the prior value so writes are stable
+ *  under concurrent calls. */
+export function nextSeqForSession(sessionId) {
+    const entry = sessions.get(sessionId);
+    if (!entry)
+        return null;
+    // Path B seqs start at 1_000_000 to keep them visually distinct from
+    // path A in the event log + so a sort by seq groups them after path A
+    // writes that share the same timestamp. Multi-million seq numbers are
+    // fine — the field is plain JSON number, no overflow risk for the
+    // forseeable future.
+    const seq = 1_000_000 + entry.seqCounter;
+    entry.seqCounter += 1;
+    return seq;
+}
+/** Best-effort sweep — call from a periodic timer or before each lookup
+ *  to keep stale entries from accumulating. Currently called from the
+ *  ingest endpoint on every POST so we don't need a dedicated timer. */
+export function sweepStaleSessions() {
+    const now = Date.now();
+    let removed = 0;
+    for (const [sid, entry] of sessions.entries()) {
+        if (now - entry.registeredAt > STALE_SESSION_MS) {
+            sessions.delete(sid);
+            removed += 1;
+        }
+    }
+    return removed;
+}
+/** Test-only: snapshot of the live map size + age distribution. Useful for
+ *  janitor diagnostics in the dashboard. */
+export function getRegistryStats() {
+    if (sessions.size === 0)
+        return { count: 0, oldestAgeMs: null };
+    const now = Date.now();
+    let oldest = 0;
+    for (const entry of sessions.values()) {
+        const age = now - entry.registeredAt;
+        if (age > oldest)
+            oldest = age;
+    }
+    return { count: sessions.size, oldestAgeMs: oldest };
+}
+/** Test-only: clear the registry between tests. Never call from production. */
+export function _resetRegistryForTests() {
+    sessions.clear();
+}
+//# sourceMappingURL=hook-session-registry.js.map

package/dist/agent/path-b-installer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * PRD §6 Phase 4d / 1.18.102 — Path B installer.
+ *
+ * Drops a `.claude/settings.local.json` into a project's cwd that registers
+ * the SDK's command-type hooks to POST events at the dashboard's
+ * /api/hooks/event endpoint. The installer is opt-in per task — the user
+ * clicks "Enable hooks" on the task card after they've decided they want
+ * real per-tool latency.
+ *
+ * Why settings.local.json (not settings.json):
+ * - The SDK's `setting_sources=['project','local']` reads both. We use
+ *   the 'local' source so we never touch the user's hand-written
+ *   settings.json. settings.local.json is conventionally gitignored —
+ *   our hooks are per-machine config (they reference a localhost dashboard
+ *   token), not source-controllable.
+ * - A future "disable hooks" path can rm the file without affecting any
+ *   hand-written project settings.
+ *
+ * Auth: the hook commands include the dashboard token in the X-Dashboard-Token
+ * header. The token is baked into the curl command at install time. If the
+ * dashboard restarts and rotates its token, the user has to re-enable hooks
+ * (a small UX cost we accept; the alternative is having hooks read the
+ * token from disk at fire-time which adds a syscall to every tool call).
+ */
+export interface SettingsTemplateOptions {
+    /** Dashboard token to include in the X-Dashboard-Token header. Required. */
+    token: string;
+    /** Localhost port the dashboard is listening on. Defaults to 3030. */
+    port?: number;
+    /** Mark the file with a comment so users know who wrote it. */
+    installerVersion?: string;
+}
+/** Build the JSON content of .claude/settings.local.json. The shape matches
+ *  the SDK's hook config schema: a top-level `hooks` map keyed by event name,
+ *  each value an array of `{ hooks: [{ type, command }] }` matchers. The
+ *  empty matcher means "always fire". */
+export declare function buildSettingsTemplate(opts: SettingsTemplateOptions): Record<string, unknown>;
+export interface InstallResult {
+    ok: boolean;
+    filePath: string;
+    /** Whether the file existed before this call. */
+    wasExisting: boolean;
+    /** Whether we replaced an existing installer-managed file vs writing fresh. */
+    wasUpdate: boolean;
+    /** Set when ok=false. */
+    error?: string;
+}
+/** Write/update .claude/settings.local.json in `workDir`. If the file
+ *  already exists and is NOT installer-managed (no _clementine key), we
+ *  bail out and refuse to overwrite to avoid clobbering user content. */
+export declare function installPathBHooks(workDir: string, opts: SettingsTemplateOptions): InstallResult;
+export interface HooksStatus {
+    /** Whether a settings.local.json exists in the workDir. */
+    installed: boolean;
+    /** Whether the file is one we wrote (has _clementine sentinel). */
+    managedByUs: boolean;
+    /** Resolved path we checked (helpful for diagnostic toasts). */
+    filePath: string;
+    /** When we installed it (ISO). null if not managed by us. */
+    installedAt?: string;
+    /** Installer version that wrote it. null if not managed by us. */
+    installerVersion?: string;
+    /** True if the file exists but came from somewhere else (user). */
+    conflictsWithUser: boolean;
+}
+/** Inspect a workDir's hook installation state. Used by the dashboard's
+ *  task card to decide whether to render "Enable hooks" or "Hooks: on". */
+export declare function getHooksStatus(workDir: string): HooksStatus;
+/** Removes our installer-managed settings.local.json. Refuses if the file
+ *  isn't ours (so a misclick doesn't delete user config). */
+export declare function uninstallPathBHooks(workDir: string): {
+    ok: boolean;
+    error?: string;
+};
+//# sourceMappingURL=path-b-installer.d.ts.map

package/dist/agent/path-b-installer.js

@@ -0,0 +1,183 @@
+/**
+ * PRD §6 Phase 4d / 1.18.102 — Path B installer.
+ *
+ * Drops a `.claude/settings.local.json` into a project's cwd that registers
+ * the SDK's command-type hooks to POST events at the dashboard's
+ * /api/hooks/event endpoint. The installer is opt-in per task — the user
+ * clicks "Enable hooks" on the task card after they've decided they want
+ * real per-tool latency.
+ *
+ * Why settings.local.json (not settings.json):
+ * - The SDK's `setting_sources=['project','local']` reads both. We use
+ *   the 'local' source so we never touch the user's hand-written
+ *   settings.json. settings.local.json is conventionally gitignored —
+ *   our hooks are per-machine config (they reference a localhost dashboard
+ *   token), not source-controllable.
+ * - A future "disable hooks" path can rm the file without affecting any
+ *   hand-written project settings.
+ *
+ * Auth: the hook commands include the dashboard token in the X-Dashboard-Token
+ * header. The token is baked into the curl command at install time. If the
+ * dashboard restarts and rotates its token, the user has to re-enable hooks
+ * (a small UX cost we accept; the alternative is having hooks read the
+ * token from disk at fire-time which adds a syscall to every tool call).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/** Hooks we install. Picked for the latency dashboard's needs:
+ *  PreToolUse + PostToolUse give us tool durations (PostToolUse carries
+ *  duration_ms). SubagentStart/Stop close the gap path C handles via
+ *  transcript backfill. Stop / Notification add nice-to-have signal but
+ *  are minimal cost. */
+const HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'SubagentStart',
+    'SubagentStop',
+    'Stop',
+    'Notification',
+    'UserPromptSubmit',
+    'SessionStart',
+    'PreCompact',
+];
+/** Build the JSON content of .claude/settings.local.json. The shape matches
+ *  the SDK's hook config schema: a top-level `hooks` map keyed by event name,
+ *  each value an array of `{ hooks: [{ type, command }] }` matchers. The
+ *  empty matcher means "always fire". */
+export function buildSettingsTemplate(opts) {
+    const port = opts.port ?? 3030;
+    // Use POSIX `curl` — preinstalled on macOS and most Linuxes; Windows users
+    // running WSL or Git Bash also have it. We add `--max-time 2` so a
+    // wedged dashboard can't stall the SDK's tool execution.
+    const curlCmd = `curl -s --max-time 2 -X POST `
+        + `-H "X-Dashboard-Token: ${opts.token}" `
+        + `-H "Content-Type: application/json" `
+        + `--data-binary @- `
+        + `http://127.0.0.1:${port}/api/hooks/event`;
+    const hooks = {};
+    for (const eventName of HOOK_EVENTS) {
+        hooks[eventName] = [
+            {
+                // Empty matcher fires for every event; the dashboard endpoint
+                // can later expose a UI for restricting to specific tool names.
+                hooks: [{ type: 'command', command: curlCmd }],
+            },
+        ];
+    }
+    return {
+        // Sentinel field so we can detect (and update) installer-managed
+        // settings without touching anything else in the file.
+        _clementine: {
+            managedBy: 'clementine-agent path-b-installer',
+            installedAt: new Date().toISOString(),
+            installerVersion: opts.installerVersion ?? '1.18.102',
+            port,
+        },
+        hooks,
+    };
+}
+/** Write/update .claude/settings.local.json in `workDir`. If the file
+ *  already exists and is NOT installer-managed (no _clementine key), we
+ *  bail out and refuse to overwrite to avoid clobbering user content. */
+export function installPathBHooks(workDir, opts) {
+    if (!workDir)
+        return { ok: false, filePath: '', wasExisting: false, wasUpdate: false, error: 'workDir required' };
+    if (!opts.token)
+        return { ok: false, filePath: '', wasExisting: false, wasUpdate: false, error: 'token required' };
+    const dir = path.join(workDir, '.claude');
+    const file = path.join(dir, 'settings.local.json');
+    let wasExisting = false;
+    let wasUpdate = false;
+    if (existsSync(file)) {
+        wasExisting = true;
+        try {
+            const raw = readFileSync(file, 'utf-8');
+            const parsed = JSON.parse(raw);
+            // Only proceed if the file was previously installed by us.
+            if (!parsed._clementine || typeof parsed._clementine !== 'object') {
+                return {
+                    ok: false,
+                    filePath: file,
+                    wasExisting: true,
+                    wasUpdate: false,
+                    error: 'settings.local.json exists but was not created by clementine — refusing to overwrite. Move or delete the file and retry.',
+                };
+            }
+            wasUpdate = true;
+        }
+        catch (err) {
+            return {
+                ok: false,
+                filePath: file,
+                wasExisting: true,
+                wasUpdate: false,
+                error: 'could not parse existing settings.local.json: ' + String(err),
+            };
+        }
+    }
+    try {
+        mkdirSync(dir, { recursive: true });
+        const content = buildSettingsTemplate(opts);
+        writeFileSync(file, JSON.stringify(content, null, 2) + '\n');
+        return { ok: true, filePath: file, wasExisting, wasUpdate };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            filePath: file,
+            wasExisting,
+            wasUpdate,
+            error: 'failed to write settings.local.json: ' + String(err),
+        };
+    }
+}
+/** Inspect a workDir's hook installation state. Used by the dashboard's
+ *  task card to decide whether to render "Enable hooks" or "Hooks: on". */
+export function getHooksStatus(workDir) {
+    const filePath = path.join(workDir, '.claude', 'settings.local.json');
+    if (!existsSync(filePath)) {
+        return { installed: false, managedByUs: false, filePath, conflictsWithUser: false };
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const sentinel = parsed._clementine;
+        if (sentinel && typeof sentinel === 'object') {
+            return {
+                installed: true,
+                managedByUs: true,
+                filePath,
+                installedAt: sentinel.installedAt,
+                installerVersion: sentinel.installerVersion,
+                conflictsWithUser: false,
+            };
+        }
+        return { installed: true, managedByUs: false, filePath, conflictsWithUser: true };
+    }
+    catch {
+        // Couldn't parse — treat as a user file we shouldn't touch.
+        return { installed: true, managedByUs: false, filePath, conflictsWithUser: true };
+    }
+}
+/** Removes our installer-managed settings.local.json. Refuses if the file
+ *  isn't ours (so a misclick doesn't delete user config). */
+export function uninstallPathBHooks(workDir) {
+    const filePath = path.join(workDir, '.claude', 'settings.local.json');
+    if (!existsSync(filePath))
+        return { ok: true };
+    const status = getHooksStatus(workDir);
+    if (!status.managedByUs) {
+        return { ok: false, error: 'settings.local.json is not managed by clementine — refusing to delete' };
+    }
+    try {
+        // Use unlinkSync via dynamic import to keep the static fs imports list
+        // tight; this path is rarely invoked.
+        const fs = require('node:fs');
+        fs.unlinkSync(filePath);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: 'failed to remove: ' + String(err) };
+    }
+}
+//# sourceMappingURL=path-b-installer.js.map

package/dist/agent/run-agent.js

@@ -253,7 +253,12 @@ export async function runAgent(prompt, opts) {
         systemPrompt: profileAppend
             ? { type: 'preset', preset: 'claude_code', append: profileAppend }
             : { type: 'preset', preset: 'claude_code' },
-        settingSources: opts.settingSources ?? ['project'],
+        // PRD §6 Phase 4d / 1.18.102: read both project and local sources by
+        // default. The path B installer writes to .claude/settings.local.json
+        // (which the SDK reads under the 'local' source) so we never clobber
+        // the user's hand-written .claude/settings.json. Callers can still
+        // override settingSources via opts.
+        settingSources: opts.settingSources ?? ['project', 'local'],
         agents,
         // SDK's McpServerConfig is a union; cast at the boundary since
         // callers can mix stdio + http + sse server shapes.
@@ -325,6 +330,17 @@ export async function runAgent(prompt, opts) {
                 }
                 // PRD Phase 4a / 1.18.85: write the session_start Event row.
                 writeEvent({ kind: 'session_start', ts: new Date().toISOString(), sessionId });
+                // PRD Phase 4d / 1.18.101: register this session in the path B
+                // hook-session registry so /api/hooks/event POSTs from the SDK can
+                // resolve sessionId → runId/eventLog and write into the same JSONL.
+                // Best-effort — telemetry must never block the run from progressing.
+                try {
+                    const { registerRunSession } = await import('./hook-session-registry.js');
+                    registerRunSession(sessionId, runId, eventLog, eventSeq);
+                }
+                catch (regErr) {
+                    logger.debug({ regErr }, 'runAgent: hook-session registry register failed (non-fatal)');
+                }
                 logger.debug({ sessionKey: opts.sessionKey, sdkSessionId: sessionId, runId }, 'runAgent: SDK session initialized');
                 continue;
             }
@@ -428,6 +444,13 @@ export async function runAgent(prompt, opts) {
                     costUsd: totalCostUsd,
                     stopReason: subtype,
                 });
+                // PRD Phase 4d / 1.18.101: unregister from the hook-session registry.
+                // Late-arriving hook events for this sessionId silently drop after this.
+                try {
+                    const { unregisterRunSession } = await import('./hook-session-registry.js');
+                    unregisterRunSession(sessionId);
+                }
+                catch { /* non-fatal */ }
                 // Mirror cost to usage_log. Same shape as the existing
                 // logQueryResult, but standalone so we don't depend on
                 // PersonalAssistant's instance state.
@@ -466,6 +489,14 @@ export async function runAgent(prompt, opts) {
             sessionId,
             toolError: errMsg,
         });
+        // PRD Phase 4d / 1.18.101: also clear path B registry on error path so
+        // the map doesn't leak entries when runs fail before session_end fires.
+        try {
+            const { unregisterRunSession } = await import('./hook-session-registry.js');
+            if (sessionId)
+                unregisterRunSession(sessionId);
+        }
+        catch { /* non-fatal */ }
         // Translate the SDK's budget-exhaustion throw into a message that
         // tells the user (a) what cap tripped and (b) how to raise it.
         // The raw SDK string ("Claude Code returned an error result:

package/dist/cli/dashboard.js

@@ -4594,6 +4594,101 @@ export async function cmdDashboard(opts) {
     // path on runAgentCron honors the signal and unwinds cleanly. The
     // CronScheduler's own catch path then writes the closing CronRunEntry
     // with status='error' + an "AbortError" message.
+    // ── PRD §6 Phase 4d / 1.18.102: Path B opt-in install ──────────
+    // Three endpoints for managing the .claude/settings.local.json hook
+    // wiring on a per-task basis. Hooks are opt-in (the user picks which
+    // tasks should pay the small per-tool overhead of curl-on-every-event)
+    // and the installer refuses to overwrite a settings.local.json that
+    // wasn't created by us.
+    app.get('/api/cron/:job/hooks-status', async (req, res) => {
+        try {
+            const jobName = req.params.job;
+            if (!jobName) {
+                res.status(400).json({ ok: false, error: 'job required' });
+                return;
+            }
+            // Find the job's workDir from the cron definitions.
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const job = jobs.find((j) => String(j.name).toLowerCase() === jobName.toLowerCase());
+            if (!job) {
+                res.status(404).json({ ok: false, error: `job "${jobName}" not found` });
+                return;
+            }
+            if (!job.workDir) {
+                res.json({ ok: true, status: { installed: false, managedByUs: false, filePath: '', conflictsWithUser: false }, message: 'Task has no workDir set — hooks need a project directory.' });
+                return;
+            }
+            const { getHooksStatus } = await import('../agent/path-b-installer.js');
+            const status = getHooksStatus(job.workDir);
+            res.json({ ok: true, workDir: job.workDir, status });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/cron/:job/enable-hooks', async (req, res) => {
+        try {
+            const jobName = req.params.job;
+            if (!jobName) {
+                res.status(400).json({ ok: false, error: 'job required' });
+                return;
+            }
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const job = jobs.find((j) => String(j.name).toLowerCase() === jobName.toLowerCase());
+            if (!job) {
+                res.status(404).json({ ok: false, error: `job "${jobName}" not found` });
+                return;
+            }
+            if (!job.workDir) {
+                res.status(400).json({ ok: false, error: 'task has no workDir set' });
+                return;
+            }
+            const port = Number(process.env.PORT) || 3030;
+            const { installPathBHooks } = await import('../agent/path-b-installer.js');
+            const result = installPathBHooks(job.workDir, { token: dashboardToken, port });
+            if (!result.ok) {
+                res.status(409).json({ ...result, ok: false });
+                return;
+            }
+            const { ok: _ignore, ...rest } = result;
+            res.json({ ...rest, ok: true, message: result.wasUpdate ? 'Hooks updated.' : 'Hooks installed. The next run of this task will emit per-tool latency to the dashboard.' });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/cron/:job/disable-hooks', async (req, res) => {
+        try {
+            const jobName = req.params.job;
+            if (!jobName) {
+                res.status(400).json({ ok: false, error: 'job required' });
+                return;
+            }
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const job = jobs.find((j) => String(j.name).toLowerCase() === jobName.toLowerCase());
+            if (!job) {
+                res.status(404).json({ ok: false, error: `job "${jobName}" not found` });
+                return;
+            }
+            if (!job.workDir) {
+                res.status(400).json({ ok: false, error: 'task has no workDir set' });
+                return;
+            }
+            const { uninstallPathBHooks } = await import('../agent/path-b-installer.js');
+            const result = uninstallPathBHooks(job.workDir);
+            if (!result.ok) {
+                res.status(409).json({ ok: false, error: result.error });
+                return;
+            }
+            res.json({ ok: true, message: 'Hooks disabled. The next run of this task will use only the in-process tap (path A).' });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
     app.post('/api/cron/run/:job/cancel', async (req, res) => {
         try {
             const jobName = req.params.job;
@@ -5720,6 +5815,87 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
+    // ── PRD Phase 4d / 1.18.101: Path B hook event ingest ──────────
+    // The Claude Agent SDK supports `.claude/settings.json`-registered command
+    // hooks (PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop,
+    // Notification, etc.). When a hook fires the SDK pipes JSON to the
+    // command's stdin; the command can POST that JSON to this endpoint to
+    // get the event recorded in the same per-run JSONL the in-process tap
+    // (path A) writes to. The result: real per-tool-call durations,
+    // approval-required events, and stop-reason hooks land in the Run detail
+    // viewer's waterfall + the Latency dashboard's split bar.
+    //
+    // Auth: dashboard token via X-Dashboard-Token header. The daemon
+    // exposes the token via CLEMENTINE_DASHBOARD_TOKEN env var, which the
+    // SDK subprocess inherits — settings.json hook commands curl this
+    // endpoint with that header.
+    app.post('/api/hooks/event', express.json({ limit: '256kb' }), async (req, res) => {
+        try {
+            const headerToken = String(req.header('x-dashboard-token') || '');
+            if (!dashboardToken || headerToken !== dashboardToken) {
+                res.status(401).json({ ok: false, error: 'invalid dashboard token' });
+                return;
+            }
+            const body = (req.body ?? {});
+            const sessionId = String(body.session_id || body.sessionId || '');
+            const hookEventName = String(body.hook_event_name || body.hookEventName || 'unknown');
+            if (!sessionId) {
+                res.status(400).json({ ok: false, error: 'session_id required in payload' });
+                return;
+            }
+            const { getRunSession, nextSeqForSession, sweepStaleSessions } = await import('../agent/hook-session-registry.js');
+            // Best-effort sweep on every POST — keeps the map bounded without a timer.
+            sweepStaleSessions();
+            const entry = getRunSession(sessionId);
+            if (!entry) {
+                // Late-arriving hook for a session we already closed (or never
+                // saw because path A registration didn't complete). Drop and tell
+                // the caller — the curl exits 0 either way so it doesn't fail
+                // the SDK's run.
+                res.status(202).json({ ok: false, dropped: true, reason: 'session not registered (race or post-end)' });
+                return;
+            }
+            const seq = nextSeqForSession(sessionId);
+            // Synthesize a RunEvent. The hook payload's shape varies by event
+            // kind; we extract the fields the dashboard waterfall renders and
+            // stash the full payload for advanced filtering later.
+            const ev = {
+                runId: entry.runId,
+                seq: seq ?? 1_000_000,
+                kind: 'hook',
+                ts: new Date().toISOString(),
+                sessionId,
+                hookEventName,
+            };
+            // Tool fields if present (PreToolUse / PostToolUse).
+            if (typeof body.tool_name === 'string')
+                ev.toolName = body.tool_name;
+            if (typeof body.tool_use_id === 'string')
+                ev.toolUseId = body.tool_use_id;
+            if (body.tool_input !== undefined)
+                ev.toolInput = body.tool_input;
+            if (body.tool_response !== undefined)
+                ev.toolResult = body.tool_response;
+            // PostToolUse can carry an explicit duration_ms (the SDK's stopwatch
+            // wraps the tool call). When present we surface it onto the event so
+            // the latency dashboard sums real numbers instead of the heuristic.
+            if (typeof body.duration_ms === 'number')
+                ev.durationMs = body.duration_ms;
+            if (typeof body.parent_tool_use_id === 'string')
+                ev.parentToolUseId = body.parent_tool_use_id;
+            // Errors: PostToolUse can flag a non-zero result; surface as toolError.
+            if (body.is_error === true) {
+                ev.toolError = typeof body.tool_response === 'string'
+                    ? body.tool_response.slice(0, 500)
+                    : 'tool returned is_error=true';
+            }
+            entry.eventLog.append(ev);
+            res.json({ ok: true, runId: entry.runId, seq });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
     // ── PRD Phase 4a / 1.18.85: per-run Event store reader ─────────
     // Returns every event captured by path A (in-process tap in runAgent)
     // for one run. Used by the new Run detail page (Phase 4b).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.100",
+  "version": "1.18.102",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",