[FEATURE] Mods: engine-owned prompt.submit receipt linked to native turn IDs

Preflight Checklist

• [x] I searched existing requests and did not find this submission-to-native-turn association request.
• [x] This is a single feature request: an authoritative receipt/lifecycle association for a native Mod submission.

Problem Statement

Is there already a supported engine-owned contract joining one exact $.prompt.submit call to its native turn(s)? If so, documentation of that contract would solve this without a new API.

An external review UI explicitly authorizes an exact message, then a session-local Mod submits it into the user's existing interactive conversation:

const result = await $.prompt.submit({ text, asUser: true })

The UI must distinguish “accepted/queued” from “this exact submission started/ended this native turn.” Matching text, keeping one pending request, or observing a successful submit return is insufficient when normal user input or another Mod has identical text. Uncertain outcomes must remain uncertain, not trigger a resend.

On exact native 2.1.291, the build-generated declarations expose:

• PromptSubmitResult: text/context/origin or drop, no new native turn/submission ID. Resolution may mean queued, not completed.
• PromptSubmitInput.turnId: the already-running turn, explicitly absent for a plugin's own submission; not the ID of its new turn.
• TurnStartInput: text and a freshly minted turnId, no submitted occurrence/origin/prompt ID.
• Classic prompt_id: prompt-grain correlation, with no documented equality/association to the native turn ID.
• next.origin / next.trace: caller/per-event middleware trace, without a documented cross-event submission-to-turn join.

Generated declaration SHA-256: c05419d753bc81d991ddec4b66af17a9172f498e59d28fad07a8e676635c07ce. This is a finding about the exact tested build, not a claim about every newer version.

Proposed Solution

Prefer an existing supported causal contract, if one exists. Otherwise expose an engine-minted submission receipt ID with an authoritative association to native turn IDs, for example:

1. $.prompt.submit returns a pinned submissionId on acceptance; prompt middleware sees the same ID.
2. A result or native lifecycle fact associates that ID with the exact turnId. It should work even if association becomes available after the acceptance result.
3. The association defines queued/new-turn/delivery-to-running-turn/batched disposition rather than making consumers infer it from timing. If several submissions share a turn, expose that relation explicitly.
4. Document behavior under concurrent producers, identical bodies, rewrites/drops, native errors/abort, and session replacement.

These IDs should be metadata only, not text or context the model reads. This is not a request for model-visible tags, permission approval, semantic-success guarantees, priority changes, or assistant/transcript capture.

Please also clarify whether “a turn of its own once idle” guarantees one new native turn per accepted plugin call under overlap. If not, consumers need to know that restriction rather than report a separate execution based on acceptance alone.

Alternative Solutions

• Text/hash equality: identical inputs are legitimate and carry no occurrence identity.
• One pending request / callback timing: a different producer or normal user can interleave. Single-flight within our Mod does not serialize all native producers.
• Classic prompt IDs: in the samples below, none equaled any observed native turn ID; the native starts' next.origin.plugin was always engine.
• Model-visible markers or reading transcripts: inappropriate for exact-message delivery and unnecessary if native receipts expose the association.
• A separate managed/SDK conversation or terminal paste: not the existing interactive conversation the user attached.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

1. The user attaches their existing interactive Claude conversation once to a review UI.
2. They authorize and send one exact review message; the Mod remains single-flight.
3. They continue using normal native input/tools, including a message whose bytes may equal the review message.
4. The UI reports start/end only from the authoritative receipt-to-turn association. Disconnect or missing evidence stays unresolved, without replay.

Additional Context

We ran a bounded zero-model native diagnostic on macOS, Node 26.5.1, exact native 2.1.291. An observer Mod and independent producers A/B used identical synthetic text with asUser:true.

Reproduction outline:

• Start a fresh interactive session with that same text as a public CLI startup argument (native composer origin).
• The observer records only source/caller metadata, byte digests, hashed classic/native IDs and ordering. It never reads session messages/transcripts or assistant output.
• Replace every turn.step with fixed synthetic text/stop chunks without calling next; delay the initial step 4 seconds.
• From $.clock.after callbacks, A/B attempt native submission while the initial turn is active. These are actual native API calls, not mocked submit events.
• Compare with one A submission after the initial turn completes.
• Block external outbound IP traffic and route the model base URL to a loopback rejector. Zero requests reached even that rejector; zero tools ran.

| Case | Mod API calls / nondropped returns | Later native starts / ends |
| --- | --- | --- |
| Isolated A control | 1 / 1 | 1 / 1 |
| Overlap A:2 + B:1 | 3 / 3 | 1 / 1 |
| Single-flight per producer A:1 + B:1 | 2 / 2 | 1 / 1 |

Counts exclude the initial composer turn. Both overlap runs were observed for 55 seconds before owned-process cleanup. All observed start texts and submit returns matched the fixed byte digest. Classic prompt IDs differed from native turn IDs; starts identified caller engine; submit returns had no checked join ID.

Limits: stubbed steps and metadata instrumentation affect scheduling. This is not physical-keyboard interleaving or proof that every input was consumed, lost, or universally coalesces. We inspected no model context. The A:2 fixture exceeds our intended single-flight; the separate A:1+B:1 control avoids that limitation. A sound existing documented contract would be preferable to an API addition.

Related but distinct:

• #101380 requests sender/delivery identity for agent messages, not an own-Mod submit receipt joined to native lifecycle.
• #95682 requests mid-turn priority; this request does not change priority.
• #101222 reports idle submits remaining pending; this request does not presume a retry or cancellation workaround.

References: Mods API, native events, build-generated declarations.