Skip to content

spec(runner): add Tool Permission Model for ExitPlanMode HITL#1586

Draft
quay-devel wants to merge 5 commits into
ambient-code:mainfrom
quay-devel:fix/1583-tool-permission-spec
Draft

spec(runner): add Tool Permission Model for ExitPlanMode HITL#1586
quay-devel wants to merge 5 commits into
ambient-code:mainfrom
quay-devel:fix/1583-tool-permission-spec

Conversation

@quay-devel
Copy link
Copy Markdown
Contributor

Summary

  • Adds a new Tool Permission Model section to specs/agents/runner.spec.md documenting the runner's pre-approval security model
  • Introduces a two-tier tool classification: Tier 1 (allowlist-only, 22 tools) for autonomous execution, Tier 2 (HITL halt) for tools requiring user interaction
  • Specifies that ExitPlanMode SHALL halt the event stream and wait for user approval — same mechanism as AskUserQuestion — rather than auto-approving
  • Includes formal requirements with Given/When/Then scenarios for allowlist completeness, plan approval halt, and no-hang guarantee for unknown prompts
  • References SDK mechanisms (can_use_tool, PermissionRequest hooks) as implementation paths
  • Adds two Design Decisions table entries explaining the rationale

Addresses #1583 — this is the spec side. Implementation PR to follow.

Test plan

  • Verify spec section flows naturally between "MCP Servers" and "System Prompt Construction"
  • Verify Tier 1 tool table covers all Claude Code built-in tools meaningful in headless environments
  • Verify Tier 2 HITL halt mechanism is consistent with existing AskUserQuestion behavior in BUILTIN_FRONTEND_TOOLS
  • Verify requirements use proper Given/When/Then format consistent with other specs
  • Verify Design Decisions entries match existing table format

🤖 Generated with Claude Code

…e#1583

Documents the runner's pre-approval security model and introduces a
two-tier tool classification: Tier 1 (allowlist-only) for autonomous tools,
Tier 2 (HITL halt) for tools requiring user interaction (AskUserQuestion,
ExitPlanMode). Includes formal requirements with scenarios for allowlist
completeness, plan approval halt, and no-hang guarantee.

Closes ambient-code#1583

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 14, 2026

Important

Review skipped

Draft detected.

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b4b5eed7-259f-433d-ad9d-f6f59715da4f

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
✨ Simplify code
  • Create PR with simplified code

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

Comment @coderabbitai help to get the list of available commands and usage tips.

@netlify
Copy link
Copy Markdown

netlify Bot commented May 14, 2026

Deploy Preview for cheerful-kitten-f556a0 canceled.

Name Link
🔨 Latest commit 6d006bd
🔍 Latest deploy log https://app.netlify.com/projects/cheerful-kitten-f556a0/deploys/6a05c880ada2ec0008a24df4

quay-devel and others added 4 commits May 14, 2026 13:00
The spec defines desired state — no need to apologize for it. Removed
the blockquote callout and simplified the status header.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Issue reference lives in the PR and commit message, not the spec body.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Drop formal requirements/scenarios, compress tool table to inline list.
Section is now ~30 lines, proportionate with other sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant