@ictechgy/context-guard 0.4.12 → 0.4.14

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes for the ContextGuard plugin are documented here.
 
 ## [Unreleased]
 
+## [0.4.14] - 2026-07-10
+
+- Added the default-off `semantic-checkpoint` experimental planning gate with deterministic readiness payloads, explicit scope/metric/rollback validation, prompt-cache caveats, and hosted-savings claim boundaries.
+- Documented semantic-checkpoint as a plan-only roadmap lane across README/plugin materials and updated the experimental token-reduction radar.
+- Expanded regression coverage for semantic-checkpoint validation, preview truncation, config isolation, and plugin copy synchronization.
+
+## [0.4.13] - 2026-06-22
+
+- Kept the Bash rewrite hook stdout JSON-parseable while routing sanitizer-worthy read-only pipelines through `context-guard-sanitize-output`.
+- Preserved fail-closed handling for side-effecting shell operators, redirections, here-strings, `tee`, network commands, environment-prefixed filters, and file-reading/writing filter options.
+
 ## [0.4.12] - 2026-06-22
 
 - Published the post-merge README, Korean README, and GitHub Pages copy polish into the npm/package metadata so package consumers see the same setup, packaging, helper-trust, and conservative savings-claim guidance as the product site.

package/README.ko.md

@@ -78,7 +78,7 @@ ContextGuard는 provider 캐시, semantic cache, 프롬프트 압축 도구를
 | Provider prompt/context caching | 안정적인 프롬프트 앞부분을 재사용합니다. | 보완 관계입니다. ContextGuard는 자주 바뀌는 컨텍스트 뒷부분을 더 작고 깨끗하게 유지하도록 돕고, `context-guard-audit`로 프롬프트 배치를 점검하며, `context-guard cost`로 Anthropic 요청이 cache read 대신 cache write가 될 가능성을 미리 알릴 수 있습니다. |
 | Semantic response cache | 같거나 비슷한 요청의 이전 답변을 재사용합니다. | 보완 관계입니다. ContextGuard는 AI 답변 캐시를 제공하지 않습니다. |
 | 프롬프트/컨텍스트 압축 | 이미 선택된 텍스트를 더 짧게 만듭니다. | 인접한 역할입니다. ContextGuard는 로컬 출력 축약과 요약을 제공하지만, 무손실 의미 압축을 보장하지 않습니다. |
-| 실험 planner/runtime | local proxy는 dry-run plan, external-forwarding design plan, gate record, one-shot loopback forwarding MVP로만 검토합니다. context-diff, visual evidence-pack, learned-compression, self-hosted metrics도 명시적 로컬 런타임만 지원합니다. | 모두 기본 비활성이며 명시적 명령이 필요합니다. `record`는 listener·traffic forwarding·DNS lookup을 시작하지 않고, `serve local-proxy`는 literal loopback IP로 제한된 1회 요청만 bind/forward하며, `--response-sandbox`는 safe UTF-8 upstream body를 compact local artifact 재조회 envelope로 대체할 수 있습니다. 별도 근거 gate와 future PR gate 없이는 model/compressor 실행, OCR/crop service, external forwarding, credential persistence, hosted API 절감 주장으로 보지 않습니다. 자세한 내용은 “실험 기능 opt-in 관리” 섹션을 참고하세요. |
+| 실험 planner/runtime | `image-context-pack`과 `semantic-checkpoint`는 plan-only gate로만 검토합니다. local proxy는 dry-run plan, external-forwarding design plan, gate record, one-shot loopback forwarding MVP로만 검토합니다. context-diff, visual evidence-pack, learned-compression, self-hosted metrics도 명시적 로컬 런타임만 지원합니다. | 모두 기본 비활성이며 명시적 명령이 필요합니다. `semantic-checkpoint`는 exact context fallback/re-expand, provenance review ack, provider-boundary ack, protected-zone denial, missed-context note가 있어야 JSON payload가 ready 상태가 됩니다. `record`는 listener·traffic forwarding·DNS lookup을 시작하지 않고, `serve local-proxy`는 literal loopback IP로 제한된 1회 요청만 bind/forward하며, `--response-sandbox`는 safe UTF-8 upstream body를 compact local artifact 재조회 envelope로 대체할 수 있습니다. 별도 근거 gate와 future PR gate 없이는 model/compressor 실행, OCR/crop service, external forwarding, credential persistence, runtime checkpoint replacement, hosted API 절감 주장으로 보지 않습니다. 자세한 내용은 “실험 기능 opt-in 관리” 섹션을 참고하세요. |
 | ContextGuard | 불필요한 파일, 로그, 반복 실패, 과도한 출력이 에이전트 컨텍스트에 들어가기 전에 줄어들도록 돕습니다. | 로컬 가드레일, 되돌릴 수 있는 로컬 보관본, 측정 도구입니다. |
 
 설계에 참고한 관련 패턴은 다음과 같습니다.
@@ -117,7 +117,7 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 - setup이나 패키징 smoke check에서 명령 매니페스트를 코드로 실행하거나 임의 `PATH`/현재 작업 디렉터리 헬퍼를 신뢰하지 않습니다.
 - 절감 수치가 필요할 때 직접 전후 비교 측정을 대신하지 않습니다.
 - 로컬 RAM/디스크 보관본은 다음에 보낼 컨텍스트를 줄이는 데 도움이 될 수 있지만 Anthropic provider prompt cache를 대체하거나 cache hit를 보장하지 않습니다. 배포나 청구 설명 전에는 Anthropic prompt caching/pricing 문서를 다시 확인하세요: https://docs.anthropic.com/en/build-with-claude/prompt-caching 및 https://platform.claude.com/docs/en/about-claude/pricing.
-- 실험 헬퍼는 대부분 dry-run 안전성 checker/planner이며 design-only external-forwarding opt-in gate를 포함합니다. 명시적 로컬 runtime은 caller-supplied context-diff replacement payload, caller-supplied visual crop/OCR evidence pack, caller-supplied learned-compression prose candidate, self-hosted metrics JSONL sidecar 기록, local-proxy runtime-gate JSONL 기록, private ready-file nonce가 필요한 one-shot `serve local-proxy` loopback forwarding, safe UTF-8 응답을 compact artifact envelope로 바꾸는 optional `--response-sandbox`, successful forwarded request용 optional shifted-cost diagnostic JSONL row만 제공합니다.
+- 실험 헬퍼는 대부분 dry-run 안전성 checker/planner이며 plan-only `image-context-pack`/`semantic-checkpoint` 평가 gate와 design-only external-forwarding opt-in gate를 포함합니다. 명시적 로컬 runtime은 caller-supplied context-diff replacement payload, caller-supplied visual crop/OCR evidence pack, caller-supplied learned-compression prose candidate, self-hosted metrics JSONL sidecar 기록, local-proxy runtime-gate JSONL 기록, private ready-file nonce가 필요한 one-shot `serve local-proxy` loopback forwarding, safe UTF-8 응답을 compact artifact envelope로 바꾸는 optional `--response-sandbox`, successful forwarded request용 optional shifted-cost diagnostic JSONL row만 제공합니다.
 - ContextGuard는 learned/synthetic compressor 실행·embedding·reranker·model call·생성형 replacement, screenshot 캡처·image crop·OCR 실행·image parsing·외부 OCR/image service, 명시적 local metrics 기록을 넘어선 self-hosted KV/latent inference optimization runtime, literal-loopback 1회 HTTP forwarding과 credential 차단을 넘어선 proxy forwarding은 제공하지 않습니다.
 - 예전 `/claude-token-optimizer:*` Claude Code 슬래시 명령을 별칭으로 제공하지 않습니다. 설치 후에는 `/context-guard:*`를 사용하세요.
 
@@ -394,6 +394,8 @@ context-guard experiments plan context-diff-compaction --json < change.diff
 context-guard experiments emit context-diff-compaction --receipt-id <artifact-id> --reexpand-command "context-guard-artifact get <artifact-id> --full" --replacement-file compact-diff.txt --json < change.diff
 context-guard experiments plan visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --missed-context-note "outside crop omitted"
 context-guard experiments emit visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --ocr-text "visible text" --ocr-confidence 0.9 --ocr-error-note "glyph may be uncertain" --missed-context-note "outside crop omitted"
+context-guard experiments plan image-context-pack --json --exact-text-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "omitted text remains retrievable before any future image pack is used" --image-size 800,600 --packed-image-size 400,300
+context-guard experiments plan semantic-checkpoint --json --goal "preserve current task state for review" --constraint "do not rewrite protected evidence" --decision "ship plan-only semantic-checkpoint gate first" --open-task "verify exact fallback before any checkpoint is used" --evidence-handle "roadmap=contextguard-artifact:0123456789abcdef" --missing-provenance-note "none known after review" --unresolved-question "which provenance handle fields become mandatory later" --exact-context-fallback-receipt 0123456789abcdef --reexpand-command "context-guard-artifact get 0123456789abcdef --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "raw transcript remains retrievable before checkpoint metadata is used"
 context-guard experiments plan learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" < sanitized-prose.txt
 context-guard experiments emit learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --replacement-file compact-prose.txt < sanitized-prose.txt
 context-guard experiments plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
