Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import { execFile } from "node:child_process";
import { access, realpath } from "node:fs/promises";
import { isAbsolute, relative, resolve } from "node:path";
import { promisify } from "node:util";
import { type AgentAdapter, defaultAgent } from "./agents/index.js";
import { findGitRoot } from "./git.js";
import { messageHash } from "./messages.js";
import type { Session } from "./schema/session.js";
import { readSessionHead } from "./session-git.js";
import { captureDisabled } from "./store/paths.js";
import { loadConfig } from "./store/stores.js";
const exec = promisify(execFile);
/**
* The link between a code commit and the thought behind it (Story 9.4). A git
* `prepare-commit-msg` hook writes a `Thought: h…` trailer naming the newest user
* message of the session that made the commit (Story 10.6: the session the
* agent's shell names, else the one in `.cogit/HEAD`); at read time the trailers
* are read back from `git log`, so the link survives a rebase or a fresh clone
* and never depends on the agent remembering a rule. A squash folds several
* commits' messages into one, so one commit can name several messages.
*/
/** The trailer key git and cogit share. */
export const THOUGHT_TRAILER = "Thought";
/** A message id (`h` plus 12 hex, `messages.ts`). */
const THOUGHT_VALUE = /^h[0-9a-f]{12}$/;
/** A full commit hash: what `%H` prints and what the records store. */
const FULL_HASH = /^[0-9a-f]{40}$/;
/**
* A `Thought:` line anywhere in a commit message. Not only git's final trailer
* block: `git merge --squash` quotes the commits indented inside the body, and a
* squash can leave several blocks. The whole line has to match, so prose that
* mentions a thought is not a link.
*/
const THOUGHT_LINE = new RegExp(`^[ \\t]*${THOUGHT_TRAILER}:[ \\t]*(h[0-9a-f]{12})[ \\t]*$`, "gim");
/** Precedes each commit in the `git log` output `parseThoughtTrailers` reads. */
const COMMIT_MARK = "\x01";
/** Commit bodies add up in a long history; execFile's 1 MB default would lose every link. */
const LOG_MAX_BUFFER = 256 * 1024 * 1024;
export interface TrailerOptions {
/** The project root (where `.cogit/` lives). */
dir: string;
/** Git's `$1`: the file holding the proposed commit message. */
messageFile: string;
/** Git's `$2`: `message`, `template`, `merge`, `squash` or `commit`. */
source?: string;
env?: NodeJS.ProcessEnv;
/** The clock used for the freshness check; defaults to now. */
now?: Date;
}
/** True when the transcript file can be read. */
async function readable(path: string): Promise<boolean> {
return access(path).then(
() => true,
() => false,
);
}
/** Git resolves the message file from the working-tree root, which is its cwd. */
function messagePath(file: string): string {
return isAbsolute(file) ? file : resolve(process.cwd(), file);
}
/** The newest user message of a transcript, as the trailer's value. */
/**
* True when the session's directory is in this project or in the working tree
* the commit is made in: git runs the hook at that tree's top, which for a
* linked worktree outside the project is not under the project's root.
* Unknown counts as here, as before.
*/
async function sessionRunsIn(
agent: AgentAdapter,
transcript: string,
dir: string,
): Promise<boolean> {
const cwd = await agent.readSessionCwd(transcript);
if (cwd === undefined) return true;
const session = await realOrSame(cwd);
for (const place of [dir, process.cwd()]) {
const root = await realOrSame((await findGitRoot(place)) ?? place);
const inside = relative(root, session);
if (inside === "" || (!inside.startsWith("..") && !isAbsolute(inside))) return true;
}
return false;
}
async function realOrSame(path: string): Promise<string> {
return realpath(path).catch(() => resolve(path));
}
async function newestThought(
agent: AgentAdapter,
transcript: string,
sessionId: string,
): Promise<string | undefined> {
const turns = await agent.readConversation(transcript);
const newest = turns.at(-1);
return newest === undefined ? undefined : messageHash(sessionId, newest);
}
/** Writes the trailer into git's message file, keeping one an `--amend` carried. */
async function writeTrailer(messageFile: string, value: string): Promise<void> {
await exec("git", [
"interpret-trailers",
"--in-place",
"--if-exists",
"doNothing",
"--trailer",
`${THOUGHT_TRAILER}: ${value}`,
"--",
messagePath(messageFile),
]);
}
/**
* True while git replays existing commits: a rebase (`rebase-merge`,
* `rebase-apply`, which `git am` shares) or a cherry-pick. Git runs
* `prepare-commit-msg` for each of them, and an old commit is not about the
* session's newest message. Unknown state counts as not replaying.
*/
async function replayingCommits(dir: string, env: NodeJS.ProcessEnv): Promise<boolean> {
let gitDir: string;
try {
const { stdout } = await exec("git", ["-C", dir, "rev-parse", "--absolute-git-dir"], { env });
gitDir = String(stdout).trim();
} catch {
return false;
}
const states = ["rebase-merge", "rebase-apply", "CHERRY_PICK_HEAD"];
const found = await Promise.all(states.map((state) => readable(resolve(gitDir, state))));
return found.includes(true);
}
/**
* Adds the `Thought:` trailer to the prepared commit message (Stories 9.4, 10.6).
* The session that made the commit wins: when the agent names it in the
* environment (a shell it started, `CLAUDE_CODE_SESSION_ID`), only that
* session's transcript counts, so two sessions in one working tree cannot take
* each other's message. A named session with no readable transcript gets no
* trailer — never a fallback to `.cogit/HEAD`, which may be another session. With
* no name (a human commit in a terminal) the fresh `.cogit/HEAD` is used.
* Merges, squashes, replayed commits and an unreadable transcript are skipped,
* and a failure is the caller's to swallow: this never blocks the commit.
*/
export async function addThoughtTrailer(opts: TrailerOptions): Promise<boolean> {
const env = opts.env ?? process.env;
if (captureDisabled(env)) return false;
if (opts.source === "merge" || opts.source === "squash") return false;
if (await replayingCommits(opts.dir, env)) return false;
const agent = defaultAgent();
const named = (env[agent.commitSessionEnv] ?? "").trim();
if (named !== "") {
const transcript = await agent.findTranscript(named, env);
if (transcript === null) return false;
// A session working in another repository (a library next to its project)
// must not stamp its message here: that record lives in the other project,
// so the link could never be followed from this one.
if (!(await sessionRunsIn(agent, transcript, opts.dir))) return false;
const value = await newestThought(agent, transcript, named);
if (value === undefined) return false;
await writeTrailer(opts.messageFile, value);
return true;
}
// Every policy gets the trailer: with the ignore policy the record stays on this
// machine, but `blame` and `show <sha>` here still follow the exact link.
const root = resolve(opts.dir);
const head = await readSessionHead(root);
if (head === undefined || head.at === undefined) return false;
const written = Date.parse(head.at);
if (!Number.isFinite(written)) return false;
const config = await loadConfig(env);
const age = (opts.now ?? new Date()).getTime() - written;
// A little clock skew is fine; a cutoff that passed (or a future date) is not.
if (age > config.trailerMaxAgeHours * 3_600_000 || age < -5 * 60_000) return false;
const transcript =
head.transcriptPath !== undefined && (await readable(head.transcriptPath))
? head.transcriptPath
: await agent.findTranscript(head.sessionId, env);
if (transcript === null) return false;
const value = await newestThought(agent, transcript, head.sessionId);
if (value === undefined) return false;
await writeTrailer(opts.messageFile, value);
return true;
}
/**
* Parses `%x01%H%x00%B` records into commit → the messages it names, in the order
* the commit message lists them, each once.
*/
export function parseThoughtTrailers(stdout: string): Map<string, string[]> {
const out = new Map<string, string[]>();
for (const record of stdout.split(COMMIT_MARK)) {
const separator = record.indexOf("\0");
if (separator === -1) continue;
const commit = record.slice(0, separator);
if (!FULL_HASH.test(commit)) continue;
const body = record.slice(separator + 1);
const thoughts = [...body.matchAll(THOUGHT_LINE)].map((match) => match[1] as string);
if (thoughts.length > 0) out.set(commit, [...new Set(thoughts)]);
}
return out;
}
export interface ReadTrailerOptions {
env?: NodeJS.ProcessEnv;
/** Skip commits older than this ISO date; a session cannot explain them. */
since?: string | undefined;
}
/**
* The `Thought:` lines of this repository (Story 9.4), keyed by full commit
* hash. A missing repository, an old git or an unreadable log only means no
* links: the map and the read verbs keep working.
*/
export async function readThoughtTrailers(
root: string,
opts: ReadTrailerOptions = {},
): Promise<Map<string, string[]>> {
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) return new Map();
const args = [
"-C",
gitRoot,
"log",
"--format=%x01%H%x00%B",
"--extended-regexp",
"--regexp-ignore-case",
`--grep=^[[:space:]]*${THOUGHT_TRAILER}:`,
...(opts.since === undefined ? [] : [`--since=${opts.since}`]),
];
try {
const { stdout } = await exec("git", args, {
maxBuffer: LOG_MAX_BUFFER,
...(opts.env === undefined ? {} : { env: opts.env }),
});
return parseThoughtTrailers(String(stdout));
} catch {
return new Map();
}
}
/** The author email of a commit, or undefined when git cannot read it. */
export async function readCommitAuthorEmail(
root: string,
ref: string,
env?: NodeJS.ProcessEnv,
): Promise<string | undefined> {
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) return undefined;
try {
const args = ["-C", gitRoot, "log", "-1", "--format=%ae", ref];
const { stdout } = await exec("git", args, env === undefined ? undefined : { env });
const email = String(stdout).trim();
return email === "" ? undefined : email;
} catch {
return undefined;
}
}
/**
* The one message a commit's final trailer block names, or undefined (no trailer,
* no such commit). This is what the commit itself was made for; a squash's quoted
* lines are not, so the Shape path never draws one from them.
*/
export async function readCommitThought(
root: string,
ref: string,
env?: NodeJS.ProcessEnv,
): Promise<string | undefined> {
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) return undefined;
const args = ["-C", gitRoot, "log", "-1", "--format=%(trailers:key=Thought,valueonly)", ref];
try {
const { stdout } = await exec("git", args, env === undefined ? undefined : { env });
const value = String(stdout).trim().split("\n")[0]?.trim() ?? "";
return THOUGHT_VALUE.test(value) ? value : undefined;
} catch {
return undefined;
}
}
/** The earliest session start, so the trailer read stops at the record's horizon. */
export function earliestSessionStart(sessions: readonly Session[]): string | undefined {
let earliest: string | undefined;
for (const session of sessions) {
if (earliest === undefined || session.startedAt < earliest) earliest = session.startedAt;
}
return earliest;
}
/** Both directions, since a record may hold seven characters and git forty. */
function sameCommit(recorded: string, commit: string): boolean {
return commit.startsWith(recorded) || recorded.startsWith(commit);
}
function thoughtsOf(
recorded: string,
trailers: ReadonlyMap<string, readonly string[]>,
): readonly string[] | undefined {
for (const [commit, thoughts] of trailers) {
if (sameCommit(recorded, commit)) return thoughts;
}
return undefined;
}
/**
* Attaches trailer-carrying commits to their message nodes (Story 9.4): the
* union of the commits the agent wrote and the commits git says belong to the
* message. A commit the agent listed under a different message moves to the
* trailer's message — the trailer wins — and a squash's commit lands on every
* message it names. A trailer for a message the record never
* summarized has nowhere to land and is left for a later build.
*/
export function attachThoughtTrailers(
sessions: readonly Session[],
trailers: ReadonlyMap<string, readonly string[]>,
): Session[] {
if (trailers.size === 0) return [...sessions];
const byThought = new Map<string, string[]>();
for (const [commit, thoughts] of trailers) {
for (const thought of thoughts) {
const list = byThought.get(thought);
if (list === undefined) byThought.set(thought, [commit]);
else if (!list.some((hash) => sameCommit(hash, commit))) list.push(commit);
}
}
return sessions.map((session) => {
let changed = false;
const nodes = session.nodes.map((node) => {
if (node.kind !== "message") return node;
const current = node.commits ?? [];
const kept = current.filter((hash) => {
const thoughts = thoughtsOf(hash, trailers);
return thoughts === undefined || thoughts.includes(node.id);
});
const claimed = (byThought.get(node.id) ?? []).filter(
(commit) => !kept.some((hash) => sameCommit(hash, commit)),
);
if (kept.length === current.length && claimed.length === 0) return node;
changed = true;
return { ...node, commits: [...kept, ...claimed] };
});
return changed ? { ...session, nodes } : session;
});
}