docs(sdk-hooks): add explicit Exit Codes section to SDK hooks guide#494
Merged
docs(sdk-hooks): add explicit Exit Codes section to SDK hooks guide#494
Conversation
The companion 'Hooks' page under openhands/usage/customization/ already spells out the 0 / 2 / other exit-code semantics, but the SDK guide (sdk/guides/hooks.mdx) only mentions 'Yes (exit 2)' in the can-block column of the Hook Types table. That leaves SDK developers reading this guide to assume the conventional Unix 'non-zero = failure = block' behavior, which does not match how the SDK (or Claude Code) actually treat hook exit codes. Add an explicit 'Exit Codes' section, mirroring the wording used in the customization docs and Claude Code's own hooks reference, including a Warning that only exit code 2 blocks. Companion to OpenHands/software-agent-sdk PR that updates the SDK HookResult docstring and 33_hooks example README with the same clarification. Co-authored-by: openhands <openhands@all-hands.dev>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
all-hands-bot
approved these changes
May 7, 2026
Contributor
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟢 Good taste - Clean documentation improvement that addresses a real user confusion point.
[RISK ASSESSMENT]
- [Overall PR]
⚠️ Risk Assessment: 🟢 LOW
Documentation-only change. Adds explicit exit code semantics to match the existing OpenHands app docs pattern. Solves the real problem that users might assume conventional Unix semantics (non-zero = block) when only exit code 2 actually blocks.
VERDICT:
✅ Worth merging: Fills a documentation gap with clear, accurate content.
KEY INSIGHT:
The <Warning> callout is especially valuable here—exit code 1 not blocking is counterintuitive and worth explicit emphasis.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
A user asked whether the SDK's stop-hook behavior (only exit code
2blocks) is (1) consistent with Claude Code, and (2) clearly documented everywhere people learn about hooks.(1) Consistency: ✅ already consistent — no SDK behavior change needed
The SDK's
HookExecutordoes:This matches Claude Code's documented hook contract exactly:
(2) Documentation gap
This repo's two hooks pages diverge:
openhands/usage/customization/hooks.mdxsdk/guides/hooks.mdxSo a developer reading the SDK guide could easily assume the conventional Unix "non-zero = failure = block" semantics — exactly the gotcha Claude Code calls out with a Warning.
Change
Add an explicit "Exit Codes" section to
sdk/guides/hooks.mdx, mirroring the wording already used inopenhands/usage/customization/hooks.mdxand Claude Code's own reference, plus a<Warning>callout that only exit2blocks.Companion PR
The SDK side gets matching updates (HookResult docstring + the
33_hooksexample README) in:No code/behavior change; documentation only.
This PR was created by an AI agent (OpenHands) on behalf of the user.
@neubig can click here to continue refining the PR