@open-agent-toolkit/cli 0.1.50 → 0.1.52

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.4
+version: 1.0.5
 description: Acts as a phase coordinator that dispatches one exact target-pinned task worker at a time, or executes exactly one bounded Task Scope when dispatched as a worker. Used by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -148,10 +148,12 @@ downgrade for a managed task.
 
 #### 4. Build the Exact Invocation Before Logging
 
-- Codex: use `providers.codex.dispatchArgs.variant` as the actual `agent_type`.
-  If the native host cannot select that registered role, launch a fresh Codex
-  child pinned to `selection.target.model` and `selection.target.effort` with
-  these canonical instructions and the Task Scope. If neither exact route is
+- Codex: use `providers.codex.dispatchArgs.variant` as the actual `agent_type`
+  and attempt the exact materialized `agent_type` first. Only explicit
+  pre-start native role-selection rejection of that exact `agent_type`, before
+  any child starts, permits a fresh pinned fallback: launch a fresh Codex child
+  pinned to `selection.target.model` and `selection.target.effort` with these
+  canonical instructions and the Task Scope. If neither exact route is
   available, block.
 - Claude: pass `providers.claude.dispatchArgs.model` as the actual Task `model`.
 - Cursor: pass `providers.cursor.dispatchArgs.model` byte-for-byte as the actual
@@ -163,6 +165,15 @@ transient retry must reuse the same exact role/model/effort payload. A
 substantive escalation must re-resolve another configured candidate without
 exceeding the same named maximum.
 
+The launcher-owned `target`, `model_axis`, and `effort_axis` come only from the
+resolver output and constructed invocation payload. They are immutable and
+must not be populated, replaced, or contradicted by worker self-report. Spawn
+acceptance confirms that configured invocation; worker output is only task
+outcome data. Missing telemetry, missing self-report, and accepted terminal
+results including `BLOCKED` never trigger fallback. Once a child starts, every
+terminal result is authoritative for that attempt and is not native
+role-selection rejection.
+
 #### 5. Dispatch and Verify Serially
 
 Run one exact task worker at a time, serially in the same worktree:

package/assets/docs/cli-utilities/configuration.md

@@ -453,7 +453,7 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
 - `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
 - `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
-- `workflow.postImplementSequence` — `wait`, `summary`, `pr`, or `docs-pr`. Controls what `oat-project-implement` chains after final review passes. `wait` stops without auto-chaining, `summary` runs only `oat-project-summary`, `pr` runs `oat-project-pr-final` (which auto-generates summary), `docs-pr` runs `oat-project-document` then `oat-project-pr-final`. When unset, the skill prompts.
+- `workflow.postImplementSequence` — legacy `wait`, `summary`, `pr`, or `docs-pr`, or `{ "preApproval": [...], "postApproval": [...] }`. Legacy values remain strings; structured arrays contain ordered, globally unique `summary`, `document`, and `pr` steps. Pre-approval steps run after final review and before final HiLL approval; post-approval steps run only after that approval. Plain retrieval keeps legacy strings and prints structured values as compact JSON; `--json` returns the raw value.
 - `workflow.reviewExecutionModel` — `subagent`, `inline`, or `fresh-session`. Default final-review execution model in `oat-project-implement`. `subagent` and `inline` run automatically. `fresh-session` is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to `subagent` or `inline` if you change your mind. When unset, the skill prompts.
 - `workflow.autoReviewAtHillCheckpoints` — boolean. Automatically run the extra lifecycle review when a HiLL checkpoint is reached. This does not control Tier 1 per-phase `oat-reviewer` gates, which run after each phase in Tier 1 regardless of this setting. When unset, the skill prompts.
 - `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.

package/assets/docs/cli-utilities/workflow-gates.md

@@ -518,7 +518,7 @@ Gate failure behavior is owned by the gate-aware skill:
 available target. Once a target actually runs, its exit code is the gate result;
 OAT does not try another target after a failed review.
 
-Gate target execution has a child-process timeout (default 10 minutes, override
+Gate target execution has a child-process timeout (default 15 minutes, override
 with `OAT_GATE_EXEC_TIMEOUT_MS`). When a review target times out, JSON output
 reports `status: review_failed`, `outcome: review_did_not_complete`,
 `timedOut: true`, and the timeout value so automation can distinguish a hung

package/assets/docs/provider-sync/commands.md

@@ -21,7 +21,7 @@ These command definitions inherit the cross-cutting CLI conventions in:
 
 - What it does: defines the day-to-day provider-sync command surface for inspecting state, reconciling provider views, and changing provider enablement.
 - When to use it: after you have canonical assets in place and need to check sync state, write provider views, or change provider config.
-- Primary commands: `oat status`, `oat sync`, `oat providers list`, `oat providers inspect`, `oat providers set`
+- Primary commands: `oat status`, `oat sync`, `oat providers list`, `oat providers inspect`, `oat providers set`, `oat providers codex materialize`
 
 ## `oat status`
 
@@ -71,6 +71,34 @@ Key behavior:
 - Options: `--enabled <providers>`, `--disabled <providers>` (comma-separated)
 - Changes take effect on next `oat sync`
 
+## `oat providers codex materialize`
+
+Purpose:
+
+- Materialize one canonical Markdown agent as a Codex TOML role and register it
+  in Codex configuration
+
+Required operands:
+
+```bash
+oat providers codex materialize <agent-name> \
+  --model <model-id> \
+  --effort <reasoning-effort>
+```
+
+Key behavior:
+
+- Project scope is the default and writes only `.codex/config.toml` plus the
+  project role file; `--scope user` writes only under `~/.codex`
+- `--agent-path` selects a specific canonical agent and `--role-name` overrides
+  the generated role name
+- Managed role registration enables multi-agent support and merges an
+  `agents.max_depth` floor of `2`
+- Project writes preserve a higher existing project depth or inherited user
+  depth without mutating user configuration; user writes do not inspect or
+  mutate project configuration
+- Existing unrelated Codex configuration and custom roles are preserved
+
 ## Notes
 
 - `oat init --scope project` is commonly used before provider-interop commands because it initializes `.oat/sync/config.json`.

package/assets/docs/provider-sync/providers.md

@@ -61,6 +61,9 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Codex `max` is a first-class dispatch effort. It is present only for the Sol family in the committed supported catalogue, for both implementer and reviewer roles.
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
+    - Managed Codex roles require `agents.max_depth >= 2` for the native topology: root (depth 0) → phase coordinator (depth 1) → task worker (depth 2). Sync and direct materialization merge that floor without lowering a higher target value; project writes also preserve a higher inherited user value.
+    - Project sync or materialization writes only the project's `.codex/config.toml`; explicit user-scope materialization writes only `~/.codex/config.toml`. Project scope may read the lower-precedence user depth, but never mutates user configuration.
+    - When managed roles exist and effective depth is missing, invalid, or below `2`, `oat doctor` and managed implementation preflight explain the topology and recommend `oat sync --scope project` or `oat sync --scope user` for the affected scope. Direct materialization with the same scope is the single-role repair path.
     - `oat-phase-implementer` is dual-mode: Phase Scope makes it a phase coordinator, while Task Scope makes the exact materialized variant a one-task worker. The coordinator does not implement ordinary tasks itself.
 
 ## Managed dispatch views
@@ -84,10 +87,16 @@ that repository change.
 
 At implementation time, the phase coordinator passes the recorded named
 maximum through invocation-only `--ceiling-tier`, resolves one exact candidate
-per bounded task, and dispatches one task worker at a time. Codex uses the
-resolver-returned materialized role. Claude and Cursor bind the exact model
-arguments described above. A missing or unselectable managed target blocks
-rather than falling back to the coordinator or a base role.
+per bounded task, and dispatches one task worker at a time. Codex first
+attempts the resolver-returned materialized role as the native `agent_type`.
+The launcher records the target, model axis, and effort axis from that resolved
+payload; worker self-report is not provenance and cannot replace those values.
+Only an explicit pre-start native role-selection rejection permits a fresh
+pinned-child fallback. An accepted child, including one that later returns
+`BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
+Claude and Cursor bind the exact model arguments described above. A missing or
+unselectable managed target blocks rather than falling back to the coordinator
+or a base role.
 
 ## Scope rules
 

