[Dante-dan]

Branch strategy

• Active development targets main.

What this PR does

Before this PR:
The Tool Approval reference describes persistent MCP decisions without distinguishing the built-in Agent delegation tools. Scheduled coordinators can mistake Full Access or MCP auto-approval for authorization to send to another Session.

After this PR:
The reference explains that session_send and session_create retain live per-call approval, including same-Agent destinations and scheduled turns with reuse_session. It describes a manual notification/interactive handoff and links the existing deliberate security ceiling and runtime completion return path.

Refs #21359 (documentation alternative only; unattended preauthorization remains an open feature request).

Why we need it and why it was done in this way

The following tradeoffs were made:
Keep the existing security contract and cross-link its detailed design instead of introducing a one-off delegation bypass. Notification recipients must already be configured; the described handoff does not automate Session routing.

The following alternatives were considered:
Changing the tool to auto-approved would contradict the current live-approval ceiling and its ancestry, cycle, and budget requirements. Repeating the full runtime design here would create a second source of truth.

Links to places where the discussion took place: #21359, #21305, #18898; merged #18865 established the current policy.

Breaking changes

None. Documentation only; no permission behavior changes.

Special notes for your reviewer

• Source trace covers the built-in policy registry, Claude guards, Pi approval extension, and autonomy tool authorization. The reported Windows 11 runtime scenario was not reproduced.
• pnpm check --plan selected format and docs only, with no test project.
• pnpm check could not run its selected tasks: sandbox denied installation of pinned pnpm 12.6.0 into the user's package-manager directory (EPERM). Existing Node 24.12.0/dependencies were used to run the repository's four docs scripts directly: links, structure, frontmatter, and generated index all passed. git diff --check passed. Oxfmt excludes Markdown by repository configuration (zero matched files).
• Local signed commit and DCO sign-off verified; GitHub signature verification checked after push.

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

• Branch: This PR targets main
• PR: The PR description is expressive enough and will help future contributors
• Code: Write code that humans can understand and Keep it simple
• Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
• Upgrade: Impact of this change on upgrade flows was considered and addressed if required
• Documentation: A user-guide update was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior.
• Self-review: I have reviewed my own code (e.g., via /gh-pr-review, gh pr diff, or GitHub UI) before requesting review from others

Release note

NONE

[cherry-ai-bot]

No confirmed findings in the 26-line documentation change at 274aad406d4c0a3a6babcf7b4b2eec194ab122e0. The delegation approval, headless denial, notification, and completion-return guidance matches the inspected implementation and existing security contract. This supports approval; future unattended preauthorization remains a separate product decision.

Captured head checks succeeded for basic-checks, render-test, general-test, repository-checks, changes, and release classification; other checks were skipped. Legacy status has no contexts, and frozen merge CI is unavailable because the base parent differs. Review was static: no local tests or runtime reproduction; CI logs were unavailable.

Cherry Review · Passed

no findings

[cherry-qa]

QA note — no functional change, skipping local testing

This PR contains no product/runtime change — every changed file is documentation, CI/automation, repository config, or test-only:

• docs/references/ai/tool-approval.md

Per QA policy, PRs like this are not tested locally: there is no user-facing behaviour to exercise, and the CI gate covers what is touched here. This is not a judgement on the change itself.

If a functional change is actually mixed in (or you want the diff re-checked), say so here and I will re-classify it and run the targeted regression cases.

Reported by QA (cherry-ai-bot). Evidence: file list from the GitHub API; no local run performed by design.