feat: add agents.defaults.params for global default provider params (#58548)

Allow setting provider params (e.g. cacheRetention) once at the
agents.defaults level instead of repeating them per-model. The merge
order is now: defaults.params -> defaults.models[key].params ->
list[agentId].params.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/reference/prompt-caching.md

@@ -20,9 +20,18 @@ For Anthropic pricing details, see:
 
 ## Primary knobs
 
-### `cacheRetention` (model and per-agent)
+### `cacheRetention` (global default, model, and per-agent)
 
-Set cache retention on model params:
+Set cache retention as a global default for all models:
+
+```yaml
+agents:
+  defaults:
+    params:
+      cacheRetention: "long" # none | short | long
+```
+
+Override per-model:
 
 ```yaml
 agents:
@@ -45,8 +54,9 @@ agents:
 
 Config merge order:
 
-1. `agents.defaults.models["provider/model"].params`
-2. `agents.list[].params` (matching agent id; overrides by key)
+1. `agents.defaults.params` (global default — applies to all models)
+2. `agents.defaults.models["provider/model"].params` (per-model override)
+3. `agents.list[].params` (matching agent id; overrides by key)
 
 ### Legacy `cacheControlTtl`
 

src/agents/pi-embedded-runner/extra-params.ts

@@ -82,6 +82,7 @@ export function resolveExtraParams(params: {
   modelId: string;
   agentId?: string;
 }): Record<string, unknown> | undefined {
+  const defaultParams = params.cfg?.agents?.defaults?.params ?? undefined;
   const modelKey = `${params.provider}/${params.modelId}`;
   const modelConfig = params.cfg?.agents?.defaults?.models?.[modelKey];
   const globalParams = modelConfig?.params ? { ...modelConfig.params } : undefined;
@@ -90,13 +91,13 @@ export function resolveExtraParams(params: {
       ? params.cfg.agents.list.find((agent) => agent.id === params.agentId)?.params
       : undefined;
 
-  if (!globalParams && !agentParams) {
+  if (!defaultParams && !globalParams && !agentParams) {
     return undefined;
   }
 
-  const merged = Object.assign({}, globalParams, agentParams);
+  const merged = Object.assign({}, defaultParams, globalParams, agentParams);
   const resolvedParallelToolCalls = resolveAliasedParamValue(
-    [globalParams, agentParams],
+    [defaultParams, globalParams, agentParams],
     "parallel_tool_calls",
     "parallelToolCalls",
   );

src/config/types.agent-defaults.ts

@@ -118,6 +118,8 @@ export type CliBackendConfig = {
 };
 
 export type AgentDefaultsConfig = {
+  /** Global default provider params applied to all models before per-model and per-agent overrides. */
+  params?: Record<string, unknown>;
   /** Primary model and fallbacks (provider/model). Accepts string or {primary,fallbacks}. */
   model?: AgentModelConfig;
   /** Optional image-capable model and fallbacks (provider/model). Accepts string or {primary,fallbacks}. */

src/config/zod-schema.agent-defaults.ts

@@ -16,6 +16,8 @@ import {
 
 export const AgentDefaultsSchema = z
   .object({
+    /** Global default provider params applied to all models before per-model and per-agent overrides. */
+    params: z.record(z.string(), z.unknown()).optional(),
     model: AgentModelSchema.optional(),
     imageModel: AgentModelSchema.optional(),
     imageGenerationModel: AgentModelSchema.optional(),