fix: send hook_config to server in RemoteConversation by xingyaoww · Pull Request #2115 · OpenHands/software-agent-sdk

xingyaoww · 2026-02-18T10:04:16Z

Summary

Fixed a bug where hook_config was being accepted by RemoteConversation but never sent to the server when creating a conversation.

Problem

When using RemoteConversation with hook_config, hooks for PreToolUse, PostToolUse, UserPromptSubmit, and Stop were never executed server-side because the hook_config wasn't included in the conversation creation payload.

The client was showing a misleading warning "RemoteConversation only supports SessionStart/SessionEnd hooks" when it should have been sending the hook configuration to the server where these hooks would be executed.

Changes

Fix the bug: Add hook_config to the payload when creating conversations via the REST API
Update example: Modified 02_remote_agent_server/01_convo_with_local_agent_server.py to demonstrate hook configuration with RemoteConversation
Remove outdated warning: Since hooks are now properly sent to the server, removed the misleading warning about unsupported hook types

Testing

Ran the modified example to verify:

No more warning about unsupported hooks
Conversation is created successfully with hook configuration
Server-side hooks are now received in the payload

Related Documentation

Hooks Guide

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	`eclipse-temurin:17-jdk`	Link
python	amd64, arm64	`nikolaik/python-nodejs:python3.12-nodejs22`	Link
golang	amd64, arm64	`golang:1.21-bookworm`	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:559e236-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-559e236-python \
  ghcr.io/openhands/agent-server:559e236-python

All tags pushed for this build

ghcr.io/openhands/agent-server:559e236-golang-amd64
ghcr.io/openhands/agent-server:559e236-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:559e236-golang-arm64
ghcr.io/openhands/agent-server:559e236-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:559e236-java-amd64
ghcr.io/openhands/agent-server:559e236-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:559e236-java-arm64
ghcr.io/openhands/agent-server:559e236-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:559e236-python-amd64
ghcr.io/openhands/agent-server:559e236-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:559e236-python-arm64
ghcr.io/openhands/agent-server:559e236-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:559e236-golang
ghcr.io/openhands/agent-server:559e236-java
ghcr.io/openhands/agent-server:559e236-python

About Multi-Architecture Support

Each variant tag (e.g., 559e236-python) is a multi-arch manifest supporting both amd64 and arm64
Docker automatically pulls the correct architecture for your platform
Individual architecture tags (e.g., 559e236-python-amd64) are also available if needed

The hook_config was being accepted but never sent to the server when creating a conversation via RemoteConversation. This meant that hooks for PreToolUse, PostToolUse, UserPromptSubmit, and Stop were never executed server-side. Changes: - Add hook_config to the payload when creating conversations on server - Update example to demonstrate hook configuration with RemoteConversation - Remove outdated warning since hooks are now sent to server Co-authored-by: openhands <openhands@all-hands.dev>

all-hands-bot

Taste Rating: 🟡 Acceptable - Core fix is correct, but example comments need updating.

VERDICT: ✅ Worth merging after fixing the outdated comments. The bug fix itself is solid.

examples/02_remote_agent_server/01_convo_with_local_agent_server.py

openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py

Verifies that hook_config is properly sent to the server when creating a RemoteConversation, ensuring server-side hooks (PreToolUse, PostToolUse, etc.) can execute. Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2026-02-18T13:36:48Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk
__init__.py	20	2	90%	68–69
openhands-sdk/openhands/sdk/agent
agent.py	231	36	84%	94, 98, 240–242, 244, 274–275, 282–283, 315, 368–369, 371, 411, 550–551, 556, 568–569, 574–575, 594–595, 597, 625–626, 633–634, 638, 646–647, 684, 690, 702, 709
openhands-sdk/openhands/sdk/conversation
state.py	184	8	95%	198, 202, 213, 352, 398–400, 514
openhands-sdk/openhands/sdk/conversation/impl
local_conversation.py	330	18	94%	277, 282, 310, 375, 420, 566–567, 570, 716, 724, 726, 737, 739–741, 923, 930–931
remote_conversation.py	594	108	81%	131, 158, 171, 173–176, 186, 208–209, 214–217, 293, 303–305, 311, 352, 484–487, 489, 509–513, 518–521, 524, 536–540, 670–671, 675–676, 687, 706–707, 726, 737–738, 758–761, 763–764, 797–799, 802–806, 808–809, 813, 815–823, 825, 862, 989, 1057–1058, 1062, 1067–1071, 1077–1083, 1096–1097, 1173, 1180, 1186–1187, 1243–1244, 1248, 1251–1253, 1258–1259
openhands-sdk/openhands/sdk/event
hook_execution.py	55	30	45%	87–92, 95–102, 104–107, 109, 112–116, 118–119, 121, 125, 128–129
openhands-sdk/openhands/sdk/event/llm_convertible
system.py	82	31	62%	66–70, 87–88, 133–134, 139–142, 145–153, 156–157, 160–166
openhands-sdk/openhands/sdk/hooks
conversation_hooks.py	157	18	88%	119–120, 153, 162, 172–173, 186–187, 193–194, 222, 269, 319, 327, 332–333, 338, 352
TOTAL	18416	5615	69%

Add HookExecutionEvent to provide full observability into hook execution: - Create new event type HookExecutionEvent with fields for hook type, command, success/blocked status, stdout/stderr, and context - Update HookEventProcessor to emit HookExecutionEvent for all hook types (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, Stop) - Add emit_hook_events parameter to control event emission (default True) - Add 'hook' to SourceType for proper event typing - Export HookExecutionEvent from openhands.sdk public API - Add comprehensive tests for HookExecutionEvent emission - Fix existing tests to handle new events being emitted The HookExecutionEvent includes: - hook_event_type: Type of hook (PreToolUse, PostToolUse, etc.) - hook_command: The command that was executed - success/blocked/exit_code: Execution result - stdout/stderr: Command output - reason/additional_context/error: Hook response data - action_id/message_id: Related event IDs - hook_input: Input data passed to hook Co-authored-by: openhands <openhands@all-hands.dev>

