feat(sdk): complete hooks implementation with additional context and stop hook #1547

ak684 · 2025-12-30T15:30:32Z

follow up to: #1467

Implement additional_context injection in UserPromptSubmit hooks
- Hook context is appended to MessageEvent.extended_content
- Context is appended to MessageEvent.extended_content and included in LLM messages
Implement stop hook integration in conversation run loop
- Stop hooks can deny premature agent completion
- Feedback from hooks is injected as a user message
- Agent continues running after stop hook denial
Add comprehensive tests for both features
- Tests for context appearing in extended_content
- Tests for context appearing in to_llm_message() output
- Tests for stop hook denial with feedback injection
- Integration tests for full conversation loop with stop hooks
Add advanced hooks example (34_hooks_advanced.py)
- Demonstrates UserPromptSubmit with additional_context
- Demonstrates Stop hook with conditional denial

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:ab9d4ec-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

Each variant tag (e.g., ab9d4ec-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., ab9d4ec-python-amd64) are also available if needed

github-actions · 2025-12-30T15:33:27Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/conversation/impl
local_conversation.py	259	97	62%	148, 150–151, 172, 202, 205–206, 220–221, 244, 249, 291–292, 296–297, 342, 350, 353–357, 364–365, 368, 377–378, 381, 388, 409, 412, 416–418, 425–427, 430, 439, 455, 457, 459, 463, 465–467, 469, 471, 477–478, 491–492, 494, 496, 500–503, 520–521, 527, 532, 535, 537, 547, 549–551, 569, 571, 575, 580, 585, 590–593, 599, 602, 606, 609, 611–613, 615, 633, 635, 649, 653, 661, 677–678, 682, 684, 686, 692–693
openhands-sdk/openhands/sdk/hooks
conversation_hooks.py	134	113	15%	35–37, 41, 46, 49–50, 53–54, 57–58, 61–62, 66–67, 69–70, 73–77, 79, 84–86, 90–92, 94, 102–103, 106–114, 116–117, 119–121, 124–128, 131–135, 137, 144–146, 154–155, 158–162, 164, 168–170, 174–176, 178, 185–187, 191, 200, 204–206, 210–212, 216–219, 223–226, 230–231, 233, 236–238, 241–245, 248–251, 253, 263, 269, 274
TOTAL	14671	6990	52%

…stop hook - Implement additional_context injection in UserPromptSubmit hooks - Hook context is appended to MessageEvent.extended_content - Context flows through condensation and is included in LLM messages - Implement stop hook integration in conversation run loop - Stop hooks can deny premature agent completion - Feedback from hooks is injected as user message with [Stop hook feedback] prefix - Agent continues running after stop hook denial - Add comprehensive tests for both features - Tests for context appearing in extended_content and to_llm_message() - Tests for stop hook denial with feedback injection - Integration tests for full conversation loop with stop hooks - Add advanced hooks example (34_hooks_advanced.py)

rbren · 2025-12-30T16:31:49Z

This likely solves #1527!

examples/01_standalone_sdk/34_hooks_advanced.py

xingyaoww · 2025-12-30T17:14:05Z

examples/01_standalone_sdk/34_hooks_advanced.py

+    config = HookConfig.from_dict(
+        {
+            "hooks": {
+                "UserPromptSubmit": [
+                    {
+                        "hooks": [{"type": "command", "command": str(context_script)}],
+                    }
+                ],
+                "Stop": [
+                    {
+                        "hooks": [{"type": "command", "command": str(stop_script)}],
+                    }
+                ],
+            }
+        }
+    )


NIT: could we make this a HookConfig a pydantic class that contains UserPromptSubmit Stop, etc, which are other pydantic class, so we can have stricter type check instead of putting together a dict like this?

I think this is a great idea. I’ll plan on implementing it in a follow-up PR so that we can keep this PR’s scope focused.

- Move 33_hooks.py to 33_hooks/ folder with separate scripts - Split into basic_hooks.py and advanced_hooks.py - Remove main() wrapper to match codebase convention (31/33 examples) - Extract shell scripts to scripts/ directory for reusability - Add README.md documenting hook types and usage Addresses review feedback: - Consolidate hook examples into folder structure - Simplify examples by removing main() wrapper

…with-additional-context-and-stop-hook-13

examples/01_standalone_sdk/33_hooks/hook_scripts/block_dangerous.sh

examples/01_standalone_sdk/33_hooks/33_hooks.py

Update the hooks documentation to reflect the new 33_hooks.py example that demonstrates all four hook types: - PreToolUse: Block dangerous commands - PostToolUse: Log tool usage - UserPromptSubmit: Inject context into user messages - Stop: Enforce task completion criteria The new example uses external hook scripts in a hook_scripts/ directory and includes a Hook Types reference table. Related to: OpenHands/software-agent-sdk#1547 Co-authored-by: openhands <[email protected]>

openhands-sdk/openhands/sdk/hooks/conversation_hooks.py

Added tests verifying LocalConversation correctly wires hook callbacks to event persistence via original_callback parameter.

