fix(codex): preserve native agent model settings (#3150)

Preserve authored string model and model_reasoning_effort settings as top-level Codex TOML keys, leaving omitted settings absent. Warn safely about unsupported or invalid metadata without exposing values. Add regression coverage and document the bounded behavior and proposed specification amendment.

Fixes #3126.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

.agents/skills/apm-spec-guardian/assets/synthesizer-return-schema.json

@@ -93,21 +93,7 @@
     "defer_v0_2": {
       "type": "array",
       "description": "Architectural work bound to a reserved slot in a future major. Each entry MUST cite the existing reserved-slot section anchor in the artifact (e.g. 'sec.4.8 workspaces reserved', 'sec.10.12 publisher attestations reserved').",
-      "items": {
-        "allOf": [
-          { "$ref": "#/definitions/fold_item" },
-          {
-            "type": "object",
-            "required": ["reserved_slot_anchor"],
-            "properties": {
-              "reserved_slot_anchor": {
-                "type": "string",
-                "description": "Section / anchor in the current artifact that already reserves space for this work."
-              }
-            }
-          }
-        ]
-      }
+      "items": { "$ref": "#/definitions/fold_item_with_reserved_slot" }
     },
     "reject": {
       "type": "array",
@@ -148,6 +134,23 @@
         "patch_instruction": { "type": "string", "description": "Concrete mechanical instruction the drafter applies. ASCII only. MUST NOT add any forbidden vendor / foundation token to the artifact." },
         "success_criterion": { "type": "string", "description": "Verifiable post-fold check (grep, schema validation, or anchor count)." }
       }
+    },
+    "fold_item_with_reserved_slot": {
+      "type": "object",
+      "description": "Same shape as fold_item plus a required reserved_slot_anchor. Inlined (not composed via allOf over fold_item) because Draft 7 has no unevaluatedProperties: an allOf branch's own additionalProperties:false would otherwise reject the sibling branch's reserved_slot_anchor key. The five base properties are intentionally duplicated here, not $ref-shared, to keep this a single closed object; test_shared_fold_item_properties_structurally_identical guards against the two copies drifting apart.",
+      "required": ["id", "theme", "spec_section", "patch_instruction", "success_criterion", "reserved_slot_anchor"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^F[1-9][0-9]*$" },
+        "theme": { "type": "string", "description": "Convergent-theme id this fold addresses (e.g. T1, T2), or 'standalone' if not part of a clustered theme." },
+        "spec_section": { "type": "string", "description": "Section / appendix / req-XXX anchor where the patch lands." },
+        "patch_instruction": { "type": "string", "description": "Concrete mechanical instruction the drafter applies. ASCII only. MUST NOT add any forbidden vendor / foundation token to the artifact." },
+        "success_criterion": { "type": "string", "description": "Verifiable post-fold check (grep, schema validation, or anchor count)." },
+        "reserved_slot_anchor": {
+          "type": "string",
+          "description": "Section / anchor in the current artifact that already reserves space for this work."
+        }
+      }
     }
   }
 }

.apm/skills/apm-spec-guardian/assets/synthesizer-return-schema.json

@@ -93,21 +93,7 @@
     "defer_v0_2": {
       "type": "array",
       "description": "Architectural work bound to a reserved slot in a future major. Each entry MUST cite the existing reserved-slot section anchor in the artifact (e.g. 'sec.4.8 workspaces reserved', 'sec.10.12 publisher attestations reserved').",
-      "items": {
-        "allOf": [
-          { "$ref": "#/definitions/fold_item" },
-          {
-            "type": "object",
-            "required": ["reserved_slot_anchor"],
-            "properties": {
-              "reserved_slot_anchor": {
-                "type": "string",
-                "description": "Section / anchor in the current artifact that already reserves space for this work."
-              }
-            }
-          }
-        ]
-      }
+      "items": { "$ref": "#/definitions/fold_item_with_reserved_slot" }
     },
     "reject": {
       "type": "array",
@@ -148,6 +134,23 @@
         "patch_instruction": { "type": "string", "description": "Concrete mechanical instruction the drafter applies. ASCII only. MUST NOT add any forbidden vendor / foundation token to the artifact." },
         "success_criterion": { "type": "string", "description": "Verifiable post-fold check (grep, schema validation, or anchor count)." }
       }
