#14873: [Feature]: Extend before_agent_start hook context with Model, Tools, and Identity fields
agents
size: S
Cluster:
Plugin and Hook Enhancements
## Summary
The current before_agent_start plugin hook provides a sanitized context (prompt, messages), which is insufficient for plugins that require "Agentic" capabilities. Specifically, external plugins cannot access the LLM instance to perform intent planning, nor can they see the tools available to the agent, or robustly identify the user (missing senderId, senderE164). This prevents the creation of advanced security and governance plugins that need to verify intent before execution.
## Proposed solution
Extend PluginHookAgentContext and PluginHookBeforeAgentStartEvent to expose the following fields, which are already available in attempt.ts:
In ctx (PluginHookAgentContext):
Model: The Model instance (enables the plugin to call the LLM for planning/verification).
modelRegistry: For model configuration access.
runId: To correlate the start event with subsequent tool calls (for caching plans).
senderId, senderE164, senderUsername: For identity verification and audit logging.
messageChannel
accountId: For full context awareness.
In event (PluginHookBeforeAgentStartEvent):
Tools: The list of tools available for this run (crucial for verifying if a user's intent matches allowed tools).
## Alternatives considered
Building a custom agent: This bypasses the plugin system entirely and fragments the ecosystem.
Using before_tool_call only: This is too late for "Intent Planning". By the time a tool is called, the "plan" has already been decided by the LLM. Security plugins need to verify the plan against policy before any tool is even attempted.
## Additional context
I have a working implementation in a fork that successfully powers an "ArmorIQ" security plugin. This plugin uses the exposed ctx.model to generate a secure execution plan and event.tools to validate it, preventing prompt injection and unauthorized actions.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR extends the `before_agent_start` plugin hook payload so plugins can do richer pre-run governance/intent checks. Specifically:
- `src/agents/pi-embedded-runner/run/attempt.ts` now passes a `tools` summary on the event and adds additional fields (run/account/sender identity, channel, model, modelRegistry) on the hook context when running `runBeforeAgentStart`.
- `src/plugins/types.ts` updates the public hook type definitions to include these new fields.
These changes integrate with the existing hook runner in `src/plugins/hooks.ts` (sequential modifying hook for `before_agent_start`) and are surfaced to external plugins via the re-export in `src/plugin-sdk/index.ts`.
<h3>Confidence Score: 3/5</h3>
- This PR is likely safe to merge after addressing the plugin-SDK type dependency and tool naming ambiguity.
- Core runtime behavior changes are limited to passing additional context into an existing hook call, but the hook type exports are part of the public plugin SDK and may break external plugin builds if the new pi-* types aren’t resolvable. Additionally, the emitted tool list may be unreliable due to duplicate fallback names.
- src/plugins/types.ts, src/agents/pi-embedded-runner/run/attempt.ts
<!-- greptile_other_comments_section -->
<sub>(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#14647: feat(plugins): allow before_agent_start hook to override model (#14...
by lailoo · 2026-02-12
84.6%
#22624: feat(plugins): add before_context_send hook and model routing via b...
by davidrudduck · 2026-02-21
84.6%
#17614: feat: allow before_agent_start hook to override model selection
by plc · 2026-02-16
83.7%
#8022: feat: implement before_model_select plugin hook
by dead-pool-aka-wilson · 2026-02-03
82.4%
#11155: feat(hooks): before_agent_start model/provider override (run-scoped...
by alanranger · 2026-02-07
82.2%
#6017: feat(hooks): add systemPrompt and tools to before_agent_start event
by yajatns · 2026-02-01
82.0%
#23559: feat(plugins): add before_context_send hook and model routing via b...
by davidrudduck · 2026-02-22
81.6%
#14544: feat: add before_context_send plugin hook
by Windelly · 2026-02-12
81.5%
#11124: feat(plugins): add before_llm_request hook for custom LLM headers
by johnlanni · 2026-02-07
81.3%
#11732: feat(plugins): add injectMessages to before_agent_start hook
by antra-tess · 2026-02-08
80.4%