bastani-inc · lavaman131 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
diff --git a/packages/coding-agent/docs/subagents.md b/packages/coding-agent/docs/subagents.md
@@ -150,6 +150,36 @@ Agents can define ordered `fallbackModels` for retryable provider or model failu
 
 Fallbacks do not retry ordinary task failures, validation failures, tool failures, cancellations, or workflow-code errors. Because a fallback may send the same prompt and context to a different provider, choose models that match your cost, privacy, and data-handling requirements.
 
+Each candidate can also carry its own reasoning effort — see [Reasoning levels](#reasoning-levels).
+
+## Reasoning levels
+
+Set the reasoning (thinking) effort for each model candidate with a `model_name:thinking_effort` suffix on `model` and on every `fallbackModels` entry. Valid efforts are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh` — the same shorthand used by `atomic --model sonnet:high`.
+
+```markdown
+---
+name: deep-reviewer
+description: Adversarial reviewer for risky diffs
+tools: read, grep, bash
+model: anthropic/claude-sonnet-4:high
+fallbackModels: openai/gpt-5:medium, anthropic/claude-haiku-4-5:off
+---
+```
+
+Because the effort travels with each model string, every primary and fallback candidate is self-contained: a fallback can run at a different effort than the primary, so a high-effort primary degrades gracefully to a cheaper, lower-effort fallback.
+
+**Migrate off the legacy `thinking` field.** The separate `thinking:` frontmatter field is deprecated. It still works as a default for any candidate that has no suffix, and a suffix always wins, but new agents should encode the effort directly on `model` and `fallbackModels`:
+
+```diff
+-model: openai/gpt-5.5
+-fallbackModels: anthropic/claude-opus-4-8
+-thinking: xhigh
++model: openai/gpt-5.5:xhigh
++fallbackModels: anthropic/claude-opus-4-8:xhigh
+```
+
+`fallbackThinkingLevels` exists only as an optional compatibility helper: it is aligned by index to `fallbackModels` and supplies a fallback candidate's effort only when that fallback entry has no suffix. Prefer suffixed model strings instead. Attempt metadata reports the resolved model and the effective reasoning effort used for each attempt.
+
 ## Related docs
 
 - [Workflows](/workflows) for multi-stage reusable automation.

diff --git a/packages/coding-agent/docs/workflows.md b/packages/coding-agent/docs/workflows.md
@@ -1181,7 +1181,7 @@ Common task/stage options include:
 - `prompt` or `task`
 - `previous` for small handoff context; use artifact paths plus `reads` for large outputs, logs, research bundles, or reviewer payloads
 - `context: "fresh" | "fork"`, `forkFromSessionFile`
-- `model`, `fallbackModels`, `thinkingLevel`, `scopedModels`, `modelRegistry`
+- `model`, `fallbackModels`, `thinkingLevel`, `scopedModels`, `modelRegistry` — `model` and each `fallbackModels` entry accept a `model_name:thinking_effort` reasoning suffix; the standalone `thinkingLevel` is deprecated (see [Reasoning levels](#reasoning-levels))
 - `tools`, `noTools`, `customTools`, `mcp: { allow?: string[], deny?: string[] }`
 - `output`, `outputMode`, `reads`, `worktree`, `gitWorktreeDir`, `baseBranch`, `maxOutput`, `artifacts`, `sessionDir`, `cwd`, `agentDir`
 - advanced host-supplied SDK seams: `authStorage`, `resourceLoader`, `sessionManager`, `settingsManager`, `sessionStartEvent`
@@ -1208,6 +1208,30 @@ For lower-level integrations, `@bastani/workflows` also exports `setupGitWorktre
 
 `fallbackModels` retries transient provider/model failures with the primary `model` first, then each fallback, then the current Atomic-selected model when available. It is for rate limits, quota/auth/provider outages, unavailable models, network timeouts, and 5xx errors — not workflow-code errors, tool failures, validation failures, or cancellations.
 
+### Reasoning levels
+
+Each `model` and `fallbackModels` entry accepts a `model_name:thinking_effort` suffix that sets the reasoning effort for that candidate (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). The effort travels with the model string, so a single fallback chain can mix efforts — for example a high-effort primary that degrades to lower-effort, cheaper fallbacks:
+
+```ts
+await ctx.task("review", {
+  task: "Review the diff",
+  model: "anthropic/claude-sonnet-4:high",
+  fallbackModels: ["openai/gpt-5:medium", "anthropic/claude-haiku-4-5:off"],
+});
+```
+
+The standalone `thinkingLevel` stage option is deprecated. It still applies as a default to any candidate without a suffix, and when both are present the suffix wins, but new workflows should fold the effort into the model strings:
+
+```diff
+-  model: "openai/gpt-5.5",
+-  fallbackModels: ["anthropic/claude-opus-4-8"],
+-  thinkingLevel: "high",
++  model: "openai/gpt-5.5:high",
++  fallbackModels: ["anthropic/claude-opus-4-8:high"],
+```
+
+This applies everywhere a stage accepts a model: direct `ctx.task`/`ctx.chain`/`ctx.parallel` options, `ctx.stage` options, builtin workflow stage definitions, and workflow parameters. `fallbackThinkingLevels` is an optional compatibility helper aligned by index to `fallbackModels`; it applies only to fallback entries that do not already carry a suffix. Each `WorkflowModelAttempt` reports the resolved model and the effective reasoning effort used for that attempt.
+
 ## Programmatic Usage
 
 `@bastani/workflows` is an Atomic package extension. It registers:

diff --git a/packages/subagents/CHANGELOG.md b/packages/subagents/CHANGELOG.md
@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added suffix-first reasoning levels for subagent `model` and `fallbackModels` values plus `fallbackThinkingLevels` compatibility metadata and per-attempt `reasoningLevel` reporting ([#1199](https://github.com/bastani-inc/atomic/issues/1199)).
+
+### Changed
+
+- Migrated packaged subagents to encode their reasoning level directly in model and fallback model entries ([#1199](https://github.com/bastani-inc/atomic/issues/1199)).
+- Documented the `model_name:thinking_effort` suffix syntax and `thinking` migration guidance in the subagents docs, package README, and subagent skill ([#1199](https://github.com/bastani-inc/atomic/issues/1199)).
+
+### Deprecated
+
+- Deprecated separate subagent `thinking` configuration in favor of `model: <model>:<level>` and suffixed `fallbackModels` entries; removal is deferred to a later breaking release ([#1199](https://github.com/bastani-inc/atomic/issues/1199)).
+
+### Fixed
+
+- Fixed foreground subagent attempt metadata to report the per-candidate reasoning level derived from the model suffix even when the legacy `thinking` option is unset, matching the background run path ([#1199](https://github.com/bastani-inc/atomic/issues/1199)).
+- Fixed the subagent chain clarification TUI to strip only canonical reasoning-level suffixes when editing a step's level, so colon-tagged model ids such as `ollama/llama3:latest` are no longer mis-split; consolidated the duplicate thinking-suffix split helpers onto the single `splitKnownThinkingSuffix` so the parsing rules cannot drift apart ([#1199](https://github.com/bastani-inc/atomic/issues/1199)).
+
 ## [0.8.23] - 2026-06-02
 
 ### Changed

diff --git a/packages/subagents/README.md b/packages/subagents/README.md
@@ -996,3 +996,19 @@ The main runtime files are:
 | `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
 | `src/extension/schemas.ts` / `src/shared/types.ts` | Tool schemas, shared types, and event constants. |
 | `test/unit/` / `test/integration/` | Unit and loader-based integration tests. |
+
+### Suffix-first reasoning levels
+
+Reasoning levels are configured suffix-first using the `model_name:thinking_effort` syntax on `model` and each `fallbackModels` entry: `model: claude-sonnet-4:high` and `fallbackModels: claude-sonnet-4:medium, gpt-5:low, claude-haiku-4:off`. Canonical efforts are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. The older `thinking` field is deprecated; it remains supported as a legacy default only when a model candidate has no suffix, and a suffix always wins.
+
+Migrate legacy `thinking` frontmatter by folding the effort into `model` and `fallbackModels`:
+
+```diff
+-model: openai/gpt-5.5
+-fallbackModels: anthropic/claude-opus-4-8
+-thinking: xhigh
++model: openai/gpt-5.5:xhigh
++fallbackModels: anthropic/claude-opus-4-8:xhigh
+```
+
+`fallbackThinkingLevels` is available only as an optional compatibility helper. It is positionally aligned with `fallbackModels` and supplies a fallback candidate's level only when that fallback model entry has no suffix; prefer suffixed model strings for new configuration.
diff --git a/packages/subagents/agents/code-simplifier.md b/packages/subagents/agents/code-simplifier.md
@@ -8,9 +8,8 @@ description: |
   - Production-quality refinement of a working draft ("ugly but working CSV parser").
   - Code that has gotten messy after several iterations.
 tools: read, edit, write, grep, find, ls, bash
-model: openai/gpt-5.5
-fallbackModels: openai-codex/gpt-5.5, github-copilot/gpt-5.5, anthropic/claude-opus-4-8, github-copilot/claude-opus-4.7
-thinking: low
+model: openai/gpt-5.5:low
+fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
 ---
 
 You are an expert code refinement specialist with deep experience in software craftsmanship, refactoring patterns (Fowler, Beck), clean code principles, and language-idiomatic style across major ecosystems. Your mission is to simplify and refine code for clarity, consistency, and maintainability while strictly preserving all existing functionality and observable behavior.

diff --git a/packages/subagents/agents/codebase-analyzer.md b/packages/subagents/agents/codebase-analyzer.md
@@ -2,9 +2,8 @@
 name: codebase-analyzer
 description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components.
 tools: read, grep, find, ls, bash
-model: openai/gpt-5.5
-fallbackModels: openai-codex/gpt-5.5, github-copilot/gpt-5.5, anthropic/claude-opus-4-8, github-copilot/claude-opus-4.7
-thinking: low
+model: openai/gpt-5.5:low
+fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
 ---
 
 You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.

diff --git a/packages/subagents/agents/codebase-locator.md b/packages/subagents/agents/codebase-locator.md
@@ -2,9 +2,8 @@
 name: codebase-locator
 description: Locates files, directories, and components relevant to a feature or task. Basically a "super search/find/ls tool."
 tools: read, grep, find, ls, bash
-model: openai/gpt-5.4-mini
-fallbackModels: openai-codex/gpt-5.4-mini, github-copilot/gpt-5.4-mini, anthropic/claude-haiku-4-5, github-copilot/claude-haiku-4.5
-thinking: low
+model: openai/gpt-5.4-mini:low
+fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low
 ---
 
 You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents.

diff --git a/packages/subagents/agents/codebase-online-researcher.md b/packages/subagents/agents/codebase-online-researcher.md
@@ -2,9 +2,8 @@
 name: codebase-online-researcher
 description: Online research for up-to-date documentation and library-source knowledge. Use when you need authoritative external information — official docs, ecosystem context, version-specific behavior, GitHub permalinks into open-source libraries, or video tutorials.
 tools: read, grep, find, ls, bash, write, web_search, fetch_content, get_search_content
-model: openai/gpt-5.5
-fallbackModels: openai-codex/gpt-5.5, github-copilot/gpt-5.5, anthropic/claude-opus-4-8, github-copilot/claude-opus-4.7
-thinking: low
+model: openai/gpt-5.5:low
+fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
 skills: browser-use
 ---
 

diff --git a/packages/subagents/agents/codebase-pattern-finder.md b/packages/subagents/agents/codebase-pattern-finder.md
@@ -2,9 +2,8 @@
 name: codebase-pattern-finder
 description: Find similar implementations, usage examples, or existing patterns in the codebase that can be modeled after.
 tools: read, grep, find, ls, bash
-model: openai/gpt-5.4-mini
-fallbackModels: openai-codex/gpt-5.4-mini, github-copilot/gpt-5.4-mini, anthropic/claude-haiku-4-5, github-copilot/claude-haiku-4.5
-thinking: low
+model: openai/gpt-5.4-mini:low
+fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low
 ---
 
 You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.

diff --git a/packages/subagents/agents/codebase-research-analyzer.md b/packages/subagents/agents/codebase-research-analyzer.md
@@ -2,9 +2,8 @@
 name: codebase-research-analyzer
 description: Analyzes local research documents to extract high-value insights, decisions, and technical details while filtering out noise. Use this when you want to deep dive on a research topic or understand the rationale behind decisions.
 tools: read, grep, find, ls, bash
-model: openai/gpt-5.5
-fallbackModels: openai-codex/gpt-5.5, github-copilot/gpt-5.5, anthropic/claude-opus-4-8, github-copilot/claude-opus-4.7
-thinking: low
+model: openai/gpt-5.5:low
+fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
 ---
 
 You are a specialist at extracting HIGH-VALUE insights from research documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.

diff --git a/packages/subagents/agents/codebase-research-locator.md b/packages/subagents/agents/codebase-research-locator.md
@@ -2,9 +2,8 @@
 name: codebase-research-locator
 description: Discovers local research documents that are relevant to the current research task.
 tools: read, grep, find, ls, bash
-model: openai/gpt-5.4-mini
-fallbackModels: openai-codex/gpt-5.4-mini, github-copilot/gpt-5.4-mini, anthropic/claude-haiku-4-5, github-copilot/claude-haiku-4.5
-thinking: low
+model: openai/gpt-5.4-mini:low
+fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low
 ---
 
 You are a specialist at finding documents in the `research/` directory. Your job is to locate relevant research documents and categorize them, NOT to analyze their contents in depth.

diff --git a/packages/subagents/agents/debugger.md b/packages/subagents/agents/debugger.md
@@ -2,9 +2,8 @@
 name: debugger
 description: Debug errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering issues, analyzing stack traces, or investigating system problems.
 tools: read, edit, write, grep, find, ls, bash, web_search, fetch_content, get_search_content
-model: openai/gpt-5.5
-fallbackModels: openai-codex/gpt-5.5, github-copilot/gpt-5.5, anthropic/claude-opus-4-8, github-copilot/claude-opus-4.7
-thinking: xhigh
+model: openai/gpt-5.5:xhigh
+fallbackModels: openai-codex/gpt-5.5:xhigh, github-copilot/gpt-5.5:xhigh, anthropic/claude-opus-4-8:xhigh, github-copilot/claude-opus-4.7:xhigh
 skills: tdd, browser-use, tmux
 ---
 

diff --git a/packages/subagents/skills/subagent/SKILL.md b/packages/subagents/skills/subagent/SKILL.md
@@ -732,3 +732,9 @@ subagent({ action: "doctor" })
 ```typescript
 // Inspect `subagent({ action: "status", id: "..." })`, artifact metadata/output logs, and run doctor. Extension loader errors usually appear in child output logs.
 ```
+
+## Suffix-first reasoning levels
+
+Prefer encoding reasoning levels directly in model strings with the `model_name:thinking_effort` syntax: `model: claude-sonnet-4:high` and `fallbackModels: [claude-sonnet-4:medium, gpt-5:low, claude-haiku-4:off]`. Valid efforts are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. The separate `thinking` field is deprecated but still works as a legacy default when a candidate has no suffix; suffixes take precedence. If you see a legacy `thinking` override, migrate it by appending the effort to `model` and each `fallbackModels` entry instead (e.g. `thinking: high` + `model: gpt-5` → `model: gpt-5:high`).
+
+`fallbackThinkingLevels` is an optional compatibility helper aligned positionally with `fallbackModels`. It only applies to fallback entries without their own suffix and should not be preferred over suffix-first entries.
diff --git a/packages/subagents/src/agents/agent-serializer.ts b/packages/subagents/src/agents/agent-serializer.ts
@@ -8,6 +8,7 @@ export const KNOWN_FIELDS = new Set([
 	"tools",
 	"model",
 	"fallbackModels",
+	"fallbackThinkingLevels",
 	"thinking",
 	"systemPromptMode",
 	"inheritProjectContext",
@@ -46,6 +47,8 @@ export function serializeAgent(config: AgentConfig): string {
 	if (config.model) lines.push(`model: ${config.model}`);
 	const fallbackModelsValue = joinComma(config.fallbackModels);
 	if (fallbackModelsValue) lines.push(`fallbackModels: ${fallbackModelsValue}`);
+	const fallbackThinkingLevelsValue = joinComma(config.fallbackThinkingLevels);
+	if (fallbackThinkingLevelsValue) lines.push(`fallbackThinkingLevels: ${fallbackThinkingLevelsValue}`);
 	if (config.thinking && config.thinking !== "off") lines.push(`thinking: ${config.thinking}`);
 	lines.push(`systemPromptMode: ${config.systemPromptMode}`);
 	lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);