简体中文 | Introduction | Changelog
Context Guard keeps important requirements from disappearing during a long Codex task. It restores a private checklist when a task is compacted or resumed, and checks recorded evidence before accepting a completion claim.
It works beside Codex Plan, Goal, memories, subagents, worktrees and the transcript. Ordinary edits, commits and pushes use Codex’s existing permissions.
Current version: 0.15.1 — 2026-10-05. Explicit resumes release ordinary pauses while preserving unfinished work; later user messages can pause again. Diagnostic status queries verify applicable sources without private writes. Bounded native macOS/Windows acceptance passed. Public availability is determined by the GitHub Release readback; see release notes and upgrade boundaries before changing an installation.
Requirements: Python 3.10 or newer, Codex CLI, and a Codex surface that loads plugins and lifecycle Hooks. The 0.15.1 acceptance batch targets Codex CLI 0.160.0; earlier CLI versions are not retested for this release. See compatibility for completed and pending checks.
git clone https://github.com/GreenLv/codex-context-guard.git
cd codex-context-guard
python3 scripts/manage_plugin.py --applyOn Windows:
py -3 scripts\manage_plugin.py --applyThe installer adds this repository as a marketplace, installs context-guard@codex-context-guard, and verifies the installed copy. It also keeps versioned copies needed by tasks that started before an upgrade.
Installing a plugin does not trust its Hooks automatically. Start a fresh Codex task, open /hooks, review and trust all nine definitions, then start another fresh task so it loads the current version.
Copy this prompt into a Codex task:
Install Context Guard from https://github.com/GreenLv/codex-context-guard
at its latest published stable release. Use this README's safe installer
and the normal Codex client. Detect my platform and verify Python 3.10+.
Follow the upgrade notes; preserve unrelated settings and existing versioned caches.
Verify the release source, installed version, source/cache parity and
fresh-task Hook loading. If Codex asks for Hook trust, guide me through
its normal confirmation once, then continue verification. Never edit trust
hashes or bypass trust. Tell me if a new task or client restart is needed.
Before upgrading to 0.15.1, verify its published Release. Here, HOME means Codex’s configuration and task-data directory, selected by CODEX_HOME. Finish old tasks before changing their HOME’s selected plugin, or keep an independent HOME explicitly on the original version while new work uses a fresh HOME. Keeping an old cache alone does not pin its Hooks: Codex may select the new version on the next turn. This release does not migrate old task state.
Use the managed installer and check the installed-version readback. Review and trust all nine Hooks in a fresh task, then start another task to load the new version. Do not overwrite consumed caches. See session storage and upgrades for the separate-HOME route and compatibility for tested limits.
If the required Python interpreter and managed cache are both unavailable, Context Guard stops with a reinstall hint. Version history is in the changelog; current behavior and platform limits are in compatibility. The 0.12.4 baseline is historical.
In a fresh task, activate Context Guard:
$context-guard
Then inspect the protected state:
context-guard status
context-guard diagnose
For a recovery check, use it on a non-trivial synthetic task, run /compact, and confirm that the same open requirements return immediately afterward.
For a worked example, follow the Context Guard walkthrough on HOL: define a document’s requirements, compact the task, then check the recovered requirements and finished document.
- Requirements, acceptance criteria, prohibitions, and later corrections keep stable task-local identities.
- Compaction and resume restore the open checklist instead of relying only on a conversational summary.
- Successful tool evidence must match the named file, URL, image, or other requested result before it can close an item.
- A delivered answer is not a completed task. A natural answer actually delivered to a pure question closes that item as
answeredand never replays after compaction; an execution obligation always needs evidence; an unknown delivery state is never presented as completion. - Images and other multimodal inputs keep only hashes and bounded metadata. When the user asks for an image change, completion evidence can be tied to an inspection of the changed image rather than merely to a successful tool call.
- Ambiguous output remains
unknown; damaged or unverifiable private state blocks completion verification. - Exports are explicit and redacted. Image bytes, credentials, and raw transcript content are not copied into the requirement ledger.
Automatic checks are used only when the request names a concrete target, such as a file, URL, edited image, or complete object list. If Context Guard cannot verify a result exactly, it leaves the item open instead of guessing. Waiting for the user, an external result, or a later turn does not close unfinished requirements.
- You decide the task and which changes are allowed.
- Repository instructions and selected Skills define the adopted workflow, but cannot grant new authority.
- Codex Plan describes the model's current steps; Context Guard can keep a read-only reference but does not edit the plan.
- Tool, file, image, UI, and public-page readbacks establish facts. They do not by themselves decide whether an action is authorized.
From version 0.13 the responsibilities split like this:
- You and the executing agent decide execution. Whether an edit, commit, push, tag, or publication is within your authorization is judged by the main executing agent from the real conversation, repository rules, and host permissions — not by a Context Guard prompt. A Context Guard allow was never authorization, and the product now says so explicitly.
- Context Guard owns correctness continuity. It recovers requirements and constraints across compaction and resume, keeps task state continuous, checks completion claims against matching deterministic evidence, tracks whether a requested answer was actually delivered, and protects its own private control state. These checks are fail-closed and never ask you to re-authorize ordinary work.
- An explicitly adopted release execution contract owns precise identity actions. Only after an explicit adoption or an explicit
context-guard releasedeclaration do tier-A actions — tags, registry publish/yank, GitHub Releases — require an exact one-shot action ticket.
Context Guard does not grant permissions or replace platform approval, and specialized tools outside Hook coverage remain outside its view.
Context Guard's checks follow the active protection level. Skills, repository instructions, or installing the plugin can suggest a level, but only you can turn on a stricter one.
| Level | How it turns on | What it does |
|---|---|---|
| Standard (default) | Activating the guard | Recovers your requirements after compaction and resume, keeps task state continuous, checks completion honestly against deterministic evidence, and tracks answer delivery. No execution approvals and no repeated authorization asks: ordinary edits, commits, pushes, status questions, and compaction never trigger a Context Guard prompt. |
| Strict | You explicitly ask for strict evidence protection | Standard, plus enforced proof obligations for the current work unit — useful for formal deliverables and multi-image work. Strict never implies release or Git gating. |
| Release | Only an explicitly adopted release execution contract or an explicit context-guard release declaration |
Standard, plus candidate-closure, publication-readiness, and exact one-shot tickets for covered tier-A identity actions (tags, registry publish/yank, GitHub Releases). Having a tag or release authorized never follows automatically from anything else. |
| Observe | Maintainer or canary configuration | Records bounded what-it-would-have-done results, without blocking anything. |
Everything else stays open by design: local edits, tests, ordinary commits, reads, searches, and dry-runs need no additional Context Guard approval, and turning the guard off stops all gating while prompt journaling continues. When a normal action is allowed, nothing appears on screen; when an action is refused — a release-contract ticket failure or an integrity failure — you get one short actionable reason.
flowchart TB
A["You give Codex a task<br/>requirements · prohibitions · acceptance checks"]
B["Context Guard keeps a private checklist<br/>and records later corrections"]
C["Codex works normally<br/>files · tools · tests · subagents"]
D["After /compact or resume<br/>the open checklist is restored"]
E{"Does every open item have<br/>matching successful evidence?"}
F["No · continue work<br/>or report the blocker"]
G["Yes · allow normal completion"]
A --> B --> C --> D --> E
E -->|No| F
E -->|Yes| G
Codex still owns the work and its native planning state. Context Guard carries the checklist across context boundaries and, when project instructions have been adopted explicitly, restores their unfinished phases and plan reference before checking completion.
Suppose the task is:
Write docs/design/checkout-v2.md.
- Keep the approved API and data-flow decisions unchanged.
- Do not change the rollout date or add infrastructure commitments.
- Follow the RFC template.
- Give every recommendation a source link or a "to verify" label.
After research, edits, diagrams, and /compact, Context Guard restores those same items. A passing Markdown check cannot close the whole task: the approved decisions, RFC template, source links, and prohibited commitments each still need matching evidence.
This example explains the contract boundary; it does not claim that Context Guard can decide whether the design itself is sound.
The same boundary applies to routine execution. After you say “finish the changes, commit and push” (完成修改，提交并推送), ordinary edits, commits, pushes, status questions, and compaction proceed without any Context Guard re-authorization, before and after a /compact. A reply that claims the whole task is complete still needs matching evidence for everything still open.
| ID | Meaning |
|---|---|
R001 |
A requirement captured for this task. |
A003 |
An acceptance item checked independently. |
E#### |
A successful evidence record that may close a compatible item. |
These are task-local identifiers, not GitHub issues or global task numbers. They may appear in progress text but the private ledger is not printed in the final reply.
When an open requirement still lacks matching evidence and the reply claims the whole task is complete, Context Guard may ask Codex to continue with this standard redacted message:
[Context Guard continuation] The task is not yet safely complete.
The message is normal when requested work is still open. If it is unexpected, ask Codex what remains and run context-guard status or context-guard diagnose. The default feedback names only the current work unit's pending-item count, one reason, and one next step — never the full historical ID list — and a turn can be corrected at most once; after that, unresolved work stays pending and the turn ends safely. Waiting for the user, an external result, or an explicitly deferred step ends the turn silently without closing unfinished requirements. Ordinary endings need no commands: when a reply verifiably completes the unit, the guard binds the unique successful evidence itself.
An old task is not guaranteed to keep its original Hook after an in-place upgrade. Follow session storage and upgrades before switching versions; if an old Hook path is missing, see Versioning for recovery guidance.
| Command | Purpose |
|---|---|
$context-guard or context-guard on |
Activate recovery and completion gating. |
context-guard off |
Disable gating while preserving prompt journaling. |
context-guard standard|strict|release|observe |
Select a protection level explicitly; release does not authorize a publication action. |
context-guard adopt <project-relative-json> |
Explicitly adopt one validated project execution contract. |
context-guard status |
Show protected-state counts without raw prompts. |
context-guard diagnose |
Show bounded diagnostics without raw prompts or replies. |
context-guard export <path> |
Write an explicit redacted handoff in the current project. |
context-guard rollover <directory> |
Validate prepared successor input and write a non-overwriting handoff plus hash manifest. |
Read Successor Pack Input before using rollover. It never creates or authorizes another task.
Runtime data is stored under Codex-managed PLUGIN_DATA. Prompt bodies, task state, evidence summaries, and recovery files remain local runtime data and are not part of this repository.
In 0.15.1, ended v2 sessions with no resumed activity are eligible for cleanup after 30 days; legacy session trees are retained. Redacted exports are created only when requested and omit raw prompts, transcripts, credentials, authorization headers, URL query values, and plugin-private paths. See Privacy.
Before updating a HOME with unfinished tasks, follow the upgrade notes.
git pull --ff-only
python3 scripts/manage_plugin.py --applyPlugin source changes require a version bump. Historical caches and trusted archives remain available to tasks that already loaded them.
codex plugin remove context-guard@codex-context-guard
codex plugin marketplace remove codex-context-guardRemoving code does not remove private runtime data. Keep old data or caches while an active task may still depend on them.
python3 scripts/validate_public_repo.py .
python3 scripts/audit_public_tree.py .
python3 scripts/run_current_behavior_suite.py
python3 scripts/check_phase3_transition.py
python3 scripts/context_guard.py self-test
ruff check .
python3 -m compileall -q scripts tests tools
git diff --checkThe current-behavior runner discovers every current test_*.py module except the byte-frozen 0.11.x observation baseline. The transition audit runs that historical baseline separately and succeeds only when its exact fixed/inverted manifest matches; running the frozen file as an ordinary all-pass suite would intentionally report failures and unexpected successes.
The Hook runtime uses only the Python standard library. CI covers Ubuntu, macOS, and Windows on Python 3.10–3.14; CI does not substitute for native Hook trust or installed lifecycle evidence.
- Context Guard checks only results it can verify deterministically. It cannot establish that arbitrary text or images are correct, and it does not replace tests or human review.
- It provides no security sandbox, transcript backup, cloud sync or agent scheduling. Codex continues to own Plan, Goal and execution.
- It grants no permissions. Publication still needs release-readiness checks, user and host authorization, and public readback.
Its recovery and completion contract does not depend on a model or agent host providing its own context protection. The architecture explains the protocol and Codex adapter.
Only the user who started the root task can adopt project workflow and plan references with context-guard adopt <project-relative-json>. Adoption leaves Codex Plan unchanged and grants no authority. Installing a Skill or mentioning a plan does not adopt it. Release controls require explicit selection, as described above.
See CONTRIBUTING.md. Report sensitive issues through GitHub Private Vulnerability Reporting as described in SECURITY.md.
Licensed under the Apache License 2.0.