feat: add prompt-based hooks for agent lifecycle events by roomote[bot] · Pull Request #11505 · RooCodeInc/Roo-Code

roomote · 2026-02-17T17:34:22Z

Related GitHub Issue

Description

This PR attempts to address Issue #11504 by implementing prompt-based hooks that allow a smaller/different model to step in at specific agent lifecycle events and provide read-only advisory output. Feedback and guidance are welcome.

Key implementation details:

Hook events supported: PreToolUse (before tool execution, with optional tool name regex matcher), PostToolUse (after tool execution), and Stop (when attempt_completion is invoked)
Configuration format: .roo/hooks.json (project-level) and ~/.roo/hooks.json (global user settings), using a Claude Code-compatible JSON format
Global hook model: Uses the active profile API configuration (tied to profile setup as requested)
Read-only hooks: No tool access. Hooks receive conversation context and produce advisory text injected into the conversation via hook_output say messages
File watching: HooksManager watches both project and global hooks.json files for changes and reloads automatically
Hook execution: Uses singleCompletionHandler to send hook prompts to the configured API provider, executing hooks sequentially

Example .roo/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write_to_file|apply_diff",
        "prompt": "Review this code change for security issues"
      }
    ],
    "Stop": [
      {
        "prompt": "Review the final result and suggest improvements"
      }
    ]
  }
}

Test Procedure

33 new tests added (18 for hook config validation, 15 for HookExecutor)
All tests pass: cd src && npx vitest run shared/__tests__/hooks.spec.ts and cd src && npx vitest run services/hooks/__tests__/HookExecutor.spec.ts
Existing tests unaffected: presentAssistantMessage-unknown-tool.spec.ts continues to pass
Full monorepo lint (14 packages) and type-check (14 packages) pass

Pre-Submission Checklist

Issue Linked: This PR is linked to an approved GitHub Issue
Scope: Changes are focused on prompt-based hooks implementation
Self-Review: Code has been self-reviewed
Testing: 33 new tests added covering validation and execution
Documentation Impact: Documentation for .roo/hooks.json format would be beneficial
Contribution Guidelines: Read and agreed

Documentation Updates

Yes, documentation for the .roo/hooks.json configuration format and supported hook events would be helpful for users

Additional Notes

This is an initial implementation covering the core hook infrastructure. Future enhancements could include:

UI-based hook configuration in the Settings panel
Per-hook model selection (currently uses active profile)
Additional hook events (e.g., PreRequest, PostResponse)
Hook output injection directly into conversation context (currently shown as advisory messages)

Start a new Roo Code Cloud session on this branch

Implements prompt-based hooks that allow a smaller/different model to step in at specific agent lifecycle events and provide read-only advisory output. Hook events supported: - PreToolUse: fires before tool execution (with optional tool name matcher) - PostToolUse: fires after tool execution completes - Stop: fires when attempt_completion is invoked Configuration via .roo/hooks.json (project) and ~/.roo/hooks.json (global), using a Claude Code-compatible format. Hooks are read-only (no tool access) and receive conversation context. Uses the active profile API configuration. New files: - src/shared/hooks.ts: types, interfaces, and validation - src/services/hooks/HooksManager.ts: config loading with file watchers - src/services/hooks/HookExecutor.ts: hook prompt building and execution - src/shared/__tests__/hooks.spec.ts: 18 validation tests - src/services/hooks/__tests__/HookExecutor.spec.ts: 15 executor tests Modified files: - packages/types/src/message.ts: added hook_output ClineSay type - src/core/webview/ClineProvider.ts: HooksManager initialization - src/core/assistant-message/presentAssistantMessage.ts: PreToolUse/PostToolUse hooks - src/core/tools/AttemptCompletionTool.ts: Stop hook Addresses #11504

roomote · 2026-02-17T17:34:51Z

Rooviewer See task

Re-reviewed after commit e8dc425. All four previously flagged issues are now resolved. No new issues found.

PostToolUse hook silently drops tool results when ToolResultBlockParam.content is in array format (returns empty string instead of extracting text blocks)
PreToolUse hooks fire before user tool-approval, wasting API calls if the user rejects the tool
PreToolUse hooks now only fire for tools that call askApproval; tools like read_file, ask_followup_question, and read_command_output bypass it and never trigger PreToolUse hooks
"hook" is added to idleAsks but should be in interactiveAsks -- causes TaskIdle to be emitted during hook approval, making external consumers incorrectly see the task as idle mid-execution

Previous reviews

e30746e: Review #1

47ff524: Review #2

055a1df: Review #3

d8b53b8: Review #4

_{Mention @roomote in a comment to request specific changes to this pull request or fix all unresolved issues.}

roomote · 2026-02-17T17:39:21Z

src/core/assistant-message/presentAssistantMessage.ts

+							const lastResult = cline.userMessageContent
+								.filter(
+									(b): b is import("@anthropic-ai/sdk").Anthropic.ToolResultBlockParam =>
+										b.type === "tool_result",
+								)
+								.pop()
+							const resultText = typeof lastResult?.content === "string" ? lastResult.content : ""


ToolResultBlockParam.content in the Anthropic SDK is typed as string | (TextBlockParam | ImageBlockParam)[]. When a tool result uses the array format (e.g., results that include images or structured text blocks), typeof lastResult?.content === "string" is false and resultText falls back to "". The PostToolUse hook then receives an empty string instead of the actual result content. Consider extracting text from array-format content:

Suggested change

const lastResult = cline.userMessageContent

.filter(

(b): b is import("@anthropic-ai/sdk").Anthropic.ToolResultBlockParam =>

b.type === "tool_result",

)

.pop()

const resultText = typeof lastResult?.content === "string" ? lastResult.content : ""

const lastResult = cline.userMessageContent

.filter(

(b): b is import("@anthropic-ai/sdk").Anthropic.ToolResultBlockParam =>

b.type === "tool_result",

)

.pop()

const resultText =

typeof lastResult?.content === "string"

? lastResult.content

: Array.isArray(lastResult?.content)

? lastResult.content

.filter((b): b is import("@anthropic-ai/sdk").Anthropic.TextBlockParam => b.type === "text")

.map((b) => b.text)

.join("\n")

: ""

_{Fix it with Roo Code or mention @roomote and request a fix.}

@roomote fix this

Fixaroo See task

Fixed the PostToolUse hook to extract text from array-format ToolResultBlockParam.content instead of silently returning an empty string. All tests (33/33) and full monorepo lint + type checks pass.

_{View commit | Revert commit}

roomote · 2026-02-17T17:39:38Z

src/core/assistant-message/presentAssistantMessage.ts

+			// === PreToolUse Hook ===
+			if (!block.partial) {
+				try {
+					const hooksManager = cline.providerRef.deref()?.getHooksManager()
+					if (hooksManager?.hasHooksForEvent("PreToolUse")) {
+						const matchingHooks = hooksManager.getMatchingHooks("PreToolUse", block.name)
+						if (matchingHooks.length > 0) {
+							const hookContext: HookContext = {
+								event: "PreToolUse",
+								toolName: block.name,
+								toolInput: block.nativeArgs || block.params,
+							}
+							const hookResults = await executeHooks(matchingHooks, hookContext, cline.apiConfiguration)
+							const hookOutput = formatHookResults(hookResults)
+							if (hookOutput) {
+								await cline.say("hook_output", `PreToolUse hook for ${block.name}:\n${hookOutput}`)
+							}
+						}
+					}
+				} catch (hookError) {
+					console.warn(`[presentAssistantMessage] PreToolUse hook error:`, hookError)
+				}
+			}


PreToolUse hooks fire here, before the tool-approval dialog that happens inside each tool's handler (e.g., askApproval in writeToFileTool.handle). Each hook makes an API call via singleCompletionHandler, so if the user subsequently rejects the tool, those API calls were wasted. For tools that require explicit approval (file writes, command execution, etc.), consider moving the hook invocation to after user approval, or at minimum guarding it with a check for auto-approval settings to avoid unnecessary API spend.

_{Fix it with Roo Code or mention @roomote and request a fix.}

@roomote fix this to avoid unneccessary API spend

Fixaroo See task

Fixed the reported issues. Moved PreToolUse hook execution into the askApproval callback so hooks only fire after user approves the tool (avoiding wasted API calls on rejected tools). Also fixed PostToolUse hook to properly extract text from array-format ToolResultBlockParam.content. All tests and type checks pass.

_{View commit | Revert commit}

…hook

…nt in PostToolUse - Moved PreToolUse hook execution into askApproval callback so hooks only fire after the user approves the tool, avoiding wasted API calls on rejected tools - Fixed PostToolUse hook to extract text from array-format ToolResultBlockParam.content instead of silently returning empty string

roomote · 2026-02-17T17:59:48Z

src/core/assistant-message/presentAssistantMessage.ts

+				// === PreToolUse Hook (fires after user approves to avoid wasting API calls on rejected tools) ===
+				try {
+					const hooksManager = cline.providerRef.deref()?.getHooksManager()
+					if (hooksManager?.hasHooksForEvent("PreToolUse")) {
+						const matchingHooks = hooksManager.getMatchingHooks("PreToolUse", block.name)
+						if (matchingHooks.length > 0) {
+							const hookContext: HookContext = {
+								event: "PreToolUse",
+								toolName: block.name,
+								toolInput: block.nativeArgs || block.params,
+							}
+							const hookResults = await executeHooks(matchingHooks, hookContext, cline.apiConfiguration)
+							const hookOutput = formatHookResults(hookResults)
+							if (hookOutput) {
+								await cline.say("hook_output", `PreToolUse hook for ${block.name}:\n${hookOutput}`)
+							}
+						}
+					}
+				} catch (hookError) {
+					console.warn(`[presentAssistantMessage] PreToolUse hook error:`, hookError)
+				}


Moving the PreToolUse hook into the askApproval callback means it only fires for tools that actually call askApproval. Several tools bypass this callback entirely and call task.ask() directly -- notably ReadFileTool, AskFollowupQuestionTool, and ReadCommandOutputTool. A PreToolUse hook with "matcher": "read_file" (or similar) will silently never execute.

The previous location (before the switch (block.name) statement, inside if (!block.partial)) ran for all tools unconditionally. A possible fix: keep the hook invocation at that original central location but guard it with a check like cline.didRejectTool after askApproval returns, or run it in both places (inside askApproval for approval-gated tools, and at the original location for tools that skip approval).

_{Fix it with Roo Code or mention @roomote and request a fix.}

@roomote should have a ask for hook approval different from askApproval, to differentiate between hook and tool approval. Fix

Fixaroo See task

Separated hook approval from tool approval and moved PreToolUse hooks to the central location so they fire for ALL tools. Added new "hook" ClineAsk type with dedicated askHookApproval function. All tests and checks pass (33 hook tests, full monorepo lint + type-check).

_{View commit | Revert commit}

… central location - Added new "hook" ClineAsk type to differentiate hook approval from tool approval - Moved PreToolUse hooks from inside askApproval callback to central location before switch(block.name), so hooks fire for ALL tools including read_file, ask_followup_question, and read_command_output - Added askHookApproval function using cline.ask("hook", ...) for hook-specific approval - Updated PostToolUse and Stop hooks to also use the new hook approval flow

roomote · 2026-02-17T18:22:01Z

packages/types/src/message.ts

+	"hook",
 ] as const satisfies readonly ClineAsk[]


"hook" is added to idleAsks, but it behaves as an interactive approval prompt (the user approves/denies hook execution so the task can continue). The other idleAsks members (completion_result, api_req_failed, etc.) represent terminal or paused states. Because "hook" is here, Task.ts will emit TaskIdle after 2 seconds of waiting for hook approval, causing external API consumers to incorrectly believe the task is idle mid-execution. This should be in interactiveAsks instead.

Suggested change

"hook",

] as const satisfies readonly ClineAsk[]

"hook",

] as const satisfies readonly ClineAsk[]

_{Fix it with Roo Code or mention @roomote and request a fix.}

@roomote fix

Fixaroo See task

Moved "hook" from idleAsks to interactiveAsks so hook approval no longer triggers false TaskIdle emissions. All tests (33), lint (14 packages), and type-check (14 packages) pass.

_{View commit | Revert commit}

…skIdle emissions

github-project-automation bot added this to Roo Code Roadmap Feb 17, 2026

github-project-automation bot moved this to New in Roo Code Roadmap Feb 17, 2026

roomote bot mentioned this pull request Feb 17, 2026

[ENHANCEMENT] Allow prompt based hook #11504

Open

2 tasks

roomote bot commented Feb 17, 2026

View reviewed changes

roomote added 2 commits February 17, 2026 17:51

fix: handle array-format ToolResultBlockParam.content in PostToolUse …

055a1df

…hook

roomote bot commented Feb 17, 2026

View reviewed changes

fix: move "hook" from idleAsks to interactiveAsks to prevent false Ta…

e8dc425

…skIdle emissions

Conversation

roomote bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related GitHub Issue

Description

Test Procedure

Pre-Submission Checklist

Documentation Updates

Additional Notes

Uh oh!

roomote bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

roomote bot Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

medasmarathon Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

roomote bot Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roomote bot Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

medasmarathon Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

roomote bot Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roomote bot Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

medasmarathon Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

roomote bot Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roomote bot Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

medasmarathon Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

roomote bot Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

roomote bot commented Feb 17, 2026 •

edited

Loading

roomote bot commented Feb 17, 2026 •

edited

Loading

roomote bot Feb 17, 2026 •

edited

Loading

roomote bot Feb 17, 2026 •

edited

Loading

roomote bot Feb 17, 2026 •

edited

Loading

roomote bot Feb 17, 2026 •

edited

Loading