M-Conch/goal-model-router

Goal Model Router

Route models for subagents inside one active Codex Goal without modifying .codex/agents/*.toml or other persistent Codex configuration.

Runtime requirements

• Codex Goal support and a subagent spawn interface that accepts per-agent model and reasoning-effort overrides.
• Python 3.9 or later for the bundled scripts.

Activation contract

Both conditions are mandatory:

1. The user explicitly invokes $goal-model-router or names this Skill.
2. get_goal confirms an active Goal.

If either condition is false, return NOT_APPLICABLE and make no routing, configuration, or agent-spawn changes. Do not create a Goal on the user's behalf unless the user separately asks to create or run one.

Required workflow

1. Confirm the Goal

Call get_goal before routing. Record:

• Goal objective and status
• main/controller model selected for the task at Goal start
• available subagent model overrides exposed by the current spawn_agent tool

The controller remains the main Goal thread. This Skill routes newly spawned subagents; it does not claim to change the already-running controller model. Goal state can be thread-local, so a child may observe get_goal: null. Do not make spawned roles repeat the activation gate; the controller's pre-spawn Goal check is authoritative for this orchestration.

2. Inventory agents and parse explicit overrides

Codex currently ships three built-in agent types:

• default: general-purpose fallback
• worker: implementation and fixes
• explorer: read-heavy codebase exploration

Names such as planner, reviewer, docs researcher, browser debugger, or release sentinel are custom workflow roles, not an exhaustive Codex role registry. Custom roles are unbounded and must be routed by their actual work.

For every prospective subagent, record:

• unique name
• official agent_type (default, worker, explorer) or custom
• one workload_class: general_reasoning, planning, exploration, implementation, verification, research, synthesis, or monitoring
• bounded purpose and expected output
• per-agent complexity dimensions and critical flags

The Goal controller assigns workload_class from the task semantics. Do not infer cost from a decorative role name. Built-in types receive safe defaults:

• default -> general_reasoning
• worker -> implementation
• explorer -> exploration

Recognize user overrides by agent name, for example:

code_mapper=gpt-5.6-terra/medium
security_gate=gpt-5.6-sol/xhigh

In an ephemeral runtime route, user overrides have highest precedence. If an explicitly requested model or effort is unavailable, stop before spawning that agent and report the exact unsupported value. Never silently replace it.

If the selected custom agent has a personal or project Agent TOML, inspect it for model and model_reasoning_effort. Codex gives values pinned in that file higher precedence than spawn values. If a pin conflicts with the user's override, stop and explain the conflict; either use an unpinned ephemeral agent or let the user change the persistent configuration. Do not edit it silently. A custom Agent whose configured name matches default, worker, or explorer shadows that built-in; inspect the resolved configuration before applying a built-in workload default.

3. Choose the smallest useful team

Choose agents from the actual work graph, not from a fixed planner/executor/ reviewer template. Planning, exploration, implementation, research, verification, synthesis, and monitoring are examples of useful boundaries.

Do not spawn ceremonial agents. Prefer one controller plus the minimum bounded subtasks that materially improve speed, isolation, or verification. The main controller may perform any workload itself, but include it in the final ledger.

4. Score complexity and route

Read routing-policy.md. Score each subtask, not only the Goal as a whole, on:

• scope
• ambiguity
• blast radius / risk
• validation difficulty
• critical flags such as security, authorization, destructive operations, or data migration

Prepare a request for scripts/route_models.py. Score every agent separately. Example:

{
  "agents": [
    {
      "name": "code_mapper",
      "agent_type": "explorer",
      "purpose": "Map affected code paths",
      "dimensions": {
        "scope": 1,
        "ambiguity": 0,
        "risk": 0,
        "validation": 1
      }
    },
    {
      "name": "ui_fixer",
      "agent_type": "custom",
      "workload_class": "implementation",
      "purpose": "Implement the bounded fix",
      "dimensions": {
        "scope": 2,
        "ambiguity": 1,
        "risk": 1,
        "validation": 1
      }
    }
  ],
  "explicit_routes": {
    "ui_fixer": {
      "model": "gpt-5.6-sol",
      "effort": "high"
    }
  },
  "available_models": ["gpt-5.6-sol", "gpt-5.6-terra"]
}

Run:

python3 scripts/route_models.py --request REQUEST.json --pretty

The output is a runtime routing plan. It is not an Agent TOML file and must not be written into .codex/agents/.

Routing precedence:

1. existing custom Agent file pin, if deliberately selected; conflicting user overrides are an error because Codex gives the file higher precedence
2. explicit user model/effort for the agent
3. Skill policy for workload class and per-agent complexity
4. deterministic capability fallback for Skill-selected models only
5. [agents] default and then parent inheritance when no override is possible

5. Spawn with runtime overrides

For each selected agent, call spawn_agent with:

• a bounded workload-specific task
• model equal to the route's selected_model
• reasoning_effort equal to selected_effort
• enough recent context for the task

Pass the built-in/custom agent type only when the current spawn interface exposes such a parameter. When it does not, preserve the workload boundary in the task name and prompt, and record that agent_type was planned rather than runtime-selected.

Do not create or edit Agent TOML files as part of routing. A persistent role configuration can override runtime expectations and defeats per-Goal dynamic routing.

Create a ledger entry immediately after every spawn:

{
  "agent": "code_mapper",
  "agent_type": "explorer",
  "workload_class": "exploration",
  "model_source": "skill_fallback",
  "requested_model": "gpt-5.6-luna",
  "selected_model": "gpt-5.6-terra",
  "effective_model": null,
  "effort": "medium",
  "status": "running",
  "retries": 0
}

6. Verify instead of assuming

After spawn and completion, use runtime evidence when available:

• spawn acceptance/result
• agent/thread metadata showing model and effort
• completion notification
• token-usage notification or persisted usage metadata

Set effective_model only from runtime evidence. If the environment exposes only the requested model, label it requested/accepted rather than claiming an independently observed model. If no evidence exists, write unverifiable.

On failure:

1. retry once with clearer context at the same model when the failure is plausibly contextual;
2. for Skill-selected routes only, escalate luna -> terra -> sol;
3. after repeated identical failure or verification-gate rejection, replan rather than blindly retry;
4. never override a user's explicit model without asking.

7. Close the Goal with an auditable report

Before marking the Goal complete, require:

• the requested work is actually complete;
• every required verification or human gate passes;
• every spawned agent has a terminal status;
• requested/selected/effective model distinctions are preserved.

Report at minimum:

Agent	Agent type	Workload	Model source	Requested	Effective	Effort	Status

Include the main Goal controller as one row.

Only call update_goal(status="complete") after all acceptance criteria pass.

Optional same-token credit estimate

Estimate savings only when per-agent input, cached-input, and output token counts are available. Use scripts/estimate_credits.py.

Before presenting a numeric result, verify that the script's dated default rates still match the current official Codex rate card. Supply custom rates when they do not.

The estimate compares the routed models against using the Goal-start controller model for the same observed token structure. Label it:

Same-token credit estimate; not an actual counterfactual rerun

Do not:

• call the estimate actual billing;
• double-count reasoning tokens if they are already included in output tokens;
• invent token counts;
• show a savings number when required usage data is absent.

When usage is missing, state Credit savings: unavailable (missing per-agent token data).

Safety rules

• Never mutate persistent Codex model configuration through this Skill.
• Never widen task permissions merely because a stronger model is selected.
• Treat security, authorization, destructive operations, and migrations as critical complexity and preserve any human approval gate.
• Keep the controller responsible for final synthesis and Goal status.