claude-code - 💡(How to fix) Fix [FEATURE] Hookable Workflow lifecycle events (completion) that support additionalContext

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

There is no hook event that lets tooling react to a Workflow finishing.

Workflows (e.g. the built-in /deep-research) run in the background and return their result to the conversation as an injected task-notification — not through any hook. I instrumented a catch-all logger on eight candidate events during a real /deep-research run (CLI 2.1.156) and confirmed the gap:

• PreToolUse / PostToolUse fire for tool_name: "Workflow" only at launch. The tool_response is the launch ack — {"status":"async_launched","taskId":...,"runId":...} — never the finished report. There is no second PostToolUse carrying the result.
• TaskCreated / TaskCompleted never fired (0 occurrences) for the workflow in the CLI, even though TaskCompleted is documented for the Agent SDK (TypeScript-only).
• Stop is turn-scoped (fires when the main agent ends a turn), not workflow-scoped — it can't distinguish "a workflow just completed" from any other turn end.
• SubagentStart / SubagentStop fire per fan-out agent (agent_type: "workflow-subagent") — ~97 subagents in one run — so there's no single completion signal, and the final synthesize agent's stop is indistinguishable from the rest.

Compounding it: even the completion events that do fire (Stop, SubagentStop) only support the top-level decision/reason output and cannot emit hookSpecificOutput.additionalContext. Per the hooks docs, additionalContext is supported only by SessionStart, Setup, UserPromptSubmit, SubagentStart, PreToolUse, and PostToolUse. So there is no event that both (a) fires once when a workflow completes and (b) can inject context back into the conversation.

The net effect: a finished workflow's output cannot be acted on automatically. For /deep-research specifically, a multi-source, fact-checked report is produced and then lost unless the user manually persists it.

Proposed Solution

Add a workflow lifecycle hook event that fires once when a Workflow completes (e.g. WorkflowCompleted, or make the documented TaskCompleted fire for CLI workflow runs), and allow it to emit hookSpecificOutput.additionalContext.

The payload should carry enough to identify and act on the run:

• hook_event_name (e.g. "WorkflowCompleted")
• workflow name and runId (and taskId)
• the workflow's returned result (or a path to it)
• status (completed / failed / cancelled)

With additionalContext support, a hook could then nudge the model — e.g. "a /deep-research report just completed; persist it to docs/research/<slug>.md" — closing the loop without user intervention. A matcher on workflow name (mirroring the tool-name matcher on PreToolUse/PostToolUse) would let hooks target specific workflows.

Alternative Solutions

Workarounds tried, all insufficient:

• PostToolUse on tool_name: "Workflow" — only sees the launch ack, never the result.
• Stop hook — fires on every main-agent turn; can't tell a workflow completion apart from any turn end, and can't inject additionalContext regardless.
• SubagentStop — fires dozens of times per run with no workflow-completion semantics.
• Manual capture — I shipped a small skill that the user invokes after a workflow to persist the in-context report. It works, but it's manual; a completion hook is exactly what would automate it.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

1. I run /deep-research "<question>". The workflow fans out ~97 subagents, verifies claims, and returns a cited report to the conversation.
2. I want that report persisted automatically to docs/research/<slug>.md so future sessions don't re-research it.
3. With a WorkflowCompleted hook that supports additionalContext, a hook matching name: "deep-research" would fire once at completion and inject: "Persist this report to docs/research/<slug>.md."
4. The report is saved without me remembering to do it — the same automation pattern that PostToolUse already enables for ordinary tools.

Additional Context

• Observed on Claude Code CLI 2.1.156 (macOS).
• Method: a catch-all command hook wired to PreToolUse, PostToolUse, PostToolBatch, Stop, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, logging each event name + stdin payload during one /deep-research run.
• The additionalContext support matrix referenced above is from the official hooks documentation (code.claude.com/docs/en/hooks and the Agent SDK hooks page).
• Related nuance: additionalContext injection is reported to be unreliable for some events/matchers in recent versions (open issues exist), so a new event should be specified to deliver additionalContext reliably.