Merge pull request #2453 from dgageot/board/add-task-budget-output-config-to-opus-4-ba6f107e

Author: aheritier

agent-schema.json

@@ -171,6 +171,33 @@
               "description": "Effort level (e.g., \"low\", \"medium\", \"high\", \"none\", \"adaptive\")"
             }
           ]
+        },
+        "task_budget": {
+          "description": "Default total-token budget for an agentic task (forwarded to Anthropic as `output_config.task_budget`, with the required `task-budgets-2026-03-13` beta header attached automatically). Configurable on any Claude model — docker-agent does not gate by model name — but at the time of writing only Claude Opus 4.7 honors it. Accepts an integer token count or an object {type: tokens, total: N}.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Token budget for the full task (combined thinking, tool calls, and output)."
+            },
+            {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": ["tokens"],
+                  "description": "Budget kind. Only \"tokens\" is supported today."
+                },
+                "total": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "description": "Total budget value."
+                }
+              },
+              "required": ["total"],
+              "additionalProperties": false
+            }
+          ]
         }
       },
       "additionalProperties": false
@@ -650,6 +677,38 @@
             32768
           ]
         },
+        "task_budget": {
+          "description": "Total-token budget for a full agentic task (forwarded to Anthropic as `output_config.task_budget`, with the required `task-budgets-2026-03-13` beta header attached automatically). Limits the combined tokens spent on thinking, tool calls, and output across the whole task. Configurable on any Claude model — docker-agent does not gate by model name — but at the time of writing only Claude Opus 4.7 honors it. Accepts an integer token count or an object {type: tokens, total: N}.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total token budget for the task (e.g., 128000)."
+            },
+            {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": ["tokens"],
+                  "description": "Budget kind. Only \"tokens\" is supported today."
+                },
+                "total": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "description": "Total budget value."
+                }
+              },
+              "required": ["total"],
+              "additionalProperties": false
+            }
+          ],
+          "examples": [
+            64000,
+            128000,
+            { "type": "tokens", "total": 128000 }
+          ]
+        },
         "routing": {
           "type": "array",
           "description": "Routing rules for request-based model selection. When configured, this model becomes a router that selects the best model based on the user's input. The model's provider/model fields define the fallback model.",

docs/concepts/models/index.md

@@ -70,6 +70,7 @@ See the [Model Providers]({{ '/providers/overview/' | relative_url }}) section f
 | `presence_penalty`  | float      | Encourage topic diversity: 0.0 to 2.0             |
 | `base_url`          | string     | Custom API endpoint                               |
 | `thinking_budget`   | string/int | Reasoning effort configuration                    |
+| `task_budget`       | int/object | Total token budget for an agentic task (Anthropic; honored by Opus 4.7 today) |
 | `provider_opts`     | object     | Provider-specific options                         |
 
 ## Reasoning / Thinking Budget

docs/configuration/models/index.md

@@ -24,6 +24,7 @@ models:
     base_url: string # Optional: custom API endpoint
     token_key: string # Optional: env var for API token
     thinking_budget: string|int # Optional: reasoning effort
+    task_budget: int|object # Optional: total task token budget (Anthropic)
     parallel_tool_calls: boolean # Optional: allow parallel tool calls
     track_usage: boolean # Optional: track token usage
     routing: [list] # Optional: rule-based model routing
@@ -45,6 +46,7 @@ models:
 | `base_url`            | string     | ✗        | Custom API endpoint URL (for self-hosted or proxied endpoints)                        |
 | `token_key`           | string     | ✗        | Environment variable name containing the API token (overrides provider default)       |
 | `thinking_budget`     | string/int | ✗        | Reasoning effort control                                                              |
+| `task_budget`         | int/object | ✗        | Total token budget for an agentic task (forwarded to Anthropic; see [Task Budget](#task-budget)). |
 | `parallel_tool_calls` | boolean    | ✗        | Allow model to call multiple tools at once                                            |
 | `track_usage`         | boolean    | ✗        | Track and report token usage for this model                                           |
 | `routing`             | array      | ✗        | Rule-based routing to different models. See [Model Routing]({{ '/configuration/routing/' | relative_url }}). |
@@ -110,6 +112,58 @@ Works for all providers:
 thinking_budget: none # or 0
 ```
 
+## Task Budget
+
+**Anthropic-only.**
+
+`task_budget` caps the **total** number of tokens the model may spend across a
+multi-step agentic task — combining thinking, tool calls, and final output
+tokens. It lets long-running agents self-regulate effort without having to
+choose a tight per-call `max_tokens`.
+
+It is forwarded to Anthropic's
+[`output_config.task_budget`](https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7)
+request field. docker-agent automatically attaches the required
+`task-budgets-2026-03-13` beta header whenever this field is set.
+
+You can configure `task_budget` on **any** Claude model — docker-agent never
+gates it by model name. At the time of writing only **Claude Opus 4.7**
+actually honors the field; other Claude models will reject requests that
+include it. Check the Anthropic release notes linked above for the current
+list of supported models.
+
+### Integer shorthand
+
+```yaml
+models:
+  opus:
+    provider: anthropic
+    model: claude-opus-4-7
+    task_budget: 128000 # total tokens for the whole task
+    thinking_budget: adaptive # works nicely together
+```
+
+### Object form
+
+Equivalent, and forward-compatible with future budget types:
+
+```yaml
+models:
+  opus:
+    provider: anthropic
+    model: claude-opus-4-7
+    task_budget:
+      type: tokens # only "tokens" is supported today
+      total: 128000
+```
+
+Setting `task_budget: 0` (or omitting the field) disables the feature — the
+model falls back to the provider's default behavior.
+
+Like other inheritable model settings, `task_budget` can also be declared on a
+[provider definition]({{ '/providers/custom/' | relative_url }}) and is
+inherited by every model that references that provider.
+
 ## Interleaved Thinking
 
 For Anthropic and Bedrock Claude models, interleaved thinking allows tool calls during model reasoning. This is enabled by default:

docs/configuration/overview/index.md

@@ -261,6 +261,7 @@ agents:
 | `temperature`         | Default sampling temperature.                                                             |
 | `max_tokens`          | Default maximum response tokens.                                                          |
 | `thinking_budget`     | Default reasoning effort/budget.                                                          |
+| `task_budget`         | Default total token budget for an agentic task (Anthropic; honored by Claude Opus 4.7 today).  |
 | `top_p`               | Default top-p sampling parameter.                                                         |
 | `frequency_penalty`   | Default frequency penalty.                                                                |
 | `presence_penalty`    | Default presence penalty.                                                                 |

docs/providers/anthropic/index.md

@@ -67,6 +67,45 @@ models:
       interleaved_thinking: false # disable if needed
 ```
 
+## Task Budget
+
+`task_budget` caps the **total** number of tokens the model may spend across a
+multi-step agentic task — combined thinking, tool calls, and final output. It
+is forwarded as
+[`output_config.task_budget`](https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7)
+and is ideal for letting long-running agents self-regulate effort without
+tightening `max_tokens` on every call.
+
+docker-agent automatically attaches the required `task-budgets-2026-03-13`
+beta header whenever this field is set. You can configure `task_budget` on
+**any** Claude model — docker-agent never gates it by model name. At the time
+of writing, only **Claude Opus 4.7** actually honors the field; other Claude
+models (Sonnet 4.5, Opus 4.5 / 4.6, etc.) are expected to reject requests
+that include it. Check the Anthropic release notes linked above for the
+current list of supported models.
+
+```yaml
+models:
+  opus:
+    provider: anthropic
+    model: claude-opus-4-7
+    task_budget: 128000 # integer shorthand → { type: tokens, total: 128000 }
+    thinking_budget: adaptive
+```
+
+Object form (forward-compatible with future budget types):
+
+```yaml
+  opus:
+    provider: anthropic
+    model: claude-opus-4-7
+    task_budget:
+      type: tokens
+      total: 128000
+```
+
+See the full schema on the [Model Configuration]({{ '/configuration/models/#task-budget' | relative_url }}) page.
+
 <div class="callout callout-info" markdown="1">
 <div class="callout-title">ℹ️ Note
 </div>

docs/providers/custom/index.md

@@ -108,6 +108,7 @@ agents:
 | `parallel_tool_calls` | boolean    | Whether to enable parallel tool calls by default.                                     | —                        |
 | `track_usage`         | boolean    | Whether to track token usage by default.                                              | —                        |
 | `thinking_budget`     | string/int | Default reasoning effort/budget.                                                      | —                        |
+| `task_budget`         | int/object | Default total token budget for an agentic task (forwarded to Anthropic; honored by Claude Opus 4.7 today). Integer shorthand or `{type: tokens, total: N}`. | —                        |
 | `provider_opts`       | object     | Provider-specific options passed through to the client.                               | —                        |
 
 ## Default Inheritance

examples/task_budget.yaml

@@ -0,0 +1,46 @@
+#!/usr/bin/env docker agent run
+
+# Anthropic `task_budget` caps the total tokens a model spends across a
+# multi-step agentic task (thinking + tool calls + final output). docker-agent
+# forwards it as `output_config.task_budget` and automatically attaches the
+# `task-budgets-2026-03-13` beta header.
+#
+# It can be set on any Claude model; at the time of writing only Claude
+# Opus 4.7 actually honors it. See:
+# https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7
+#
+# Run the demo command with:  docker agent run task_budget.yaml -c demo
+
+# Declare the provider explicitly so we can reference claude-opus-4-7 before
+# it lands in the public models.dev catalog. For catalog-known models you can
+# set `task_budget` directly under `models.<name>` without this block.
+providers:
+  anthropic-opus-47:
+    provider: anthropic
+    token_key: ANTHROPIC_API_KEY
+
+agents:
+  root:
+    model: opus-bounded
+    description: a helpful assistant with a bounded task token budget
+    instruction: Stay within the configured task token budget.
+    commands:
+      demo: "design and sketch a small Python CLI that fetches weather data"
+    toolsets:
+      - type: shell
+
+models:
+  # Integer shorthand = a "tokens" budget of 128k for the whole task.
+  opus-bounded:
+    provider: anthropic-opus-47
+    model: claude-opus-4-7
+    task_budget: 128000
+    thinking_budget: adaptive # task_budget pairs well with adaptive thinking
+
+  # Explicit object form, equivalent to `task_budget: 64000`.
+  opus-bounded-tight:
+    provider: anthropic-opus-47
+    model: claude-opus-4-7
+    task_budget:
+      type: tokens
+      total: 64000

pkg/config/latest/model_config_clone_test.go

@@ -24,6 +24,7 @@ func TestModelConfig_Clone_DeepCopiesPointerFields(t *testing.T) {
 		ParallelToolCalls: &parallel,
 		TrackUsage:        &trackUsage,
 		ThinkingBudget:    &ThinkingBudget{Effort: "high"},
+		TaskBudget:        &TaskBudget{Type: "tokens", Total: 128000},
 		ProviderOpts:      map[string]any{"key": "value"},
 		Routing: []RoutingRule{
 			{Model: "fast", Examples: []string{"quick question"}},
@@ -39,6 +40,7 @@ func TestModelConfig_Clone_DeepCopiesPointerFields(t *testing.T) {
 	*original.ParallelToolCalls = false
 	*original.TrackUsage = false
 	original.ThinkingBudget.Effort = "low"
+	original.TaskBudget.Total = 1
 	original.ProviderOpts["key"] = "mutated"
 	original.Routing[0].Examples[0] = "mutated"
 
@@ -49,6 +51,8 @@ func TestModelConfig_Clone_DeepCopiesPointerFields(t *testing.T) {
 	assert.True(t, *clone.ParallelToolCalls)
 	assert.True(t, *clone.TrackUsage)
 	assert.Equal(t, "high", clone.ThinkingBudget.Effort)
+	assert.Equal(t, 128000, clone.TaskBudget.Total)
+	assert.Equal(t, "tokens", clone.TaskBudget.Type)
 	assert.Equal(t, "value", clone.ProviderOpts["key"])
 	assert.Equal(t, "quick question", clone.Routing[0].Examples[0])
 }