1# Codex Tool Mapping
2 
3Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
4 
5| Skill references | Codex equivalent |
6|-----------------|------------------|
7| `Task` tool (dispatch subagent) | `spawn_agent` (see [Subagent dispatch requires multi-agent support](#subagent-dispatch-requires-multi-agent-support)) |
8| Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
9| Task returns result | `wait_agent` |
10| Task completes automatically | `close_agent` to free slot |
11| `TodoWrite` (task tracking) | `update_plan` |
12| `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
13| `Read`, `Write`, `Edit` (files) | Use your native file tools |
14| `Bash` (run commands) | Use your native shell tools |
15 
16## Subagent dispatch requires multi-agent support
17 
18Add to your Codex config (`~/.codex/config.toml`):
19 
20```toml
21[features]
22multi_agent = true
23```
24 
25This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
26 
27Legacy note: Codex builds before `rust-v0.115.0` exposed spawned-agent
28waiting as `wait`. Current Codex uses `wait_agent` for spawned agents. The
29`wait` name now belongs to code-mode `exec/wait`, which resumes a yielded exec
30cell by `cell_id`; it is not the spawned-agent result tool.
31 
32## Environment Detection
33 
34Skills that create worktrees or finish branches should detect their
35environment with read-only git commands before proceeding:
36 
37```bash
38GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
39GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
40BRANCH=$(git branch --show-current)
41```
42 
43- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
44- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
45 
46See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
47Step 1 for how each skill uses these signals.
48 
49## Codex App Finishing
50 
51When the sandbox blocks branch/push operations (detached HEAD in an
52externally managed worktree), the agent commits all work and informs
53the user to use the App's native controls:
54 
55- **"Create branch"** — names the branch, then commit/push/PR via App UI
56- **"Hand off to local"** — transfers work to the user's local checkout
57 
58The agent can still run tests, stage files, and output suggested branch
59names, commit messages, and PR descriptions for the user to copy.
60