@@ -406,6 +408,8 @@ context-guard experiments enable output-receipt-trim --root .
 context-guard experiments disable output-receipt-trim --root .
 ```
 
+`plan semantic-checkpoint`는 plan-only/eval-only gate입니다. CLI flag는 dry-run 검토를 위해 optional이지만, JSON payload에서는 goal, exact fallback receipt, local re-expand command, provider-boundary ack, protected-zone policy `deny`, missed-context note, provenance review note가 없으면 readiness blocker로 남습니다. re-expand command는 `context-guard-artifact get <id> --full` 또는 `context-guard artifact get <id> --full` 형태의 로컬 artifact 재조회만 허용합니다. `--missing-provenance-note`는 `none known after review` 같은 검토 확인 문구일 수 있습니다. 이 gate는 `emit`/`record`/`serve` runtime, 새 `context-guard-semantic-checkpoint` binary, file write, transcript/prompt edit, model/provider/network call, replacement context, hosted token/cost savings claim을 제공하지 않습니다.
+
 local-proxy 예시는 side effect 기준으로 나뉩니다.
 
 - `plan local-proxy`는 advisory metadata만 만들며 forwarding을 켜지 않습니다.
@@ -420,6 +424,8 @@ local-proxy 예시는 side effect 기준으로 나뉩니다.
 | --- | --- | --- |
 | `context-diff-compaction` | dry-run diff 조언과 명시적 `emit ... --receipt-id ... --reexpand-command ...` 런타임으로 caller-supplied compact replacement를 출력합니다. | `plan`은 replacement를 emit하지 않습니다. `emit`은 reviewable hunk, input diff와 일치하는 exact local artifact content/re-expand metadata와 더 작은 caller-supplied replacement가 모두 있을 때만 동작하며, ContextGuard가 semantic compression을 생성하거나 hosted token/cost 절감 주장 근거로 쓰지 않습니다. |
 | `visual-crop-ocr` | dry-run visual evidence 조언과 명시적 `emit visual-crop-ocr` 런타임으로 caller-supplied evidence pack을 출력합니다. | `emit`은 full visual evidence receipt, missed-context note, 완전한 user-supplied crop 및/또는 OCR evidence가 필요합니다. ContextGuard는 screenshot 캡처, image crop, OCR 실행, image parsing, 외부 service 호출, 파일 쓰기, hosted token/cost 절감 주장을 하지 않습니다. |
+| `image-context-pack` | pxpipe-inspired image/context packing 평가를 위한 plan-only dry-run gate입니다. | 명시적 평가 의도, exact text artifact fallback, protected-zone denial, provider-measured matched-task boundary, missed-context guardrail, 그리고 `visual-crop-ocr`이 기존 caller-supplied visual evidence-pack surface라는 확인이 필요합니다. ContextGuard는 image rendering, OCR 실행, image parsing, model/provider call, proxy traffic, binary artifact 저장, replacement evidence 출력, hosted token/cost savings claim을 하지 않습니다. |
+| `semantic-checkpoint` | 현재 작업 상태를 review용으로 보존할 준비가 되었는지 확인하는 plan-only/eval-only gate입니다. | CLI flag는 optional이지만 JSON readiness는 exact context fallback/re-expand, provider-boundary ack, protected-zone denial, missed-context note, provenance review note가 없으면 blocked입니다. `--missing-provenance-note`는 `none known after review` 같은 검토 확인 문구일 수 있습니다. ContextGuard는 file write, transcript/prompt edit, model/provider/network call, replacement context, `emit`/`record`/`serve` runtime, 새 binary, hosted token/cost savings claim을 하지 않습니다. |
 | `learned-compression` | deny-by-default 정책 검사와 명시적 `emit learned-compression` 런타임으로 verified exact fallback content가 있는 caller-supplied compact prose candidate를 출력합니다. | `emit`은 sanitized trusted prose, protected-signal denial, input과 일치하는 verified local fallback artifact, 더 작은 caller-supplied prose candidate가 필요합니다. ContextGuard는 compressor, embedding, reranker, model call, subprocess, external service, 생성형 replacement, hosted savings claim을 실행/생성하지 않습니다. |
 | `self-hosted-metrics-ledger` | dry-run preview와 명시적 `record ... --ledger-jsonl` 런타임으로 local/model-server latency, memory, quality, energy, throughput, local-cost metric을 기록합니다. | dry-run preview는 ledger 파일을 쓰지 않습니다. 명시적 record 명령만 로컬 JSONL sidecar를 쓰며, hosted API token/cost 절감 주장 근거로는 쓰지 않습니다. |
 | `local-proxy` | 미래 local proxy 후보에 대한 localhost-only advisory metadata, future external forwarding용 design-only `plan local-proxy-external-forwarding` review, 명시적 `record local-proxy-runtime-gate --ledger-jsonl` gate row runtime, 명시적 one-shot `serve local-proxy` loopback forwarding MVP, safe UTF-8 응답을 compact artifact envelope로 바꾸는 optional `--response-sandbox`, successful forwarded request용 optional `--diagnostic-ledger-jsonl` shifted-cost diagnostics. | `plan`은 ledger를 쓰지 않습니다. `record`는 localhost-only metadata와 `--runtime-gate-ack`가 있을 때만 로컬 JSONL row를 쓰며 listener 시작이나 traffic forwarding, DNS lookup을 하지 않습니다. `serve`는 `--forwarding-gate-ack --once`, private `--ready-file` nonce handoff, literal loopback bind/target IP, nonzero port, byte/time limit, credential-free request가 필요하며 external forwarding, CONNECT/TLS proxying, API-key persistence, hosted API 절감 주장을 하지 않습니다. `--response-sandbox`는 safe UTF-8 response text만 sanitized local artifact receipt로 저장하고 raw body 대신 redacted rehydration command template가 담긴 compact envelope를 반환하며 hosted token/cost savings claim은 아닙니다. `--diagnostic-ledger-jsonl`은 successful-forward 진단 row만 쓰며 raw header/body와 hosted-savings claim을 저장하지 않습니다. `plan local-proxy-external-forwarding`은 threat model/allowlist/redaction/provider-evidence design metadata만 출력하고 DNS lookup, external service call, traffic forwarding, credential persistence, hosted savings claim을 하지 않습니다. |
@@ -431,7 +437,8 @@ local-proxy 예시는 side effect 기준으로 나뉩니다.
 ContextGuard는 아직 다음 기능을 제공하지 않습니다.
 
 - caller-supplied learned candidate emitter를 넘어서는 learned/synthetic compressor 실행 또는 생성형 replacement
-- caller-supplied visual evidence-pack emitter를 넘어서는 생성형 crop/OCR 또는 visual-token pruning runtime
+- caller-supplied visual evidence-pack emitter와 plan-only image-context-pack dry-run gate를 넘어서는 생성형 crop/OCR, visual-token pruning runtime, image-context-pack rendering/runtime
+- plan-only semantic-checkpoint gate를 넘어서는 emit/record/serve runtime, replacement context, file-writing checkpoint store, transcript/prompt edit, provider/model/network-backed checkpointing, 새 `context-guard-semantic-checkpoint` binary
 - 명시적 local metrics 기록을 넘어서는 self-hosted KV/latent optimization
 - one-shot literal-loopback local proxy MVP를 넘어서는 external/daemon/credential-bearing proxy forwarding runtime
 

package/README.md

@@ -80,7 +80,7 @@ ContextGuard complements provider and semantic caches, and works alongside promp
 | Provider prompt/context caching | Reusing stable prompt prefixes. | Complementary; ContextGuard helps keep the changing tail of context smaller and cleaner, `context-guard-audit` can flag likely volatile prefix layouts, and `context-guard cost` can warn when an Anthropic request is likely to cache-write instead of cache-read. |
 | Semantic response cache | Reusing answers to identical or similar requests. | Complementary; ContextGuard does not serve cached AI answers. |
 | Prompt/context compression | Shortening text that is already selected for the model. | Adjacent; ContextGuard trims and summarizes local output, but does not promise lossless semantic compression. |
-| Experimental planners and local runtimes | Default-off and explicit-command-only; covers local-proxy plans and gate records plus narrow local runtimes for caller-supplied context-diff, visual evidence-pack, learned-compression, and self-hosted metrics evidence. | The local proxy `record` command starts no listener and forwards no traffic; `serve local-proxy` binds and forwards only literal loopback IPs for one bounded request; `--response-sandbox` can replace a safe UTF-8 upstream body with a compact local artifact rehydration envelope. Compressor/model execution, OCR/crop services, external forwarding, credential persistence, and hosted-savings claims stay out of scope until a separate evidence gate and future PR allow them. |
+| Experimental planners and local runtimes | Default-off and explicit-command-only; covers plan-only `image-context-pack` and `semantic-checkpoint` gates plus local-proxy plans/gate records and narrow local runtimes for caller-supplied context-diff, visual evidence-pack, learned-compression, and self-hosted metrics evidence. | `image-context-pack` and `semantic-checkpoint` are dry-run planning gates only: they do not emit replacements, call models/providers, proxy traffic, write files, or make hosted token/cost savings claims. `semantic-checkpoint` additionally requires exact context fallback/re-expand metadata, provenance review acknowledgement, provider-boundary acknowledgement, protected-zone denial, and missed-context notes before the JSON payload reports readiness. The local proxy `record` command starts no listener and forwards no traffic; `serve local-proxy` binds and forwards only literal loopback IPs for one bounded request; `--response-sandbox` can replace a safe UTF-8 upstream body with a compact local artifact rehydration envelope. Compressor/model execution, OCR/crop services, external forwarding, credential persistence, runtime checkpoint replacement, and hosted-savings claims stay out of scope until a separate evidence gate and future PR allow them. |
 | ContextGuard | Avoiding unnecessary files, logs, repeated failures, and noisy output before they enter agent context. | Local guardrails, reversible artifacts, and measurement. |
 
 Related patterns that informed the design:
@@ -119,7 +119,7 @@ If you need a savings claim, measure it on your own tasks:
 - It does not execute command manifests as code or trust arbitrary `PATH`/current-working-directory helpers during setup or packaged smoke checks.
 - It does not replace real before/after measurement when you need a savings claim.
 - Local RAM/disk receipts can help reduce what you send next, but they do **not** replace Anthropic's provider prompt cache or guarantee cache hits. Recheck Anthropic prompt-caching and pricing docs before release or billing claims: https://docs.anthropic.com/en/build-with-claude/prompt-caching and https://platform.claude.com/docs/en/about-claude/pricing.
-- Experimental helpers are mostly dry-run checker/planner surfaces, including a design-only external-forwarding opt-in gate. Explicit local runtimes exist only for caller-supplied context-diff replacement payloads, caller-supplied visual crop/OCR evidence packs, caller-supplied learned-compression prose candidates, self-hosted metrics JSONL sidecar records, local-proxy runtime-gate JSONL records, and one-shot `serve local-proxy` loopback forwarding with a private ready-file nonce, optional `--response-sandbox` compact artifact envelopes for safe UTF-8 responses, plus optional shifted-cost diagnostic JSONL rows for successful forwarded requests.
+- Experimental helpers are mostly dry-run checker/planner surfaces, including plan-only `image-context-pack` and `semantic-checkpoint` evaluation gates and a design-only external-forwarding opt-in gate. Explicit local runtimes exist only for caller-supplied context-diff replacement payloads, caller-supplied visual crop/OCR evidence packs, caller-supplied learned-compression prose candidates, self-hosted metrics JSONL sidecar records, local-proxy runtime-gate JSONL records, and one-shot `serve local-proxy` loopback forwarding with a private ready-file nonce, optional `--response-sandbox` compact artifact envelopes for safe UTF-8 responses, plus optional shifted-cost diagnostic JSONL rows for successful forwarded requests.
 - ContextGuard does not ship learned/synthetic compressor execution, embeddings, rerankers, model calls, generated replacement text, screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, self-hosted KV/latent inference optimization beyond explicit local metrics recording, or broader proxy forwarding beyond literal-loopback, one-request HTTP forwarding with credential material blocked.
 - It does not alias the old `/claude-token-optimizer:*` Claude Code slash-command namespace. Use `/context-guard:*` after installing this plugin.
 
@@ -441,6 +441,8 @@ context-guard experiments plan context-diff-compaction --json < change.diff
 context-guard experiments emit context-diff-compaction --receipt-id <artifact-id> --reexpand-command "context-guard-artifact get <artifact-id> --full" --replacement-file compact-diff.txt --json < change.diff
 context-guard experiments plan visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --missed-context-note "outside crop omitted"
 context-guard experiments emit visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --ocr-text "visible text" --ocr-confidence 0.9 --ocr-error-note "glyph may be uncertain" --missed-context-note "outside crop omitted"
+context-guard experiments plan image-context-pack --json --exact-text-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "omitted text remains retrievable before any future image pack is used" --image-size 800,600 --packed-image-size 400,300
+context-guard experiments plan semantic-checkpoint --json --goal "preserve current task state for review" --constraint "do not rewrite protected evidence" --decision "ship plan-only semantic-checkpoint gate first" --open-task "verify exact fallback before any checkpoint is used" --evidence-handle "roadmap=contextguard-artifact:0123456789abcdef" --missing-provenance-note "none known after review" --unresolved-question "which provenance handle fields become mandatory later" --exact-context-fallback-receipt 0123456789abcdef --reexpand-command "context-guard-artifact get 0123456789abcdef --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "raw transcript remains retrievable before checkpoint metadata is used"
 context-guard experiments plan learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" < sanitized-prose.txt
 context-guard experiments emit learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --replacement-file compact-prose.txt < sanitized-prose.txt
 context-guard experiments plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
@@ -453,6 +455,10 @@ context-guard experiments enable output-receipt-trim --root .
 context-guard experiments disable output-receipt-trim --root .
 ```
 
+`plan image-context-pack` is intentionally plan-only and side-effect free: it emits deterministic JSON metadata, does not render or parse images, does not run OCR, does not store binary image artifacts, does not call providers or proxy traffic, and does not duplicate `visual-crop-ocr`. Any future omission of exact text must keep a verified exact text fallback, deny protected zones, record missed-context guardrails, and treat image/request byte reductions as proxy evidence until provider-measured matched tasks prove token/cost deltas.
+
+`plan semantic-checkpoint` is also plan-only/eval-only. Its CLI flags are optional so incomplete plans can produce reviewer JSON, but missing readiness fields block the JSON payload until exact context fallback is present. Ready plans require a goal, exact fallback receipt, a local re-expand command shaped as `context-guard-artifact get <id> --full` or `context-guard artifact get <id> --full`, provider-boundary acknowledgement, protected-zone policy `deny`, missed-context notes, and provenance review notes. `--missing-provenance-note` may be a review acknowledgement such as `none known after review`. The gate has no `emit`, `record`, or `serve` runtime, no `context-guard-semantic-checkpoint` binary, no file writes, transcript or prompt edits, model/provider/network calls, replacement context, or hosted token/cost savings claim.
+
 The local-proxy examples are intentionally split by side effect:
 
 - `plan local-proxy` produces advisory metadata only; it does not enable forwarding.
@@ -463,12 +469,14 @@ The local-proxy examples are intentionally split by side effect:
 
 By default, project settings are stored in `.context-guard/experiments.json`. Use `--config <path>` only for an explicit project-local override. Experiment metadata includes risk level, gate requirements, explicit command/flag surfaces, and claim boundaries so hosted API token/cost savings are not claimed without provider-measured matched-task evidence. `experiments enable` records intent only; it does not run helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
 
-Shipped experimental checker/planner surfaces, plus explicit local context-diff, visual evidence, learned-candidate, metrics, and proxy-gate record runtimes, are intentionally narrow:
+Shipped experimental checker/planner surfaces, plus explicit local context-diff, visual evidence, learned-candidate, metrics, proxy-gate record runtimes, and the plan-only image-context-pack and semantic-checkpoint gates, are intentionally narrow:
 
 | Planner/checker/runtime | What it emits | Hard boundary |
 | --- | --- | --- |
 | `context-diff-compaction` | Dry-run diff advice plus an explicit `emit ... --receipt-id ... --reexpand-command ...` runtime for caller-supplied compact replacements. | `plan` emits no replacement. `emit` requires reviewable hunks, exact local artifact re-expand metadata whose stored content matches the input diff, and a smaller caller-supplied replacement; ContextGuard does not generate semantic compression or support hosted token/cost savings claims. |
 | `visual-crop-ocr` | Dry-run visual evidence advice plus an explicit `emit visual-crop-ocr` runtime for caller-supplied evidence packs. | `emit` requires a full visual evidence receipt, missed-context note, and complete user-supplied crop and/or OCR evidence; ContextGuard does not capture screenshots, crop images, run OCR, parse images, call external services, write files, or support hosted token/cost savings claims. |
+| `image-context-pack` | Pxpipe-inspired dry-run plan metadata only for future image/context packing evaluation. | `plan` emits no image, replacement, evidence pack, binary artifact, ledger, listener, or proxy. It requires exact text fallback receipt/re-expand metadata before omitted text is used, protected-zone denial, missed-context notes, and an explicit provider boundary acknowledgement for provider/model measured matched-task evidence. `visual-crop-ocr` remains the caller-supplied visual evidence-pack surface; `image-context-pack` is not a duplicate emitter or verified exact binary/image fallback. |
+| `semantic-checkpoint` | Plan-only/eval-only checkpoint readiness metadata for preserving task state during review. | `plan` emits deterministic JSON metadata only. CLI flags are optional, but readiness is blocked in JSON until exact context fallback, local re-expand metadata, provider-boundary acknowledgement, protected-zone denial, missed-context note, and provenance review note are present. `--missing-provenance-note` may be a review acknowledgement such as `none known after review`. It writes no files, edits no transcript or prompt, calls no model/provider/network, emits no replacement context, has no `emit`/`record`/`serve` runtime or new binary, and makes no hosted token/cost savings claim. |
 | `learned-compression` | Deny-by-default policy checks plus an explicit `emit learned-compression` runtime for caller-supplied compact prose candidates with verified exact fallback content. | `emit` requires sanitized trusted prose, protected-signal denial, a verified local fallback artifact matching the input, and a smaller caller-supplied prose candidate; ContextGuard does not run compressors, embeddings, rerankers, model calls, subprocesses, external services, generated replacement text, or hosted savings claims. |
 | `self-hosted-metrics-ledger` | Dry-run preview plus an explicit `record ... --ledger-jsonl` runtime for local/model-server latency, memory, quality, energy, throughput, and local-cost metrics. | The dry-run preview does not write a ledger; the explicit record command writes only local JSONL sidecars and still does not support hosted API token/cost savings claims. |
 | `local-proxy` | Localhost-only advisory metadata, design-only `plan local-proxy-external-forwarding` review for future external forwarding, an explicit `record local-proxy-runtime-gate --ledger-jsonl` runtime for one local gate row, an explicit one-shot `serve local-proxy` loopback forwarding MVP, optional `--response-sandbox` compact artifact envelopes, and optional `--diagnostic-ledger-jsonl` shifted-cost diagnostics for successful forwarded requests. | `plan` writes no ledger. `record` writes only after localhost-only metadata and `--runtime-gate-ack`; it starts no listener, forwards no traffic, and performs no DNS lookup. `serve` additionally requires `--forwarding-gate-ack --once`, a private `--ready-file` nonce handoff, literal loopback bind/target IPs, nonzero ports, bounded bytes/timeouts, and credential-free requests; it performs no external forwarding, no CONNECT/TLS proxying, no API-key persistence, and no hosted-savings claim. `--response-sandbox` can store safe UTF-8 response text as a sanitized local artifact receipt and return a compact envelope with redacted rehydration command templates; it does not claim hosted token/cost savings. `--diagnostic-ledger-jsonl` writes only successful-forward diagnostics with no raw headers/bodies and no hosted-savings claim. `plan local-proxy-external-forwarding` emits threat-model/allowlist/redaction/provider-evidence design metadata only and still performs no DNS lookup, external service call, traffic forwarding, credential persistence, or hosted-savings claim. |
@@ -481,6 +489,8 @@ ContextGuard does not yet ship:
 
 - learned/synthetic compressor execution or generated replacement text beyond the caller-supplied learned candidate emitter
 - generated crop/OCR or visual-token pruning runtime beyond the caller-supplied visual evidence-pack emitter
+- generated image-context-pack renderers, binary/image artifact fallback, or pxpipe-style proxy/runtime beyond the plan-only evaluation gate
+- semantic-checkpoint emit/record/serve runtime, replacement context, file-writing checkpoint store, transcript/prompt editing, provider/model/network-backed checkpointing, or a new `context-guard-semantic-checkpoint` binary
 - self-hosted KV/latent optimization beyond explicit local metrics recording
 - external, daemon, or credential-bearing proxy forwarding beyond the one-shot literal-loopback local proxy MVP
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/context-guard",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "ContextGuard CLI helpers for keeping AI coding agent context focused and local-first.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/ictechgy/context-guard#readme",

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

@@ -37,5 +37,5 @@
     "gated-experiments",
     "future-roadmap"
   ],
-  "version": "0.4.12"
+  "version": "0.4.14"
 }

package/plugins/context-guard/README.ko.md

@@ -119,7 +119,11 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 
 ContextGuard는 모델 토큰을 줄이기 위해 작업을 외부 AI 서비스로 전송하지 않습니다. 모든 헬퍼 명령은 로컬에서 동작합니다. 로컬 RAM/디스크 보관본은 다음에 보낼 컨텍스트를 줄이는 데 도움될 수 있지만 provider prompt cache를 대체하지 않습니다. Anthropic 배포나 청구 설명 전에는 공식 prompt caching/pricing 문서를 다시 확인하세요: https://docs.anthropic.com/en/build-with-claude/prompt-caching 및 https://platform.claude.com/docs/en/about-claude/pricing.
 
