Align template-reference null selection semantics

CONTRIBUTING.md

@@ -308,9 +308,10 @@ not transfer ownership of user compute to Core or prove process quiescence.
 Public Environment Templates belong to Core and its execution database, independently
 of provider image/build templates. Resolve a tenant-owned reference once at Session
 creation, freeze the effective ordinary hosted configuration and reuse inline
-initialization. Do not pass template IDs into Provider or Runtime. Omitted network
-inherits; overrides may only narrow policy. Preserve unresolved caller intent for
-creation retries and recover committed results before reading mutable templates.
+initialization. Do not pass template IDs into Provider or Runtime. Omitted or null
+network inherits the complete template policy; overrides may only narrow policy.
+Preserve unresolved caller intent for creation retries and recover committed
+results before reading mutable templates.
 For template-reference Session initialization, omitted/null env, files, commands
 and packages inherit. Overlay non-null env keys; replace non-null files and command
 lists, including empty lists. Select each package manager independently: omitted/null
@@ -393,8 +394,12 @@ Templates preserve default, latest and explicit version selectors. An omitted or
 null reference version selects the default at Session creation and projects as
 `version: null` in Template responses. Session responses contain concrete versions;
 only validated installation metadata crosses the Runtime boundary. A supplied
-Session Skill list replaces the template list; omission inherits. Null list
-overrides remain unqualified and reject rather than silently changing selection.
+Session Skill, Plugin or capability-directory list replaces its template list;
+omission and null inherit, while an empty list clears that selection. This differs
+from Template resource updates, where null clears lists and resets network to the
+pinned enabled default. Preserve caller intent and frozen Session snapshots in
+both cases. Public capability directories remain caller paths; adapter-owned
+installation directories are not portable public paths.
 
 Inline and referenced Skill ZIPs use the same confidential initialization snapshot and installer.
 Core validates portable manifests and bounded regular-file archives, returns only

contracts/agents-api/README.md

@@ -174,7 +174,7 @@ user-managed enrollment remain outside this qualification.
 | Area | Missing or unverified scope |
 | --- | --- |
 | Subagents / multi_agent | Six reads and same-child recovery have three-harness Docker evidence; optional native operations, live child progress, full lifecycle/interactions and tool combinations remain explicit gaps |
