feat(hooks): add agent_name field to BeforeAgent/AfterAgent hook inputs

[Weaxs]

Summary

Add an optional agent_name field to BeforeAgent and AfterAgent hook inputs, allowing hook scripts to distinguish between the main agent and subagents (e.g. browser_agent, codebase_investigator).

Currently, BeforeAgent/AfterAgent hooks fire for both the main agent and subagents with no way to tell them apart. This causes hooks intended only for the main agent (e.g. auto-commit, post-task notifications) to also fire during subagent execution.

Details

• Added optional agentName field to AgentLoopContext interface
• Set agentName = definition.name when creating subagent execution context in LocalAgentExecutor
• Added optional agent_name field to BeforeAgentInput and AfterAgentInput interfaces
• Populated agent_name from context.agentName in HookEventHandler.fireBeforeAgentEvent() and fireAfterAgentEvent()
• agent_name is undefined for the main agent, and set to the subagent name (e.g. "browser_agent") for subagents

Hook scripts can use this to skip subagent execution:

agent_name=$(echo "$input" | jq -r '.agent_name // empty')
if [ -n "$agent_name" ]; then
  echo '{"continue": true}'
  exit 0
fi

Related Issues

Fixes #15269

How to Validate

1. Run unit tests:

   npx vitest run packages/core/src/hooks/hookEventHandler.test.ts

2. Verify that the new tests pass:
   • fireBeforeAgentEvent → agent_name is undefined for main agent context
   • fireBeforeAgentEvent → agent_name is "browser_agent" for subagent context
   • fireAfterAgentEvent → same assertions for both main and subagent
3. Create a test hook script that logs the agent_name field and verify:
   • Main agent turn → agent_name is absent/null
   • Delegating to a subagent (e.g. codebase_investigator) → agent_name is "codebase_investigator"

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the agent hook system by introducing an "agent_name" field to "BeforeAgent" and "AfterAgent" hook inputs. This addition provides crucial context to hook scripts, allowing them to determine if they are being executed by the main agent or a subagent. This enables developers to write more precise and targeted hook logic, preventing hooks intended for the main agent from running unnecessarily during subagent operations and improving overall system control and flexibility.

Highlights

• Hook Context Enhancement: Introduced an optional "agent_name" field to "BeforeAgent" and "AfterAgent" hook inputs, allowing hook scripts to differentiate between the main agent and subagents (e.g., "browser_agent", "codebase_investigator").
• Subagent Identification: The "agent_name" field is populated with the subagent's name when a subagent context is created, and remains "undefined" for the main agent, providing clear distinction.
• Improved Hook Control: Enabled hook scripts to conditionally execute logic based on whether the hook is triggered by the main agent or a specific subagent, preventing unintended actions during subagent operations.
• Documentation and Testing: Updated the hooks reference documentation to reflect the new "agent_name" field and added comprehensive unit tests to verify its correct population for both main and subagent contexts.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces an agentName property to the AgentLoopContext and hook event inputs (BeforeAgentInput, AfterAgentInput). This enhancement allows hooks to distinguish between events originating from the main agent and those from subagents, providing more precise control over hook execution. The LocalAgentExecutor is updated to correctly propagate the subagent's name to its context. Corresponding documentation in docs/hooks/reference.md has been updated, and new unit tests in hookEventHandler.test.ts confirm that the agent_name is accurately included (or undefined for the main agent) in both BeforeAgent and AfterAgent events. I have no feedback to provide.