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 { isGraftEntry } from '../hosts/config-write.js';
type Json = Record<string, any>;
const slCmd = (name: 'graft' | 'trail' = 'graft') => `node "\${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/${name}-statusline.cjs"`;
/** trail's status line, from the shim in `.trail/` (see claude/init.ts). */
const TRAIL_SL_CMD = 'node "${CLAUDE_PROJECT_DIR:-.}/.trail/statusline.cjs"';
/** Stable marker for "this statusLine is Graft's", not the full command string —
* an older shim path or a GRAFT_DIR wrapper still names this file. Either name. */
const STATUSLINE_HELPER = /(graft|trail)-statusline\.cjs|\.trail\/statusline\.cjs/;
const FOOTER = 'graft/[\\w./-]+\\.md';
// Every form graft is actually invoked as. 'graft:*' covers a global install;
// the other two cover a repo working on graft itself (or any consumer running it
// from a checkout), where the binary is not on PATH under that name. A retrieval
// call that raises a permission prompt loses to grep, which never does.
const ALLOW_ENTRIES = [
'Bash(trail:*)',
'Bash(graft:*)',
'Bash(npx graft:*)',
'Bash(graft-dev:*)',
'Bash(node dist/cli.js:*)',
];
/** Where the repo-level install's shims sit, relative to whatever project is open. */
const REPO_HELPERS = '${CLAUDE_PROJECT_DIR:-.}/.claude/helpers';
/**
* `helpers` is the directory holding `graft-hooks.cjs`, and it is a parameter for
* one reason: the user-level install (see hosts/claude-global.ts) has to name an
* absolute path. A `${CLAUDE_PROJECT_DIR}` command works only where a previous
* `graft init` wrote a shim into that project — which is exactly the case the
* global copy exists to cover, so it cannot reuse the repo form.
*/
function hookCmd(arg: string, helpers: string = REPO_HELPERS, name: 'graft' | 'trail' = 'graft'): string {
return `node "${helpers}/${name}-hooks.cjs" ${arg}`;
}
/**
* A hook command that exits 0 whatever happens to it (every event since D116 item 6; PreToolUse first, for this). Copilot CLI reads
* the repo's `.claude/settings.json` and denies the tool call when a
* PreToolUse hook exits non-zero, so a shim that can't be found (a host
* started in a subfolder without CLAUDE_PROJECT_DIR, the shim gone after an
* uninstall) or a missing node would deny every shell command. `|| exit 0`
* means the same in sh and Windows cmd. The hook's answer travels as JSON on
* stdout, never as an exit code, so nothing is lost by it.
*/
export function failOpen(command: string): string {
return `${command} || exit 0`;
}
/** trail's committed hook, `.trail/hook.cjs`, run for one event. */
export function trailHookCmd(arg: string): string {
return `node "\${CLAUDE_PROJECT_DIR:-.}/.trail/hook.cjs" ${arg}`;
}
function graftBlocks(helpers?: string, name: 'graft' | 'trail' = 'graft'): Record<string, Json[]> {
return hookBlocks((arg) => hookCmd(arg, helpers, name));
}
/**
* Every hook event, each running `command(<event arg>)`.
*
* Every `timeout` here is in seconds: Claude Code and Codex read it that way.
* Versions before 0.23 wrote 8000-15000 meaning milliseconds, which the host
* read as hours; merging again replaces them. The prompt hook also keeps to a
* hard budget of its own (prompt-hook.ts PROMPT_BUDGET_MS), well inside this.
*/
function hookBlocks(command: (arg: string) => string): Record<string, Json[]> {
// D116 item 6: every event fails open, not only PreToolUse: a `git stash -u` or `git clean` before the wiring is
// committed takes the untracked shim while settings.json still names it, and a missing shim must stay quiet.
const hookCmd_ = (arg: string) => failOpen(command(arg));
return {
PostToolUse: [
{ matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: hookCmd_('post-edit'), timeout: 10 }] },
// Score the usage mix and sum token savings. A graft retrieval (CLI `graft …`
// via Bash, or the `graft_*` MCP tools) prints a `[graft] tokens saved ≈ N`
// footer this hook sums into the session total; the same hook classifies
// Read/Grep/Glob as source reads vs graft as graft reads, which is what feeds
// `graft stats` and the `session_summary` graft-vs-grep ratio. Broad matcher,
// but the handler no-ops instantly unless there is something to record, so an
// unrelated Bash or a plain Read costs only a stdin read. `Skill` is the
// agent using a skill: one of the repo's goes to the workspace as a run.
{ matcher: 'Bash|mcp__graft__|mcp__trail__|Read|Grep|Glob|Skill', hooks: [{ type: 'command', command: hookCmd_('tool-savings'), timeout: 8 }] },
],
// Longer than the other hooks: its `graft ask` is a real query, and a query
// brings the graph up to date first (graph/refresh.ts). The hook itself
// stops at its own total budget (PROMPT_BUDGET_MS) and reads this number
// back (promptAskTimeout) so its ask child always fits inside it.
UserPromptSubmit: [{ hooks: [{ type: 'command', command: hookCmd_('prompt'), timeout: 15 }] }],
// Before every shell command: pre-bash.js, which fails open, behind a
// command that fails open too (see failOpen). Claude Code reads `timeout`
// in seconds, so 5 caps the wait a wedged hook could add to one command,
// after which the command runs anyway.
PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: hookCmd_('pre-bash'), timeout: 5 }] }],
// A Bash call that failed fires this, never PostToolUse (D34): learned
// skills mark the outcome for the next catch-up. Fails open like
// PreToolUse, since some hosts read a non-zero exit as a refusal.
PostToolUseFailure: [{ matcher: 'Bash', hooks: [{ type: 'command', command: hookCmd_('post-bash-fail'), timeout: 5 }] }],
SessionStart: [{ hooks: [{ type: 'command', command: hookCmd_('session-start'), timeout: 10 }] }],
Stop: [{ hooks: [{ type: 'command', command: hookCmd_('stop'), timeout: 10 }] }],
// Sends the telemetry queue in a detached child, so closing Claude isn't
// slowed. Not fired when the terminal is killed; session start sends what's left.
SessionEnd: [{ hooks: [{ type: 'command', command: hookCmd_('session-end'), timeout: 5 }] }],
};
}
/**
* Is this allowlist entry one graft wrote?
*
* Scoped to the forms graft is actually invoked as — NOT any rule mentioning
* "graft". A user who allowlists their own `Bash(graft-mytool:*)` keeps it; only
* graft's own set is replaced, which is what lets a renamed entry disappear on
* upgrade instead of accumulating beside its replacement.
*/
export function isGraftAllowEntry(entry: unknown): boolean {
return /^Bash\((?:trail|graft|npx graft|graft-dev|node dist\/cli\.js)(?::|\))/.test(String(entry));
}
/** Is this footer regex graft's? It points at the card tree, which is graft's alone. */
export function isGraftFooterRegex(re: unknown): boolean {
return String(re).includes('graft/');
}
function envNoStatusline(): boolean {
const v = process.env.GRAFT_NO_STATUSLINE;
return v !== undefined && v !== '' && v !== '0' && v !== 'false';
}
/** True when init should write (or refresh) Graft's Claude Code statusLine. */
export function statuslineWanted(opts: { statusline?: boolean } = {}): boolean {
return opts.statusline !== false && !envNoStatusline();
}
function isGraftStatusline(value: unknown): boolean {
if (!value || typeof value !== 'object') return false;
const command = (value as Json).command;
return typeof command === 'string' && STATUSLINE_HELPER.test(command);
}
function applyStatusline(
merged: Json,
key: 'statusLine' | 'subagentStatusLine',
warnings: string[],
wanted: boolean,
foreignWarning: string,
name: 'graft' | 'trail' = 'graft',
): void {
const current = merged[key];
const ours = isGraftStatusline(current);
if (!wanted) {
if (!current || ours) delete merged[key];
else warnings.push(foreignWarning);
return;
}
if (!current || ours) {
merged[key] = { type: 'command', command: slCmd(name) };
return;
}
warnings.push(foreignWarning);
}
export function mergeGraftSettings(
existing: Json,
opts: { statusline?: boolean; name?: 'graft' | 'trail' } = {},
): { merged: Json; warnings: string[] } {
const merged: Json = { ...(existing ?? {}) };
const name = opts.name ?? 'graft';
const warnings: string[] = [];
const wanted = statuslineWanted(opts);
applyStatusline(
merged, 'statusLine', warnings, wanted,
`Existing statusLine left untouched (a session allows only one). To use ${name === 'trail' ? 'Trail' : 'Graft'}, point it at .claude/helpers/${name}-statusline.cjs.`,
name,
);
applyStatusline(
merged, 'subagentStatusLine', warnings, wanted,
'Existing subagentStatusLine left untouched.',
name,
);
merged.hooks = { ...(merged.hooks ?? {}) };
for (const [event, blocks] of Object.entries(graftBlocks(undefined, name))) {
const prior = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
const foreign = prior.filter((e: Json) => !isGraftEntry(e)); // drop old Graft entries → idempotent
merged.hooks[event] = [...foreign, ...blocks];
}
// Drop graft's own prior regex before re-adding, so a change to FOOTER replaces
// the old pattern instead of stacking beside it. The user's regexes are kept.
const priorFooter = Array.isArray(merged.footerLinksRegexes) ? merged.footerLinksRegexes : [];
merged.footerLinksRegexes = [...priorFooter.filter((r: unknown) => !isGraftFooterRegex(r)), FOOTER];
// headless/subagent runs hard-deny Bash by default; without an allowlist entry
// `graft ask`'s own Bash calls (and the skill it installs) can't run out-of-box.
// Same shape as the hooks merge above: drop graft's prior entries, then add the
// current set. Append-only left a renamed invocation form in the user's settings
// forever, with nothing able to remove it.
merged.permissions = { ...(merged.permissions ?? {}) };
const priorAllow = Array.isArray(merged.permissions.allow) ? merged.permissions.allow : [];
merged.permissions.allow = [...priorAllow.filter((e: unknown) => !isGraftAllowEntry(e)), ...ALLOW_ENTRIES];
return { merged, warnings };
}
/**
* The hook blocks alone, merged into a settings file, with the shims addressed by
* absolute path — `~/.claude/settings.json`, where a write reaches every project on
* the machine (see hosts/claude-global.ts for why that copy has to exist).
*
* Hooks only, deliberately. `mergeGraftSettings` also claims the statusline, the
* footer regex and a Bash allowlist, and each of those is a reasonable thing to
* accept for a repo you ran `graft init` in and an unreasonable thing to impose on
* every repo you ever open — a statusline especially, since a session allows exactly
* one and taking it globally would silently outrank the user's own. The hooks are the
* piece that has to be global, because they are what a worktree loses.
*
* Same idempotent shape as the repo merge: graft's prior entries are dropped before
* the current set is added, so re-running converges instead of stacking.
*/
export function mergeGraftHooks(existing: Json, helpers: string): { merged: Json } {
const merged: Json = { ...(existing ?? {}) };
merged.hooks = { ...(merged.hooks ?? {}) };
for (const [event, blocks] of Object.entries(graftBlocks(helpers))) {
const prior = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
const foreign = prior.filter((e: Json) => !isGraftEntry(e));
merged.hooks[event] = [...foreign, ...blocks];
}
return { merged };
}
/** Drop every fragment graft or trail wrote from a settings object, keeping the user's. */
function withoutOurs(existing: Json): Json {
const merged: Json = { ...(existing ?? {}) };
for (const key of ['statusLine', 'subagentStatusLine'] as const) if (isGraftStatusline(merged[key])) delete merged[key];
if (merged.hooks && typeof merged.hooks === 'object' && !Array.isArray(merged.hooks)) {
const hooks: Json = {};
for (const [event, prior] of Object.entries(merged.hooks)) {
const kept = Array.isArray(prior) ? prior.filter((e: Json) => !isGraftEntry(e)) : prior;
if (!Array.isArray(kept) || kept.length) hooks[event] = kept;
}
if (Object.keys(hooks).length) merged.hooks = hooks;
else delete merged.hooks;
}
if (Array.isArray(merged.footerLinksRegexes)) {
const kept = merged.footerLinksRegexes.filter((r: unknown) => !isGraftFooterRegex(r));
if (kept.length) merged.footerLinksRegexes = kept;
else delete merged.footerLinksRegexes;
}
if (merged.permissions && typeof merged.permissions === 'object' && Array.isArray(merged.permissions.allow)) {
const allow = merged.permissions.allow.filter((e: unknown) => !isGraftAllowEntry(e));
const permissions: Json = { ...merged.permissions };
if (allow.length) permissions.allow = allow;
else delete permissions.allow;
if (Object.keys(permissions).length) merged.permissions = permissions;
else delete merged.permissions;
}
return merged;
}
/**
* trail's part of the committed `.claude/settings.json`: one SessionStart entry
* running `.trail/hook.cjs`, and nothing else. For a teammate without trail it
* shows the learnings and offers trail; with trail it hands off to the install.
* Anything an older init put here (status line, the other hooks, allowlist,
* footer regex) comes out, so the file a team commits is the same on every machine.
*/
export function mergeTrailShared(existing: Json): Json {
const merged = withoutOurs(existing);
merged.hooks = { ...(merged.hooks ?? {}) };
merged.hooks.SessionStart = [
...(Array.isArray(merged.hooks.SessionStart) ? merged.hooks.SessionStart : []),
...hookBlocks(trailHookCmd).SessionStart!,
];
return merged;
}
/**
* trail's part of `.claude/settings.local.json`, the person's own: the status
* line, the footer regex and the allowlist, plus, when `~/.claude` doesn't carry
* them (`--no-global`), the hooks for every event but session start, which the
* shared file already runs once.
*/
export function mergeTrailLocal(
existing: Json,
opts: { statusline?: boolean; hooks?: boolean } = {},
): { merged: Json; warnings: string[] } {
const merged = withoutOurs(existing);
const warnings: string[] = [];
if (statuslineWanted(opts)) {
for (const key of ['statusLine', 'subagentStatusLine'] as const) {
if (!merged[key]) merged[key] = { type: 'command', command: TRAIL_SL_CMD };
else if (key === 'statusLine') warnings.push('Existing statusLine left untouched (a session allows only one). To use Trail, point it at .trail/statusline.cjs.');
}
}
if (opts.hooks) {
merged.hooks = { ...(merged.hooks ?? {}) };
for (const [event, blocks] of Object.entries(hookBlocks(trailHookCmd))) {
if (event === 'SessionStart') continue;
merged.hooks[event] = [...(Array.isArray(merged.hooks[event]) ? merged.hooks[event] : []), ...blocks];
}
}
merged.footerLinksRegexes = [...(merged.footerLinksRegexes ?? []), FOOTER];
merged.permissions = { ...(merged.permissions ?? {}) };
merged.permissions.allow = [...(merged.permissions.allow ?? []), ...ALLOW_ENTRIES];
return { merged, warnings };
}