feat(context-guard): zone-crossing hooks, token bands, and the workflow continuation router

docs/CATALOG.md

@@ -75,7 +75,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc
 - [`claude-memory`](../plugins/claude-memory) — Keeps a repo's Claude Code memory layer healthy and under your control, against criteria derived from official Claude Code documentation. The audit skill checks the instruction/memory layer (CLAUDE.md, CLAUDE.local.md, .claude/rules/, auto-memory) with a deterministic script-backed spine plus judgment-tier checks. The stateless skill inspects, disables, and (confirm-gated) purges Claude-written auto memory across all settings scopes.
 - [`claude-ops`](../plugins/claude-ops) — Claude Code operations toolkit. Seven skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view — queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort and a repo-pull + marketplace-refresh launch step), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.
 - [`rate-limit-guard`](../plugins/rate-limit-guard) — Shared rate-limit guard for loop lanes: a statusline wrapper tees the subscription rate-limit windows to a fixed machine-scope file, a StopFailure hook records rate-limit stops reactively, and a reader contract fixes how consuming sessions pause and resume.
-- [`context-guard`](../plugins/context-guard) — Per-session context-window observability: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (zones.json SSOT with shipped defaults), and a reader contract fixes how consuming sessions interpret the snapshots.
+- [`context-guard`](../plugins/context-guard) — Per-session context-window observability plus the first shipped consumer: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (percentage bands plus window-class token bands, conservative-min combination, zones.json SSOT with shipped defaults), a reader contract fixes how consuming sessions interpret the snapshots, and zone-crossing hooks inject continuation guidance once per transition into a worse zone (advisory by default; an optional blocking mode gates new mutating work on a fresh dumb-zone snapshot with handoff-writing exempt), with a PostCompact hook persisting an evidence-degraded marker.
 - [`plugin-quality`](../plugins/plugin-quality) — Post-use behavioral audit of Claude Code plugin components: a six-step audit workflow (evidence capture, grounded mapping in a fresh subagent, blindspot pass, interactive contract lock, presence-gated review seams, work-item emit with draft+confirm) over any skill, agent, hook, command, or config you have actually used — zone-informed by context-guard snapshots when present, conservative when not.
 - [`skill-quality`](../plugins/skill-quality) — Skill-authoring QA tooling: a static contract checker that runs twenty-two deterministic checks over a Claude Code skill (frontmatter, per-skill listing-entry cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence, precompute opportunity, injection shell-declaration, fresh-eyes declaration conformance), a shared skill-listing budget reporter across a set of skills, and a bundled evals.json schema for validation. Runs against any repo's skills directory via the convention-resolution ladder — no baked layout.
 

docs/conventions/hook-telemetry/README.md

@@ -180,3 +180,6 @@ producers without coordinating with them or each other.
 | `claude-ops` plugin | `skill-usage-audit` (two producers: PostToolUse/Skill and UserPromptExpansion — see schema) | `data/skill-usage-audit.schema.json` |
 | `claude-ops` plugin | `tool-failure-audit` | `data/tool-failure-audit.schema.json` |
 | `autonomy` plugin | `lane-stop-gate` | `data/lane-stop-gate.schema.json` |
+| `context-guard` plugin | `zone-crossing-inject` (two producers: PostToolBatch and UserPromptSubmit — see schema) | `data/zone-crossing-inject.schema.json` |
+| `context-guard` plugin | `zone-gate` | `data/zone-gate.schema.json` |
+| `context-guard` plugin | `post-compact-mark` | `data/post-compact-mark.schema.json` |

docs/conventions/hook-telemetry/data/post-compact-mark.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/hook-telemetry/data/post-compact-mark.schema.json",
+  "title": "post-compact-mark telemetry data",
+  "description": "Per-hook `data` payload for context-guard's PostCompact evidence-degraded marker hook. Discovered from the envelope `hook` value \"post-compact-mark\". Evolves additive-only.",
+  "type": "object",
+  "required": ["trigger"],
+  "additionalProperties": true,
+  "properties": {
+    "trigger": {
+      "type": "string",
+      "description": "Compaction trigger from the hook payload: \"manual\" (/compact) | \"auto\" | \"unknown\" (absent or unrecognized in the payload)."
+    }
+  }
+}

