Skip to content

Phase 1B — Local Investigation Plan

  • Date: 2026-08-01
  • Status: Approved and executed (2026-08-02) — read-only workstreams ran as written; the [NEEDS SEPARATE APPROVAL] steps were deferred and not run. Approval recorded in Decisions.md, ADR-0003.
  • Phase: Phase 1B — Local Investigation
  • Approval flags: steps that modify configuration or route live traffic are marked [NEEDS SEPARATE APPROVAL] and are not part of the default read-only execution.

Objective

Verify, from the local environment, how Claude Code and the local OmniRoute instance exchange model and runtime information, so that the source of the generic model label and any viable resolved-provider data source are traced with evidence. No statusline is implemented in this phase.

Scope and constraints

  • Read-only by default. No edits to .claude/settings.local.json, user settings, OmniRoute configuration, or Docker state unless a step is separately approved.
  • No live inference requests. Querying the gateway's chat endpoints routes traffic to external providers and incurs cost. The default plan only queries endpoints that read stored data or routing tables (usage logs, request logs, models catalog, model-resolve). Any live request is [NEEDS SEPARATE APPROVAL].
  • Secrets. The OmniRoute token lives in .claude/settings.local.json (gitignored). It is never echoed, logged, or committed. API auth uses an environment variable, never an inline command argument. Captured evidence is redacted before it is written to Findings/ or committed.
  • No sensitive request content. Transcripts and logs may contain prompts and request bodies. Inspection extracts only model/route/session metadata, never message content.
  • No implementation. The statusline design and any code remain out of scope.

Authoritative references

  • code.claude.com/docs/en/statusline — official statusline contract (fetched 2026-08-01; authoritative). Confirmed: JSON on stdin; fields incl. model.id, model.display_name, workspace.current_dir, session_id, transcript_path, cost, context_window, rate_limits; no documented resolved-provider field; no CLI payload-dump command; claude --debug logs statusline exit code/stderr; 300 ms debounce; slow scripts are cancelled; statusline runs locally and consumes no API tokens.
  • Research/2026-08-01 - Perplexity Research Round 01..04 — external leads to test locally (OmniRoute Auto-Combo wiki, API reference, DeepWiki logs-and-audit).
  • References/Bibliography.md — source provenance; verification statuses updated as each source is assessed locally.
  • Architecture.md — investigation boundaries and the evidence chain.

Workstream A — Statusline input contract

Goal: document what Claude Code actually sends to a statusline in this installation, and what the model label is.

  • A1. Locate the active statusline configuration. Inspect ~/.claude/settings.json (user) and project settings for statusLine and subagentStatusLine. Record the configured command. (Read-only; redact any secrets.)
  • A2. Capture the real payload.
  • Primary (read-only): locate the current session transcript under ~/.claude/projects/-Users-unscriptedbykramy-Claude-AI-Engineering-Lab/. Inspect the JSONL structure and extract per-message model/route metadata only (requested model, response model field if present, usage). Record whether anything beyond the requested label appears.
  • Experimental [NEEDS SEPARATE APPROVAL]: temporarily set statusLine to a capture script that writes stdin to a file, run a short Claude session, then restore the prior config. Yields the exact payload bytes. claude --debug can be enabled for exit code/stderr on the first invocation.
  • A3. Document the observed schema. Compare observed fields against the documented schema; list present, absent, and null fields; record the exact model.id / model.display_name values and whether they equal auto/cheap or a resolved provider name.

Workstream B — OmniRoute local topology

