Show the smart-routing savings estimate in the Claude mod

README.md

@@ -269,14 +269,15 @@ Use `SMART_ROUTER_CONFIG_VERSION` at launch to select a smart-routing configurat
 Each version defines separate Claude Code and Codex flag mappings; the existing versions
 use identical mappings for both agents. The Claude-only version disables routing for Codex:
 
-| Version | Routed agents | Subagent routing | First-prompt routing | Orchestrator |
-| --- | --- | --- | --- | --- |
-| `first_prompt_and_subagent_no_orch_v0` | Claude, Codex | On | On | Off |
-| `subagent_only_v0` | Claude, Codex | On | Off | Off |
-| `subagent_only_v1` | Claude, Codex | On | Off | Off |
-| `subagent_orch_v0` | Claude, Codex | On | Off | On |
-| `subagent_orch_v1` | Claude, Codex | On | Off | On |
-| `subagent_orch_v0_claude_only` | Claude | On | Off | On |
+| Version | Routed agents | Subagent routing | First-prompt routing | Orchestrator | Claude savings |
+| --- | --- | --- | --- | --- | --- |
+| `first_prompt_and_subagent_no_orch_v0` | Claude, Codex | On | On | Off | Off |
+| `subagent_only_v0` | Claude, Codex | On | Off | Off | Off |
+| `subagent_only_v1` | Claude, Codex | On | Off | Off | Off |
+| `subagent_orch_v0` | Claude, Codex | On | Off | On | Off |
+| `subagent_orch_v1` | Claude, Codex | On | Off | On | Off |
+| `subagent_orch_v0_claude_only` | Claude | On | Off | On | Off |
+| `subagent_orch_savings_v0` | Claude, Codex | On | Off | On | On |
 
 `first_prompt_and_subagent_no_orch_v0` is the customer configuration for first-prompt
 and subagent routing without orchestration: `ENABLE_SMART_ROUTING_V2=1`,
@@ -294,10 +295,21 @@ and sets all three flags to `"0"` for Codex. Codex uses its ordinary launch and
 managed default model, without routing or orchestration. Explicit launch/session
 on/off controls retain their existing precedence over presets.
 
+`subagent_orch_savings_v0` uses the routing and orchestration flags from `subagent_orch_v1`
+and sets `ENABLE_SMART_ROUTING_SAVINGS=1`. Savings tracking, endpoint-price refresh,
+pricing, and the above-prompt savings/orchestrator-version row are opt-in and currently
+implemented for Claude. Every existing preset sets this flag to `"0"`, overriding an
+inherited `"1"`. Without a selector, explicitly set `ENABLE_SMART_ROUTING_SAVINGS=1`
+with routing enabled to use the feature.
+
+```bash
+SMART_ROUTER_CONFIG_VERSION=subagent_orch_savings_v0 ug claude
+```
+
 `SMART_ROUTER_NAME` still selects the router independently of the preset.
 
-Smart-routed Claude and Codex sessions install `smart-router`. The `subagent_orch_v0`
-and `subagent_orch_v1` versions also install and activate the bundled `smart-router-orchestrator` skill.
+Smart-routed Claude and Codex sessions install `smart-router`. The `subagent_orch_v0`,
+`subagent_orch_v1`, and `subagent_orch_savings_v0` versions also install and activate the bundled `smart-router-orchestrator` skill.
 For example:
 
 ```bash
@@ -306,8 +318,8 @@ SMART_ROUTER_CONFIG_VERSION=subagent_orch_v0 ug claude
 
 The version takes precedence over conflicting legacy flags. Once the agent is selected,
 UG expands its mapping into
-`ENABLE_SMART_ROUTING_V2`, `ENABLE_SMART_ROUTING_SUBAGENT_ONLY`, and
-`ENABLE_SMART_ROUTER_ORCHESTRATOR` for the launched session. When the version is
+`ENABLE_SMART_ROUTING_V2`, `ENABLE_SMART_ROUTING_SUBAGENT_ONLY`,
+`ENABLE_SMART_ROUTER_ORCHESTRATOR`, and `ENABLE_SMART_ROUTING_SAVINGS` for the launched session. When the version is
 unset or empty, these legacy flags retain their existing behavior, including
 first-prompt routing through `ENABLE_SMART_ROUTING_V2=1`. Unknown versions are ignored:
 no preset is applied, the inherited environment is unchanged, and commands continue normally.

docs/claude-mod.md

@@ -61,3 +61,39 @@ UG passes the resolved routing flags and recipe in the existing launch settings
 `pluginConfigs["ug-smart-router"].options`. Claude supplies these to `register(on, options)`.
 `unset` lists originally absent flags because native options cannot carry null values.
 The source remains static; no additional launch snapshot file is created.
+
+## Savings estimate
+
+`hooks/register.ts` draws a row under the status band, styled like it: the estimated
+savings from smart routing, with the amount in a pill (green for a saving, yellow when
+routing cost more), and, when the launch activates Smart Router Orchestrator, the skill's
+`metadata.version` from `SKILL.claude.md`, labeled `Unity Gateway Smart Router v<version>`.
+The row goes after the other `AbovePrompt` handlers' output, so it stays under the band
+whichever order Claude runs them in. For each turn request, main agent and
+subagents, the mod sums token usage by the model that served it and its baseline. Main
+is its own baseline, and a subagent's baseline is the main model in effect when it ran.
+Under first-prompt routing, requests before the user changes the main model are priced
+against the model the session started on.
+
+After each turn the mod writes those sums to `savings_usage`, a file in the launch's
+temporary directory. It then runs the `savings_pricer` argv
+(`python -P -m ucode.smart_routing.savings`), which prices the sums from the
+workspace's cached endpoint rates and prints the estimate's parts (direction, amount,
+percent) as one JSON line. Each savings-enabled routed launch
+refreshes that cache on a background thread. An estimate is hidden, not undercounted,
+when any served or baseline model has no rate. The orchestrator version is passed
+as `orchestrator_version`.
+
+Savings hooks live in `hooks/register.ts` alongside the routing controls: Claude
+allows one hook module per plugin and its capability scanner follows engine API
+calls only within that module. The shared `session.start` handler captures the
+start model before first-prompt routing. Savings handlers are registered only
+when the launch options explicitly enable the feature.
+
+The entire savings mod requires `ENABLE_SMART_ROUTING_SAVINGS=1`. Otherwise no usage
+is tracked or written, no endpoint rates are fetched, no pricer runs, and no savings or
+orchestrator-version row is shown; the three options stay at their declared defaults.
+All existing versioned configurations set the flag to `"0"`. Select
+`SMART_ROUTER_CONFIG_VERSION=subagent_orch_savings_v0` to enable it with subagent
+routing and orchestration. Session routing off/on also disables/restores savings
+from the launch baseline.

skills/smart-router/SKILL.md

@@ -30,4 +30,7 @@ Continue in the root unless the user explicitly requests a subagent. Honor that
 native tools and normal harness model selection, without Smart Router Orchestrator; keep routing off.
 Existing children can finish. When turned on, apply the `smart-router-orchestrator`
 skill to further work only if the session was launched with `ENABLE_SMART_ROUTER_ORCHESTRATOR=1`.
-Do not change the orchestration feature flag. Return the command's result.
+For launches with `ENABLE_SMART_ROUTING_SAVINGS=1`, off/on also disables/restores
+savings tracking and its display row. All earlier versioned presets disable savings;
+`subagent_orch_savings_v0` enables it with subagent routing and orchestration.
+Do not change the orchestration or savings launch baseline. Return the command's result.