[luv-324] fix: enforce Stop hook on OpenCode + cut 0.0.10-beta.8

[NiveditJain]

Summary

• OpenCode Stop fix: require-*-before-stop policies fired (visible in dashboard) but the agent stopped without retry — same failure mode as Cursor pre-[luv-319] fix: enforce Stop hook on Cursor Agent CLI + cut 0.0.10-beta.6 #318 / Copilot pre-[luv-299] fix: enforce require-*-before-stop on GitHub Copilot CLI #299. Root cause: no cli === "opencode" branch in policy-evaluator.ts for Stop / SubagentStop, so OpenCode fell into the generic exit-2 path. The shim's applyDecision turns exit-2 into throw new Error(reason), but throwing from inside the session.idle event callback is a no-op — OpenCode is already idle by the time the event fires. Fix: emit {hookSpecificOutput: {additionalContext: <MANDATORY ACTION reasonText>}} for opencode Stop/SubagentStop in both deny and instruct paths. The shim's existing plumbing routes additionalContext through client.session.prompt(...) which submits a new user message and re-triggers the agent loop — same model as Cursor's followup_message and Copilot's {decision: "block", reason}.
• Async + await for Stop: applyDecision is now async and awaits client.session.prompt for Stop/SubagentStop events specifically (fire-and-forget for tool events to avoid hot-path SDK round-trip latency) — without the await, OpenCode could tear down the plugin context before the SDK call lands.
• Gemini: already correct (AfterAgent → Stop emits {decision: "block", reason}); added unit tests pinning both deny and instruct shapes to prevent regression.
• Pi: agent_end is observation-only by upstream design (Pi's loop has already exited; AgentEndEventResult exposes no block field). Documented in CLAUDE.md; no code change.
• Release: cuts 0.0.10-beta.8 by promoting the Unreleased CHANGELOG entry to a versioned heading. package.json was already at 0.0.10-beta.8 (pre-bumped by chore commit a146ae6 after beta.7 release).

Test plan

• bun run test:run — 1582 unit tests pass, includes new opencode shim Stop tests + opencode/gemini Stop branch coverage in policy-evaluator.test.ts
• bun run test:e2e — 296 e2e tests pass
• bun run lint — clean (1 pre-existing img warning, unrelated)
• bunx tsc --noEmit — clean
• bun run build:cli — bundles cleanly
• CI green on luv-324 (build / docs / quality / test×3 / test-e2e + CodeRabbit)
• CodeRabbit review feedback addressed (CHANGELOG entry suffix, docs CLI count)
• Manual smoke: trigger session.idle in OpenCode with a require-*-before-stop policy active; confirm the agent receives a follow-up prompt instead of silently stopping
• Verify dashboard activity feed still records the deny entry

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR fixes enforcement of require-*-before-stop policies on OpenCode CLI for Stop/SubagentStop events. The policy evaluator now returns exitCode: 0 with hookSpecificOutput.additionalContext for deny/instruct decisions, and the plugin shim makes applyDecision async to await client.session.prompt and prevent handler teardown before retry prompts complete.

Changes

OpenCode Stop/SubagentStop Policy Enforcement

Layer / File(s)	Summary
Policy Evaluator Logic src/hooks/policy-evaluator.ts	Adds OpenCode-specific deny and instruct branches for Stop/SubagentStop that return exitCode 0 with hookSpecificOutput.additionalContext, bypassing generic per-event handling.
Plugin Shim Async Handling src/hooks/integrations.ts	Makes applyDecision async and threads eventName; for Stop/SubagentStop with additionalContext, awaits client.session.prompt and swallows errors; other events continue non-blocking forwarding.
Policy Evaluator Tests __tests__/hooks/policy-evaluator.test.ts	Validates OpenCode Stop/SubagentStop deny/instruct response shapes (exitCode 0, hookSpecificOutput.additionalContext, MANDATORY ACTION REQUIRED prefix); asserts PreToolUse deny preserves Claude-style permissionDecision without additionalContext; includes Gemini Stop decision block format coverage.
Plugin Shim Tests __tests__/hooks/opencode-plugin-shim.test.ts	Three new cases: (1) shim awaits client.session.prompt for session.idle with additionalContext and blocks until resolved, (2) rejection swallowed and handler completes, (3) exit code 2 still throws for backward compatibility.
Documentation & Changelog docs/configuration.mdx, CHANGELOG.md	Updates OpenCode documentation to clarify decision-to-semantics mapping for Stop/SubagentStop deny/instruct using client.session.prompt; adds changelog entry documenting the enforcement fix.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• exospherehost/failproofai#299: Modifies Stop/SubagentStop decision handling in policy-evaluator with CLI-specific branches and revised response shapes.
• exospherehost/failproofai#318: Adds CLI-specific Stop/SubagentStop handling in policy-evaluator for a different CLI platform.
• exospherehost/failproofai#297: Modifies the OpenCode plugin shim and its test suite.

Poem

🐰 A hop, skip, and await—
the prompt no longer tears down too late!
Stop events now signal their way,
with async shims here to stay. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% 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
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.
Title check	✅ Passed	The title clearly summarizes the main fix (enforce Stop hook on OpenCode) and references the version bump, directly aligned with the primary changeset.
Description check	✅ Passed	The description provides comprehensive context covering root cause, solution, test plan with checkmarks, and known pending items; however, the template checklist items are missing.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Around line 5-7: Collapse the long narrative under the "### Fixes" section
into a single short summary line and append the PR number (e.g., "(`#323`)"); for
example, replace the long paragraph describing changes to policy-evaluator.ts,
the OpenCode shim’s session.idle behavior and client.session.prompt awaits, and
new tests (policy-evaluator.test.ts and opencode-plugin-shim.test.ts) with one
concise line referencing the core change (e.g., "Make require-*-before-stop
policies enforce on OpenCode; update policy-evaluator.ts and opencode shim to
await client.session.prompt for Stop/SubagentStop and add tests (`#323`)").

In `@docs/configuration.mdx`:
- Line 199: Update the outdated phrase "Unlike the other four CLIs," in the
sentence that begins with that text to reflect the current CLI count or remove
the numeric reference; locate the sentence in configuration.mdx that reads
"Unlike the other four CLIs," (the larger paragraph describing OpenCode
_(beta)_) and replace it with either "Unlike the other CLIs," or "Unlike the
other six CLIs," depending on whether you want a precise count, ensuring the
rest of the sentence and punctuation remain unchanged.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f0f6c01d-21e0-402a-ab49-a3cc36efe71c

📥 Commits

Reviewing files that changed from the base of the PR and between a146ae6 and 0587195.

📒 Files selected for processing (6)

• CHANGELOG.md
• __tests__/hooks/opencode-plugin-shim.test.ts
• __tests__/hooks/policy-evaluator.test.ts
• docs/configuration.mdx
• src/hooks/integrations.ts
• src/hooks/policy-evaluator.ts