context-checkpoint

name	context-checkpoint
description	Use when task completion or context usage requires a handoff readiness check
user-invocable	false

Context Checkpoint

Overview

Monitor context consumption and trigger proactive handoff before quality degrades. Called after every task completion in executing-beads.

Core principle: Better to hand off early than to lose context and produce bad work.

How It Works

Layer 1 — Native context awareness (always present). Codex Sonnet 4.5+, Sonnet 4.6, and Haiku 4.5 receive context state after every tool call:

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

No hook needed — workers already know their context state from system_warning. Thresholds are loaded from thresholds.json at the project root:

Model	Soft threshold	Hard threshold
Opus	65%	85%
Sonnet	50%	70%
Haiku	40%	60%

Source of truth: thresholds.json.

The Go worker enforces the hard stop as a backstop: if the agent does not respond to the soft threshold, handleContextThreshold sends a handoff and kills the subprocess at hard threshold (soft + 20%).

Quality Signals (Override Token Count)

These symptoms indicate context degradation regardless of token usage — treat as immediate handoff:

• Repeating yourself — suggesting something already tried or discussed
• Forgetting earlier context — asking about decisions already made
• Hallucinating paths — referencing files or functions that don't exist
• Growing confusion — needing to re-read files you already read

Checkpoint Protocol

Green (Continue)

system_warning shows usage well below soft threshold. Proceed to next task.

Soft Threshold Breached

Finish your current atomic step (complete the file edit, run its verification, record the result). Then:

• Do NOT start another edit-verify cycle.
• Follow handoff steps below.

Hard Threshold Breached

Stop after your very next tool call. Write a minimal handoff (goal + files modified + next steps). Any in-progress work will be captured by the compaction safety net.

Handoff Steps

1. Close current task if work is complete
2. For in-progress work: oro task update <id> --notes "Partial: <what's done, what remains>"
3. Verify remaining work exists as tasks (create if needed)
4. Use create-handoff skill with tasks: section
5. git pull --rebase && git push
   • Note: The pre-commit hook automatically syncs task metadata, so manual sync is not needed

Handoff Template Addition

When handing off due to context checkpoint, add tasks: section to handoff YAML:

tasks:
  completed: [oro-xxx, oro-yyy]
  in_progress: [oro-zzz]
  remaining: [oro-aaa, oro-bbb]
  epic: oro-www

Red Flags

• Ignoring hook messages and starting new tasks
• Skipping checkpoint after task completion
• Not saving in-progress state before handoff
• Producing a handoff without the tasks: section
• Rationalizing "just one more task" after handoff message