Document (and optionally control) where UserPromptSubmit `additionalContext` lands relative to the user's prompt

What happened

A UserPromptSubmit hook returning hookSpecificOutput.additionalContext has its text delivered as a separate role: "developer" message appended after the user's prompt. Because the injected block is then the last thing the model reads, it can be mistaken for the task itself.

Observed on codex-cli 0.149.1, gpt-5.6-sol (high). A hook injected a style directive ("write in prose, not fragments…"). The model replied:

Understood. Ready for the task.

…and performed no work. The user's actual prompt was one position earlier and lost the attention contest to the trailing developer message.

Why this is a docs bug, not just a model quirk

The hooks reference says only that output is "added as extra developer context". It does not specify:

• the role the text is delivered under, or
• its position relative to the user's prompt.

Hook authors therefore have no way to know their text lands in the final, highest-salience slot of the context — which is exactly the position prompt-engineering guidance recommends for the one instruction you most want obeyed. Injected context placed there competes with the task instead of qualifying it.

The role: "developer" placement is visible in the transcript excerpt in #16933, but that issue is about TUI visibility, so the mechanism is only documented there by accident.

Contrast with Claude Code

Claude Code injects UserPromptSubmit context as a <system-reminder> inside the user turn, so it reads as an annotation on the prompt and the prompt stays last. Codex's hook input/output contract is otherwise Claude-compatible — the same hook scripts run unmodified in both — which makes this one silent divergence easy to hit when porting hooks.

Workaround

Prepending a task anchor to every Codex-bound injection, which re-points the model at the prompt:

[Directive attached to the user's message above — NOT a message of its own;
do not acknowledge it. The user's message is the task: execute it now, with
the directive below applied.]

This works, but it costs tokens on every turn and has to be applied by each hook author independently. Note that it must be phrased as an annotation; framing it as an out-of-band system command instead tends to trip the model's prompt-injection defenses, so it surfaces the text to the user rather than acting on it.

Requests

1. Document the role and the position of additionalContext relative to the user's prompt, for each event that supports it.
2. Optionally, offer in-turn placement — e.g. a placement field on hookSpecificOutput, or matching Claude Code's in-user-turn shape — so cross-harness hooks don't each need their own anchor.

Related

• #16933 — transcript excerpt showing the role: "developer" message (visibility ask, not placement)
• #16486, #20766, #21696 — all TUI-visibility asks; none change what the model sees
• #19385 — PreToolUse doesn't support additionalContext

Environment

• codex-cli 0.149.1, Linux
• Model: gpt-5.6-sol, reasoning effort high
• Hook: UserPromptSubmit, JSON output with hookSpecificOutput.additionalContext