cx-viewer 1.0.2 → 1.0.4

package/concepts/en/GlobalSettings.md

@@ -1,4 +1,4 @@
-# CC-Viewer Configuration Reference
+# CX-Viewer Configuration Reference
 
 ## 1. Global Settings Panel (UI)
 
@@ -8,7 +8,7 @@ Open via top-left menu → "Global Settings".
 |---------|------|---------|-------------|
 | Filter Irrelevant Requests | Switch | On | Hide heartbeat, count_tokens, sub-agent and other non-main-agent requests |
 | Expand Body Diff JSON | Switch | Off | Expand Body Diff section by default in request detail panel |
-| Log Directory | Text Input | `~/.claude/cc-viewer` | Root directory for project log read/write. Supports `~/` expansion. Takes effect immediately on Enter or blur |
+| Log Directory | Text Input | `~/.codex/cx-viewer` | Root directory for project log read/write. Supports `~/` expansion. Takes effect immediately on Enter or blur |
 
 ## 2. Display Settings Panel (UI)
 
@@ -17,7 +17,7 @@ Open via top-left menu → "Display Settings".
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | Collapse Tool Results | Switch | On | Collapse tool call result blocks in chat view |
-| Expand Thinking | Switch | On | Expand Claude's thinking/reasoning blocks by default |
+| Expand Thinking | Switch | On | Expand Codex reasoning/thinking blocks by default |
 | Show Full Tool Content | Switch | Off | Show full untruncated tool call content |
 | Auto Resume Session | Switch + Options | Off | Automatically choose when session resume prompt appears: `Continue` or `New` |
 
@@ -33,7 +33,7 @@ All UI settings are persisted to `<log_dir>/preferences.json` via the `/api/pref
   "collapseToolResults": true,
   "expandThinking": true,
   "showFullToolContent": false,
-  "logDir": "~/.claude/cc-viewer",
+  "logDir": "~/.codex/cx-viewer",
   "resumeAutoChoice": null,
   "disabledPlugins": [],
   "presetShortcuts": []
@@ -55,94 +55,95 @@ All UI settings are persisted to `<log_dir>/preferences.json` via the `/api/pref
 
 ## 4. Environment Variables
 
-### CC-Viewer Specific
+### CX-Viewer Specific
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CCV_LOG_DIR` | `~/.claude/cc-viewer` | Log storage root directory. Special values: `tmp`/`temp` use system temp dir |
-| `CCV_CLI_MODE` | unset | `=1` enables CLI mode (PTY terminal) |
-| `CCV_SDK_MODE` | unset | `=1` enables Agent SDK mode (no terminal) |
-| `CCV_WORKSPACE_MODE` | unset | `=1` enables workspace selection mode |
-| `CCV_PROJECT_DIR` | `process.cwd()` | Project working directory for file operations and Git commands |
-| `CCV_PROXY_PORT` | unset | Local MITM proxy port |
-| `CCV_BYPASS_PERMISSIONS` | unset | `=1` skip tool permission approval (with `--dangerously-skip-permissions`) |
-| `CCV_DISABLE_DELTA` | unset | `=1` disable incremental log storage, write full messages every time |
-| `CCV_DEBUG` | unset | `=1` enable HTTP proxy debug logging |
-| `CCV_DEBUG_PLUGINS` | unset | `=1` enable plugin loading debug logging |
+| `CXV_LOG_DIR` | `~/.codex/cx-viewer` | Log storage root directory. Special values: `tmp`/`temp` use system temp dir |
+| `CXV_CLI_MODE` | unset | `=1` enables CLI mode (PTY terminal) |
+| `CXV_SDK_MODE` | unset | `=1` enables Codex SDK mode (no terminal) |
+| `CXV_WORKSPACE_MODE` | unset | `=1` enables workspace selection mode |
+| `CXV_PROJECT_DIR` | `process.cwd()` | Project working directory for file operations and Git commands |
+| `CXV_PROXY_PORT` | unset | Local Codex proxy port |
+| `CXV_BYPASS_PERMISSIONS` | unset | `=1` skip tool permission approval with Codex bypass mode |
+| `CXV_DISABLE_DELTA` | unset | `=1` disable incremental log storage, write full messages every time |
+| `CXV_DEBUG` | unset | `=1` enable debug logging |
+| `CXV_DEBUG_PLUGINS` | unset | `=1` enable plugin loading debug logging |
 
 ### Internal IPC
 
 | Variable | Description |
 |----------|-------------|
-| `CCVIEWER_PORT` | Server port for ask-bridge/perm-bridge communication |
-| `CCV_EDITOR_PORT` | Server port for ccv-editor file editing bridge |
+| `CXVIEWER_PORT` | Server port for ask-bridge/perm-bridge communication |
+| `CXV_EDITOR_PORT` | Server port for cxv-editor file editing bridge |
 
 ### External (Read-only)
 
 | Variable | Description |
 |----------|-------------|
-| `ANTHROPIC_BASE_URL` | Custom Anthropic API address |
+| `OPENAI_BASE_URL` | Custom OpenAI-compatible API base URL |
 | `SHELL` | User's shell (PTY spawn and shell config detection) |
 | `http_proxy` / `HTTPS_PROXY` etc. | HTTP proxy config (via undici EnvHttpProxyAgent) |
 
 ## 5. CLI Arguments
 
 ```
