feat: forge work system — auto-install, multi-provider routing, cost dashboard, MCP tools

[CodeWithJuber]

What & why

The forge work system (substrate, guards, memory, routing) didn't auto-activate in Claude sessions, the cost dashboard was empty, model routing was advisory-only with no provider support, and most commands weren't accessible via MCP. This PR fixes all four gaps:

Stream 1 — Auto-install settings.json merge: forge init now merges hooks, permissions, and statusline into ~/.claude/settings.json automatically (idempotent, preserves existing entries). Adds --no-settings flag to skip.

Stream 2 — Multi-provider model routing: New src/providers.js with Anthropic + OpenRouter built-in and custom endpoint support. forge config command for provider management. forge route --apply writes the recommended model to settings.json. forge route --provider <name> switches provider inline.

Stream 3 — Cost dashboard fixes: Hook metrics recording fills .forge/metrics.jsonl (best-effort, never blocks). estimateSpendFromLogs() fallback reads Claude session logs when ccusage is unavailable. Dashboard shows real spend tile + per-model breakdown. /api/spend endpoint added.

Stream 4 — MCP tool expansion (8 → 14 tools): forge_cost, forge_dash_data, forge_brain, forge_ledger_query, forge_diagnose, forge_doctor.

Checklist

• npm test passes (Node 18/20/22) — 452 tests, 450 pass, 2 skipped, 0 fail
• npm run check passes (Biome lint + format)
• New public functions have a test — 11 new provider tests + updated MCP tests
• Conventional commit message (feat:/fix:/docs: …)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dev deps ok)
• Substrate/docs updated if this changes forge substrate, forge impact, router/gate, or MCP substrate tools

Risk & rollback

• Risk level: medium
• Rollback plan: Revert commit. Settings merge is idempotent and append-only (never removes user entries). Provider config is opt-in (.forge/providers.json). Metrics recording is best-effort (swallowed errors). MCP tools are additive.

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (no swallowing)
• Authorization/ownership checked (if it touches access)
• Logs contain no secrets/PII
• If AI-assisted: I understand it, verified the package APIs, and it has tests

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

forgekit/src/providers.js

Lines 146 to 149 in 7b96778

	const modelId = MODELS[tierKey]?.id;
	if (!modelId) return { ok: false, reason: `unknown tier "${tierKey}"` };
	const prev = settings.model;
	settings.model = tierKey;

Apply routed provider model IDs

With any non-default provider selected, such as forge route "..." --provider openrouter --apply or after forge config provider openrouter, this still derives modelId from the global Anthropic MODELS table and writes the tier key (sonnet, haiku, etc.) to settings. The active provider mapping saved in .forge/providers.json is never read here, so OpenRouter/custom providers are silently ignored even though the CLI reports a model as applied.

---

forgekit/src/providers.js

Line 55 in 7b96778

merged.providers[name] = { ...merged.providers[name], ...cfg };

Deep-merge provider model overrides

If a user customizes only one model for a built-in provider, this shallow merge replaces the provider's entire models object. For example, overriding just OpenRouter's sonnet leaves haiku/opus missing, and resolveModel then falls back to raw Anthropic IDs for those tiers instead of the OpenRouter-prefixed defaults. Merge models separately so partial provider overrides do not break the remaining tiers.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".