docs/conventions/hook-telemetry/data/zone-crossing-inject.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/hook-telemetry/data/zone-crossing-inject.schema.json",
+  "title": "zone-crossing-inject telemetry data",
+  "description": "Per-hook `data` payload for context-guard's zone-crossing injection hook (PostToolBatch + UserPromptSubmit — the envelope `hook_event` distinguishes them). Discovered from the envelope `hook` value \"zone-crossing-inject\". Emitted only on a zone transition (either direction); unchanged-zone and unknown runs emit nothing. Evolves additive-only.",
+  "type": "object",
+  "required": ["zone", "injected"],
+  "additionalProperties": true,
+  "properties": {
+    "zone": {
+      "type": "string",
+      "description": "The newly resolved zone word: \"smart\" | \"acceptable\" | \"dumb\" (unknown never emits)."
+    },
+    "previous": {
+      "type": "string",
+      "description": "The last recorded zone word, empty string when this is the session's first recorded observation."
+    },
+    "injected": {
+      "type": "boolean",
+      "description": "true when guidance was injected (transition into a worse zone); false for a silently recorded improvement."
+    }
+  }
+}

docs/conventions/hook-telemetry/data/zone-gate.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/hook-telemetry/data/zone-gate.schema.json",
+  "title": "zone-gate telemetry data",
+  "description": "Per-hook `data` payload for context-guard's blocking-mode PreToolUse gate. Discovered from the envelope `hook` value \"zone-gate\". Emitted only when the gate denies (envelope status \"blocked\"); every allowed or fail-open path emits nothing. Evolves additive-only.",
+  "type": "object",
+  "required": ["zone", "grace", "calls_seen"],
+  "additionalProperties": true,
+  "properties": {
+    "zone": {
+      "type": "string",
+      "description": "Always \"dumb\" — the only zone the gate can deny in."
+    },
+    "grace": {
+      "type": "integer",
+      "description": "The grace budget in effect (zone_gate_grace_calls, in-script default 20)."
+    },
+    "calls_seen": {
+      "type": "integer",
+      "description": "Matched tool calls observed for this session since it entered the dumb zone, including the denied one."
+    }
+  }
+}

plugins/context-guard/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "context-guard",
-  "version": "0.3.0",
-  "description": "Per-session context-window observability: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (zones.json SSOT with shipped defaults), and a reader contract fixes how consuming sessions interpret the snapshots.",
+  "version": "0.4.0",
+  "description": "Per-session context-window observability plus the first shipped consumer: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (percentage bands plus window-class token bands, conservative-min combination, zones.json SSOT with shipped defaults), a reader contract fixes how consuming sessions interpret the snapshots, and zone-crossing hooks inject continuation guidance once per transition into a worse zone (advisory by default; an optional blocking mode gates new mutating work on a fresh dumb-zone snapshot with handoff-writing exempt), with a PostCompact hook persisting an evidence-degraded marker.",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"
@@ -14,6 +14,28 @@
     "tee",
     "zones",
     "context-degradation",
-    "session"
-  ]
+    "session",
+    "hooks"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "userConfig": {
+    "context_guard_hooks_enabled": {
+      "type": "boolean",
+      "title": "context-guard hooks kill switch",
+      "description": "Master switch for the zone-crossing injection, blocking gate, and PostCompact marker hooks",
+      "default": true
+    },
+    "zone_hook_mode": {
+      "type": "string",
+      "title": "Zone hook posture",
+      "description": "advisory (default) injects guidance only; blocking additionally denies new Write/Edit/NotebookEdit/Agent/Workflow calls on a fresh dumb-zone snapshot past the grace budget (fail-open on unknown; handoff-path writes, reads, Bash, and Skill stay allowed)",
+      "default": "advisory"
+    },
+    "zone_gate_grace_calls": {
+      "type": "string",
+      "title": "Blocking-gate grace budget",
+      "description": "Blocking mode only: number of matched tool calls allowed after the session first resolves dumb before the gate denies (in-script default 20)",
+      "default": "20"
+    }
+  }
 }