docs(hooks): document agent-based hooks example (51_agent_hooks)#519
docs(hooks): document agent-based hooks example (51_agent_hooks)#519VascoSch92 wants to merge 2 commits into
Conversation
Adds an "Agent-based Hooks" section to the hooks guide covering the new type="agent" hook from software-agent-sdk#3052: how the reviewer sub-agent returns an allow/deny decision, the key HookDefinition fields, isolated sub-conversation execution, agent-hook:* metrics, and fail-open behaviour. Documents examples/01_standalone_sdk/51_agent_hooks/main.py so the agent-sdk "check documented examples" CI passes.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
@burakkeless Could you give a look of the docs please? |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟢 Good taste - Excellent documentation of the new agent-based hooks feature.
This PR provides clear, well-structured documentation that follows all repository conventions. The auto-sync format is correct, examples are comprehensive, and the technical content is accurate.
[IMPROVEMENT OPPORTUNITIES] (Optional, non-blocking)
- The "Exit Codes" section (lines 28-47) could be clarified to indicate it applies specifically to shell script hooks, since agent-based hooks use a different mechanism (JSON payload). Consider adding a note like "For shell script hooks:" to prevent potential confusion.
[RISK ASSESSMENT]
- [Overall PR]
⚠️ Risk Assessment: 🟢 LOW
Documentation-only change that adds new content without modifying existing functionality. The auto-sync format follows the established pattern and will be validated by CI. The branch name matches the agent-sdk PR branch, ensuring proper integration testing.
VERDICT:
✅ Worth merging: High-quality documentation that clearly explains the new feature with excellent examples.
KEY INSIGHT:
The documentation effectively positions agent-based hooks as a semantic alternative to syntactic shell script filters, with the awk /etc/passwd example perfectly illustrating why LLM-based evaluation adds value beyond pattern matching.
Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/docs/actions/runs/26374283356
| - Stop (quality reviewer): refuses to let the main agent finish until the | ||
| required deliverable exists in the workspace. | ||
|
|
||
| For shell-command hooks see ../33_hooks/33_hooks.py. |
There was a problem hiding this comment.
/33_hooks/main.py is the correct path
| sensitive file* even though no obvious keyword (`cat`, `/etc/shadow`) appears. | ||
|
|
||
| Key fields on an agent `HookDefinition`: | ||
|
|
|
@VascoSch92 I left 2 comments , but overall it looks good to me.
|
3 participants
Summary
Documents the new
type="agent"hook introduced in OpenHands/software-agent-sdk#3052 by adding an Agent-based Hooks section tosdk/guides/hooks.mdx.The section covers:
{"decision": "allow"|"deny", "reason": ...}payloadHookDefinitionfields (system_prompt,tools,timeout,max_iterations)agent-hook:*metrics merged into the parent, and fail-open-on-error behaviourexamples/01_standalone_sdk/51_agent_hooks/main.pyWhy
The agent-sdk [Optional] Docs example CI (
check_documented_examples.py) fails on #3052 because the new51_agent_hooksexample is undocumented. This PR adds that documentation.The branch name matches the agent-sdk PR branch (
burak/2864-agent-based-hook-evaluation) so the agent-sdk check picks up this feature branch instead of falling back tomain.Related: OpenHands/software-agent-sdk#3052