Skip to content
Docs menu

Your own tools and approvals

Give the agent app-specific tools with defineTool, decide every permission ask in your own code, and see how the permission engine treats your tools.

View .md

Most apps need the agent to reach their own data: look up a customer, read a ticket, draft a message. You add those as tools in a pi extension passed to createSession({ extensions }), and you answer the permission engine's asks with an approve callback.

Define a tool

defineTool and Type are re-exported from @venom/harness (the pinned copies the harness runs on), so schema types line up without depending on pi or typebox.

import { type Approver, createHarness, defineTool, type InlineExtension, provider, Type } from "@venom/harness";

const lookupAccount = defineTool({
  name: "lookup_account",
  label: "Lookup account",
  description: "Read a debtor account by id (e.g. A-1042): balance, due date, contact preferences, notes.",
  promptSnippet: "lookup_account: read an account by id",
  parameters: Type.Object({ id: Type.String() }),
  annotations: { readOnlyHint: true },          // allowed in every mode, never asks
  async execute(_toolCallId, { id }) {
    const account = await db.accounts.get(id);
    return { content: [{ type: "text", text: JSON.stringify(account) }], details: undefined };
  },
});

const sendReminder = defineTool({
  name: "send_reminder",
  label: "Send reminder",
  description: "Send a payment reminder email for an account. Requires approval.",
  promptSnippet: "send_reminder: email a payment reminder",
  parameters: Type.Object({ id: Type.String(), body: Type.String() }),
  async execute(_toolCallId, { id, body }) {
    await mailer.sendReminder(id, body);
    return { content: [{ type: "text", text: `queued reminder for ${id}` }], details: undefined };
  },
});

const tools: InlineExtension = {
  name: "collections-tools",
  factory: (pi) => {
    pi.registerTool(lookupAccount);
    pi.registerTool(sendReminder);
  },
};
defineTool field Purpose
name the id the model calls and rules name (deny: ["send_reminder"])
label a short human label
description what the model reads to decide when to call it
promptSnippet the one-line entry in the system prompt's tool list
parameters a typebox schema; the arguments are typed from it
annotations.readOnlyHint true makes the tool allowed in every mode, plan included
execute(toolCallId, args, …) returns { content: [...], details }; throw to report an error to the model

Register tools once per session in factory. Keep the tool list the same for the whole session: a changing list breaks the model server's prompt cache.

Answer the asks

const approve: Approver = async (req) => {
  if (req.tool === "send_reminder") {
    const ok = await approvals.requestFromHuman({ tenant, summary: req.summary, input: req.input }); // your UI
    return ok ? { action: "allow-once" } : { action: "deny", feedback: "The collector rejected this reminder." };
  }
  return { action: "deny", feedback: `${req.tool} is not part of this workflow` };
};

const harness = createHarness({
  cwd: workspace,
  mode: "default",
  approve,
  provider: provider.providerOptionsFromEnv(process.env),
  rules: { deny: ["web_fetch", "web_search", "bash(curl:*)", "bash(wget:*)"] },
  sandboxNetwork: false,
  compat: false,
});
const session = await harness.createSession({ extensions: [tools] });

The approver is called only when the policy says "ask". Without one, every ask is denied with a reason the model reads. Approvals are serialized per harness, subagents included, so your UI sees one request at a time per harness.

The ApprovalRequest it receives:

Field Meaning
tool tool name (bash, edit, send_reminder, mcp__server__tool)
input the call's arguments
summary a one-line description, for your UI
reason why the policy asks
mode, cwd the harness's mode and workspace
suggestions rules that would allow similar calls
rules what "allow always" stores: one rule per segment of a compound command that asked. Show them all; when empty, offer only "allow once"
toolCallId, parentToolCallId pi's id of the call; for a subagent's call, the parent's task call

The decision:

action Effect
allow-once this call only
allow-session remember the request's rules (or the rule / rules you return) for this harness
allow-project also write them to the project's permission file
deny refuse; feedback is shown to the model so it can change course

denyApprover is the default approver; nonInteractiveHint(tool) returns the text a headless denial gives the model (for an MCP tool, the exact allow rules that would let it run).

How the engine treats your tools

Your tool default, accept-edits plan yolo
annotations: { readOnlyHint: true } allowed allowed allowed
anything else asks your approve denied allowed
named by a deny rule denied denied denied
named by an ask rule asks asks asks
named by an allow rule allowed denied unless read-only allowed

Rules are checked first: deny, then ask, then plan mode, then allow, then the read-only hint and the mode. In auto mode, a call that would ask only because of the mode goes to a classifier model instead of your approver. Every decision is a permission event and an audit record, the same as for built-in tools. Your tool's output is treated as untrusted content, like read or MCP output: the model sees it inside <untrusted_…> tags and the prompt-injection detector scans it. Put customer-provided text through your tools rather than into the prompt, so it gets the same treatment.

Ask the user a question

The built-in ask tool (ASK_TOOL, askExtension) lets the model ask the person a multiple-choice question. Hosts with a UI answer it; in a session without one the tool returns NO_ANSWER_TEXT and the model proceeds on its own judgment.

Errors

Symptom Fix
Your tool never asks, it is always denied The session runs in plan mode, or a deny rule names it
Your tool runs without asking in default It has readOnlyHint: true, or an allow rule names it
The model keeps retrying a denied call Return feedback that says what to do instead
Type errors on parameters Import Type from @venom/harness, not your own typebox copy