SubagentStop hook systemMessage not displayed in UI

Resolved 💬 3 comments Opened Jan 4, 2026 by ImproperSubset Closed Feb 19, 2026

Description

When a SubagentStop hook returns JSON with a systemMessage field, the message is not displayed in the Claude Code UI, despite documentation suggesting it should be shown to the user.

Steps to Reproduce

  1. Add a SubagentStop hook to ~/.claude/settings.json:
{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"systemMessage\": \"Subagent completed: '$CLAUDE_SUBAGENT_TYPE'\"}'"
          }
        ]
      }
    ]
  }
}
  1. Restart Claude Code
  2. Trigger a subagent using the Task tool
  3. Observe the UI

Expected Behavior

The message "Subagent completed: [type]" should be displayed to the user in the chat UI, as the documentation states:

systemMessage - Optional warning message shown to the user

Actual Behavior

No message is displayed. The hook fires (confirmed by testing with file logging), but the systemMessage is not surfaced to the user.

Use Case

This feature would be valuable for providing visibility into agent delegation - letting users see when subagents complete and what type/model was used, improving trust and transparency in the agentic workflow.

Environment

  • Claude Code version: Latest
  • OS: Linux (WSL2)

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