-ccv [options] [claude args...]
+cxv [options] [codex args...]
 ```
 
-### CC-Viewer Options
+### CX-Viewer Options
 
 | Argument | Description |
 |----------|-------------|
-| `-logger` | Install/repair Claude Code hooks |
-| `--uninstall` / `-uninstall` | Remove all CC-Viewer integration |
+| `-logger` | Install/repair Codex logger integration |
+| `--uninstall` / `-uninstall` | Remove all CX-Viewer integration |
 | `--help` / `-h` / `help` | Show help text |
 | `--version` / `-v` | Show version |
 | `-SDK` / `--sdk` | Use Agent SDK mode |
-| `--d` | Shortcut for `--dangerously-skip-permissions` |
-| `--ad` | Shortcut for `--allow-dangerously-skip-permissions` |
-| `run` | Run command through proxy (`ccv run -- claude ...`) |
+| `--d` | Shortcut for `--dangerously-bypass-approvals-and-sandbox` |
+| `--ad` | Legacy compatibility flag for CXV-side bypass toggles |
+| `run` | Run command through the CXV wrapper (`cxv run -- codex ...`) |
 
-### Claude Pass-through (common)
+### Codex Pass-through (common)
 
 | Argument | Description |
 |----------|-------------|
-| `-c` / `--continue` | Continue last session |
-| `-r` / `--resume` | Resume specific session |
-| `-p` / `--print` | Non-interactive output |
+| `continue` | Resume the last session (`codex resume --last`) |
+| `resume [session-id]` | Resume a specific session |
+| `exec [prompt]` | Non-interactive Codex execution |
 | `--model` | Specify model |
-| `--permission-mode` | Permission mode |
-| `--system-prompt` | Custom system prompt |
-| `--max-budget-usd` | Maximum budget |
+| `--search` | Enable live web search mode |
+| `-C` / `--cd` | Set working directory |
+| `--sandbox` | Set sandbox mode |
+| `--ask-for-approval` | Set approval policy |
 
 ## 6. Hook Configuration
 
-CC-Viewer auto-registers hooks in `~/.claude/settings.json` under `hooks.PreToolUse`:
+CX-Viewer's Codex integration primarily uses the local wrapper/proxy path. Hook bridges use current Codex tool names only.
 
-### 1. AskUserQuestion Bridge
-- **Matcher**: `"AskUserQuestion"`
+### 1. request_user_input Bridge
+- **Matcher**: `"request_user_input"`
 - **Command**: `node <install_dir>/lib/ask-bridge.js`
-- **Purpose**: Forward Claude's questions to Web UI, wait for user answers
+- **Purpose**: Forward tool/user approval prompts to the Web UI when a bridge path is active
 
 ### 2. Permission Approval Bridge
 - **Matcher**: `""` (empty = match all tools)
 - **Command**: `node <install_dir>/lib/perm-bridge.js`
-- **Purpose**: Only `Bash`/`Edit`/`Write`/`NotebookEdit` require Web UI approval; others pass through
+- **Purpose**: Mutating or external tools such as `shell_command`, `apply_patch`, `web_search`, and `image_generation` require Web UI approval; others pass through
 
 ## 7. Shell Integration
 
-CC-Viewer injects a `claude()` function into `~/.zshrc` (or `.bashrc`):
+CX-Viewer can inject a `codex()` wrapper into `~/.zshrc` (or `.bashrc`) in logger mode:
 
 ```bash
