Add telemetry batch routing advisor

README.ko.md

@@ -131,7 +131,7 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 | 출력 축약과 민감정보 가림 | 테스트·빌드·검색·diff 출력을 작게 만들고, 에이전트 컨텍스트에 들어가기 전에 민감해 보이는 값을 가립니다. |
 | 선언형 출력 필터 | 사용자 정의 JSON DSL로 성공 출력만 명시적으로 줄이고, 보호해야 하는 실패 출력은 원문 stdout/stderr와 종료 코드를 보존합니다. |
 | 로컬 로그 보관소 | 큰 로그를 대화 밖 로컬 저장소에 보관하고, 요약 정보나 요청한 줄 범위만 다시 가져옵니다. |
-| Anthropic 비용 가드 | `context-guard cost preflight/observe/ledger/compile`이 cache 위험과 비용 범위를 추정하고, 원문 대신 keyed HMAC fingerprint만 저장하며, `--enforce`를 명시하지 않으면 경고만 합니다. |
+| Anthropic 비용 가드 | `context-guard cost preflight/observe/ledger/compile`이 cache 위험과 비용 범위를 추정하고, `context-guard route-advisor`가 로컬 총비용·batchability route 후보를 요약하며, ledger를 쓸 때도 원문 대신 keyed HMAC fingerprint만 저장합니다. `--enforce`를 명시하지 않으면 경고만 합니다. |
 | 예산 기반 컨텍스트 패커 | 우선순위가 있는 로컬 파일 근거를 바이트 예산 안의 Markdown 팩으로 조립하고, 로컬 신호에서 `build`용 manifest를 추천하며, `--explain`, `--adaptive-k`, `--symbol-memory`로 로컬 자문 메타데이터를 덧붙일 수 있습니다. |
 | Tool/MCP schema pruner | 로컬 catalog에서 bounded top-k tool/schema 자문 리포트를 만들고, compact 요약 기록과 전체 가림 처리된 payload 재조회 경로를 남깁니다. |
 | 보수적 stdin 압축기 | 선택한 JSON, diff, 로그, 검색 출력, 코드, 산문을 줄이고, 관측 바이트 근거와 추정 토큰 proxy를 함께 표시합니다. `--mode readable`은 exact fallback 안내가 있는 opt-in 산문 preview를 추가합니다. |
@@ -287,6 +287,15 @@ long-command 2>&1 | ./plugins/context-guard/bin/context-guard-artifact store --c
 
 `context-guard-tool-prune`은 로컬 tool 또는 MCP catalog를 결정적 lexical heuristic(어휘 기반 휴리스틱)으로 순위화해 제한된 top-k 자문 리포트를 만듭니다. inline schema는 관측된 UTF-8 바이트 예산을 지키고, 누락되거나 예산 때문에 생략된 schema는 `.context-guard/tool-prune`의 compact 요약 기록과 별도 가림 처리 payload로 다시 조회할 수 있습니다. 이 기능은 안내용이며 MCP 설정을 변경하지 않습니다. 토큰 값은 provider가 측정한 절감 수치가 아니라 추정 proxy입니다.
 
+### 총비용, batchability, routing 후보 자문
+
+```bash
+./plugins/context-guard/bin/context-guard route-advisor --workload workload.json --json
+./plugins/context-guard/bin/context-guard-cost route-advisor --feature batch_api=true --feature structured_outputs=true --json < workload.json
+```
+
+`context-guard route-advisor`는 로컬 passive advisor입니다. caller가 제공한 workload JSON, provider feature 선언, usage telemetry, 외부·로컬 shifted cost를 읽고 total-cost accounting, batchability blocker, batch API·prompt-cache prefix 보존·structured outputs·저비용 모델 평가 같은 route 후보를 출력합니다. queue를 시작하거나 provider를 호출하거나 pricing 문서를 새로 가져오지 않으며, provider feature는 caller-supplied 또는 unknown/recheck-required로 표시합니다. 추천은 후보일 뿐이고, hosted token/cost 절감 주장은 여전히 matched successful task, 비열등 quality gate, shifted-cost evidence가 있어야 합니다.
+
 ### 선택한 로컬 텍스트를 보수적으로 압축하기
 
 ```bash

README.md

@@ -134,7 +134,7 @@ Legacy local CLI wrappers (`claude-token-*`, `claude-read-symbol`, `claude-trim-
 | Output trimming and sanitizing | Keeps test, build, search, and diff output compact while redacting likely secrets before they enter agent context. |
 | Declarative output filter | Opt-in JSON DSL for user-owned command filters with protected failure passthrough and validation before use. |
 | Local artifact store | Saves large sanitized logs outside the conversation and returns compact receipts or exact requested slices. |
