Codex to Untether event mapping
This document describes how Codex exec --json events are translated to Untether's normalised event model.
This document describes how Codex exec --json events are translated to Untether’s normalised event model.
Authoritative source: The schema definitions are in
src/untether/schemas/codex.pyand the translation logic is insrc/untether/runners/codex.py. When in doubt, refer to the code.
Invocation
Untether runs Codex non-interactively; it never stops to ask for approval, and approvals, plan mode, AskUserQuestion, live sessions and steer are Claude Code features (Antigravity CLI has its own, without live sessions). The argv (prompt on stdin) is:
codex [extra_args] [--profile <p>] [--model=<m>] [-c model_reasoning_effort=<level>] \
exec --json --skip-git-repo-check --color=never [--sandbox read-only] \
[resume <thread_id> | resume --last] -
extra_argsdefault to["-c", "notify=[]"]and sit at the root, beforeexec. A deny-list rejects managed flags (--json,--skip-git-repo-check,--color,--output-schema,--output-last-message,--ask-for-approval/-a, exec-only--ignore-rules/--ignore-user-config), bypass flags (--yolo,--dangerously-bypass-approvals-and-sandbox,--approve-for-me,--not-so-yolo,--dangerously-bypass-hook-trust,--sandbox danger-full-access,-cvalues mentioningdanger-full-access,:danger,bypassordangerously), workspace flags (--cd/-C,--worktree) and a bare--, in every spelling. A blocked flag stops the Codex engine loading, and the error names the flag (#209, see Engine CLI flags). Root--sandbox read-only|workspace-writestays allowed.- Approval policy (
/config→ Approval policy): full auto (default) adds no sandbox flag, so Codex uses its own sandbox setting. safe adds--sandbox read-onlyat theexeclevel (beforeresume, which has no--sandbox), so it outranks root-level sandbox flags andconfig.toml. Untether never passes--ask-for-approval:codex execignores it and forces approval tonever(#830). Any otherpermission_modevalue logscodex.permission_mode.unknownonce per value and runs full auto, except on a webhook run, which runs safe instead and logscodex.webhook_unknown_mode_safe(#1142). - Model and resume id are validated before spawn (no leading dash, no control characters;
runner.argv.invalid_value). The model is joined to its flag; the thread id is positional inexec resume, where clap (0.160.1) reads a dash-leading token as an option, so validation is the whole defence there (#1034). - Resume value = thread UUID only (#1065, checked on codex-cli 0.162.1, 2026-10-13).
codex exec resume [SESSION_ID]natively takes a thread id or a thread name, but an unknown name (or any other non-UUID value, such as a URL) silently starts a new thread instead of failing, while an unknown UUID fails cleanly (no rollout found for thread id …). Untether keys sessions on thethread.startedUUID, so a name never resumed under Untether anyway (the run failed the “emitted session id … but expected …” check after the new thread was created).CodexRunner.check_resume_valuetherefore refuses anything but a UUID before spawning. Native gap recorded here: thread names are not available on Untether’s surface; revisit if Codex adds a strict lookup (fail when the name is unknown) or reports the name with the thread id. - Reasoning (
/config→ Reasoning):low,medium,highorxhigh, passed as-c model_reasoning_effort=<level>.minimalis not offered (#416). - Exit code 2 with a clap argv error on stderr (
error: unexpected argument …and similar) also logscodex.argv.rejectedwith the argv, to flag upstream flag drift.
The 3-event Untether schema
The Untether event model uses 3 event types. The action event includes a phase field to represent started/updated/completed lifecycles.
1) started
Emitted once as soon as you know the resume token (Codex: thread.started.thread_id).
{
"type": "started",
"engine": "codex",
"resume": { "engine": "codex", "value": "0199..." },
"title": "Codex", // optional
"meta": { "model": "o3", "permissionMode": "safe" } // optional: used for 🏷 footer
}
Note: Codex JSONL does not include model or permission info in its event stream. The runner populates meta.model from the /config model override (falling back to codex-mini-latest for display), meta.effort when a reasoning level is set, and meta.permissionMode only when the approval policy is safe (non-default). See Invocation for what each setting does to argv.
2) action
Emitted for everything that is progress / updates / warnings / per-item lifecycle.
{
"type": "action",
"engine": "codex",
"action": {
"id": "item_5",
"kind": "tool", // command | tool | file_change | web_search | subagent | note | turn | warning | telemetry
"title": "docs.search", // short label for renderer
"detail": { ... } // structured payload (freeform)
},
"phase": "started", // started | updated | completed
"ok": true, // optional; present when phase=completed (or warnings)
"message": "optional text", // optional; logs/warnings can use this
"level": "info" // optional: debug|info|warning|error
}
3) completed
Emitted once at end-of-run with the final answer (from agent_message) and final status.
{
"type": "completed",
"engine": "codex",
"resume": { "engine": "codex", "value": "0199..." }, // if known
"ok": true,
"answer": "Done. I updated the docs...",
"error": null,
"usage": { "input_tokens": 24763, "cached_input_tokens": 24448, "cache_write_input_tokens": 0,
"output_tokens": 122, "reasoning_output_tokens": 64 } // optional; THREAD running total
}
The runner forwards turn.completed.usage unchanged: all five fields, as the thread’s running total. The bridge then rewrites the five flat fields to this run’s delta using the per-thread ledger in session_costs.json, and adds thread_total_usage (the running total) and token_delta_source (#419; details in the cheatsheet). /usage in a Codex chat shows the token totals of the chat’s last Codex session, with cached input and reasoning output shown as subsets (#417). Codex has no subscription-quota data.
Why this fits Untether cleanly:
- Your
startedcorresponds to the old “session.started” concept (runner learns resume token; bridge can now safely serialise per thread). - Your
actionis “everything that would have been action.started/action.completed/log/error” collapsed into one stream. - Your
completedcorresponds to finalRunResult+ status, using Codex’sagent_messageas the answer source.
How everything fits together (end-to-end)
From the bridge/runner point of view:
-
Bridge receives Telegram prompt
-
Bridge tries to extract a resume line (
codex resume <uuid>) from the message/reply (runner-owned parsing). -
Bridge calls
runner.run(prompt, resumeTokenOrNone) -
Codex runner spawns
codex exec --json ...and reads JSONL line-by-line. -
The first moment the runner can know thread identity is:
thread.started→ containsthread_id(this is your resume value)
-
Runner must (per Untether’s concurrency invariant) acquire the per-thread lock as soon as the new thread token is known, before emitting
started. -
Runner translates subsequent Codex JSONL lines into
actionevents for progress rendering. -
Runner captures the final answer from
item.completedwhereitem.type="agent_message". -
Runner emits exactly one
completedevent when the run ends (turn.completedor failure), including the captured final answer.
Direct translation: every Codex exec --json line → your 3-event schema
Codex emits two categories: top-level lines and item lines.
A) Top-level lines
thread.started
Codex:
{"type":"thread.started","thread_id":"0199..."}
→ Untether:
-
emit
started:resume.value = thread_id
This is exactly the “learn resume tag” moment you described.
turn.started
Codex:
{"type":"turn.started"}
→ Untether (recommended):
-
emit
actionwith a synthetic action id, e.g."turn_0"kind="turn",phase="started",title="turn started"
You can also drop it if your UI doesn’t care, but if you want “every codex type translates”, this maps cleanly into action.
turn.completed
Codex includes usage:
{"type":"turn.completed","usage":{...}}
→ Untether:
-
emit
completedok=trueanswer = last seen agent_message text(or""if none)usage = usage(optional)
This is your authoritative “run succeeded” boundary.
turn.failed
Codex:
{"type":"turn.failed","error":{"message":"..."}}
→ Untether:
-
emit
completedok=falseerror = error.messageanswer = last seen agent_message(if any; usually empty)
This is “run ended, but failed”.
Top-level error (stream error)
Codex:
{"type":"error","message":"stream error: broken pipe"}
Cheatsheet meaning: this is a fatal stream failure (not just a tool failure).
However, Codex may also emit transient reconnect notices as type="error" with
messages like "Reconnecting... 1/5" while it retries a dropped stream. Treat
those as non-fatal progress updates (do not end the run).
→ Untether (does not end the run on its own):
Reconnecting... N/M→actionwith idcodex.reconnect,kind="note",level="info",detail={ attempt, max };phase="started"for attempt 1,"updated"after, so the row updates in place- any other message → a warning
action(kind="warning",phase="completed",ok=false,level="warning",message=message)
The run ends via turn.completed / turn.failed, or when the process exits: a non-zero exit code emits a warning plus completed with ok=false (codex exec failed (rc=…) with a stderr excerpt); a clean exit with no turn.* emits completed with ok=true and the captured answer, or ok=false if no thread_id was ever seen.
B) Item lines: item.started, item.updated, item.completed
All item lines include item.id and it is stable across updates/completion.
That means your action.action.id should just be item.id — perfect match to “stable within a run”.
General rule (for any item.* line)
action.action.id = item.idaction.phase = started | updated | completedaction.action.kindderived fromitem.typeaction.action.detailcontains the relevant item fields (possibly trimmed)
Now, map each item.type:
Item-type mapping: item.type → action.kind/title/detail/ok
Below is a “complete coverage” mapping for all item types listed in the cheatsheet.
1) agent_message
Codex:
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"...","phase":"final_answer"}}
item.phase is optional (commentary, final_answer, or absent).
→ Untether:
phase="commentary"→actionwithkind="note",title=item.text,detail={ phase: "commentary" }on started/updated/completed (ok=trueon completion)- any other
agent_message: noaction; onitem.completedthe text is stored for the turn - the final answer is the turn’s last
final_answermessage, else its last message with no phase; it is delivered by the eventualcompletedevent (a newturn.startedresets it)
2) reasoning (usually only item.completed, if enabled)
Codex gives a text breadcrumb.
→ Untether action:
kind="note"title=item.textphasemaps 1:1 to started/updated/completed;ok=trueon completion
3) command_execution (item.started and item.completed)
Codex fields include command, status, aggregated_output (often noisy), and
exit_code (null or omitted until completion).
→ Untether action:
kind="command"title=item.commandwith the run directory prefix stripped from pathsphasemaps 1:1 to started/updated/completed- on completion:
detail={ exit_code, status }andok = (item.status == "completed")(andexit_code == 0when it is an int);aggregated_outputis never copied
Note: “failed” command becomes ok=false but it’s still just an action completion — the overall run might still succeed later, depending on agent behaviour.
4) file_change (only item.completed)
Codex contains changes[] and status.
→ Untether action:
kind="file_change"title= the changed paths joined with,(orN fileswhen none carry a path)detail={ changes: [{ path, kind }], status, error: null }phase="completed"(started/updated lines are ignored)ok = (item.status == "completed")
5) mcp_tool_call (item.started and item.completed)
Codex contains server/tool/arguments/status and may include result/error on completion. Result can be large; may include base64 in content blocks.
→ Untether action:
-
kind="tool" -
title=f"{item.server}.{item.tool}" -
detail={ server, tool, arguments, status } -
on completion, include summary of result:
- e.g.
detail.result_summary = { content_blocks: N, has_structured: bool } - include
detail.error_messageif failed
- e.g.
-
phasemaps 1:1 to started/updated/completed -
ok = (item.status == "completed" and item.error is None)
Full result.content is never copied into detail (it can hold large base64 blobs); only the summary is kept.
6) web_search (item.started and item.completed)
Codex includes query (empty on item.started), an untyped action
({"type": "search"|"open_page"|"find_in_page"|"other", …}) and, on
completion, opaque results. The schema keeps action/results as Any so an
unknown future action type never drops the line (#419).
→ Untether action (same raw id on both phases, so the started row completes in place):
-
kind="web_search" -
phase="started"/"completed",ok=trueon completion -
titlefromrunners/codex.py:_web_search_title():action.typetitle detail.action_typerendered prefix searchaction.query→query→ first 3queriesjoined with·(+(+N more))searchsearched:searchwith no query at allweb searchothernone open_pageaction.url→query→pageopen_pageopened:find_in_page"<pattern>" in <url>,"<pattern>", orurl→query→pagefind_in_pagefind in page:other/ absent / unknown,querynon-emptyquerysearchsearched:other/ absent / unknown, noqueryweb searchothernone -
detail={ query, action_type, url?, result_count? }— rawresultsare never copied (only their count). -
Claude’s
WebSearchsets noaction_typeand keeps thesearched:prefix.
7) todo_list (item.started, item.updated, item.completed)
Codex includes checklist items with completed booleans.
→ Untether action:
kind="note"title="todo <done>/<total>: <first unfinished item>"(…: donewhen all are complete;todowhen the list is empty)detail={ done, total }phasemaps 1:1 to started/updated/completedok=truewhen phase completed
This is the one case where item.updated is common; your unified action event is exactly the right shape for it.
8) Item error (non-fatal warning as an item; only item.completed)
Codex:
{"type":"item.completed","item":{"id":"item_9","type":"error","message":"command output truncated"}}
Cheatsheet: this is a non-fatal warning (different from top-level fatal error).
→ Untether action:
kind="warning"title="⚠️ " + item.message,detail={ message },message=item.message, whereitem.messagehas its paths sanitised first: a path under the home folder becomes~/…, one inside the project becomes relative, any other absolute path[path], and URLs[url](#1066)level="warning"phase="completed"(started/updated lines are ignored)ok=true: the progress row shows the ⚠️ as its status, not ✗; it does not end the run (#987)- a repeat of a message already shown in the run is dropped: Codex 0.160 emits each config warning (e.g. an ignored
[project]table in~/.codex/config.toml) twice, under two item ids
9) collab_tool_call and unknown item types
collab_tool_call (sub-agent coordination) decodes but emits no action. An item.* line whose item.type Untether doesn’t know decodes as unknown_item (instead of being dropped as invalid JSONL) and also emits nothing.
Suggested “single-pass” translator logic (pseudocode)
This shows how to implement it without needing more than one pass or complicated buffering:
final_answer = None
resume = None
did_emit_started = False
did_emit_completed = False
turn_index = 0
def emit(evt): yield evt # emit to the output event stream
for line in codex_jsonl_stream:
t = line["type"]
if t == "thread.started":
resume = {"engine": "codex", "value": line["thread_id"]}
# acquire per-thread lock here (for new sessions) before emitting started
emit({"type":"started","engine":"codex","resume":resume,"title":"Codex"})
did_emit_started = True
continue
if t == "turn.started":
emit({"type":"action","engine":"codex",
"action":{"id":f"turn_{turn_index}","kind":"turn","title":"turn started","detail":{}},
"phase":"started"})
continue
if t == "item.started" or t == "item.updated" or t == "item.completed":
item = line["item"]
item_type = item["type"]
item_id = item["id"]
if t == "item.completed" and item_type == "agent_message":
final_answer = item.get("text","")
continue
# map item_type -> kind/title/detail/ok
action_evt = map_item_to_action(item, phase=t.split(".")[1])
emit(action_evt)
continue
if t == "turn.completed":
emit({"type":"completed","engine":"codex","resume":resume,
"ok":True,"answer":final_answer or "",
"error":None,"usage":line.get("usage")})
did_emit_completed = True
continue
if t == "turn.failed":
emit({"type":"completed","engine":"codex","resume":resume,
"ok":False,"answer":final_answer or "",
"error":line["error"]["message"]})
did_emit_completed = True
continue
if t == "error": # stream error: progress/warning only, never ends the run
emit(reconnect_note_or_warning(line.get("message")))
continue
# If the stream ends without turn.completed/failed: rc != 0 -> completed ok=False;
# rc == 0 -> completed ok=True with final_answer (ok=False if no thread_id was seen)
This design preserves the Untether ordering/serialisation principles: started happens as soon as resume token is known, actions stream in order, and exactly one completed closes the run.
One practical note: what “completed” should mean
Even though you learn the final answer at agent_message, you generally want completed to be emitted at the turn boundary (turn.completed / turn.failed), because:
- you can attach usage (
turn.completed.usage) only there, - you guarantee
completedis truly the last event, - you still use
agent_messageas the authoritative answer payload.
That still matches your intent (“completed is when we get final answer”) because the answer comes from agent_message; you just publish it at the terminal boundary.