---
purpose: Explain OMP model roles, prewalk transitions, selector precedence, and cache implications.
applies_to: Choosing default, smol, task, tiny, or commit models and configuring prewalk.
entrypoint: config/omp/config.yml and modules.agents.omp in hosts/*/default.nix.
verification: Run omp models for each provider, the focused OMP config test, and hey check.
update_when: OMP role precedence, prewalk, provider sessions, or model thinking support changes.
---

# OMP model roles and prewalk

## Recommended plan-to-code flow

Use the same Sol model at different thinking levels on each side of prewalk:

```nix
modules.agents.omp = {
  smolModel = "openai-codex/gpt-5.6-sol:low";

  modelRoles = {
    default = "openai-codex/gpt-5.6-sol:medium";
    task = "openai-codex/gpt-5.6-terra";
    tiny = "openai-codex/gpt-5.6-luna:low";
    commit = "openai-codex/gpt-5.6-luna:low";
  };
};
```

With `prewalk.enabled: true`, the main session follows this sequence:

1. Start on `modelRoles.default`: Sol at medium thinking for investigation and planning.
2. Stay there until the first mutating `edit` or `write` call.
3. Prewalk switches once to its destination, which defaults to `@smol`.
4. Continue on the same Sol model at low thinking for implementation.

A read-only session never switches. A session that mutates pays one transition, not one per turn. Prewalk changes the main session model; it does not create a delegated agent.

## Choose or suppress the prewalk destination

OMP 17.2.11 exposes only `prewalk.enabled` as a persistent setting. It has no persistent destination key in `config.yml`.

Use session flags when the post-trigger model should not be `@smol`:

```sh
omp --prewalk-into @default
omp --prewalk-into openai-codex/gpt-5.6-sol:medium
omp --no-prewalk
```

`--prewalk-into` changes the destination for that session; `@default` keeps the session on the default role. `--no-prewalk` disables the handoff even when `prewalk.enabled` is true. To make another destination permanent, add the flag to a wrapper or alias rather than inventing an unsupported YAML key. Recheck this contract with `omp --help` and `omp config list --json` after OMP upgrades.

## Role contracts

| Role      | Use                                                                                                                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `default` | Initial main-session model, including the prewalk investigation and planning phase.                                                                                                                    |
| `smol`    | General fast-model alias and default prewalk destination. In OMP 17.2.11, bundled agents including `scout` and `librarian` also resolve `@smol`, so changing it has a wider effect than prewalk alone. |
| `task`    | Default model for delegated `task` agents. It is independent of `smol`; leave off a thinking suffix when agent frontmatter or per-task `effort` should choose the level.                               |
| `tiny`    | Lightweight background work such as titles, memory, difficulty classification, and unexpected-stop detection. Set it explicitly when it should not fall back to `smol`.                                |
| `commit`  | Commit-message work. Set it explicitly when it should not fall back to `smol`.                                                                                                                         |

Thinking suffixes belong on roles whose contract requires a fixed level. The plan-to-code configuration fixes `default` at `medium`, `smol` at `low`, and routine `tiny`/`commit` work at `low`, while leaving delegated `task` effort unconstrained.

Check current provider support instead of assuming a suffix exists:

```sh
omp models openai-codex
```

OMP 17.2.11 reports `low`, `medium`, `high`, `xhigh`, and `max` for GPT-5.6 Luna, Sol, and Terra. Luna's minimum listed level is `low`, not `minimal` or `off`.

## Put each value in one place

Shared role policy belongs in `config/omp/config.yml`. Host-only auth, quota, or provider differences belong in the host's `modules.agents.omp` block.

`smol` has an extra environment override. Its precedence is:

1. `--smol`
2. `PI_SMOL_MODEL`, generated by `modules.agents.omp.smolModel`
3. Rendered `modelRoles.smol` from `config/omp/config.yml` plus host `modelRoles`

When `smolModel` is non-null, omit `modelRoles.smol` from that host overlay. The wrapper environment wins, so the duplicate role is dead configuration that can drift. For a shared `smol` policy, set `modelRoles.smol` in `config/omp/config.yml` and leave `smolModel` null.

Provider prefixes and model availability are host-specific. Validate selectors with `omp models <provider>` on the target host; do not invent ids by combining prefixes from different providers.

## Provider-session and cache cost

The same-model effort change is cheaper than a Sol-to-Terra handoff, but it is not free.

In OMP 17.2.11, prewalk applies a temporary model switch. The OpenAI Codex Responses provider closes its continuation state at that switch even when the model id is unchanged, so the `previous_response_id` chain resets once. Changing the thinking level can also clear an inherited provider prompt-cache key.

Keeping Sol on both sides still avoids a cross-model transcript handoff and preserves better model-local cache locality than switching to Terra. It does not guarantee a provider cache hit; describe the design as one controlled reset with stable model identity, not as a zero-reset transition.

Recheck this section when OMP changes provider-session reset behavior.

## Verification

After changing role or prewalk configuration:

```sh
omp --version
omp models openai-codex
bash modules/agents/omp/test-config-yml.sh
hey check
```

The runtime files under `~/.omp/agent` are Nix-managed outputs. Inspect them when diagnosing precedence, but edit `config/omp/config.yml`, the host module block, or `modules/agents/omp/default.nix` instead.
