@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/cli/hook/hook-command.js

@@ -0,0 +1,211 @@
+/**
+ * `reticle hook install|uninstall|status|prompt`: the prompt-capture hook, outside `init`.
+ *
+ * `init` installs the hook for the agents it finds. These are the same steps on their own: add it
+ * to a project wired before the hook existed, remove exactly what was added, or say per agent
+ * whether prompts are captured. `prompt` is what the agent hook itself runs.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { AGENT_FLAG, MCP_FALLBACK_AGENTS, PROMPT_CAPTURE_NOTICE, PROMPT_HOOK_AGENTS, PromptHookAgent, PromptHookStatus, claudeAvailableProbe, installPromptHook, promptHookInstalled, promptHookNpxOnly, promptHookTargets, uninstallPromptHook, } from '@reticlehq/init';
+import { ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { discoverProjectConfigs } from '../config/config-discovery.js';
+import { agentCaptureOff, agentCaptureOffIn, capturePrompt, hookAck } from './prompt-hook.js';
+import { captureToolCall, toolHookAck } from './tool-hook.js';
+import { AT_FLAG, PROMPT_WRITE_ACTION, TOOL_WRITE_ACTION, hookBinFor } from './hook-fast.js';
+import { exportStructure } from './episode-structure.js';
+const HookAction = {
+    PROMPT: 'prompt',
+    /** What the agent's post-tool hook runs: one of the agent's own tool calls. */
+    TOOL: 'tool',
+    /** The episodes, for a dataset: `--structure` is the text-free page structure per step. */
+    EXPORT: 'export',
+    INSTALL: 'install',
+    UNINSTALL: 'uninstall',
+    STATUS: 'status',
+};
+const STRUCTURE_FLAG = '--structure';
+/** An agent hook that names none is Claude Code's: the stand-in this command replaces was. */
+const DEFAULT_AGENT = PromptHookAgent.CLAUDE_CODE;
+/** The payload is a few kilobytes. More than this is not a prompt payload, and is not read. */
+const MAX_STDIN_BYTES = 1024 * 1024;
+/** A hook whose agent never closes stdin must still end, and let the prompt through. */
+const STDIN_WAIT_MS = 3_000;
+const readText = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const fileIo = { exists: existsSync, readFile: readText };
+/** The project folder `cwd` belongs to: the nearest `.reticle.json` above it, else `cwd`. */
+export function projectDirOf(cwd) {
+    return discoverProjectConfigs(cwd).found[0]?.directory ?? cwd;
+}
+export function claudeCliHere() {
+    const probe = claudeAvailableProbe();
+    return 0 === spawnSync(probe.command, probe.args, { stdio: 'ignore', timeout: 5_000 }).status;
+}
+/** The payload on stdin, bounded in size and in time. Never rejects. */
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        const done = () => {
+            clearTimeout(timer);
+            resolve(data);
+        };
+        const timer = setTimeout(done, STDIN_WAIT_MS);
+        timer.unref();
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+            if (MAX_STDIN_BYTES < data.length) {
+                data = '';
+                done();
+            }
+        });
+        process.stdin.on('end', done);
+        process.stdin.on('error', done);
+    });
+}
+/**
+ * One row per agent: does it capture prompts here, through its hook or the MCP instructions, or is
+ * capture off. `reticle doctor` prints the same rows.
+ */
+export function promptCaptureRows(projectDir, env, claudeCli, home = homedir()) {
+    if (agentCaptureOff(env)) {
+        return [`off on this machine (${ReticleEnv.PROMPT_CAPTURE})`];
+    }
+    if (agentCaptureOffIn(projectDir)) {
+        return ['off in this project ("promptCapture": false in .reticle.json)'];
+    }
+    // The project only, as `install` reads it: a row says what `install` would do here.
+    const targets = promptHookTargets(fileIo, projectDir, undefined, claudeCli, join);
+    // Where the bin can run directly (not Windows), an npx-only install is slower than it needs to be.
+    const direct = hookBinFor(home, process.platform) !== undefined;
+    const rows = targets.map((t) => {
+        if (!promptHookInstalled(t.spec, t.existing)) {
+            return `✗ ${t.spec.label}: no hook; run \`reticle hook install\``;
+        }
+        const slow = direct && promptHookNpxOnly(t.spec, t.existing)
+            ? `, through npx (~400 ms slower per call); run \`reticle hook install\` to run it directly`
+            : '';
+        return `✓ ${t.spec.label}: hook installed (${t.path})${slow}${t.spec.activation === undefined ? '' : `. ${t.spec.activation}`}`;
+    });
+    rows.push(`MCP instructions only: ${MCP_FALLBACK_AGENTS.join(', ')}`);
+    return rows;
+}
+function install(cwd, print) {
+    const projectDir = projectDirOf(cwd);
+    // The project's own agents only. An agent installed on this machine is not one this repo uses.
+    const targets = promptHookTargets(fileIo, projectDir, undefined, claudeCliHere(), join);
+    if (0 === targets.length) {
+        print('No agent with a prompt hook is used here. The MCP instructions cover the others.');
+        return 0;
+    }
+    let failed = 0;
+    for (const target of targets) {
+        const merged = installPromptHook(target.spec, target.existing, hookBinFor(homedir(), process.platform));
+        if (PromptHookStatus.ALREADY === merged.status) {
+            print(`✓ ${target.spec.label}: already installed (${target.path})`);
+        }
+        else if (PromptHookStatus.MANUAL === merged.status) {
+            failed++;
+            print(`✗ ${target.spec.label}: ${target.path} is not plain JSON, so it was left alone`);
+        }
+        else {
+            mkdirSync(dirname(target.path), { recursive: true });
+            writeFileSync(target.path, merged.content);
+            print(`✓ ${target.spec.label}: installed (${target.path})`);
+        }
+        if (target.spec.activation !== undefined) {
+            print(`  ${target.spec.activation}`);
+        }
+    }
+    print(PROMPT_CAPTURE_NOTICE);
+    return 0 === failed ? 0 : 1;
+}
+/** Remove our entry from every config any agent reads here. Other entries stay. */
+function uninstall(cwd, print) {
+    const projectDir = projectDirOf(cwd);
+    let removed = 0;
+    for (const spec of PROMPT_HOOK_AGENTS) {
+        for (const rel of spec.paths) {
+            const path = join(projectDir, rel);
+            const out = uninstallPromptHook(spec, readText(path));
+            if (!out.changed) {
+                continue;
+            }
+            removed++;
+            if (null === out.content) {
+                rmSync(path, { force: true });
+            }
+            else {
+                writeFileSync(path, out.content);
+            }
+            print(`✓ ${spec.label}: removed (${path})`);
+        }
+    }
+    if (0 === removed) {
+        print('No prompt-capture hook was installed here.');
+    }
+    return 0;
+}
+export async function handleHook(argv, print = (line) => process.stdout.write(`${line}\n`)) {
+    const action = argv[0] ?? HookAction.STATUS;
+    const cwd = process.cwd();
+    // `prompt` normally never reaches here either: the fast path answers it and runs `prompt-write`.
+    if (HookAction.PROMPT === action || PROMPT_WRITE_ACTION === action) {
+        const at = argv.indexOf(AGENT_FLAG);
+        const agent = (-1 === at ? undefined : argv[at + 1]) ?? DEFAULT_AGENT;
+        // The fast path's writer is told when the prompt arrived; run directly, it is now.
+        const given = Number(argv[argv.indexOf(AT_FLAG) + 1]);
+        const arrived = -1 !== argv.indexOf(AT_FLAG) && Number.isFinite(given) ? given : Date.now();
+        capturePrompt(agent, await readStdin(), { cwd, env: process.env, now: () => arrived });
+        if (HookAction.PROMPT === action) {
+            process.stdout.write(hookAck(agent));
+        }
+        return 0;
+    }
+    // `tool` normally never reaches here: `bin/reticle.js` answers it on the fast path and runs
+    // `tool-write`, the capture itself, in a detached child. Both write the same record.
+    if (HookAction.TOOL === action || TOOL_WRITE_ACTION === action) {
+        const at = argv.indexOf(AGENT_FLAG);
+        const agent = (-1 === at ? undefined : argv[at + 1]) ?? DEFAULT_AGENT;
+        const payload = await readStdin();
+        captureToolCall(agent, payload, { cwd, env: process.env, now: () => Date.now() });
+        if (HookAction.TOOL === action) {
+            process.stdout.write(toolHookAck(agent, payload));
+        }
+        return 0;
+    }
+    if (HookAction.EXPORT === action) {
+        if (!argv.includes(STRUCTURE_FLAG)) {
+            print(`hook export needs ${STRUCTURE_FLAG}: the text-free page structure is the only export.`);
+            return 1;
+        }
+        const root = join(projectDirOf(cwd), ReticleDir.ROOT);
+        const summary = exportStructure(root, (line) => process.stdout.write(`${line}\n`));
+        process.stderr.write(`${String(summary.steps)} snapshot steps exported; ${String(summary.skippedCut)} cut short and skipped\n`);
+        return 0;
+    }
+    if (HookAction.INSTALL === action) {
+        return install(cwd, print);
+    }
+    if (HookAction.UNINSTALL === action) {
+        return uninstall(cwd, print);
+    }
+    if (HookAction.STATUS === action) {
+        const rows = promptCaptureRows(projectDirOf(cwd), process.env, claudeCliHere());
+        for (const row of rows) {
+            print(row);
+        }
+        return 0;
+    }
+    print(`unknown hook action: ${action}. Use install, uninstall, status, prompt --agent <id>, tool --agent <id> or export --structure.`);
+    return 1;
+}

