Upgrading: the completion guard
One completionGuard replaces the stop guard (stopGuard) and finishWithTransform. It judges what would end a run before the run commits it: onOutput a structured output (a __finish__ submission or a finishWith tool's result), onReply a natural text reply. Guide: Completion Guard.
The guard runs on runtime-js and the Cloudflare Durable Object. CF Workflows, Temporal and DBOS refuse an agent that declares it, typed (framework_not_supported), as they refused stopGuard.
What breaks
finishWithTransform is gone
Pick the path that matches what your transform did.
1. It mapped the tool's result to the agent's output. Return the agent's output from execute. This is the main path:
// Before
defineTool({
finishWith: true,
outputSchema: z.object({ data: z.string() }),
finishWithTransform: (out) => ({ result: out.data.toUpperCase() }),
execute: async (input) => ({ data: input.data }),
});
// After
defineTool({
finishWith: true,
outputSchema: z.object({ result: z.string() }), // the agent's output shape
execute: async (input) => ({ result: input.data.toUpperCase() }),
});2. It gated the output (it threw, or returned undefined, to keep the run going). Return revise from onOutput:
completionGuard: {
onOutput: async (ctx) =>
ctx.candidate.valid && ctx.candidate.output.items.length > 0
? { action: 'accept' }
: { action: 'revise', feedback: 'Submit at least one item.' },
},3. It adjusted or enriched the output. Return accept_with from onOutput. Your output is parsed against the agent's outputSchema:
completionGuard: {
onOutput: async (ctx) => {
if (!ctx.candidate.valid) return { action: 'revise', feedback: ctx.candidate.issues.join('; ') };
return { action: 'accept_with', output: { ...ctx.candidate.output, reviewedBy: await currentReviewer() } };
},
},stopGuard becomes completionGuard.onReply
4. Move the function to onReply and rename its verdicts and options:
| Before | After |
|---|---|
stopGuard: { run } | completionGuard: { onReply } |
{ action: 'stop' } | { action: 'accept' } (returning nothing still accepts) |
{ action: 'continue', feedback } | { action: 'revise', feedback } |
{ action: 'fail', message } | { action: 'fail', message, code?, details? } |
maxContinues | maxRevisions (shared with onOutput) |
onError: 'stop' | onError: 'accept' (still the default for onReply) |
ctx.continuesUsed / ctx.continuesLeft | ctx.revisionsUsed / ctx.revisionsLeft |
AgentResult.stopGuard, RunMetadata.stopGuard | AgentResult.completionGuard, RunMetadata.completionGuard |
report { continuesUsed, exhausted?, error? } | { revisionsUsed, exhausted?, error?, outputAdjusted? } |
framework_stop_guard_rejected | framework_completion_guard_rejected (or the verdict's own code) |
framework_stop_guard_failed | framework_completion_guard_failed (retryable when the thrown error is) |
completionReason: 'stop_guard_exhausted' | 'completion_guard_exhausted' |
completionReason: 'stop_guard_error' | 'completion_guard_error' |
log events core.stop_guard.* | core.completion_guard.{accepted, accepted_with, revised, exhausted, errored, failed} |
the DO's /status field stopGuard | completionGuard |
An invalid finishWith result fails the run
Before, a finishWith result that failed the agent's outputSchema went back to the model as a failed call on runtime-js and the Cloudflare Durable Object, and completed the run as is on CF Workflows, Temporal and DBOS. Now, on every runtime, it is treated as a bug in your app: the run fails with framework_completion_output_contract_violation (non-retryable), naming the schema issues. A __finish__ submission that fails the schema still goes back to the model.
5. To keep the old behaviour, add one line:
completionGuard: {
onOutput: async (ctx) =>
ctx.candidate.valid ? { action: 'accept' } : { action: 'revise', feedback: ctx.candidate.issues.join('; ') },
},DBOS: runs in flight across the deploy
A DBOS workflow that is in flight across the deploy and recovers past a finishWith step applies the new check on replay: a run that would have completed with a result that fails the outputSchema now fails with framework_completion_output_contract_violation. Drain in-flight and persistent-mode runs before deploying, or accept that such a run may fail this way.
onAgentComplete carries a completionKey
AgentCompletePayload.completionKey is required. Code that builds the hook's argument itself (a custom loop, a test) passes one. Use it to make an effect run once: onAgentComplete runs before the run's terminal commit and is at-least-once (recipe).
The context format's kind
The context-format kind stop_guard is now completion_guard, with on: 'reply' | 'output'. A custom contextFormat.render that matched 'stop_guard' matches 'completion_guard':
case 'completion_guard':
return `Reviewer feedback on your ${row.on}: ${row.feedback}`;The context source of a guard's rows is 'completion_guard', and their stamp metadata.helixCompletionGuard.
Core exports
| Removed | Use |
|---|---|
StopGuardConfig, StopGuardContext, StopGuardVerdict, StopGuardReport, StopGuardEvent | CompletionGuardConfig, ReplyGuardContext / OutputGuardContext, ReplyVerdict / OutputVerdict, CompletionGuardReport, CompletionGuardEvent |
isStopGuardOffered, runStopGuard, countStopGuardContinues, stopGuardVerdictSchema | isReplyGuardOffered, runReplyGuard / runOutputGuard, countCompletionGuardRevisions, replyVerdictSchema / outputVerdictSchema |
stopGuardReportSchema | completionGuardReportSchema |
ToolConfig.finishWithTransform, Tool._finishWithTransform | the paths above |
checkFinishWithOutput, finishWithOutputOf, finishWithOutputMarkerSchema, finishWithOutputRejectedText | parseOutputCandidate, acceptedOutputOf, acceptedOutputMarkerSchema |
COMMON_METADATA_KEYS.FINISH_WITH_OUTPUT | COMMON_METADATA_KEYS.ACCEPTED_OUTPUT (on every accepted call's row, __finish__ too) |
findCommittedFinish | findCommittedTerminal (completes only from the accepted-output marker) |
withoutUnknownCode | nothing: a provider error keeps its own code |
Log events core.finish_with.output_rejected and core.finish_with.output_marker_dropped are now core.completion.output_contract_violation and core.completion.accepted_output_marker_dropped.
Stored data
Stored run records from before this release are not migrated (user ruling 2026-11-15: no backwards compatibility): start with fresh stores. The migrations rename the report's column only: a run recorded with stop_guard_exhausted or stop_guard_error keeps that reason, so Postgres V35 fails on a database that still holds one, and on D1 and DO-SQLite that run record no longer reads. These migrations are roll-forward only: an older release cannot read a run record written after them.
| Store | Migration |
|---|---|
| Postgres | V35: renames runs.stop_guard to completion_guard; replaces the reason CHECK with the new reasons |
| D1 | V37: the same rename |
| DO-SQLite | 33: renames runs.stop_guard to completion_guard (on a new Durable Object, whose table already has completion_guard, it drops the empty stop_guard) |
| Redis | the run hash field is completionGuard (a run recorded before the upgrade reads no report) |
| Memory | nothing to migrate |
Deploy the new release to everything that reads or writes a store at the same time.
New
onOutputjudges every structured output, on an ordinary step, in forced completion, in Final Step and on a deferredfinishWithcall:accept,accept_with,reviseorfail. In forced completion areviseis a miss undermaxCompletionRetries.- One exhaustion rule. When
maxRevisionsruns out, the run does what it would have done without the objection: a reply stands; an output enters forced completion carrying your last feedback (forced triggercompletion_guard). - Recovery never re-runs the guard. The accepted output is recorded on the accepted call's row in the step commit.