Hooks

Tools let the agent call your app. Hooks let your app hear the pipeline: the user’s transcript before the agent acts on it, dictation before it is pasted, your own tool calls before and after they execute, and a receipt when the turn finishes. With hooks, VoiceOS can become the voice front-end for an app you already built — your handler recognizes an intent, does the work in your own backend, and answers in the notch. The agent never runs. Hooks are ordinary MCP tools with reserved names (voiceos_hook_*) that VoiceOS calls with a hard deadline. They are hidden from the agent — the model can never see or invoke them.

The events

Hook	Fires	Your handler can
`transcript`	Final agent-mode input, before the agent stream opens	observe · rewrite · add context · block · answer the turn
`dictation`	Polished dictation text, just before it is pasted	observe · rewrite · consume (nothing is pasted)
`preToolUse`	Before one of your own tools executes	observe · rewrite args · deny · escalate to a confirmation
`postToolUse`	After your tool ran, before the model reads the result	observe · replace the result
`turnComplete`	Turn teardown (fire-and-forget)	observe a receipt: transcript, response, tools used

Declaring hooks

Two manifest additions: a hooks block, and the transcript permission — the grant that makes the access loud at install and at share review.

"permissions": [
  { "kind": "transcript", "scope": "agent" }
],
"hooks": {
  "transcript": { "apps": ["com.acme.desktop"] },
  "preToolUse": { "scope": "own" },
  "turnComplete": {}
}

Rules the validator enforces:

Any hook requires the transcript permission. Scope "agent" covers transcript, preToolUse, postToolUse, and turnComplete; scope "dictation" covers dictation; "all" covers both.
dictation hooks must name their apps. There is no global dictation listening — the hook fires only while one of the listed bundle ids is the frontmost app. apps is optional (but encouraged) on every other hook.
Tool taps are scoped to your own tools. scope: "own" is the only v1 value.

Users see a dedicated callout on the install sheet when a manifest declares hooks, and can switch any integration’s hooks off at any time with the Transcript access toggle on its page — without uninstalling it.

Writing handlers

defineHooks registers the reserved tools on your MCP server:

import { defineHooks } from "@voiceos/integration-sdk";

defineHooks(server, {
  async transcript({ transcript, frontmostApp }) {
    if (!looksLikeOrderIntent(transcript)) return {}; // continue untouched
    const order = await createDraftOrder(transcript);
    return {
      decision: "handled",
      responseText: "Draft order created.",
      view: { blocks: [orderCard(order)] }, // glance blocks, widget allowed
    };
  },

  async preToolUse({ toolName, args }) {
    if (toolName === "delete_records" && args.count > 100) {
      return { requireConfirmation: true, reason: "Deletes over 100 records." };
    }
    return {};
  },
});

Every handler receives one typed input object and returns the same envelope:

interface HookResult {
  decision?: "continue" | "block" | "handled"; // default "continue"
  updatedText?: string;        // transcript / dictation rewrite
  updatedArgs?: object;        // preToolUse arg rewrite
  updatedResult?: unknown;     // postToolUse result replacement
  additionalContext?: string;  // transcript: extra context for the model
  requireConfirmation?: true;  // preToolUse: escalate to a user card
  responseText?: string;       // shown in the notch when handled/blocked
  view?: { blocks: unknown[] }; // notch card when handled (glance contract)
  reason?: string;             // logged, never shown to the model
}

Returning {} — or nothing — means “continue untouched”.

Deadlines and fail-open

Hooks are called with a hard budget, shared across every subscribed integration, and always fail open: a handler that is slow, broken, or disconnected behaves exactly like no handler at all.

Event	Budget	On timeout
`dictation`	250 ms	the original text is pasted
`transcript`	500 ms	the turn proceeds unmodified
`preToolUse` / `postToolUse`	2 000 ms	the tool runs / result passes through
`turnComplete`	not awaited	—

Keep handlers fast. Do the quick check inline; kick real work to your own backend and return.

What hooks can never do

Approve anything. requireConfirmation is one-way: a hook can add a confirmation, never remove, soften, or answer one. The user’s per-tool lock pills always win.
See other apps’ tools. v1 tool taps cover your own tools only.
Outlive the user’s consent. The Transcript access toggle silences every hook of an integration instantly, and hooks stripped of the transcript permission never load at all.

Review

Published integrations that declare hooks get extra scrutiny in the automated share review: transcripts forwarded beyond your stated purpose, or a listening app that doesn’t present itself as one, are rejection criteria. Say what you listen for in your summary — an app that hears the user should read like one.

Get started

Building blocks

Custom widgets

Ship it

Reference

The events

Declaring hooks

Writing handlers

Deadlines and fail-open

What hooks can never do

Review

​The events

​Declaring hooks

​Writing handlers

​Deadlines and fail-open

​What hooks can never do

​Review

The events

Declaring hooks

Writing handlers

Deadlines and fail-open

What hooks can never do

Review