-| Anthropic cost guard | `context-guard cost preflight/observe/ledger/compile` estimates cache-risk and cost ranges, stores only keyed HMAC fingerprints, and stays passive unless `--enforce` is explicit. |
+| Anthropic cost guard | `context-guard cost preflight/observe/ledger/compile` estimates cache-risk and cost ranges, `context-guard route-advisor` summarizes local total-cost/batchability route candidates, stores only keyed HMAC fingerprints where a ledger is used, and stays passive unless `--enforce` is explicit. |
 | Budgeted context packer | Assembles prioritized local file evidence into a byte-budgeted Markdown pack, can suggest a build-compatible manifest from local signals, adds `--explain` for compact local selection reasons plus bounded repo-map metadata, and adds opt-in `--adaptive-k` / `--symbol-memory` advisory metadata. |
 | Tool/MCP schema pruner | Emits bounded top-k tool/schema advisory reports from local catalogs with compact receipts and full sanitized payload retrieval. |
 | Conservative stdin compressor | Shrinks selected JSON, diffs, logs, search output, code, and prose with observed byte evidence and estimated token proxies; `--mode readable` adds an opt-in readable prose preview with exact fallback guidance. |
@@ -314,6 +314,15 @@ The packer uses deterministic standard-library heuristics only: no network, mode
 
 `context-guard-cache-score` is a local static lint for prompt/request layout. It estimates total and cacheable-prefix size with a tokenizer-free char/4 proxy, warns about dynamic-looking values near the prefix, and records provider caveats for OpenAI, Anthropic, Gemini, or a generic threshold. It does not call providers, store raw prompts, estimate prices, observe cache hits, or prove token/cost savings; verify real cache behavior with provider usage telemetry.
 
