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 Overview

Greptile Summary

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.

Confidence Score: 3/5

• 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

_{(4/5) You can add custom instructions or style guidelines for the agent here!}