SingleShotOptions

Defined in: packages/core/src/runtime/singleShot.ts:92

Options that qualify a runSingleShot run without changing how it behaves.

Properties

announceOutstandingWork?

optional announceOutstandingWork?: boolean

Defined in: packages/core/src/runtime/singleShot.ts:131

[[EXT-158]] — announce, at the end of the run, that the agent’s own checklist still had non-completed items. Scope (d), decided here rather than in a red cell.

WHY THIS IS OPT-IN, AND WHY THE DEFAULT IS THE QUIET ONE

This runtime has two very different classes of caller. gth ask and gth exec are a person running a verb and reading what comes back — the surface this notice exists for, and they set this. gth batch, gth eval and gth workflow drive it as a HARNESS, hundreds of cells at a time, folding each run into a report; a per-cell sentence about an unfinished checklist is noise to a reader who is looking at aggregate outcomes, and it appears on precisely the cells that PASSED, since the notice speaks only for the completed ending.

A default-on flag with an opt-out would have put that output into every harness whose author never heard of this node, and the first anyone would know of it is a changed report. Default-off means the failure direction is a surface that stays silent until someone adds one line — which is a missing notice rather than a changed contract, and it is recoverable by the person who notices.

This is about the notice, never the detection. The fact is recorded on every run through every path; runner.getOutstandingWork() answers for a batch cell exactly as it does for gth ask. Only whether a sentence is printed is what this decides.

Note also that displayRunEndReport, which draws this notice, writes through displayNotice and so goes to stderr — so even switched on it cannot change the stdout a caller parses, nor the answer this function returns, which is what gth batch’s cases assert on.

announceResumeHint?

optional announceResumeHint?: boolean

Defined in: packages/core/src/runtime/singleShot.ts:171

GS2-106 — print the continue hint after the run (gth ask --resume <run id> "…"), subject to the user’s output.resumeHint rung. Opt-in for the reason announceOutstandingWork is: ask and exec set it; the harnesses do not, and their cells could not be resumed anyway. The gate itself, and why, is documented in runtime/resumeHint.ts.

announceRunRecap?

optional announceRunRecap?: boolean

Defined in: packages/core/src/runtime/singleShot.ts:163

[[EXT-178]] — request an end-of-run recap on this run, subject to the user’s recap rung.

SCOPE (4), DECIDED HERE AND NOT IN A RED CELL — AND WHY IT IS A SECOND FLAG

The surface table is the one announceOutstandingWork sets out, with the same split: gth ask and gth exec are a person running a verb and reading what comes back, and they set this; gth batch, gth eval and gth workflow drive this runtime as a harness and do not.

It is a separate flag rather than a second meaning for that one, because the two differ in the thing that matters most about a default. The notice is deterministic, free and bounded; a recap is a model call — the user’s tokens, the user’s latency, the user’s money — per cell. Folding them together would mean a harness author who once opted into a free sentence had thereby opted a thousand-cell suite into a thousand extra model calls, with no line in their own code to point at. Two flags make the expensive one its own, visible decision.

Excluded elsewhere by the same structure — a surface that does not ask does not get one:

review / pr end with a full written verdict that already says what was examined and what was found. A recap of a review is the banner problem in its purest form.
ACP and AG-UI are embedders whose client owns the end-of-turn surface. Spending a model call server-side for a paragraph the protocol has no field for, and that the client may already be writing itself, is not ours to decide; [[EXT-158]]’s notice travels there as structured data, which is the right shape for a protocol.

Neither the rung nor this flag changes what a caller parses. The recap is rendered through displayNotice, which writes to stderr, and the answer this function returns is untouched — the property [[EXT-158]] was careful to keep and that gth batch’s cases assert on. The value itself reaches a caller as SingleShotResult.recap.

displayCommand?

optional displayCommand?: string

Defined in: packages/core/src/runtime/singleShot.ts:101

GS2-95 — the name of the command the USER typed, for the run header (eval, batch, workflow, gth-batch). Omit it and the header names command, which is right for every caller whose verb IS its name (ask, exec).

It is deliberately NOT command: that argument selects the agent’s mode prompt, so a caller that renamed itself through it would change which system prompt its runs execute under.

origin?

optional origin?: string

Defined in: packages/core/src/runtime/singleShot.ts:181

GS2-106 — the fan-out surface driving this run (batch, eval, gth-batch, workflow), recorded on the conversation as its origin. A direct ask/exec omits it.

An explicit option rather than something inferred from displayCommand: that one names the header, and a header is free to change its wording, while this decides whether every resume surface refuses the row. The two happen to hold the same words today; nothing should rely on it.

resume?

optional resume?: SingleShotResume

Defined in: packages/core/src/runtime/singleShot.ts:189

GS2-106 — continue a recorded conversation instead of starting one: the conversation the caller’s resume seam already resolved and checked (ask --resume, exec --resume, gth history resume). The run re-enters threadId from its checkpoint and appends content as a fresh user message; the turn is recorded under conversationId.