Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
index 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. Use
Gating 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: