feat(hooks): task-boundary test discovery hook [OMN-7261] by jonahgabriel · Pull Request #1504 · OmniNode-ai/omniclaude

jonahgabriel · 2026-05-01T21:45:55Z

Summary

New hook: pre_tool_use_task_boundary_tests.sh fires on git commit / gh pr create
Test discovery: finds relevant test files for staged Python files via path heuristics (tests/test_<module>.py, tests/<path>/test_*.py)
Execution: runs only discovered tests with --timeout=120, 120s budget
Debounce: 60s cooldown per repo to avoid re-running on rapid consecutive commits
Fail-open: exits 0 on timeout, missing pytest, infra errors (never blocks Claude Code)
Opt-in: TASK_BOUNDARY_TESTS bit 58 in ONEX_HOOKS_MASK — disabled by default
37 unit tests covering trigger conditions, debounce, discovery, timeout, full main() integration

Files changed

File	Purpose
`plugins/onex/hooks/lib/task_boundary_tests.py`	Python test discovery + execution logic
`plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh`	Shell hook wrapper
`plugins/onex/hooks/hooks.json`	Registered under PreToolUse with Bash matcher
`plugins/onex/hooks/lib/hook_bits.sh`	Regenerated with TASK_BOUNDARY_TESTS bit 58
`tests/hooks/test_task_boundary_tests.py`	37 unit tests

Verification

uv run pytest tests/hooks/test_task_boundary_tests.py -v
# 37 passed in 0.06s
uv run ruff check plugins/onex/hooks/lib/task_boundary_tests.py
# All checks passed!

Linked

OMN-7261
Cross-repo: feat(enums): add TASK_BOUNDARY_TESTS bit to EnumHookBit [OMN-7261] omnibase_core#1025 (enum bit)

Evidence-Source: OCC#669

Summary by CodeRabbit

New Features
- Adds a pre-tool hook that auto-runs relevant Python tests for git commit / gh pr create, can block the action on failures, and uses a per-repo debounce and timeout.
Chores
- Improved hook gating and enablement handling, stricter shell error handling, safer fail-open behavior, and more robust project/repo detection.
Tests
- Added extensive tests covering triggers, debounce, discovery, execution results, timeout/missing-tool fail-open semantics, and shell integration.

Evidence-Ticket: OMN-7261

Task-boundary test hook fires on git commit / gh pr create, discovers relevant tests for staged Python files, and runs them with a 120s budget. Blocks on test failure; fails open on timeout/infra errors. Opt-in via TASK_BOUNDARY_TESTS bit in ONEX_HOOKS_MASK (default: disabled until user enables it). Files: - lib/task_boundary_tests.py: test discovery + execution logic - scripts/pre_tool_use_task_boundary_tests.sh: shell hook wrapper - hooks.json: registered under PreToolUse with Bash matcher - lib/hook_bits.sh: regenerated with TASK_BOUNDARY_TESTS bit 58 - tests/hooks/test_task_boundary_tests.py: 37 unit tests

coderabbitai · 2026-05-01T21:46:01Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2e1aeee2-efcb-4bec-b66a-f53e5f767ada

📥 Commits

Reviewing files that changed from the base of the PR and between 6185155 and 5b807d1.

📒 Files selected for processing (2)

plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh
tests/hooks/test_task_boundary_tests.py

🚧 Files skipped from review as they are similar to previous changes (1)

tests/hooks/test_task_boundary_tests.py

📝 Walkthrough

Walkthrough

Adds a PreToolUse Bash hook that runs staged-Python-file test discovery and pytest (120s) before git commit / gh pr create. Introduces per-repo debounce, a new hook bit, gating by mask, a Python runner, a shell wrapper, and comprehensive tests.

Changes

Task Boundary Tests Hook

Layer / File(s)	Summary
Hook Registration `plugins/onex/hooks/hooks.json`	Appends a `PreToolUse` matcher for `Bash` that executes `pre_tool_use_task_boundary_tests.sh`.
Hook Bits / Mask `plugins/onex/hooks/lib/hook_bits.sh`	Adds `TASK_BOUNDARY_TESTS` bit (`0x400000000000000`) to `hook_bits_bit_for_name()` and widens `HOOK_BITS_DEFAULT_MASK` to `0x7ffffffffffffff`.
Core Logic `plugins/onex/hooks/lib/task_boundary_tests.py`	New Python executable implementing trigger detection (`git commit` / `gh pr create`), repo-root resolution, staged `*.py` enumeration, mapping changed files to candidate `tests/` targets (including `tests/hooks/` and parent-dir variants), per-repo debounce markers, running pytest under a 120s timeout, returning allow (exit 0) or writing `{"decision":"block","reason":...}` and exiting `2` on test failures; treats pytest timeout or missing pytest as fail-open (allow).
Hook Wrapper / Wiring `plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh`	New strict-mode Bash pre-hook that reads hook JSON from stdin, optionally enforces repo eligibility, loads `hook_bits.sh` and only applies gating if the `TASK_BOUNDARY_TESTS` bit is present in `ONEX_HOOKS_MASK` (otherwise it proceeds without gating), validates `tool_name == "Bash"` and command triggers, invokes the Python runner with a sanitized env, logs stderr, echoes results, exits `2` on block, and fails open (echo original payload; exit `0`) on setup or runtime errors.
Tests `tests/hooks/test_task_boundary_tests.py`	Adds extensive pytest coverage: trigger matching variations, debounce behavior, deterministic debounce key and touching, repo-root detection, staged-file handling, test discovery and deduplication, `_run_tests` pass/fail/timeout/missing-pytest semantics, main() integration flows (allow/pass-through/block), and shell-script end-to-end behaviors (gate disabled, fail-open scenarios).

Sequence Diagram

sequenceDiagram
    actor User
    participant Bash as "Bash (tool)"
    participant HookGate as "PreToolUse Hook Gate"
    participant Script as "pre_tool_use_task_boundary_tests.sh"
    participant Python as "task_boundary_tests.py"
    participant Git as "git"
    participant Pytest as "pytest"

    User->>Bash: run git commit / gh pr create
    Bash->>HookGate: invoke PreToolUse hooks (stdin JSON)
    HookGate->>Script: execute pre_tool_use_task_boundary_tests.sh
    Script->>Script: parse stdin, check TASK_BOUNDARY_TESTS mask
    alt Gate enabled & tool == Bash & trigger command
        Script->>Python: run task_boundary_tests.py (stdin payload)
        Python->>Git: locate repo root (.git)
        Git-->>Python: repo root path
        Python->>Git: list staged *.py files
        Git-->>Python: staged files
        Python->>Python: map changed files → candidate tests under tests/
        Python->>Pytest: run discovered tests (timeout 120s)
        Pytest-->>Python: results (pass/fail/timeout)
        alt Tests pass or no applicable tests
            Python-->>Script: exit 0 (allow)
            Script-->>HookGate: print original payload and exit 0
        else Tests fail
            Python-->>Script: print JSON {"decision":"block"} and exit 2
            Script-->>HookGate: exit 2 (block)
        end
    else Gate disabled or non-trigger
        Script-->>HookGate: passthrough original payload and exit 0
    end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I hop through staged files, sniff and test,
Nudge pytest gently, then pause or let you rest.
If reds appear, I thump and hold the gate,
If greens prevail, I cheer and celebrate. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main addition: a new task-boundary test discovery hook system with the jira ticket reference.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch jonah/omn-7261-task-boundary-test-hooks