package/assets/docs/provider-sync/scope-and-surface.md

@@ -48,9 +48,22 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
 - `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
 - Codex project-scope subagent sync writes `.codex/config.toml` and `.codex/agents/*.toml` at command layer after path-mapping sync. Every generated project Codex variant and registration is repository-owned, version-controlled provider output. OAT provides no automatic ignore mechanism for this project output; collaborators review and commit it like other project configuration.
+- Managed Codex roles require an effective `agents.max_depth` of at least `2` for `root (0) → phase coordinator (1) → task worker (2)`. Sync and direct materialization apply that floor without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in the project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
+- If a managed role has missing, invalid, or insufficient effective depth, `oat doctor` and managed implementation preflight report the topology and give a scope-specific repair: `oat sync --scope project` for project scope or `oat sync --scope user` for user scope. For a single role, use `oat providers codex materialize` with the same explicit scope.
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
 - Codex user-config materialization writes user-owned implementer and reviewer roles under the user provider directory, `~/.codex`; it does not write those roles into the repository.
 
+## Codex managed dispatch
+
+For managed Codex work, the resolver-returned materialized role is attempted as
+the native `agent_type` first. The launcher owns the resulting target, model,
+and reasoning-effort provenance, derived from the resolved candidate and
+compiled invocation payload; worker output cannot populate or overwrite it.
+A fresh pinned child is allowed only after explicit pre-start native
+role-selection rejection. Missing runtime telemetry, missing self-report, or a
+child accepted by the native route that later returns `BLOCKED` are not
+role-selection rejection and do not permit fallback.
+
 ## Non-interop namespaces in the same CLI
 
 - `oat project new <name>` (workflow/project scaffolding)

package/assets/docs/reference/cli-reference.md

@@ -66,7 +66,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#validating-plan-metadata).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#plan-declared-parallelism).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 - `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. For `artifact_validation_failed`, correct the artifact and rerun the gate for successful revalidation before receive. `targeting_correlation_failed` sets `receiveEligible: false`; do not run review-receive even if it reports an artifact path. Orchestrators should read the structured result rather than poll the filesystem. The command runs standalone (for example, `--review-scope final`), not only inside `oat-project-implement`. See [Workflow Gates → Gate completion signal](../cli-utilities/workflow-gates.md#gate-completion-signal).
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
@@ -92,7 +92,7 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
 - `workflow.hillCheckpointDefault` (`every` | `final`) — default HiLL checkpoint behavior in `oat-project-implement`
 - `workflow.archiveOnComplete` (`boolean`) — skip the archive prompt in `oat-project-complete`
 - `workflow.createPrOnComplete` (`boolean`) — skip the "Open a PR?" prompt in `oat-project-complete`
-- `workflow.postImplementSequence` (`wait` | `summary` | `pr` | `docs-pr`) — post-implementation chaining behavior
+- `workflow.postImplementSequence` (legacy `wait` | `summary` | `pr` | `docs-pr`, or structured `{preApproval, postApproval}` arrays) — approval-aware post-implementation chaining
 - `workflow.reviewExecutionModel` (`subagent` | `inline` | `fresh-session`) — default final-review execution model
 - `workflow.autoReviewAtHillCheckpoints` (`boolean`) — auto-run the extra lifecycle review at HiLL checkpoints
 - `workflow.autoNarrowReReviewScope` (`boolean`) — auto-narrow re-review scope to fix-task commits

package/assets/docs/workflows/projects/hill-checkpoints.md

@@ -10,7 +10,7 @@ OAT supports two checkpoint classes:
 - Workflow phase checkpoints
 - Plan phase checkpoints
 
-The [phase review gate](reviews.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
+The [Phase gate review](reviews.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
 
 ## Workflow checkpoints (`state.md`)
 

package/assets/docs/workflows/projects/implementation-execution.md

@@ -113,6 +113,19 @@ An unresolved non-interactive preflight blocks. Managed `Uncapped` and
 `Inherit Host Defaults` are explicit modes; omitted policy state is not an
 implicit fallback.
 
+For a managed Codex implementer, preflight also resolves the effective
+`agents.max_depth`. Native `root (0) → phase coordinator (1) → task worker (2)`
+execution requires a depth of at least `2`. Missing, invalid, or lower values
+block before dispatch and identify the owning scope:
+
+- Project scope: run `oat sync --scope project`
+- User scope: run `oat sync --scope user`
+- Single-role repair: rerun `oat providers codex materialize` with the required
+  agent name, model, effort, and matching scope
+
+Project preflight may inherit a valid higher user depth, but remediation never
+writes across the project/user boundary.
+
 ## Resolve the Effective Named Maximum
 
 For each phase, the orchestrator determines the task maximum:
@@ -202,9 +215,14 @@ candidate above the maximum or absent from the configured ladder blocks.
 Build the complete host payload before writing dispatch logs:
 
 - **Codex:** use `providers.codex.dispatchArgs.variant` as the actual
-  `agent_type`. If the registered role cannot be selected, launch a fresh Codex
-  child pinned to `selection.target.model` and `selection.target.effort` with
-  canonical `oat-phase-implementer` instructions and the Task Scope.
+  `agent_type`. An accepted launch with that exact materialized role is
+  authoritative evidence of the configured invocation for coordinators and
+  task workers. A fresh Codex child pinned to `selection.target.model` and
+  `selection.target.effort` is permitted only after an actual native
+  role-selection rejection; missing self-reporting or model/effort telemetry
+  does not justify the fallback. An accepted child, including one that later
+  returns `BLOCKED`, is a task outcome and never triggers another pinned-child
+  fallback.
 - **Claude:** pass `providers.claude.dispatchArgs.model` as the actual Task
   `model`. Its separate effort axis is `not-applicable`.
 - **Cursor:** pass `providers.cursor.dispatchArgs.model` byte-for-byte as the
@@ -238,6 +256,14 @@ Configured defaults and configured gate invocation remain distinct from runtime
 identity; when runtime identity is not observed, the report says so without
 weakening exact requested model or effort controls.
 
+After constructing the complete payload, the launcher records the selected
+target and requested model/effort controls in the report. Those configured
+invocation fields are launcher-owned and derive from resolver output plus the
+actual payload; worker output cannot populate or overwrite them. Optional
+coordinator or worker self-report remains non-authoritative runtime evidence.
+Runtime attestation, when available, is separate host-generated metadata rather
+than an agent claim.
+
 ## Task Scope and Commit Verification
 
 Each worker receives only one task:
@@ -348,6 +374,11 @@ context. An unresolved or verification-failing conflict stops fan-in.
 
 ## Phase Review Gate and HiLL
 
+Phase gate review is independent from HiLL: a configured passing gate continues
+automatically, while a HiLL checkpoint pauses for human approval. For the final
+phase, approval-aware post-implementation sequences run pre-approval work only
+after final review and post-approval work only after the recorded approval.
+
 After standard review passes and bookkeeping is committed, an enabled
 `oat_phase_review_gate` may run a target-neutral external review for the phase.
 Passing artifacts are still received for durable disposition; blocking

package/assets/docs/workflows/projects/lifecycle.md

@@ -84,6 +84,15 @@ This distinction matters during completion: `oat-project-complete` can skip the
 
 ### Auto-review at HiLL checkpoints
 
+### Approval-aware post-implementation sequencing
+
+`workflow.postImplementSequence` can use the legacy string values or a structured
+`{ preApproval, postApproval }` value. After the final review passes, OAT
+snapshots the effective sequence, runs ordered pre-approval steps, records final
+HiLL approval, and only then runs post-approval steps. The snapshot is
+restart-safe: an incomplete sequence routes back to implementation and resumes
+from its first incomplete step.
+
 When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (minors auto-converted to fix tasks, no user prompts). Disabled by default. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
 
 ### Phase-review setup during planning

package/assets/docs/workflows/projects/reviews.md

@@ -207,7 +207,24 @@ Final review `passed` gate requires:
   - Project-scope Codex role files are generated from canonical `.agents/agents/*.md` during `oat sync --scope project`.
   - User-config Codex roles materialize under `~/.codex`; project-config and supported-catalogue roles remain in the project-scoped, version-controlled `.codex` view.
   - Some Codex hosts require explicit user authorization before the skill may call `spawn_agent`. In those hosts, `oat-project-review-provide` should ask whether to delegate to `oat-reviewer` instead of reporting the reviewer as unresolved.
-- If subagent dispatch is unavailable, follow the existing fallback path (fresh session preferred, inline reset as fallback).
+  - An accepted launch using the exact materialized `agent_type` is authoritative
+    configured-invocation evidence for a reviewer. After the complete payload
+    is built, the launcher records its `target`, `model_axis`, and
+    `effort_axis`; reviewer self-report cannot supply or overwrite those
+    fields. Optional self-report is non-authoritative, while runtime
+    attestation is host-generated metadata.
+  - A fresh pinned CLI child is a fallback only for an actual native
+    role-selection rejection, never for absent self-reporting or model/effort
+    telemetry. A child accepted by the native host, including one that later
+    returns `BLOCKED`, has produced a review outcome and cannot trigger the
+    fallback.
+  - An accepted reviewer that returns `BLOCKED` blocks the relevant review. It
+    cannot trigger the pinned fallback, and absent findings in that blocked
+    outcome cannot be interpreted as a pass.
+- For unmanaged review dispatch, if subagent dispatch is unavailable, follow
+  the existing fallback path (fresh session preferred, inline reset as
+  fallback). This generic fallback does not override managed exact-target
+  rules: a managed reviewer that cannot be launched exactly blocks the review.
 
 ## Reference artifacts
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.50",
-  "docs-config": "0.1.50",
-  "docs-theme": "0.1.50",
-  "docs-transforms": "0.1.50"
+  "cli": "0.1.52",
+  "docs-config": "0.1.52",
+  "docs-theme": "0.1.52",
+  "docs-transforms": "0.1.52"
 }

package/assets/skills/oat-agent-instructions-analyze/references/docs/provider-reference.md

@@ -220,6 +220,8 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 - Enable feature flag in config:
   - `[features]`
   - `multi_agent = true`
+- For OAT's nested root → coordinator → worker topology, configure
+  `[agents] max_depth = 2` or higher.
 - Define role(s) in config:
   - `[agents.oat-reviewer]` (or role names your workflow dispatches)
 - Dispatch by role name using `agent_type` (not `subagent_type`).
@@ -228,8 +230,12 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 **Note on OAT provider sync:**
 
 - Codex runtime dispatch is config-role based (`[agents.<name>]`) and TOML-backed.
-- OAT currently does not sync canonical markdown agents into `.codex/agents`.
-- Canonical markdown agent definitions require a markdown→TOML adapter to become Codex-executable role configs.
+- OAT sync exports canonical Markdown agents as `.codex/agents/*.toml` role
+  configs and registers them in `.codex/config.toml`.
+- Project-scoped output is repository-owned and version controlled. Explicit
+  user-scope materialization writes under `~/.codex` instead.
+- Sync and direct materialization merge an `agents.max_depth` floor of `2`
+  without lowering a higher project or inherited user value.
 
 ### Other Codex Resources
 

package/assets/skills/oat-agent-instructions-apply/references/docs/provider-reference.md

@@ -220,6 +220,8 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 - Enable feature flag in config:
   - `[features]`
   - `multi_agent = true`
+- For OAT's nested root → coordinator → worker topology, configure
+  `[agents] max_depth = 2` or higher.
 - Define role(s) in config:
   - `[agents.oat-reviewer]` (or role names your workflow dispatches)
 - Dispatch by role name using `agent_type` (not `subagent_type`).
@@ -228,8 +230,12 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 **Note on OAT provider sync:**
 
 - Codex runtime dispatch is config-role based (`[agents.<name>]`) and TOML-backed.
-- OAT currently does not sync canonical markdown agents into `.codex/agents`.
-- Canonical markdown agent definitions require a markdown→TOML adapter to become Codex-executable role configs.
+- OAT sync exports canonical Markdown agents as `.codex/agents/*.toml` role
+  configs and registers them in `.codex/config.toml`.
+- Project-scoped output is repository-owned and version controlled. Explicit
+  user-scope materialization writes under `~/.codex` instead.
+- Sync and direct materialization merge an `agents.max_depth` floor of `2`
+  without lowering a higher project or inherited user value.
 
 ### Other Codex Resources