Feature: structured completion signals for headless/automated sessions

Problem

When running Claude Code in headless mode (claude -p "prompt" --output-format json), there's no reliable way to determine if the agent actually completed the task vs. hit the turn limit vs. got stuck.

The current approach is to ask Claude to output a magic string (TASK_COMPLETE or TASK_BLOCKED) and grep for it in the output:

if echo "$result_text" | grep -qF "TASK_COMPLETE"; then
  echo "done"
elif echo "$result_text" | grep -qF "TASK_BLOCKED"; then
  echo "blocked"
else
  echo "unknown — maybe hit turn limit?"
fi

This is fragile: the signal can appear in code blocks, partial output, or not at all.

Proposal

Add structured completion metadata to the JSON output:

{
  "result": "...",
  "completion_reason": "natural" | "max_turns" | "error" | "user_signal",
  "turns_used": 18,
  "turns_max": 25
}

Alternatively, support a --completion-signal flag that Claude Code itself validates:

claude -p "prompt" --output-format json --completion-signal "TASK_COMPLETE"

The CLI would then set a top-level "completed": true/false in the JSON based on whether the signal appeared in Claude's final response (not in code blocks or intermediate output).

Context

I run 50+ autonomous tasks per week via headless Claude Code. Reliable completion detection is essential for task queue management — knowing whether to mark a task as completed, failed, or needs-retry.