Invocation hooks

Portable hooks apply the same policy around Harnest-owned ADK and LangGraph boundaries. From the agent root, create an observational agent hook starter:

harnest add lifecycle audit

Use --project <agent-root> when running the command from elsewhere, then choose the boundary and phase that owns the policy.

Boundary	Decorators	Typical use
Agent	`lifecycle.agent.before/after/on_error`	Request policy and accounting
Model	`lifecycle.model.before/after/on_error`	Input and output policy
Tool	`lifecycle.tool.before/after/on_error`	Tool guardrails and results
MCP	`lifecycle.mcp.before/after/on_error`	Governed remote-tool policy
HTTP	`lifecycle.http.before/after/on_error`	Routing and response-head policy

from harnest import lifecycle

@lifecycle.tool.before(order=-100)
async def check_tool(context, request):
    if context.tool_name == "delete_account":
        return context.finish({"error": "tool_disabled"})
    return context.next()

Control flow

Return context.next() to continue, optionally with a replacement value. Return context.finish(result) to end the chain with a final result. Tool, MCP, and HTTP before and after interceptors require explicit control flow. Agent and model hooks accept legacy return values, but explicit transitions keep policy readable and portable. Error hooks normally return context.next(). An MCP error hook can use finish(...) only for a recoverable provider failure; it cannot bypass approval or cancellation.

Ordering

Property	Behavior
Primary order	Lower integer `order` values run first
Tie-break	Plugin dependency/source order, then source location
Transformer	Can replace the current value
Observer	Reads an event without replacing it
Rejection	Stops work before the protected phase
Error observer	Cannot hide the original failure
Agent identity	Model hooks receive the managed agent or SubAgent performing that model call

Model hooks identify the calling agent in agent_name. User, session, and invocation IDs remain shared with the root request, including concurrent SubAgents. Keep business operations in Agent Tools. Hooks should apply policy, observation, or transformation around those operations.

Portable or native?

Requirement	Choose
Same policy on ADK and LangGraph	Portable hook
ADK runner or plugin API	ADK native integration
LangGraph middleware or graph runtime	LangGraph native integration

Native integrations

Isolate behavior that must use the selected framework directly.

Overview

Get started

Harnest Studio

Guides

API reference

Invocation hooks

Control flow

Ordering

Portable or native?

Native integrations

​Control flow

​Ordering

​Portable or native?

Native integrations

Control flow

Ordering

Portable or native?