---
title: Your own tools and approvals
description: 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.
section: harness
order: 30
audience: [builder, agent]
sources: [packages/harness/examples/custom-tool.ts, packages/harness/src/types.ts, packages/harness/src/harness.ts, packages/harness/src/session.ts, docs/build-an-agent-app.md]
features: []
---

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 {#define}

`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.

```ts
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 {#approver}

```ts
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 {#policy}

| 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 {#ask}

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 {#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 {#related}

- [The permission engine](/docs/harness/permissions.md)
- [Sessions, events and cost](/docs/harness/sessions.md#events)
- [Plugins section](/docs/plugins.md), to ship tools as a reusable plugin instead
