Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
import { readFileSync, existsSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { join, basename, isAbsolute, relative, resolve } from 'node:path';
import { homedir } from 'node:os';
import { readWiring } from './stats.js';
import { formatBlastRadius, formatOrientation, notesOnTouch, standingDirective, teamNotesDirective, type Touch } from './format.js';
import { commitLines, listNotes, setupCommitLine, standingLearnings } from '../notes/notes.js';
import { liveLearnings } from '../notes/learning-fields.js';
import { noteAuthor, teammatesOn } from '../notes/git-facts.js';
import { indexFreshness, staleBanner } from '../context/check.js';
import { dropStoredPrompts, patchStats, readSession, writeSession, resolveContextDir } from './state.js';
import { emit, emitHook, graftJson, payloadSessionId, withContextDirArg } from './hook-io.js';
import { codexPostBashPart, postBashPart, sessionStartPart } from './skills-wiring.js';
import { handlePrompt } from './prompt-hook.js';
import { runUpkeep } from '../upkeep-run.js';
import { runningVersion, wiredHostIds } from '../upkeep.js';
import { hostsWiredForTrail } from '../hosts/registry.js';
import { flushClosedSessions, summarizeSession } from '../telemetry/sessions.js';
import { maybeFlushInBackground } from '../telemetry/flush.js';
import { handleStopEvent } from './stop.js';
import { main as preBashMain } from './pre-bash.js';
import { classifyToolUse, commandInvokesGraft, isMcpToolName, isGraftMcpTool, parseSavings, recordToolUse, type ToolKind } from './session-metrics.js';
import { adoptRepoBrand, brand, commandOnPath, repoWiredForTrail, tag, trailHandoverLine, trailOnPath } from '../brand.js';
import { fitTrailServerToMachine } from '../hosts/claude-global.js';
import { globalCopyCovers } from './hook-layers.js';
import { keepsNotes, noteCounts, repoPlace, type NoteCounts } from '../notes/home.js';
import { branchesStale, overlapMark, readBranchCache, refreshBranches, SESSION_REFRESH_MS } from '../notes/branches.js';
import { learningFiles } from '../notes/repo-trail.js';
import { inWorkspace, maybeSyncInBackground } from '../cloud/workspace-sync.js';
import { cacheDir, readJson, writeJsonAtomic } from '../util/state.js';
import { countBucket, type AgentHost } from '../telemetry/contract.js';
import { detectHost } from '../trace/host.js';
import type { HookOut } from '../skills/types.js';
import { track } from '../telemetry/track.js';
import { skillsDirective } from '../skills/skills.js';
import { everyRepoLearnings } from '../notes/every-repo.js';
import type { Note } from '../notes/notes.js';
import { hostFacts } from '../skills/host-facts.js';
import { trailNow } from '../skills/settings.js';
import { recordSkillUse, skillOfToolUse } from './skill-use.js';
import { keptContext, keptNotice } from './start-init.js';
export { lastFileScopeHint, promptAskTimeout } from './prompt-hook.js';
function readStdin(): any {
const seam = process.env.GRAFT_TEST_STDIN;
const raw = seam !== undefined ? seam : safeReadFd0();
try {
const input = JSON.parse(raw);
return input && typeof input === 'object' && !Array.isArray(input) ? input : {};
} catch { return {}; }
}
function safeReadFd0(): string { try { return readFileSync(0, 'utf8'); } catch { return ''; } }
function projectDir(input: any): string {
return process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd();
}
export function underGraft(dir: string, file: string): boolean {
const rel = file.startsWith(dir) ? file.slice(dir.length) : file;
const posix = rel.replace(/^[/\\]+/, '').replace(/\\/g, '/');
return posix.startsWith('graft/') || posix.startsWith('.trail/cache/');
}
function checkStaleCount(dir: string): number {
const r = graftJson(dir, withContextDirArg(dir, ['check', '.', '--json']));
const g = r?.graph ?? {};
return (g.changed?.length ?? 0) + (g.added?.length ?? 0) + (g.removed?.length ?? 0);
}
/**
* The absolute path of the file a PostToolUse edit touched, across host edit-tool
* shapes:
* - Claude Code (`Write`/`Edit`/`MultiEdit`) states it directly as
* `tool_input.file_path` (already absolute).
* - Codex (`apply_patch`) carries the whole patch in `tool_input.command` and
* names the file in the patch header (`*** Add File:` / `*** Update File:`),
* as a repo-relative path — resolved against `dir` here. Take the first
* Add/Update target; that one file is enough to mark the graph dirty and
* draw a blast radius (the sync re-checks the whole tree anyway).
* Returns null when neither shape yields a path, so the hook stays a clean no-op.
*/
export function editedFilePath(input: any, dir: string): string | null {
const direct = input?.tool_input?.file_path;
if (typeof direct === 'string' && direct.trim()) return direct;
const cmd = input?.tool_input?.command;
if (typeof cmd === 'string' && cmd) {
const m = /^\*\*\*\s+(?:Add|Update)\s+File:\s+(.+?)\s*$/m.exec(cmd);
if (m) return isAbsolute(m[1]) ? m[1] : join(dir, m[1]);
}
return null;
}
async function handlePostEdit(input: any, dir: string): Promise<void> {
const file = editedFilePath(input, dir);
if (!file || underGraft(dir, file)) return;
patchStats(dir, { dirty: true, staleCount: checkStaleCount(dir), lastFile: basename(file) });
const out: string[] = [];
const w = readWiring(dir);
if (w) { const br = formatBlastRadius(w, file); if (br) out.push(br); }
const overlap = await editOverlap(input, dir, file);
if (overlap) out.push(overlap);
const learned = learningsOnTouch(input, dir);
if (learned) out.push(learned);
// One hook, one answer: two JSON objects on stdout would be read as neither.
if (out.length) emit('PostToolUse', out.join('\n\n'));
}
/** Branch-and-function pairs remembered per session, so each is said once. */
const INJECTED_OVERLAPS_CAP = 40;
/**
* Under trail, a teammate's open branch that changes the function this edit
* just changed, for the agent to read and tell the person about, each branch
* and function once a session. Parsing loads grammars, so it's imported only
* when the edited file is one some branch changes. Never throws.
*/
async function editOverlap(input: any, dir: string, file: string): Promise<string | null> {
if (brand() !== 'trail' || !keepsNotes(dir)) return null;
try {
const top = repoPlace(dir);
if (!top.git) return null;
const { functionOverlaps, editOverlapDirective } = await import('../notes/edit-overlap.js');
const found = await functionOverlaps(top.checkout, resolve(dir, file), input?.tool_input, noteAuthor(top.checkout));
if (!found.length) return null;
const id = input?.session_id || 'default';
const s = readSession(dir, id);
const seen = new Set(s.injectedOverlaps ?? []);
const fresh = found.filter((o) => o.symbols.some((x) => !seen.has(`${o.ref} ${x.id}`)));
if (!fresh.length) return null;
s.injectedOverlaps = [...seen, ...fresh.flatMap((o) => o.symbols.map((x) => `${o.ref} ${x.id}`))].slice(-INJECTED_OVERLAPS_CAP);
writeSession(dir, id, s);
const base = readBranchCache(top.checkout)?.base ?? 'origin/main';
return fresh.slice(0, 2).map((o) => editOverlapDirective(o, base, tag(), overlapMark())).join('\n\n');
} catch {
return null;
}
}
/**
* PostToolUse on a retrieval tool. Two jobs, both a pure parse of the payload the
* hook already received (no re-run):
*
* 1. Score the usage mix: classify the tool as a graft retrieval or a source
* read (Read/Grep/Glob) and bump the session's `graftReads`/`sourceReads`.
* Until this ran, those counters were never incremented, so
* `session_summary` telemetry shipped 0/0 for every session.
* 2. Sum any `[graft] tokens saved ≈ N` footers in the output into the running
* `savedTokens` total, so the statusline's `~N tok saved` reflects the
* session across CLI and MCP.
*
* A `[graft]` footer is itself proof graft ran, so it also counts as a graft
* read even when the tool name alone (a bare `Bash`) couldn't say so. A graft use
* also flags the turn (`turnUsedGraft`) so the Stop hook's tally can resolve
* whether the reply told the user what it saved. Stays a no-op on the
* Write/Edit/unrelated-Bash majority: nothing to classify and no footer means
* nothing is written.
*/
function handleToolUse(input: any, dir: string): void {
recordToolUse(dir, payloadSessionId(input),
{ ...classifyAndScore(input?.tool_name, input?.tool_input?.command, () => input?.tool_response ?? input), host: telemetryHost(input) });
}
/**
* Under trail, the learnings about the file a Read, Edit or Write just touched,
* or that a shell command (`sed -n 1,40p src/a.ts`, `cat`, a test run) names,
* each once a session. A trail command is skipped: its own output already
* carries the learnings that bear on it. Never throws.
*/
export function learningsOnTouch(input: any, dir: string): string | null {
try {
if (brand() !== 'trail' || !keepsNotes(dir)) return null;
const ti = input?.tool_input ?? {};
const path = typeof ti.file_path === 'string' ? ti.file_path : typeof ti.notebook_path === 'string' ? ti.notebook_path : null;
let touch: Touch;
if (path) {
const rel = relative(dir, isAbsolute(path) ? path : join(dir, path)).replace(/\\/g, '/');
if (!rel || rel.startsWith('..') || underGraft(dir, path)) return null;
touch = { file: rel, verb: input?.tool_name === 'Read' ? 'opened' : 'changed' };
} else if (typeof ti.command === 'string' && ti.command && !commandInvokesGraft(ti.command)) {
touch = { command: ti.command };
} else return null;
const notes = liveLearnings(listNotes(dir, { branches: false }));
if (!notes.length) return null;
const id = payloadSessionId(input);
const s = readSession(dir, id);
const text = notesOnTouch(notes, touch, s);
if (text) writeSession(dir, id, s);
return text;
} catch {
// A learning that doesn't arrive costs one reminder; a broken hook costs the turn.
return null;
}
}
/**
* PostToolUse's one answer: the skills part's, with the learnings about what
* the call touched added to its context. Two JSON objects on stdout would be
* read as neither. A block is the whole answer, so then no learning is used up.
*/
export function withTouchLearnings(out: HookOut, input: any, dir: string): HookOut {
if (out.block) return out;
const learned = learningsOnTouch(input, dir);
if (!learned) return out;
return { ...out, context: [out.context, learned].filter(Boolean).join('\n\n') };
}
/** Who to put a tool use down to: Cursor and Copilot CLI run these hooks too. */
function telemetryHost(input: unknown): AgentHost {
const host = detectHost(input).host;
return host === 'cursor' || host === 'copilot' ? host : 'claude-code';
}
/**
* Classify a tool use and, only when it could carry a graft footer, parse the
* savings out of its (lazily-serialised) output.
*
* Source reads (Read/Grep/Glob) never print a `[graft]` footer, and their output
* is a whole file or every match — serialising and regexing that on every read
* is the expensive, pointless case the widened PostToolUse matcher would
* otherwise hit. So skip `payload()` entirely for them. For anything else, a
* footer is itself proof graft ran (a bare `Bash graft …` the name couldn't
* classify), so its presence upgrades the kind to 'graft'.
*/
function classifyAndScore(
toolName: string | undefined,
command: string | undefined,
payload: () => unknown,
): { kind: ToolKind | null; savedTokens: number } {
let kind = classifyToolUse(toolName, command);
if (kind === 'source') return { kind, savedTokens: 0 };
const savedTokens = parseSavings(JSON.stringify(payload() ?? ''));
if (savedTokens > 0) kind = 'graft';
return { kind, savedTokens };
}
/**
* Cursor `postToolUse` (https://cursor.com/docs/hooks). Same job as
* {@link handleToolUse} but over Cursor's payload shape: `tool_output` holds the
* JSON-stringified result (a Shell `graft …` call's footer lives in its stdout),
* and the session key is `conversation_id`. MCP graft calls are skipped here —
* `afterMCPExecution` owns them, and counting both would double the graft tally.
* The skip covers both the prefixed (`MCP:graft_find_code`) and bare
* (`graft_find_code`) tool-name shapes, so the guard — not just the installed
* matcher — is what prevents the double count.
*/
function handleCursorPostTool(input: any, dir: string): void {
const toolName = String(input?.tool_name ?? '');
if (isMcpToolName(toolName) || isGraftMcpTool(toolName)) return; // handled by handleCursorMcp
const command = input?.tool_input?.command ?? input?.tool_input?.cmd;
recordToolUse(dir, cursorSessionId(input),
{ ...classifyAndScore(toolName, command, () => input?.tool_output ?? input?.tool_response ?? input), host: 'cursor' });
}
/**
* Cursor `afterMCPExecution`: fires only for MCP tools, so a graft tool is
* recognised by its name and its savings read out of `result_json`. This is the
* one place graft MCP calls are counted for Cursor.
*/
function handleCursorMcp(input: any, dir: string): void {
const toolName = String(input?.tool_name ?? '');
if (!isGraftMcpTool(toolName)) return;
const savedTokens = parseSavings(JSON.stringify(input?.result_json ?? input?.result ?? input ?? ''));
recordToolUse(dir, cursorSessionId(input), { kind: 'graft', savedTokens, host: 'cursor' });
}
/** Cursor keys a chat by `conversation_id` (its `session_id` equivalent). */
function cursorSessionId(input: any): string {
return payloadSessionId({ session_id: input?.conversation_id || input?.session_id });
}
const DAY_MS = 24 * 60 * 60 * 1000;
/**
* Once a day per repo, the `repo_seen` event: whether `.trail/` is committed
* here, how many learnings it holds, and whether this machine shares the repo
* with a workspace. Queued only, like every hook's telemetry.
*/
export function trackRepoSeen(dir: string, now = Date.now()): void {
try {
const place = repoPlace(dir);
if (!place.git) return;
const mark = join(cacheDir(place.checkout), 'trail-repo-seen.json');
if (now - (readJson<{ at?: number }>(mark)?.at ?? 0) < DAY_MS) return;
writeJsonAtomic(mark, { at: now }, true);
const tracked = execFileSync('git', ['ls-files', '--', '.trail'], { cwd: place.checkout, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, windowsHide: true });
track(
'repo_seen',
{ trail_committed: String(tracked.trim().length > 0), learnings_bucket: countBucket(learningFiles(place.checkout).length), workspace: String(inWorkspace(place.checkout)) },
{ repo: place.checkout },
);
} catch {
// A missed sighting undercounts one repo for one day.
}
}
/**
* When the learnings committed on this checkout's HEAD went up since the last
* session here: how many came in and how many there are, as buckets. A repo
* with committed learnings is where trail starts paying off, so this is the
* activation count. `first_look` marks the first time this clone is seen, so
* a clone of a repo that already had them isn't counted as new ones.
*/
export function trackLearningsCommitted(dir: string): void {
try {
const place = repoPlace(dir);
if (!place.git) return;
const listed = execFileSync('git', ['ls-tree', '-r', '--name-only', 'HEAD', '--', '.trail/learnings'], {
cwd: place.checkout, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, windowsHide: true,
});
const count = listed.split('\n').filter((f) => f.endsWith('.md')).length;
const mark = join(cacheDir(place.checkout), 'trail-learnings-committed.json');
const before = readJson<{ count?: number }>(mark)?.count;
if (before === count) return;
writeJsonAtomic(mark, { count }, true);
if (count <= (before ?? 0)) return;
track(
'learnings_committed',
{ added_bucket: countBucket(count - (before ?? 0)), total_bucket: countBucket(count), first_look: String(before === undefined) },
{ repo: place.checkout },
);
} catch {
// Not a repo with a HEAD yet, or git is slow: counted next session.
}
}
/**
* Learnings added to this repo but sitting uncommitted in `.trail/learnings/` (from trail init's
* read of past sessions, or a session that ended before committing) reach no
* teammate. Once a day per repo, the first reply says so, with the line that
* makes the case for committing them. Empty when everything is committed.
*/
export function uncommittedDirective(dir: string, now = Date.now()): string {
try {
const place = repoPlace(dir);
if (!place.git) return '';
const status = execFileSync('git', ['status', '--porcelain', '--untracked-files=all', '--', '.trail/learnings'], {
cwd: place.checkout, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, windowsHide: true,
});
const n = status.split('\n').filter((l) => l.trimEnd().endsWith('.md')).length;
const setup = setupUncommitted(place.checkout);
if (!n && !setup) return '';
const mark = join(cacheDir(place.checkout), 'trail-uncommitted-said.json');
if (now - (readJson<{ at?: number }>(mark)?.at ?? 0) < DAY_MS) return '';
writeJsonAtomic(mark, { at: now }, true);
if (setup) {
const line = setupCommitLine(teammatesOn(place.checkout));
return `${tag()} trail's shared setup here (.trail/ and .claude/settings.json) isn't committed yet, so teammates' Claude can't read the learnings. Say so once, at the end of your first reply, with this line, word for word: ${line}\n`;
}
const line = commitLines({}, teammatesOn(place.checkout), 'repo').uncommitted;
const them = n === 1 ? "learning added to this repo (in .trail/learnings/) isn't committed yet, so no teammate's agent has it" : "learnings added to this repo (in .trail/learnings/) aren't committed yet, so no teammate's agent has them";
return `${tag()} ${n} ${them}. Say so once, at the end of your first reply, with this line, word for word: ${line}\n`;
} catch {
return '';
}
}
/**
* trail's shared setup isn't in the last commit: `.trail/hook.cjs` isn't
* tracked, or HEAD's `.claude/settings.json` doesn't run it. Only checked
* where the hook is on disk, so a repo still set up the old way says nothing.
*/
export function setupUncommitted(checkout: string): boolean {
if (!existsSync(join(checkout, '.trail', 'hook.cjs'))) return false;
const git = (args: string[]) => execFileSync('git', args, { cwd: checkout, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, windowsHide: true });
try {
git(['ls-files', '--error-unmatch', '--', '.trail/hook.cjs']);
} catch {
return true;
}
try {
return !git(['show', 'HEAD:.claude/settings.json']).includes('/.trail/hook.cjs');
} catch {
return true;
}
}
/** The most the session-start hook waits on `git fetch` for teammates' branches. */
export const BRANCH_FETCH_CAP_MS = 3000;
/**
* At session start, under trail: read what teammates have pushed, so the
* session's first prompt already knows their learnings and where their work
* overlaps; send any learnings and uses the workspace hasn't seen; and count
* the repo once a day. The fetch is the one wait, capped at
* BRANCH_FETCH_CAP_MS and skipped when the branches were read in the last
* minute; a fetch that runs out of time still reads the branches already here.
* The sync only spawns a detached child.
*/
function trailAtStart(dir: string): void {
if (brand() !== 'trail' || !keepsNotes(dir)) return;
try {
const top = repoPlace(dir);
if (top.git && branchesStale(top.checkout, Date.now(), SESSION_REFRESH_MS)) refreshBranches(top.checkout, { fetchTimeoutMs: BRANCH_FETCH_CAP_MS });
} catch {
// Without it, the first prompt sees what the last refresh saw.
}
maybeSyncInBackground(dir);
trackRepoSeen(dir);
trackLearningsCommitted(dir);
}
/** What the session-start text says about learnings, read once. */
interface StartLearnings {
/** This repo keeps learnings on this machine. */
kept: boolean;
count: number | NoteCounts;
/** The skills line, plus under trail the standing learnings and the uncommitted line. */
extra: string;
}
/**
* The learnings part of the session-start text. It needs nothing from
* `graft/`: the learnings are their own files. Empty on any read failure,
* which costs the session its learnings, never its start.
*/
function learningsAtStart(dir: string): StartLearnings {
// 1b (P21, J16): every-repo personal learnings load in every repo, a plain one too, skills on or off; never a
// lesson (R47: everyRepoLearnings leaves them out). Shown as standing learnings, phase 0's framing.
let every: Note[] = [];
try { every = everyRepoLearnings(); } catch { /* none this time */ }
try {
if (!keepsNotes(dir)) return { kept: false, count: 0, extra: standingDirective(every) };
const skills = skillsDirective(dir);
const standing = brand() === 'trail' ? standingDirective(withEvery(standingLearnings(dir), every)) + uncommittedDirective(dir) : standingDirective(every);
return { kept: true, count: noteCounts(dir), extra: skills + standing };
} catch {
return { kept: false, count: 0, extra: standingDirective(every) };
}
}
/** This repo's standing learnings, then the every-repo ones not already among them (by id). */
function withEvery(here: Note[], every: Note[]): Note[] {
const ids = new Set(here.map((n) => n.id).filter(Boolean));
return [...here, ...every.filter((n) => !n.id || !ids.has(n.id))];
}
/**
* D87: what the person kept on `trail init`'s screen, named once at the next interactive startup or resume in that
* repo with its undo. Skills on or off. A notice where the host shows one, else context from Trail.
*/
function keptAtStart(input: any, dir: string): { notice?: string; context?: string } {
try {
const source = typeof input?.source === 'string' && input.source ? input.source : 'startup';
if (source !== 'startup' && source !== 'resume') return {};
if (typeof input?.agent_id === 'string' && input.agent_id) return {};
if (String(process.env.CLAUDE_CODE_ENTRYPOINT ?? '').startsWith('sdk')) return {};
const cwd = typeof input?.cwd === 'string' && input.cwd ? input.cwd : dir;
const line = keptNotice(repoPlace(cwd).key, process.env, trailNow(process.env));
if (!line) return {};
return hostFacts(process.env, detectHost(input).host).startNotice ? { notice: line } : { context: keptContext(line) };
} catch {
return {};
}
}
/**
* The session-start text: the orientation from `graft/INDEX.md` with the
* learnings in it, or, where INDEX.md is missing (never built here; `graft/` is
* git-ignored, so a teammate's fresh clone has none), the learnings alone.
*/
function orientationAtStart(dir: string, learnings: StartLearnings): string {
try {
const idx = readFileSync(join(resolveContextDir(dir), 'INDEX.md'), 'utf8');
const banner = staleBanner(indexFreshness(dir)) ?? undefined;
// Where the map is: `.trail/cache/` in a repo on trail, `graft/` elsewhere (context/map-dir.ts).
const mapDir = relative(dir, resolveContextDir(dir)).split('\\').join('/') || 'graft';
return formatOrientation(idx, undefined, banner, learnings.count, learnings.kept, learnings.extra, mapDir);
} catch {
return learnings.kept ? `${tag()} ${teamNotesDirective(learnings.count, true)}${learnings.extra}` : learnings.extra;
}
}
/** The repo's committed `.mcp.json` still registers trail's server (set up before 0.23). */
function repoNamesTrailServer(dir: string): boolean {
try {
return Boolean(JSON.parse(readFileSync(join(dir, '.mcp.json'), 'utf8'))?.mcpServers?.trail);
} catch {
return false;
}
}
export async function main(event: string): Promise<void> {
// Shims before pre-bash.js existed send PreToolUse here: hand it straight
// over, before any of the work the other events share.
if (event === 'pre-bash') { await preBashMain(event); return; }
// trail's own headless Claude calls (the first-run read of past sessions) run with this set.
if (process.env.TRAIL_NO_HOOKS === '1') return;
const input = readStdin();
// Registered in the repo and in ~/.claude, Claude Code runs both: one answers.
// Who sent the payload decides first: Copilot CLI runs only the repo's copy.
if (globalCopyCovers(event, process.argv[1], homedir(), process.env, input)) return;
const dir = projectDir(input);
// A failed Bash call (PostToolUseFailure, D34): the skills mark, and 1b's wall fix as its one answer, before any of
// the work the other events share.
if (event === 'post-bash-fail') { emitHook('PostToolUseFailure', await postBashPart(input, dir, true)); return; }
// Codex's PostToolUse on Bash, on every exit (3.4): the skills mark, and the wall fix where its context reaches the model.
if (event === 'codex-post-bash') { emitHook('PostToolUse', await codexPostBashPart(input, dir)); return; }
adoptRepoBrand(dir, process.env, hostsWiredForTrail);
if (event === 'session-start') {
// The skills part first, so nothing below can skip it (a repo with no graft/INDEX.md included).
const skills = await sessionStartPart(input, dir);
// Before anything is emitted: refresh this repo's wiring if it was written by
// an older graft, and pick up any cached "newer version on npm" answer.
// background:false — the registry check stays off the network here; the CLI
// and the MCP server fill that cache, this only reads it.
const upkeep = runUpkeep(dir, runningVersion(), { background: false }).lines;
// On graft without trail, in a repo graft set up: once a week, the agent
// tells the person how to get it.
const handover = wiredHostIds(dir).includes('claude') ? trailHandoverLine() : null;
if (handover) upkeep.push(handover);
// Roll up any session that ended since we were last here, then send the
// queue from a detached child: what session end didn't get to (a killed
// terminal never fires it) goes now. Once a day at most, never waited on.
flushClosedSessions(dir);
maybeFlushInBackground();
// Once per repo: older versions kept the prompt in each session file.
try { dropStoredPrompts(dir); } catch { /* tried again next session */ }
trailAtStart(dir);
// A repo on trail, opened on a machine that has graft but not the trail command.
// Only while its .mcp.json still names a trail server: once it doesn't, trail: true takes back the stand-in.
if (repoWiredForTrail(dir)) fitTrailServerToMachine(homedir(), resolve(dir), { trail: trailOnPath() || !repoNamesTrailServer(dir), graft: commandOnPath('graft') });
const text = orientationAtStart(dir, learningsAtStart(dir));
const kept = keptAtStart(input, dir);
// The skills context comes after the learnings; its notice is for the person.
const out = [upkeep.join('\n'), text, skills.context, kept.context].filter(Boolean).join('\n\n');
const notice = [skills.notice, kept.notice].filter(Boolean).join('\n') || undefined;
emitHook('SessionStart', { context: out, notice });
return;
}
// Claude closing: send the queue from a detached child, so quitting isn't slowed.
if (event === 'session-end') { maybeFlushInBackground(); return; }
if (event === 'post-edit') { await handlePostEdit(input, dir); return; }
if (event === 'tool-savings') {
handleToolUse(input, dir);
recordSkillUse(skillOfToolUse(input), input, dir);
// PostToolUse on Bash: the skills mark, and the post-tool offer channel's context (3.4),
// then the learnings about the file the call touched, in the same one answer.
emitHook('PostToolUse', withTouchLearnings(await postBashPart(input, dir, false), input, dir));
return;
}
if (event === 'cursor-post-tool') { handleCursorPostTool(input, dir); return; }
if (event === 'cursor-mcp') { handleCursorMcp(input, dir); return; }
// Cursor closes a chat: force-close THIS conversation into a bucketed
// `session_summary` now (its file's mtime is fresh, so the idle sweep would
// skip it). Attributed to Cursor. The idle sweep stays on Claude's
// session-start, whose Stop fires per turn and so has no real end signal.
if (event === 'cursor-session-end') { summarizeSession(dir, cursorSessionId(input), { host: 'cursor' }); return; }
if (event === 'stop') { await handleStopEvent(input, dir); return; }
// An edit's payload, not a Stop's: the turn-end bookkeeping only, so its one answer stays the edit's.
if (event === 'post-edit-sync') { await handlePostEdit(input, dir); await handleStopEvent(input, dir, { skills: false }); return; }
if (event === 'prompt') { await handlePrompt(input, dir); return; }
}