_{Review rate limit: 4/5 reviews remaining, refill in 12 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-05-01T21:46:18Z

⚠️ Hostile Reviewer — DEGRADED (informational)

Blocking findings (critical/error): 0
Total findings: 0
Models succeeded: none

Note: All reviewer models failed or were unavailable. Degraded results are informational during the pilot phase (OMN-8524) and do not block merge. Error: cli_review exited non-zero (all models failed or binary error)

Gate semantics (pilot phase)

Verdict	Meaning	Blocks merge?
`passed`	No critical/error findings	No
`blocked`	CRITICAL or ERROR findings found	Yes
`degraded`	All models unavailable (infra)	No (pilot)

Powered by omniintelligence.review_pairing.cli_review — node-based adversarial review via HandlerLlmCliSubprocess (OMN-8524)

…oundary-test-hooks-local

coderabbitai

Actionable comments posted: 5

🧹 Nitpick comments (1)

tests/hooks/test_task_boundary_tests.py (1)

46-50: ⚡ Quick win

Add regressions for the missing edge cases.

The suite covers the happy path, but it still misses gh pr create after ; and the case where a failed run should not start the debounce window. Those are the two regressions most likely to slip through here.

Also applies to: 252-289

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/hooks/test_task_boundary_tests.py` around lines 46 - 50, Add two
regression tests in tests/hooks/test_task_boundary_tests.py: one that asserts
tbt._is_trigger_command returns True for a command with a preceding semicolon
(e.g., "...; gh pr create --title 'x'") to cover the semicolon edge-case, and
another that verifies a failed run does not start the debounce window by
ensuring the task-boundary tracker (use the same test helper that simulates runs
in this suite) does not update its last-start/debounce state after a run that is
marked failed; refer to the existing test helpers and tbt._is_trigger_command
and the test names pattern (e.g., test_gh_pr_create_with_semicolon,
test_failed_run_does_not_start_debounce) when adding these cases so they mirror
the other tests in this file.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@plugins/onex/hooks/lib/hook_bits.sh`:
- Line 7: The default hook bits mask HOOK_BITS_DEFAULT_MASK was widened to
include the TASK_BOUNDARY_TESTS bit which makes that hook opt-out instead of
opt-in; change HOOK_BITS_DEFAULT_MASK so it does not contain the
TASK_BOUNDARY_TESTS bit (restore the previous mask value or explicitly remove
the TASK_BOUNDARY_TESTS bit from the constant) and leave TASK_BOUNDARY_TESTS
only enabled when explicitly added by consumers.

In `@plugins/onex/hooks/lib/task_boundary_tests.py`:
- Around line 31-36: The regex _RE_GH_PR_CREATE used by _is_trigger_command
doesn't treat ';' as a command separator so constructs like "echo hi; gh pr
create" won't match; update the pattern for _RE_GH_PR_CREATE to include ';' (and
other shell separators if desired, e.g., '||') as alternatives (mirror what
_RE_GIT_COMMIT does) so that _is_trigger_command correctly detects "gh pr
create" following a semicolon.
- Around line 166-178: The debounce marker is being touched before running
tests, which starts the cooldown even on failures; move the call to
_touch_debounce(debounce_key) so it only executes after tests pass: call
_run_tests(repo_root, tests), check the returned passed flag, and if passed is
True then call _touch_debounce(debounce_key) (only after this success path and
before any json.dump/sys.exit that indicates success); do not touch the debounce
key on the early exits or when passed is False.
- Around line 112-126: The subprocess.run call in task_boundary_tests.py is
passing the pytest CLI flag "--timeout=120" but the project lacks the
pytest-timeout plugin; add "pytest-timeout" to the dev dependencies in
pyproject.toml (dev dependency group) so pytest recognizes that flag, and mirror
the same addition for any CI or hook scripts that invoke pytest with --timeout
(e.g., the invocation in plugins/onex/hooks/scripts/epic_postaction_gate.sh), or
alternatively remove the "--timeout=120" argument and rely solely on the
subprocess.run timeout controlled by TEST_TIMEOUT_SECONDS.

In `@plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh`:
- Around line 34-57: The script can return early and leave stdin buffered;
ensure you drain stdin before any non-standard exit by adding a stdin drain
(e.g., read/discard all input) both after the failed source of onex-paths.sh
(the block that currently does: source ".../onex-paths.sh" || { echo ...; exit
1; }) and immediately before the early passthrough return triggered by
onex_hook_gate TASK_BOUNDARY_TESTS || exit 0 so the hook preserves the stdin
passthrough contract; update those locations to discard stdin prior to exit and
then exit 0.

---

Nitpick comments:
In `@tests/hooks/test_task_boundary_tests.py`:
- Around line 46-50: Add two regression tests in
tests/hooks/test_task_boundary_tests.py: one that asserts
tbt._is_trigger_command returns True for a command with a preceding semicolon
(e.g., "...; gh pr create --title 'x'") to cover the semicolon edge-case, and
another that verifies a failed run does not start the debounce window by
ensuring the task-boundary tracker (use the same test helper that simulates runs
in this suite) does not update its last-start/debounce state after a run that is
marked failed; refer to the existing test helpers and tbt._is_trigger_command
and the test names pattern (e.g., test_gh_pr_create_with_semicolon,
test_failed_run_does_not_start_debounce) when adding these cases so they mirror
the other tests in this file.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 062de5ba-c00b-468e-ad97-ff94fdb7f591

📥 Commits

Reviewing files that changed from the base of the PR and between 2a37395 and 1a927a8.

📒 Files selected for processing (5)

plugins/onex/hooks/hooks.json
plugins/onex/hooks/lib/hook_bits.sh
plugins/onex/hooks/lib/task_boundary_tests.py
plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh
tests/hooks/test_task_boundary_tests.py

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh`:
- Around line 99-104: The grep patterns checking COMMAND in the
pre_tool_use_task_boundary_tests.sh hook are inconsistent: one pattern uses \|\|
(matching only "||") while the other uses \| (matching only "|"), so pipe
contexts like "foo | git commit" or "foo || gh pr create" are missed; update
both regexes that reference COMMAND (the lines that match 'git\s+commit' and
'gh\s+pr\s+create') to accept one or more pipe characters (e.g., use a
quantifier like \|+ or an alternation covering both) in the
'(^|\s|&&|\|\||;|...)' portion so both single and double pipes are matched
consistently. Ensure the anchors remain the same and only the pipe token portion
is changed so COMMAND detection continues to work for both "|" and "||".

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0c8336d3-da9f-48e6-850f-ecb9df2a1459

📥 Commits

Reviewing files that changed from the base of the PR and between 1a927a8 and 220f927.

📒 Files selected for processing (3)

plugins/onex/hooks/lib/task_boundary_tests.py
plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh
tests/hooks/test_task_boundary_tests.py

✅ Files skipped from review due to trivial changes (1)

plugins/onex/hooks/lib/task_boundary_tests.py

🚧 Files skipped from review as they are similar to previous changes (1)

tests/hooks/test_task_boundary_tests.py

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh`:
- Line 81: Guard the unprotected source of common.sh so failures don't cause the
script to exit under set -e: before sourcing "${HOOKS_DIR}/scripts/common.sh"
check that the file exists and is readable (e.g., test -f/-r) and only source it
inside that conditional; if the file is missing or not readable, emit a
non-fatal warning message and continue so the hook remains fail-open—do not
allow errors from sourcing to propagate (use a conditional source or append a
no-fail fallback) and update the reference at the existing source line.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 842d18d9-5f6d-4cd9-840a-d74f7a45dcb0

📥 Commits

Reviewing files that changed from the base of the PR and between 220f927 and 594ee6e.

📒 Files selected for processing (3)

plugins/onex/hooks/lib/task_boundary_tests.py
plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh
tests/hooks/test_task_boundary_tests.py

✅ Files skipped from review due to trivial changes (1)

tests/hooks/test_task_boundary_tests.py

🚧 Files skipped from review as they are similar to previous changes (1)

plugins/onex/hooks/lib/task_boundary_tests.py

coderabbitai

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh`:
- Around line 46-54: The hook-bit loading/parsing must fail-open: guard sourcing
HOOK_BITS_PATH (check file existence before calling source) so source
"$HOOK_BITS_PATH" cannot cause set -e to abort, and make hook_bits_parse_mask
invoked in a way that returns an empty TASK_BOUNDARY_MASK on error (e.g. capture
its output with a fallback like || true) so TASK_BOUNDARY_MASK is never left as
a failing command; then ensure hook_bits_is_enabled is only called when
TASK_BOUNDARY_BIT and TASK_BOUNDARY_MASK are non-empty (use TASK_BOUNDARY_BIT
from hook_bits_bit_for_name and TASK_BOUNDARY_MASK from hook_bits_parse_mask) so
the script always exits 0 unless you intentionally block.
- Around line 27-30: Wrap the path-bootstrap sequence that sets _SELF,
SCRIPT_DIR and PLUGIN_ROOT with a fail-open guard so any error in the bootstrap
does not exit non-zero: if the realpath/cd resolution fails, drain stdin (e.g.
run cat to consume input) and then exit 0. Concretely, ensure the compound
assignment for _SELF, the SCRIPT_DIR calculation, and PLUGIN_ROOT expansion are
guarded as a unit (referencing _SELF, SCRIPT_DIR, PLUGIN_ROOT) and on failure
run cat >/dev/null (to drain stdin) then exit 0.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e483dacf-b048-4fed-a6a9-829270088caa

📥 Commits

Reviewing files that changed from the base of the PR and between 594ee6e and 6185155.

📒 Files selected for processing (2)

plugins/onex/hooks/scripts/pre_tool_use_task_boundary_tests.sh
tests/hooks/test_task_boundary_tests.py

🚧 Files skipped from review as they are similar to previous changes (1)

tests/hooks/test_task_boundary_tests.py

github-actions Bot enabled auto-merge May 1, 2026 21:49

github-actions Bot added this pull request to the merge queue May 2, 2026

github-merge-queue Bot removed this pull request from the merge queue due to no response for status checks May 2, 2026