[FEATURE] PostTask hook — fire when background agent completes

[mlops-kelvin]

Problem Statement

When orchestrating multiple background agents via the Task tool with run_in_background: true, there is no way to be notified when an agent completes. The orchestrator must manually poll TaskOutput to check status. This makes reactive orchestration impossible — the orchestrator is always polling, never responding.

In our multi-agent system (3 persistent agents coordinating via subagents), we run 3-5 background agents in parallel regularly. The orchestrator currently has no choice but to either:

1. Block on each agent sequentially (defeats the purpose of parallelism)
2. Poll TaskOutput repeatedly (wastes context window on polling calls)
3. Wait for the system-reminder notification (unreliable timing, no hook integration)

We built an entire cron + wake + messaging infrastructure to handle event-driven coordination BETWEEN sessions. But WITHIN a session, we have no event-driven primitive for "agent finished, here's the result, act on it."

Proposed Solution

A PostTask hook (or SubagentStop enhancement) that fires when a background agent completes, with access to:

• task_id — which agent finished
• agent_type / subagent_type — what kind of agent it was
• status — success/failure/timeout
• result_summary — the agent's final output (or first N characters)

This would enable:

• Reactive orchestration: launch dependent tasks immediately when blockers complete
• External notification: pipe completions to logging, monitoring, or messaging systems
• Workflow automation: trigger next steps without human/orchestrator polling

Priority

High — this is the missing primitive for anyone building multi-agent orchestration on Claude Code.

Category

Core / Tools

Alternatives Considered

• The current system-reminder notifications for agent progress are helpful but not hookable — they appear in the conversation but don't trigger any external action.
• Polling TaskOutput works but consumes context window budget on status checks rather than productive work.
• We considered writing agent results to files and using file-watching, but this adds another infrastructure layer for what should be a native primitive.

[michaelsheka]

I wrote an partly duplicate issue with a suggestion how to solve it

[yurukusa]

A workaround using Stop hook + file-based signaling:

SIGNAL_DIR="/tmp/cc-task-signals"
mkdir -p "$SIGNAL_DIR"
SIGNAL="$SIGNAL_DIR/task-$(date +%s).done"
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) Agent completed in $PWD" > "$SIGNAL"
notify-send "Claude Code" "Background agent completed" 2>/dev/null
osascript -e 'display notification "Background agent completed" with title "Claude Code"' 2>/dev/null
printf '\a' >&2
exit 0

The main agent can poll for completion:

SIGNAL_DIR="/tmp/cc-task-signals"
[ -d "$SIGNAL_DIR" ] || exit 0
COMPLETED=$(ls "$SIGNAL_DIR"/*.done 2>/dev/null | wc -l)
if [ "$COMPLETED" -gt 0 ]; then
    CONTEXT="$COMPLETED background task(s) completed:
$(cat "$SIGNAL_DIR"/*.done)"
    rm -f "$SIGNAL_DIR"/*.done
    jq -n --arg ctx "$CONTEXT" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":$ctx}}'
fi
exit 0

This creates a simple inter-agent notification system: background agents write .done files when they finish, and the main agent picks them up on the next user prompt.