Context Guard

What It Does

Hooks and a quality rule to keep AI context files in sync with the codebase. Prevents content filter errors on standard OSS files. Two-tier enforcement for context doc freshness.

Primary platform: Claude Code (full automation, 12 hook events). Other platforms with hook support — Gemini CLI (11 events), Copilot (8, preview), Cursor (4+), Cline (3) — can use adapted hooks from platforms/ packages (coming soon). For platforms without hooks (Codex CLI, OpenCode, Windsurf), use bin/context-verify.sh as a manual or CI-based alternative.

Enforcement Tiers

Default: Tier 1 only. Add Tier 2 with install strict.

Components

content-filter-guard.sh (PreToolUse → Write)

• HIGH-risk (CODE_OF_CONDUCT.md, LICENSE, SECURITY.md): blocks write, returns fetch commands for canonical URL
• MEDIUM-risk (CHANGELOG.md, CONTRIBUTING.md): allows write, advises chunked writing
• All other files: passes through silently

context-structural-change.sh (PostToolUse → Write|Edit)

Fires after creating/editing structural files. Reminds which context files may need updating:

• commands/*.md, .claude/skills/*/SKILL.md, .agents/skills/*/SKILL.md → update AGENTS.md first, then CLAUDE.md, llms.txt, and any affected bridge files
• .claude/agents/*.md, .agents/agents/*.md → AGENTS.md, llms.txt
• .claude/rules/*.md → AGENTS.md and CLAUDE.md if rule references changed
• Config files (package.json, pyproject.toml, etc.) → update AGENTS.md first, then only the bridge files with tool-specific command/tooling notes

If your repository uses the .agents/ layout instead of .claude/, apply the same AGENTS-first update order to the equivalent skill and agent paths above.

context-drift-check.sh (PostToolUse → Bash)

Fires after git commit. Compares context file last-modified commit vs most recent source commit. Detects broken path references. Throttled to max once per hour via .git/.context-guard-last-check.

context-guard-stop.sh (Stop — Tier 1)

Fires on session end. Checks for uncommitted structural changes without context updates. Returns {"decision": "block"} if drift detected. Checks stop_hook_active flag to prevent infinite loops.

context-commit-guard.sh (PreToolUse → Bash — Tier 2)

Fires before git commit. Checks staging area for structural files without context files. Exit 2 blocks the commit.

context-session-start.sh (SessionStart)

Fires at session start. Quick context health check: counts context files, detects stale files (source commits ahead), warns if aggregate line count exceeds budget. Advisory only — cannot block session start.

context-forced-eval.sh (UserPromptSubmit)

Fires on every user prompt. Checks for context-related keywords and injects a skill evaluation sequence that instructs Claude to evaluate and activate ContextDocs skills before responding. Keyword-gated to avoid overhead on unrelated prompts. Advisory only — never blocks.

context-updater agent

Autonomous agent (.claude/agents/context-updater.md) launched by Claude in response to hook output. Applies surgical, incremental context file updates. Uses .git/.context-updater-running flag for loop prevention.

Installation

/contextdocs:context-guard install (Tier 1): copies hooks to .claude/hooks/, agent to .claude/agents/, rule to .claude/rules/, merges config into .claude/settings.json.

/contextdocs:context-guard install strict (Tier 1 + 2): adds context-commit-guard.sh and its PreToolUse Bash entry.

Settings.json

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write", "hooks": [{ "type": "command", "command": ".claude/hooks/content-filter-guard.sh" }] },
      { "if": "Bash(git commit*)", "hooks": [{ "type": "command", "command": ".claude/hooks/context-commit-guard.sh" }] }
    ],
    "PostToolUse": [
      { "if": "Bash(git commit*)", "hooks": [{ "type": "command", "command": ".claude/hooks/context-drift-check.sh" }] },
      { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": ".claude/hooks/context-structural-change.sh" }] }
    ],
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": ".claude/hooks/context-session-start.sh" }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": ".claude/hooks/context-forced-eval.sh" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": ".claude/hooks/context-guard-stop.sh" }] }
    ]
  }
}

The PreToolUse if: Bash(git commit*) entry for context-commit-guard.sh is only added with install strict (Tier 2).

if: vs matcher: — Claude Code v2.1.85 added if: (permission-rule syntax, e.g. Bash(git commit*)) so hooks fire only on matching bash commands. Older versions ignore unknown if: — the in-script substring guards keep both safe. Use matcher: "Bash" when the hook needs every Bash invocation.

Uninstallation

/contextdocs:context-guard uninstall removes all hook scripts, the context-updater agent, settings.json entries, and the quality rule.

Troubleshooting

Untether Compatibility

When running via Untether (Telegram bridge), context-guard-stop.sh checks UNTETHER_SESSION env var and exits immediately — Stop hook blocks would displace user content in Telegram output. All other hooks (drift check, structural reminders, content filter, commit guard) work normally. If you don't use Untether, this has no effect.

Hook System Reference

For the complete hook event catalogue (17 events), handler types (command, http, prompt, agent), advanced features (async, once, timeout, matcher, updatedInput, CLAUDE_ENV_FILE), and settings.json schema, load the companion reference: SKILL-reference.md