-| Environment Templates | Unsupported restricted hostname forms, null network/list selection and exact hosted errors remain gaps. Template-reference env/files/commands/packages composition follows [qualified field rules](environment-templates.md#template-and-inline-configuration-composition). CRUD/list, files, env/setup/system/npm/Python, inline/referenced Skills, Plugins, workspace capability directories and Session references have recorded coverage. Environment Plugin MCP transport and placement limits are [listed separately](environment-templates.md#environment-origin-mcp-plugins) |
+| Environment Templates | Unsupported restricted hostname forms and exact hosted errors remain gaps. Referenced null network and capability-list selection follow [qualified inheritance rules](template-null-selection.md). Template-reference env/files/commands/packages composition follows [qualified field rules](environment-templates.md#template-and-inline-configuration-composition). CRUD/list, files, env/setup/system/npm/Python, inline/referenced Skills, Plugins, workspace capability directories and Session references have recorded coverage. Environment Plugin MCP transport and placement limits are [listed separately](environment-templates.md#environment-origin-mcp-plugins) |
 | Input and configuration | Non-text initial input, broader content/configuration unions and reasoning/verbosity combinations; [structured output](structured-output.md) has qualified Claude function profiles on none and Core-managed Docker openai_hosted, with other combinations remaining gaps |
 | Tools and interactions | [Deferred discovery qualification](tool-search.md), other tool types, effective tool-set enforcement and result/cancel publication ordering; MiniMax public functions and service-origin MCP remain unsupported |
 | Vault and Credentials | Archive semantics, in-flight token withdrawal and exact hosted selection/error behavior; static/OAuth CRUD, replacement and scoped dispatch-time refresh are implemented (see credential guide for qualification) |

contracts/agents-api/environment-templates.md

@@ -23,8 +23,8 @@ and five-operation SandboxProvider path as inline configuration.
   Creation timestamp plus ID supplies stable local ordering. Missing/foreign IDs
   and cursors return the same not-found result. No compute is allocated by CRUD.
 - Session `environment_template_id` resolves under the caller's tenant. Omitted
-  network inherits; enabled can narrow to restricted or disabled. Restricted can
-  narrow to an exact-host subset or disabled; disabled cannot widen. Effective
+  or null network inherits; enabled can narrow to restricted or disabled.
+  Restricted can narrow to an exact-host subset or disabled; disabled cannot widen. Effective
   configuration is frozen without passing the template ID to execution.
 - Updating/deleting a template does not change existing Sessions. Creation retries
   recover recorded caller intent before template lookup, including after deletion;
@@ -123,10 +123,10 @@ creation, `"latest"` selects latest, and a positive version string selects that
 version. A Session freezes tenant-authorized bytes and concrete version metadata
 in its creation transaction. Later source deletion, default changes or template
 updates cannot change that Session or its committed creation retry. A supplied
-Session Skill list replaces the template list; omission inherits. Template
+Session Skill list replaces the template list; omission/null inherit. Template
 responses include `version: null` for an unresolved default selector; resolved
-Session references retain a concrete version string. Null list overrides remain
-unqualified and reject. See [resource selector qualification](resource-selector-semantics.md).
+Session references retain a concrete version string. See [resource selector
+qualification](resource-selector-semantics.md) and [null selection evidence](template-null-selection.md).
 References return type/skill_id/version/name/description in Session metadata,
 while template responses retain unresolved selectors. Confidential bundle content
 never appears in these metadata responses. The common Runtime installation path
@@ -187,17 +187,17 @@ A hosted
 Skill directories with `skills`; complete package-relative resources are retained.
 The same parser, template resolution and encrypted Session snapshot serve inline
 and template requests. Only type/name/description appears in public Plugin metadata.
-Template Plugin lists inherit on omission and replace when supplied. Template
-updates accept null/empty clearing; explicit null Session overrides remain an
-unconfirmed semantic and reject.
+Referencing Session Plugin lists inherit on omission/null and replace when a
+non-null list is supplied, including empty-list clearing. Template resource updates
+continue to accept null/empty clearing.
 
 `capability_directories` currently accepts clean absolute paths within `/workspace`.
 Initial files and setup can populate them. The shared initializer snapshots these
 directories after setup, then publishes one protected installed manifest. Recovery
 uses those installed bytes even if the source directory changes or is removed.
 This timing and workspace restriction are local implementation choices, not claims
 about unspecified upstream behavior. A supplied Session directory list replaces
-the template list; omitted lists inherit. Missing, overlapping duplicate Skill
+the template list; omitted/null lists inherit. Missing, overlapping duplicate Skill
 names, unsupported manifests and nonregular files reject initialization without
 publishing completion. Directory-discovered Skills do not become fabricated
 inline entries in public `skills` or `plugins` metadata.
@@ -516,9 +516,9 @@ appear automatically in public metadata or initialization diagnostics.
 The [current Template reference](https://developers.openai.com/api/reference/python/resources/beta/subresources/agents/subresources/environments/subresources/templates)
 mentions different GA/beta defaults; this service retains `agents=v1` and the
 [fixed baseline](upstream.json), whose omitted network is enabled. Exact upstream
-errors, no-op timestamps, concurrent pagination and referenced Session null-network
-override semantics remain unverified. The last case explicitly rejects in this
-batch rather than guessing inheritance. This batch is not full protocol compatibility.
+errors, concurrent pagination and broader network combinations remain unverified.
+Referenced null network follows the [qualified inheritance rule](template-null-selection.md);
+unsupported hostname forms still reject. This is not full protocol compatibility.
 
 ## Template and inline configuration composition
 
@@ -559,7 +559,9 @@ subdirectories `official-env-setup` and `official-files-packages`. Reports retai
 fixed-source snapshots, raw status/body/request IDs, command-output proofs,
 accounting, cleanup and credential scans. This covers the observed fixtures rather
 than all possible combinations. Null network and null Skill/Plugin/directory list
-selection remain outside this batch. No new protocol version is introduced.
+selection remained outside that composition batch; the
+[subsequent qualification](template-null-selection.md) records those rules.
+No new protocol version is introduced.
 
 ### Core checks for composition (2026-09-23)
 

contracts/agents-api/openapi.yaml

@@ -2883,22 +2883,24 @@ paths:
         and setup_commands inherit. Non-null files and command lists replace; env
         overlays by key; each package manager inherits on omission/null and otherwise
         replaces its list. Empty lists clear their selected field. Tenant-owned environment_template_id
-        references inherit omitted network and allow only narrowing overrides. Referenced
-        network:null is explicitly unsupported pending semantic verification. Core
-        freezes effective configuration; template updates/deletion do not alter Session
-        snapshots or same-intent creation retries. Inline or tenant-owned skill_reference
-        Skills share initialization. Templates preserve default/latest/explicit selectors;
+        references inherit omitted/null network and allow only narrowing overrides.
+        Inline hosted network:null retains the enabled default; updating a Template
+        with network:null resets its saved policy to enabled. Core freezes effective
+        configuration; template updates/deletion do not alter Session snapshots or
+        same-intent creation retries. Inline or tenant-owned skill_reference Skills
+        share initialization. Templates preserve default/latest/explicit selectors;
         Session creation freezes concrete metadata and encrypted content atomically.
-        Skill-list omission inherits and a supplied list replaces; null overrides
-        and null version selectors remain unqualified and reject. Source deletion/default
-        updates cannot change committed Session Skill contents. Deferred function
-        discovery uses type-only tool_search and per-function defer_loading in the
-        qualified single-agent Claude environment:none function profile, including
-        qualified inline image messages and text results. Explicit web_search mode
-        disabled and programmatic_tool_calling enabled false use frozen common Runtime
-        controls. Enabled forms remain unqualified. Omitted programmatic configuration
-        preserves native behavior, a documented difference from the official default-on
-        behavior. Other combinations remain unqualified; see the operation coverage.
+        Skill, Plugin and capability-directory list omission/null inherit; a non-null
+        list replaces, including empty-list clearing. Omitted/null Skill version selectors
+        resolve the default version. Source deletion/default updates cannot change
+        committed Session Skill contents. Deferred function discovery uses type-only
+        tool_search and per-function defer_loading in the qualified single-agent Claude
+        environment:none function profile, including qualified inline image messages
+        and text results. Explicit web_search mode disabled and programmatic_tool_calling
+        enabled false use frozen common Runtime controls. Enabled forms remain unqualified.
+        Omitted programmatic configuration preserves native behavior, a documented
+        difference from the official default-on behavior. Other combinations remain
+        unqualified; see the operation coverage.
       parameters:
       - description: agents=v1
         in: header

contracts/agents-api/operation-evidence.md

@@ -73,7 +73,7 @@ Paths in the appendix include `/v1`. SDK names here omit `client.`. `P` means pa
 | 28 | beta.agents.environments.files.list | P: direct regular-file directory, opaque cursor | None located | F/D/K recorded live workspace listing | 1,024-entry prefilter bound; no recursion/symlinks; exact defaults/path/errors/mutation invalidation unknown |
 | 29 | beta.agents.environments.templates.create | P: reusable network/files/env/setup/packages/Skills/Plugins/capability config, 201 | R `template-create`; V nullable Skill selector projection | C DB; I/K recorded real frozen-reference initialization | Restricted forms and unqualified combinations; complete hosted initialization semantics |
 | 30 | beta.agents.environments.templates.retrieve | P: safe resource read | R `template-read`, deleted owned read; V nullable Skill selector projection | C DB; I/K recorded reference workflow | Full field/default/redaction parity; no live-secret projection inference |
-| 31 | beta.agents.environments.templates.update | P: field replacement/null clearing, empty timestamp touch | R `template-patch`, `template-null`, `template-noop`; V nullable Skill selector projection | C DB no-op; I/K recorded frozen Session behavior | Referenced Session files/env/setup/packages overrides reject; null network/list/Skill-version remains unresolved |
+| 31 | beta.agents.environments.templates.update | P: field replacement/null clearing, empty timestamp touch | R `template-patch`, `template-null`, `template-noop`; V nullable Skill selector projection | C DB no-op; I/K recorded frozen Session behavior | Template update and referencing Session selection are distinct; composition and null inheritance are qualified separately in environment-templates.md/template-null-selection.md; uncommon fields/errors remain unverified |
 | 32 | beta.agents.environments.templates.list | P: scoped cursor list | R `template-list-empty-scoped` | Recorded resource DB checks; no positive C list replay | Full nonempty/multipage/mutation/default/error parity |
 | 33 | beta.agents.environments.templates.delete | P: delete resource, preserve committed Session snapshot | R `cleanup` at Template path, post-delete read | C DB; K recorded live deletion then continuation | Concurrent references/delete and exact errors |
 | 34 | beta.agents.vaults.create | P: tenant resource, 201 | R `vault-create`, `vault-empty-token-fixture` | C DB; O recorded MCP attachment workflow | Archive lifecycle, full defaults and selection parity |
@@ -106,7 +106,7 @@ Paths in the appendix include `/v1`. SDK names here omit `client.`. `P` means pa
 
 1. **Public generic semantics:** sampled create/event/envelope/error/no-op corrections are merged. Resource-by-resource omissions/null/default/error params, malformed queries, list caps, unknown/empty query handling, concurrent mutation and deletion require separate evidence. Metadata U+0000 remains an implementation-validation question from the prior audit, not a newly reproduced result here.
 2. **Session differences:** The Session admission batch removes idle `none` creation and empty metadata update. Local durable creation idempotency remains an explicit difference. Whitespace-only input succeeds officially but is rejected by the existing Core message validator; this newly observed difference is queued separately. Session agent updates, newer Environment shapes and root Item turn_id are baseline-upgrade questions.
-3. **Template/Skill composition:** referenced files/env/setup/packages override rejection is a known implementation gap; exact merge/replacement/null semantics need evidence. Null override lists, unversioned Skill content, top-level version metadata and last/default/latest deletion remain unresolved.
+3. **Template/Skill composition:** shared env/files/setup/packages selection is covered by the composition batch; template-reference null network/capability lists are covered by the null-selection batch. Official derived capability-directory projection remains different. Skill content/default metadata are covered by file-resource-semantics.md; sole-version deletion, visibility and broader numbering/error behavior remain unverified.
 4. **Execution coverage:** use T's qualified matrix, not a blanket missing-image/structured-output claim. MiniMax functions/service MCP, optional tool combinations, unsupported images/placements and broader native lifecycle are explicit restrictions. PTC omission retains approved native behavior; Claude/MiniMax public Usage remains null; child settlement cadence/native close limits remain visible. No second executor/model loop or guessed counters are justified.
 5. **Workspace and resources:** live Files bounds, symlink/path/cursor choices, artifact overwrite/republishing/headers/cancellation edges, full Environment metadata/lifecycle and Vault archive/in-flight-token semantics remain partial or unknown. Retired Core-managed E2B acceptance cannot qualify current user enrollment.