+    },
+    "fold_item_with_reserved_slot": {
+      "type": "object",
+      "description": "Same shape as fold_item plus a required reserved_slot_anchor. Inlined (not composed via allOf over fold_item) because Draft 7 has no unevaluatedProperties: an allOf branch's own additionalProperties:false would otherwise reject the sibling branch's reserved_slot_anchor key. The five base properties are intentionally duplicated here, not $ref-shared, to keep this a single closed object; test_shared_fold_item_properties_structurally_identical guards against the two copies drifting apart.",
+      "required": ["id", "theme", "spec_section", "patch_instruction", "success_criterion", "reserved_slot_anchor"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^F[1-9][0-9]*$" },
+        "theme": { "type": "string", "description": "Convergent-theme id this fold addresses (e.g. T1, T2), or 'standalone' if not part of a clustered theme." },
+        "spec_section": { "type": "string", "description": "Section / appendix / req-XXX anchor where the patch lands." },
+        "patch_instruction": { "type": "string", "description": "Concrete mechanical instruction the drafter applies. ASCII only. MUST NOT add any forbidden vendor / foundation token to the artifact." },
+        "success_criterion": { "type": "string", "description": "Verifiable post-fold check (grep, schema validation, or anchor count)." },
+        "reserved_slot_anchor": {
+          "type": "string",
+          "description": "Section / anchor in the current artifact that already reserves space for this work."
+        }
+      }
     }
   }
 }

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- `docs/src/content/docs/specs/openapm-v0.1.md` adds proposed `req-tg-015` for Codex-native `model`/`model_reasoning_effort` preservation and bounded dropped-metadata diagnostics. (#3150)
+
+### Fixed
+
+- Codex agent conversion preserves native `model` and `model_reasoning_effort` settings and warns about dropped metadata instead of silently losing it. (#3150)
+
 ## [0.33.0] - 2026-10-02
 
 ### Added

CONFORMANCE.json

@@ -1544,12 +1544,23 @@
       "tests": [
         "tests/spec_conformance/test_manifest_reqs.py::test_user_scoped_mcp_target_selection_ignores_project_signals"
       ]
+    },
+    {
+      "conformance_class": "consumer",
+      "id": "req-tg-015",
+      "keyword": "MUST",
+      "section": "8.5.1",
+      "status": "active",
+      "test_count": 1,
+      "tests": [
+        "tests/spec_conformance/test_manifest_reqs.py::test_codex_native_model_settings_preserved_and_dropped_metadata_bounded"
+      ]
     }
   ],
   "spec_version": "v0.1.1",
   "summary_by_class": {
     "consumer": {
-      "active": 91,
+      "active": 92,
       "skipped": 1,
       "unbound": 0,
       "xfail": 0
@@ -1573,5 +1584,5 @@
       "xfail": 0
     }
   },
-  "total_requirements": 125
+  "total_requirements": 126
 }

CONFORMANCE.md

@@ -33,7 +33,7 @@ APM claims the proposed deployed-prompt-audit capability (req-pl-019, req-pl-020
 | Class | Active | Skipped | Xfail | Unbound |
 |-------|-------:|--------:|------:|--------:|
 | Producer | 12 | 0 | 0 | 0 |
-| Consumer | 91 | 1 | 0 | 0 |
+| Consumer | 92 | 1 | 0 | 0 |
 | Registry | 1 | 0 | 0 | 0 |
 | Governance | 20 | 0 | 0 | 0 |
 
@@ -166,6 +166,7 @@ APM claims the proposed deployed-prompt-audit capability (req-pl-019, req-pl-020
 | [req-tg-012](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-012) | MUST | 8.5.6 | consumer | active | 1 | - |
 | [req-tg-013](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-013) | MUST | 8.5.7 | consumer | active | 7 | - |
 | [req-tg-014](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-014) | MUST | 8.5.8 | consumer | active | 1 | - |
+| [req-tg-015](docs/src/content/docs/specs/openapm-v0.1.md#req-tg-015) | MUST | 8.5.1 | consumer | active | 1 | - |
 
 ## Waivers
 

apm.lock.yaml

@@ -1590,7 +1590,7 @@ deployments:
   owners:
   - .
   active_owner: .
-  content_hash: sha256:e6e2771f2fe8578e72d12e51edcc3817717f8a0bbef66d8a8a5c556f0dce06d7
+  content_hash: sha256:2115c15be67270f2b969b7f49e88d9686382d4aed10fed21ae47811c36981c98
 - kind: project-relative
   target: legacy
   value: .agents/skills/apm-strategy
@@ -3104,7 +3104,7 @@ local_deployed_file_hashes:
   .agents/skills/apm-spec-guardian/assets/comment-template.md: sha256:8f5703aa98d1036d2418ffa45eac9d0270504dac33f3e9b1892884a9d48da1a6
   .agents/skills/apm-spec-guardian/assets/linter-checklist.md: sha256:b3b60af18f4b37e9f68815aaf8001617b81cc24fb8fe0a1f19074db93efa6b3b
   .agents/skills/apm-spec-guardian/assets/panelist-return-schema.json: sha256:bb66b270394c386665c6b93d83befe05ce9f8206abf8d656079c29d65729fefd
-  .agents/skills/apm-spec-guardian/assets/synthesizer-return-schema.json: sha256:e6e2771f2fe8578e72d12e51edcc3817717f8a0bbef66d8a8a5c556f0dce06d7
+  .agents/skills/apm-spec-guardian/assets/synthesizer-return-schema.json: sha256:2115c15be67270f2b969b7f49e88d9686382d4aed10fed21ae47811c36981c98
   .agents/skills/apm-strategy/SKILL.md: sha256:6c7fbc821fef930ab76764c7b33d55bd181f31cdd406cff5ce7cf14d1071c2ef
   .agents/skills/auth/SKILL.md: sha256:bf1039cb63dbb968d50dbf4a9e4ceec9a4c30e40e8dd666d404f1c39eda55bc0
   .agents/skills/cli-logging-ux/SKILL.md: sha256:b04d5282a9f21b33c75ac98c41c7eab7e562eafea8c89bbb5732d9956958fe7c

docs/public/specs/manifests/openapm-v0.1.requirements.yml

@@ -460,6 +460,11 @@ requirements:
     section: "8.5.8"
     conformance_class: consumer
     notes: "user-scoped MCP target selection uses a disclosed versioned capability contract, ignores project-only detection signals, applies first-source precedence without fallback, filters mixed sets, and refuses zero-supported selections before user manifest, lockfile, or target-config mutation"
+  - id: req-tg-015
+    keyword: MUST
+    section: "8.5.1"
+    conformance_class: consumer
+    notes: "a conforming consumer providing the Codex-native agent conversion capability preserves a source-declared model or model_reasoning_effort string value in its native top-level placement, leaves either field absent when absent from the source, diagnoses a non-string source value by field name without including that value, and emits a diagnostic bounded on dropped-field count (at least one shown when any are dropped), per-field name length, and ASCII-sanitized field-name display (never the value) for any other dropped, non-capability-restriction frontmatter field"
   - id: req-pr-006
     keyword: MUST
     section: "8.1"

docs/src/content/docs/contributing/development-guide.md

@@ -500,3 +500,13 @@ The workflow distinguishes three modes:
 
 These checks cannot detect every semantic drift. Choosing the appropriate
 mode remains a human decision; the harness exposes the choice, not the answer.
+
+The same limit applies to the `apm-spec-guardian` skill's review panel. Its
+synthesizer-return schema validates that a `defer_v0_2` entry's
+`reserved_slot_anchor` field is **present and of type string** -- a
+structural, type-only check. It does not verify that the cited anchor is one of
+the spec's actual reserved-for-v0.2 sections (for example Section 4.8
+workspaces, Section 7.9 version withdrawal, Section 10.12 publisher
+attestations, or Appendix B). Confirming that a cited anchor genuinely
+reserves the space it claims remains a human/panel judgment, not something
+schema validation can substitute for.

docs/src/content/docs/producer/author-primitives/instructions-and-agents.md

@@ -168,6 +168,7 @@ for...
 | `name` | recommended | Display name; defaults to filename stem |
 | `description` | yes | Used by Cascade and Copilot to decide when to surface the agent |
 | `model` | optional | Pinned model the harness should switch to when invoked |
+| `model_reasoning_effort` | optional | Native Codex reasoning effort, supplied as a string |
 | `tools` | optional | Whitelist of tools the persona may call |
 | `color` | optional | Display color for harnesses that render it (Copilot, Claude, OpenCode). OpenCode requires a `#rgb`/`#rrggbb` hex literal or one of its theme names; see "Common pitfalls" below |
 | `handoffs` | optional | List of agent names (or VS Code structured handoff objects) this agent can hand off to |
@@ -182,9 +183,21 @@ of the supported capability tags (`read`, `write`, `shell`, `web`,
 `*`). If any unsupported tag is present, the agent is not deployed at
 all -- APM fails closed. Kiro may warn and fall back if the specified
 `model` is unavailable; APM passes the value through without
-validation. Codex translates only `name`, `description`, and the
-Markdown body; APM does not yet generate the complete per-agent MCP
-transport definitions needed to preserve `model` or `tools`. When
+validation.
+
+Codex receives `name`, `description`, and the Markdown body as
+`developer_instructions`. Supplied string values for `model` and
+`model_reasoning_effort` become top-level keys in the generated agent TOML,
+as documented in the [Codex custom agent format](https://developers.openai.com/codex/subagents/#custom-agents).
+Omitted fields remain absent; APM does not translate model names, choose
+defaults, or validate which models and effort values your Codex supports.
+Non-string values are dropped with a warning naming the field.
+
+Other frontmatter fields are dropped with a warning that APM does not
+translate them for Codex. This includes other native Codex settings and
+any `codex:` block; there is no namespaced or arbitrary passthrough.
+Remove unnecessary fields, or do not rely on their settings in the
+generated agent. APM still cannot preserve `tools` restrictions. When
 `tools` is present, `apm install` warns that the generated agent may
 inherit every project or session MCP server. Remove `tools` if
 unrestricted access is intentional; otherwise, do not use the
@@ -222,7 +235,7 @@ offending package and field so you can fix the source.
 | grok-build | `.grok/agents/<name>.md` | verbatim |
 | cursor | `.cursor/agents/<name>.md` | verbatim |
 | opencode | `.opencode/agents/<name>.md` | verbatim |
-| codex | `.codex/agents/<name>.toml` | `name` and `description` -> TOML; body becomes `developer_instructions`; unsupported `tools` emits a warning |
+| codex | `.codex/agents/<name>.toml` | `name`, `description`, and supplied string `model` / `model_reasoning_effort` -> top-level TOML; body becomes `developer_instructions`; dropped metadata emits warnings |
 | kiro | `.kiro/agents/<relative-stem>.md` | `description`, `model`, `tools` kept; `name` and unknown fields stripped; identity from path; fail closed on unsupported tools (ref: [kiro.dev/docs/custom-agents](https://kiro.dev/docs/custom-agents/), accessed 2026-08-03) |
 | grok-build | `.grok/agents/<name>.md` | verbatim |
 | windsurf | not deployed | Windsurf has no agents primitive -- author personas as skills (Cascade auto-invokes by description) |