-미래 learned, self-hosted 최적화 아이디어는 [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md)에 gated experiment로 기록하며, fixture-only 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 둡니다. learned compression은 `context-guard experiments plan learned-compression` dry-run checker와 명시적 `context-guard experiments emit learned-compression` caller-supplied candidate emitter만 shipped 상태이고, self-hosted-metrics-ledger는 dry-run preview와 명시적 `context-guard experiments record self-hosted-metrics-ledger` local JSONL record를 제공하며, dry-run preview는 ledger 파일을 쓰지 않습니다. visual crop/OCR은 caller-supplied evidence-pack emit, context-diff는 verified-receipt caller-supplied replacement emit만 제공합니다. local proxy는 `context-guard experiments plan local-proxy` localhost-only dry-run advisory plan, design-only `context-guard experiments plan local-proxy-external-forwarding` gate, 명시적 `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` gate row record, private ready-file nonce가 필요한 one-shot `context-guard experiments serve local-proxy` loopback forwarding MVP와 successful forwarded request용 optional shifted-cost diagnostic JSONL row만 shipped 상태입니다. record는 no listener/no traffic forwarding/no DNS lookup/no external service/no API-key persistence boundary를 유지하고, serve는 private ready-file nonce, literal loopback IP, `--once`, credential-free request만 허용하고 CONNECT/TLS proxying도 지원하지 않습니다. `--response-sandbox`는 safe UTF-8 response text만 local artifact receipt로 저장하고 raw body 대신 redacted rehydration command template가 담긴 compact envelope를 돌려주며 hosted token/cost savings claim은 아닙니다. `--diagnostic-ledger-jsonl`은 successful forwarded request 뒤에만 진단 row를 쓰며 raw header/body나 hosted-savings evidence를 저장하지 않습니다. `plan local-proxy-external-forwarding`은 threat model, HTTPS allowlist, credential redaction, provider-evidence boundary를 점검하는 dry-run design gate이고 listener, DNS lookup, external service call, traffic forwarding, credential persistence, external proxy forwarding runtime, hosted savings claim을 제공하지 않습니다. learned/synthetic compressor 실행·embedding·reranker·model call·생성형 replacement, generated OCR/crop 또는 visual-token pruning, self-hosted KV/latent runtime 최적화, one-shot literal-loopback local proxy MVP를 넘어선 external/daemon/credential-bearing proxy forwarding runtime은 shipped가 아닙니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, broader local proxy forwarding constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
+미래 learned, self-hosted 최적화 아이디어는 [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md)에 gated experiment로 기록하며, fixture-only 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 둡니다. learned compression은 `context-guard experiments plan learned-compression` dry-run checker와 명시적 `context-guard experiments emit learned-compression` caller-supplied candidate emitter만 shipped 상태이고, self-hosted-metrics-ledger는 dry-run preview와 명시적 `context-guard experiments record self-hosted-metrics-ledger` local JSONL record를 제공하며, dry-run preview는 ledger 파일을 쓰지 않습니다. visual crop/OCR은 caller-supplied evidence-pack emit, image-context-pack은 pxpipe-inspired image/context packing 평가를 위한 plan-only dry-run gate, semantic-checkpoint는 review용 task-state checkpoint 계획을 위한 plan-only/eval-only gate, context-diff는 verified-receipt caller-supplied replacement emit만 제공합니다. image-context-pack은 exact text artifact fallback, protected-zone denial, provider-boundary acknowledgement for provider-measured matched tasks, missed-context guardrail, 그리고 visual-crop-ocr이 기존 caller-supplied visual evidence-pack surface라는 plan output 확인이 필요하며, image rendering, OCR 실행, image parsing, model/provider call, proxy traffic, binary artifact 저장, replacement evidence 출력, hosted token/cost savings claim을 하지 않습니다. semantic-checkpoint는 CLI flag가 optional이지만 JSON readiness에서 exact context fallback/re-expand, provider-boundary ack, protected-zone policy `deny`, missed-context note, provenance review note가 없으면 blocked이며, `--missing-provenance-note`는 `none known after review` 같은 검토 확인 문구일 수 있습니다. 허용되는 re-expand command는 `context-guard-artifact get <id> --full` 또는 `context-guard artifact get <id> --full` 형태이고, emit/record/serve runtime, 새 `context-guard-semantic-checkpoint` binary, file write, transcript/prompt edit, model/provider/network call, replacement context, hosted token/cost savings claim은 없습니다. local proxy는 `context-guard experiments plan local-proxy` localhost-only dry-run advisory plan, design-only `context-guard experiments plan local-proxy-external-forwarding` gate, 명시적 `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` gate row record, private ready-file nonce가 필요한 one-shot `context-guard experiments serve local-proxy` loopback forwarding MVP와 successful forwarded request용 optional shifted-cost diagnostic JSONL row만 shipped 상태입니다. record는 no listener/no traffic forwarding/no DNS lookup/no external service/no API-key persistence boundary를 유지하고, serve는 private ready-file nonce, literal loopback IP, `--once`, credential-free request만 허용하고 CONNECT/TLS proxying도 지원하지 않습니다. `--response-sandbox`는 safe UTF-8 response text만 local artifact receipt로 저장하고 raw body 대신 redacted rehydration command template가 담긴 compact envelope를 돌려주며 hosted token/cost savings claim은 아닙니다. `--diagnostic-ledger-jsonl`은 successful forwarded request 뒤에만 진단 row를 쓰며 raw header/body나 hosted-savings evidence를 저장하지 않습니다. `plan local-proxy-external-forwarding`은 threat model, HTTPS allowlist, credential redaction, provider-evidence boundary를 점검하는 dry-run design gate이고 listener, DNS lookup, external service call, traffic forwarding, credential persistence, external proxy forwarding runtime, hosted savings claim을 제공하지 않습니다. learned/synthetic compressor 실행·embedding·reranker·model call·생성형 replacement, generated OCR/crop, visual-token pruning, plan-only image-context-pack dry-run gate를 넘어선 image-context-pack rendering/runtime, plan-only semantic-checkpoint gate를 넘어선 emit/record/serve runtime이나 replacement context/file-writing checkpoint store/transcript-prompt edit/provider-backed checkpointing, self-hosted KV/latent runtime 최적화, one-shot literal-loopback local proxy MVP를 넘어선 external/daemon/credential-bearing proxy forwarding runtime은 shipped가 아닙니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, broader local proxy forwarding constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
+
+```bash
+context-guard experiments plan semantic-checkpoint --json --goal "preserve current task state for review" --constraint "do not rewrite protected evidence" --decision "ship plan-only semantic-checkpoint gate first" --open-task "verify exact fallback before any checkpoint is used" --evidence-handle "roadmap=contextguard-artifact:0123456789abcdef" --missing-provenance-note "none known after review" --unresolved-question "which provenance handle fields become mandatory later" --exact-context-fallback-receipt 0123456789abcdef --reexpand-command "context-guard-artifact get 0123456789abcdef --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "raw transcript remains retrievable before checkpoint metadata is used"
+```
 
 교차 에이전트 규칙 스니펫은 안내용입니다. 대상 에이전트가 반드시 따른다고 보장할 수 없으므로, 절감 주장이 필요하면 실제 전후 동작을 직접 측정하세요.
 

package/plugins/context-guard/README.md

@@ -128,7 +128,7 @@ These helpers reduce common sources of context bloat, but they do not guarantee
 
 ContextGuard also does not send work to external AI providers to save model tokens. All helper commands run locally. Local RAM/disk receipts can reduce what you choose to send, but they do not replace a provider prompt cache. Before release or billing claims for Anthropic, recheck the official prompt-caching and pricing docs: https://docs.anthropic.com/en/build-with-claude/prompt-caching and https://platform.claude.com/docs/en/about-claude/pricing.
 
-Future learned, multimodal, and self-hosted optimization ideas are tracked in [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md), with fixture-only starters in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md). ContextGuard ships dry-run planners/checkers for local-proxy advisory plans and design-only external-forwarding gates, plus narrow explicit local runtimes for caller-supplied context-diff replacement payloads, caller-supplied visual crop/OCR evidence packs, caller-supplied learned-compression prose candidates, self-hosted metrics JSONL sidecar records, local-proxy runtime-gate JSONL records, one-shot `serve local-proxy` loopback forwarding with a private ready-file nonce, optional `--response-sandbox` compact artifact envelopes for safe UTF-8 responses, and optional shifted-cost diagnostic JSONL rows for successful forwarded requests. Learned/synthetic compressor execution beyond the caller-supplied candidate emitter, embeddings, rerankers, model calls, generated replacement text, screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file evidence writes, self-hosted KV/latent runtime optimization beyond explicit local metrics recording, and external/daemon/hostname-DNS, credential-bearing, or external proxy forwarding beyond literal-loopback one-request HTTP forwarding are not shipped. That radar and the fixtures do not claim hosted API savings without provider-measured matched-task evidence. The radar's later-roadmap gates also keep neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, and broader local proxy forwarding constraints experimental/non-shipped until a separate future PR satisfies those gates.
+Future learned, multimodal, and self-hosted optimization ideas are tracked in [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md), with fixture-only starters in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md). ContextGuard ships dry-run planners/checkers for a plan-only `image-context-pack` evaluation gate, local-proxy advisory plans, and design-only external-forwarding gates, plus narrow explicit local runtimes for caller-supplied context-diff replacement payloads, caller-supplied visual crop/OCR evidence packs, caller-supplied learned-compression prose candidates, self-hosted metrics JSONL sidecar records, local-proxy runtime-gate JSONL records, one-shot `serve local-proxy` loopback forwarding with a private ready-file nonce, optional `--response-sandbox` compact artifact envelopes for safe UTF-8 responses, and optional shifted-cost diagnostic JSONL rows for successful forwarded requests. Learned/synthetic compressor execution beyond the caller-supplied candidate emitter, embeddings, rerankers, model calls, generated replacement text, screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file evidence writes, generated image-context-pack renderers, binary/image artifact fallback, pxpipe-style proxy/runtime, self-hosted KV/latent runtime optimization beyond explicit local metrics recording, and external/daemon/hostname-DNS, credential-bearing, or external proxy forwarding beyond literal-loopback one-request HTTP forwarding are not shipped. That radar and the fixtures do not claim hosted API savings without provider-measured matched-task evidence. The radar's later-roadmap gates also keep neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, and broader local proxy forwarding constraints experimental/non-shipped until a separate future PR satisfies those gates.
 
 ## Experimental opt-ins
 
