|
| 1 | +#!/usr/bin/env node |
| 2 | +// SessionStart hook: warns an agent session whose instructions are stale, or |
| 3 | +// which started in the primary checkout (#5167). |
| 4 | +// |
| 5 | +// Claude Code loads `AGENTS.md` and `.claude/skills/` from the directory a |
| 6 | +// session starts in, once, at session start. A worktree created later does not |
| 7 | +// change what was loaded, so a session started in a stale checkout follows |
| 8 | +// stale rules for its whole run, however fresh the branches it cuts are. The |
| 9 | +// v2.0.0 release session did exactly that (#5159): it started in a primary |
| 10 | +// checkout 447 commits behind `origin/v2/main` and ran three steps on a |
| 11 | +// superseded `release` skill. |
| 12 | +// |
| 13 | +// So `.claude/settings.json` runs this at session start. It fetches |
| 14 | +// `origin/v2/main` and asks whether `v2/main` has changed the instructions |
| 15 | +// since this checkout's HEAD branched from it: |
| 16 | +// |
| 17 | +// git diff --quiet HEAD...origin/v2/main -- AGENTS.md .claude/ |
| 18 | +// |
| 19 | +// The three dots matter. They diff the merge base against `origin/v2/main`, |
| 20 | +// so a branch that edits the instructions itself (a PR like the one that |
| 21 | +// added this file) is not reported stale for its own edits, while a checkout |
| 22 | +// that lacks any instruction change `v2/main` has made is. |
| 23 | +// |
| 24 | +// The hook never blocks the session and never fails it: whatever it prints is |
| 25 | +// added to the session's context, and the rule in `AGENTS.md` (Issue-driven |
| 26 | +// work style) says what the session does about it. A failed fetch (offline, a |
| 27 | +// lock held by another session's fetch) is reported, and the check runs |
| 28 | +// against the `origin/v2/main` already on disk rather than not at all. |
| 29 | + |
| 30 | +import { spawnSync } from "node:child_process"; |
| 31 | +import path from "node:path"; |
| 32 | +import { fileURLToPath, pathToFileURL } from "node:url"; |
| 33 | + |
| 34 | +/** The branch whose instructions a session must be running. */ |
| 35 | +export const BASE = "origin/v2/main"; |
| 36 | + |
| 37 | +/** The paths Claude Code loads its instructions from at session start. */ |
| 38 | +export const INSTRUCTION_PATHS = ["AGENTS.md", ".claude/"]; |
| 39 | + |
| 40 | +/** How long the fetch may take before the check falls back to the local ref. */ |
| 41 | +export const FETCH_TIMEOUT_MS = 15_000; |
| 42 | + |
| 43 | +/** How many changed paths a STALE report names before summarizing the rest. */ |
| 44 | +export const MAX_NAMED = 5; |
| 45 | + |
| 46 | +/** |
| 47 | + * Pure: the lines to print, from what the checks found. |
| 48 | + * |
| 49 | + * @param {{ |
| 50 | + * fetched: boolean, |
| 51 | + * baseSha: string | null, |
| 52 | + * stale: boolean, |
| 53 | + * changed: string[], |
| 54 | + * primary: boolean, |
| 55 | + * }} state |
| 56 | + * @returns {string[]} |
| 57 | + */ |
| 58 | +export function report({ fetched, baseSha, stale, changed, primary }) { |
| 59 | + const lines = []; |
| 60 | + if (!fetched) |
| 61 | + lines.push( |
| 62 | + `session-instructions-check: could not fetch ${BASE}; checking against the copy already on disk.`, |
| 63 | + ); |
| 64 | + if (baseSha === null) { |
| 65 | + lines.push( |
| 66 | + `session-instructions-check: cannot resolve ${BASE}, so whether this session's AGENTS.md and skills are current is UNKNOWN. Run \`git fetch origin v2/main\` and re-check before doing anything.`, |
| 67 | + ); |
| 68 | + } else if (stale) { |
| 69 | + const named = |
| 70 | + changed.length > MAX_NAMED |
| 71 | + ? `${changed.slice(0, MAX_NAMED).join(", ")} and ${changed.length - MAX_NAMED} more` |
| 72 | + : changed.join(", "); |
| 73 | + lines.push( |
| 74 | + `STALE: this session's instructions differ from ${BASE} (${baseSha.slice(0, 8)}). ` + |
| 75 | + `${BASE} has changed ${named} since this checkout's HEAD branched from it, ` + |
| 76 | + "and Claude Code loaded AGENTS.md and the skills from this checkout at session start. " + |
| 77 | + "Stop, and ask for a session started in a worktree freshly cut from origin/v2/main " + |
| 78 | + "(AGENTS.md, Issue-driven work style), rather than continuing on rules that cannot be trusted.", |
| 79 | + ); |
| 80 | + } else { |
| 81 | + lines.push( |
| 82 | + `session-instructions-check: AGENTS.md and .claude/ match ${BASE} (${baseSha.slice(0, 8)}).`, |
| 83 | + ); |
| 84 | + } |
| 85 | + if (primary) |
| 86 | + lines.push( |
| 87 | + "session-instructions-check: this session started in the primary checkout, which concurrent " + |
| 88 | + "sessions share. Do the work in a git worktree freshly cut from origin/v2/main, never here " + |
| 89 | + "(AGENTS.md, Issue-driven work style).", |
| 90 | + ); |
| 91 | + return lines; |
| 92 | +} |
| 93 | + |
| 94 | +function git(args, cwd, opts = {}) { |
| 95 | + const r = spawnSync("git", args, { cwd, encoding: "utf8", ...opts }); |
| 96 | + return { status: r.error ? -1 : r.status, stdout: r.stdout ?? "" }; |
| 97 | +} |
| 98 | + |
| 99 | +/** |
| 100 | + * Run the checks in the repository at `cwd`. |
| 101 | + * |
| 102 | + * @param {{ cwd: string, fetch?: boolean }} opts |
| 103 | + * @returns {string[]} the lines to print |
| 104 | + */ |
| 105 | +export function checkSession({ cwd, fetch = true }) { |
| 106 | + const fetched = |
| 107 | + !fetch || |
| 108 | + git(["fetch", "--quiet", "origin", "v2/main"], cwd, { |
| 109 | + timeout: FETCH_TIMEOUT_MS, |
| 110 | + }).status === 0; |
| 111 | + const resolved = git( |
| 112 | + ["rev-parse", "--verify", "--quiet", `${BASE}^{commit}`], |
| 113 | + cwd, |
| 114 | + ); |
| 115 | + const baseSha = resolved.status === 0 ? resolved.stdout.trim() : null; |
| 116 | + |
| 117 | + let changed = []; |
| 118 | + if (baseSha !== null) { |
| 119 | + const diff = git( |
| 120 | + ["diff", "--name-only", `HEAD...${BASE}`, "--", ...INSTRUCTION_PATHS], |
| 121 | + cwd, |
| 122 | + ); |
| 123 | + // No merge base (an unrelated history) also lands here, as a failed |
| 124 | + // diff: the instructions cannot be shown current, so they count as stale. |
| 125 | + changed = |
| 126 | + diff.status === 0 |
| 127 | + ? diff.stdout.split("\n").filter(Boolean) |
| 128 | + : ["(no common history with HEAD)"]; |
| 129 | + } |
| 130 | + |
| 131 | + // In a linked worktree the git dir is `.git/worktrees/<name>`, apart from |
| 132 | + // the common dir; in the primary checkout the two are the same. |
| 133 | + const dirs = git( |
| 134 | + ["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"], |
| 135 | + cwd, |
| 136 | + ).stdout.split("\n"); |
| 137 | + const primary = dirs.length >= 2 && dirs[0] !== "" && dirs[0] === dirs[1]; |
| 138 | + |
| 139 | + return report({ |
| 140 | + fetched, |
| 141 | + baseSha, |
| 142 | + stale: changed.length > 0, |
| 143 | + changed, |
| 144 | + primary, |
| 145 | + }); |
| 146 | +} |
| 147 | + |
| 148 | +if ( |
| 149 | + process.argv[1] && |
| 150 | + import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href |
| 151 | +) { |
| 152 | + const repoRoot = path.resolve( |
| 153 | + path.dirname(fileURLToPath(import.meta.url)), |
| 154 | + "..", |
| 155 | + ); |
| 156 | + console.log(checkSession({ cwd: repoRoot }).join("\n")); |
| 157 | +} |
0 commit comments