+### Advise on total cost, batchability, and routing
+
+```bash
+./plugins/context-guard/bin/context-guard route-advisor --workload workload.json --json
+./plugins/context-guard/bin/context-guard-cost route-advisor --feature batch_api=true --feature structured_outputs=true --json < workload.json
+```
+
+`context-guard route-advisor` is a local, passive advisor. It reads caller-supplied workload JSON, provider feature declarations, usage telemetry, and shifted external/local costs, then emits total-cost accounting, batchability blockers, and candidate routes such as batch API, prompt-cache prefix preservation, structured outputs, or cheaper-model evaluation. It does not start a queue, call providers, refresh pricing docs, or treat bundled provider feature knowledge as authoritative; unknown or caller-supplied features are marked recheck-required. Recommendations are candidates only, and hosted token/cost savings claims still require matched successful tasks with non-inferior quality and shifted-cost evidence.
+
 ### Compress selected local text conservatively
 
 ```bash

context-guard-kit/README.md

@@ -16,6 +16,7 @@ Claude Code CLI 컨텍스트 낭비를 줄이기 위한 도구 모음입니다.
 - `context_pack.py` — 우선순위가 있는 로컬 파일 근거를 바이트 예산 안의 Markdown context pack으로 조립하고, 로컬 query/diff/output 신호에서 build manifest를 추천합니다.
 - `context_filter.py` — 사용자 소유 JSON DSL로 성공 출력 라인 필터를 적용하되, 보호해야 할 실패 출력은 원문 그대로 통과시킵니다.
 - `tool_schema_pruner.py` — 로컬 tool/MCP catalog를 top-k schema 자문 리포트로 줄이고, 전체 정제된 schema는 receipt/payload로 재조회할 수 있게 합니다.
+- `cost_guard.py` — provider usage/cache cost preflight·observe·compile과 local-only route-advisor total-cost/batchability 후보를 출력합니다.
 - `benchmark_runner.py` — 고정 task/variant fixture로 A/B token/cost 절감 benchmark, cost-shift ledger, report를 생성합니다.
 - `setup_wizard.py` — 설치 후 project-local `.claude/settings.json`을 대화형으로 선택하고 병합합니다.
 - `failed_attempt_nudge.py` — 반복 Bash 실패 시 `/clear`/`/compact`와 전략 전환을 짧게 권유합니다.
@@ -64,6 +65,8 @@ python3 context-guard-kit/sanitize_output.py -- git diff
 
 `cost_guard.py compile`은 section manifest의 `protected`, `semantic_sensitive`, `protected_zone_classes`, `content_type`, `volatile`, `ttl`, `bytes` 필드를 읽어 `protected_zone_policy`와 `transform_policy`를 출력합니다. `protected=true`와 `volatile=true`가 같이 있으면 volatile이 cache ordering을 tail 쪽으로 보내고, protection은 transform/retrieval 정책만 제어합니다. 대용량 protected section에는 local artifact retrieval을 안내하지만 provider prompt cache를 대체한다고 주장하지 않습니다.
 
+`cost_guard.py route-advisor`와 dispatcher alias `context-guard route-advisor`는 caller-supplied workload JSON, provider feature 선언, usage telemetry, shifted external/local cost sidecar를 합쳐 local-only total-cost/batchability/routing 후보 자문을 출력합니다. queue를 시작하거나 provider를 호출하지 않고, provider feature matrix를 authoritative하게 내장하지 않으며, batch API·prompt cache·structured outputs·lower-cost model 추천은 matched successful task와 shifted-cost evidence 전까지 절감 주장으로 해석하면 안 됩니다.
+
 `experimental_registry.py`는 `context-guard experiments`의 project-local 메타데이터 진입점입니다. 기본 비활성이며, `enable`/`disable`은 `.context-guard/experiments.json`만 갱신하고 기존 헬퍼 동작은 여전히 명시적 flag가 있어야 바뀝니다. 레지스트리는 receipt-backed 출력 축약 경로(`trim_command_output.py --digest markdown|json --artifact-receipt`)와 protected-zone 정책 경로(`context_compress.py --protected-policy`, `cost_guard.py compile`의 protected section 메타데이터)를 명시적 flag 실험으로 표시합니다.
 
 `experimental_registry.py plan context-diff-compaction`은 읽기 전용 dry-run planner이고, `experimental_registry.py emit context-diff-compaction --receipt-id ... --reexpand-command ...`는 명시적 로컬 runtime입니다. `plan`은 diff 파일과 hunk만 요약하고 replacement text를 만들지 않습니다. `emit`은 review 가능한 hunk, 입력 diff와 일치하는 로컬 보관본 내용, 유효한 재확장 메타데이터, 더 작은 caller-supplied replacement가 모두 있을 때만 caller-supplied compact replacement text를 출력합니다. 로컬 보관본 내용을 검증하지만 re-expand 명령을 실행하거나 hosted savings를 주장하지 않습니다.

context-guard-kit/context_guard_commands.py

@@ -82,6 +82,8 @@
     "tool-prune": ("context-guard-tool-prune",),
     "compress": ("context-guard-compress",),
     "cost": ("context-guard-cost",),
+    "route-advisor": ("context-guard-cost", "route-advisor"),
+    "route": ("context-guard-cost", "route-advisor"),
     "cache-score": ("context-guard-cache-score",),
     "bench": ("context-guard-bench",),
     "read-symbol": ("context-guard-read-symbol",),
@@ -186,6 +188,7 @@
 DISPATCHER_SMOKE_CASES: tuple[dict[str, Any], ...] = (
     {"entrypoint": "context-guard", "args": ["experiments", "list", "--json"], "mode": "json"},
     {"entrypoint": "context-guard", "args": ["cost", "--help"], "mode": "text"},
+    {"entrypoint": "context-guard", "args": ["route-advisor", "--help"], "mode": "text"},
     {"entrypoint": "context-guard", "args": ["cache-score", "--help"], "mode": "text"},
     {"entrypoint": "context-guard-pack", "args": ["suggest", "--help"], "mode": "text"},
     {"entrypoint": "context-guard-pack", "args": ["auto", "--help"], "mode": "text"},