@@ -141,6 +141,8 @@ context-guard experiments plan context-diff-compaction --json < change.diff
 context-guard experiments emit context-diff-compaction --receipt-id <artifact-id> --reexpand-command "context-guard-artifact get <artifact-id> --full" --replacement-file compact-diff.txt --json < change.diff
 context-guard experiments plan visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --missed-context-note "outside crop omitted"
 context-guard experiments emit visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --ocr-text "visible text" --ocr-confidence 0.9 --ocr-error-note "glyph may be uncertain" --missed-context-note "outside crop omitted"
+context-guard experiments plan image-context-pack --json --exact-text-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "omitted text remains retrievable before any future image pack is used" --image-size 800,600 --packed-image-size 400,300
+context-guard experiments plan semantic-checkpoint --json --goal "preserve current task state for review" --constraint "do not rewrite protected evidence" --decision "ship plan-only semantic-checkpoint gate first" --open-task "verify exact fallback before any checkpoint is used" --evidence-handle "roadmap=contextguard-artifact:0123456789abcdef" --missing-provenance-note "none known after review" --unresolved-question "which provenance handle fields become mandatory later" --exact-context-fallback-receipt 0123456789abcdef --reexpand-command "context-guard-artifact get 0123456789abcdef --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "raw transcript remains retrievable before checkpoint metadata is used"
 context-guard experiments plan learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" < sanitized-prose.txt
 context-guard experiments emit learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --replacement-file compact-prose.txt < sanitized-prose.txt
 context-guard experiments plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