-# >>> CC-Viewer Auto-Inject >>>
-claude() { ... }
-# <<< CC-Viewer Auto-Inject <<<
+# >>> CX-Viewer Auto-Inject >>>
+codex() { ... }
+# <<< CX-Viewer Auto-Inject <<<
 ```
 
-All `claude` commands are automatically routed through CC-Viewer proxy for log capture and Web UI features.
+Interactive `codex` commands are routed through CX-Viewer for log capture and Web UI features, while pass-through commands such as `codex --help` and `codex auth` continue to run directly.
 
-Uninstall: `ccv --uninstall` or manually delete content between the markers.
+Uninstall: `cxv --uninstall` or manually delete content between the markers.
 
 ## 8. Proxy Configuration (Proxy Profile)
 
@@ -187,7 +188,7 @@ Plugin enable/disable managed via `disabledPlugins` array in `preferences.json`.
 ## 10. Directory Structure
 
 ```
-~/.claude/cc-viewer/               # Log root directory
+~/.codex/cx-viewer/                # Log root directory
 ├── preferences.json               # User preferences
 ├── workspaces.json                # Workspace registry
 ├── profile.json                   # Proxy configuration
@@ -199,7 +200,7 @@ Plugin enable/disable managed via `disabledPlugins` array in `preferences.json`.
 │   └── images/                    # Persistent uploaded image copies
 └── ...
 
