Permission approval UX is non-functional end-to-end: modes are display-only, dialog doesn't block, response protocol untested

[arcavenai]

What happened

The permission/approval system in forestage's custom TUI (--mode forestage, the default) is wired visually but has three functional gaps that together mean the user has no reliable way to approve or deny tool-use requests while running in the forestage TUI.

1. Permission mode toggle (Shift+Tab) is display-only

src/tui/app.rs:213-266 defines PermissionMode (Default / AcceptEdits / Plan / Auto / Bypass). src/tui/input.rs:420-421 dispatches InputAction::CyclePermissionMode on Shift+BackTab. src/tui/mod.rs:291-296 handles the action by calling state.permission_mode = state.permission_mode.next() and updating the status-bar label.

No code path sends the new mode to the Claude Code subprocess. The status bar shows [acceptEdits] but Claude Code is still in whatever mode it was initialized with via system/init (src/protocol_ext.rs:187, src/tui/app.rs:345-350). Cycling is a lie — it mutates forestage's display and nothing else.

2. The permission dialog does not command attention

When a PermissionRequest hook event arrives (src/protocol_ext.rs:315-336 → BridgeEvent::PermissionRequest), it lands on AppState.pending_permission (src/tui/app.rs:475) and src/tui/layout.rs:79-110 reserves a 6-row slot above the input area. The rendering is passive — it just appears where the input moves up a bit. There is:

• no focus pull
• no bell / terminal alert
• no color flash or animation
• no conversation-area dim or modal overlay
• no keypress queue interception explaining what to do
• no timeout indicator, no "Claude is waiting" hint

If the user is reading earlier output when a prompt arrives, nothing signals that the agent is blocked on them. The prompt quietly appears in the layout and stays there.

3. The approve/deny response is explicitly unvalidated and may hang

src/bridge.rs:174-203 contains this WARNING, added in PR #24 review fix 0f4dff1:

WARNING: This protocol format is unvalidated against Claude Code's actual hook response protocol. The hook system may expect a different JSON shape. If the format is wrong, Claude Code will hang waiting for a valid response. Needs integration testing before relying on permission prompt functionality.

send_permission_response() sends:

{"type":"permission_response","permission_response":{"behavior":"allow"|"deny"}}

No one has confirmed Claude Code accepts that shape. Pressing a or d may leave the subprocess hung forever with no user-visible feedback beyond "Permission: allowed" in the status bar.

Expected behavior

The user sees a clear, attention-commanding prompt when Claude Code asks for permission. Pressing a key produces a response that Claude Code actually accepts, and the session proceeds. Cycling permission modes with Shift+Tab changes the actual permission posture of the running session, matching Claude Code's own Shift+Tab behavior.

Concretely:

1. Mode cycling is wired through. Shift+Tab in forestage produces the same effect as Shift+Tab in vanilla Claude Code — the subprocess's permission mode actually changes. Mechanism is TBD: a control message on the NDJSON stream, a SIGHUP-style reload, or (failing that) a restart with the new --permission-mode flag.

2. The dialog commands attention. Options to consider (not all mutually exclusive):

   • Render as a true modal overlay (centered, dimmed background) rather than a layout slot
   • Visual/audio alert on arrival (terminal bell, color flash, border animation)
   • Keyboard input is routed to the dialog until resolved (no accidental typing into the input box)
   • Status bar shows "Claude is waiting for approval" with the pending tool name
   • Optional: allow /permissions slash command or /approve, /deny typed commands as alternatives to a / d

3. The response protocol is validated. Integration test against a live Claude Code subprocess:

   • Confirm the JSON shape Claude Code actually expects for hook permission responses
   • Confirm whether it's type: permission_response or something else (maybe the hook system uses a different envelope)
   • Confirm whether behavior: allow is correct vs. action: allow, decision: allow, permission: grant, etc.
   • Add a regression test (VCR cassette or mock subprocess) that captures the working shape
   • Remove the WARNING comment once validated

4. Failure is visible. If the subprocess does not acknowledge the response within N seconds, surface a warning: "Claude Code did not respond to permission; the protocol may be wrong. Fall back to `--mode claude` for this session." Better a loud failure than a silent hang.

Reproduction

1. forestage (launches default --mode forestage TUI)
2. Prompt Claude to do something that triggers a tool permission check, e.g. run \ls /etc` via bash`
3. Observe the prompt appears quietly above the input area
4. Press Shift+Tab a few times; note that the status bar label changes but the actual permission posture of the subprocess does not (reproducible by comparing to --mode claude behavior)
5. Press a on a permission prompt; note: response may or may not actually unblock the subprocess, depending on whether the unvalidated JSON shape happens to match

Scope

This is one meta-issue because the three gaps are not independently fixable — a working UX requires all three. If this turns out to be too large for one PR, split after the response-protocol integration test clarifies what the correct shape is (that test is the critical path; everything else is UI work).

References

