docs(agents): scope tool OBO claim to plugin-toolkit tools

[MarioCadenas]

Problem

The Level 1 section of docs/plugins/agents.md (invoke-routes paragraph) claimed:

Every tool call runs through asUser(req) so SQL executes as the requesting user, file access respects Unity Catalog ACLs, and telemetry spans are created automatically.

That OBO guarantee is only true for plugin-toolkit tools. It is false for hand-rolled tool({ execute }) tools, which run as the app's service principal — a security-relevant claim for anyone wiring an ambient tool that touches user data.

Evidence (code)

Tool dispatch splits by source in packages/appkit/src/plugins/agents/tool-dispatch.ts → runToolEntry:

• case "toolkit" (tool-dispatch.ts:179) → deps.context.executeTool(runState.req, …), and executeTool wraps the call in provider.asUser(req) (plugin-context.ts:231). User identity.
• case "function" (tool-dispatch.ts:197) → entry.functionTool.execute(args) directly. No req, no asUser, no runInUserContext. Service-principal identity.

The public tool({ execute }) signature is execute: (args) => … (tools/tool.ts:49) — it receives only the validated arguments, never req, so a hand-rolled tool cannot opt into OBO even if it wanted to. The agents plugin sets up no ambient user-context ALS around the run (no asUser/runInUserContext references in agents.ts), so getWorkspaceClient() inside such a tool resolves to the SP client.

The telemetry half of the original sentence is true for all tools — traceTool (tool-dispatch.ts:142) wraps every dispatch — so that part is preserved.

Change

Rewords the one sentence to:

• Keep the "every tool call is traced" claim (accurate).
• Scope the asUser(req) / SQL-as-user / UC-ACL guarantee to plugin-toolkit tool calls.
• State that hand-rolled tool({ execute }) runs as the service principal and cannot opt into OBO.
• Point readers to execution-context.md.

Docs-only, one line changed.

Verification

• Link target ./execution-context.md confirmed to exist as a sibling; matches the doc's existing relative-link idiom (./stability.md). Both <name> occurrences are inside inline-code spans, so MDX will not parse them as JSX.
• Not run: pnpm docs:build / typecheck — this worktree has no node_modules installed and I did not install deps. Docusaurus onBrokenLinks: "throw" will validate the link in CI.

This pull request and its description were written by Isaac.