feat(codex): complete phase-one runtime compatibility

docs/content/docs/framework/agent/runtime.en.mdx

@@ -28,7 +28,40 @@ agent = Agent(name="assistant", runtime="codex")
 | Value | Description |
 | :--- | :--- |
 | `adk` (default) | Google ADK's built-in execution flow; fits almost every case. |
-| `codex` | An alternative backend for advanced customization. |
+| `codex` | Uses the OpenAI Codex SDK to drive the inner loop. |
+
+Install the optional dependency before using the Codex runtime:
+
+```bash
+pip install "veadk-python[codex]"
+```
+
+### Codex security configuration
+
+Codex defaults to a session-isolated workspace, the `workspace_write` sandbox, no network access, and denial of escalated operations. Broader access must be enabled explicitly:
+
+```python title="agent.py"
+from veadk import Agent
+from veadk.runtime.codex import CodexRuntimeConfig
+
+agent = Agent(
+    name="assistant",
+    runtime="codex",
+    codex_runtime_config=CodexRuntimeConfig(
+        sandbox="workspace_write",
+        approval_mode="auto_review",
+        network_access=True,
+        # Set this explicitly to work inside an existing project.
+        workspace_root="/workspace/codex",
+    ),
+)
+```
+
+`full_access` and `reuse_workspace=True` relax filesystem isolation and should only be enabled in trusted environments.
+
+### Codex observability
+
+Codex-native lifecycle notifications and ADK Function/MCP tool calls are converted into ADK Events. Runtime logs use stable `codex_*` event names and attribution fields such as `invocation_id`, `call_id`, `tool`, `status`, and `duration_ms`. Tool arguments, tool results, API tokens, credentials, and backend addresses are not logged. Token usage is exposed through `codex_event_type=token_usage` events and the corresponding log entry.
 
 ## Request processing
 

docs/content/docs/framework/agent/runtime.mdx

@@ -28,7 +28,40 @@ agent = Agent(name="assistant", runtime="codex")
 | 取值 | 说明 |
 | :--- | :--- |
 | `adk`（默认） | 使用 Google ADK 内置的执行流程，适用于绝大多数场景。 |
-| `codex` | 其他执行后端，面向高级定制场景。 |
+| `codex` | 使用 OpenAI Codex SDK 驱动内层循环。 |
+
+使用 Codex runtime 前安装可选依赖：
+
+```bash
+pip install "veadk-python[codex]"
+```
+
+### Codex 安全配置
+
+Codex 默认使用独立 Session workspace、`workspace_write` 沙箱、禁用网络，并拒绝需要提权的操作。需要扩大权限时必须显式配置：
+
+```python title="agent.py"
+from veadk import Agent
+from veadk.runtime.codex import CodexRuntimeConfig
+
+agent = Agent(
+    name="assistant",
+    runtime="codex",
+    codex_runtime_config=CodexRuntimeConfig(
+        sandbox="workspace_write",
+        approval_mode="auto_review",
+        network_access=True,
+        # 若需在已有工程内工作，显式指定目录；默认使用 Session 隔离目录。
+        workspace_root="/workspace/codex",
+    ),
+)
+```
+
+`full_access` 和 `reuse_workspace=True` 会放宽不同调用之间的文件系统边界，只应在受信环境中开启。
+
+### Codex 可观测性
+
+Codex 原生生命周期和 ADK Function/MCP 工具调用都会转换为 ADK Event。运行日志使用稳定的 `codex_*` 事件名，并包含 `invocation_id`、`call_id`、`tool`、`status`、`duration_ms` 等可归因字段。日志不会记录工具参数、工具结果、API Token、凭证或后端地址；Token Usage 通过 `codex_event_type=token_usage` 事件及对应日志提供。
 
 ## 请求处理
 

examples/codex_with_skill_and_mcp/README.md

@@ -55,8 +55,10 @@ python examples/codex_with_skill_and_mcp/main.py
 
 ## Notes
 
-- Tools execute inside the runtime's shim, so they are invisible to Codex and do
-  not surface as separate ADK events (tracing/UI) today.
-- Interactive MCP auth (mid-turn credential prompts) is not driven under
-  `runtime="codex"`; static auth (headers / bearer token / ve-identity workload
-  tokens) works.
+- Tools are dispatched by the runtime shim, while calls, results, state
+  changes, confirmations, and authentication surface as standard ADK events
+  for Session/Trace/UI.
+- Static authentication (headers / bearer tokens / ve-identity workload
+  tokens) and ADK interactive authentication requested during tool execution
+  are supported. Authentication required before an MCP toolset can list tools
+  still depends on the corresponding ADK/MCP client capability.

examples/codex_with_skill_and_mcp/README.zh.md

@@ -47,6 +47,6 @@ python examples/codex_with_skill_and_mcp/main.py
 
 ## 说明
 
-- 工具在 runtime 的 shim 内执行，因此对 Codex 不可见，目前不会作为独立的 ADK 事件出现（trace/前端看不到这步）。
-- 交互式 MCP 鉴权（对话中途弹凭证）在 `runtime="codex"` 下不驱动；静态鉴权（header / bearer token / ve-identity workload token）可用。
+- 工具由 runtime 的 shim 调度，但调用、结果、状态变更、确认和鉴权都会作为标准 ADK 事件进入 Session/Trace/UI。
+- 支持静态鉴权（header / bearer token / ve-identity workload token）以及工具执行中触发的 ADK 交互式鉴权；MCP toolset 在列举工具前触发的鉴权仍取决于对应 ADK/MCP 客户端能力。
 ```

pyproject.toml

@@ -56,6 +56,10 @@ dependencies = [
 veadk = "veadk.cli.cli:veadk"
 
 [project.optional-dependencies]
+codex = [
+    "openai-codex==0.1.0b3",
+    "openai-codex-cli-bin==0.137.0a4",
+]
 extensions = [
     "redis>=5.0",                                           # For Redis database
     "cozeloop>=0.1.21",                                     # For Cozeloop Prompt manager