Skip to content
AndonDocs
GitHub
Change Andon

How a study is kept from pushing

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

A study is a run that answers a question instead of changing code: it reads, runs the app, asks through Needs you and ends with a proposal (Studies). It must never push a branch or open a pull request, whichever agent runs it. Keep every layer below when you change the launch path. The code is apps/agent/src/study.ts, and its header says the same in short.

Three layers

  1. The run contract (apps/agent/src/run-contract.ts, the study contract) has no push lines, and says the run never pushes or opens a pull request. It sits above any repository instruction to push.
  2. Claude Code’s deny rules. STUDY_DENIED_TOOLS go into the run’s settings.json under permissions.deny: git push and gh pr create, merge, ready, edit, close, comment and review. Deny rules win over any allow rule and any permission mode.
  3. Git itself, for every executor. studyGitEnv sets GIT_CONFIG_COUNT and GIT_CONFIG_KEY_n / GIT_CONFIG_VALUE_n in the session’s environment so every push URL is rewritten to /andon-study-runs-never-push/, a path that isn’t a repository. So git push fails with a message that says why, and gh pr create fails the same way because it pushes first. Fetching and reading still work. The rewrite is:
    • url./andon-study-runs-never-push/.pushInsteadOf with an empty value, which covers every URL;
    • the same key once for each remote URL the workspace has at launch (read with STUDY_REMOTE_URL_ARGS), so a person’s own longer pushInsteadOf for that URL doesn’t win;
    • an exact insteadOf for each pushurl, because git doesn’t apply pushInsteadOf to a pushurl.

The third layer has one gap. A push to a URL that is no remote’s, typed in the session, follows a person’s own pushInsteadOf when one covers it (git takes the longest match, and the first of equal ones). There, only the contract and Claude’s deny rules stop it.

Andon’s own pushes skip a study too

The agent pushes on a run’s behalf in three places: the safety net, merging without GitHub and memory proposals. Each acts only on a run that delivers, and for a study noDelivery() (run-contract.ts) answers study. A study is never a PR group, either: not a group of one when it starts, and not a group’s recipe. A person’s own Push branch or Move to machine on the card still pushes: that is their decision, not the run’s.

The mock folder

A study may build a working mock to show in its proposal, but never in the repository. At launch, prepareStudyMock makes the card’s folder, <scratchRoot>/andon-study-mocks/<card id> (studyMockPath), and refuses it if it overlaps the worktree, sits inside any git repository, or is outside the machine’s workspaceRoots. The study then runs without a mock, and the agent’s log says why.

The session gets the folder as an extra directory (Claude and Codex --add-dir, Gemini --include-directories), in $ANDON_STUDY_MOCK, and in a short brief (studyMockBrief): write the mock only there, and show it in the proposal page or as a second page published with publish_output from that folder. It is the only place outside the workspace a run may publish from. The folder belongs to the card, so a follow-up turn keeps building the same mock. When the card reaches Done, the agent moves the folder to the Trash. Nothing from the mock is in the worktree, so there is nothing of it to commit or push.

Tests

apps/agent/src/study.test.ts covers the environment and the mock folder’s checks; apps/agent/test/study.int.test.ts runs a study end to end against a real git remote and the fake gh, and checks that nothing reached either.