Goal: identify the local OmniRoute process, its storage, and its read-only API surface.

  • B1. Confirm the process and container. docker ps to identify the OmniRoute container (image, name, port mapping). Confirm the localhost:<gateway-port> listener belongs to it. (Read-only.)
  • B2. Locate configuration and data storage. Inspect container mounts / volumes (read-only) to find config and the SQLite database. Confirm the call_logs table and inspect its schema via sqlite3 .schema (metadata only).
  • B3. Inventory read-only endpoints. Query with the local token from an environment variable (never inline):
  • GET /v1/models — catalog.
  • GET /api/usage/request-logs — request-level logs.
  • GET /api/usage/logs — usage logs.
  • GET /api/sessions — session metadata.
  • GET /api/analytics/auto-routing — aggregate routing stats.
  • GET /api/cloud/model/resolve?model=auto/cheap — resolve a logical model via the local routing table. Record reachability, auth requirements, and response shape for each, redacting sensitive fields. Do not follow links that trigger inference.

Workstream C — Resolved-route exposure

Goal: determine whether and where the resolved provider/model is observable, and whether it can reach the statusline.

  • C1. Per-request log fields. From request-logs / call_logs rows, list the fields captured per request: requested model, resolved provider/model, routing strategy, session id, latency, token usage, cost. Determine whether resolved provider/model is actually recorded (DeepWiki claimed the columns exist; verify against local schema and rows).
  • C2. Session correlation. Correlate a session_id from the current transcript with request-log rows to see whether the resolved route for a known real request is recoverable. This tests the "reliable interface" question.
  • C3. Header exposure. X-OmniRoute-Session-Id / X-OmniRoute-Cache header observation requires a live gateway request [NEEDS SEPARATE APPROVAL]. Deferred unless approved.
  • C4. Bridge to the statusline. Determine whether any observed field (payload, transcript, logs, endpoint) carries resolved-provider data that a statusline could consume locally, and whether that consumption can be read-only and low-latency.

Workstream D — Failure and fallback behavior

Goal: document behavior when metadata is missing or infrastructure is unavailable.

  • D1. Generic label. Confirm whether model.display_name is auto/cheap (or auto) and record what that implies for any statusline rendering.
  • D2. Absent/null fields. From the captured payload and transcript, note which fields are absent or null early in a session (per the docs: context_window.current_usage, used_percentage, rate_limits are only populated after API responses; session_name, prompt_id, pr, worktree, etc. are conditional).
  • D3. OmniRoute-down behavior. Requires stopping/restarting the container [NEEDS SEPARATE APPROVAL]. Deferred; documented as a planned experiment.
  • D4. Latency and reliability constraints. Record the doc-established constraints (300 ms debounce, script cancellation, no token cost, terminal-width bounded output) as design inputs.

Evidence capture protocol

  • Raw observations and captures are written to Findings/ as dated reports, one per workstream or consolidated as warranted:
  • Findings/2026-08-01 - Phase 1B - Statusline Input Contract.md
  • Findings/2026-08-01 - Phase 1B - OmniRoute Topology and Logs.md
  • Findings/2026-08-01 - Phase 1B - Resolved-Route Exposure.md
  • Every claim is tagged per CLAUDE.md: Verified fact, Observation, Hypothesis, or Recommendation, with evidence.
  • All captures are redacted of tokens, prompts, and request content before being committed.
  • No external claims become project facts without local evidence.

Deliverables

  • Investigation reports in Findings/ (above).
  • Updated open questions in Knowledge-Base.md (resolved vs still open).
  • Verified data-flow update in Architecture.md (only what local evidence supports).
  • Updated verification statuses in References/Bibliography.md for sources assessed locally.

Gate (from Roadmap, Phase 1B)

Phase 1B is complete when:

  1. The major statusline fields and integration points are traced locally.
  2. The source of the generic model label (auto / auto/cheap) is explained or explicitly marked unresolved.
  3. No material implementation assumption remains undocumented.

Approval requests

To execute the default read-only plan, approve this plan. Separately, the following are not included unless approved:

  • A temporary capture script under statusLine (Workstream A2 experimental path).
  • Any live request through the gateway, including header observation (Workstream C3).
  • Stopping/restarting the OmniRoute container to test down-behavior (Workstream D3).