• src/bridge.rs:174-203 — send_permission_response with the WARNING
• src/tui/app.rs:213-266 — PermissionMode enum and cycle
• src/tui/app.rs:268-275 — PermissionPrompt struct
• src/tui/app.rs:475 — where pending_permission is set
• src/tui/app.rs:1076-1120 — render_permission_prompt
• src/tui/input.rs:420-425 — Shift+Tab / a / d bindings
• src/tui/layout.rs:79-110 — layout with permission prompt slot
• src/tui/mod.rs:291-312 — action handlers for cycle/allow/deny
• src/protocol_ext.rs:315-336 — PermissionRequest event parsing
• PR probe(aclaude): TUI prototype — headless Claude Code with custom ratatui interface #24 review commit 0f4dff1 — C1 finding that produced the WARNING

[arcaven]

Part A shipped — `--dangerously-skip-permissions` now available

`ArcavenAE/forestage@4c4e28a` adds `--dangerously-skip-permissions` (alias `--yolo`) as a CLI flag and a config field (`[marvel] dangerously_skip_permissions = true`). When set, forestage passes `--dangerously-skip-permissions` to the claude subprocess at spawn time — the same mechanism director/multiclaude uses for every autonomous agent (see `cli.go:5552`, `daemon.go:2063`, `runner.go:89+315`).

Five unit tests cover mode-only / skip-only / both-set / empty / TOML round-trip. Refactored the four spawn sites (`session.rs` run_prompt / start_streaming_session / interactive_session + `bridge.rs` NDJSON spawn) onto a shared `permission_flags_for(&MarvelConfig)` helper.

What this means for #37: autonomous agents (marvel teams, multiclaude-style fleets) can now run without any permission UI at all — the WARNING path in `bridge.rs:174-203` is never reached, the display-only `Shift+Tab` is never toggled, the passive dialog never renders. Part A closes the escape hatch in the most load-bearing use case.

What's still open (interactive use still needs this):

• Part B — `Shift+Tab` cycle must actually change the subprocess's mode, not just the status-bar label.
• Part C — validate the permission-response JSON shape against live Claude Code and remove the WARNING. This is the critical path; B and D depend on it.
• Part D — dialog must command attention (modal overlay, input routing, optional bell).

Parts B / C / D are tracked as separate work items with B and D linked as blocked by C. I'll leave this meta-issue open until they all ship.

Refs: `ArcavenAE/forestage@4c4e28a`

[arcaven]

Part C closed as a pivot — the approach is architecturally ruled out

The probe for Part C (validate the permission-response JSON shape) finished with a finding that changes the shape of Parts B and D.

Short version: Claude Code's `stream-json` stdin does NOT accept permission responses. The `--include-hook-events` flag emits `PermissionRequest` to stdout for monitoring only — there is no reciprocal input path. Permission decisions are only accepted from hooks registered in `.claude/settings.json` (command-type stdout or http-type response body).

Authoritative: `code.claude.com/docs/en/hooks` (PermissionRequest Hook Reference) plus `claude --help`. Cross-checked against the claude-code-guide research agent.

Shipped in `ArcavenAE/forestage@1e350a7`:

• `bridge.rs send_permission_response` now returns a clear error instead of silently sending a message Claude Code will never read. The WARNING comment is replaced with a pointer to the finding and a list of working alternatives.
• `protocol_ext.rs parse_hook_event` was checking the wrong field name (`subtype`); the documented field is `hook_event_name`. Accepts both for backward-compat. Two regression tests added.
• `tui/mod.rs` PermissionAllow/PermissionDeny unified — both clear the pending prompt and surface the error explanation in the status bar instead of the old 'Permission: allowed/denied' lie.

What this changes about #37 Parts B and D:

• Part B (Shift+Tab wire-through): same architectural constraint. Subprocess permission mode cannot be changed mid-session via stream-json stdin.
• Part D (dialog commands attention): becomes meaningful only after dynamic responses actually work.

Both depend on implementing the HTTP-hook pattern — register an http-type hook in `.claude/settings.json` pointing at a local HTTP server forestage runs, forward the POST to the TUI's event loop, respond with the decision as the HTTP response body. This is the documented path to dynamic permission decisions and is now the load-bearing piece for the rest of #37.

Full finding: `_kos/findings/finding-021-claude-permission-protocol.md` in aae-orc.

Workarounds that work today (all already shipped or available):

• `--dangerously-skip-permissions` (Part A, shipped 4c4e28a)
• `--allowedTools "Bash(git *) Edit"` — fine-grained static pre-approval
• `--disallowedTools "..."` — denylist
• `--permission-mode acceptEdits|auto|dontAsk|plan|bypassPermissions` — various non-prompting modes

Refs: `ArcavenAE/forestage@1e350a7`, finding-021 (aae-orc)

[arcavenai]

Tested in forestage f6cb783 via forestage --persona naomi-nagata --theme the-expanse --permission-mode plan. Still non-functional.

Reproduction:

1. Footer does not display "plan mode on" or any indicator of current permission mode (regression vs the marvel-launched claude.yaml case where the footer shows ⏸ plan mode on (shift+tab to cycle)).
2. Read-only tools work without prompting (pwd, ls).
3. Asked it to touch test.txt — refused (correct, plan mode).
4. Shift+tab cycles modes; reached acceptEdits.
5. Asked it again — what looks like a permission prompt appeared with Write * <unknown> rendered in green.
6. The prompt options do not have focus. The input field still has focus, and there is no apparent way to navigate to the options or select one.

So the dialog now renders, but it's still non-functional from a user-input perspective: it doesn't capture focus, and there's no way to accept/deny.