From 6cfe810402d02cab40100be896bbb91bb367aeb1 Mon Sep 17 00:00:00 2001 From: pashpashpash Date: Fri, 24 Apr 2026 20:30:33 -0700 Subject: [PATCH] Refresh the Codex runtime docs Refresh the Codex runtime docs and cross-link the Codex harness, OpenAI provider, agent runtime, plugin hook, ACP agent, and status pages. --- docs/.i18n/glossary.zh-CN.json | 12 +++ docs/concepts/agent-runtimes.md | 10 ++- docs/concepts/model-providers.md | 6 +- docs/gateway/config-agents.md | 2 +- docs/plugins/codex-harness.md | 124 ++++++++++++++++++------------- docs/providers/openai.md | 8 +- docs/tools/acp-agents.md | 4 +- docs/tools/plugin.md | 3 +- 8 files changed, 113 insertions(+), 56 deletions(-) diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 92e3db5fe8e..05f4859ae63 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -3,6 +3,18 @@ "source": "OpenClaw", "target": "OpenClaw" }, + { + "source": "OpenAI", + "target": "OpenAI" + }, + { + "source": "OpenAI provider", + "target": "OpenAI provider" + }, + { + "source": "Status", + "target": "Status" + }, { "source": "Gateway", "target": "Gateway 网关" diff --git a/docs/concepts/agent-runtimes.md b/docs/concepts/agent-runtimes.md index e2b94797dbb..f8c41ed3a8f 100644 --- a/docs/concepts/agent-runtimes.md +++ b/docs/concepts/agent-runtimes.md @@ -46,6 +46,10 @@ That means OpenClaw selects an OpenAI model ref, then asks the Codex app-server runtime to run the embedded agent turn. It does not mean the channel, model provider catalog, or OpenClaw session store becomes Codex. +For the OpenAI-family prefix split, see [OpenAI](/providers/openai) and +[Model providers](/concepts/model-providers). For the Codex runtime support +contract, see [Codex harness](/plugins/codex-harness#v1-support-contract). + ## Runtime ownership Different runtimes own different amounts of the loop. @@ -84,7 +88,9 @@ OpenClaw chooses an embedded runtime after provider and model resolution: Explicit plugin runtimes fail closed by default. For example, `runtime: "codex"` means Codex or a clear selection error unless you set -`fallback: "pi"` in the same override scope. +`fallback: "pi"` in the same override scope. A runtime override does not inherit +a broader fallback setting, so an agent-level `runtime: "codex"` is not silently +routed back to PI just because defaults used `fallback: "pi"`. ## Compatibility contract @@ -122,6 +128,8 @@ session systems. ## Related - [Codex harness](/plugins/codex-harness) +- [OpenAI](/providers/openai) - [Agent harness plugins](/plugins/sdk-agent-harness) - [Agent loop](/concepts/agent-loop) - [Models](/concepts/models) +- [Status](/cli/status) diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index 0d979137b51..b1d14b2cfe2 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -20,7 +20,8 @@ For model selection rules, see [/concepts/models](/concepts/models). OpenAI API-key provider in PI, `openai-codex/` uses Codex OAuth in PI, and `openai/` plus `agents.defaults.embeddedHarness.runtime: "codex"` uses the native Codex app-server harness. See [OpenAI](/providers/openai) - and [Codex harness](/plugins/codex-harness). + and [Codex harness](/plugins/codex-harness). If the provider/runtime split is + confusing, read [Agent runtimes](/concepts/agent-runtimes) first. - Plugin auto-enable follows that same boundary: `openai-codex/` belongs to the OpenAI plugin, while the Codex plugin is enabled by `embeddedHarness.runtime: "codex"` or legacy `codex/` refs. @@ -75,6 +76,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no** - Optional rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (single override) - Example models: `openai/gpt-5.4`, `openai/gpt-5.4-mini` - GPT-5.5 direct API support is future-ready here once OpenAI exposes GPT-5.5 on the API +- Verify direct API availability with `openclaw models list --provider openai` + before using `openai/gpt-5.5` without the Codex app-server runtime - CLI: `openclaw onboard --auth-choice openai-api-key` - Default transport is `auto` (WebSocket-first, SSE fallback) - Override per model via `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`) @@ -118,6 +121,7 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no** - Auth: OAuth (ChatGPT) - PI model ref: `openai-codex/gpt-5.5` - Native Codex app-server harness ref: `openai/gpt-5.5` with `agents.defaults.embeddedHarness.runtime: "codex"` +- Native Codex app-server harness docs: [Codex harness](/plugins/codex-harness) - Legacy model refs: `codex/gpt-*` - Plugin boundary: `openai-codex/*` loads the OpenAI plugin; the native Codex app-server plugin is selected only by the Codex harness runtime or legacy diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md index fe82d8dc5d5..9224859790d 100644 --- a/docs/gateway/config-agents.md +++ b/docs/gateway/config-agents.md @@ -400,7 +400,7 @@ Codex app-server harness. For the mental model, see - `fallback`: `"pi"` or `"none"`. In `runtime: "auto"`, omitted fallback defaults to `"pi"` so old configs can keep using PI when no plugin harness claims a run. In explicit plugin runtime mode, such as `runtime: "codex"`, omitted fallback defaults to `"none"` so a missing harness fails instead of silently using PI. Runtime overrides do not inherit fallback from a broader scope; set `fallback: "pi"` alongside the explicit runtime when you intentionally want that compatibility fallback. Selected plugin harness failures always surface directly. - Environment overrides: `OPENCLAW_AGENT_RUNTIME=` overrides `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` overrides fallback for that process. - For Codex-only deployments, set `model: "openai/gpt-5.5"` and `embeddedHarness.runtime: "codex"`. You may also set `embeddedHarness.fallback: "none"` explicitly for readability; it is the default for explicit plugin runtimes. -- Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy sessions with transcript history but no recorded pin are treated as PI-pinned. `/status` shows non-PI harness ids such as `codex` next to `Fast`. +- Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy sessions with transcript history but no recorded pin are treated as PI-pinned. `/status` reports the effective runtime, for example `Runtime: OpenClaw Pi Default` or `Runtime: OpenAI Codex`. - This only controls the embedded chat harness. Media generation, vision, PDF, music, video, and TTS still use their provider/model settings. **Built-in alias shorthands** (only apply when the model is in `agents.defaults.models`): diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 17e2cfda206..ef5ea20e5b9 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -26,7 +26,7 @@ These are in-process OpenClaw hooks, not Codex `hooks.json` command hooks: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` -- `after_tool_call` +- `before_tool_call`, `after_tool_call` - `before_message_write` for mirrored transcript records - `agent_end` @@ -36,6 +36,9 @@ result is returned to Codex. This is separate from the public `tool_result_persist` plugin hook, which transforms OpenClaw-owned transcript tool-result writes. +For the plugin hook semantics themselves, see [Plugin hooks](/plugins/hooks) +and [Plugin guard behavior](/tools/plugin). + The harness is off by default. New configs should keep OpenAI model refs canonical as `openai/gpt-*` and explicitly force `embeddedHarness.runtime: "codex"` or `OPENCLAW_AGENT_RUNTIME=codex` when they @@ -369,9 +372,19 @@ To opt in to Codex guardian-reviewed approvals, set `appServer.mode: } ``` -Guardian is a native Codex approval reviewer. When Codex asks to leave the sandbox, write outside the workspace, or add permissions like network access, Codex routes that approval request to a reviewer subagent instead of a human prompt. The reviewer applies Codex's risk framework and approves or denies the specific request. Use Guardian when you want more guardrails than YOLO mode but still need unattended agents to make progress. +Guardian mode uses Codex's native auto-review approval path. When Codex asks to +leave the sandbox, write outside the workspace, or add permissions like network +access, Codex routes that approval request to the native reviewer instead of a +human prompt. The reviewer applies Codex's risk framework and approves or denies +the specific request. Use Guardian when you want more guardrails than YOLO mode +but still need unattended agents to make progress. -The `guardian` preset expands to `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"`, and `sandbox: "workspace-write"`. Individual policy fields still override `mode`, so advanced deployments can mix the preset with explicit choices. +The `guardian` preset expands to `approvalPolicy: "on-request"`, +`approvalsReviewer: "auto_review"`, and `sandbox: "workspace-write"`. +Individual policy fields still override `mode`, so advanced deployments can mix +the preset with explicit choices. The older `guardian_subagent` reviewer value is +still accepted as a compatibility alias, but new configs should use +`auto_review`. For an already-running app-server, use WebSocket transport: @@ -397,20 +410,20 @@ For an already-running app-server, use WebSocket transport: Supported `appServer` fields: -| Field | Default | Meaning | -| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` spawns Codex; `"websocket"` connects to `url`. | -| `command` | `"codex"` | Executable for stdio transport. | -| `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. | -| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | -| `mode` | `"yolo"` | Preset for YOLO or guardian-reviewed execution. | -| `approvalPolicy` | `"never"` | Native Codex approval policy sent to thread start/resume/turn. | -| `sandbox` | `"danger-full-access"` | Native Codex sandbox mode sent to thread start/resume. | -| `approvalsReviewer` | `"user"` | Use `"guardian_subagent"` to let Codex Guardian review prompts. | -| `serviceTier` | unset | Optional Codex app-server service tier: `"fast"`, `"flex"`, or `null`. Invalid legacy values are ignored. | +| Field | Default | Meaning | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` spawns Codex; `"websocket"` connects to `url`. | +| `command` | `"codex"` | Executable for stdio transport. | +| `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. | +| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | +| `mode` | `"yolo"` | Preset for YOLO or guardian-reviewed execution. | +| `approvalPolicy` | `"never"` | Native Codex approval policy sent to thread start/resume/turn. | +| `sandbox` | `"danger-full-access"` | Native Codex sandbox mode sent to thread start/resume. | +| `approvalsReviewer` | `"user"` | Use `"auto_review"` to let Codex review native approval prompts. `guardian_subagent` remains a legacy alias. | +| `serviceTier` | unset | Optional Codex app-server service tier: `"fast"`, `"flex"`, or `null`. Invalid legacy values are ignored. | The older environment variables still work as fallbacks for local testing when the matching config field is unset: @@ -477,7 +490,7 @@ Guardian-reviewed Codex approvals: appServer: { mode: "guardian", approvalPolicy: "on-request", - approvalsReviewer: "guardian_subagent", + approvalsReviewer: "auto_review", sandbox: "workspace-write", }, }, @@ -553,9 +566,11 @@ The Codex harness has three hook layers: | Codex native hooks | Codex | Low-level Codex lifecycle and native tool policy from Codex config. | OpenClaw does not use project or global Codex `hooks.json` files to route -OpenClaw plugin behavior. Codex native hooks are useful for Codex-owned -operations such as shell policy, native tool result review, stop handling, and -native compaction/model lifecycle, but they are not the OpenClaw plugin API. +OpenClaw plugin behavior. For the supported native tool and permission bridge, +OpenClaw injects per-thread Codex config for `PreToolUse`, `PostToolUse`, and +`PermissionRequest`. Other Codex hooks such as `SessionStart`, +`UserPromptSubmit`, and `Stop` remain Codex-level controls; they are not exposed +as OpenClaw plugin hooks in the v1 contract. For OpenClaw dynamic tools, OpenClaw executes the tool after Codex asks for the call, so OpenClaw fires the plugin and middleware behavior it owns in the @@ -564,10 +579,9 @@ OpenClaw can mirror selected events, but it cannot rewrite the native Codex thread unless Codex exposes that operation through app-server or native hook callbacks. -When newer Codex app-server builds expose native compaction and model lifecycle -hook events, OpenClaw should version-gate that protocol support and map the -events into the existing OpenClaw hook contract where the semantics are honest. -Until then, OpenClaw's `before_compaction`, `after_compaction`, `llm_input`, and +Compaction and LLM lifecycle projections come from Codex app-server +notifications and OpenClaw adapter state, not native Codex hook commands. +OpenClaw'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. @@ -583,31 +597,31 @@ around that boundary. 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. | -| OpenClaw channel routing and delivery | Supported | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime. | -| OpenClaw dynamic tools | Supported | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path. | -| Prompt and context plugins | Supported | OpenClaw builds prompt overlays and projects context into the Codex turn before starting or resuming the thread. | -| Context engine lifecycle | Supported | Assemble, ingest or 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 OpenClaw-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. | -| Native shell and patch block or observe | Supported through the native hook relay | Codex `PreToolUse` and `PostToolUse` are relayed for supported Codex-native tools. Blocking is supported; argument rewriting is not. | -| Native permission policy | Supported through the native hook relay | Codex `PermissionRequest` can be routed through OpenClaw policy where the runtime exposes it. | -| App-server trajectory capture | Supported | OpenClaw records the request it sent to app-server and the app-server notifications it receives. | +| Surface | Support | Why | +| --------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| OpenAI model loop through Codex | Supported | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation. | +| OpenClaw channel routing and delivery | Supported | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime. | +| OpenClaw dynamic tools | Supported | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path. | +| Prompt and context plugins | Supported | OpenClaw builds prompt overlays and projects context into the Codex turn before starting or resuming the thread. | +| Context engine lifecycle | Supported | Assemble, ingest or 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 OpenClaw-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. | +| Native shell and patch block or observe | Supported through the native hook relay | Codex `PreToolUse` and `PostToolUse` are relayed for the committed native tool surfaces. Blocking is supported; argument rewriting is not. | +| Native permission policy | Supported through the native hook relay | Codex `PermissionRequest` can be routed through OpenClaw policy where the runtime exposes it. | +| App-server trajectory capture | Supported | OpenClaw 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 OpenClaw 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. OpenClaw 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 OpenClaw-owned transcript writes, not Codex-native tool records. | Could mirror transformed records, but canonical rewrite needs Codex support. | -| Rich native compaction metadata | OpenClaw 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 OpenClaw compaction hooks are notification-level in Codex mode. | Add Codex pre/post compaction hooks if plugins need to veto or rewrite native compaction. | -| Stop or final-answer gating | Codex has native stop hooks, but OpenClaw does not expose final-answer gating as a v1 plugin contract. | Future opt-in primitive with loop and timeout safeguards. | -| Native MCP hook parity | Codex owns MCP execution, and full pre/post hook payload parity depends on Codex MCP handler support. | Add Codex MCP hook payloads, then relay them through the same native hook path. | -| Byte-for-byte model API request capture | OpenClaw 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. | +| Surface | V1 Boundary | Future Path | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| Native tool argument mutation | Codex native pre-tool hooks can block, but OpenClaw 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. OpenClaw 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 OpenClaw-owned transcript writes, not Codex-native tool records. | Could mirror transformed records, but canonical rewrite needs Codex support. | +| Rich native compaction metadata | OpenClaw 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 OpenClaw compaction hooks are notification-level in Codex mode. | Add Codex pre/post compaction hooks if plugins need to veto or rewrite native compaction. | +| Stop or final-answer gating | Codex has native stop hooks, but OpenClaw does not expose final-answer gating as a v1 plugin contract. | Future opt-in primitive with loop and timeout safeguards. | +| Native MCP hook parity as a committed v1 surface | The relay is generic, but OpenClaw has not version-gated and tested native MCP pre/post hook behavior end to end. | Add OpenClaw MCP relay tests and docs once the supported app-server protocol floor covers those payloads. | +| Byte-for-byte model API request capture | OpenClaw 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. | ## Tools, media, and compaction @@ -617,6 +631,11 @@ OpenClaw still builds the tool list and receives dynamic tool results from the harness. Text, images, video, music, TTS, approvals, and messaging-tool output continue through the normal OpenClaw delivery path. +The native hook relay is intentionally generic, but the v1 support contract is +limited to the Codex-native tool and permission paths that OpenClaw tests. Do not +assume every future Codex hook event is an OpenClaw plugin surface until the +runtime contract names it. + Codex MCP tool approval elicitations are routed through OpenClaw'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 @@ -644,9 +663,11 @@ understanding continue to use the matching provider/model settings such as ## Troubleshooting -**Codex does not appear in `/model`:** enable `plugins.entries.codex.enabled`, -select an `openai/gpt-*` model with `embeddedHarness.runtime: "codex"` (or a -legacy `codex/*` ref), and check whether `plugins.allow` excludes `codex`. +**Codex does not appear as a normal `/model` provider:** that is expected for +new configs. Select an `openai/gpt-*` model with +`embeddedHarness.runtime: "codex"` (or a legacy `codex/*` ref), enable +`plugins.entries.codex.enabled`, and check whether `plugins.allow` excludes +`codex`. **OpenClaw uses PI instead of Codex:** `runtime: "auto"` can still use PI as the compatibility backend when no Codex harness claims the run. Set @@ -675,5 +696,8 @@ turn for that agent must be a Codex-supported OpenAI model. - [Agent Harness Plugins](/plugins/sdk-agent-harness) - [Agent runtimes](/concepts/agent-runtimes) - [Model Providers](/concepts/model-providers) +- [OpenAI provider](/providers/openai) +- [Status](/cli/status) +- [Plugin hooks](/plugins/hooks) - [Configuration Reference](/gateway/configuration-reference) - [Testing](/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/providers/openai.md b/docs/providers/openai.md index a8d43002f5b..78d30756276 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -15,6 +15,10 @@ OpenAI provides developer APIs for GPT models. OpenClaw supports three OpenAI-fa OpenAI explicitly supports subscription OAuth usage in external tools and workflows like OpenClaw. +Provider, model, runtime, and channel are separate layers. If those labels are +getting mixed together, read [Agent runtimes](/concepts/agent-runtimes) before +changing config. + ## Quick choice | Goal | Use | Notes | @@ -96,7 +100,9 @@ Choose your preferred auth method and follow the setup steps. `openai/*` is the direct OpenAI API-key route unless you explicitly force the Codex app-server harness. GPT-5.5 itself is currently subscription/OAuth - only; use `openai-codex/*` for Codex OAuth through the default PI runner. + only; use `openai-codex/*` for Codex OAuth through the default PI runner, or + use `openai/gpt-5.5` with `embeddedHarness.runtime: "codex"` for native + Codex app-server execution. ### Config example diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index 2d5484736b5..66e1fdfef50 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -66,7 +66,9 @@ injects a per-turn native hook relay so plugin hooks can block `PermissionRequest` events through OpenClaw approvals. The v1 relay is deliberately conservative: it does not mutate Codex-native tool arguments, rewrite Codex thread records, or gate final answers/Stop hooks. Use explicit -ACP only when you want the ACP runtime/session model. +ACP only when you want the ACP runtime/session model. The embedded Codex support +boundary is documented in the +[Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract). Natural-language triggers that should route to the ACP runtime: diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 8327b8383e0..6b24e48d5d2 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -420,7 +420,8 @@ Native Codex app-server runs bridge Codex-native tool events back into this hook surface. Plugins can block native Codex tools through `before_tool_call`, observe results through `after_tool_call`, and participate in Codex `PermissionRequest` approvals. The bridge does not rewrite Codex-native tool -arguments yet. +arguments yet. The exact Codex runtime support boundary lives in the +[Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract). For full typed hook behavior, see [SDK Overview](/plugins/sdk-overview#hook-decision-semantics).