agent-control

Portable checkpoint, authorization, correction, and completion controls for Codex, Claude Code, and other hook-capable coding agents.

This is the runtime-control companion to long-running-project-memory:

• project memory owns durable facts, runbooks, plans, transient task state, semantic audits, and history;
• agent control owns exact prompt capture, resumable checkpoints, authorization envelopes, protected-operation manifests, correction handling, urgent overrides, rollback evidence, and terminal completion gates.

Neither package contains application-specific deployment policy. A consuming project supplies protected paths/actions and its own runbooks.

Design boundary

Routine owner-authorized work remains frictionless. Hooks observe ordinary edits and commands without requiring checkpoint or manifest ceremony. Checkpoints are for protected, risky, resumed, or multi-session work.

Protected actions require an exact prepared manifest unless a bounded urgent incident override is active. An urgent override permits immediate repair inside its declared scope, captures before-images and outcomes as it runs, and reconciles deferred bookkeeping at urgent close; it never widens the repair scope or disables destructive-action safety.

The included live-wait gate parses command structure and strips heredoc bodies. Words such as “while” and “until” in prose or file content do not trigger it.

Included

agent-control.json                            Portable policy defaults
template/tools/agent_control.py               Shared checkpoint/control core
template/tools/test_agent_control.py          Core and hook tests
template/.codex/config.toml                   Codex project adapter
template/.codex/hooks.json                    Codex lifecycle hooks
template/.codex/compact-prompt.md             Checkpoint-aware compaction prompt
template/.claude/settings.agent-control.json  Claude hook merge fragment
template/.claude/hooks/live_wait_gate.py      Syntax-aware wait protection
.github/workflows/ci.yml                      Public template validation

Install into a project

From the target repository root:

cp -r /path/to/agent-control/template/. .
chmod +x tools/agent_control.py tools/test_agent_control.py \
  .claude/hooks/live_wait_gate.py
python3 tools/agent_control.py doctor
python3 -m unittest tools.test_agent_control

Merge .claude/settings.agent-control.json into an existing .claude/settings.json; do not overwrite unrelated hooks. Codex reads the repository-owned .codex/ adapter after the project is trusted and the hook hash is reviewed.

Customize agent-control.json:

• protected_paths: file patterns that require a prepared manifest;
• protected_command_patterns: shell patterns for production, destructive, external-system, or other-process operations;
• terminal_event_required: whether claimed checkpoints may stop without a terminal event;
• urgent_override.enabled: whether bounded incident mode is available.

Typical protected workflow

python3 tools/agent_control.py checkpoint create \
  --task release-fix --session-key SESSION --prompt 'Fix the live regression now' \
  --objective 'Restore the failing endpoint' --next 'Inspect the failure' \
  --scope 'src/**'

python3 tools/agent_control.py checkpoint claim \
  --task release-fix --session-key SESSION

python3 tools/agent_control.py envelope \
  --task release-fix --action deploy --target production --target 'src/**'

python3 tools/agent_control.py manifest \
  --task release-fix --session-key SESSION --tool Bash --action deploy \
  --target production --command './deploy.sh'

For a live incident:

python3 tools/agent_control.py urgent begin \
  --task release-fix --session-key SESSION \
  --reason 'Active users cannot search' --scope 'src/search/**' \
  --scope 'command:./deploy.sh'

# repair and verify immediately

python3 tools/agent_control.py urgent close \
  --task release-fix --verification 'Live search returned expected results'

Non-goals

• No automatic deployment decisions.
• No project-specific Git preflight or database repair.
• No static memory or changelog system.
• No blocking of routine corrections while bookkeeping catches up.
• No bypass for destructive operations outside an urgent override’s exact authorized scope.

MIT licensed.