# 🛡️ Canon Boundary Guard

Canon Boundary Guard is a Codex plugin that packages a provenance-boundary skill and an optional hook bundle.

It helps Codex keep project evidence, chat context, operator instructions, working hypotheses, and model assumptions in separate cognitive layers during a session.

The older standalone skill layout is preserved in the standalone-skill-v1 branch.

🔎 What It Does

Codex often works with several kinds of information at the same time:

• files already in the project
• messages from the current conversation
• instructions that tell Codex how to behave
• runtime context shown at the start of a session
• assumptions that come from the model itself

Canon Boundary Guard gives Codex a compact classification frame for those sources.

The goal is not only to protect file edits. The frame is meant to stay useful while Codex reads, reasons, decides, restructures, and eventually writes persistent project content.

⚠️ Why It Exists

When Codex works on a repository, it reads more than files.

It may also use conversation history, runtime context, tool output, instructions, compressed summaries, and model assumptions.

Those sources do not have the same authority.

A project file is not the same thing as a temporary chat message. An instruction for Codex is not the same thing as content that belongs in the repository. A model assumption is not the same thing as verified evidence.

Canon Boundary Guard exists to keep those boundaries visible while Codex reasons, decides, and eventually writes persistent project content.

🧩 AGENTS.md Authority

In some Codex environments, such as editor-integrated sessions, AGENTS.md instructions may appear at the start of the conversation as a visible user-role message before the operator's real first request.

That display role is not enough to decide authority.

The block may refer to the current working directory, even when the actual instruction source is global, such as an AGENTS.md stored in Codex home.

Canon Boundary Guard includes a countermeasure for this case: a leading block starting with AGENTS.md instructions for <path> is treated as Codex runtime instruction-chain material, not ordinary chat and not repository content.

When this distinction matters, verify the authority layer before using the block as project evidence or writing it into persistent files.

📦 Install

Canon Boundary Guard is installed as a Codex plugin.

It is not installed like an old standalone skill.

1. Add this repository to Codex:

codex plugin marketplace add XxYouDeaDPunKxX/canon-boundary-guard-codex

2. Open Codex and open the plugin picker or plugin list. In Codex UIs that support slash commands, you can use:

/plugins

3. Install or enable Canon Boundary Guard.

4. Start a new thread.

5. Ask Codex to use it:

Use Canon Boundary Guard for this session.

For the hook to work, enable plugin hooks in your Codex config:

[features]
hooks = true
plugin_hooks = true

Then restart Codex. If your Codex UI exposes a hook review view such as /hooks, use it to review and trust the bundled hook. In editor integrations where /hooks is not available, open the plugin details or approve the hook when Codex shows the trust prompt.

The hook is recommended, but the skill can still be used without it.

If you prefer the older manual setup, use the standalone-skill-v1 branch and copy the canon-boundary-guard/ folder into your Codex skills directory.

▶️ Use

Use the plugin when a session depends on keeping old context, current instructions, external information, working hypotheses, model assumptions, and project evidence separate.

Use Canon Boundary Guard for this session.

You can also call the bundled skill directly:

Use $canon-boundary-guard for this session.

🤖 AI-Assisted Development

This project was developed with AI assistance.

The project, documentation, and repository materials were shaped through human-directed work supported by AI tools during drafting, structuring, review, and refinement.

AI assistance does not make the project automatically correct, complete, or suitable for every use case. Read it, test it, and adapt it to your own context.

📜 License

This project is licensed under CC BY-SA 4.0: Creative Commons Attribution-ShareAlike 4.0 International.

See LICENSE.

⚙️ Technical details

This section is for readers who want to inspect the actual operating model behind the plugin. It uses the skill's internal terms directly.

🧱 Plugin Structure

.agents/
`-- plugins/
    `-- marketplace.json
plugins/
`-- canon-boundary-guard-codex/
    |-- .codex-plugin/
    |   `-- plugin.json
    |-- hooks/
    |   `-- hooks.json
    `-- skills/
        `-- canon-boundary-guard/
            |-- SKILL.md
            |-- agents/openai.yaml
            |-- references/frame.md
            `-- scripts/inject_frame.py

