Ch7. Tools, Approval, Connections

Requester, approver, and execution identity in 0.78–0.82

defineTool now uses approval. Approved calls execute with the requester's authority. Approval does not automatically transfer the approver's privileges. Workflow and agent calls also recheck requester access before dispatch.

In approval: { request: always(), response: ... }, a response policy replaces the default requester-only policy. Compare composite identity, including authenticator, principalType, and tenant, rather than principalId alone. Only server-side approval.settled or input.resolved confirms the final decision; a submission or approval.candidate event does not.

An executing defineTool may inspect ctx.approval.responder; using that person's token requires an explicit design. auto() uses a decision model and may send inputs to its provider. It does not replace authentication or authorization. Multiple already-pending requests under once() must each be resolved.

Human in the loop.

Catalog calls and real names

Use eve__search for discovery and eve__tool({ name, input }) for deferred or connection tools. A connection tool is named <connection>__<tool>. Load skills with eve__skill({ name }). Traces and evals record the resolved tool or skill rather than the catalog wrapper.

Built-in tools.

Tools are typed actions the model can request. The most important operational fact is that authored tool execute runs in the app runtime. If it can access secrets or internal APIs, treat it as privileged code.

Tool Structure

import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Return mock weather data for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});

Standards:

• description is model-facing routing text
• inputSchema is a control surface
• execute must tolerate replay and retries
• returned data may enter history and telemetry, so minimize it

Minimize Model-visible Output

Use toModelOutput when hooks/channels need rich output but the model should see only a summary.

// Spread this projection into defineTool({ ...outputProjection, ... }).
const outputProjection = {
  toModelOutput(output: { id: string; riskLevel: string }) {
    return { type: "text" as const, value: `Report ${output.id}: risk ${output.riskLevel}.` };
  },
};

This prevents CRM rows, audit payloads, pricing tables, and PII from being copied into later model context.

Approval Policy

import { defineTool } from "eve/tools";
import { always } from "eve/tools/approval";
import { z } from "zod";

export default defineTool({
  description: "Refund a customer charge.",
  inputSchema: z.object({
    chargeId: z.string(),
    amount: z.number().positive(),
  }),
  approval: always(),
  async execute(input) {
    return refundCharge(input);
  },
});

Input-based Approval

const approval = ({ toolInput }: { toolInput?: { amount?: number } }) => {
  const amount = Number(toolInput?.amount ?? 0);
  return amount > 1000;
};

Keep business policy in pure functions under agent/lib/ and unit test it. Do not hide large policy logic inside tool definitions.

HITL Is Durable Parking

When approval is required, Eve emits input.requested and parks the session in turn.waiting. The process is not held open. The session resumes when the answer arrives.

Connections

Connections expose external MCP or OpenAPI tools that you do not author.

The model discovers them through eve__search and calls qualified names.

import { defineMcpClientConnection } from "eve/connections";
import { once } from "eve/tools/approval";

export default defineMcpClientConnection({
  url: "https://mcp.linear.app/mcp",
  description: "Linear workspace: issues, projects, cycles, and comments.",
  auth: {
    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
  },
  tools: { allow: ["search_issues", "get_issue"] },
  approval: once(),
});

Tokens Stay Out Of The Model

Connection tokens are resolved in the app runtime and injected into outbound requests. They do not become model context. This is a major safety property, but scope still matters.

Tool Auth vs Connection Auth vs Route Auth

Route auth does not automatically make tool or connection scopes safe.

ask_question vs Approval

All use the same durable input.requested pause protocol, but their intent is different.

Tool Design Checklist