feat(plugin): surface permission forecasts before execution (#1418)

[JeremyDev87]

Summary

• Add permission_forecast.py module to format permission classes and approval bundles into compact status lines
• Display forecast in user-prompt-submit hook output after mode indicator
• Derive permission hints from mode type in standalone mode (ACT → repo-write, EVAL → read-only)
• Add tests for formatting and display logic

Changes

• packages/claude-code-plugin/hooks/lib/permission_forecast.py — New module: format permission forecast
• packages/claude-code-plugin/hooks/lib/mode_engine.py — Integrate forecast into build_instructions
• packages/claude-code-plugin/hooks/user-prompt-submit.py — Display forecast in hook output
• packages/claude-code-plugin/tests/test_permission_forecast.py — Unit tests
• packages/claude-code-plugin/hooks/test_user_prompt_submit.py — Integration tests

Test plan

• yarn workspace codingbuddy test — 244 files, 6171 tests passed
• CI checks pass
• Manual verification: PLAN/ACT/EVAL show permission forecast line

Closes #1418

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
codingbuddy-landing	Ready	Preview, Comment	Apr 7, 2026 9:48am

[JeremyDev87]

Review: CHANGES_REQUESTED

CI Status: PASS

All 28 checks green (build, type-check, lint, tests, security, e2e).

Spec Compliance (#1418)

Acceptance Criterion	Status
Users see upcoming permission classes before risky execution	PASS
Approval bundles surfaced compactly	PASS
Forecast shown sparingly, not repeated	FAIL (double-print bug)
Tests cover no-forecast, read-only, repo-write, network, external	PASS

Issues Found

[MEDIUM] Duplicate forecast output in standalone mode
Files: hooks/lib/mode_engine.py:468-474 and hooks/user-prompt-submit.py:100-103

In standalone mode, the permission forecast is printed twice:

1. mode_engine.py build_instructions() appends the forecast into the returned instructions string (lines 468-474):

from permission_forecast import generate_standalone_forecast
forecast_line = generate_standalone_forecast(mode_upper)
if forecast_line:
    instructions += "\n\n" + forecast_line

2. user-prompt-submit.py then calls generate_standalone_forecast() again and prints it separately (lines 100-103):

forecast_line = generate_standalone_forecast(detected_mode)
if forecast_line:
    print(forecast_line)

Since print(instructions) already contains the forecast from step 1, the user sees it twice. This contradicts the spec requirement that the forecast be "shown sparingly rather than repeated."

Fix: Remove the forecast call from one of the two locations. Recommended: remove the block from mode_engine.py:468-474 and keep it only in user-prompt-submit.py, which already handles both MCP and standalone paths consistently. This keeps build_instructions() focused on mode instructions and avoids coupling it to the forecast display concern.

---

[LOW] Unused PERMISSION_CLASS_ICONS dictionary
File: hooks/lib/permission_forecast.py:28-34

PERMISSION_CLASS_ICONS is defined but never referenced by any code in the codebase. If this is reserved for future use (e.g., a richer display), consider adding a comment noting that, or remove it until needed to keep the module clean.

---

[LOW] format_permission_forecast_from_mcp() not called by production code
File: hooks/lib/permission_forecast.py:110

This function is defined and thoroughly tested but not imported by any production module. Only test files reference it. If this is intentional preparation for wiring into MCP response handling later, this is fine as-is. Consider adding a brief comment noting it is reserved for MCP integration so future reviewers do not flag it as dead code.

Summary

Severity	Count
CRITICAL	0
HIGH	0
MEDIUM	1
LOW	2

The new permission_forecast.py module is well-structured — pure functions, good type hints, thorough docstrings, and comprehensive test coverage (unit + integration). The standalone forecast logic correctly mirrors the MCP server's mode-permission mapping. The only actionable issue is the double-print bug in standalone mode, which directly contradicts the "low-noise" spec requirement.

Recommendation: REQUEST CHANGES

Fix the duplicate forecast output in standalone mode, then this is ready to merge.

[JeremyDev87]

Re-Review: APPROVE

CI Status: PASS (28/28 checks green)

Previous Issues: All 3 resolved

1. MEDIUM: Duplicate forecast output in standalone mode — FIXED. mode_engine.py is no longer in the changed files list. Forecast output is now exclusively in user-prompt-submit.py (lines 85-89 for MCP-available path, lines 103-106 for standalone path). No duplication.

2. LOW: Unused PERMISSION_CLASS_ICONS dict — FIXED. The dict is completely absent from permission_forecast.py. Only PERMISSION_CLASS_LABELS exists (text-only labels, no icons).

3. LOW: format_permission_forecast_from_mcp not called — FIXED. Docstring now reads: "NOTE: Reserved for future MCP integration — not yet called by production code." Clear intent documented.

New Issues Found: 0

Code is clean after the amend:

• All functions are pure (no I/O, no side effects) as documented
• Test coverage is thorough: 3 test classes in unit tests (empty, read-only, bundles, multi-class, MCP extraction, standalone per-mode, case insensitivity, unknown mode)
• Integration tests cover ACT/PLAN/EVAL/AUTO/no-keyword paths
• No hardcoded secrets, no empty catch blocks, no debug prints
• Security checks passed in CI

Recommendation: APPROVE