💡 Conversational Permission Approvals: Avatar Explains Before Acting

[github-actions[bot]]

Summary

When an agent attempts a sensitive tool call (file write, shell command, computer use action, MCP tool with side effects), the avatar pauses, verbally explains in plain language what it's about to do and why, and waits for a spoken or one-click approval. Replace the dev-centric "raw JSON tool call diff" approval modal that every agentic tool ships today with a conversational, human-readable consent flow tuned for non-technical users.

Market Signal

The Claude Agent SDK exposes permission modes, hooks, and declarative allow/deny rules — the primitives are there but every consumer (Claude Code, Cursor, Windsurf) renders approvals as JSON or shell-command snippets that intimidate non-developers. As Claude Computer Use, MCP marketplaces, and autonomous loops proliferate in 2026, the gap between "agent can do anything" and "user understands what just happened" is becoming the central trust problem in agentic UX. Anthropic's own documentation calls out permission UX as a primary integration concern. No competitor targets non-technical users here.

User Signal

No direct issues yet (pre-launch), but the PRD's Sarah persona explicitly distrusts "black box" automation and the architecture document already calls out a Security bounded context with ApiKeyState and admin checks — signaling the team already views consent as a first-class concern. Discussion #65 (Avatar-Fronted Computer Use) raises the stakes: cross-app actions on a user's real desktop demand a consent layer that non-developers can actually parse.

Technical Opportunity

The SDK's permission hook system fires before tool execution and can be wired into TalkTerm's existing Security bounded context. A PermissionRequest aggregate in shared/types/domain/ carries the tool name, arguments, and a natural-language explanation generated by a lightweight Claude call ("Claude wants to delete report-draft.docx because you asked it to clean up old files. Approve?"). The avatar's TTS pipeline speaks the explanation; the existing IPC agent:* namespace gains a permission:request / permission:resolve round-trip; voice STT enables spoken "yes/no" approval via the existing VoiceSession aggregate. The Audit repository captures every approval for replay. All adapters already exist as ports — this is composition, not invention.

Assessment

Dimension	Score	Rationale
Feasibility	medium	SDK hooks exist but the explanation-generation prompt and barge-in voice approval flow need careful tuning. ~1 medium epic.
Impact	high	Becomes the defining UX differentiator vs. dev-centric competitors and unlocks safe Computer Use for non-technical users.
Urgency	high	Computer Use + MCP marketplace = trust crisis arriving fast in 2026; first to solve consent UX wins the non-technical segment.

Adversarial Review

Strongest objection: "Approval prompts will destroy flow — users will train themselves to say 'yes' to everything within a week, defeating the whole point (consent fatigue is well-documented in browser permission research)."

Rebuttal: Three mitigations make this defensible: (1) risk tiering — read-only and idempotent tools auto-approve, only destructive/external actions prompt; (2) session-scoped batch consent — "approve all file edits in this folder for this session" drops the prompt count to 1–2 per task; (3) the explanation itself is the value, not the click — even an instant approval surfaces what the agent is doing, which is what Sarah actually needs (not gatekeeping every action, but understanding them). This is closer to a screen-reader narrating actions than a UAC dialog.

Suggested Next Step

Spike on the SDK permission hook + a 50-line prompt that converts a tool call into a one-sentence plain-English explanation. Validate that latency stays under 500ms so the avatar doesn't feel laggy. Then create a product brief covering risk tiering, batch consent scopes, and integration with the Security bounded context.

---

Proposed by the BMAD Analyst (Mary) on 2026-04-07.
Workflow run