pi-smart-model-routing

Pi extension for a configurable daily model plus an on-demand expert model. The main conversation uses the daily model for ordinary work; it can call ask_master on explicit user request or for a concrete high-consequence change or unresolved consequential decision meeting the gates below, without switching the main model. Each expert consultation uses a fresh context, only the explicitly supplied evidence, and a single model request with no tools. The daily model explores code and verifies behavior; the expert provides focused judgment or requests specific missing evidence. You can also explicitly ask Pi to call ask_master in chat.

Install

pi install npm:pi-smart-model-routing

For local development before publishing:

pi install C:/Dev/pi-extensions/pi-smart-model-routing

Restart Pi or run /reload after installing. Disable any older standalone extension that also registers ask_master; only one extension should own this tool. Installation does not set up model access or credentials.

Global configuration

Create <Pi agent directory>/pi-smart-model-routing.json only if you want to override defaults. Pi's normal agent directory is ~/.pi/agent/ (or the directory selected by PI_CODING_AGENT_DIR). No project configuration is read, and installing the package does not create a config file.

{
  "dailyModel": {
    "provider": "openai-codex",
    "id": "gpt-6.1-sol",
    "thinking": "high"
  },
  "expertModel": {
    "provider": "openai-codex",
    "id": "gpt-6-astra",
    "thinking": "xhigh"
  }
}

The above values are also the defaults when the file is absent. When a file exists, both model objects and all three fields in each object are required. thinking accepts off, minimal, low, medium, high, xhigh, or max. Model provider/ID must be present in your Pi model registry and authenticated. An invalid or unreadable file does not fall back to the defaults: Pi reports the configuration error and expert calls fail until it is corrected. Missing models or authentication are reported explicitly; the extension never silently substitutes a different model.

In an interactive Pi session, run /smart-model-routing to choose Daily or Expert, then change its model or thinking level. The action menu shows the configured provider/model and thinking level beside each action, refreshing after every save. The model picker lists only available authenticated models; the thinking picker lists levels supported by the selected model. Cancelling a picker leaves the file unchanged and returns to the action menu. Saving writes the global JSON file, refreshes the status line, and returns to the selected role's action menu so you can change its other setting. Esc from that menu returns to the Daily/Expert menu; Esc again exits. Daily changes take effect only in the next genuinely new session (the current model stays unchanged); expert changes take effect on the next ask_master call. An invalid existing file must be corrected before using the command; saving never silently replaces it.

Only a genuinely new, empty session automatically selects the configured daily model and thinking level. Resuming, forking and reloading an existing session do not override a manual model selection. Expert calls leave the main session's model unchanged. While an expert request runs, the tool displays the provider's streamed thinking text or reasoning summary when available (a rolling 3,000-character preview); otherwise it displays elapsed waiting time. Providers may not expose their full internal reasoning. The final tool result contains the expert's answer and any incompleteness notice, not its thinking preview or intermediate commentary. There is no fixed 24K-character initial-evidence cap; the input budget is derived from the expert model's context window. Referenced file ranges and text artifacts are admitted whole within that budget, and omitted evidence is disclosed rather than silently cut. Each consultation makes only one model request; there is no internal investigation loop or automatic retry.

Session report

Run /smart-model-routing report in interactive TUI mode to open a local, read-only report. Use Up/Down or PgUp/PgDn to scroll and Esc/Enter to close. With no argument, /smart-model-routing still opens model configuration. The report works without valid routing configuration or model authentication: it reads the current session's raw entries only, does not call any model, write session entries, send the report into model context, upload data or read other session files. RPC/JSON/print modes do not support this custom view.

The scope is all recorded branches of the current session, including pre-compaction history and history copied by fork/clone; it is not a bill for work newly executed since startup. The report shows:

• Visible direct and nested ask_master invocations, known overlap blocks and observed outcome counts. A complete return means the response/evidence delivery completed, not that the decision or task was solved. Missing results remain unknown, not presumed running or failed.
• Attributable input/output/cache-read/cache-write tokens, token and cost record coverage, totals and averages over valid records only. Reasoning tokens are shown as an output subset, never added again; one-hour cache writes are already part of cache-write tokens. Partial/invalid token records are not silently zero-filled.
• Stored expert cost estimates and their share of the same-scope recorded session cost. The denominator includes main-model usage, tool usage, standalone usage entries and summaries; expert tool usage is already included, not added twice. Zero-denominator shares are N/A. These are historical estimates, not invoices; zero pricing does not establish free usage.
• Groups by historical expert model, the main model that issued the call (physical response model when recorded), and purpose. Main-model groups include visible non-known-blocked invocations per 100 assistant messages, not per task. Unknown metadata is kept in an unknown group rather than replaced by current configuration.

Calls/results are correlated within their originating branch, not merged by fingerprint; an identical request can be a real repeated consultation. Audit entries enrich existing calls and never add another billed invocation. Result-only observations are retained with unknown origin, and unmatched audits/conflicting results are disclosed. Nested trace IDs are scoped to their outer invocation. Nested metadata can be absent or truncated and generally cannot reveal overlap blocks or per-expert usage: the outer tool's aggregate usage is never assigned wholesale to the expert. Coverage excludes only known blocks, so nested unknowns may still include blocked attempts. Failed/cancelled requests may have incurred cost without returning usage. Missing usage is not zero consumption; report totals are attributable recorded usage, not a complete request or billing ledger.

Historical elapsed time, explicit/A/B/C trigger classification, adoption rate, actual savings and quality improvement are not reconstructed. Comparing those effects requires additional measurement or a controlled task baseline; this report provides cost and behavior indicators only.

When to consult the expert

The daily model normally investigates, implements and verifies work itself. User prohibitions, consultation limits and operation authorization take precedence. An explicit request to use ask_master is honored when the expert is available and no consultation is outstanding. Otherwise consultation requires at least one of the following gates:

• A — Concrete high-consequence change: materially changing authorization/isolation, irreversible data operations, durability/ordering guarantees or widely consumed public contracts, with an evidence-supported failure path to unauthorized access, unrecoverable loss, corruption or widespread compatibility breakage. Independent review is required even with high confidence, passing tests or a clear implementation path.
• B — Unresolved consequential decision: targeted investigation and feasible checks leave competing evidence-supported options or explanations requiring different actions, with substantial correctness, compatibility or rework consequences, and no identified practical direct check would settle the choice.
• C — Important design/feasibility review before implementation: a plan introduces or materially changes a core technical approach, critical dependency, cross-module responsibilities or data flow, and a wrong choice would require substantial reimplementation. After checking existing code and platform constraints, obtain one focused review before committing the plan, even with high confidence or a clear implementation path. Review feasibility, simpler alternatives, critical assumptions, minimal validation and first-version scope, not detailed implementation. Small features, local edits and direct reuse of established patterns do not qualify for C.

Other engineering scenarios fit these gates rather than creating additional topic-based triggers:

Topic labels such as architecture, concurrency or security, subjective uncertainty, repeated failures and generic final-review requests do not qualify on their own. Unknown code should be investigated by the daily model; missing requirements, business priorities or authorization should be clarified with the user. Each consultation addresses one bounded decision with focused evidence and a brief justification. Once actionable, stop consulting and implement and verify. Gather requested evidence before reassessing the gates; only material new evidence leaving a qualifying decision unresolved or reopening it, or a new explicit user request within their limits, warrants another consultation. Expert advice is not user authorization, and incomplete answers are not approval. If necessary review cannot be completed, pause only the affected decision or risky action and report the blocker.

These are shared model-facing instructions, not a programmatic routing guarantee. Cross-model compliance and cost savings have not been measured; differing models may still interpret the same instructions differently.

Single-request expert consultation

The expert receives no tools. ask_master prepares the explicitly referenced evidence, then makes one streamed model request through the configured provider. It never searches the workspace on the expert's behalf, executes expert tool calls, starts a wrap-up round, or automatically retries. Expert models no longer need tool-calling support. Provider errors are reported rather than silently routed to another model.

