docs: clarify Agent harness's agentId suffix is a resume token, not a running signal

[zknpr]

Problem

The Claude Code harness appends a fixed-format suffix to every Agent() return:

agentId: <id> (use SendMessage with to: '<id>' to continue this agent)
<usage>total_tokens: ... duration_ms: ...</usage>

This is a resume token for continuing the same agent thread via SendMessage. It is not a "still running" or "in background" status signal — the agent has finished by the time the harness emits this suffix.

Evidence this confuses callers

Searching one real Claude Code session transcript (314 MB JSONL) for codex:codex-rescue activity:

• 1635 occurrences of the agentId: <id> (use SendMessage...) suffix appended to agent returns.
• 0 occurrences of the codex-companion's actual background-mode string started in the background as <jobId>.
• Multiple cases of the calling Claude misreading the harness suffix as a background-running indicator. Two literal turns from that transcript:

"That was the codex-rescue agent launcher completing — it spawned the actual codex CLI subprocess as background task bfp55bays and exited. The codex review itself (gpt-5.5 xhigh) is still running in background and will produce a separate completion notification when done."

"Task 3 dispatched async (codex working in background). Waiting for completion notification."

In both quoted turns the work had in fact completed — Agent() returned, the Codex task was done, and the misread came purely from the harness's resume-token suffix being mistaken for a status line.

The pattern is common enough that affected users have started memorializing it as project-level memory ("never say 'codex is still running in background' after Agent() returns; verify with git status / tests immediately") rather than fixing the underlying confusion at the plugin documentation layer.

Fix

Adds one bullet in two caller-side locations:

• plugins/codex/skills/codex-result-handling/SKILL.md — Internal guidance for presenting Codex helper output, which the caller (main Claude) consults when processing the agent's return.
• plugins/codex/commands/rescue.md Operating rules — the most common user-facing entry point, /codex:rescue.

The bullet explicitly:

1. Names the exact suffix format the harness emits.
2. Identifies it as a resume token, not a status signal.
3. Lists the two specific misreads that have actually occurred in practice ("Codex is running in background", "task dispatched async") so the rule has concrete anchors callers can pattern-match against.
4. Points callers to the real signal (stdout above the suffix) and to git status --short as the verify step when --write was in effect.

No functional changes

Documentation-only. Both edited files are caller-side guidance; no code paths change. +2 lines, 0 deletions.

🤖 Generated with Claude Code