Hand-back check: give it its own switch

[EdbertChan]

Summary

A check catches replies that hand the user a step the agent could have run. Here it never ran, because it shared a switch with features that are off.

This gives that check its own switch. It also still turns on when the older switch is on.

The new switch is off by default.

Review Claim

Approve a separate switch for turning on the hand-back check, so it can run without turning on the other reflect features.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The new switch defaults to off and the old switch still turns the check on, so nothing changes until someone opts in. The check only reports; it never blocks a reply.

Slice Rationale

The switch and its hook change are one claim. The written rule and the planning guide are other claims and ship separately.

Non-goals

• No change to what the check judges.
• No change to the other reflect checks.
• No fix for the failing test noted below; it fails the same way on the base.

Measured

Command: python3 -m unittest engine/hooks/handback-needs-attempt/tests/test_hooks.py

• base: Ran 9 tests ... FAILED (failures=1) (the one failure is test_stop_wrapper_never_blocks_the_reply)
• head: Ran 11 tests ... FAILED (failures=1) (the same one failure; the 2 new tests pass)

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/_flags/tests printed Ran 45 tests ... OK
• python3 scripts/ci/check_hook_test_coverage.py engine/hooks/handback-needs-attempt printed check_hook_test_coverage: OK (1 hook(s) checked)
• Known failing on the base and the head: test_stop_wrapper_never_blocks_the_reply prints catstack-hook-error handback-needs-attempt: ... rejected blank or synthetic model
• Not run: the check flagging a real handoff in a live session. Blocker: hooks run from the installed copy, which only updates after this merges and ./install.sh runs

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <sha>
• Post-revert steps: None
• Data migration? No

🤖 Generated with Claude Code

---

Note

Low Risk
Additive flag wiring with default-off behavior and unchanged reflect-enforcement compatibility; the check remains advisory and does not block replies.

Overview
The handback-needs-attempt Stop hook no longer runs only when CATSTACK_REFLECT_ENFORCEMENT is on. It gets its own opt-in flag (default off) so the hand-back judge can run without enabling the rest of reflect/automate-me.

CATSTACK_REFLECT_ENFORCEMENT=1 still enables the check, preserving today’s behavior for anyone already using that switch. The hook’s gate and shared _flags wiring are updated accordingly, with two new unit tests covering the dedicated flag path.

^{Reviewed by Cursor Bugbot for commit a38ea67. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: cab39655-cd5c-4290-952b-54694bc704d7)

[mergify]

Queued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-12 20:06 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ❌ Checks failed · on draft merge queue: checking #1360 on main (2f93d6c), stacked on 4 pull requests ahead #1362
• 🚫 Left the queue — 2026-10-12 21:12 UTC · at a17475f9e0f89cdc4071ac4c54c7bd0cce9d078a

This pull request spent 1 hour 6 minutes 10 seconds in the queue, including 47 minutes 40 seconds running CI.

Reason

The merge conditions cannot be satisfied due to failing checks

• test

Failing checks:

• ❌ test (job log)

Hint

You may have to fix your CI before adding the pull request to the queue again.
If you update this pull request, to fix the CI, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

Waiting for

• check-success = test

All conditions

• check-success = test
• check-success = lint
• check-success = validate

Requeued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-12 22:51 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ❌ Checks timed out · on draft merge queue: checking #1360 on main (76f7a53), stacked on #1358, #1359 and #1336 #1367
• 🚫 Left the queue — 2026-10-12 23:52 UTC · at a17475f9e0f89cdc4071ac4c54c7bd0cce9d078a

This pull request spent 1 hour 45 seconds in the queue, including 1 hour 30 seconds running CI.

Reason

The merge conditions cannot be satisfied: the checks did not pass within the checks timeout of 1 hour

These checks were still running:

• test

Failing checks:

• 🟠 test (job log)

Hint

You may have to fix your CI before adding the pull request to the queue again.

If you update this pull request, to fix the CI, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

Waiting for

• check-success = test

All conditions

• check-success = test
• check-success = lint
• check-success = validate

Requeued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-13 01:12 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ❌ Checks timed out · on draft merge queue: checking #1360 on main (31c49a8) #1370
• 🚫 Left the queue — 2026-10-13 02:18 UTC · at 42ee33c69ca49de9b4f01e6325f3334d8bdfed51

This pull request spent 1 hour 5 minutes 32 seconds in the queue, including 1 hour 33 seconds running CI.

Reason

The merge conditions cannot be satisfied: the checks did not pass within the checks timeout of 1 hour

These checks were still running:

• test

Failing checks:

• 🟠 test (job log)

Hint

You may have to fix your CI before adding the pull request to the queue again.

If you update this pull request, to fix the CI, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

Waiting for

• check-success = test

All conditions

• check-success = test
• check-success = lint
• check-success = validate

Requeued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

🛑 Queue command has been cancelled

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: d0274e66-9f25-4672-a3b6-8d47b33ee02a)

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-13 04:08 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ❌ Checks timed out — 2026-10-13 04:08 UTC · on draft merge queue: checking #1354 + #1374 + #1360 together on main (d89f0c8) #1376
• ✂️ Bisecting to identify the failing PR (round 1/1)
• 🚫 Left the queue — 2026-10-13 06:10 UTC · at a38ea6789bb9e039623d8dd8a413aae088aa6c84

This pull request spent 2 hours 1 minute 55 seconds in the queue, including 1 hour 31 seconds running CI.

Reason

The merge conditions cannot be satisfied: the checks did not pass within the checks timeout of 1 hour

These checks were still running:

• test

Failing checks:

• 🟠 test (job log)

Hint

You may have to fix your CI before adding the pull request to the queue again.

If you update this pull request, to fix the CI, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

Requeued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-13 07:00 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #1360 on main (7ede769) #1392
• ✅ Merged — 2026-10-13 08:01 UTC · at 95a74291d755e687967c28f33352a237d59bca81 · squash

This pull request spent 1 hour 1 minute 18 seconds in the queue, including 1 hour 57 seconds running CI.

Required conditions to merge

• check-success = lint
• check-success = test
• check-success = validate