fix(codex): preserve native agent model settings

.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) |