empty-payload-sentinel-guard

name	empty-payload-sentinel-guard
description	Guard requests from closing instantly when a tool returns nothing by injecting the sentinel message and logging the event.
metadata	{"author":"ychampion"}

SKILL: Empty Payload Sentinel Guard

Domain: tool-orchestration
Trigger: Apply this when a tool_result block might legitimately be empty (shell commands with no stdout, MCP commands returning content: [], statements that finish silently) so the assistant still sees something to react to. Source Pattern: Distilled from reviewed tool-loop and result-shaping patterns.

Core Method

Run the same emptiness check used inside isToolResultContentEmpty: undefined/null, whitespace strings, empty arrays, or arrays whose text blocks are themselves empty count as empty. When the check fires, log tengu_tool_empty_result with the sanitized tool name and short-circuit the persistence path by returning the original block with content: "({toolName} completed with no output)", guaranteeing the model always sees at least one token even when the tool produced nothing.

Key Rules

• Copy the normalized emptiness logic from isToolResultContentEmpty so structured arrays and whitespace-only strings are treated identically.
• Call sanitizeToolNameForAnalytics before logging so GrowthBook metrics stay consistent.
• Only swap the content; leave tool_use_id, tool_version, and other metadata untouched.
• Keep the sentinel text stable—downstream budgeting, logging, and tests rely on the literal ({toolName} completed with no output) message.

Example Application

Invoke this guard inside maybePersistLargeToolResult before any size checks; if the guard fires, it returns the sentinel immediately and prevents the empty </function_results> tail from tricking Claude into ending the turn.

Anti-Patterns (What NOT to do)

• Don’t reinject a sentinel into non-empty results or structured content; the guard is exclusively for truly empty outputs.
• Don’t skip the analytics event—without it you lose signals that a tool ran but returned nothing.
• Don’t persist an empty file just to explain emptiness; the guard rewrites the content in memory without writing disk files.