…er.py Co-authored-by: OpenHands Bot <contact@all-hands.dev>

examples/02_remote_agent_server/01_convo_with_local_agent_server.py

- Add hook_config field to ConversationState for persistence - Add hook_config field to SystemPromptEvent for observability in event stream - Update visualize and __str__ methods to display hook info - Store final hook_config in state when plugins are loaded (LocalConversation) - Add hook_config property to RemoteState to fetch from server - Add hook_config to ConversationStateProtocol - Resolve HookConfig forward reference in SystemPromptEvent via model_rebuild This enables users to see what hooks are configured for a conversation via the state API and in the SystemPromptEvent at the start of conversation. Co-authored-by: openhands <openhands@all-hands.dev>

xingyaoww · 2026-02-19T16:49:38Z

tests/cross/test_remote_conversation_live_server.py

+                ],
+            )
+        ],
+    )


@OpenHands can we add a on_stop hook, and make sure we assert that the current post_tool_use hook and the on_stop hook both works? We should also assert that the client will receive the new HookExecutionEvent before say this is implemented

I'm on it! xingyaoww can track my progress at all-hands.dev

Summary

I addressed the PR review comment requesting enhanced test coverage for the test_hook_config_sent_to_server test.

Changes Made (commit 2444bd1e)

File: tests/cross/test_remote_conversation_live_server.py

✅ Added on_stop hook - Configured both post_tool_use and stop hooks in the test

✅ Patched LLM to trigger hooks - Created a fake completion that returns a finish tool call, which triggers:

PostToolUse hook (after finish tool executes)

Stop hook (when agent attempts to stop)

✅ Assert HookExecutionEvent received - Added verification that the client receives HookExecutionEvent for both hook types with:

Correct hook_event_type ("PostToolUse" and "Stop")

success == True

blocked == False

exit_code == 0

Correct hook_command path

✅ Added HookExecutionEvent import to the test file

Verification

Pre-commit hooks pass (ruff format, ruff lint, pycodestyle, pyright)

Changes have been pushed to the fix/remote-conversation-hook-config branch

The test now comprehensively validates that hook_config is properly sent to the server and that both PostToolUse and Stop hooks execute correctly, with HookExecutionEvent events properly received by the client.

- Add on_stop hook in addition to post_tool_use hook - Use patched LLM that returns finish tool call to trigger hooks - Assert HookExecutionEvent events are received for both PostToolUse and Stop - Verify hook execution details (success, blocked, exit_code, command) Co-authored-by: openhands <openhands@all-hands.dev>

Use git commit 2444bd1e66191598f07e7f91adcd6f1c69b78dac from OpenHands/software-agent-sdk#2115 This includes the fix for sending hook_config to server in RemoteConversation. Co-authored-by: openhands <openhands@all-hands.dev>

xingyaoww requested a review from enyst February 18, 2026 12:28

xingyaoww marked this pull request as ready for review February 18, 2026 12:28

xingyaoww mentioned this pull request Feb 18, 2026

feat(app_server): Load hooks from workspace .openhands/hooks.json OpenHands/OpenHands#12773

Draft

all-hands-bot approved these changes Feb 18, 2026

View reviewed changes

examples/02_remote_agent_server/01_convo_with_local_agent_server.py Outdated Show resolved Hide resolved

examples/02_remote_agent_server/01_convo_with_local_agent_server.py Show resolved Hide resolved

openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py Show resolved Hide resolved

test: add test for hook_config being sent to server

80ba8c6

Verifies that hook_config is properly sent to the server when creating a RemoteConversation, ensuring server-side hooks (PreToolUse, PostToolUse, etc.) can execute. Co-authored-by: openhands <openhands@all-hands.dev>

xingyaoww marked this pull request as draft February 18, 2026 17:16

xingyaoww and others added 2 commits February 18, 2026 17:22

Update examples/02_remote_agent_server/01_convo_with_local_agent_serv…

8acdc2f

…er.py Co-authored-by: OpenHands Bot <contact@all-hands.dev>

xingyaoww commented Feb 18, 2026

View reviewed changes

examples/02_remote_agent_server/01_convo_with_local_agent_server.py Outdated Show resolved Hide resolved

xingyaoww and others added 2 commits February 19, 2026 02:43

Apply suggestion from @xingyaoww

16caa43

xingyaoww commented Feb 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: send hook_config to server in RemoteConversation#2115

fix: send hook_config to server in RemoteConversation#2115
xingyaoww wants to merge 7 commits intomainfrom
fix/remote-conversation-hook-config

xingyaoww commented Feb 18, 2026 •

edited by github-actions bot

Loading

Uh oh!

all-hands-bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

xingyaoww Feb 19, 2026

Uh oh!

openhands-ai bot Feb 19, 2026

Uh oh!

openhands-ai bot Feb 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

xingyaoww commented Feb 18, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Changes

Testing

Related Documentation

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

xingyaoww Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Feb 19, 2026

Choose a reason for hiding this comment

Summary

Changes Made (commit 2444bd1e)

Verification

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

xingyaoww commented Feb 18, 2026 •

edited by github-actions bot

Loading

github-actions bot commented Feb 18, 2026 •

edited

Loading

Changes Made (commit `2444bd1e`)