@@ -153,7 +155,11 @@ context-guard experiments enable output-receipt-trim --root .
 context-guard experiments disable output-receipt-trim --root .
 ```
 
-Use `--config <path>` only for an explicit project-local override. Registry entries include risk, gate requirements, explicit command/flag surfaces, and claim boundaries; hosted API token/cost savings still require provider-measured matched-task evidence. The registry can discover existing explicit-flag experiments such as `context-guard-trim-output --digest ... --artifact-receipt` and `context-guard-compress --protected-policy`, run dry-run advisory planners such as `context-guard experiments plan context-diff-compaction`, `context-guard experiments plan visual-crop-ocr`, `context-guard experiments plan learned-compression`, `context-guard experiments plan self-hosted-metrics-ledger`, `context-guard experiments plan local-proxy`, and design-only `context-guard experiments plan local-proxy-external-forwarding`, and run explicit local runtimes such as `context-guard experiments emit context-diff-compaction ...`, `context-guard experiments emit visual-crop-ocr ...`, `context-guard experiments emit learned-compression ...`, `context-guard experiments record self-hosted-metrics-ledger ...`, `context-guard experiments record local-proxy-runtime-gate ...`, `context-guard experiments serve local-proxy ...`, and successful-forward `context-guard experiments serve local-proxy --diagnostic-ledger-jsonl ...` diagnostics. The context-diff emit runtime only emits caller-supplied compact replacements when reviewable hunks, exact local artifact re-expand metadata whose stored content matches the input diff, and a smaller replacement are present; it does not generate semantic compression or permit hosted savings claims. The visual lane ships a dry-run planner plus an explicit local evidence-pack emitter: both use only caller-supplied full-evidence receipts, crop metadata, OCR text, confidence/error notes, and missed-context notes; screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file writes, and hosted savings claims are not shipped. The learned-compression lane ships a deny-by-default dry-run policy check plus an explicit local candidate emitter for caller-supplied compact prose with verified exact fallback content: learned/synthetic compressor execution, embeddings, rerankers, model calls, subprocesses, external services, generated replacement text, and hosted savings claims are not shipped. The self-hosted metrics planner emits a dry-run ledger-compatible preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost metrics; the dry-run preview does not write a ledger, while `context-guard experiments record self-hosted-metrics-ledger --ledger-jsonl ...` writes only local JSONL sidecars and still does not permit hosted API token/cost savings claims. The local-proxy planner emits localhost-only advisory metadata only, while `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` appends one local gate row only after localhost-only metadata and `--runtime-gate-ack`: it starts no listener, forwards no traffic, and performs no DNS lookup. `context-guard experiments serve local-proxy ...` is the separate forwarding MVP: it requires `--forwarding-gate-ack --once`, a private `--ready-file` nonce handoff, literal loopback bind/target IPs, no hostname DNS targets, nonzero ports, byte/time limits, and credential-free requests; it performs no external forwarding, no CONNECT/TLS proxying, no API-key persistence, and no hosted-savings claim. `--response-sandbox` can store safe UTF-8 response text as a sanitized local artifact receipt and return a compact envelope with redacted rehydration command templates; it does not claim hosted token/cost savings. `--diagnostic-ledger-jsonl` writes one shifted-cost diagnostic row only after a successful forwarded request, with no raw headers/bodies and no hosted-savings evidence. `plan local-proxy-external-forwarding` emits threat-model/allowlist/redaction/provider-evidence design metadata only and still starts no listener, performs no DNS lookup, calls no external service, forwards no traffic, persists no credentials, and does not ship an external proxy forwarding runtime. `experiments enable` records intent only; it does not run those helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
+`image-context-pack` is a plan-only/dry-run gate for pxpipe-inspired image/context packing evaluation. It requires exact text artifact fallback, protected-zone denial, provider-boundary acknowledgement for provider-measured matched tasks, missed-context guardrails, and acknowledgement in the plan output that `visual-crop-ocr` is the existing caller-supplied visual evidence-pack surface. It does not render images, run OCR, call models/providers, proxy traffic, store binary artifacts, emit replacement evidence, or support hosted token/cost savings.
+
+`semantic-checkpoint` is a plan-only/eval-only gate for reviewable task-state checkpoint planning. Its flags are optional at the CLI so incomplete dry runs can return JSON, but readiness remains blocked in the JSON payload until the plan includes a goal, exact fallback receipt, local re-expand command, provider-boundary acknowledgement, protected-zone policy `deny`, missed-context note, and provenance review note. `--missing-provenance-note` can be a review acknowledgement such as `none known after review`; allowed local re-expand shapes are `context-guard-artifact get <id> --full` and `context-guard artifact get <id> --full`. It has no `emit`, `record`, or `serve` runtime, no new `context-guard-semantic-checkpoint` binary, writes no files, edits no transcript or prompt, calls no model/provider/network, emits no replacement context, and makes no hosted token/cost savings claim.
+
+Use `--config <path>` only for an explicit project-local override. Registry entries include risk, gate requirements, explicit command/flag surfaces, and claim boundaries; hosted API token/cost savings still require provider-measured matched-task evidence. The registry can discover existing explicit-flag experiments such as `context-guard-trim-output --digest ... --artifact-receipt` and `context-guard-compress --protected-policy`, run dry-run advisory planners such as `context-guard experiments plan context-diff-compaction`, `context-guard experiments plan visual-crop-ocr`, `context-guard experiments plan learned-compression`, `context-guard experiments plan semantic-checkpoint`, `context-guard experiments plan self-hosted-metrics-ledger`, `context-guard experiments plan local-proxy`, and design-only `context-guard experiments plan local-proxy-external-forwarding`, and run explicit local runtimes such as `context-guard experiments emit context-diff-compaction ...`, `context-guard experiments emit visual-crop-ocr ...`, `context-guard experiments emit learned-compression ...`, `context-guard experiments record self-hosted-metrics-ledger ...`, `context-guard experiments record local-proxy-runtime-gate ...`, `context-guard experiments serve local-proxy ...`, and successful-forward `context-guard experiments serve local-proxy --diagnostic-ledger-jsonl ...` diagnostics. The context-diff emit runtime only emits caller-supplied compact replacements when reviewable hunks, exact local artifact re-expand metadata whose stored content matches the input diff, and a smaller replacement are present; it does not generate semantic compression or permit hosted savings claims. The visual lane ships a dry-run planner plus an explicit local evidence-pack emitter: both use only caller-supplied full-evidence receipts, crop metadata, OCR text, confidence/error notes, and missed-context notes; screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file writes, and hosted savings claims are not shipped. The learned-compression lane ships a deny-by-default dry-run policy check plus an explicit local candidate emitter for caller-supplied compact prose with verified exact fallback content: learned/synthetic compressor execution, embeddings, rerankers, model calls, subprocesses, external services, generated replacement text, and hosted savings claims are not shipped. The semantic-checkpoint lane ships only the plan/eval gate above: no runtime emit/record/serve surface, file-writing checkpoint store, transcript/prompt edit, provider/model/network-backed checkpointing, replacement context, new binary, or hosted savings claim is shipped. The self-hosted metrics planner emits a dry-run ledger-compatible preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost metrics; the dry-run preview does not write a ledger, while `context-guard experiments record self-hosted-metrics-ledger --ledger-jsonl ...` writes only local JSONL sidecars and still does not permit hosted API token/cost savings claims. The local-proxy planner emits localhost-only advisory metadata only, while `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` appends one local gate row only after localhost-only metadata and `--runtime-gate-ack`: it starts no listener, forwards no traffic, and performs no DNS lookup. `context-guard experiments serve local-proxy ...` is the separate forwarding MVP: it requires `--forwarding-gate-ack --once`, a private `--ready-file` nonce handoff, literal loopback bind/target IPs, no hostname DNS targets, nonzero ports, byte/time limits, and credential-free requests; it performs no external forwarding, no CONNECT/TLS proxying, no API-key persistence, and no hosted-savings claim. `--response-sandbox` can store safe UTF-8 response text as a sanitized local artifact receipt and return a compact envelope with redacted rehydration command templates; it does not claim hosted token/cost savings. `--diagnostic-ledger-jsonl` writes one shifted-cost diagnostic row only after a successful forwarded request, with no raw headers/bodies and no hosted-savings evidence. `plan local-proxy-external-forwarding` emits threat-model/allowlist/redaction/provider-evidence design metadata only and still starts no listener, performs no DNS lookup, calls no external service, forwards no traffic, persists no credentials, and does not ship an external proxy forwarding runtime. `experiments enable` records intent only; it does not run those helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
 
 Cross-agent rule snippets are advisory: the target agent may ignore them, so measure actual before/after behavior when you need a savings claim.
 

package/plugins/context-guard/bin/context-guard-experiments

@@ -46,6 +46,7 @@ MAX_VISUAL_OCR_TEXT_BYTES = 64_000
 MAX_LEARNED_COMPRESSION_INPUT_BYTES = 128_000
 MAX_LEARNED_COMPRESSION_REPLACEMENT_BYTES = 64_000
 MAX_LEARNED_COMPRESSION_ARTIFACT_METADATA_BYTES = 64_000
+IMAGE_CONTEXT_PACK_MAX_DIMENSION = 16_384
 MAX_SELF_HOSTED_METRICS_INPUT_BYTES = 64_000
 SELF_HOSTED_METRICS_SCHEMA_VERSION = "contextguard.bench.self-hosted-metrics.v1"
 SELF_HOSTED_METRICS_KEY = "self_hosted_metrics"
@@ -67,6 +68,9 @@ LOCAL_PROXY_DIAGNOSTIC_SCHEMA_VERSION = "contextguard.experiments.local-proxy-fo
 LOCAL_PROXY_READY_SCHEMA_VERSION = "contextguard.experiments.local-proxy-ready.v1"
 LOCAL_PROXY_EXTERNAL_DESIGN_SCHEMA_VERSION = "contextguard.experiments.local-proxy-external-forwarding-design.v1"
 LOCAL_PROXY_RESPONSE_SANDBOX_SCHEMA_VERSION = "contextguard.experiments.local-proxy-response-sandbox.v1"
+IMAGE_CONTEXT_PACK_PLAN_SCHEMA_VERSION = "contextguard.experiments.image-context-pack-plan.v1"
+SEMANTIC_CHECKPOINT_PLAN_SCHEMA_VERSION = "contextguard.experiments.semantic-checkpoint-plan.v1"
+IMAGE_CONTEXT_PACK_PROVIDER_BOUNDARY = "provider-measured-matched-tasks-required"
 LOCAL_PROXY_DEFAULT_BIND_HOST = "127.0.0.1"
 LOCAL_PROXY_DEFAULT_BIND_PORT = 0
 LOCAL_PROXY_DEFAULT_TARGET_HOST = "127.0.0.1"
@@ -259,6 +263,103 @@ EXPERIMENTS: tuple[Experiment, ...] = (
             "OCR confidence/error notes when OCR is present, and missed-context guardrails before human review."
         ),
     ),
+    Experiment(
+        id="image-context-pack",
+        name="Pxpipe-inspired image context pack planning gate",
+        summary=(
+            "Plan-only evaluation gate for pxpipe-inspired image/context packing without rendering images, "
+            "emitting visual artifacts, or changing runtime behavior."
+        ),
+        stability="experimental",
+        default_enabled=False,
+        risk_level="high",
+        claim_boundary=(
+            "Image/request byte reductions are proxy evidence only; hosted token/cost savings require "
+            "provider-measured matched successful tasks."
+        ),
+        gate_requirements=(
+            "explicit opt-in",
+            "verified exact text artifact fallback before omitted text is used",
+            "protected-zone denial",
+            "provider/model measurement boundary",
+            "missed-context guardrails",
+            "relation to visual-crop-ocr",
+        ),
+        runtime_status="available-plan-only",
+        commands=("context-guard experiments plan image-context-pack",),
+        opt_in_flags=(
+            "plan image-context-pack",
+            "--exact-text-fallback-receipt",
+            "--reexpand-command",
+            "--provider-boundary-ack",
+            "--protected-zone-policy deny",
+            "--missed-context-note",
+            "--image-size",
+            "--packed-image-size",
+        ),
+        config_effect=(
+            "Registry enablement records project-local intent only; image-context-pack exposes only a deterministic "
+            "plan command. It does not add an emit/record/serve runtime, render images, run OCR, call models, proxy "
+            "traffic, write binary artifacts, or duplicate the caller-supplied visual-crop-ocr evidence-pack emitter."
+        ),
+        evidence_contract=(
+            "The planner requires acknowledgements for explicit evaluation intent, verified exact text artifact fallback, "
+            "protected-zone denial, provider/model measured matched-task boundaries, missed-context review, and the fact that "
+            "visual-crop-ocr is the existing caller-supplied visual evidence-pack surface, not a verified "
+            "exact binary/image fallback."
+        ),
+    ),
+
+    Experiment(
+        id="semantic-checkpoint",
+        name="Semantic checkpoint planning gate",
+        summary=(
+            "Plan-only evaluation gate for semantic checkpoint metadata and provenance readiness without "
+            "emitting replacement context or changing runtime behavior."
+        ),
+        stability="experimental",
+        default_enabled=False,
+        risk_level="high",
+        claim_boundary=(
+            "Semantic checkpoint metadata is dry-run planning evidence only; it cannot replace raw context or "
+            "claim hosted token/cost savings without future provider-measured matched successful tasks."
+        ),
+        gate_requirements=(
+            "explicit planning goal",
+            "verified exact context fallback before checkpoint metadata is used",
+            "provider/model measurement boundary",
+            "protected-zone denial",
+            "missed-context guardrails",
+            "provenance review acknowledgement",
+        ),
+        runtime_status="available-plan-only",
+        commands=("context-guard experiments plan semantic-checkpoint",),
+        opt_in_flags=(
+            "plan semantic-checkpoint",
+            "--goal",
+            "--constraint",
+            "--decision",
+            "--open-task",
+            "--evidence-handle",
+            "--missing-provenance-note",
+            "--unresolved-question",
+            "--exact-context-fallback-receipt",
+            "--reexpand-command",
+            "--provider-boundary-ack",
+            "--protected-zone-policy deny",
+            "--missed-context-note",
+        ),
+        config_effect=(
+            "Registry enablement records project-local intent only; semantic-checkpoint exposes only a deterministic "
+            "plan command. It does not add an emit/record/serve runtime, call models/providers, proxy traffic, write "
+            "files, edit prompts/transcripts, replace context, or emit checkpoint candidates."
+        ),
+        evidence_contract=(
+            "The planner requires a goal, exact context artifact fallback, protected-zone denial, provider/model "
+            "measured matched-task boundary, missed-context notes, and provenance review notes before checkpoint metadata "
+            "is ready for plan review; raw context remains authoritative."
+        ),
+    ),
     Experiment(
         id="learned-compression",
         name="Learned/synthetic compression candidate gate",
@@ -1735,6 +1836,308 @@ def command_plan_visual_crop_ocr(args: argparse.Namespace) -> int:
     return 0
 
 
+def image_context_pack_size_payload(raw: str | None) -> tuple[dict[str, Any] | None, bool]:
+    size = parse_int_tuple(raw, count=2)
+    if raw is None or not str(raw).strip():
+        return None, True
+    if size is None:
+        return None, False
+    width, height = size
+    if width <= 0 or height <= 0:
+        return {"width": width, "height": height}, False
+    return {"width": width, "height": height}, True
+
+
+def image_context_pack_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
+    receipt_id = args.exact_text_fallback_receipt.strip() if args.exact_text_fallback_receipt else None
+    reexpand_command = args.reexpand_command.strip() if args.reexpand_command else None
+    reexpand_valid, fallback_blocker = valid_learned_reexpand_command(receipt_id, reexpand_command)
+    fallback_blocker_map = {
+        "missing_exact_fallback": "missing_exact_text_fallback",
+        "invalid_reexpand_command": "invalid_exact_text_reexpand_command",
+    }
+    source_size, source_size_valid = image_context_pack_size_payload(args.image_size)
+    packed_size, packed_size_valid = image_context_pack_size_payload(args.packed_image_size)
+    missed_context_notes = clean_values(args.missed_context_note)
+    protected_policy = (args.protected_zone_policy or "deny").strip().lower()
+
+    blockers: list[str] = []
+    if fallback_blocker:
+        blockers.append(fallback_blocker_map.get(fallback_blocker, fallback_blocker))
+    if not args.provider_boundary_ack:
+        blockers.append("missing_provider_measurement_boundary")
+    if not missed_context_notes:
+        blockers.append("missing_missed_context_note")
+    if protected_policy != "deny":
+        blockers.append("protected_zone_denial_required")
+    if not source_size_valid:
+        blockers.append("invalid_image_size")
+    if not packed_size_valid:
+        blockers.append("invalid_packed_image_size")
+    blockers = list(dict.fromkeys(blockers))
+
+    source_area = source_size["width"] * source_size["height"] if source_size and source_size_valid else None
+    packed_area = packed_size["width"] * packed_size["height"] if packed_size and packed_size_valid else None
+    area_delta = source_area - packed_area if source_area is not None and packed_area is not None else None
+    ready = not blockers
+
+    return {
+        "tool": TOOL_NAME,
+        "schema_version": CONFIG_SCHEMA_VERSION,
+        "plan_schema_version": IMAGE_CONTEXT_PACK_PLAN_SCHEMA_VERSION,
+        "experiment_id": "image-context-pack",
+        "mode": "dry_run",
+        "status": "ready_for_plan_review" if ready else "blocked_until_image_context_pack_gate_ready",
+        "plan_only": {
+            "command_advertised": True,
+            "emit_command_available": False,
+            "record_command_available": False,
+            "serve_command_available": False,
+            "runtime_behavior_changed": False,
+            "replacement_or_visual_evidence_emitted": False,
+        },
+        "external_services": {
+            "called": False,
+            "network": False,
+            "model_calls": False,
+            "ocr_service": None,
+            "image_service": None,
+            "proxy_forwarding": False,
+        },
+        "runtime_side_effects": {
+            "files_written": False,
+            "image_rendering": False,
+            "ocr_execution": False,
+            "image_parsing": False,
+            "binary_artifacts_written": False,
+            "proxy_forwarding": False,
+            "stable_runtime_behavior_changed": False,
+        },
+        "text_fallback": {
+            "required": True,
+            "available": bool(reexpand_valid),
+            "receipt_id": receipt_id,
+            "reexpand_command": reexpand_command,
+            "verified": False,
+            "must_be_verified_before_omitted_text_is_used": True,
+            "note": (
+                "This dry-run validates only local receipt/re-expand shape. A future runtime must verify exact "
+                "text artifact content before relying on omitted exact text."
+            ),
+        },
+        "protected_zones": {
+            "policy": protected_policy,
+            "override_allowed": False,
+            "denied_classes": [
+                "code",
+                "diffs",
+                "identifiers",
+                "hashes",
+                "paths",
+                "numeric_constants",
+                "json_keys",
+                "stack_frames",
+                "secrets",
+                "prompt_like_instructions",
+            ],
+        },
+        "image_pack_plan": {
+            "source_label": sanitize_self_hosted_text(args.source_label) if args.source_label else "manual-plan",
+            "source_image_size": source_size,
+            "packed_image_size": packed_size,
+            "source_area": source_area,
+            "packed_area": packed_area,
+            "area_delta": area_delta,
+            "area_reduction_is_proxy_only": area_delta is not None,
+            "image_or_request_byte_reductions_are_proxy_evidence_only": True,
+        },
+        "measurement_boundary": {
+            "provider_boundary_acknowledged": bool(args.provider_boundary_ack),
+            "provider_boundary_policy": IMAGE_CONTEXT_PACK_PROVIDER_BOUNDARY,
+            "provider_measured_matched_tasks_required_for_hosted_claims": True,
+            "provider_model_specific": True,
+            "hosted_api_token_savings_claim_allowed": False,
+            "hosted_api_cost_savings_claim_allowed": False,
+        },
+        "relation_to_visual_crop_ocr": {
+            "visual_crop_ocr_is_existing_surface": True,
+            "visual_crop_ocr_remains_caller_supplied_visual_evidence_pack": True,
+            "image_context_pack_is_planning_gate_not_duplicate_emitter": True,
+            "verified_exact_binary_or_image_fallback_claimed": False,
+        },
+        "review_plan": {
+            "readiness_blockers": blockers,
+            "missed_context_notes": missed_context_notes,
+            "next_steps": [
+                "Keep exact text artifact fallback verified before any future image/context packing omits source text.",
+                "Deny protected evidence zones before any future lossy visual packing is considered.",
+                "Measure provider/model token and cost fields on matched successful tasks before any hosted savings claim.",
+                "Use visual-crop-ocr only for caller-supplied visual evidence packs; this gate emits no images or evidence.",
+            ],
+        },
+        "claim_boundary": (
+            "Dry-run image-context-pack planning only; image/request byte reductions are proxy evidence and no hosted "
+            "token/cost savings claim is allowed without provider-measured matched successful tasks."
+        ),
+        "candidate_replacement": None,
+    }
+
+
+def command_plan_image_context_pack(args: argparse.Namespace) -> int:
+    payload = image_context_pack_plan_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        print("ContextGuard image-context-pack plan (dry-run only)")
+        print("No image rendering, OCR/image service, model call, proxy forwarding, binary artifact, or replacement was emitted.")
+        print(f"Status: {payload['status']}")
+        if payload["review_plan"]["readiness_blockers"]:
+            print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0
+
+
+def semantic_checkpoint_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
+    goal = args.goal.strip() if args.goal else None
+    receipt_id = args.exact_context_fallback_receipt.strip() if args.exact_context_fallback_receipt else None
+    reexpand_command = args.reexpand_command.strip() if args.reexpand_command else None
+    reexpand_valid, fallback_blocker = valid_learned_reexpand_command(receipt_id, reexpand_command)
+    fallback_blocker_map = {
+        "missing_exact_fallback": "missing_exact_context_fallback",
+        "invalid_reexpand_command": "invalid_exact_context_reexpand_command",
+    }
+    protected_policy = (args.protected_zone_policy or "deny").strip().lower()
+    missed_context_notes = clean_values(args.missed_context_note)
+    missing_provenance_notes = clean_values(args.missing_provenance_note)
+
+    blockers: list[str] = []
+    if not goal:
+        blockers.append("missing_goal")
+    if fallback_blocker:
+        blockers.append(fallback_blocker_map.get(fallback_blocker, fallback_blocker))
+    if not args.provider_boundary_ack:
+        blockers.append("missing_provider_measurement_boundary")
+    if protected_policy != "deny":
+        blockers.append("protected_zone_denial_required")
+    if not missed_context_notes:
+        blockers.append("missing_missed_context_note")
+    if not missing_provenance_notes:
+        blockers.append("missing_provenance_review")
+    blockers = list(dict.fromkeys(blockers))
+    ready = not blockers
+
+    return {
+        "tool": TOOL_NAME,
+        "schema_version": CONFIG_SCHEMA_VERSION,
+        "plan_schema_version": SEMANTIC_CHECKPOINT_PLAN_SCHEMA_VERSION,
+        "experiment_id": "semantic-checkpoint",
+        "mode": "dry_run",
+        "status": "ready_for_plan_review" if ready else "blocked_until_semantic_checkpoint_gate_ready",
+        "plan_only": {
+            "command_advertised": True,
+            "emit_command_available": False,
+            "record_command_available": False,
+            "serve_command_available": False,
+            "runtime_behavior_changed": False,
+            "replacement_context_emitted": False,
+        },
+        "external_services": {
+            "called": False,
+            "network": False,
+            "model_calls": False,
+            "provider_calls": False,
+            "proxy_forwarding": False,
+        },
+        "runtime_side_effects": {
+            "files_written": False,
+            "transcript_edited": False,
+            "prompt_edited": False,
+            "context_replaced": False,
+            "stable_runtime_behavior_changed": False,
+        },
+        "checkpoint_metadata": {
+            "goal": goal,
+            "constraints": clean_values(args.constraint),
+            "decisions": clean_values(args.decision),
+            "open_tasks": clean_values(args.open_task),
+            "evidence_provenance_handles": clean_values(args.evidence_handle),
+            "unresolved_questions": clean_values(args.unresolved_question),
+        },
+        "exact_context_fallback": {
+            "required": True,
+            "available": bool(reexpand_valid),
+            "receipt_id": receipt_id,
+            "reexpand_command": reexpand_command,
+            "verified": False,
+            "must_be_verified_before_checkpoint_metadata_is_used": True,
+            "allowed_reexpand_shapes": [
+                "context-guard-artifact get RECEIPT --full",
+                "context-guard artifact get RECEIPT --full",
+            ],
+        },
+        "protected_zones": {
+            "policy": protected_policy,
+            "override_allowed": False,
+            "denied_classes": [
+                "code",
+                "diffs",
+                "identifiers",
+                "hashes",
+                "paths",
+                "numeric_constants",
+                "json_keys",
+                "stack_frames",
+                "secrets",
+                "prompt_like_instructions",
+            ],
+        },
+        "measurement_boundary": {
+            "provider_boundary_acknowledged": bool(args.provider_boundary_ack),
+            "provider_boundary_policy": IMAGE_CONTEXT_PACK_PROVIDER_BOUNDARY,
+            "provider_measured_matched_tasks_required_for_hosted_claims": True,
+            "provider_model_specific": True,
+            "hosted_api_token_savings_claim_allowed": False,
+            "hosted_api_cost_savings_claim_allowed": False,
+        },
+        "provenance_review": {
+            "required": True,
+            "reviewed": bool(missing_provenance_notes),
+            "missing_provenance_notes": missing_provenance_notes,
+            "missing_provenance_warnings": [] if missing_provenance_notes else ["missing_provenance_review"],
+            "checkpoint_cannot_replace_raw_context_without_complete_provenance": True,
+        },
+        "review_plan": {
+            "readiness_blockers": blockers,
+            "missed_context_notes": missed_context_notes,
+            "next_steps": [
+                "Keep exact raw context fallback verified before checkpoint metadata is used.",
+                "Deny protected evidence zones before any semantic checkpoint summary is considered.",
+                "Keep provenance handles and missing-provenance review notes attached to checkpoint metadata.",
+                "Measure provider/model token and cost fields on matched successful tasks before any hosted savings claim.",
+            ],
+        },
+        "claim_boundary": (
+            "Dry-run semantic-checkpoint planning only; checkpoint metadata is not replacement context and no hosted "
+            "token/cost savings claim is allowed without provider-measured matched successful tasks."
+        ),
+        "candidate_replacement": None,
+    }
+
+
+def command_plan_semantic_checkpoint(args: argparse.Namespace) -> int:
+    payload = semantic_checkpoint_plan_payload(args)
+    if args.json:
+        emit_json(payload)
+    else:
+        print("ContextGuard semantic-checkpoint plan (dry-run only)")
+        print("No files, prompts, transcripts, model/provider calls, proxy forwarding, or replacement context were emitted.")
+        print(f"Status: {payload['status']}")
+        if payload["review_plan"]["readiness_blockers"]:
+            print(f"Readiness blockers: {', '.join(payload['review_plan']['readiness_blockers'])}")
+        print(payload["claim_boundary"])
+    return 0
+
+
 def visual_crop_ocr_evidence_pack_payload(args: argparse.Namespace) -> dict[str, Any]:
     payload = visual_crop_ocr_plan_payload(args)
     blockers = list(payload["review_plan"]["readiness_blockers"])
@@ -4467,6 +4870,58 @@ def build_parser() -> argparse.ArgumentParser:
     visual_ocr.add_argument("--json", action="store_true", help="Emit JSON output.")
     visual_ocr.set_defaults(func=command_plan_visual_crop_ocr)
 
+    image_context_pack = plan_sub.add_parser(
+        "image-context-pack",
+        help="Dry-run a plan-only pxpipe-inspired image/context packing gate without rendering images.",
+    )
+    image_context_pack.add_argument("--source-label", help="Safe label for this image/context packing plan.")
+    image_context_pack.add_argument("--image-size", help="Optional source image/context canvas size as width,height integers.")
+    image_context_pack.add_argument("--packed-image-size", help="Optional planned packed image size as width,height integers.")
+    image_context_pack.add_argument("--exact-text-fallback-receipt", help="Local exact text artifact receipt id for omitted source text.")
+    image_context_pack.add_argument("--reexpand-command", help="Local exact text re-expand command bound to the receipt id.")
+    image_context_pack.add_argument(
+        "--provider-boundary-ack",
+        action="store_true",
+        help="Acknowledge hosted claims require provider-measured matched successful tasks for the target model.",
+    )
+    image_context_pack.add_argument(
+        "--protected-zone-policy",
+        default="deny",
+        choices=("deny", "allow"),
+        help="Protected evidence handling; only deny can pass the plan gate.",
+    )
+    image_context_pack.add_argument("--missed-context-note", action="append", help="Potential context omitted by a future pack. Repeatable.")
+    image_context_pack.add_argument("--json", action="store_true", help="Emit JSON output.")
+    image_context_pack.set_defaults(func=command_plan_image_context_pack)
+
+    semantic_checkpoint = plan_sub.add_parser(
+        "semantic-checkpoint",
+        help="Dry-run a plan-only semantic checkpoint metadata gate without replacing raw context.",
+    )
+    semantic_checkpoint.add_argument("--goal", help="Planning goal for the semantic checkpoint metadata.")
+    semantic_checkpoint.add_argument("--constraint", action="append", help="Constraint the checkpoint metadata must preserve. Repeatable.")
+    semantic_checkpoint.add_argument("--decision", action="append", help="Decision captured by the checkpoint metadata. Repeatable.")
+    semantic_checkpoint.add_argument("--open-task", action="append", help="Open task captured by the checkpoint metadata. Repeatable.")
+    semantic_checkpoint.add_argument("--evidence-handle", action="append", help="Evidence/provenance handle supporting the checkpoint. Repeatable.")
+    semantic_checkpoint.add_argument("--missing-provenance-note", action="append", help="Missing provenance review note or 'none known after review'. Repeatable.")
+    semantic_checkpoint.add_argument("--unresolved-question", action="append", help="Unresolved question for checkpoint review. Repeatable.")
+    semantic_checkpoint.add_argument("--exact-context-fallback-receipt", help="Local exact raw context artifact receipt id.")
+    semantic_checkpoint.add_argument("--reexpand-command", help="Local exact context re-expand command bound to the receipt id.")
+    semantic_checkpoint.add_argument(
+        "--provider-boundary-ack",
+        action="store_true",
+        help="Acknowledge hosted claims require provider-measured matched successful tasks for the target model.",
+    )
+    semantic_checkpoint.add_argument(
+        "--protected-zone-policy",
+        default="deny",
+        choices=("deny", "allow"),
+        help="Protected evidence handling; only deny can pass the plan gate.",
+    )
+    semantic_checkpoint.add_argument("--missed-context-note", action="append", help="Potential context missed by checkpoint metadata. Repeatable.")
+    semantic_checkpoint.add_argument("--json", action="store_true", help="Emit JSON output.")
+    semantic_checkpoint.set_defaults(func=command_plan_semantic_checkpoint)
+
     self_hosted = plan_sub.add_parser(
         "self-hosted-metrics-ledger",
         help="Dry-run self-hosted/local metrics ledger sidecar evidence without writing a ledger.",
@@ -4757,7 +5212,7 @@ def normalize_negative_csv_option_values(argv: list[str] | None) -> list[str] |
         argv = sys.argv[1:]
     normalized: list[str] = []
     pending_csv_option: str | None = None
-    csv_options = {"--crop-bounds"}
+    csv_options = {"--crop-bounds", "--image-size", "--packed-image-size"}
     for token in argv:
         if pending_csv_option is not None:
             normalized.append(f"{pending_csv_option}={token}")

package/plugins/context-guard/bin/context-guard-rewrite-bash

@@ -19,6 +19,7 @@ import sys
 SHELL_OPERATOR_TOKENS = {";", ";;", ";&", ";;&", "&", "&&", "|", "||", "<", ">", "<<", ">>", "<>", "(", ")"}
 SHELL_OPERATOR_CHARS = frozenset(";&|<>()")
 ENV_ASSIGNMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*")
+SAFE_PIPE_FILTER_BASENAMES = frozenset({"cat", "head", "tail", "wc", "sort", "uniq"})
 WRAPPER_BASENAMES = frozenset({
     "trim_command_output.py",
     "context-guard-trim-output",
@@ -164,6 +165,59 @@ def split_single_safe_command(command: str) -> list[str] | None:
     return argv
 
 
+def split_safe_sanitizer_pipeline(command: str) -> list[list[str]] | None:
+    """Return argv segments for a narrow read-only pipeline safe to sanitizer-wrap.
+
+    Compound search/diff/log commands are useful in practice (`git diff | cat`,
+    `rg token . | head`), but arbitrary shell operators can branch output to
+    files/network or change control flow before the sanitizer sees it.  This
+    helper therefore allows only plain `|` pipelines where the first segment is
+    sanitizer-worthy and every later segment is a simple stdout filter.  It
+    intentionally rejects redirection, here-doc/string, `tee`, `curl`, `&&`,
+    command substitution, and other shell syntax.
+    """
+    if not command.strip():
+        return None
+    if any(char in command for char in "\n\r\t`"):
+        return None
+    if "$(" in command or "${" in command:
+        return None
+    try:
+        lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        tokens = list(lexer)
+    except ValueError:
+        return None
+    if "|" not in tokens:
+        return None
+
+    segments: list[list[str]] = [[]]
+    for token in tokens:
+        is_operator = token in SHELL_OPERATOR_TOKENS or (
+            any(char in SHELL_OPERATOR_CHARS for char in token)
+            and all(char in SHELL_OPERATOR_CHARS for char in token)
+        )
+        if is_operator:
+            if token != "|":
+                return None
+            if not segments[-1]:
+                return None
+            segments.append([])
+            continue
+        if any(char in token for char in "`\n\r\t"):
+            return None
+        if "$(" in token or "${" in token:
+            return None
+        segments[-1].append(token)
+    if not segments or not segments[-1] or len(segments) < 2:
+        return None
+    if not (is_sanitizable_output_command(segments[0]) or is_log_streaming_command(segments[0])):
+        return None
+    if not all(is_safe_pipe_filter(segment) for segment in segments[1:]):
+        return None
+    return segments
+
+
 def command_basename(command: str) -> str:
     return os.path.basename(command)
 