Use grep on raw JSON input instead of jq for detecting dangerous commands. This makes the example work out of the box without requiring jq installation.

…with-additional-context-and-stop-hook-13

openhands-ai · 2026-01-06T15:33:18Z

Looks like there are a few issues preventing this PR from being merged!

GitHub Actions are failing:
- [Optional] Docs example

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #1547 at branch `ak684/featsdk-complete-hooks-implementation-with-additional-context-and-stop-hook-13`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

xingyaoww

LGTM! Thank you!

xingyaoww · 2026-01-06T15:35:42Z

@ak684
PR looks good to me - just need to get these doc merged as well OpenHands/docs#230

Update the hooks documentation to reflect the new 33_hooks.py example that demonstrates all four hook types: - PreToolUse: Block dangerous commands - PostToolUse: Log tool usage - UserPromptSubmit: Inject context into user messages - Stop: Enforce task completion criteria The new example uses external hook scripts in a hook_scripts/ directory and includes a Hook Types reference table. Related to: OpenHands/software-agent-sdk#1547 Co-authored-by: openhands <[email protected]>

ak684 force-pushed the ak684/featsdk-complete-hooks-implementation-with-additional-context-and-stop-hook-13 branch from 322a14d to 4c36ba1 Compare December 30, 2025 15:41

ak684 force-pushed the ak684/featsdk-complete-hooks-implementation-with-additional-context-and-stop-hook-13 branch from 4c36ba1 to bda858e Compare December 30, 2025 15:46

enyst self-requested a review December 30, 2025 15:59

xingyaoww reviewed Dec 30, 2025

View reviewed changes

examples/01_standalone_sdk/34_hooks_advanced.py Outdated Show resolved Hide resolved

xingyaoww reviewed Dec 30, 2025

View reviewed changes

examples/01_standalone_sdk/34_hooks_advanced.py Outdated Show resolved Hide resolved

xingyaoww reviewed Dec 30, 2025

View reviewed changes

ak684 and others added 3 commits January 2, 2026 04:11

fix: break long lines in hooks example to pass linting

175b0bd

Merge branch 'main' into ak684/featsdk-complete-hooks-implementation-…

815a264

…with-additional-context-and-stop-hook-13

xingyaoww reviewed Jan 2, 2026

View reviewed changes

examples/01_standalone_sdk/33_hooks/hook_scripts/block_dangerous.sh Outdated Show resolved Hide resolved

xingyaoww reviewed Jan 2, 2026

View reviewed changes

examples/01_standalone_sdk/33_hooks/33_hooks.py Show resolved Hide resolved

xingyaoww mentioned this pull request Jan 2, 2026

Update hooks example to new 33_hooks.py with all hook types OpenHands/docs#230

Merged

xingyaoww reviewed Jan 2, 2026

View reviewed changes

openhands-sdk/openhands/sdk/hooks/conversation_hooks.py Show resolved Hide resolved

ak684 and others added 3 commits January 3, 2026 04:10

fix: wire up original_callback in hook processor for event forwarding

62831a0

Added tests verifying LocalConversation correctly wires hook callbacks to event persistence via original_callback parameter.

refactor: remove jq dependency from hook example

046c60a

Use grep on raw JSON input instead of jq for detecting dangerous commands. This makes the example work out of the box without requiring jq installation.

Merge branch 'main' into ak684/featsdk-complete-hooks-implementation-…

1c9db5c

…with-additional-context-and-stop-hook-13

xingyaoww approved these changes Jan 6, 2026

View reviewed changes

ak684 merged commit 877b4fe into main Jan 6, 2026
21 of 22 checks passed

ak684 deleted the ak684/featsdk-complete-hooks-implementation-with-additional-context-and-stop-hook-13 branch January 6, 2026 18:45

enyst mentioned this pull request Jan 6, 2026

feat: Add plugin loading example demonstrating skills, hooks, and MCP #1616

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(sdk): complete hooks implementation with additional context and stop hook #1547

feat(sdk): complete hooks implementation with additional context and stop hook #1547

Uh oh!

ak684 commented Dec 30, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Dec 30, 2025 •

edited

Loading

Uh oh!

rbren commented Dec 30, 2025

Uh oh!

Uh oh!

Uh oh!

xingyaoww Dec 30, 2025

Uh oh!

ak684 Jan 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

openhands-ai bot commented Jan 6, 2026

Uh oh!

xingyaoww left a comment

Uh oh!

xingyaoww commented Jan 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

feat(sdk): complete hooks implementation with additional context and stop hook #1547

feat(sdk): complete hooks implementation with additional context and stop hook #1547

Uh oh!

Conversation

ak684 commented Dec 30, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rbren commented Dec 30, 2025

Uh oh!

Uh oh!

Uh oh!

xingyaoww Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

ak684 Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

openhands-ai bot commented Jan 6, 2026

Uh oh!

xingyaoww left a comment

Choose a reason for hiding this comment

Uh oh!

xingyaoww commented Jan 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ak684 commented Dec 30, 2025 •

edited by github-actions bot

Loading

github-actions bot commented Dec 30, 2025 •

edited

Loading