/refine is how you trigger a refinement pass.
What a refinement pass does
When you run/refine inside a session, the harness:
- Reads the trajectory — the messages, tool calls, and outcomes of the current run.
- Extracts evidence — what worked, what didn’t, and what patterns the model reached for repeatedly.
- Proposes updates to supplemental state, backed by concrete evidence pointers.
- Snapshots the previous state so any change can be rolled back.
- Applies the update to supplemental state only. The base system prompt is never touched.
Why the base prompt is immutable
The base prompt is the contract: it defines what the agent is, what tools it has, what invariants it must uphold. Rewriting it makes behavior drift unrecoverably. Refinement adds layered guidance on top instead — you can inspect it, roll it back, or throw it away.Rollback
Every/refine pass writes a snapshot. If a refinement made things worse, roll back to the previous snapshot and try again.
Compaction is the sibling mechanism
Refinement updates guidance. Compaction trims context. When a session grows too long for the model’s context window, the compaction pipeline (compact, calculateContextTokens, prepareBranchEntries) produces a shorter transcript that keeps the important entries. See Sessions for the storage side and Refinement guide for how to use /refine in practice.