Skip to content

docs: subagent_ended hook fields (incl. targetSessionKey identity) aren't documented #95186

Description

@ken-jo

The plugin-hooks doc (docs/plugins/hooks.md) lists subagent_ended but doesn't say what fields the event carries, and that tripped me up.

I ran into this while building agent-connector — a small SDK that deploys one MCP server + lifecycle hooks across many agent CLIs and normalizes their hook events — so I was comparing each CLI's actual hook payload against its documentation. For subagent_spawned the doc even calls out the extra fields (resolvedModel/resolvedProvider), and that event's type extends a base with a field named agentId. So I assumed subagent_ended had an agentId too — but it doesn't.

Looking at the source, PluginHookSubagentEndedEvent (src/plugins/hook-types.ts) is its own type whose only identity field is targetSessionKey (no agentId/subagentId), plus outcome, reason, error?, runId?. A plugin author reaching for event.agentId in a subagent_ended handler just silently gets undefined.

Could the Subagents section get one line for subagent_ended, the way subagent_spawned already has — naming targetSessionKey as the identity field and noting there's no agentId on this event? Happy to send the doc PR if that's welcome (I'd sign off the commit and mark it AI-assisted per CONTRIBUTING).

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low-priority cleanup, docs, polish, ergonomics, or speculative work.clawsweeper:linked-pr-openClawSweeper found an open linked pull request for this issue.clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions