[Feature]: Agent-based hook evaluation (HookType.AGENT)

[burakkeless]

Is there an existing feature request for this?

• I have searched existing issues and feature requests, and this is not a duplicate.

Problem or Use Case

Some hook decisions can't be made from the event payload alone — they require the evaluator to go look at something first. Prompt-based hooks are limited to what's in the payload; agent-based hooks let the evaluator actively investigate before deciding.

Issue #2755 identifies that HookType.PROMPT is declared in openhands-sdk/openhands/sdk/hooks/config.py but unimplemented, and proposes filling that gap. A complementary gap exists but hasn't been flagged yet: there is no agent-based hook type at all — not even a stub in the enum. The current HookType only contains COMMAND and PROMPT.

Use cases:

• Stop hooks — "Did the agent actually complete everything in TASKS.json?" → subagent reads the file, compares it against session activity, then decides.
• Pre-tool-use hooks — "Does this rm -rf target have uncommitted changes?" → subagent checks git state before allowing the command.
• Post-tool-use hooks — "Do tests still pass after this file edit?" → subagent runs the relevant test suite and blocks continuation on failure.

Proposed Solution

Enum change

HookType in openhands-sdk/openhands/sdk/hooks/config.py currently has only COMMAND and PROMPT. This proposal adds a third value:

class HookType(str, Enum):
    """Types of hooks that can be executed."""
    COMMAND = "command"  # Shell command executed via subprocess
    PROMPT = "prompt"    # LLM-based evaluation (implemented in #2755)
    AGENT = "agent"      # Agent-based evaluation with tool access

Add a new hook flavor, configured like prompt hooks but with tool access via a short-lived Conversation.

Config shape

{
  "stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "agent",
          "prompt": "Read TASKS.json and verify every pending item has been addressed. Respond with ALLOW or DENY plus any remaining items.",
          "model": "claude-sonnet-4-6",
          "tools": ["file_editor", "terminal"],
          "timeout": 60
        }
      ]
    }
  ]
}

Execution flow

1. Executor instantiates a short-lived Conversation with the configured LLM and restricted toolset (tools allowlist)
2. Hook event payload passed as JSON context; user's prompt becomes the task
3. Subagent runs until it emits a structured decision or hits timeout
4. Response parsed as {"decision": "allow" | "deny", "reason": "..."} and returned as a HookResult

Changes required (on top of prompt-hooks foundation from #2755)

• New HookType.AGENT enum value in openhands-sdk/openhands/sdk/hooks/config.py
• tools field on HookDefinition (allowlist, not denylist)
• New branch in HookExecutor.execute() that spawns a Conversation instead of a single LLM call
• Higher default timeout than prompt hooks (60s vs 30s) to reflect multi-turn evaluation

Design defaults

Concern	Default
Tool scoping	Read-only by default; write access requires explicit opt-in
Context passing	HookEvent payload always included; additional context (TASKS.json, history) opt-in via a context field
Recursion guard	Hooks do not fire inside hook-spawned subagents — prevents infinite loops when the evaluator itself has hooks configured
Response format	Same structured JSON as prompt hooks — both flavors produce identical HookResult downstream
Cost controls	Log token usage per invocation; default to a fast/cheap model; gate PreToolUse agent hooks behind explicit opt-in to avoid runaway costs on tool-heavy sessions
Cancellation	Subagent Conversation must be cancellable from the executor so parent-conversation interrupts terminate in-flight hooks cleanly

Mirrors Claude Code's agent-based hooks design, adapted to OpenHands' existing Conversation and HookExecutor infrastructure.

Alternatives Considered

No response

Priority / Severity

Medium - Would improve experience

Estimated Scope

Unknown - Not sure about the technical complexity

Feature Area

• Agent API / Core functionality
• Tools / Tool system
• Skills / Plugins
• Agent Server
• Workspace management
• Configuration / Settings
• Examples / Templates
• Documentation
• Testing / Development tools
• Performance / Optimization
• Integrations (GitHub, APIs, etc.)
• Other

Technical Implementation Ideas (Optional)

No response

Additional Context

No response

[jpelletier1]

Hi @VascoSch92, this came in from the open source community - FYI

[VascoSch92]

It seems that this issue overlaps with #2755 but they are not equivalent. Although this feature is more powerful than the other, it is a question of power/cost trade-off. I don't know if we should just implement this one and discard #2755. I'm curious about what other people think about that.

Moreover, I believe this new feature (presented in issue #2840) could play a role.

[burakkeless]

In my opinion, prompt hooks aren't just a weaker version of hooks .They occupy a distinct point on the power/cost curve between command and agent hooks. Their whole premise is single-shot evaluation: one LLM call, one decision.
For use cases where that's enough, the single-output model actually behaves more deterministically than an agent hook with no tools. Even with an empty tool list, an agent hook still spins up a Conversation, which adds overhead and non-determinism you don't need when the decision is purely a judgment call on the payload. @VascoSch92

[VascoSch92]

@burakkeless

You're right.

My point was that agent hooks are more powerful because they cover the prompt hook as a special case — you just don't give it any tools.

I'm trying to figure out whether there's a real use case and enough demand from the community to have both features, or whether this one will do the job. Two hook types means two code paths to keep in sync, they'd at least need to share a HookResult contract so consumers don't care which flavor produced it.

Curious about that:

the single-output model actually behaves more deterministically than an agent hook with no tools.

Why? A conversation is just putting framework around a prompt but you have totally control on what the LLM see.
To make an Agent Hook behave like a Prompt Hook you should "just" pass:

• system_prompt="..." (override the ~200-line default)
• include_default_tools=[]
• tools=[]
• agent_context=None
• max_iteration_per_run=1
• security_policy_filename=""

Any default left in place (condenser, stuck detector, agent loop) could move the behavior away from a single LLM call

That said, this suggests the prompt hook could be implemented as a thin wrapper that constructs an agent hook with this stripped-down config. Users get the simpler API; maintainers get one execution path.

The resoueces overhead has to be computed thought :-)

[burakkeless]

@VascoSch92

Fully agree with the approach you laid out. My earlier response was coming from the angle of "we probably don't need prompt hooks at all" but output-wise there's no technical difference between the two, so the thin-wrapper path is a really nice ergonomic compromise.

One concern I'd flag, though I don't have enough visibility into the codebase to know if it's real or not: if anything inside the session layer (event log, usage tracking, tracing, metrics , etc.) records hook execution based on how it was produced rather than what kind of hook it was declared as, the thin-wrapper approach could create a subtle inconsistency. A user configures a prompt hook, expects prompt-hook-shaped telemetry, but internally it runs through a Conversation and gets logged as a subagent execution. That kind of leaky abstraction could create tech debt on the maintainer side.

Given that agent hooks would spin up a Conversation, worth checking how event/usage/tracing pipelines handle that before committing to the wrapper approach. I don't have enough insight into those parts of the project to judge the impact, but wanted to flag it just in case.

[VascoSch92]

@burakkeless

One concern I'd flag, though I don't have enough visibility into the codebase to know if it's real or not: if anything inside the session layer (event log, usage tracking, tracing, metrics , etc.) records hook execution based on how it was produced rather than what kind of hook it was declared as, the thin-wrapper approach could create a subtle inconsistency. A user configures a prompt hook, expects prompt-hook-shaped telemetry, but internally it runs through a Conversation and gets logged as a subagent execution. That kind of leaky abstraction could create tech debt on the maintainer side.

That’s a good point, and it’s something we constantly deal with bugs on. While we have the power to control everything, it's very easy to overlook all the variables at play. Sometimes, we genuinely forget to reset the metrics or save the conversation in the correct folder with the right name.

Fully agree with the approach you laid out. My earlier response was coming from the angle of "we probably don't need prompt hooks at all" but output-wise there's no technical difference between the two, so the thin-wrapper path is a really nice ergonomic compromise.

Do you want to give it a shot? I’d be happy to review the PR once it's ready.

[burakkeless]

Hey @VascoSch92, the PR is ready for review: #3052.