-/tmp/cc-viewer-uploads/            # Temporary upload file directory
+/tmp/cx-viewer-uploads/            # Temporary upload file directory
 ```
 
 ## 11. Server Configuration
@@ -224,9 +225,6 @@ Plugin enable/disable managed via `disabledPlugins` array in `preferences.json`.
 
 | Key | Description |
 |-----|-------------|
-| `cxv_cacheExpireAt` | Cache countdown expiration time |
-| `cxv_cacheType` | Cache type label |
-| `ccv_sseSlim` | Enable SSE incremental pruning (desktop performance optimization) |
-| `ccv_calibrationModel` | KV-Cache context window calibration model |
-| `ccv_fileExplorerOpen` | File explorer panel toggle |
-| `cc-viewer-terminal-width` | Terminal panel width (pixels) |
+| `cxv_viewMode` | Current responsive view mode override |
+| `cxv_fileExplorerOpen` | File explorer panel toggle |
+| `cx-viewer-terminal-width` | Terminal panel width (pixels) |

package/concepts/en/MainAgent.md

@@ -2,22 +2,22 @@
 
 ## Definition
 
-MainAgent is the primary request chain in Claude Code when not in agent team mode. Every interaction between the user and Claude Code produces a series of API requests, where MainAgent requests form the core conversation chain — they carry the complete system prompt, tool definitions, and message history.
+MainAgent is the primary request chain for Codex when it is handling the user's turn directly. Every user interaction can produce multiple captured entries; MainAgent entries form the core conversation chain. For OpenAI Responses API traffic, they carry `instructions`, `tools`, `input`, and response content.
 
 ## Identification
 
-In cc-viewer, MainAgent is identified by `req.mainAgent === true`, automatically tagged by `interceptor.js` during request capture.
+In CX-Viewer, MainAgent is identified by `req.mainAgent === true`. The tag is assigned by the capture layer for all supported Codex paths: OpenAI Responses API traffic, Codex app-server events, and Codex SDK events.
 
 Criteria (all must be met):
-- The request body contains a `system` field (system prompt)
-- The request body contains a `tools` array (tool definitions)
-- The system prompt contains "Claude Code" signature text
+- The entry is explicitly marked `mainAgent: true`
+- The entry is not marked as a subAgent or synthetic tool event
+- Responses API fallback detection checks for Codex `instructions`, an `input` array, and main-agent tool shape
 
 ## Differences from SubAgent
 
 | Feature | MainAgent | SubAgent |
 |---------|-----------|----------|
-| system prompt | Complete Claude Code main prompt | Streamlined task-specific prompt |
+| instructions | Complete Codex main instructions | Streamlined task-specific instructions |
 | tools array | Contains all available tools | Usually contains only a few tools needed for the task |
-| Message history | Accumulates full conversation context | Contains only sub-task related messages |
-| Caching behavior | Has prompt caching (5-minute TTL) | Usually no caching or smaller cache |
+| input | Accumulates full conversation context | Contains only sub-task related input |
+| Usage metadata | Full turn-level token usage when available | Per-subtask usage when the Codex source reports it |

package/concepts/en/ProxySwitch.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-Hot-Switch Proxy lets you dynamically redirect API requests to a different endpoint without restarting Claude Code. This is useful when using third-party API proxy services.
+Hot-Switch Proxy lets you dynamically redirect Codex/OpenAI API requests to a different endpoint without restarting the current CX Viewer session. This is useful when using a compatible third-party API proxy service.
 
-> ⚠️ Do not use this feature if you are a Claude Max subscriber.
+> Use only with endpoints and keys you are authorized to use. The active profile replaces request authentication and may route prompts, files, and tool context through the configured service.
 
 ## Fields
 
@@ -26,7 +26,7 @@ When a proxy is active, `interceptor.js` performs the following before each API
 
 ## Config File
 
-Configuration is stored at `~/.claude/cc-viewer/profile.json`. Click the folder icon in the title to open the directory:
+Configuration is stored at `~/.codex/cx-viewer/profile.json`. Click the folder icon in the title to open the directory:
 
 ```json
 {

package/concepts/en/QRCode.md

@@ -2,28 +2,28 @@
 
 ## How It Works
 
-CC Viewer starts an HTTP server on your machine and generates a **local network address** (e.g., `http://192.168.1.100:7008`). Scan the QR code with your phone to access Claude Code from your mobile device over the same WiFi network.
+CX Viewer starts an HTTP server on your machine and generates a **local network address** (e.g., `http://192.168.1.100:7008`). Scan the QR code with your phone to access the viewer from your mobile device over the same WiFi network.
 
 ## Why Can't I Connect?
 
 Common reasons:
 
 1. **Not on the same network** — Your phone and computer must be connected to the same WiFi (same router / same network name)
-2. **Firewall blocking** — macOS/Windows firewall may block incoming connections; allow CC Viewer's port
+2. **Firewall blocking** — macOS/Windows firewall may block incoming connections; allow CX Viewer's port
 3. **Corporate/school network isolation** — Some enterprise networks isolate device-to-device communication (AP isolation)
 4. **VPN interference** — A VPN on either device may disrupt the network path
 
 ## Security Notice
 
-> ⚠️ CC Viewer's LAN service is accessible to all devices on the same network by default.
+> CX Viewer's LAN service is accessible to all devices on the same network by default.
 
 - Be cautious when using on **public WiFi** (cafes, airports) — others on the same network could potentially access your service
-- CC Viewer uses **token-based authentication** for LAN access (token is embedded in the URL); requests without a valid token are rejected
+- CX Viewer uses **token-based authentication** for LAN access (token is embedded in the URL); requests without a valid token are rejected
 - Recommended for use on trusted home or office networks
 
 ## Beyond the LAN
 
-If you need remote access to Claude Code from a different network (e.g., when traveling):
+If you need remote access to CX Viewer from a different network (e.g., when traveling):
 
 - **Tunneling tools** — frp, ngrok, Tailscale, etc. to expose local services to the internet
-- **CC Viewer plugins** — Configure a proxy middleware via the plugin system for cross-network access (see plugin docs)
+- **CX Viewer plugins** — Configure a proxy middleware via the plugin system for cross-network access (see plugin docs)

package/concepts/en/ResponseFields.md

@@ -1,17 +1,17 @@
 # Response Body Field Reference
 
-Field reference for the Claude API `/v1/messages` response body.
+Field reference for CX-Viewer's normalized Codex response body.
 
 ## Top-Level Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
-| **model** | string | The model name actually used, e.g. `claude-opus-4-6` |
-| **id** | string | Unique identifier for this response, e.g. `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **model** | string | The model name actually used |
+| **id** | string | Unique response or streamed item identifier when available |
 | **type** | string | Always `"message"` |
 | **role** | string | Always `"assistant"` |
 | **content** | array | Array of content blocks output by the model, containing text, tool calls, thinking process, etc. |
-| **stop_reason** | string | Reason for stopping: `"end_turn"` (normal completion), `"tool_use"` (tool execution needed), `"max_tokens"` (token limit reached) |
+| **stop_reason** | string | Normalized reason/status for stopping, such as `"end_turn"`, `"completed"`, `"failed"`, or `"max_tokens"` |
 | **stop_sequence** | string/null | The sequence that triggered the stop, usually `null` |
 | **usage** | object | Token usage statistics (see below) |
 
@@ -27,24 +27,12 @@ Field reference for the Claude API `/v1/messages` response body.
 
 | Field | Description |
 |-------|-------------|
-| **input_tokens** | Number of input tokens that did not hit the cache (billed at full price) |
-| **cache_creation_input_tokens** | Number of tokens for newly created cache entries (cache write, billed higher than normal input) |
-| **cache_read_input_tokens** | Number of tokens that hit the cache (cache read, billed much lower than normal input) |
 | **output_tokens** | Number of tokens output by the model |
-| **service_tier** | Service tier, e.g. `"standard"` |
-| **inference_geo** | Inference geography, e.g. `"not_available"` means no geography info is provided |
-
-## cache_creation Sub-Fields
-
-| Field | Description |
-|-------|-------------|
-| **ephemeral_5m_input_tokens** | Number of tokens for short-term cache creation with a 5-minute TTL |
-| **ephemeral_1h_input_tokens** | Number of tokens for long-term cache creation with a 1-hour TTL |
-
-> **About cache billing**: The unit price of `cache_read_input_tokens` is much lower than `input_tokens`, while the unit price of `cache_creation_input_tokens` is slightly higher than normal input. Therefore, maintaining a high cache hit rate in ongoing conversations can significantly reduce costs. You can visually monitor this ratio through the "Hit Rate" metric in cc-viewer.
+| **reasoning_output_tokens** | Reasoning tokens when the source reports them |
+| **total_tokens** | Total tokens reported by the source |
 
 ## stop_reason Meanings
 
 - **end_turn**: The model completed its reply normally
-- **tool_use**: The model needs to call a tool; the content will include a `tool_use` block. The next request must append a `tool_result` in the messages to continue the conversation
+- **tool_use**: The model needs to call a tool; CX-Viewer shows the matching tool result when the capture source provides it
 - **max_tokens**: The reply was truncated due to reaching the `max_tokens` limit and may be incomplete

package/concepts/en/SubAgent-Search.md

@@ -2,13 +2,13 @@
 
 ## Definition
 
-Search is a sub-agent type spawned by Claude Code's main agent to perform codebase searches. It executes targeted file and content searches using tools like Glob, Grep, and Read, then returns the results to the parent agent.
+Search is a sub-agent type spawned by Codex's main agent to perform codebase searches. It discovers available search and reading capabilities through `tool_search`, then returns the results to the parent agent.
 
 ## Behavior
 
 - Spawned automatically when the main agent needs to search or explore the codebase
 - Runs in an isolated context with read-only access
-- Uses Glob for file pattern matching, Grep for content search, and Read for file inspection
+- Uses current Codex/deferred tools for file pattern matching, content search, and file inspection
 - Returns search results to the parent agent for further processing
 
 ## When It Appears

package/concepts/en/Teammate.md

@@ -2,22 +2,22 @@
 
 ## Definition
 
-A Teammate is a collaborative agent in Claude Code Agent Team mode. When the main agent creates a team via `TeamCreate` and spawns teammates using the `Agent` tool, each teammate runs as an independent agent process with its own context window and toolset, communicating with team members through `SendMessage`.
+A Teammate is a collaborative agent in Codex Agent Team mode. The main agent discovers the available multi-agent tools through `tool_search`; when those tools are available, each teammate runs as an independent agent process with its own context window and toolset.
 
 ## Differences from SubAgent
 
 | Feature | Teammate | SubAgent |
 |---------|----------|----------|
 | Lifecycle | Persistent, can receive multiple messages | One-off task, destroyed upon completion |
-| Communication | SendMessage bidirectional messaging | Parent→child unidirectional call, returns result |
+| Communication | Team messaging through the available multi-agent toolset | Parent→child unidirectional call, returns result |
 | Context | Independent full context, retained across turns | Isolated task context |
 | Collaboration | Team collaboration, can communicate with each other | Hierarchical structure, only interacts with parent agent |
 | Task Type | Complex multi-step tasks | Single tasks such as search and exploration |
 
 ## Behavior
 
-- Created by the main agent (team lead) via the `Agent` tool and assigned a `team_name`
-- Shares task lists through `TaskList` / `TaskGet` / `TaskUpdate`
+- Created by the main agent (team lead) through available multi-agent tooling and assigned a team identity
+- Shares task state through the available multi-agent task/status tools
 - Enters idle state after each turn, waiting to be woken by a new message
 - Can be gracefully terminated via `shutdown_request`
 

package/concepts/en/Tool-apply_patch.md

@@ -0,0 +1,11 @@
+# apply_patch
+
+`apply_patch` is Codex's structured file-editing tool. It accepts a freeform patch, not JSON.
+
+Use it to:
+
+- Add, delete, or update repository files.
+- Keep edits reviewable instead of writing files through shell redirection.
+- Express focused local changes precisely.
+
+Legacy `FileChange` and `fileChange` entries map to this tool.

package/concepts/en/Tool-create_goal.md

@@ -0,0 +1,8 @@
+# create_goal
+
+`create_goal` starts a new active goal only when the user or system explicitly asks for one. It fails if an unfinished goal already exists.
+
+Fields:
+
+- `objective`: concrete objective, required.
+- `token_budget`: optional; set it only when the user explicitly asks for a token budget.

package/concepts/en/Tool-exec.md

@@ -0,0 +1,88 @@
+# exec
+
+`exec` is the main Code Mode orchestration suite. It runs an async JavaScript module in a fresh V8 isolate and turns the tools loaded for the current turn into callable JavaScript methods. It is therefore more than a JavaScript evaluator: it is the composition layer for shell, file, planning, goal, MCP, web, image, plugin, and other dynamically loaded capabilities.
+
+## What the suite provides
+
+- **One JavaScript surface for many tools.** Every enabled nested tool is available on the global `tools` object.
+- **Sequential composition.** A result from one tool can be inspected and passed into the next tool in the same script.
+- **Parallel orchestration.** Independent calls can be combined with `Promise.all` to reduce round trips.
+- **Dynamic discovery.** `ALL_TOOLS` exposes enabled tool metadata, including deferred tools that may not appear in the generated reference text.
+- **Typed call guidance.** The runtime description generates TypeScript-like declarations from each nested tool's input and output schema.
+- **Incremental and multimodal output.** Scripts can emit text, ordinary images, generated images, and immediate progress notifications.
+- **Cross-call state.** Serializable values can be stored and loaded by later `exec` calls in the same session.
+- **Long-running cells.** Work that outlives the initial yield window returns a cell id and continues through `wait`.
+
+Nested tools keep their own schemas, sandbox boundaries, and approval requirements. Calling a tool through `exec` does not bypass its policy.
+
+## Calling nested tools
+
+Tool names are normalized into valid JavaScript identifiers. A plain tool such as `shell_command` is called as `tools.shell_command(...)`; a namespaced tool such as `web.run` is exposed as a name like `tools.web__run(...)`.
+
+- Function tools take an object argument.
+- Freeform tools, such as `apply_patch`, take a string argument.
+- A nested call returns an object or string according to that tool's contract.
+- Deferred tools remain discoverable by filtering `ALL_TOOLS` by `name` or `description`.
+
+Sequential composition:
+
+```js
+const goal = await tools.get_goal({});
+text(goal);
+```
+
+Parallel composition:
+
+```js
+const [status, resources] = await Promise.all([
+  tools.shell_command({ command: "git status --short", workdir: "/workspace" }),
+  tools.list_mcp_resources({}),
+]);
+text(status);
+text(resources);
+```
+
+## Runtime helpers
+
+| Helper | Purpose |
+| --- | --- |
+| `text(value)` | Append text output; objects should be serialized explicitly when needed. |
+| `image(value, detail?)` | Forward a base64 data URL, image item, or MCP image content block. |
+| `generatedImage(result)` | Forward an image-generation result and optional output hint. |
+| `notify(value)` | Emit an additional output immediately while the script continues. |
+| `store(key, value)` | Save a serializable value for later `exec` calls in this session. |
+| `load(key)` | Read a value previously saved with `store`. |
+| `exit()` | Finish the script successfully at the current point. |
+| `setTimeout` / `clearTimeout` | Schedule or cancel callbacks inside the isolate. |
+| `yield_control()` | Yield accumulated output immediately while leaving the script running. |
+| `ALL_TOOLS` | Inspect `{ name, description }` metadata for enabled nested tools. |
+
+Pending timers alone do not keep the isolate alive. Await an explicit promise when delayed work must complete.
+
+## Input and execution lifecycle
+
+The input is raw JavaScript source, not JSON, a quoted string, or a Markdown code block. The script is evaluated as an async module, so top-level `await` is available.
+
+An optional first-line pragma controls the initial yield window and direct output budget:
+
+```js
+// @exec: {"yield_time_ms": 10000, "max_output_tokens": 2000}
+const result = await tools.shell_command({
+  command: "npm test",
+  workdir: "/workspace",
+  timeout_ms: 120000,
+});
+text(result);
+```
+
+- `yield_time_ms` defaults to 10,000 milliseconds.
+- `max_output_tokens` defaults to 10,000 tokens.
+- When work is still running at the yield boundary, `exec` returns `Script running with cell ID ...`.
+- Pass that id to `wait`; repeat until the cell completes, or use `terminate: true` to stop it.
+- Once evaluation finishes, the isolate is destroyed and unawaited promises are discarded. Values survive only when explicitly saved with `store`.
+
+## Environment boundaries
+
+The isolate intentionally has no Node.js APIs, direct filesystem access, direct network access, or `console`. Use nested tools for those capabilities and explicit output helpers for results. HTTP image URLs cannot be passed directly to `generatedImage`; image output must follow the helper's data/result contract.
+
+This design lets one `exec` call act as a small, policy-aware workflow: discover capabilities, call several tools, branch on their results, preserve state, and emit only the useful combined output.

package/concepts/en/Tool-followup_task.md

@@ -0,0 +1,10 @@
+# followup_task
+
+`followup_task` assigns a follow-up task to an existing non-root agent and starts a turn when that agent is idle. If it is already running, the task is delivered at a safe message boundary or after the pending tool call.
+
+Fields:
+
+- `target`: agent id or canonical task name, required.
+- `message`: follow-up task instructions, required.
+
+It is intended for reusing an agent whose existing context is relevant to the next task.

package/concepts/en/Tool-get_goal.md

@@ -0,0 +1,5 @@
+# get_goal
+
+`get_goal` reads the current thread goal, including status, budget, token usage, elapsed time, and remaining budget.
+
+It is read-only and does not create or change a goal.

package/concepts/en/Tool-image_generation.md

@@ -0,0 +1,5 @@
+# image_generation
+
+`image_generation` generates PNG images. It is the currently loaded image-generation capability, not a legacy file-reading or editing tool.
+
+Use it for bitmap visual assets such as illustrations, textures, sprites, mockups, and transparent-background cutouts.

package/concepts/en/Tool-interrupt_agent.md

@@ -0,0 +1,9 @@
+# interrupt_agent
+
+`interrupt_agent` stops an agent's current turn, if one is running, and returns its previous status. The target remains available for later messages and follow-up tasks.
+
+Field:
+
+- `target`: agent id or canonical task name, required.
+
+Use it to redirect obsolete work, not as a replacement for normal messaging.

package/concepts/en/Tool-list_agents.md

@@ -0,0 +1,9 @@
+# list_agents
+
+`list_agents` reads the live agent tree for the current root thread and reports each task's status.
+
+Field:
+
+- `path_prefix`: optional canonical task-path prefix used to narrow the tree; omit it to list all live agents.
+
+This is a read-only inspection tool and does not start, interrupt, or close agents.

package/concepts/en/Tool-list_mcp_resource_templates.md

@@ -0,0 +1,8 @@
+# list_mcp_resource_templates
+
+`list_mcp_resource_templates` lists parameterized resource templates exposed by MCP servers. Templates are useful for dynamic context such as a file, record, or business object selected by parameters.
+
+Fields:
+
+- `server`: optional MCP server filter.
+- `cursor`: optional pagination cursor.

package/concepts/en/Tool-list_mcp_resources.md

@@ -0,0 +1,8 @@
+# list_mcp_resources
+
+`list_mcp_resources` lists resources provided by MCP servers. Resources can supply files, database schemas, or application-specific context, and should be preferred over web search when available.
+
+Fields:
+
+- `server`: optional MCP server filter.
+- `cursor`: optional pagination cursor.

package/concepts/en/Tool-read_mcp_resource.md

@@ -0,0 +1,10 @@
+# read_mcp_resource
+
+`read_mcp_resource` reads a concrete resource from an MCP server.
+
+Fields:
+
+- `server`: MCP server name, required.
+- `uri`: resource URI, required, usually from `list_mcp_resources`.
+
+Legacy generic `MCPToolCall` and `mcpToolCall` names are not current loaded tool names; they map here for compatibility.

package/concepts/en/Tool-request_user_input.md

@@ -0,0 +1,9 @@
+# request_user_input
+
+`request_user_input` asks the user one to three structured short questions in Plan mode. Use it only when the answer is genuinely useful for unblocking or materially improving the plan.
+
+Fields:
+
+- `questions`: required array of questions.
+- Each question includes `id`, `header`, `question`, and `options`.
+- `autoResolutionMs`: optional auto-continue window for non-blocking questions.

package/concepts/en/Tool-send_message.md

@@ -0,0 +1,10 @@
+# send_message
+
+`send_message` queues a message for an existing agent and delivers it promptly, without starting a new turn.
+
+Fields:
+
+- `target`: relative or canonical task name returned by `spawn_agent`, required.
+- `message`: context, evidence, or guidance to queue, required.
+
+Use `followup_task` instead when an idle target must actively start another task.

package/concepts/en/Tool-shell_command.md

@@ -0,0 +1,12 @@
+# shell_command
+
+`shell_command` runs commands in the user's shell. Calls must set `workdir` so command behavior does not depend on an implicit current directory.
+
+Common fields:
+
+- `command`: command to execute, required.
+- `workdir`: working directory, required.
+- `timeout_ms`: optional timeout.
+- `sandbox_permissions`: use the default sandbox, or request `require_escalated` when the command genuinely needs it.
+- `justification`: user-facing approval question for escalated commands.
+- `prefix_rule`: optional narrowly scoped persistent approval prefix.

package/concepts/en/Tool-spawn_agent.md

@@ -0,0 +1,11 @@
+# spawn_agent
+
+`spawn_agent` creates a sub-agent for one concrete, bounded task that can make useful progress independently. The new agent receives a canonical task name and shares the workspace with the root agent.
+
+Fields:
+
+- `task_name`: lowercase task identifier, required.
+- `message`: initial task instructions, required.
+- `fork_turns`: optional amount of recent conversation context to copy.
+
+Do not use it for work that is tightly sequential or lacks an independent deliverable.