Recommend Stop hooks for repository quality gates

openhands/usage/customization/hooks.mdx

@@ -105,7 +105,7 @@
 
 ### `hooks.json` Format
 
 The `.openhands/hooks.json` file maps hook event types to matchers and commands using `snake_case` keys:
 
 ```json
 {
@@ -358,7 +358,7 @@
 
 <Tabs>
   <Tab title="CLI">
     Use the `/skills` command in the CLI to see loaded skills, hooks, and MCPs for the current session.
   </Tab>
   <Tab title="Cloud / Web">
     Active hooks are loaded automatically when a conversation starts. Hook execution events appear in the
@@ -384,6 +384,6 @@
 
 ## See Also
 
-- [Repository Customization](/openhands/usage/customization/repository) - Setup scripts and pre-commit hooks
+- [Repository Customization](/openhands/usage/customization/repository) - Setup scripts and repository-specific hooks
 - [Skills](/overview/skills) - Extend agent behavior with prompt-based skills
 - [Hooks (SDK Guide)](/sdk/guides/hooks) - Programmatic hooks for SDK developers

openhands/usage/customization/repository.mdx

@@ -3,7 +3,7 @@
 description: You can customize how OpenHands interacts with your repository by creating a `.openhands` directory at the root level.
 ---
 
 ## Skills (formerly Microagents)
 
 Skills allow you to extend OpenHands prompts with information specific to your project and define how OpenHands
 should function. See [Skills Overview](/overview/skills) for more information.
@@ -29,26 +29,42 @@
 
 See the dedicated [Hooks](/openhands/usage/customization/hooks) page for the full guide.
 
-## Pre-commit Script
-You can add a `.openhands/pre-commit.sh` file to create a custom git pre-commit hook that runs before each commit.
-This can be used to enforce code quality standards, run tests, or perform other checks before allowing commits.
+## Repository-Specific Stop Hooks
 
-For example:
-```bash
+For repository-specific quality gates, use a [Stop hook](/openhands/usage/customization/hooks) in `.openhands/hooks.json`.
+Stop hooks run when OpenHands tries to finish a task and can block completion until formatting, linting, tests, or other
+repo-specific checks pass. They work across current agent-server-backed OpenHands flows.
+
+For example, create `.openhands/hooks/quality_gate.sh`:
+
+```bash .openhands/hooks/quality_gate.sh
 #!/bin/bash
-# Run linting checks
-cd frontend && npm run lint
-if [ $? -ne 0 ]; then
-  echo "Frontend linting failed. Please fix the issues before committing."
-  exit 1
-fi
+cd "${OPENHANDS_PROJECT_DIR:-$PWD}"
 
-# Run tests
-cd backend && pytest tests/unit
-if [ $? -ne 0 ]; then
-  echo "Backend tests failed. Please fix the issues before committing."
-  exit 1
+# Replace this with your repo's checks, such as npm run lint, pytest, or make test.
+if ! make test 2>&1; then
+  echo '{"decision":"deny","reason":"Quality checks failed. Fix them before finishing."}'
+  exit 2
 fi
 
 exit 0
 ```
+
+Then register it in `.openhands/hooks.json`:
+
+```json .openhands/hooks.json
+{
+  "stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        { "command": ".openhands/hooks/quality_gate.sh", "timeout": 120 }
+      ]
+    }
+  ]
+}
+```
+
+If you currently use `.openhands/pre-commit.sh`, migrate those checks to Stop hooks when you want quality gates to apply
+to current agent-server-backed OpenHands flows. Move the check commands into a Stop hook script like the one above. See the
+[Hooks](/openhands/usage/customization/hooks) guide for complete behavior and JSON response details.