docs(assistant): complete + harden the confirmation gate (HITL) pattern#50
Merged
Conversation
The last "operate my app" piece. Design settled with the user: middleware + convention, NOT CommandRecord fields (getRisk(id) is an external map, so the closed record stays closed). Like macros/recordSequence, the ~40-line gate ships as a PATTERN, not a package (hard-don't #2 — no god-package-of-one, no natural package home). Rewrote docs/hand-written-assistant-runtime.md Piece 1 from a sketch to a complete, SECURE implementation: - createApprovalStore — one-use tokens bound to the exact {command, params}. - confirmationGate — a dispatch wrapper returning a confirmation_required errors-as-data proposal for risky assistant calls. - Security fix that motivated the hardening: the token is minted by the RUNTIME after a human approves and NEVER returned to the model. The prior sketch's `!ctx?.approvedToken` truthiness check (any token passes) plus a hinted token-in-proposal would let the model self-approve by lifting the token from the tool result. The proposal now carries only {command, params, preview}. acture-ai-assistant skill §2 updated (trust boundary, one-use call-bound tokens, convention-not-fields / pattern-not-package). Roadmap v1.18 entry. Docs/skill only — no package, no changeset, no version bump. Claude-Session: https://claude.ai/code/session_016teVFousRsWNhiiPNpG1p9
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The last "operate my app" piece: a human-in-the-loop confirmation gate for destructive/irreversible AI dispatch (research-11 §6). Design settled with the user: middleware + convention, NOT
CommandRecordfields —getRisk(id)is an external map, so the closed record stays closed. Like macros /recordSequence, the ~40-line gate ships as a pattern, not a package (hard-don't #2 — no god-package-of-one, no natural existing package home).Changes
Rewrote
docs/hand-written-assistant-runtime.mdPiece 1 from a sketch to a complete, secure implementation:createApprovalStore— one-use tokens bound to the exact{command, params}.confirmationGate— a dispatch wrapper returning aconfirmation_requirederrors-as-data proposal for risky assistant calls.The security fix that motivated hardening it: the token is minted by the runtime after a human approves, and never returned to the model. The prior sketch's
!ctx?.approvedTokentruthiness check (any token passes) plus a hinted token-in-proposal would let the model self-approve by lifting the token from the tool result. The proposal now carries only{command, params, preview}; tokens are one-use and call-bound.acture-ai-assistantskill §2 updated (trust boundary, one-use call-bound tokens, the settled convention-not-fields / pattern-not-package decision). Roadmap v1.18.Scope
Docs + skill only — no package, no changeset, no version bump (pattern delivery, like macros).
Milestone
With this, the "operate my app" story is complete: write side (tools/MCP) + read side (resources + getState, shipped as
acture-mcp-server1.2.0/1.3.0) + HITL confirmation + macro capture + the runtime bridge.https://claude.ai/code/session_016teVFousRsWNhiiPNpG1p9