Fix return-direct terminal tool completion

[roackb2]

Summary

• add the host-authored ToolDefinition returnDirect contract
• finish successful terminal tools without a redundant model request
• keep failed terminal tools recoverable within the same run budget
• preserve complete transcripts plus ordered, awaited terminal event delivery
• document the generic Heddle versus host ownership boundary

Verification

• yarn build
• yarn vitest run src/tests/integration/core/run-agent.test.ts src/tests/integration/core/agent-loop.test.ts src/tests/integration/control-plane/session-runtime.test.ts (96 passed)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-09T10:31:33.828098Z	f9459f4	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f9459f4be2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid persisting an unfulfillable checkpoint reminder

When the normal read-and-record tool profile includes memory_checkpoint, any successful non-memory tool makes AgentMemoryCheckpointTracker.trackCheckpointNeed() require a checkpoint, and pushHostRequirementReminders() appends the “Before your final answer” system message. Finishing here immediately after a successful return-direct tool gives the model no opportunity to satisfy that requirement; conversation runs then persist and replay this stale reminder on the next user turn. Suppress the reminder for terminal completion or explicitly resolve the checkpoint policy before returning.

Useful? React with 👍 / 👎.

[roackb2]

Verification on head c21310d:

• yarn build: passed
• Focused terminal completion tests: 96/96 passed
• yarn lint: passed
• yarn test:unit: 145 files, 957/957 passed on clean rerun
• GitHub PR checks: all six passed (eslint, typecheck, unit, integration, Postgres reference, browser integration)

A local full integration run reported 460/461 because an ambient user-owned skill has a description over the 1024-character validation limit. The same integration suite passes in clean GitHub CI, confirming this is unrelated to the PR.

No merge, release, or publish performed.