docs(agent): plan the HITL approval fix (F-024)

[mmabrouk]

What

Design-only workspace for fixing the broken human-in-the-loop (HITL) tool approval flow, QA finding F-024. No code change.

Adds docs/design/agent-workflows/projects/hitl-fix/ (README, context, research, plan, status).

The bug (F-024)

Claude harness + an Ask permission rule + a gateway tool: the permission gate fires, but the playground shows no "Run this tool? Approve / Deny" prompt. The tool-call card resolves straight to ERROR: "User refused permission to run tool" and the run auto-denies. Park → approve → resume never triggers. Separately, Pi's "Permission policy" field offers only auto/deny — no ask — so HITL is not configurable for Pi at all.

Root cause (across layers)

The renderer (ToolPart.tsx), the AI-SDK egress (stream.py emits tool-approval-request), and the cross-turn resume (HITLResponder + extractApprovalDecisions) are all correct. The break is one conflicting reply in the runner:

• On an ask gate with a human surface, HITLResponder.onPermission returns deny to "park", and attachPermissionResponder maps that to session.respondPermission(id, "reject").
• For Claude, reject produces a failed tool call ("User refused permission to run tool"), which maybeCloseTool (tracing/otel.ts) records as a tool_result {isError:true}.
• The egress projects that as tool-output-error on the same toolCallId as the approval-requested part, so the AI SDK merges and the error overwrites the approval prompt.

Park (the surface signal) and reject (the harness reply) contradict each other on the wire.

Proposed fix (smallest-correct)

• Runner: add a runner-internal park outcome; on park, do not send reject (end the turn with the tool pending), so the approval-requested part is the last word. No wire change. (Fallback B: suppress the park-induced failed tool_result in the otel layer.)
• Egress / FE: no change for the Claude path once the runner stops poisoning the wire (assertion-only tests).
• Pi: hide ask for Pi in the form now (honest, tiny); track real Pi HITL via relay enforcement (open-issues S5.2) as a follow-up.

Test plan covers runner unit + SDK egress/ingest contract + golden wire (unchanged) + live FE e2e (park → approve → resume) + a replay-test pin.

Decisions needed

See the pinned "Decision needed" comment.

https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 25, 2026 2:07pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f7c18493-90a6-4b27-b535-795ceb8cd0c0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/hitl-fix

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[mmabrouk]

🔸 Decision needed — HITL approval fix (F-024)

The bug. Claude + an Ask rule + a tool: the gate fires but the playground shows no Approve/Deny prompt — the tool resolves to ERROR "User refused permission to run tool" and the run auto-denies. Pi can't do HITL at all (only auto/deny, no ask).

Root cause (one line). The runner parks an ask gate by replying reject to the harness AND emitting the approval-request event; for Claude, reject produces a failed tool call that the egress projects as tool-output-error on the same toolCallId, overwriting the approval-requested part. The FE renderer, the egress, and the cross-turn resume are all already correct — only the runner's park reply poisons the wire.

Proposed fix. Runner: park WITHOUT sending reject (add an internal park outcome; end the turn with the tool pending), so the approval part survives to the FE. No wire change. The existing FE + egress + resume machinery then works as built.

Decision 1 — park mechanism.

• A (recommended): add a runner-internal park outcome; on park, do not reply reject (or reply the harness's cancel/defer, never reject). Clean, no wire change.
• B (fallback): keep reject, but suppress the resulting failed tool_result in the otel layer. Pattern-matchy; couples otel to the responder. Use only if A can't end the turn cleanly.

Decision 2 — Pi HITL.

• Pi-1 (recommended now): hide/grey-out ask for Pi in the form. Pi declares permissions:false and never raises a gate, so offering ask would be a lie. Honest, tiny, ships with the Claude fix.
• Pi-2 (follow-up): enforce ask for Pi's resolved tools via the relay (open-issues S5.2 — needs a turn-boundary park/resume in the relay). The only way Pi can actually gate tools. Larger; tracked separately.

The one real fork: how Pi HITL should behave (Pi-1 now vs commit to building Pi-2). The Claude fix is unambiguous (Approach A).

My recommendation: Approach A + Option Pi-1 now, with Pi-2 tracked as the real Pi HITL path.

One empirical unknown (settled by the live test in the plan): whether ending the parked turn without reject leaves Claude cleanly stopped, and whether a cold-replayed turn 2 re-raises the gate so the stored approval applies. If it doesn't, resume falls back to the runner replaying the approved tool result into the transcript.

Full design: docs/design/agent-workflows/projects/hitl-fix/ (research.md = the layer-by-layer trace; plan.md = the fix + test plan).

[mmabrouk]

lgtm