ToolContext
Context available during the tool hook (wraps one tool execution).
Extends TurnContext with tool-specific data and control flow methods:
deny() for soft-blocking, skipCall() for mocking, modifyArgs() for
argument transformation.
Extends
Section titled “Extends”Properties
Section titled “Properties”agent:
object
Agent definition: name, model, instructions.
instructions
Section titled “instructions”instructions:
string
model:
string
name:
string
Inherited from
Section titled “Inherited from”args:
Record<string,unknown>
Arguments from the LLM. Middleware can modify via modifyArgs().
callId
Section titled “callId”callId:
string
Tool call ID from the model response.
callIndex
Section titled “callIndex”callIndex:
number
Which tool call within this model response (0-based).
config
Section titled “config”config:
Record<string,unknown>
Middleware-specific configuration from the agent definition.
Inherited from
Section titled “Inherited from”history
Section titled “history”history:
Message[]
Canonical conversation history (append-only).
Inherited from
Section titled “Inherited from”input:
Message[]
Input messages for this turn.
Inherited from
Section titled “Inherited from”output
Section titled “output”output:
string|null
Assistant’s final text output for this turn. null until the turn completes.
Inherited from
Section titled “Inherited from”sessionId
Section titled “sessionId”sessionId:
string
Unique session identifier.
Inherited from
Section titled “Inherited from”startedAt
Section titled “startedAt”startedAt:
number
Timestamp when this turn started.
Inherited from
Section titled “Inherited from”state:
Record<string,unknown>
Session state — typed fields with optional reducers, shared across all turns.
Inherited from
Section titled “Inherited from”tool:
object
Tool definition (name, description, schema, approval flag).
description
Section titled “description”description:
string
jsonSchema
Section titled “jsonSchema”jsonSchema:
Record<string,unknown>
name:
string
requireApproval?
Section titled “requireApproval?”
optionalrequireApproval?:boolean| ((args) =>boolean|Promise<boolean>)
turnId
Section titled “turnId”turnId:
string
Unique turn identifier.
Inherited from
Section titled “Inherited from”turnIndex
Section titled “turnIndex”turnIndex:
number
Turn number within this session (0-based).
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”abort()
Section titled “abort()”abort(
reason):never
Hard-stop the turn. Throws AbortError that unwinds the entire onion stack.
Parameters
Section titled “Parameters”reason
Section titled “reason”string
Returns
Section titled “Returns”never
Throws
Section titled “Throws”Inherited from
Section titled “Inherited from”approve()
Section titled “approve()”approve():
void
Explicitly approve the tool call (reserved for future HITL flows).
Returns
Section titled “Returns”void
deny()
Section titled “deny()”deny(
reason):void
Deny the tool call. Returns an error message to the LLM so it can adapt. Does NOT throw — this is a soft failure.
Parameters
Section titled “Parameters”reason
Section titled “reason”string
Returns
Section titled “Returns”void
emit()
Section titled “emit()”emit(
event):void
Emit a stream event to the consumer.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”modifyArgs()
Section titled “modifyArgs()”modifyArgs(
newArgs):void
Replace or merge tool call arguments.
Parameters
Section titled “Parameters”newArgs
Section titled “newArgs”Record<string, unknown>
Returns
Section titled “Returns”void
registerTool()
Section titled “registerTool()”registerTool(
tool):void
Register a tool on the agent. Call in the agent hook before next().
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”skipCall()
Section titled “skipCall()”skipCall(
result):void
Skip tool execution and return a synthetic result (for mocking/testing).
Parameters
Section titled “Parameters”result
Section titled “result”Returns
Section titled “Returns”void