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.
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 |
Related
- The permission engine
- Sessions, events and cost
- Plugins section, to ship tools as a reusable plugin instead