Proposal: update specification — inline Permission Question Widget for single-file permission requests #2178

Closed
opened 2026-04-03 06:02:02 +00:00 by freemo · 2 comments
Owner

Spec Update Proposal

Triggered By

  • Commit 0be3f85c (merged 2026-04-03): feat(tui): implement Permission Question Widget (closes #997)

Change: Inline Permission Question Widget

What changed in the implementation

Commit 0be3f85c implemented an inline PermissionQuestionWidget that renders directly in the conversation stream for single-file permission requests. This is a new UX pattern not currently described in the spec.

What the implementation adds:

  1. PermissionQuestionWidget — a Static-based Textual widget that renders inline in the conversation stream (not as a separate screen or prompt replacement). Used for single-file permission requests.

  2. InlinePermissionQuestion domain model with fields:

    • file_path: str — path of the file the actor wants to operate on
    • request_type: PermissionRequestType — type of operation
    • diff_content: str — unified diff content (may be empty)
    • actor_name: str — name of the actor requesting permission
  3. PermissionRequestType enum: FILE_WRITE, FILE_DELETE, FILE_READ, SHELL_EXEC, NETWORK

  4. PermissionDecision enum: ALLOW_ONCE, ALLOW_ALWAYS, REJECT_ONCE, REJECT_ALWAYS

  5. Widget behavior:

    • Renders inline in conversation stream (not replacing the prompt)
    • Navigation: up/down arrows to cycle options, enter to confirm
    • Single-key shortcuts: a (allow once), A (allow always), r (reject once), R (reject always)
    • v key opens the full PermissionsScreen for multi-file diff view
    • Shows diff content inline when available
    • Emits PermissionDecisionEvent when a decision is made

Relationship to existing spec:

The ADR-044 spec currently describes:

  • PermissionsScreen — pushed for tool permission requests (full screen)
  • QuestionWidget — replaces the prompt during actor permission requests

The implementation adds a third pattern: an inline widget in the conversation stream for single-file operations, with the full PermissionsScreen accessible via v key.

Spec sections affected

ADR-044 (TUI Architecture) — Prompt Architecture section currently says:

QuestionWidget — replaces the prompt during actor permission requests (allow/reject choices)

This should be updated to distinguish between:

  • Single-file requests: inline PermissionQuestionWidget in conversation stream
  • Multi-file requests: full PermissionsScreen pushed

docs/specification.md — The TUI section describing permission handling should be updated to document:

  • The inline permission question widget and its 4-decision model
  • The PermissionRequestType enum (FILE_WRITE, FILE_DELETE, FILE_READ, SHELL_EXEC, NETWORK)
  • The PermissionDecision enum (ALLOW_ONCE, ALLOW_ALWAYS, REJECT_ONCE, REJECT_ALWAYS)
  • The keyboard shortcuts (a/A/r/R, up/down, enter, v)
  • The routing logic: single-file → inline widget; multi-file → PermissionsScreen

Proposed spec addition

In the TUI section of docs/specification.md, add a subsection under the permission handling area:

#### Inline Permission Question Widget

For single-file permission requests, the TUI renders a `PermissionQuestionWidget` inline in the conversation stream. This avoids interrupting the conversation flow for simple allow/reject decisions.

The widget displays:
- The actor name and requested operation type
- The target file path
- Four decision options with keyboard shortcuts

| Key | Decision | Scope |
|-----|----------|-------|
| `a` | Allow once | This operation only |
| `A` | Allow always | All operations this session |
| `r` | Reject once | This operation only |
| `R` | Reject always | All operations this session |

Navigate options with `up`/`down` and confirm with `enter`, or use the single-key shortcuts directly. Press `v` to open the full `PermissionsScreen` for multi-file diff review.

**Permission request types**: `file_write`, `file_delete`, `file_read`, `shell_exec`, `network`.

For multi-file operations, the full `PermissionsScreen` is pushed directly (no inline widget).

Rationale

The inline widget is a genuine UX improvement over the spec's original QuestionWidget (which replaced the prompt). Rendering inline in the conversation stream keeps context visible and is more ergonomic for single-file decisions. The 4-decision model (once/always × allow/reject) is also more expressive than a simple allow/reject. This is an implementation improvement that should be reflected in the spec.


Scope

Section Change Type
docs/specification.md — TUI permission handling Add inline widget description, decision enum, request type enum, keyboard shortcuts
docs/adr/ADR-044-tui-architecture-and-framework.md — Prompt Architecture Update QuestionWidget description to distinguish inline vs full-screen

Awaiting human approval before any branch or PR is created.


Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Update Proposal ### Triggered By - **Commit `0be3f85c`** (merged 2026-04-03): `feat(tui): implement Permission Question Widget` (closes #997) --- ## Change: Inline Permission Question Widget ### What changed in the implementation Commit `0be3f85c` implemented an inline `PermissionQuestionWidget` that renders directly in the conversation stream for single-file permission requests. This is a new UX pattern not currently described in the spec. **What the implementation adds:** 1. **`PermissionQuestionWidget`** — a `Static`-based Textual widget that renders inline in the conversation stream (not as a separate screen or prompt replacement). Used for single-file permission requests. 2. **`InlinePermissionQuestion`** domain model with fields: - `file_path: str` — path of the file the actor wants to operate on - `request_type: PermissionRequestType` — type of operation - `diff_content: str` — unified diff content (may be empty) - `actor_name: str` — name of the actor requesting permission 3. **`PermissionRequestType` enum**: `FILE_WRITE`, `FILE_DELETE`, `FILE_READ`, `SHELL_EXEC`, `NETWORK` 4. **`PermissionDecision` enum**: `ALLOW_ONCE`, `ALLOW_ALWAYS`, `REJECT_ONCE`, `REJECT_ALWAYS` 5. **Widget behavior**: - Renders inline in conversation stream (not replacing the prompt) - Navigation: `up`/`down` arrows to cycle options, `enter` to confirm - Single-key shortcuts: `a` (allow once), `A` (allow always), `r` (reject once), `R` (reject always) - `v` key opens the full `PermissionsScreen` for multi-file diff view - Shows diff content inline when available - Emits `PermissionDecisionEvent` when a decision is made **Relationship to existing spec:** The ADR-044 spec currently describes: - `PermissionsScreen` — pushed for tool permission requests (full screen) - `QuestionWidget` — replaces the prompt during actor permission requests The implementation adds a **third pattern**: an inline widget in the conversation stream for single-file operations, with the full `PermissionsScreen` accessible via `v` key. ### Spec sections affected **ADR-044 (TUI Architecture)** — Prompt Architecture section currently says: > **QuestionWidget** — replaces the prompt during actor permission requests (allow/reject choices) This should be updated to distinguish between: - Single-file requests: inline `PermissionQuestionWidget` in conversation stream - Multi-file requests: full `PermissionsScreen` pushed **`docs/specification.md`** — The TUI section describing permission handling should be updated to document: - The inline permission question widget and its 4-decision model - The `PermissionRequestType` enum (FILE_WRITE, FILE_DELETE, FILE_READ, SHELL_EXEC, NETWORK) - The `PermissionDecision` enum (ALLOW_ONCE, ALLOW_ALWAYS, REJECT_ONCE, REJECT_ALWAYS) - The keyboard shortcuts (a/A/r/R, up/down, enter, v) - The routing logic: single-file → inline widget; multi-file → PermissionsScreen ### Proposed spec addition In the TUI section of `docs/specification.md`, add a subsection under the permission handling area: ```markdown #### Inline Permission Question Widget For single-file permission requests, the TUI renders a `PermissionQuestionWidget` inline in the conversation stream. This avoids interrupting the conversation flow for simple allow/reject decisions. The widget displays: - The actor name and requested operation type - The target file path - Four decision options with keyboard shortcuts | Key | Decision | Scope | |-----|----------|-------| | `a` | Allow once | This operation only | | `A` | Allow always | All operations this session | | `r` | Reject once | This operation only | | `R` | Reject always | All operations this session | Navigate options with `up`/`down` and confirm with `enter`, or use the single-key shortcuts directly. Press `v` to open the full `PermissionsScreen` for multi-file diff review. **Permission request types**: `file_write`, `file_delete`, `file_read`, `shell_exec`, `network`. For multi-file operations, the full `PermissionsScreen` is pushed directly (no inline widget). ``` ### Rationale The inline widget is a genuine UX improvement over the spec's original `QuestionWidget` (which replaced the prompt). Rendering inline in the conversation stream keeps context visible and is more ergonomic for single-file decisions. The 4-decision model (once/always × allow/reject) is also more expressive than a simple allow/reject. This is an implementation improvement that should be reflected in the spec. --- ## Scope | Section | Change Type | |---------|-------------| | `docs/specification.md` — TUI permission handling | Add inline widget description, decision enum, request type enum, keyboard shortcuts | | `docs/adr/ADR-044-tui-architecture-and-framework.md` — Prompt Architecture | Update QuestionWidget description to distinguish inline vs full-screen | --- **Awaiting human approval before any branch or PR is created.** --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
freemo added this to the v3.7.0 milestone 2026-04-03 06:02:10 +00:00
freemo self-assigned this 2026-04-03 16:57:58 +00:00
Author
Owner

approved

approved
Author
Owner

PR #2599 reviewed, approved, and merged.

The specification and ADR-044 have been updated to document the inline PermissionQuestionWidget for single-file permission requests, as proposed in this issue.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #2599 reviewed, approved, and merged. The specification and ADR-044 have been updated to document the inline `PermissionQuestionWidget` for single-file permission requests, as proposed in this issue. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#2178
No description provided.