• .agents/plugins/marketplace.json exposes the plugin to Codex as a marketplace entry.
• plugins/canon-boundary-guard-codex/.codex-plugin/plugin.json identifies the plugin and points Codex to bundled skills and hooks.
• plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/SKILL.md defines the full operating frame.
• plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/references/frame.md contains the compact frame emitted by the hook script.
• plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/scripts/inject_frame.py reads the compact frame and emits a hook payload.
• plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/agents/openai.yaml contains Codex-facing skill metadata.
• plugins/canon-boundary-guard-codex/hooks/hooks.json wires the frame into PreToolUse for matched write tools when plugin hooks are enabled.

🧠 Operating Posture

The skill is designed to keep source classes separate throughout the session, not only at write time.

The frame should affect reading, analysis, planning, conflict detection, and persistence decisions. The hook only re-surfaces the compact frame near matched write tools.

🧬 Provenance Layers

Canon Boundary Guard uses six source classes. They do not decide whether something is true by themselves. They describe where the material came from and whether it can safely become persistent project content.

• L0 EVIDENCE: project files, git state, tests, schemas, lockfiles, diagnostics, command output, or verified tool output.
• L1 SHAPING: conversation material not approved for persistence.
• L1A AUTHORIZED DELTA: operator-approved material for the current turn, before it is written.
• L2 AGENT CONTROL: instructions that shape agent behavior, not project content.
• L2A CODEX INSTRUCTION CHAIN: AGENTS guidance and runtime instruction-chain material.
• L3 MODEL PRIOR: unverified model memory, assumed conventions, generic best practice, or unstated framework behavior.

Non-L0 material is tagged only when the output would change if the source changed.

The important boundary is persistence. L1, L2, L2A, and L3 can shape how Codex works, but they should not silently become repository content. L1A can be written only inside the scope approved by the operator. L2 and L2A require an explicit request for agent-facing instructions before they can be persisted.

🧩 AGENTS.md Prelude

A leading user-role block starting with:

AGENTS.md instructions for <path>

is classified as L2A runtime instruction-chain material.

It is not operator chat, not project content, and not dependent on filesystem confirmation. If it contains an <environment_context>...</environment_context> block, that block is runtime metadata.

The first operator request starts after this prelude.

🔁 Hook Injection

plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/scripts/inject_frame.py is intentionally small. It reads plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/references/frame.md, strips surrounding whitespace, and emits JSON for a Codex PreToolUse hook:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "<contents of plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/references/frame.md>"
  },
  "systemMessage": "<contents of plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/references/frame.md>"
}

The hook is highly recommended for sessions where repository content, project rules, protocols, naming, workflows, or AGENTS.md authority may matter. It is intended for matched write tools, for example apply_patch, Write, or Edit.

The hook is not the core mechanism of the skill. It is a reinforcement point that re-surfaces the compact frame before matched write tools.

In current Codex runtimes, some edits may be applied through internal file-change paths that do not expose a visible hook event. Treat the hook as a best-effort reinforcement layer, not as complete enforcement.

The frame is injected as hookSpecificOutput.additionalContext, which is the model-visible context path for PreToolUse. The same frame is also surfaced as a systemMessage so the hook activity remains visible in the UI or event stream.

It does not block the tool call, rewrite the requested operation, or decide project policy. Its job is to put the classification frame back into the instruction stream at the moment a write may happen.

🪝 Plugin Hook Setup

The plugin manifest points to:

plugins/canon-boundary-guard-codex/hooks/hooks.json

The default hook configuration is:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "apply_patch|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python ${PLUGIN_ROOT}/skills/canon-boundary-guard/scripts/inject_frame.py",
            "timeout": 5,
            "statusMessage": "Provenance frame"
          }
        ]
      }
    ]
  }
}

Codex hooks use hooks as the canonical feature key. Plugin-bundled hooks are off by default in this release. Enable both with:

[features]
hooks = true
plugin_hooks = true

After installation or hook changes, restart Codex. If your Codex UI exposes a hook review view such as /hooks, use it to review and trust the bundled hook. In editor integrations where /hooks is not available, open the plugin details or approve the hook when Codex shows the trust prompt. Plugin hooks are non-managed hooks and do not run until trusted.

If your system requires python3 instead of python, adjust the hook command in your local plugin copy or configure an equivalent hook in your Codex config.toml.

🧯 Fallback Behavior

If plugins/canon-boundary-guard-codex/skills/canon-boundary-guard/references/frame.md is missing, the hook script still emits a systemMessage:

Canon Boundary Guard frame missing: provenance protection degraded.

This keeps the failure visible without blocking execution.

That fallback is deliberate: the skill should not make normal work impossible because a local file is missing, but it should also not fail silently.