nodmix 2026.5.25

package/docs/plugins/codex-harness-reference.md

@@ -0,0 +1,409 @@
+---
+summary: "Configuration, auth, discovery, and app-server reference for the Codex harness"
+title: "Codex harness reference"
+read_when:
+  - You need every Codex harness config field
+  - You are changing app-server transport, auth, discovery, or timeout behavior
+  - You are debugging Codex harness startup, model discovery, or environment isolation
+---
+
+This reference covers the detailed configuration for the bundled `codex`
+plugin. For setup and routing decisions, start with
+[Codex harness](/plugins/codex-harness).
+
+## Plugin config surface
+
+All Codex harness settings live under `plugins.entries.codex.config`.
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          discovery: {
+            enabled: true,
+            timeoutMs: 2500,
+          },
+          appServer: {
+            mode: "guardian",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Supported top-level fields:
+
+| Field                      | Default                  | Meaning                                                                                                                                   |
+| -------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `discovery`                | enabled                  | Model discovery settings for Codex app-server `model/list`.                                                                               |
+| `appServer`                | managed stdio app-server | Transport, command, auth, approval, sandbox, and timeout settings.                                                                        |
+| `codexDynamicToolsLoading` | `"searchable"`           | Use `"direct"` to put Nodmix dynamic tools directly in the initial Codex tool context.                                                  |
+| `codexDynamicToolsExclude` | `[]`                     | Additional Nodmix dynamic tool names to omit from Codex app-server turns.                                                               |
+| `codexPlugins`             | disabled                 | Native Codex plugin/app support for migrated source-installed curated plugins. See [Native Codex plugins](/plugins/codex-native-plugins). |
+| `computerUse`              | disabled                 | Codex Computer Use setup. See [Codex Computer Use](/plugins/codex-computer-use).                                                          |
+
+## App-server transport
+
+By default, Nodmix starts the managed Codex binary shipped with the bundled
+plugin:
+
+```bash
+codex app-server --listen stdio://
+```
+
+This keeps the app-server version tied to the bundled `codex` plugin instead of
+whichever separate Codex CLI happens to be installed locally. Set
+`appServer.command` only when you intentionally want to run a different
+executable.
+
+For an already-running app-server, use WebSocket transport:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            transport: "websocket",
+            url: "ws://gateway-host:39175",
+            authToken: "${CODEX_APP_SERVER_TOKEN}",
+            requestTimeoutMs: 60000,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Supported `appServer` fields:
+
+| Field                         | Default                                                | Meaning                                                                                                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `transport`                   | `"stdio"`                                              | `"stdio"` spawns Codex; `"websocket"` connects to `url`.                                                                                                                                                  |
+| `command`                     | managed Codex binary                                   | Executable for stdio transport. Leave unset to use the managed binary.                                                                                                                                    |
+| `args`                        | `["app-server", "--listen", "stdio://"]`               | Arguments for stdio transport.                                                                                                                                                                            |
+| `url`                         | unset                                                  | WebSocket app-server URL.                                                                                                                                                                                 |
+| `authToken`                   | unset                                                  | Bearer token for WebSocket transport.                                                                                                                                                                     |
+| `headers`                     | `{}`                                                   | Extra WebSocket headers.                                                                                                                                                                                  |
+| `clearEnv`                    | `[]`                                                   | Extra environment variable names removed from the spawned stdio app-server process after Nodmix builds its inherited environment.                                                                       |
+| `requestTimeoutMs`            | `60000`                                                | Timeout for app-server control-plane calls.                                                                                                                                                               |
+| `turnCompletionIdleTimeoutMs` | `60000`                                                | Quiet window after Codex accepts a turn or after a turn-scoped app-server request while Nodmix waits for `turn/completed`.                                                                              |
+| `mode`                        | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution.                                                                                                                                                           |
+| `approvalPolicy`              | `"never"` or an allowed guardian approval policy       | Native Codex approval policy sent to thread start, resume, and turn.                                                                                                                                      |
+| `sandbox`                     | `"danger-full-access"` or an allowed guardian sandbox  | Native Codex sandbox mode sent to thread start and resume. Active Nodmix sandboxes narrow `danger-full-access` turns to Codex `workspace-write`; the turn network flag follows Nodmix sandbox egress. |
+| `approvalsReviewer`           | `"user"` or an allowed guardian reviewer               | Use `"auto_review"` to let Codex review native approval prompts when allowed.                                                                                                                             |
+| `defaultWorkspaceDir`         | current process directory                              | Workspace used by `/codex bind` when `--cwd` is omitted.                                                                                                                                                  |
+| `serviceTier`                 | unset                                                  | Optional Codex app-server service tier. `"priority"` enables fast-mode routing, `"flex"` requests flex processing, and `null` clears the override. Legacy `"fast"` is accepted as `"priority"`.           |
+
+The plugin blocks older or unversioned app-server handshakes. Codex app-server
+must report stable version `0.125.0` or newer.
+
+## Approval and sandbox modes
+
+Local stdio app-server sessions default to YOLO mode:
+`approvalPolicy: "never"`, `approvalsReviewer: "user"`, and
+`sandbox: "danger-full-access"`. This trusted local operator posture lets
+unattended Nodmix turns and heartbeats make progress without native approval
+prompts that nobody is around to answer.
+
+If Codex's local system requirements file disallows implicit YOLO approval,
+reviewer, or sandbox values, Nodmix treats the implicit default as guardian
+instead and selects allowed guardian permissions. Hostname-matching
+`[[remote_sandbox_config]]` entries in the same requirements file are honored
+for the sandbox default decision.
+
+Set `appServer.mode: "guardian"` for Codex guardian-reviewed approvals:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            mode: "guardian",
+            serviceTier: "priority",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+The `guardian` preset expands to `approvalPolicy: "on-request"`,
+`approvalsReviewer: "auto_review"`, and `sandbox: "workspace-write"` when those
+values are allowed. Individual policy fields override `mode`. The older
+`guardian_subagent` reviewer value is still accepted as a compatibility alias,
+but new configs should use `auto_review`.
+
+When an Nodmix sandbox is active, the local Codex app-server process still
+runs on the Gateway host. Nodmix therefore keeps Codex's own filesystem
+sandbox for native code-mode turns. `danger-full-access` turns are narrowed to
+Codex `workspace-write`, and `workspace-write` turn `networkAccess` is derived
+from the Nodmix sandbox egress setting: Docker `network: "none"` stays
+offline, while `network: "bridge"` or a custom Docker network permits outbound
+access.
+
+On Ubuntu/AppArmor hosts, Codex bwrap can fail under `workspace-write` before
+the shell command starts. If you see
+`bwrap: setting up uid map: Permission denied` or
+`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`, run
+`nodmix doctor` and fix the reported host namespace policy for the Nodmix
+service user rather than granting broader Docker container privileges. Prefer
+a scoped AppArmor profile for the service process; the
+`kernel.apparmor_restrict_unprivileged_userns=0` fallback is host-wide and has
+security tradeoffs.
+
+## Auth and environment isolation
+
+Auth is selected in this order:
+
+1. An explicit Nodmix Codex auth profile for the agent.
+2. The app-server's existing account in that agent's Codex home.
+3. For local stdio app-server launches only, `CODEX_API_KEY`, then
+   `OPENAI_API_KEY`, when no app-server account is present and OpenAI auth is
+   still required.
+
+When Nodmix sees a ChatGPT subscription-style Codex auth profile, it removes
+`CODEX_API_KEY` and `OPENAI_API_KEY` from the spawned Codex child process. That
+keeps Gateway-level API keys available for embeddings or direct OpenAI models
+without making native Codex app-server turns bill through the API by accident.
+
+Explicit Codex API-key profiles and local stdio env-key fallback use app-server
+login instead of inherited child-process env. WebSocket app-server connections
+do not receive Gateway env API-key fallback; use an explicit auth profile or the
+remote app-server's own account.
+
+Stdio app-server launches inherit Nodmix's process environment by default.
+Nodmix owns the Codex app-server account bridge and sets `CODEX_HOME` to a
+per-agent directory under that agent's Nodmix state. That keeps Codex config,
+accounts, plugin cache/data, and thread state scoped to the Nodmix agent
+instead of leaking in from the operator's personal `~/.codex` home.
+
+Nodmix does not rewrite `HOME` for normal local app-server launches. Codex-run
+subprocesses such as `nodmix`, `gh`, `git`, cloud CLIs, and shell commands see
+the normal process home and can find user-home config and tokens. Codex may also
+discover `$HOME/.agents/skills` and `$HOME/.agents/plugins/marketplace.json`;
+that `.agents` discovery is intentionally shared with the operator home and is
+separate from isolated `~/.codex` state.
+
+Nodmix plugins and Nodmix skill snapshots still flow through Nodmix's own
+plugin registry and skill loader. Personal Codex `~/.codex` assets do not. If
+you have useful Codex CLI skills or plugins from a Codex home that should become
+part of an Nodmix agent, inventory them explicitly:
+
+```bash
+nodmix migrate codex --dry-run
+nodmix migrate apply codex --yes
+```
+
+If a deployment needs additional environment isolation, add those variables to
+`appServer.clearEnv`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`appServer.clearEnv` only affects the spawned Codex app-server child process.
+Nodmix removes `CODEX_HOME` and `HOME` from this list during local launch
+normalization: `CODEX_HOME` stays per-agent, and `HOME` stays inherited so
+subprocesses can use normal user-home state.
+
+## Dynamic tools
+
+Codex dynamic tools default to `searchable` loading. Nodmix does not expose
+dynamic tools that duplicate Codex-native workspace operations:
+
+- `read`
+- `write`
+- `edit`
+- `apply_patch`
+- `exec`
+- `process`
+- `update_plan`
+
+Most remaining Nodmix integration tools, such as messaging, media, cron,
+browser, nodes, gateway, `heartbeat_respond`, and `web_search`, are available
+through Codex tool search under the `nodmix` namespace. This keeps the initial
+model context smaller. `sessions_yield` and message-tool-only source replies
+stay direct because those are turn-control contracts. `sessions_spawn` stays
+searchable so Codex's native `spawn_agent` remains the primary Codex subagent
+surface, while explicit Nodmix or ACP delegation is still available through
+the `nodmix` dynamic tool namespace.
+
+Set `codexDynamicToolsLoading: "direct"` only when connecting to a custom Codex
+app-server that cannot search deferred dynamic tools or when debugging the full
+tool payload.
+
+## Timeouts
+
+Nodmix-owned dynamic tool calls are bounded independently from
+`appServer.requestTimeoutMs`. Each Codex `item/tool/call` request uses the first
+available timeout in this order:
+
+- A positive per-call `timeoutMs` argument.
+- For `image_generate`, `agents.defaults.imageGenerationModel.timeoutMs`.
+- For `image_generate` without a configured timeout, the 120 second
+  image-generation default.
+- For the media-understanding `image` tool, `tools.media.image.timeoutSeconds`
+  converted to milliseconds, or the 60 second media default.
+- The 30 second dynamic-tool default.
+
+Dynamic tool budgets are capped at 600000 ms. On timeout, Nodmix aborts the
+tool signal where supported and returns a failed dynamic-tool response to Codex
+so the turn can continue instead of leaving the session in `processing`.
+
+After Codex accepts a turn, and after Nodmix responds to a turn-scoped
+app-server request, the harness expects Codex to make current-turn progress and
+eventually finish the native turn with `turn/completed`. If the app-server goes
+quiet for `appServer.turnCompletionIdleTimeoutMs`, Nodmix best-effort
+interrupts the Codex turn, records a diagnostic timeout, and releases the
+Nodmix session lane so follow-up chat messages are not queued behind a stale
+native turn.
+
+Most non-terminal notifications for the same turn disarm that short watchdog
+because Codex has proven the turn is still alive. Raw `custom_tool_call_output`
+completions keep the short post-tool watchdog armed because they are the
+turn-scoped tool-result handoff. Completed `agentMessage` items and pre-tool raw
+assistant `rawResponseItem/completed` items arm the assistant-output release: if
+Codex then goes quiet without `turn/completed`, Nodmix best-effort interrupts
+the native turn and releases the session lane. Post-tool raw assistant progress
+keeps waiting for `turn/completed` or the terminal watchdog. Timeout diagnostics
+include the last app-server notification method and, for raw assistant response
+items, the item type, role, id, and a bounded assistant text preview.
+
+## Model discovery
+
+By default, the Codex plugin asks the app-server for available models. Model
+availability is owned by Codex app-server, so the list can change when Nodmix
+upgrades the bundled `@openai/codex` version or when a deployment points
+`appServer.command` at a different Codex binary. Availability can also be
+account-scoped. Use `/codex models` on a running gateway to see the live catalog
+for that harness and account.
+
+If discovery fails or times out, Nodmix uses a bundled fallback catalog for:
+
+- GPT-5.5
+- GPT-5.4 mini
+- GPT-5.2
+
+The current bundled harness is `@openai/codex` `0.132.0`. A `model/list` probe
+against that bundled app-server returned:
+
+| Model id            | Default | Hidden | Input modalities | Reasoning efforts        |
+| ------------------- | ------- | ------ | ---------------- | ------------------------ |
+| `gpt-5.5`           | Yes     | No     | text, image      | low, medium, high, xhigh |
+| `gpt-5.4`           | No      | No     | text, image      | low, medium, high, xhigh |
+| `gpt-5.4-mini`      | No      | No     | text, image      | low, medium, high, xhigh |
+| `gpt-5.3-codex`     | No      | No     | text, image      | low, medium, high, xhigh |
+| `gpt-5.2`           | No      | No     | text, image      | low, medium, high, xhigh |
+| `codex-auto-review` | No      | Yes    | text, image      | low, medium, high, xhigh |
+
+Hidden models can be returned by the app-server catalog for internal or
+specialized flows, but they are not normal model-picker choices.
+
+Tune discovery under `plugins.entries.codex.config.discovery`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          discovery: {
+            enabled: true,
+            timeoutMs: 2500,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Disable discovery when you want startup to avoid probing Codex and use only the
+fallback catalog:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          discovery: {
+            enabled: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Workspace bootstrap files
+
+Codex handles `AGENTS.md` itself through native project-doc discovery. Nodmix
+does not write synthetic Codex project-doc files or depend on Codex fallback
+filenames for persona files, because Codex fallbacks only apply when
+`AGENTS.md` is missing.
+
+For Nodmix workspace parity, the Codex harness resolves the other bootstrap
+files. `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` are forwarded as
+Nodmix Codex developer instructions because they define the active agent,
+available workspace guidance, and user profile. `HEARTBEAT.md` content is not
+injected; heartbeat turns get a collaboration-mode pointer to read the file when
+it exists and is non-empty. `BOOTSTRAP.md` and `MEMORY.md` when present are
+forwarded as Nodmix turn input reference context.
+
+## Environment overrides
+
+Environment overrides remain available for local testing:
+
+- `NODMIX_CODEX_APP_SERVER_BIN`
+- `NODMIX_CODEX_APP_SERVER_ARGS`
+- `NODMIX_CODEX_APP_SERVER_MODE=yolo|guardian`
+- `NODMIX_CODEX_APP_SERVER_APPROVAL_POLICY`
+- `NODMIX_CODEX_APP_SERVER_SANDBOX`
+
+`NODMIX_CODEX_APP_SERVER_BIN` bypasses the managed binary when
+`appServer.command` is unset.
+
+`NODMIX_CODEX_APP_SERVER_GUARDIAN=1` was removed. Use
+`plugins.entries.codex.config.appServer.mode: "guardian"` instead, or
+`NODMIX_CODEX_APP_SERVER_MODE=guardian` for one-off local testing. Config is
+preferred for repeatable deployments because it keeps the plugin behavior in the
+same reviewed file as the rest of the Codex harness setup.
+
+## Related
+
+- [Codex harness](/plugins/codex-harness)
+- [Codex harness runtime](/plugins/codex-harness-runtime)
+- [Native Codex plugins](/plugins/codex-native-plugins)
+- [Codex Computer Use](/plugins/codex-computer-use)
+- [OpenAI provider](/providers/openai)
+- [Configuration reference](/gateway/configuration-reference)

package/docs/plugins/codex-harness-runtime.md

@@ -0,0 +1,247 @@
+---
+summary: "Runtime boundaries, hooks, tools, permissions, and diagnostics for the Codex harness"
+title: "Codex harness runtime"
+read_when:
+  - You need the Codex harness runtime support contract
+  - You are debugging native Codex tools, hooks, compaction, or feedback upload
+  - You are changing plugin behavior across PI and Codex harness turns
+---
+
+This page documents the runtime contract for Codex harness turns. For setup and
+routing, start with [Codex harness](/plugins/codex-harness). For config fields,
+see [Codex harness reference](/plugins/codex-harness-reference).
+
+## Overview
+
+Codex mode is not PI with a different model call underneath. Codex owns more of
+the native model loop, and Nodmix adapts its plugin, tool, session, and
+diagnostic surfaces around that boundary.
+
+Nodmix still owns channel routing, session files, visible message delivery,
+Nodmix dynamic tools, approvals, media delivery, and a transcript mirror.
+Codex owns the canonical native thread, native model loop, native tool
+continuation, and native compaction unless the active Nodmix context engine
+declares that it owns compaction.
+
+Prompt routing follows the selected runtime, not just the provider string. A
+native Codex turn receives Codex app-server developer instructions, while an
+explicit PI compatibility route keeps the normal Nodmix/PI system prompt even
+when it uses Codex-flavored OpenAI auth or transport.
+
+Native Codex keeps Codex-owned base/model/personality instructions and
+project-doc behavior according to the active Codex thread config. Lightweight
+Nodmix runs still preserve their existing project-doc suppression. Nodmix
+developer instructions cover Nodmix runtime concerns such as source-channel
+delivery, Nodmix dynamic tools, ACP delegation, adapter context, and the
+active agent workspace profile files. Nodmix skill catalogs plus `MEMORY.md`
+and active `BOOTSTRAP.md` content are projected as turn input reference context
+for native Codex.
+
+## Thread bindings and model changes
+
+When an Nodmix session is attached to an existing Codex thread, the next turn
+sends the currently selected OpenAI model, approval policy, sandbox, and service
+tier to app-server again. Switching from `openai/gpt-5.5` to
+`openai/gpt-5.2` keeps the thread binding but asks Codex to continue with the
+newly selected model.
+
+## Visible replies and heartbeats
+
+When a direct/source chat turn runs through the Codex harness, visible replies
+default to the message tool: final assistant text stays private unless the
+agent calls `message(action="send")`. This matches GPT models well because they
+can decide whether source-channel output is useful. Set
+`messages.visibleReplies: "automatic"` to restore the old mode where final
+assistant text posts automatically.
+
+Codex heartbeat turns also get `heartbeat_respond` in the searchable Nodmix
+tool catalog by default, so the agent can record whether the wake should stay
+quiet or notify without encoding that control flow in final text.
+
+Heartbeat-specific initiative guidance is sent as a Codex collaboration-mode
+developer instruction on the heartbeat turn itself. Ordinary chat turns restore
+Codex Default mode instead of carrying heartbeat philosophy in their normal
+runtime prompt. When a non-empty `HEARTBEAT.md` exists, the heartbeat
+collaboration-mode instructions point Codex at the file instead of inlining its
+contents.
+
+## Hook boundaries
+
+The Codex harness has three hook layers:
+
+| Layer                                 | Owner                    | Purpose                                                             |
+| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
+| Nodmix plugin hooks                 | Nodmix                 | Product/plugin compatibility across PI and Codex harnesses.         |
+| Codex app-server extension middleware | Nodmix bundled plugins | Per-turn adapter behavior around Nodmix dynamic tools.            |
+| Codex native hooks                    | Codex                    | Low-level Codex lifecycle and native tool policy from Codex config. |
+
+Nodmix does not use project or global Codex `hooks.json` files to route
+Nodmix plugin behavior. For the supported native tool and permission bridge,
+Nodmix injects per-thread Codex config for `PreToolUse`, `PostToolUse`,
+`PermissionRequest`, and `Stop`.
+
+When Codex app-server approvals are enabled, meaning `approvalPolicy` is not
+`"never"`, the default injected native hook config omits `PermissionRequest` so
+Codex's app-server reviewer and Nodmix's approval bridge handle real
+escalations after review. Operators can explicitly add `permission_request` to
+`nativeHookRelay.events` when they need the compatibility relay.
+
+Other Codex hooks such as `SessionStart` and `UserPromptSubmit` remain
+Codex-level controls. They are not exposed as Nodmix plugin hooks in the v1
+contract.
+
+For Nodmix dynamic tools, Nodmix executes the tool after Codex asks for the
+call, so Nodmix fires the plugin and middleware behavior it owns in the
+harness adapter. For Codex-native tools, Codex owns the canonical tool record.
+Nodmix can mirror selected events, but it cannot rewrite the native Codex
+thread unless Codex exposes that operation through app-server or native hook
+callbacks.
+
+Codex app-server item notifications also provide async `after_tool_call`
+observations for native tool completions that are not already covered by the
+native `PostToolUse` relay. These observations are for telemetry and plugin
+compatibility only; they cannot block, delay, or mutate the native tool call.
+
+Compaction and LLM lifecycle projections come from Codex app-server
+notifications and Nodmix adapter state, not native Codex hook commands.
+Nodmix's `before_compaction`, `after_compaction`, `llm_input`, and
+`llm_output` events are adapter-level observations, not byte-for-byte captures
+of Codex's internal request or compaction payloads.
+
+Codex native `hook/started` and `hook/completed` app-server notifications are
+projected as `codex_app_server.hook` agent events for trajectory and debugging.
+They do not invoke Nodmix plugin hooks.
+
+## V1 support contract
+
+Supported in Codex runtime v1:
+
+| Surface                                       | Support                                                                          | Why                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI model loop through Codex               | Supported                                                                        | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation.                                                                                                                                                                                                                                                                          |
+| Nodmix channel routing and delivery         | Supported                                                                        | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime.                                                                                                                                                                                                                                                                    |
+| Nodmix dynamic tools                        | Supported                                                                        | Codex asks Nodmix to execute these tools, so Nodmix stays in the execution path.                                                                                                                                                                                                                                                                                |
+| Prompt and context plugins                    | Supported                                                                        | Nodmix projects Nodmix-specific prompt/context into the Codex turn while leaving Codex-owned base, model, personality, and configured project-doc prompts in the native Codex lane. Native Codex developer instructions accept only command guidance explicitly scoped to `codex_app_server`; legacy global command hints remain for non-Codex prompt surfaces. |
+| Context engine lifecycle                      | Supported                                                                        | Assemble, ingest, after-turn maintenance, and context-engine compaction coordination run for Codex turns.                                                                                                                                                                                                                                                           |
+| Dynamic tool hooks                            | Supported                                                                        | `before_tool_call`, `after_tool_call`, and tool-result middleware run around Nodmix-owned dynamic tools.                                                                                                                                                                                                                                                          |
+| Lifecycle hooks                               | Supported as adapter observations                                                | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads.                                                                                                                                                                                                                                           |
+| Final-answer revision gate                    | Supported through native hook relay                                              | Codex `Stop` is relayed to `before_agent_finalize`; `revise` asks Codex for one more model pass before finalization.                                                                                                                                                                                                                                                |
+| Native shell, patch, and MCP block or observe | Supported through native hook relay                                              | Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on Codex app-server `0.125.0` or newer. Blocking is supported; argument rewriting is not.                                                                                                                                                               |
+| Native permission policy                      | Supported through Codex app-server approvals and compatibility native hook relay | Codex app-server approval requests route through Nodmix after Codex review. The `PermissionRequest` native hook relay is opt-in for native approval modes because Codex emits it before guardian review.                                                                                                                                                          |
+| App-server trajectory capture                 | Supported                                                                        | Nodmix records the request it sent to app-server and the app-server notifications it receives.                                                                                                                                                                                                                                                                    |
+
+Not supported in Codex runtime v1:
+
+| Surface                                             | V1 boundary                                                                                                                                     | Future path                                                                               |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Native tool argument mutation                       | Codex native pre-tool hooks can block, but Nodmix does not rewrite Codex-native tool arguments.                                               | Requires Codex hook/schema support for replacement tool input.                            |
+| Editable Codex-native transcript history            | Codex owns canonical native thread history. Nodmix owns a mirror and can project future context, but should not mutate unsupported internals. | Add explicit Codex app-server APIs if native thread surgery is needed.                    |
+| `tool_result_persist` for Codex-native tool records | That hook transforms Nodmix-owned transcript writes, not Codex-native tool records.                                                           | Could mirror transformed records, but canonical rewrite needs Codex support.              |
+| Rich native compaction metadata                     | Nodmix observes compaction start and completion, but does not receive a stable kept/dropped list, token delta, or summary payload.            | Needs richer Codex compaction events.                                                     |
+| Compaction intervention                             | Current Nodmix compaction hooks are notification-level in Codex mode.                                                                         | Add Codex pre/post compaction hooks if plugins need to veto or rewrite native compaction. |
+| Byte-for-byte model API request capture             | Nodmix can capture app-server requests and notifications, but Codex core builds the final OpenAI API request internally.                      | Needs a Codex model-request tracing event or debug API.                                   |
+
+## Native permissions and MCP elicitations
+
+For `PermissionRequest`, Nodmix only returns explicit allow or deny decisions
+when policy decides. A no-decision result is not an allow. Codex treats it as no
+hook decision and falls through to its own guardian or user approval path.
+
+Codex app-server approval modes omit this native hook by default. This behavior
+applies when `permission_request` is explicitly included in
+`nativeHookRelay.events` or a compatibility runtime installs it.
+
+When an operator chooses `allow-always` for a Codex native permission request,
+Nodmix remembers that exact provider/session/tool input/cwd fingerprint for a
+bounded session window. The remembered decision is intentionally exact-match
+only: a changed command, arguments, tool payload, or cwd creates a fresh
+approval.
+
+Codex MCP tool approval elicitations are routed through Nodmix's plugin
+approval flow when Codex marks `_meta.codex_approval_kind` as
+`"mcp_tool_call"`. Codex `request_user_input` prompts are sent back to the
+originating chat, and the next queued follow-up message answers that native
+server request instead of being steered as extra context. Other MCP elicitation
+requests fail closed.
+
+## Queue steering
+
+Active-run queue steering maps onto Codex app-server `turn/steer`. With the
+default `messages.queue.mode: "steer"`, Nodmix batches steer-mode chat
+messages for the configured quiet window and sends them as one `turn/steer`
+request in arrival order.
+
+Codex review and manual compaction turns can reject same-turn steering. In that
+case, Nodmix waits for the active run to finish before starting the prompt.
+Use `/queue followup` or `/queue collect` when messages should queue by default
+instead of steering. See [Steering queue](/concepts/queue-steering).
+
+## Codex feedback upload
+
+When `/diagnostics [note]` is approved for a session using the native Codex
+harness, Nodmix also calls Codex app-server `feedback/upload` for relevant
+Codex threads. The upload asks app-server to include logs for each listed thread
+and spawned Codex subthreads when available.
+
+The upload goes through Codex's normal feedback path to OpenAI servers. If Codex
+feedback is disabled in that app-server, the command returns the app-server
+error. The completed diagnostics reply lists the channels, Nodmix session ids,
+Codex thread ids, and local `codex resume <thread-id>` commands for the threads
+that were sent.
+
+If you deny or ignore the approval, Nodmix does not print those Codex ids and
+does not send Codex feedback. The upload does not replace the local Gateway
+diagnostics export. See [Diagnostics export](/gateway/diagnostics) for the
+approval, privacy, local bundle, and group-chat behavior.
+
+Use `/codex diagnostics [note]` only when you specifically want the Codex
+feedback upload for the currently attached thread without the full Gateway
+diagnostics bundle.
+
+## Compaction and transcript mirror
+
+When the selected model uses the Codex harness, native thread compaction is
+delegated to Codex app-server unless an active context engine declares
+`ownsCompaction: true`. Owning context engines compact first and cause Nodmix
+to abandon the old Codex backend thread so the next turn can rehydrate a fresh
+thread from engine-managed context. Nodmix keeps a transcript mirror for
+channel history, search, `/new`, `/reset`, and future model or harness
+switching.
+
+When a context engine requests Codex thread-bootstrap projection, Nodmix
+projects tool-call names and ids, input shapes, and redacted tool-result content
+into the fresh Codex thread. It does not copy raw tool-call argument values into
+that projection.
+
+The mirror includes the user prompt, final assistant text, and lightweight Codex
+reasoning or plan records when the app-server emits them. Today, Nodmix only
+records native compaction start and completion signals. It does not yet expose a
+human-readable compaction summary or an auditable list of which entries Codex
+kept after compaction.
+
+Because Codex owns the canonical native thread, `tool_result_persist` does not
+currently rewrite Codex-native tool result records. It only applies when
+Nodmix is writing an Nodmix-owned session transcript tool result.
+
+## Media and delivery
+
+Nodmix continues to own media delivery and media provider selection. Image,
+video, music, PDF, TTS, and media understanding use matching provider/model
+settings such as `agents.defaults.imageGenerationModel`, `videoGenerationModel`,
+`pdfModel`, and `messages.tts`.
+
+Text, images, video, music, TTS, approvals, and messaging-tool output continue
+through the normal Nodmix delivery path. Media generation does not require PI.
+When Codex emits a native image-generation item with a `savedPath`, Nodmix
+forwards that exact file through the normal reply-media path even if the Codex
+turn has no assistant text.
+
+## Related
+
+- [Codex harness](/plugins/codex-harness)
+- [Codex harness reference](/plugins/codex-harness-reference)
+- [Native Codex plugins](/plugins/codex-native-plugins)
+- [Plugin hooks](/plugins/hooks)
+- [Agent harness plugins](/plugins/sdk-agent-harness)
+- [Diagnostics export](/gateway/diagnostics)
+- [Trajectory export](/tools/trajectory)