Skip to content

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:

typescript
// 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:

typescript
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:

typescript
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:

BeforeAfter
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? }
maxContinuesmaxRevisions (shared with onOutput)
onError: 'stop'onError: 'accept' (still the default for onReply)
ctx.continuesUsed / ctx.continuesLeftctx.revisionsUsed / ctx.revisionsLeft
AgentResult.stopGuard, RunMetadata.stopGuardAgentResult.completionGuard, RunMetadata.completionGuard
report { continuesUsed, exhausted?, error? }{ revisionsUsed, exhausted?, error?, outputAdjusted? }
framework_stop_guard_rejectedframework_completion_guard_rejected (or the verdict's own code)
framework_stop_guard_failedframework_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 stopGuardcompletionGuard

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:

typescript
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':

typescript
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 ​

RemovedUse
StopGuardConfig, StopGuardContext, StopGuardVerdict, StopGuardReport, StopGuardEventCompletionGuardConfig, ReplyGuardContext / OutputGuardContext, ReplyVerdict / OutputVerdict, CompletionGuardReport, CompletionGuardEvent
isStopGuardOffered, runStopGuard, countStopGuardContinues, stopGuardVerdictSchemaisReplyGuardOffered, runReplyGuard / runOutputGuard, countCompletionGuardRevisions, replyVerdictSchema / outputVerdictSchema
stopGuardReportSchemacompletionGuardReportSchema
ToolConfig.finishWithTransform, Tool._finishWithTransformthe paths above
checkFinishWithOutput, finishWithOutputOf, finishWithOutputMarkerSchema, finishWithOutputRejectedTextparseOutputCandidate, acceptedOutputOf, acceptedOutputMarkerSchema
COMMON_METADATA_KEYS.FINISH_WITH_OUTPUTCOMMON_METADATA_KEYS.ACCEPTED_OUTPUT (on every accepted call's row, __finish__ too)
findCommittedFinishfindCommittedTerminal (completes only from the accepted-output marker)
withoutUnknownCodenothing: 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.

StoreMigration
PostgresV35: renames runs.stop_guard to completion_guard; replaces the reason CHECK with the new reasons
D1V37: the same rename
DO-SQLite33: renames runs.stop_guard to completion_guard (on a new Durable Object, whose table already has completion_guard, it drops the empty stop_guard)
Redisthe run hash field is completionGuard (a run recorded before the upgrade reads no report)
Memorynothing to migrate

Deploy the new release to everything that reads or writes a store at the same time.

New ​

  • onOutput judges every structured output, on an ordinary step, in forced completion, in Final Step and on a deferred finishWith call: accept, accept_with, revise or fail. In forced completion a revise is a miss under maxCompletionRetries.
  • One exhaustion rule. When maxRevisions runs 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 trigger completion_guard).
  • Recovery never re-runs the guard. The accepted output is recorded on the accepted call's row in the step commit.

Released under the MIT License.