​

Reasoning effort

​

Levels

EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max']

​

Where effort comes from

​

Config keys

# config.yaml
roles:
  work:
    model: workhorse:mid
    effort: high
    sub:
      security:
        model: claude-opus-5-5
        effort: max

tiered_execution:
  tiers:
    frontier:
      model: claude-opus-5-5
      harness: claude-code
      difficulties: [expert]
      effort: xhigh
  escalation:
    effort_first: true

# projects.yaml
projects:
  myproject:
    path: /home/user/Projects/myproject
    effort: medium

// an xBRIEF plan or item's metadata (free-form key, like metadata.difficulty)
{ "metadata": { "effort": "high" } }

​

Clamping

• If the resolved level is supported, it’s used as-is.
• If not, the highest supported level below it is used instead (max requested on a harness with no max falls to xhigh).
• If nothing supported ranks below it, the lowest supported level is used (low requested against a model that only supports high/max becomes high).
• If the model and harness restrictions don’t overlap at all, the requested level is kept as-is and flagged with a warning rather than dropped.

​

Tier escalation

tiered_execution:
  escalation:
    enabled: true
    retries_at_tier: 1
    max_promotions: 2
    effort_first: true

1. No effective difficulty → block.
2. Promotions already at max_promotions → block.
3. Already at expert → block.
4. Attempts below retries_at_tier → retry.
5. effort_first is on and this item has not raised effort yet → raise-effort one level above its current staffed effort (via supportedEffortLevels(), so the raise never exceeds what the model/harness pair accepts) instead of promoting to the next tier’s model.
6. Otherwise → promote to the next tier’s model, exactly as before effort_first existed.

​

Relaunch keeps effort

• A persisted effort wins on relaunch whatever its source. A roles.<role>.effort config change reaches new spawns only; it does not retroactively change an agent that already has a pinned effort.
• The persisted level is always re-clamped to the relaunch’s model and harness, so a model or harness switch (max on claude-code relaunched under ohmypi) clamps down and the clamped level is what gets stored back — never the original request.
• A legacy or effort-less agent resolves through the normal role → project → default chain on its first relaunch, and that resolved value is then pinned for every relaunch after it.

​

Changing effort on a running session

• The level is first clamped to the model, the same as at launch.
• A session that is mid-turn is refused (409 busy), because Claude Code queues typed input during a turn and the change could land after the window. A pending permission prompt or a subagent holding the input is also refused (409), and nothing is typed.
• No confirmation within 10 seconds answers 504 not-confirmed; a rejected level answers 422 effort-rejected. In both cases the stored effort is unchanged.
• A confirmed change is stored as explicit: on the conversation row, or in the agent’s state.json, where relaunch pins it.

​

What honors it today

• pan start <id> for work-agent spawns.
• Definition-less role runs (review sub-roles, the standing supervisor) and their codex/omp launcher fields (getRoleRuntimeBaseCommand, getCodexLauncherFields, getOhmypiLauncherFields in src/lib/agents/runtime-command.ts).
• Every relaunch path: resume (resumeAgent), restart (restartAgent), crash recovery (recoverAgent), the messaging fresh-launch fallback, session rotation, crash respawn, and cloister model handoff — see Relaunch keeps effort.
• Conversations — dashboard creation (sidebar and Home composer effort pickers, and the New conversation with options… dialog, whose default and its source come from GET /api/effort/default?model=&harness=&issue=), resume, restart-all, switch-model (clamped to the new model), and pan handoff/pan fork --effort (default: inherit the source conversation’s effort). pi’s off/minimal are stored as low.
• Live change on a running session — claude-code conversations and claude-code agents through /effort, and codex, ACP, OpenCode, and pi conversations through their control channels — see Changing effort on a running session.
• Every harness adapter — codex (TUI and app-server), OpenCode and Kimi via ACP, native Kimi Code, Pi and Muse — receives a resolved, clamped level from its producer and never applies its own default (see How each harness receives effort).
• The review parent’s fresh spawn — roles.review.effort (the resumed-session branch keeps the saved session’s effort unchanged) (PAN-4256).
• The test role’s dispatch — both the automatic post-review queue and the manual re-dispatch route — roles.test.effort (PAN-4256).
• pan worker run --effort <level> (PAN-4256).
• pan spawn --effort <level> — item metadata.effort → plan metadata.effort → roles.worker.effort → high; only claude-code and codex panes get a mapped --effort/model_reasoning_effort flag, every other harness launches with no effort flag (PAN-4256).
• pan flywheel start — roles.flywheel.effort at the next start; a paused Flywheel resumed keeps the effort it started with (PAN-4256).
• POST /api/agents (an explicit effort field in the body) and POST /api/agents/:id/restart (ditto, pinning the relaunch as explicit) (PAN-4256).
• pan start --remote work agents on Fly — roles.work.effort (PAN-4256).
• Tiered-execution work spawns — a registered swarm slot (resolveSlotTierSpawnParams) and the single work agent (resolveSingleWorkTierSpawnParams) both staff through resolveStaffing(), which resolves effort via the same precedence chain with the item’s tier as layer 4, and pickLaunchEffort() (src/lib/agents/launch-effort.ts) lets that staffed value win over pan start’s non-explicit default while still letting an explicit --effort outrank it.
• The standing tier supervisor (spawnTierSupervisor) and the merge-train’s re-review dispatch (reDispatchVerification in src/lib/cloister/merge-train-deps.ts), both via resolveEffort({ role: 'review', ... }).
• Planning — pan plan --effort, the dashboard Plan dialog (default high, all five levels), and the planning half of pan start on an unplanned issue. The start-planning API rejects an unknown level with 400; the planner resolves with role plan (roles.plan.effort → project → high) and is clamped to the planning model and harness. The planning prompt’s effort section names the resolved level, and high and above add the probe pass.
• pan strike (roles.strike.effort → project → high); --dry-run prints the resolved level and its source.
• Recording — every new sessions.json line carries the launch effort, and every new cost-ledger row (cost_events.effort, events.jsonl) carries the effort its request ran at: for claude-code the level on the transcript record, else the session’s launch effort. Rows recorded before this change read as unrecorded.
• Reporting — pan cost effort [--issue <id>] [--json] groups spend by effort, one bucket per level plus unrecorded.
• Display — Agents page History rows and the detail header show <level> (<source>); pan status prints Effort:; pan show prints effort and includes effort/effortSource in --json. The conversation composer chip shows it for conversations.