The Open Framework for Building Agents
docs(eve): Add HITL approval authz docs (#2512)
Ben Pankow428a3801730f
diff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.mdindex 785860640..aff02be0a 100644--- a/docs/tools/human-in-the-loop.md+++ b/docs/tools/human-in-the-loop.md@@ -56,6 +56,47 @@ Policies can also return `"approved"` or `"denied"` to decide automatically. UseGating a side effect on approval is also how you make non-idempotent work safe across replays: a charge or email that sits behind `always()` can't fire from a re-run step without a fresh human decision.+### Authorizing approval responses++You may also define an approval response policy that decides whether the authenticated person who selects **Approve** may approve that specific call:++```ts title="agent/tools/refund_charge.ts"+import { defineTool } from "eve/tools";+import { always } from "eve/tools/approval";+import { z } from "zod";++export default defineTool({+ description: "Refund a charge.",+ inputSchema: z.object({ chargeId: z.string() }),+ approval: {+ request: always(),+ response: ({ responder, request, response, session, auth }) => {+ // The Slack channel authenticates the responder and includes the workspace and user IDs.+ // Larger apps can look up approver membership here instead.+ const approvers = ["slack:T012AB3CD:U045EF6GH", "slack:T012AB3CD:U078JK9LM"];+ const canApprove = approvers.includes(responder.principalId);++ return canApprove+ ? { status: "allowed" }+ : { status: "rejected", reason: "This user cannot approve refunds." };+ },+ },+ async execute(input) {+ return refund(input);+ },+});+```++The `response` policy receives:++- `responder`: the authenticated principal that submitted the response, including its `principalId`, `principalType`, `authenticator`, and `attributes`. Your route or channel supplies this identity.+- `request`: the stable `requestId`, `callId`, `toolName`, and typed `toolInput` for the call being approved.+- `response`: the submitted decision. Response policies run for approval, so its current value is `{ decision: "approve" }`.+- `session`: read-only session identity and lineage: `id`, `initiator`, `parent`, and `turn`.+- `auth`: narrow `getToken(provider, options?)` and `requireAuth(provider, options?)` capabilities bound to the responder. Use these when authorization depends on a provider identity or permission; an interactive provider flow parks durably and then retries the policy.++Return `{ status: "allowed" }` to accept the approval. Return `{ status: "rejected", reason }` to leave the shared request pending so another eligible responder can approve it.+### Skipping approval for schedule-dispatched turns`session.auth.current` identifies the caller of this turn. Markdown schedules use the app principal (`authenticator: "app"`, `principalId: "eve:app"`, `principalType: "runtime"`) automatically. A `run` schedule must pass its `appAuth` to `send(...)` for the child session to use that principal. Match all three fields to skip approval for automated turns while still prompting when a person calls the same tool: