Add encrypted Agent defaults and frozen Session execution overrides

CONTRIBUTING.md

@@ -1908,14 +1908,38 @@ replaced; do not carry obsolete compatibility code forward to satisfy this secti
   binding failures never fall back to anonymous execution. Exact URL equality,
   immutable selection timing, implicit response population and hosted error/redirect
   semantics remain local decisions or unverified gaps. No new MCP loop is permitted.
+- Saved Agent execution defaults use separate input and safe-output Core extensions.
+  Keep model-provider bundles whole at every replacement boundary: endpoint, key,
+  protocol and limits must never be independently inherited. Ordinary Agent JSON
+  contains only safe provider fields and an output-only configured flag; encrypt the
+  complete bundle separately with tenant/Agent binding and a distinct purpose.
+  Commit configuration and secret changes together under the Agent row lock. Merge
+  only the extension's supplied members; omission preserves, provider null clears
+  its bundle, and extension null clears both defaults and secret. Model-only edits
+  require no key. Validate the merged harness/protocol/limits without reading keys.
+  Read safe defaults and ciphertext in one database snapshot for Session creation;
+  a complete Session override need not decrypt the inherited bundle.
+- Hosted Session provider selection resolves explicit bundle, saved bundle, then
+  deployment bundle, and freezes it in the existing encrypted Session-owned row.
+  Convert existing native operator options only at server composition, never in
+  scheduling. Retain the complete selected operator options in the private encrypted
+  Session snapshot for deployment fallback, preserving headers, query parameters
+  and native settings; do not reconstruct them from a smaller public input type. Keep runtime dispatch on the common adapter path and fail closed for
+  missing/decryption-failed snapshots. Agent edits/deletion, restart and idle
+  suspend/resume never resolve defaults again. Record caller intent for every new
+  hosted Session before resolving defaults, including inline deployment fallback;
+  matching retries return committed state without replay. No Turn-level overrides,
+  provider catalog or self-hosted/none credential expansion is included. Public
+  input/null semantics and examples live in `contracts/agents-api/model-execution.md`.
 - Public Agent updates use `POST /v1/agents/{agent_id}` with the same tenant/Beta
   boundary and shared saved-field validation. Preserve omission separately from
   null; only supplied fields replace saved values. Metadata is a separate whole-map
   replacement, with null/empty clearing it. Lock the tenant-owned Agent row while
   merging validated fields and enforcing the complete configuration bound, then
   commit configuration, metadata and update timestamp together. Never write a stale
   full snapshot over another update. No-field updates read without changing timestamps.
-  Supplied nested fields currently replace the whole field and explicit null uses
+  Except for the Core execution-default extension described above, supplied nested
+  fields replace the whole field and explicit null uses
   existing saved defaults; exact hosted nested/null and no-op timestamp semantics
   remain unverified. Model-derived reasoning defaults remain a separate gap.
   Neither updates nor retries modify existing Session snapshots or execution state.

contracts/agents-api/harness-selection.md

@@ -77,8 +77,10 @@ For multiple engines, use an exclusive `by_harness` object in the private
 `AGENTS_API_EXECUTION_OPTIONS_FILE`, with one existing adapter-options object per
 engine. No engine inherits another engine's credentials. A legacy flat options
 object is usable only by the deployment default engine. Missing options for a
-selected engine fail execution. Credentials stay in private operator files and
-transient adapter requests, never Agent defaults, metadata or effective responses.
+selected engine fail execution. Operator credentials stay in private files and
+encrypted hosted Session snapshots. Saved Agent provider credentials use separately
+encrypted defaults; public reads return only safe fields and a configured flag.
+Credentials never enter metadata or ordinary effective responses.
 A Session may instead provide the [write-only model execution extension](model-execution.md);
 its frozen configuration takes precedence without operator fallback.
 

contracts/agents-api/model-execution.md

@@ -1,10 +1,71 @@
-# Session model execution extension
+# Agent defaults and Session model execution
 
-Core accepts optional top-level `x_agents_core.model_provider` on Session creation.
+Core accepts optional `x_agents_core.model_provider` on saved Agent creation and
+update, and the same top-level bundle as an explicit Session creation override.
 This is a Core extension, not part of the pinned upstream protocol. It supplies
 execution input only: there is no Provider CRUD, catalog, model alias resolution or
 product permission model in Core.
 
+## Saved defaults and precedence
+
+A saved Agent is editable configuration, not a permanently bound runtime. Create
+or update it with `model`, optional `x_agents_core.harness`, and an optional complete
+`x_agents_core.model_provider`. Create/update/retrieve/list responses return safe
+provider fields and the output-only `api_key_configured` flag. They never return
+`api_key`, ciphertext or a reusable credential reference. Normal Agent JSON stores
+only the safe view; the secret bundle has a separate encrypted row bound to the
+tenant and Agent with a distinct encryption purpose. Agent writes commit safe
+configuration and ciphertext together. A model-only edit does not require a key.
+
+Session creation resolves each explicit model/harness override before saved defaults;
+when no harness is selected, the deployment harness applies. The pinned API still
+requires a model for an inline Agent and when creating a saved Agent. There is no
+model-name inference. Provider precedence is: complete Session bundle, complete
+saved bundle, then configured deployment bundle. Never merge a replacement endpoint
+with an inherited key. A model-only override reuses the entire inherited bundle.
+Codex requires `responses`; Claude SDK and MiniMax Code require `anthropic`, with
+positive context/output limits for MiniMax Code. Validate the resolved combination
+before writing a Session. Core-supplied provider credentials remain hosted-only.
+
+| Operation | Omitted | Explicit null |
+| --- | --- | --- |
+| Agent update `x_agents_core` | Preserve both defaults | Clear harness and provider, including its secret |
+| Agent update nested `model_provider` | Preserve the existing bundle | Clear the entire saved bundle |
+| Agent update nested `harness` | Preserve existing harness | Reject; use extension null to reset |
+| Session top-level `x_agents_core` | Inherit provider defaults | Inherit provider defaults |
+| Session nested `model_provider` | Inherit provider defaults | Inherit provider defaults |
+| Session inline `agent.x_agents_core` | Inherit saved harness | Reset to deployment harness |
+
+An empty Session execution extension remains invalid. An explicitly null provider
+is a defined inheritance request; an empty/partial provider object is invalid.
+Unknown, duplicate or output-only saved-provider input fields are rejected. Saved
+Agent creation without a harness may save a valid bundle, with final harness
+compatibility checked at Session admission. Provider-only Agent updates preserve
+the saved harness and validate their merged compatibility under the row lock.
+Session inline `agent.x_agents_core` remains harness-only; the provider override
+belongs at the Session request's top level.
+
+Read the Agent configuration and encrypted bundle from one coherent database
+snapshot. Explicit complete Session overrides do not need to decrypt a saved
+bundle. Persist a new Session-owned encrypted snapshot atomically with Session and
+environment creation. Existing Sessions never consult the Agent again: edits, key
+replacement, deletion, suspend/resume and process restarts cannot change their
+model, harness or provider. A missing/wrong encryption key fails closed. Retain the
+same deployment credential-encryption key across restarts. V1 has no Turn override,
+provider catalog, Session migration or new execution loop.
+
+All new hosted requests record caller intent before resolving mutable defaults,
+including inline requests that use deployment defaults. Matching creation retries
+recover the committed Session before resolving the Agent or provider again and do
+not enqueue another input. Streaming remains outside the retry identity. Existing
+historical rows keep their documented retry limitations; this change does not
+rewrite them. Omitted and explicit fields retain the existing local intent-hash
+semantics rather than promising upstream equivalence.
+
+See the [TypeScript client example](../../packages/agents-client/saved-agent-defaults.md).
+
+## Session override example
+
 ```json
 {
   "agent": {"model": "exact-provider-model", "x_agents_core": {"harness": "mcode"}},
@@ -30,7 +91,7 @@ larger than context; both must be positive for MiniMax Code. Use the actual mode
 limits. Native provider availability is checked during execution, not by a new probe.
 `agent.model` retains its exact meaning; this extension never changes model identity.
 
-The entire supplied configuration is frozen and encrypted in the Session creation
+The entire resolved provider configuration is frozen and encrypted in the Session creation
 transaction, with a distinct credential-crypto purpose and tenant/Session binding.
 Creation retries include this intent in their request hash; changing the key or
 endpoint under the same idempotency key conflicts. Recovery reads the committed
@@ -40,7 +101,18 @@ extension is write-only and has no update endpoint.
 
 At dispatch, Core resolves its encrypted snapshot into the existing native adapter
 options. It does not fall back to operator credentials when a snapshot is missing
-or cannot decrypt. Omission preserves the existing operator-options behavior.
+or cannot decrypt. For hosted Sessions, omission resolves saved defaults first and then the configured
+deployment provider bundle. Deployment provider defaults from
+`AGENTS_API_EXECUTION_OPTIONS_FILE` are converted at the server composition boundary
+and frozen using the same encrypted Session snapshot. That snapshot also retains
+the complete selected private operator options, including native request headers,
+query parameters and permission settings; dispatch does not reconstruct a lossy
+subset or reread those defaults. New hosted Sessions validate this deployment
+bundle using the same HTTPS/key/protocol rules: legacy operator HTTP endpoints
+must move to HTTPS; invalid defaults fail admission rather than being silently
+rewritten. Explicit and saved provider bundles continue to
+use the existing typed adapter mapping. Other environments and
+historical Sessions retain their existing operator-options behavior.
 Core needs its configured credential encryption key to accept and resume these
 Sessions; retaining the same key is required across restarts. Native harness homes
 may contain private provider configuration under the existing qualified hosted