* feat(hooks): add respond action for tool execution bypass
Add a new HookActionRespond that allows hooks to return tool results directly, skipping actual tool execution. This enables plugin tool injection, caching, and mocking capabilities.
- Add HookActionRespond constant and support in HookManager
- Extend ToolCallHookRequest with HookResult field
- Implement respond action handling in process hooks and agent loop
- Add comprehensive tests for respond and deny_tool actions
- Update documentation with hook actions table and examples
* docs(hooks): add JSON-RPC protocol and plugin tool injection documentation
Add comprehensive documentation for hook JSON-RPC protocol and plugin tool injection capabilities:
- Add "Hook Actions" section to README.zh.md explaining respond action for tool execution bypass
- Create hook-json-protocol.md/.zh.md detailing JSON-RPC 2.0 protocol for all hook methods
- Create plugin-tool-injection.md/.zh.md with complete examples for external tool implementation
- Document how hooks can inject tool definitions and return results via respond action
- Include Python and Go examples for weather query plugin implementation
* feat(agent): emit tool events and feedback for hook results
Add ToolExecStart event emission and tool feedback for hook results to ensure consistent behavior between normal tool execution and hook bypass scenarios. This maintains parity in event tracking and user feedback when tools are executed via hooks.
* style(agent): format whitespace in hook structs and constants
Remove trailing whitespace and standardize spacing in JSON struct tags, constants, and test data for improved code consistency.
* feat(hooks): add media support for plugin tool injection
Extend the hook respond action to support media file handling:
- Add `media` field for returning images and files from hooks
- Add `response_handled` field to control turn completion behavior
- When response_handled=true, media is automatically delivered to user
- When response_handled=false, media is passed to LLM for vision requests
This enables plugins to directly return generated images, downloaded
files, and other media content either to users or for LLM analysis.
* docs(hooks): document security implications of respond action
Add security boundary documentation explaining that the respond action
bypasses ApproveTool checks, allowing hooks to return results for any
tool without approval. Include recommendations for secure hook
implementation and code comments marking the security considerations.
Changes:
- Add "Security Boundaries" section to plugin-tool-injection docs
- Document bypass of approval checks and associated risks
- Provide security recommendations and example code
- Add inline security comments in hooks.go and loop.go
* refactor(agent): improve completeness of tool result cloning and hook processing
Extend cloneToolResult to properly copy ArtifactTags and Messages fields,
ensuring deep copies of all ToolResult data. Consolidate event emission
and user message handling to match the normal tool execution flow.
* fix(agent): align hook respond path with normal tool execution flow
The hook respond code path was missing several critical behaviors that
existed in normal tool execution:
- Add logging for tool calls with arguments preview
- Add is_tool_call metadata to user-facing messages
- Handle attachment delivery failures by setting error state and
notifying LLM
- Set ResponseHandled=false when using bus for media delivery
- Check for steering messages and graceful interrupts after tool
execution, skipping remaining tools when appropriate
- Poll for SubTurn results that arrived during tool execution
This ensures consistent behavior between hook-responded tool calls and
normally executed tool calls.
* test(agent): add tests for hook respond media error handling
Add comprehensive tests for the hook respond code path when media
delivery fails. Tests cover error media channel scenarios and verify
proper error state handling.
Also document that AfterTool is not called when using respond action,
as it provides the final answer directly (design decision).
Harmoon