@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/hook-index.js

@@ -0,0 +1,164 @@
+// The hook index: a small file written at the end of every deposit so a hook never parses the whole observation log.
+// SessionStart reads `projects` (the recurring signatures per project folder); PostToolUse reads `signatures` (sessions and
+// what followed, by exact signature). Both are pure functions of the store.
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { resolveReads } from './recall-pool.js';
+import { aboveBaseRate, fitReads, PUSH_FLOORS, toolShapeId } from './recall-reads.js';
+import { expandHome } from './allow.js';
+import { slugOf } from './store.js';
+const INDEX_FILE = 'hook-index.json';
+/** A signature is "recurring" once it has been seen in this many sessions. */
+export const RECURRING_SESSIONS = 2;
+const PER_PROJECT = 12;
+const FOLLOWED = 3;
+/** SessionStart ranks by sessions within this many latest sessions of its repository: the `measure --last 300 --repo` window the G1 reading uses. */
+export const RECENT_SESSIONS = 300;
+const topFollowed = (following) => Object.entries(following)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, FOLLOWED);
+const tally = () => ({ sessions: new Set(), following: {}, harness: new Set() });
+// The same order `measure` uses, so the window here is the window `measure --last 300 --repo` counts.
+const byStart = (a, b) => (a.tsFirst ?? '').localeCompare(b.tsFirst ?? '') || a.session.localeCompare(b.session);
+const WORKTREE_SLUG = '--claude-worktrees-';
+/**
+ * Groups project folder slugs into repositories without knowing any root: a worktree slug folds into its repository's, and a slug that
+ * extends another stored slug (a subfolder) joins the shortest one, the same extension rule `belongs` applies at recall time.
+ */
+const repositoryOf = (projects) => {
+    const baseOf = (project) => project.split(WORKTREE_SLUG)[0] ?? project;
+    const bases = [...new Set(projects.map(baseOf))].sort((a, b) => a.length - b.length);
+    return (project) => {
+        const base = baseOf(project);
+        return bases.find((candidate) => base === candidate || base.startsWith(`${candidate}-`)) ?? base;
+    };
+};
+export const buildIndex = (store, redactDomains, at, reads = [], next) => {
+    const projectOf = new Map(store.sessions.map((session) => [session.session, session.project]));
+    // The latest 300 of each repository, not of the whole store: another repository's deposits must not move this one's ranking.
+    const family = repositoryOf([...new Set(store.sessions.map((session) => session.project))]);
+    const byRepository = new Map();
+    for (const session of store.sessions) {
+        const key = family(session.project);
+        const group = byRepository.get(key) ?? [];
+        byRepository.set(key, group);
+        group.push(session);
+    }
+    const recentNames = new Set([...byRepository.values()].flatMap((group) => group.sort(byStart).slice(-RECENT_SESSIONS).map((session) => session.session)));
+    const overall = new Map();
+    const byProject = new Map();
+    for (const error of store.errors) {
+        const project = projectOf.get(error.session);
+        const targets = [overall];
+        if (project !== undefined) {
+            const own = byProject.get(project) ?? new Map();
+            byProject.set(project, own);
+            targets.push(own);
+        }
+        for (const target of targets) {
+            const entry = target.get(error.sig) ?? tally();
+            target.set(error.sig, entry);
+            entry.sessions.add(error.session);
+            if (error.harnessVersion !== null)
+                entry.harness.add(error.harnessVersion);
+            for (const tool of error.next)
+                entry.following[tool] = (entry.following[tool] ?? 0) + 1;
+        }
+    }
+    const signatures = {};
+    for (const [sig, entry] of overall) {
+        if (entry.sessions.size >= RECURRING_SESSIONS)
+            signatures[sig] = { sessions: entry.sessions.size, followed: topFollowed(entry.following) };
+    }
+    const projects = {};
+    for (const [project, sigs] of byProject) {
+        const rows = [...sigs.entries()]
+            .filter(([, entry]) => entry.sessions.size >= RECURRING_SESSIONS)
+            .map(([sig, entry]) => ({
+            sig,
+            sessions: entry.sessions.size,
+            recent: [...entry.sessions].filter((name) => recentNames.has(name)).length,
+            followed: topFollowed(entry.following),
+            harness: [...entry.harness].sort(),
+        }))
+            .filter((row) => row.recent > 0)
+            .sort((a, b) => b.recent - a.recent || b.sessions - a.sessions || a.sig.localeCompare(b.sig))
+            .slice(0, PER_PROJECT);
+        if (rows.length > 0)
+            projects[project] = rows;
+    }
+    return {
+        at,
+        redactDomains: [...redactDomains],
+        projects,
+        signatures,
+        fit: Object.fromEntries(resolveReads(aboveBaseRate(store, fitReads(store, PUSH_FLOORS)), reads).map((read) => [toolShapeId(read.tool, read.keys), read])),
+        ...(next === undefined ? {} : { recoveryByFrame: next.recovery, positionsByFrame: next.positions }),
+    };
+};
+export const indexPath = (storeDir) => join(storeDir, INDEX_FILE);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// The file is ours; these checks guard a torn or foreign file, and the inner rows are trusted as written (as the store's are).
+const isIndex = (value) => isRecord(value) && isRecord(value.projects) && isRecord(value.signatures) && Array.isArray(value.redactDomains) && typeof value.at === 'string';
+/** The index as written, or undefined when there is none (or it is torn): a hook then says nothing. */
+export const readIndex = async (storeDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(indexPath(storeDir), 'utf8'));
+        return isIndex(parsed) ? parsed : undefined;
+    }
+    catch {
+        // A missing or torn index is "no index".
+        return undefined;
+    }
+};
+/** `<root>/.claude/worktrees/<name>` belongs to `<root>`, so a worktree session sees its repository's history. */
+export const repositoryRoot = (cwd) => {
+    const marker = /[\\/]\.claude[\\/]worktrees[\\/]/.exec(cwd);
+    return marker === null ? cwd : cwd.slice(0, marker.index);
+};
+/** A project folder belongs to the repository when its slug is the root's slug or extends it (a subfolder or a worktree). */
+const belongs = (project, rootSlug) => project === rootSlug || project.startsWith(`${rootSlug}-`);
+/** True when a project folder slug belongs to the repository `root` sits in (a worktree path counts as its repository). */
+export const inRepository = (project, root) => belongs(project, slugOf(repositoryRoot(resolve(expandHome(root)))));
+const clip = (text, length) => (text.length <= length ? text : `${text.slice(0, length - 1)}…`);
+/** The top recurring signatures for the repository, as a short block for injection; undefined when there is nothing to say. */
+export const contextBlock = (index, options) => {
+    const rootSlug = slugOf(repositoryRoot(options.cwd));
+    const merged = new Map();
+    for (const [project, rows] of Object.entries(index.projects)) {
+        if (!belongs(project, rootSlug))
+            continue;
+        for (const row of rows) {
+            if (options.harness !== undefined && !row.harness.includes(options.harness))
+                continue;
+            const have = merged.get(row.sig);
+            if (have === undefined) {
+                merged.set(row.sig, { ...row });
+                continue;
+            }
+            have.sessions += row.sessions;
+            have.recent += row.recent;
+            const following = {};
+            for (const [tool, count] of [...have.followed, ...row.followed])
+                following[tool] = (following[tool] ?? 0) + count;
+            have.followed = topFollowed(following);
+        }
+    }
+    const rows = [...merged.values()].sort((a, b) => b.recent - a.recent || b.sessions - a.sessions || a.sig.localeCompare(b.sig)).slice(0, options.top);
+    if (rows.length === 0)
+        return undefined;
+    const header = `oars recall: errors that recur in this repository's earlier sessions${options.harness === undefined ? '' : ` (Claude Code ${options.harness})`}. Check these before retrying:`;
+    const lines = rows.map((row) => {
+        const followed = row.followed.map(([tool]) => tool).join(', ');
+        return `- ${clip(row.sig, 120)} (${String(row.recent)} sessions in the last ${String(RECENT_SESSIONS)}${followed === '' ? '' : `; next: ${followed}`})`;
+    });
+    const kept = [];
+    let used = header.length;
+    for (const line of lines) {
+        if (used + 1 + line.length > options.maxChars)
+            break;
+        kept.push(line);
+        used += 1 + line.length;
+    }
+    return kept.length === 0 ? undefined : [header, ...kept].join('\n');
+};

package/dist/sessions/hooks.d.ts

@@ -0,0 +1,17 @@
+import { type Emit } from '../telemetry/emit.js';
+import type { HookCall } from './schema.js';
+import { type SessionsRuntime } from './store.js';
+import type { NightlyTelemetry } from '../telemetry/health.js';
+export type HookEvent = HookCall['event'];
+export declare const HOOK_EVENTS: readonly HookEvent[];
+/** The runtime a hook process runs with. Only `nightly` reads the non-Claude stores (a saved `--allow cursor` or `--allow codex`); the Stop path stays free of it. */
+export declare const hookRuntime: (event: HookEvent, env: {
+    [name: string]: string | undefined;
+}, platform: NodeJS.Platform, home: string, io: Pick<SessionsRuntime, "stdin" | "stdout">) => SessionsRuntime;
+/** What the nightly run records with, and nothing for any other hook: the telemetry folder sits beside the session store under the config directory, so `oars telemetry` and the nightly run read and write the same one. The version is read only for the nightly run, so the per-tool hooks never touch the manifest. */
+export declare const nightlyTelemetry: (event: HookEvent, env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string, version: () => string, now: () => number) => NightlyTelemetry | undefined;
+/**
+ * Runs one hook. It never fails or blocks the session it runs in: whatever happens, it resolves (the process exits 0), and the
+ * hook-call line records the outcome, with the failure's first line when there was one, so the record is evidence, not a claim.
+ */
+export declare const runHook: (event: HookEvent, stdin: string, runtime: SessionsRuntime, now: () => number, telemetry?: NightlyTelemetry, emit?: Emit) => Promise<string | undefined>;