package/dist/command/cli/hook/hook-fast.d.ts

@@ -0,0 +1,31 @@
+/** The actions the detached writers run. Not for people: `hook tool` and `hook prompt` are. */
+export declare const TOOL_WRITE_ACTION = "tool-write";
+export declare const PROMPT_WRITE_ACTION = "prompt-write";
+/** The prompt's arrival time, handed to its writer: a writer that finishes late is still ordered. */
+export declare const AT_FLAG = "--at";
+/**
+ * This CLI's bin as an agent hook should name it: `$HOME/...` when under the home folder, so no
+ * user name lands in a committed file; undefined on Windows, whose shells do not all read `||`
+ * and `$HOME`, so the hooks there stay on npx alone. See `directHookCommand` in `@reticlehq/init`.
+ */
+export declare function hookBinFor(home: string, platform: string, bin?: string): string | undefined;
+/** What the hook prints. Cursor and Gemini CLI read stdout as JSON; the rest need nothing. */
+export declare function toolHookAck(agent: string, payload?: string): string;
+/** What the prompt hook prints. Cursor reads `{ continue }`, Gemini CLI any JSON; the rest nothing. */
+export declare function promptHookAck(agent: string): string;
+interface FastIo {
+    readStdin: () => Promise<string>;
+    write: (text: string) => void;
+    /** Start the writer, detached, with `input` on its stdin. Resolves once the input is handed over. */
+    spawnWriter: (args: readonly string[], input: string) => Promise<void>;
+    now?: () => number;
+}
+export declare function runToolHookFast(argv: readonly string[], io: FastIo): Promise<void>;
+/**
+ * The prompt hook: let the prompt through at once, keep it in a detached writer. The writer gets
+ * the arrival time, so an older prompt never replaces a newer one however the writers finish.
+ */
+export declare function runPromptHookFast(argv: readonly string[], io: FastIo): Promise<void>;
+/** The process entry `bin/reticle.js` calls for `hook tool` or `hook prompt`. Always exits 0. */
+export declare function mainHookFast(action: string, argv: readonly string[]): Promise<void>;
+export {};

package/dist/command/cli/hook/hook-fast.js

@@ -0,0 +1,136 @@
+/**
+ * The post-tool hook's fast path: answer at once, write in a detached child.
+ *
+ * Cursor and Gemini CLI wait for a hook to exit, and document no background option. Through the
+ * full CLI the hook took p50 ~300 ms per call (100 synthetic payloads each), almost all of it
+ * loading modules the hook never uses. `bin/reticle.js` sends `hook tool` here before the CLI
+ * loads. This module imports only Node built-ins: it reads the payload, prints the agent's answer,
+ * pipes the payload to a detached `hook tool-write` (the real capture, `tool-hook.ts`), and returns.
+ *
+ * Kept free of `@reticlehq/*` imports on purpose: every import here is paid on every tool call.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+/** The actions the detached writers run. Not for people: `hook tool` and `hook prompt` are. */
+export const TOOL_WRITE_ACTION = 'tool-write';
+export const PROMPT_WRITE_ACTION = 'prompt-write';
+/** The prompt's arrival time, handed to its writer: a writer that finishes late is still ordered. */
+export const AT_FLAG = '--at';
+const HOOK_COMMAND = 'hook';
+const PROMPT_ACTION = 'prompt';
+const WINDOWS = 'win32';
+const CURSOR = 'cursor';
+const GEMINI = 'gemini';
+const CODEX = 'codex';
+/** Read without parsing: the fast path pays for every byte of work on every call. */
+const CODEX_STOP = /"hook_event_name"\s*:\s*"Stop"/;
+/** The payload is a few kilobytes. More than this is not a hook payload, and is not read. */
+const MAX_STDIN_BYTES = 1024 * 1024;
+/** An agent that never closes stdin must still get its answer. */
+const STDIN_WAIT_MS = 3_000;
+/** `bin/reticle.js`, from `dist/command/cli/hook/hook-fast.js`. */
+const BIN = fileURLToPath(new URL('../../../../bin/reticle.js', import.meta.url));
+/**
+ * This CLI's bin as an agent hook should name it: `$HOME/...` when under the home folder, so no
+ * user name lands in a committed file; undefined on Windows, whose shells do not all read `||`
+ * and `$HOME`, so the hooks there stay on npx alone. See `directHookCommand` in `@reticlehq/init`.
+ */
+export function hookBinFor(home, platform, bin = BIN) {
+    if (WINDOWS === platform) {
+        return undefined;
+    }
+    const under = 0 < home.length && bin.startsWith(`${home}/`);
+    return under ? `$HOME${bin.slice(home.length)}` : bin;
+}
+/** What the hook prints. Cursor and Gemini CLI read stdout as JSON; the rest need nothing. */
+export function toolHookAck(agent, payload = '') {
+    if (CURSOR === agent || GEMINI === agent) {
+        return '{}\n';
+    }
+    // Codex's Stop rejects plain text and wants JSON when it exits 0; its other hooks need nothing.
+    return CODEX === agent && CODEX_STOP.test(payload) ? '{}\n' : '';
+}
+/** What the prompt hook prints. Cursor reads `{ continue }`, Gemini CLI any JSON; the rest nothing. */
+export function promptHookAck(agent) {
+    if (CURSOR === agent) {
+        return `${JSON.stringify({ continue: true })}\n`;
+    }
+    return GEMINI === agent ? '{}\n' : '';
+}
+const agentOf = (argv) => {
+    const at = argv.indexOf('--agent');
+    return (-1 === at ? undefined : argv[at + 1]) ?? 'claude-code';
+};
+export async function runToolHookFast(argv, io) {
+    const agent = agentOf(argv);
+    const payload = await io.readStdin();
+    io.write(toolHookAck(agent, payload));
+    try {
+        await io.spawnWriter([HOOK_COMMAND, TOOL_WRITE_ACTION, ...argv], payload);
+    }
+    catch {
+        // A lost record is better than an agent told its tool failed.
+    }
+}
+/**
+ * The prompt hook: let the prompt through at once, keep it in a detached writer. The writer gets
+ * the arrival time, so an older prompt never replaces a newer one however the writers finish.
+ */
+export async function runPromptHookFast(argv, io) {
+    const arrived = (io.now ?? Date.now)();
+    const payload = await io.readStdin();
+    io.write(promptHookAck(agentOf(argv)));
+    try {
+        await io.spawnWriter([HOOK_COMMAND, PROMPT_WRITE_ACTION, ...argv, AT_FLAG, String(arrived)], payload);
+    }
+    catch {
+        // A prompt that is not kept must still go through.
+    }
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        const done = () => {
+            clearTimeout(timer);
+            resolve(data);
+        };
+        const timer = setTimeout(done, STDIN_WAIT_MS);
+        timer.unref();
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+            if (MAX_STDIN_BYTES < data.length) {
+                data = '';
+                done();
+            }
+        });
+        process.stdin.on('end', done);
+        process.stdin.on('error', done);
+    });
+}
+function spawnWriter(args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [BIN, ...args], {
+            detached: true,
+            stdio: ['pipe', 'ignore', 'ignore'],
+            windowsHide: true,
+        });
+        child.on('error', reject);
+        child.stdin.end(input, () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+/** The process entry `bin/reticle.js` calls for `hook tool` or `hook prompt`. Always exits 0. */
+export async function mainHookFast(action, argv) {
+    const io = { readStdin, write: (text) => process.stdout.write(text), spawnWriter };
+    if (PROMPT_ACTION === action) {
+        await runPromptHookFast(argv, io);
+    }
+    else {
+        await runToolHookFast(argv, io);
+    }
+    // Exit only once the answer is flushed: an exit can drop a pipe write still in flight.
+    process.stdout.write('', () => process.exit(0));
+}

package/dist/command/cli/hook/prompt-hook.d.ts

@@ -0,0 +1,30 @@
+export { agentCaptureOff, agentCaptureOffIn } from '../../../memory/intent/record-request.js';
+/**
+ * The prompt and the folder it was sent from, read from one agent's payload.
+ *
+ * Every agent sends `prompt` except Windsurf (`tool_info.user_prompt`). Every agent sends `cwd`
+ * except Cursor (`workspace_roots`) and Windsurf (none: its hook runs in the workspace root).
+ */
+export declare function promptFromPayload(agent: string, payload: unknown, fallbackCwd: string, env: NodeJS.ProcessEnv): {
+    prompt: string | undefined;
+    cwd: string;
+};
+/** What the prompt hook prints; one table with the fast path's. */
+export { promptHookAck as hookAck } from './hook-fast.js';
+/**
+ * The `.reticle` folders a prompt sent from `cwd` belongs in.
+ *
+ * The nearest project above `cwd`, and every app below it that declares the same project id. In a
+ * monorepo `init` writes the app's config at the root too, and the app's runs read the request
+ * from the APP's `.reticle`, so a prompt kept only at the root is a prompt no run ever carries.
+ */
+export declare function captureRoots(cwd: string): string[];
+interface CaptureIo {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly now: () => number;
+}
+/** Keep one prompt. Never throws: the folders it wrote to, or none. */
+export declare function capturePrompt(agent: string, raw: string, io: CaptureIo): {
+    written: string[];
+};

package/dist/command/cli/hook/prompt-hook.js

@@ -0,0 +1,199 @@
+/**
+ * `reticle hook prompt --agent <id>`: what an agent's prompt-submit hook runs.
+ *
+ * The user's request is what a verdict is checked against, and an agent relays it only when it
+ * remembers to. So the agent's own hook hands it over, before the model reads it. This writes, in
+ * the project's `.reticle/`:
+ *
+ *   request.json    the newest prompt, in the shape `reticle_intent { declare, request }` writes;
+ *                   a run written soon after carries it, so it reaches the user's own linked
+ *                   workspace with that run when the project shares requests;
+ *   requests.jsonl  every prompt, one line each, oldest first.
+ *
+ * Secrets are redacted before anything is written. It stays offline, finishes fast, writes nothing
+ * outside `.reticle/`, and never blocks the prompt: every failure is exit 0 and nothing written.
+ * Nothing here reaches telemetry: `cli.ts` runs this before it reports the command.
+ */
+import { closeSync, constants, existsSync, fstatSync, ftruncateSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, writeSync, } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { PromptHookAgent } from '@reticlehq/init';
+import { PromptContextSchema } from '@reticlehq/core/artifacts';
+import { discoverProjectConfigs } from '../config/config-discovery.js';
+import { MAX_REQUEST, agentCaptureOff, agentCaptureOffIn, promptContextFor, redactSecrets, sharesRequests, } from '../../../memory/intent/record-request.js';
+export { agentCaptureOff, agentCaptureOffIn } from '../../../memory/intent/record-request.js';
+import { readTextOrUndefined } from '../../../memory/project/fs/fs-port.js';
+import { WORKSPACE_GITIGNORE, workspaceGitignore, } from '../../../memory/journal/on-disk/workspace-gitignore.js';
+/** A hook fired twice for one prompt (VS Code and Copilot CLI read one file) keeps one copy. */
+const DUPLICATE_WINDOW_MS = 10_000;
+/** The history moves aside once it passes this size, so `.reticle/` cannot grow without end. */
+const MAX_HISTORY_BYTES = 2 * 1024 * 1024;
+/**
+ * The tags an agent harness wraps around a prompt it wrote for itself: a background task that
+ * finished, a slash command, a shell escape, a reminder. Only these names. A user prompt that starts
+ * with a tag of their own (`<Button> must be disabled`) is a real request, and is kept.
+ */
+const HARNESS_TAGS = [
+    'system-reminder',
+    'task-notification',
+    'agent-message',
+    'cross-session-message',
+    'teammate-message',
+    'command-name',
+    'command-message',
+    'command-args',
+    'local-command-stdout',
+    'local-command-stderr',
+    'local-command-caveat',
+    'bash-input',
+    'bash-stdout',
+    'bash-stderr',
+    'persisted-output',
+    'user-prompt-submit-hook',
+];
+const HARNESS_PROMPT = new RegExp(`^<(?:${HARNESS_TAGS.join('|')})[\\s>]`);
+/** Where each agent names its project when the payload does not. */
+const PROJECT_DIR_ENV = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'GEMINI_PROJECT_DIR'];
+const JSON_INDENT = 2;
+const isObject = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
+const text = (value) => 'string' === typeof value && 0 < value.trim().length ? value : undefined;
+/**
+ * The prompt and the folder it was sent from, read from one agent's payload.
+ *
+ * Every agent sends `prompt` except Windsurf (`tool_info.user_prompt`). Every agent sends `cwd`
+ * except Cursor (`workspace_roots`) and Windsurf (none: its hook runs in the workspace root).
+ */
+export function promptFromPayload(agent, payload, fallbackCwd, env) {
+    const body = isObject(payload) ? payload : {};
+    const toolInfo = isObject(body['tool_info']) ? body['tool_info'] : {};
+    const prompt = PromptHookAgent.WINDSURF === agent
+        ? (text(toolInfo['user_prompt']) ?? text(body['prompt']))
+        : (text(body['prompt']) ?? text(toolInfo['user_prompt']));
+    const roots = Array.isArray(body['workspace_roots']) ? body['workspace_roots'] : [];
+    const cwd = text(body['cwd']) ??
+        text(roots[0]) ??
+        PROJECT_DIR_ENV.map((name) => text(env[name])).find((dir) => dir !== undefined) ??
+        fallbackCwd;
+    return { prompt, cwd };
+}
+/** What the prompt hook prints; one table with the fast path's. */
+export { promptHookAck as hookAck } from './hook-fast.js';
+/**
+ * The `.reticle` folders a prompt sent from `cwd` belongs in.
+ *
+ * The nearest project above `cwd`, and every app below it that declares the same project id. In a
+ * monorepo `init` writes the app's config at the root too, and the app's runs read the request
+ * from the APP's `.reticle`, so a prompt kept only at the root is a prompt no run ever carries.
+ */
+export function captureRoots(cwd) {
+    if (!existsSync(cwd)) {
+        return [];
+    }
+    const { found } = discoverProjectConfigs(cwd);
+    const nearest = found.find((config) => isWithin(config.directory, cwd));
+    if (nearest === undefined) {
+        return [];
+    }
+    const apps = found.filter((config) => config.directory !== nearest.directory &&
+        config.projectId !== undefined &&
+        config.projectId === nearest.projectId &&
+        isWithin(nearest.directory, config.directory));
+    return [nearest, ...apps].map((config) => join(config.directory, ReticleDir.ROOT));
+}
+/** Is `inner` the folder `outer` or inside it? */
+function isWithin(outer, inner) {
+    const rel = relative(outer, inner);
+    return '' === rel || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/** Keep one prompt. Never throws: the folders it wrote to, or none. */
+export function capturePrompt(agent, raw, io) {
+    try {
+        if (agentCaptureOff(io.env)) {
+            return { written: [] };
+        }
+        const { prompt, cwd } = promptFromPayload(agent, JSON.parse(raw), io.cwd, io.env);
+        if (prompt === undefined || HARNESS_PROMPT.test(prompt.trim())) {
+            return { written: [] };
+        }
+        const written = [];
+        for (const root of captureRoots(cwd)) {
+            if (keepIn(root, agent, prompt.trim(), io.now())) {
+                written.push(root);
+            }
+        }
+        return { written };
+    }
+    catch {
+        return { written: [] };
+    }
+}
+/** Write one prompt into one `.reticle`. False when the project opted out, or it is a repeat. */
+function keepIn(root, agent, prompt, at) {
+    const projectDir = dirname(root);
+    if (agentCaptureOffIn(projectDir)) {
+        return false;
+    }
+    const requestPath = join(root, ReticleDir.REQUEST_FILE);
+    const request = redactSecrets(prompt, MAX_REQUEST);
+    if (repeats(requestPath, request, at)) {
+        return false;
+    }
+    const context = promptContextFor(prompt, [], at, sharesRequests(projectDir, root));
+    mkdirSync(root, { recursive: true });
+    // The hook can run before any daemon has written `.reticle/.gitignore`: write it, or add the
+    // prompt files to an older one, before a prompt lands where `git add -A` would take it.
+    const ignorePath = join(root, WORKSPACE_GITIGNORE);
+    const ignore = workspaceGitignore(readTextOrUndefined(ignorePath));
+    if (ignore !== undefined) {
+        writeFileSync(ignorePath, ignore);
+    }
+    // Writers run detached and can finish out of order: the request is the NEWEST prompt, so an
+    // older one that lands late goes to the history only.
+    if (!newerHeld(requestPath, at)) {
+        const tmp = `${requestPath}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(context, null, JSON_INDENT)}\n`);
+        renameSync(tmp, requestPath);
+    }
+    const historyPath = join(root, ReticleDir.REQUESTS_LOG_FILE);
+    // ponytail: one rotated file; older history is dropped once a second one fills.
+    // Every step goes through one open file, so the path cannot change between a check and a write.
+    // It is not opened to append: Windows cannot truncate a file that is open to append. Two hooks
+    // that write in the same instant can lose one line of history.
+    const fd = openSync(historyPath, constants.O_RDWR | constants.O_CREAT);
+    try {
+        let end = fstatSync(fd).size;
+        if (MAX_HISTORY_BYTES < end) {
+            writeFileSync(join(root, ReticleDir.REQUESTS_LOG_ROTATED_FILE), readFileSync(fd));
+            ftruncateSync(fd, 0);
+            end = 0;
+        }
+        writeSync(fd, `${JSON.stringify({ at, agent, request: context.request })}\n`, end);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return true;
+}
+/** The request file already holds a prompt that arrived after `at`. */
+function newerHeld(requestPath, at) {
+    try {
+        const held = PromptContextSchema.safeParse(JSON.parse(readFileSync(requestPath, 'utf8')));
+        return held.success && held.data.at !== undefined && held.data.at > at;
+    }
+    catch {
+        return false;
+    }
+}
+/** The same prompt was kept a moment ago: a second hook for the same submit. */
+function repeats(requestPath, request, at) {
+    try {
+        const held = PromptContextSchema.safeParse(JSON.parse(readFileSync(requestPath, 'utf8')));
+        if (!held.success || held.data.at === undefined) {
+            return false;
+        }
+        return held.data.request === request && at - held.data.at < DUPLICATE_WINDOW_MS;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/command/cli/hook/tool-hook.d.ts

@@ -0,0 +1,21 @@
+/** The `kind` of a record this hook writes, beside the daemon's `start` and `call`. */
+export declare const AGENT_TOOL_RECORD: "agent_tool";
+/** The `kind` of a record that only names the agent's model (Claude Code's session start). */
+export declare const AGENT_MODEL_RECORD: "agent_model";
+/** The `kind` of the agent's closing message at the end of a turn. */
+export declare const AGENT_STOP_RECORD: "agent_stop";
+/** A result keeps this many characters; its full size is kept beside it. */
+export declare const MAX_TOOL_TEXT = 4000;
+type Json = Record<string, unknown>;
+/** One record from a post-tool payload, or from a payload that only names the model. */
+export declare function toolRecordFrom(agent: string, payload: unknown, now: number, base: string): Json | undefined;
+export { toolHookAck } from './hook-fast.js';
+interface CaptureIo {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly now: () => number;
+}
+/** Keep one tool call. Never throws: the `.reticle` roots it wrote to, or none. */
+export declare function captureToolCall(agent: string, raw: string, io: CaptureIo): {
+    written: string[];
+};