~/daily/work 2026-11-20 · published 2026-11-21

Fresh code first, once per session

A PreToolUse hook that pulls a clean default branch the first time a session touches a repository, and otherwise only fetches and tells the model what is behind.

The bug it prevents

An agent reads code that is three commits behind its remote, plans a change against it and opens a pull request that conflicts or reverts something. Nobody did anything wrong. The checkout was just old.

Rule 12 of the harness says the first time a session touches a repository, it fetches and updates it before reading or changing code. Pull request #178 added that rule on 2026-11-20, together with the hook that applies it so nobody has to remember.

What the hook decides

`hooks/fresh-pull.py` runs before the file and shell tools. It finds the repository from the file being touched, or from the first `cd` of a shell command. It acts only for repositories of the organization, and only once per session and repository (a marker file in the cache directory, cleaned after seven days).

State of the checkoutWhat the hook does
Clean, on its default branch, with an upstreamgit pull --ff-only, silently
Anything else, and it is behindgit fetch, then one line of context for the model: how many commits behind, on which branch, whether there are local changes
Anything else, and it is not behindNothing
Any error or timeout (8 seconds per git call)Silence; the tool call proceeds

It never stashes, resets, rebases or switches branch, and it never blocks a tool call. When it only fetched, the message tells the model to rebase or merge after the owner of the local work agrees.

Trade-offs

The hook costs a fetch on first touch, bounded by the timeout. In return the common case, a clean checkout of `main`, needs no thought. The uncommon case, a feature branch that is behind, becomes a sentence in the model's context instead of a surprise at merge time.

Two choices came from caution. First, it prefers saying nothing over guessing: a failed fetch is silent. Second, it does not try to be clever about dirty trees. Untracked files are ignored when deciding whether a tree is dirty, but tracked edits stop the pull.

There is an off switch (FRESH_PULL=off) and a widening switch for repositories outside the organization (FRESH_PULL_ANY=1). I kept the default narrow on purpose: a hook that touches a repository it does not own is a different kind of risk.