package/dist/sessions/hooks.js

@@ -0,0 +1,281 @@
+// The hook entry points. Each takes the hook's stdin and returns the text for stdout (or undefined for none). They are fail-open:
+// any error inside one is swallowed, so a hook can never fail or block a Claude Code session. Each call is counted in
+// `hook-calls.jsonl` with its own duration, so `measure` can count recall calls per session and the timings can be checked.
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { defaultConfigDir } from '../credentials.js';
+import { noEmit } from '../telemetry/emit.js';
+import { frameWords, HOOK_HARNESS, recallFields } from '../telemetry/fields.js';
+import { cursorRoot } from './cursor.js';
+import { SOURCES, sourceLabel } from './sources.js';
+import { ACTION_TABLES, actionOf } from './actions.js';
+import { errorCodeOf, signatureOf } from './extract.js';
+import { appendHookCall } from './hook-calls.js';
+import { contextBlock, readIndex } from './hook-index.js';
+import { bundleNext, frameKeyOf, lastTable, mergePositions, positionsRecall, recoveryDecision, recoveryRecall, signatureRecall, isSignatureRetry } from './recall-next.js';
+import { pushRecall, tailOf } from './recall-push.js';
+import { statedAt, statedOf } from './transcript-tail.js';
+import { toolShapeId } from './recall-reads.js';
+import { makeRedactor } from './redact.js';
+import { errorLine, inputKey, logStep, newContext, runDeposit, stampKey, tryLog } from './steps.js';
+import { deposit, depositSession, readSaved } from './store.js';
+import { recordSurvival } from './survival.js';
+export const HOOK_EVENTS = ['session-start', 'prompt', 'pre-tool', 'post-tool', 'stop', 'nightly'];
+const TOP = 5;
+const MAX_CHARS = 1200;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const parse = (stdin) => {
+    try {
+        const parsed = JSON.parse(stdin);
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+};
+const str = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+const additional = (eventName, context) => `${JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, additionalContext: context } })}\n`;
+/** What a next-node read needs of the hook's input: the session, the transcript's tail (version, model), and the clock; undefined when the harness gave no session, since the holdback arm is the session's. */
+const nextInputOf = async (runtime, input, now) => {
+    const sid = str(input.session_id);
+    if (sid === undefined)
+        return undefined;
+    const transcript = str(input.transcript_path);
+    const tail = transcript === undefined ? '' : await tailOf(transcript);
+    const { harnessVersion } = statedOf(tail);
+    return { next: { storeDir: runtime.storeDir, sid, tail, platform: process.platform, at: new Date(now()).toISOString() }, asker: { harness: HOOK_HARNESS, harnessVersion } };
+};
+/**
+ * The split-positions table (Item 3): the kept bundle's positions first, the local pool's second. A `repeat` read (UserPromptSubmit) goes out only when the table differs from
+ * the one this session was last sent, shown or held, so a held session and a shown one hear the same number of times.
+ */
+const positionsTable = async (runtime, input, now, index, repeat) => {
+    const prepared = await nextInputOf(runtime, input, now);
+    if (prepared === undefined)
+        return undefined;
+    const bundle = await bundleNext(runtime.storeDir, prepared.asker);
+    const positions = mergePositions(bundle?.positions ?? [], index?.positionsByFrame?.[frameKeyOf(prepared.asker)] ?? []);
+    if (positions.length === 0)
+        return undefined;
+    const previous = repeat ? await lastTable(runtime.storeDir, prepared.next.sid) : undefined;
+    return positionsRecall(prepared.next, prepared.asker, positions, bundle?.poolVersion ?? index?.at ?? '', previous);
+};
+const sessionStart = async (runtime, input, now) => {
+    const cwd = str(input.cwd);
+    const index = await readIndex(runtime.storeDir);
+    const block = index === undefined || cwd === undefined ? undefined : contextBlock(index, { cwd, top: TOP, maxChars: MAX_CHARS });
+    const recall = await positionsTable(runtime, input, now, index, false);
+    const model = str(input.model);
+    const shown = recall?.arm === 'shown' ? recall.answer.rendered : undefined;
+    const text = [block, shown].filter((part) => part !== undefined).join('\n\n');
+    return {
+        hit: text !== '' || recall !== undefined,
+        queried: index !== undefined || recall !== undefined,
+        ...(text === '' ? {} : { output: additional('SessionStart', text) }),
+        ...(recall === undefined ? {} : { recall }),
+        ...(model === undefined ? {} : { model }),
+    };
+};
+/** UserPromptSubmit: the positions table again, only when it changed since this session's last one. */
+const prompt = async (runtime, input, now) => {
+    const recall = await positionsTable(runtime, input, now, await readIndex(runtime.storeDir), true);
+    if (recall === undefined)
+        return { hit: false, queried: false };
+    return recall.arm === 'shown' ? { output: additional('UserPromptSubmit', recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
+};
+const inputKeys = (input) => (isRecord(input.tool_input) ? Object.keys(input.tool_input) : []);
+/**
+ * The fit push. The only output this hook writes is `additionalContext`: it holds no permission decision and changes no input, so whatever it does, the call runs as asked.
+ * A call with no read says nothing and logs no recall step: that is nearly every call, and nobody asked. A held push is a hit, for what it would have shown, with no output.
+ */
+const preTool = async (runtime, input, now) => {
+    const sid = str(input.session_id);
+    const tool = str(input.tool_name);
+    if (sid === undefined || tool === undefined)
+        return { hit: false, queried: false };
+    const index = await readIndex(runtime.storeDir);
+    if (index === undefined)
+        return { hit: false, queried: false };
+    const recall = await pushRecall({ storeDir: runtime.storeDir, sid, tool, keys: inputKeys(input), transcript: str(input.transcript_path), platform: process.platform, at: new Date(now()).toISOString(), index });
+    if (recall === undefined)
+        return { hit: false, queried: false };
+    return recall.arm === 'shown' ? { output: additional('PreToolUse', recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
+};
+/** A failed tool arrives as PostToolUseFailure with the text in `error` (Bash and PowerShell start it with `Exit code N`); a PostToolUse response that starts that way is read too. */
+const failureText = (input) => {
+    const failed = str(input.error);
+    if (failed !== undefined)
+        return failed;
+    const response = str(input.tool_response);
+    return response !== undefined && /^Exit code \d+/.test(response) ? response : undefined;
+};
+/**
+ * The recovery edge (Item 2): what followed a failure of this action and error class, from the kept bundle for the session's setup and then the local pool, held to A33's
+ * holdback like every next-node read. A same-step retry or a local edge under the floor says nothing, signature line included; the signature line answers only a failure no cell covers.
+ */
+const postTool = async (runtime, input, now) => {
+    const tool = str(input.tool_name);
+    const text = failureText(input);
+    const prepared = tool === undefined || text === undefined ? undefined : await nextInputOf(runtime, input, now);
+    if (tool === undefined || text === undefined || prepared === undefined)
+        return { hit: false, queried: false };
+    const index = await readIndex(runtime.storeDir);
+    const bundle = await bundleNext(runtime.storeDir, prepared.asker);
+    if (index === undefined && bundle === undefined)
+        return { hit: false, queried: false };
+    const action = actionOf(ACTION_TABLES['claude-code'], tool).action;
+    const code = errorCodeOf(text);
+    const decision = recoveryDecision(bundle, index === undefined ? undefined : { recovery: index.recoveryByFrame?.[frameKeyOf(prepared.asker)] ?? {}, poolVersion: index.at }, action, code);
+    const event = str(input.hook_event_name) ?? 'PostToolUseFailure';
+    if (decision.kind === 'serve') {
+        const recall = await recoveryRecall(prepared.next, prepared.asker, action, code, decision);
+        return recall.arm === 'shown' ? { output: additional(event, recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
+    }
+    // A same-step retry, a local cell too thin to serve, and a cell whose top is that nothing followed all end the lookup: a cell that exists but says nothing is not a reason to fall back to a signature count.
+    if (decision.kind === 'retry' || decision.kind === 'floor' || decision.kind === 'ended')
+        return { hit: false, queried: true };
+    const sig = signatureOf(tool, text, makeRedactor(index?.redactDomains ?? []));
+    const found = index?.signatures[sig];
+    if (index === undefined || found === undefined || isSignatureRetry(tool, found))
+        return { hit: false, queried: true };
+    const recall = await signatureRecall(prepared.next, prepared.asker, tool, sig, found, index.at);
+    return recall.arm === 'shown' ? { output: additional(event, recall.answer.rendered), hit: true, queried: true, recall } : { hit: true, queried: true, recall };
+};
+const stop = async (runtime, input, now) => {
+    const transcript = str(input.transcript_path);
+    if (transcript === undefined)
+        return { hit: false, queried: false };
+    // The SessionEnd hook is the `stop` trigger (spec 4.1); derive and index follow at the nightly run, so only a deposit row is logged.
+    const deposited = await runDeposit(newContext(runtime.storeDir, now, 'stop'), false, inputKey('stop', [transcript], []), async (trace) => ({ value: await depositSession(runtime, transcript, now, trace), in: { transcript: 1 } }));
+    return { hit: deposited === 'deposited', queried: false };
+};
+const nightlyRun = async (runtime, now, timing) => {
+    // A state.json that cannot be read is a failed deposit run like any other: its error row and the skipped derive row (spec 4.4) are logged.
+    const saved = await readSaved(runtime.storeDir).catch((failure) => runDeposit(newContext(runtime.storeDir, now, 'nightly'), true, inputKey('nightly', [], []), () => Promise.reject(failure instanceof Error ? failure : new Error(String(failure)))));
+    const result = await runDeposit(newContext(runtime.storeDir, now, 'nightly'), true, inputKey('nightly', saved.allow, saved.redactDomains), async (trace) => {
+        const parseStart = timing.clock();
+        const done = await deposit(runtime, { allow: saved.allow, redactDomains: saved.redactDomains, now }, trace);
+        timing.parseMs = timing.clock() - parseStart;
+        return { value: done, in: { transcript: done.sessions + done.subagents + done.unchanged } };
+    });
+    const survival = await recordSurvival(runtime, saved.allow, now);
+    // A source store that could not be read does not fail the run, so the record carries it or nobody sees it.
+    const counts = Object.entries(result.sources);
+    const unreadable = counts.flatMap(([, tally]) => tally.unreadableLogged)[0];
+    if (unreadable !== undefined)
+        return { hit: true, queried: false, error: await errorLine(runtime.storeDir, unreadable) };
+    // A skip for an unsafe session id is likewise reported, never silent (the `rejected` doc in sources.ts); an unreadable store, which names its own reason, takes precedence.
+    const skipped = counts.find(([, tally]) => tally.rejected > 0);
+    if (skipped !== undefined)
+        return { hit: true, queried: false, error: `Skipped ${String(skipped[1].rejected)} ${sourceLabel(skipped[0], runtime.sources ?? SOURCES)} sessions whose id is not a safe file name` };
+    // A survival read that fails every night is otherwise invisible, for the same reason; it comes last because the run itself did not lose a session.
+    return survival === null ? { hit: true, queried: false, error: await errorLine(runtime.storeDir, 'Commit survival not read this run.') } : { hit: true, queried: false };
+};
+/** The nightly run, then (when telemetry is given) the store-health snapshot and the run's cost. Recording happens after the run and cannot change its outcome or its error. */
+const nightly = async (runtime, now, telemetry) => {
+    const timing = { clock: telemetry?.now ?? now, parseMs: 0 };
+    const started = timing.clock();
+    let outcome;
+    let failure;
+    let failed = false;
+    try {
+        outcome = await nightlyRun(runtime, now, timing);
+    }
+    catch (thrown) {
+        failure = thrown;
+        failed = true;
+    }
+    if (telemetry !== undefined) {
+        // Loaded here so the hooks that run before every tool call never pay for the telemetry modules.
+        const { recordRunCost, recordStoreHealth } = await import('../telemetry/health.js');
+        await recordStoreHealth(telemetry, runtime);
+        recordRunCost(telemetry, { totalMs: timing.clock() - started, parseMs: timing.parseMs, failed: failed || outcome?.error !== undefined });
+    }
+    if (failed)
+        throw failure;
+    return outcome ?? { hit: false, queried: false };
+};
+/** What a lookup hook looks up, as its recall key (spec 4.2 names none for a lookup): the cwd for session-start, the failure's signature for post-tool, the call's shape for pre-tool; null when it had nothing to look up. */
+const lookupKey = (event, input) => {
+    if (event === 'session-start') {
+        const cwd = str(input.cwd);
+        return cwd === undefined ? null : stampKey(event, cwd);
+    }
+    if (event === 'prompt')
+        return stampKey(event, 'positions');
+    const tool = str(input.tool_name);
+    if (event === 'pre-tool')
+        return tool === undefined ? null : stampKey(event, toolShapeId(tool, inputKeys(input)));
+    const text = failureText(input);
+    return event === 'post-tool' && tool !== undefined && text !== undefined ? stampKey(event, signatureOf(tool, text, makeRedactor([]))) : null;
+};
+/** The runtime a hook process runs with. Only `nightly` reads the non-Claude stores (a saved `--allow cursor` or `--allow codex`); the Stop path stays free of it. */
+export const hookRuntime = (event, env, platform, home, io) => ({
+    storeDir: join(defaultConfigDir(env, platform, home), 'oars', 'sessions'),
+    projectsRoot: join(env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), 'projects'),
+    ...(event === 'nightly' ? { cursorRoot: cursorRoot(platform, env, home), sourceRoots: Object.fromEntries(SOURCES.map((source) => [source.name, source.root(platform, env, home)])) } : {}),
+    ...io,
+});
+/** What the nightly run records with, and nothing for any other hook: the telemetry folder sits beside the session store under the config directory, so `oars telemetry` and the nightly run read and write the same one. The version is read only for the nightly run, so the per-tool hooks never touch the manifest. */
+export const nightlyTelemetry = (event, env, platform, home, version, now) => event === 'nightly' ? { env, telemetry: { dir: join(defaultConfigDir(env, platform, home), 'oars', 'telemetry'), platform }, version: version(), now } : undefined;
+/**
+ * Runs one hook. It never fails or blocks the session it runs in: whatever happens, it resolves (the process exits 0), and the
+ * hook-call line records the outcome, with the failure's first line when there was one, so the record is evidence, not a claim.
+ */
+export const runHook = async (event, stdin, runtime, now, telemetry, emit = noEmit) => {
+    const started = performance.now();
+    let session = null;
+    let outcome = { hit: false, queried: false };
+    let failed = false;
+    let failure;
+    let key = null;
+    let transcript;
+    try {
+        const input = parse(stdin);
+        transcript = str(input.transcript_path);
+        key = lookupKey(event, input);
+        session = str(input.session_id) ?? null;
+        if (event === 'session-start')
+            outcome = await sessionStart(runtime, input, now);
+        else if (event === 'prompt')
+            outcome = await prompt(runtime, input, now);
+        else if (event === 'pre-tool')
+            outcome = await preTool(runtime, input, now);
+        else if (event === 'post-tool')
+            outcome = await postTool(runtime, input, now);
+        else if (event === 'stop')
+            outcome = await stop(runtime, input, now);
+        else
+            outcome = await nightly(runtime, now, telemetry);
+    }
+    catch (thrown) {
+        failure = thrown;
+        failed = true;
+    }
+    const ms = Math.round(performance.now() - started);
+    // The failure line is masked once, the same for the hook-calls line and the step row beside it; both writes are guarded, so a counter
+    // that cannot be written never costs the session its context.
+    const line = failed ? await errorLine(runtime.storeDir, failure).catch(() => 'unknown error') : outcome.error ?? null;
+    await tryLog(() => appendHookCall(runtime.storeDir, { at: new Date(now()).toISOString(), event, session, hit: outcome.hit, ms, startMs: Math.round(started), error: line }));
+    // A lookup hook that ran a query (or failed trying) is a `recall` step started by its own trigger; the deposit hooks logged their rows as they ran.
+    if (key !== null && (failed || outcome.queried)) {
+        const report = { in: { query: 1 }, out: failed ? {} : { matches: outcome.hit ? 1 : 0 }, key };
+        await tryLog(() => logStep(newContext(runtime.storeDir, now, event), 'recall', failed ? 'error' : 'ok', ms, report, line));
+    }
+    // After the answer is settled and the local rows are written; it runs before hook-bin prints, at the cost measured in t876 item 5. `emit` never throws. A push states its own frame;
+    // every other fire reads the transcript's tail the way a push does, so the version and model are there on a miss, a post-tool, and a stop. (A nightly run has no hook input, so it has no transcript to read.)
+    const { recall } = outcome;
+    const stated = recall?.frame !== undefined || transcript === undefined ? undefined : await statedAt(transcript);
+    emit('hook', {
+        name: event,
+        latencyMs: ms,
+        outcome: failed ? 'error' : recall?.arm === 'held' ? 'held' : outcome.hit ? 'hit' : 'miss',
+        bytes: Buffer.byteLength(outcome.output ?? ''),
+        // The nightly is the scheduled task, not a harness's hook: it names no harness.
+        ...frameWords(event === 'nightly' ? undefined : recall?.frame?.harness ?? HOOK_HARNESS, recall?.frame?.harnessVersion ?? stated?.harnessVersion, recall?.frame?.model ?? outcome.model ?? stated?.model),
+    });
+    // A push is a recall: its read is the family its query names (the `fit` push names none), and its arm is the exposure record, as a count of one.
+    if (recall !== undefined)
+        emit('recall', recallFields(recall, [recall.query.family ?? 'fit']));
+    return outcome.output;
+};

package/dist/sessions/identity.d.ts

@@ -0,0 +1,27 @@
+import { type ActionTable, type CanonicalAction } from './actions.js';
+import type { Redactor } from './redact.js';
+import type { PullIdentity, ShellIdentity, StepIdentity, ToolPull } from './schema.js';
+/** A word of a shell command, as the tokenizer read it. */
+export interface WordOfCommand {
+    text: string;
+    quoted: boolean;
+}
+export declare const NUMBER_FLAG = "-N";
+export declare const isPositional: ({ text, quoted }: WordOfCommand) => boolean;
+/**
+ * A pull with its package name as written (the command was redacted before it was read, and the name is checked once more part by part, as a host and a skill-run name are). A package off the public list can be identified by its version, so the version is masked beside it; a stated version of a listed package stays stated.
+ * A name that is not one (a URL, a path, a mask) is `<literal>`.
+ */
+export declare const pullIdentity: (pull: ToolPull, redact: Redactor) => PullIdentity;
+/** A shell step whose program is private or unreadable: its flags are its own, so none are kept. */
+export declare const UNREAD_SHELL: ShellIdentity;
+export declare const shellIdentity: (program: string, args: readonly WordOfCommand[], pulls: readonly ToolPull[], redact: Redactor) => ShellIdentity;
+/** What a non-shell call's step reads as. `native` comes back masked unless every name it holds is public, since an MCP name spells out its server. */
+export declare const callIdentity: (table: ActionTable, action: CanonicalAction, native: string, shown: string, input: {
+    skill: string | undefined;
+    url: string | undefined;
+    redact: Redactor;
+}) => {
+    native: string;
+    identity: StepIdentity;
+};

package/dist/sessions/identity.js

@@ -0,0 +1,131 @@
+// A step's `identity` (recall spec Section 2.2): what the step acted on, by action. A program, subcommand, flag, MCP server and tool pass through
+// `public-vocabulary.ts` and become `<literal>` when it does not list them; a skill-run name, a host, and a pull name are kept as they are after the
+// operator's redaction (CAPTURE 24), and what leaves the machine is decided at the deposit's one gate and by the pool.
+import { mcpOf } from './actions.js';
+import { isWireName, isWirePullName, wireName } from './pool-wire.js';
+import { BUNDLING_PROGRAMS, isPublicMcpTool, isRegistryVersion, LITERAL, PRIVATE, PUBLIC_FLAGS, PUBLIC_MCP_SERVERS, PUBLIC_PACKAGES, PUBLIC_PROGRAMS, PUBLIC_SUBCOMMANDS } from './public-vocabulary.js';
+const orLiteral = (name, allowed) => (allowed.has(name) ? name : LITERAL);
+/**
+ * A long-tail name (a skill run, a host, a pull) as the store keeps it: the name itself, or `<literal>` when it is not a name or the operator's redaction would change it. The test is the wire's own (`wireName`), so a name stored here is a
+ * name the deposit sends, and a list never decides it: the pool does, by deploy. The operator's exclusion terms are the deposit's, since they change after the capture.
+ */
+const keptName = (name, redact, hasShape = isWireName) => {
+    const kept = wireName({ redact, terms: [] }, name, hasShape);
+    return kept === PRIVATE ? LITERAL : kept;
+};
+const SHORT_CLUSTER = /^-[a-z]{1,4}$/;
+const SHORT_LETTER = /^-[A-Za-z]$/;
+// A short flag with a value joined after a non-letter, as in `-c1-200`: the first capture is the name and the rest is the value, which is dropped.
+const JOINED_VALUE = /^(-[A-Za-z])[^A-Za-z]/;
+// `head -20`: the digits are the value and the flag has no name of its own, so every such flag reads alike.
+const BARE_NUMBER = /^-\d+$/;
+export const NUMBER_FLAG = '-N';
+/**
+ * The names one flag word holds, without its value. On a program that bundles, a short cluster reads as its letters, so `-rf` and `-fr` agree;
+ * a value joined to a flag there can still read as letters, one each and never the word. On any other program the cluster is the literal.
+ */
+const flagNames = (text, bundles) => {
+    const name = text.split('=')[0] ?? text;
+    if (name.startsWith('--') || PUBLIC_FLAGS.has(name))
+        return [orLiteral(name, PUBLIC_FLAGS)];
+    if (SHORT_LETTER.test(name))
+        return [name];
+    if (BARE_NUMBER.test(name))
+        return [NUMBER_FLAG];
+    const joined = JOINED_VALUE.exec(name)?.[1];
+    if (joined !== undefined)
+        return [joined];
+    return bundles && SHORT_CLUSTER.test(name) ? Array.from(name.slice(1), (letter) => `-${letter}`) : [LITERAL];
+};
+const flagsOf = (program, args) => {
+    const bundles = BUNDLING_PROGRAMS.has(program);
+    const flags = new Set();
+    for (const { text, quoted } of args) {
+        if (text === '--')
+            break;
+        if (quoted || !text.startsWith('-') || text.includes('$'))
+            continue;
+        for (const name of flagNames(text, bundles))
+            flags.add(name);
+    }
+    return [...flags].sort();
+};
+export const isPositional = ({ text, quoted }) => !quoted && text !== '' && !text.startsWith('-') && !/[$\\/]/.test(text);
+/** A subcommand from the program's own table, wherever a global flag's value left it; a positional word outside the table is the literal. */
+const subOf = (program, args) => {
+    const table = PUBLIC_SUBCOMMANDS.get(program);
+    if (table === undefined)
+        return null;
+    const positional = args.filter(isPositional);
+    const known = positional.find(({ text }) => table.has(text));
+    if (known !== undefined)
+        return known.text;
+    return positional.length === 0 ? null : LITERAL;
+};
+const REGISTRY_OF = {
+    npm: 'npm',
+    pypi: 'pypi',
+    cargo: 'crates',
+    go: 'go',
+    gem: 'rubygems',
+    brew: 'homebrew',
+    skill: 'skill',
+    plugin: 'plugin',
+    mcp: 'mcp',
+};
+/**
+ * A pull with its package name as written (the command was redacted before it was read, and the name is checked once more part by part, as a host and a skill-run name are). A package off the public list can be identified by its version, so the version is masked beside it; a stated version of a listed package stays stated.
+ * A name that is not one (a URL, a path, a mask) is `<literal>`.
+ */
+export const pullIdentity = (pull, redact) => {
+    const name = keptName(pull.name, redact, isWirePullName);
+    const showsVersion = PUBLIC_PACKAGES.has(name) && pull.version !== null && isRegistryVersion(pull.version);
+    return { registry: REGISTRY_OF[pull.ecosystem], name, version: pull.version === null ? null : showsVersion ? pull.version : LITERAL };
+};
+/** A shell step whose program is private or unreadable: its flags are its own, so none are kept. */
+export const UNREAD_SHELL = { program: LITERAL, sub: null, flags: [] };
+/** Flags of `git checkout` that take only paths: a checkout with one of them acts on a path, never on a branch. */
+const PATH_ONLY_FLAGS = new Set(['--ours', '--theirs', '--patch', '-p', '--pathspec-from-file']);
+/**
+ * The class of what a `git checkout` acts on, from the line alone and never the target's text. A `--` marker or a path-only flag proves a path; a target word the segment drops (the same
+ * words `isPositional` refuses: quoted, or holding a slash, a backslash, or `$`) with neither proof could be a branch (`feature/x`) or a path (`src/a.ts`), so it is `word`; no such word is absent.
+ */
+const checkoutTarget = (all) => {
+    // Words before `checkout` are the global options of `git` (`-C <dir>`), not what the checkout acts on.
+    const args = all.slice(all.findIndex(({ text, quoted }) => !quoted && text === 'checkout') + 1);
+    const dashes = args.findIndex(({ text, quoted }) => !quoted && text === '--');
+    const flagWords = (dashes < 0 ? args : args.slice(0, dashes)).filter(({ text, quoted }) => !quoted && text.startsWith('-')).map(({ text }) => text.split('=')[0] ?? text);
+    if (dashes >= 0 || flagWords.some((flag) => PATH_ONLY_FLAGS.has(flag)))
+        return 'path';
+    return args.some((word) => (word.quoted || !word.text.startsWith('-')) && !isPositional(word)) ? 'word' : undefined;
+};
+export const shellIdentity = (program, args, pulls, redact) => {
+    if (!PUBLIC_PROGRAMS.has(program))
+        return UNREAD_SHELL;
+    const sub = subOf(program, args);
+    const target = program === 'git' && sub === 'checkout' ? checkoutTarget(args) : undefined;
+    const identity = { program, sub, flags: flagsOf(program, args), ...(target === undefined ? {} : { target }) };
+    return pulls.length === 0 ? identity : { ...identity, pulls: pulls.map((pull) => pullIdentity(pull, redact)) };
+};
+const hostOf = (url, redact) => {
+    if (url === undefined || url === '')
+        return { host: null };
+    // The parser drops credentials, the path, and the query, and lower-cases the host; the redactor and the name shape then decide, and the pool hashes it on arrival.
+    const parsed = URL.canParse(url) ? new URL(url).hostname : '';
+    return { host: keptName(parsed, redact) };
+};
+/** What a non-shell call's step reads as. `native` comes back masked unless every name it holds is public, since an MCP name spells out its server. */
+export const callIdentity = (table, action, native, shown, input) => {
+    if (action === 'web.fetch' || action === 'web.search')
+        return { native: shown, identity: hostOf(input.url, input.redact) };
+    if (action === 'skill.run')
+        return { native: shown, identity: { skill: keptName(input.skill ?? '', input.redact) } };
+    const mcp = action === 'mcp.call' ? mcpOf(table, native) : undefined;
+    if (mcp === undefined)
+        return { native: shown, identity: null };
+    if (!PUBLIC_MCP_SERVERS.has(mcp.server))
+        return { native: LITERAL, identity: { server: LITERAL, tool: LITERAL } };
+    if (!table.toolDelimited || !isPublicMcpTool(mcp.server, mcp.tool))
+        return { native: LITERAL, identity: { server: mcp.server, tool: LITERAL } };
+    return { native, identity: { server: mcp.server, tool: mcp.tool } };
+};