@@ -214,6 +268,70 @@ def npm_script_args(rest: list[str]) -> list[str]:
     return rest[i:]
 
 
+def _filter_args_are_stdin_only(first: str, args: list[str]) -> bool:
+    """Accept small, option-only filter argv forms that do not name files."""
+    if first == "cat":
+        return not args
+    long_no_value_options = {
+        "head": set(),
+        "tail": set(),
+        "wc": {"--bytes", "--chars", "--lines", "--words"},
+        "sort": {"--ignore-leading-blanks", "--dictionary-order", "--ignore-case", "--general-numeric-sort", "--human-numeric-sort", "--numeric-sort", "--reverse", "--unique"},
+        "uniq": {"--count", "--repeated", "--unique", "--ignore-case"},
+    }.get(first, set())
+    short_no_value_chars = {
+        "head": set(),
+        "tail": {"f", "F", "r"},
+        "wc": {"c", "m", "l", "w"},
+        "sort": {"b", "d", "f", "g", "h", "n", "r", "u"},
+        "uniq": {"c", "d", "u", "i"},
+    }.get(first, set())
+    value_options = {"-n", "--lines", "-c", "--bytes"} if first in {"head", "tail"} else set()
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            return i == len(args) - 1
+        if arg.startswith("--") and "=" in arg:
+            name, value = arg.split("=", 1)
+            if name not in value_options:
+                return False
+            if not re.fullmatch(r"[+-]?\d+[KkMmGg]?", value):
+                return False
+            i += 1
+            continue
+        if arg in value_options:
+            if i + 1 >= len(args):
+                return False
+            if not re.fullmatch(r"[+-]?\d+[KkMmGg]?", args[i + 1]):
+                return False
+            i += 2
+            continue
+        if arg in long_no_value_options:
+            i += 1
+            continue
+        if arg.startswith("--"):
+            return False
+        if arg.startswith("-") and arg != "-":
+            if not set(arg[1:]).issubset(short_no_value_chars):
+                return False
+            i += 1
+            continue
+        if arg.startswith("-"):
+            return False
+        return False
+    return True
+
+
+def is_safe_pipe_filter(argv: list[str]) -> bool:
+    if not argv:
+        return False
+    first = command_basename(argv[0])
+    if first not in SAFE_PIPE_FILTER_BASENAMES:
+        return False
+    return _filter_args_are_stdin_only(first, argv[1:])
+
+
 def is_noisy_command(argv: list[str]) -> bool:
     argv = strip_env_prefix(argv)
     if not argv:
@@ -423,6 +541,16 @@ def build_sanitized_command(wrapper: str, command: str) -> str:
     return shlex.join(wrapped_argv)
 
 
+def print_updated_command(wrapped: str) -> None:
+    response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "updatedInput": {"command": wrapped},
+        }
+    }
+    print(json.dumps(response, ensure_ascii=False))
+
+
 def main() -> int:
     if any(arg in {"-h", "--help"} for arg in sys.argv[1:]):
         print("ContextGuard helper: context-guard-rewrite-bash")
@@ -450,11 +578,25 @@ def main() -> int:
     argv = split_single_safe_command(command)
     if not argv:
         if unparseable_command_needs_sanitizer(command):
-            deny(
-                "Search/diff/log command contains shell operators that cannot be safely rewritten. "
-                "Run the command through context-guard-sanitize-output explicitly, simplify it, or set "
-                f"{FAIL_OPEN_ENV}=1 to run unsanitized intentionally."
-            )
+            safe_pipeline = split_safe_sanitizer_pipeline(command)
+            if safe_pipeline is None:
+                deny(
+                    "Search/diff/log command contains shell operators that are not in ContextGuard's "
+                    "read-only pipe allowlist. Simplify to a plain pipeline ending in cat/head/tail/wc/sort/uniq, "
+                    "run context-guard-sanitize-output explicitly after review, or set "
+                    f"{FAIL_OPEN_ENV}=1 to run unsanitized intentionally."
+                )
+                return 0
+            wrapper = find_wrapper("sanitize")
+            if wrapper is None:
+                deny(
+                    "Search/diff/log command blocked because it contains shell operators and "
+                    "context-guard-sanitize-output is not installed next to context-guard-rewrite-bash. "
+                    "Install the sanitizer or set "
+                    f"{FAIL_OPEN_ENV}=1 to run unsanitized intentionally."
+                )
+                return 0
+            print_updated_command(build_sanitized_command(wrapper, command))
             return 0
         print_noop()
         return 0
@@ -490,13 +632,7 @@ def main() -> int:
         print("{}")
         return 0
 
-    response = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "updatedInput": {"command": wrapped},
-        }
-    }
-    print(json.dumps(response, ensure_ascii=False))
+    print_updated_command(wrapped)
     return 0