The expert does not inherit the main conversation, prior consultations, main-session tools, extensions, skills or automatic project instructions. It cannot read or search files, edit files, execute commands, run tests, access the network or delegate. The daily model remains responsible for code exploration, implementation and verification.

When evidence is insufficient, the expert should limit its conclusions and identify the specific missing evidence, why it matters, and what the daily model should inspect or verify. The daily model investigates with its own tools and decides whether expert input is still necessary. A follow-up ask_master call must be concise and self-contained: include the current decision, relevant prior conclusions and focused new evidence, not the whole transcript. Do not retry an unchanged request. Supplied evidence can be selective or misleading; the expert must challenge unsupported claims without pretending to have independently inspected the workspace.

Each consultation retains a 10-minute local deadline and dynamic input/output budgets. Unexpected tool calls are never executed; tool-associated commentary is not promoted to a final answer. Output exhaustion, unexpected tool calls and omitted initial evidence produce an incomplete result with recovery guidance for the daily model. Provider usage is returned directly for session accounting. For audit-shape continuity, the existing investigation metadata field remains, with one round, zero tool calls and no autonomously observed sources. Its complete flag describes request/evidence delivery, not proof that the expert reached a verified conclusion; a delivered answer may still request more evidence.

Expert evidence contract

ask_master keeps caller-reported knownFacts separate from optional inferences (hypotheses) and openQuestions (uncertainties or missing evidence). Existing callers can omit both new fields. Claims are not automatically verified: supply supporting fileRanges or text artifacts for important decisions. Source paths and line ranges are retained even when you supply a custom label, including in omission disclosures. The expert is instructed to cite sources, disclose uncertainty, and treat evidence as data rather than instructions; this is not an independent fact-checking or prompt-injection security guarantee. Each consultation remains independent, so follow-ups must include their relevant context explicitly.

Request identity and lifecycle

Completed consultations store the original toolCallId, a SHA256 of the initial system/user prompts, captured workspace/tool-policy identity, expert provider/model/thinking/output-budget settings in Pi's existing session entries. The tool-policy version distinguishes tool-free consultations from historical autonomous investigations. The prompt hash identifies the supplied system/user prompts, not an immutable workspace snapshot. Completed answers are not used to block repeated requests, including after branch restore: new files or edits can change the answer even when the question and supplied evidence are identical. Historical entries remain readable; no separate prompt database is created.

ask_master requests sequential execution from Pi and holds a single outstanding-consultation slot per extension instance, including across session/tree scope replacements. Other requests return a pending reference to the original call until its raw work settles. Cancellation/deadline ends the local wait promptly and stops progress updates, but does not release that slot while already-started provider/filesystem work remains outstanding. A provider that never settles keeps the slot occupied. Session replacement, reload, shutdown and tree navigation invalidate the old scope; late output cannot record completion or update the new UI. Reloading the extension/process is not proof that remote work stopped. Providers remain responsible for stopping network work and billing when cancellation is signalled.

Initial evidence preparation accepts only regular text files and shares a separate read allowance of min(32 MiB, maxInputTokens * 8 bytes) across file ranges and artifacts. Files exceeding the remaining allowance are omitted whole before reading, even when a small line range was requested; no unbounded whole-file read is used. File changes during reading fail explicitly. Initial prompt budgeting includes the system prompt, complete user message and the final omission disclosure. If the complete prompt exceeds the estimated input budget, the last included evidence items are omitted whole until it fits; if even the all-omitted prompt cannot fit, the request fails explicitly. Any initial omission forces an incomplete result regardless of the model's wording. The estimate is not an exact provider tokenizer guarantee.

Development

npm test
npm pack --dry-run

The package does not include the separate local Android shell/logcat output guard. Never store credentials in this configuration file or in a published tarball. Review Pi extensions before installation: they execute with the host user's permissions.