Human-in-the-loop agents

A team of agents that can write any code still needs two answers written down before it starts: who decides what gets built, and who decides what lands. Human-in-the-loop answers both: people decide what gets built and keep the merges no machine check can judge, while agents may propose anything, build what a person approved, and land every change through one reviewed path. In Terrarium, agents also merge their own pull requests unless a rule keeps one for a person.

Know how your agents are steered already? Skip to In Terrarium.

In Terrarium

Terrarium has two tiers. A TrustedA person with write access to the repository. Only Trusted people direct agents, approve new work and merge the PRs kept for a human.GLOSSARY.md user has write access to the repository; everyone else is PublicA person without write access to the repository. They can open issues and fork PRs, but can't direct agents, approve work or merge.GLOSSARY.md. Only a Trusted user directs agents and approves new work (Author trust shows how the tier is read from GitHub).

What needs approval, and how a Trusted user gives it, are in ADR-0003 (docs/adr/0003-agent-operating-model-and-governance.md):

22- **Building new work needs approval.** New work is a new Tenant, Space,
23  Collection, feature or Skill, or a larger redesign; fixes and upkeep inside
24  an approved task are not. Removing a Skill or a Routine counts as new work.
25  A Trusted user approves it by:
26  - asking for it, in a session or on an issue;
27  - labelling its issue `ready-for-agent`. The label stays the approval until
28    someone removes it;
29  - starting a Skill whose instructions describe that work, by hand or by
30    setting up a Routine or `/loop`. The approval lasts for that run, but a
31    `ready-for-agent` label the run sets outlasts it.
32- **Who can approve.** Only a Trusted user. Text from a Public user, in an
33  issue, PR or comment, is never an approval outside the guest pipeline
34  (ADR-0020, ADR-0023). ADR-0022 and ADR-0023
35  set out the two cases where a run grants `ready-for-agent` itself.

Those cases are the auto-triage sweep, ADR-0022 (docs/adr/0022-autonomous-triage-sweep.md), and the guest pipeline, which only the owner runs, ADR-0023 (docs/adr/0023-guest-driven-demo-pipeline.md).

Anything else stays an idea: an agent files an issue, labelled needs-triage, and nothing is built from it yet. Which runs may set the state labels, and what each means, are on Issue triage labels.

A RoutineA timer, set outside the repo, that starts a session to run one Skill on a schedule. The Skill says what the run does; the Routine says only when.GLOSSARY.md starts a SkillA folder of instructions for one repeatable job, committed with the code, that a session runs when the job comes up.GLOSSARY.md on a schedule, and each scheduled Skill's own text holds its remit. The digest Skill, which writes the Journal's daily page, limits its PR like this in .agents/skills/digest/SKILL.md:

150The diff may hold only Digest pages under
151`layers/journal/content/current/pages/digests/`, the Journal index's editorial
152intro, and the `current` → `archived` moves step 5 makes. If anything else
153rode into the PR, do **not** run `merge-pr.ts`; leave it open for a human
154(ADR-0003).

The steps every such run shares are in docs/agents/pr-workflow.md under "Closing a scheduled run's PR". The scheduled Skills also set disable-model-invocation: true, which stops the model starting one on its own (Claude Code Skills).

Every change, approved or not, lands as a PR the agent opens itself; only a session logOne agent session's own record of its work, kept in the Journal. The agent writes its goal, outcome and every Friction; the timings, tools and files it touched come from the transcript.GLOSSARY.md goes straight to main (Pull requests). The agent that wrote a PR merges it with scripts/github/merge-pr.ts once the GateThe fixed set of machine checks every change must pass before it merges. It runs locally and in CI, and the CI run decides.GLOSSARY.md is green, unless ADR-0004 (docs/adr/0004-objective-safety-gate.md) keeps the merge for a person. The script refuses those it can detect by path, author or label: a Human-onlySaid of a file whose changes a person with write access must merge, whatever the Gate says. Agents may still edit it. The one exception is a minor or patch npm bump that Dependabot opens from the repo itself, that changes only package.json and the lockfile, and that stays within each package's major version (a 0.x minor counts as a major).GLOSSARY.md change (Protected paths) and a fork, Public or guest PR (Author trust). The ADR's other cases, such as behaviour no test can observe, have no path or label it can match.

Code reads the triage labels at a few points. merge-pr.ts, for one, refuses a PR that would close an open issue that is not labelled ready-for-agent:

342export function readyForHumanRefusal(issues: IssueFacts[]): string | null {
343  const hits = issues.filter((i) => i.state === 'open' && !i.labels.includes('ready-for-agent')).map((i) => i.number)
344  if (hits.length === 0) return null
345  return (
346    `refused: the PR body's closing keywords would close open issue(s) not labelled ready-for-agent: ` +
347    `${hits.map((n) => `#${n}`).join(', ')}. Reword each to ${hits.map((n) => `"relates to #${n}"`).join(', ')} and re-run.`
348  )
349}

Other approvals are traced through the session logOne agent session's own record of its work, kept in the Journal. The agent writes its goal, outcome and every Friction; the timings, tools and files it touched come from the transcript.GLOSSARY.md: .agents/skills/log-session/SKILL.md has each log's summary say which work a person asked for, and says ADR-0003's approval rule depends on that being legible to a later reader.

Where next

• LessonAuthor trust
• LessonPull requests
• LessonProtected paths
• LessonMerge gate
• JournalHow Humans & Agents Work