ToolInfo model + the AppTools tool/toolkit registration sub-protocol.
The vendor return type fastmcp Tool is TYPE_CHECKING-only; an in-process tool is the
framework-neutral ClientTool handle.
AppTools is the app.tools namespace of the assembled facade (tai42_contract.app).
DEFAULT_RETRYABLE_KINDS
tai42_contract.tools.retry.DEFAULT_RETRYABLE_KINDS
MAX_ATTEMPTS_CEILING
tai42_contract.tools.retry.MAX_ATTEMPTS_CEILING
NEVER_RETRYABLE_KINDS
tai42_contract.tools.retry.NEVER_RETRYABLE_KINDS
TOOL_EXTRA_IDEMPOTENCY_KEY
tai42_contract.tools.meta.TOOL_EXTRA_IDEMPOTENCY_KEY
TOOL_META_BADGES
tai42_contract.tools.meta.TOOL_META_BADGES
TOOL_META_CRASH_RESUME
tai42_contract.tools.meta.TOOL_META_CRASH_RESUME
True: a detached recorded run of this tool (a hook or trigger fire, a background submit) found
lost after a worker crash is resumed instead of left lost.
TOOL_META_HIDDEN
tai42_contract.tools.meta.TOOL_META_HIDDEN
True: the tool declares itself hidden; the tool listing reports the declaration.
TOOL_META_PAUSES
tai42_contract.tools.meta.TOOL_META_PAUSES
True: this tool can pause — it can return a park signal (SuspendedInteraction or
ResumeBuffered) because it parks, asks, or waits on a participant out of band. A tool without it never pauses.
AppTools
tai42_contract.tools.AppTools
Members
tool_title
tai42_contract.tools.AppTools.tool_title
func.
Parameters
get_tool
tai42_contract.tools.AppTools.get_tool
key.
Parameters
has_tool
tai42_contract.tools.AppTools.has_tool
key, answered by a lookup of that one name.
Parameters
get_tools
tai42_contract.tools.AppTools.get_tools
get_client_tools
tai42_contract.tools.AppTools.get_client_tools
names (all when None) as framework-neutral handles; an unknown name raises.
Parameters
run_tool
tai42_contract.tools.AppTools.run_tool
key with arguments and return its result.
offload_sync runs a synchronous tool body off the event loop in a worker thread.
continues_chain is an in-process seam keyword ONLY (no request model, MCP
argument, or tool argument sets it): when given, the dispatch’s call frame SETS
the ambient call chain to it rather than pushing key, so a continuation
runner restores a parked run’s chain on the one dispatch that resumes it.
extras is likewise an in-process seam keyword ONLY (no request model, MCP
argument, or tool argument sets it): the mapping a door carries into the run it
starts. It is set on the dispatch’s call frame — ambient and read-only for THAT
frame, so the started tool reads it through extras and every nested frame
starts empty. A visit checks the keys against the target’s declaration before the
run; None binds an empty mapping.
Parameters
extras
tai42_contract.tools.AppTools.extras
extras mapping the current run was started with (empty when none).
A door carries author-configured extras into a run; a tool reads the keys it declared
(@app.tools.tool(extras_keys=...)) here. The mapping is read-only and scoped to the
started target’s own frame — every nested dispatch reads an empty mapping, so nothing leaks
down. No request model, MCP argument, or tool argument can set it.
declared_extras
tai42_contract.tools.AppTools.declared_extras
extras keys tool name is declared to read (empty when it declares none).
A preset inherits its base tool’s declared keys. The visit checks a door’s extras against
this set before starting the target and refuses an undeclared key.
Parameters
pauses
tai42_contract.tools.AppTools.pauses
key can return a park signal.
The tool registered under key declares TOOL_META_PAUSES, or it is an extension
branch whose base declares it or whose extension stack holds an extension registered
with pauses=True, or it is a preset (transformed tool) whose parent_tool chain
reaches such a tool. An unknown name answers False (its own dispatch surfaces the
not-found). A dispatch of a tool that answers False and returns a park signal is
refused with UndeclaredPauseError.
Parameters
remove_tool
tai42_contract.tools.AppTools.remove_tool
name.
Parameters
surface_generation
tai42_contract.tools.AppTools.surface_generation
get_tools/get_client_tools keys the cache on it.
register_tool_info
tai42_contract.tools.AppTools.register_tool_info
name’s extension combos, attaching each combo stack to the base.
Parameters
unregister_tool_info
tai42_contract.tools.AppTools.unregister_tool_info
name.
Parameters
unregister_tool_base
tai42_contract.tools.AppTools.unregister_tool_base
tool_name and return the names removed.
Parameters
tool_refs_extractor
tai42_contract.tools.AppTools.tool_refs_extractor
name registered, or None when it declared none.
Parameters
template_refs_extractor
tai42_contract.tools.AppTools.template_refs_extractor
name registered, or None when it declared none.
Parameters
kwargs_template_refs
tai42_contract.tools.AppTools.kwargs_template_refs
tool with kwargs names, one TemplateRef per id.
site is the place inside kwargs (system_prompt, subagents[0].system_prompt), in the
walk’s order; [] when the blob names none. A tool the registry does not serve names nothing:
[], as the platform’s delete referees read a stored call of it; the call itself fails where it
runs. Reads the ids with the same walk the platform’s write check and delete referees run. Raises
ValueError naming the place, quoting no value, for a blob the tool’s input refuses, and
RuntimeError for a fault of a declared tool_refs or template_refs extractor.
Parameters
register_rename_referee
tai42_contract.tools.AppTools.register_rename_referee
ToolRenameReferee consulted before a tool rename.
A plugin holding tool-name references calls this through the tai42_app
handle when its module loads. Every registered referee is asked once, with the
old name and every extension branch tool bound off it together, on a rename and
on the rename preview; it answers holders keyed by asked name and has no side
effect. Any holder blocks the rename and the holders are named. Registering
the same provider object twice raises loudly — a double registration is a
plugin bug, never a silent duplicate consult. Re-keying what the plugin holds under
the name belongs in a rename cascade (register_rename_cascade).
Parameters
register_rename_cascade
tai42_contract.tools.AppTools.register_rename_cascade
ToolRenameCascade run when a preset rename proceeds.
A plugin holding records keyed by a preset/tool name calls this through the
tai42_app handle when its module loads. A cascade is called once for each tool
the rename moves (the preset, then each extension branch tool bound off it), with
that tool’s old and new name, only after every veto and guard has passed and the
new name is bound, before the old name is torn down; a cascade raising fails the
rename and undoes it. Registering the same provider object twice raises loudly — a
double registration is a plugin bug, never a silent duplicate re-key.
Parameters
rename_cascades
tai42_contract.tools.AppTools.rename_cascades
ToolRenameCascade, in registration order.
register_delete_referee
tai42_contract.tools.AppTools.register_delete_referee
ToolDeleteReferee consulted before a preset delete.
A plugin holding resources keyed on a preset/tool name calls this through the
tai42_app handle when its module loads. Every registered referee is asked once,
with every tool the delete removes together — the preset and every extension branch
tool bound off it — on a delete and on the delete preview; it answers holders keyed
by asked name and has no side effect. Any holder VETOES the delete and the holders
are named. Cleanup belongs in a delete cascade (register_delete_cascade).
Registering the same provider object twice raises loudly — a double registration is
a plugin bug, never a silent duplicate consult.
Parameters
register_delete_cascade
tai42_contract.tools.AppTools.register_delete_cascade
ToolDeleteCascade run when a preset delete proceeds.
A plugin holding resources keyed on a preset/tool name calls this through the
tai42_app handle when its module loads. A cascade is called once for each tool
the delete removes (the preset, then each extension branch tool bound off it), with
that tool’s name, only after every veto and guard has passed and before the record
is removed; a cascade raising fails the delete. Registering the same provider object
twice raises loudly — a double registration is a plugin bug, never a silent
duplicate cleanup.
Parameters
delete_cascades
tai42_contract.tools.AppTools.delete_cascades
ToolDeleteCascade, in registration order.
register_detach_referee
tai42_contract.tools.AppTools.register_detach_referee
StateTemplateDetachReferee consulted before a state-template detach.
A holder of door bindings that name templates (e.g. per-node state bindings, or the
platform’s own preset/route/hook/schedule bindings) calls this through the
tai42_app handle when its module loads. Every registered referee is asked for the
(state, template) on a detach and on the detach preview; it answers holders and
has no side effect. Any non-empty answer blocks the detach and the holders are named.
Registering the same provider object twice raises loudly — a double registration is a
bug, never a silent duplicate consult.
Parameters
register_tier
tai42_contract.tools.AppTools.register_tier
base_tool’s registration tier (a RouteAction).
The authorization character enforced everywhere the tier is consulted.
A fenced or secret tier gates BOTH authoring a preset over the base tool
(admin-only) AND running the tool: a fenced/secret tool runs only for an
administrator, at every execution door, and a preset authored over it inherits
that fence at run time. read/write carry no execution gate. This is the
programmatic form of @app.tools.tool(tier=...); both write the one shared
registry (also read on the authoring side as app.presets.registration_tier).
One declaration per base tool; a duplicate raises loudly.
Parameters
tier
tai42_contract.tools.AppTools.tier
base_tool declared, or None when it declared none.
None means no execution fence; authoring keeps the presets’ default write action.
Parameters
ClientTool
tai42_contract.tools.ClientTool
name is the full registered name (never truncated); input_schema is the JSON Schema of
the arguments, the schema the MCP edge advertises. invoke returns the tool’s value with
secrets masked, or a SuspendedInteraction / ResumeBuffered (by type, unadapted) when a
tool that declares it can pause parked; it raises ClientToolError for a failure the
model should see (the body raised, a driver reached a FAILED terminal, the result cannot be
JSON-encoded, the arguments do not validate), and raises every other error raw (tier refusal,
authorization, unknown or vanished tool, a park signal from a tool that does not declare it can
pause — UndeclaredPauseError — cancellation).
Members
name
tai42_contract.tools.ClientTool.name
description
tai42_contract.tools.ClientTool.description
input_schema
tai42_contract.tools.ClientTool.input_schema
invoke
tai42_contract.tools.ClientTool.invoke
arguments.
Parameters
ClientToolError
tai42_contract.tools.ClientToolError
ComposedToolRef
tai42_contract.tools.ComposedToolRef
site is the base tool’s own words for where the name sits (None when the place has no
inner position); tool_kwargs is the kwargs that place passes to the composed tool, as
stored (None when the config passes none).
Attributes
NestedDoorFrameError
tai42_contract.tools.call_frame.NestedDoorFrameError
tool_call_frame was opened on a non-fresh run context.
A door frame is the outermost minting frame of a run: it opens only when no run is already in
flight in the current context. This is raised when the door’s task inherited a running run’s
ambient context — a non-empty call chain, or an already-bound run-delivery context — which
means the task was spawned as a new root of execution WITHOUT a fresh context. Minting the
run’s delivery identity under an inherited one would key the new run’s terminal to the caller’s
run instead of to the door’s own completion, so the frame refuses to open.
ReferenceHolder
tai42_contract.tools.ReferenceHolder
kind is the holder’s kind ("hook", "preset version"; a plugin declares its own),
tag the feature tag the holder’s own doors are registered under (the tag a role’s grant
map names), name the holder’s own name, locator the fields that place the reference
inside the holder (a version, a node id), and summary the line a person reads. A caller
whose role may not read tag reads the holders of one kind as a single count holder:
kind and tag as above, name the tag, locator only count, and a summary
that names no holder.
Attributes
RunDelivery
tai42_contract.tools.call_frame.RunDelivery
run_delivery_id is the uuid4 minted once at the outermost run start,
shared by every nested dispatch, sibling branch, and re-park of the run so
its single terminal delivers once. delivery is the DeliveryAddress
the starting door bound as the run’s completion address, or None when the
door has no receiver.
Attributes
StateTemplateDetachReferee
tai42_contract.tools.StateTemplateDetachReferee
TemplateDeleteReferee
tai42_contract.tools.TemplateDeleteReferee
TemplateRef
tai42_contract.tools.TemplateRef
site is the base tool’s own words for the place, printed as given.
Attributes
TemplateRefsExtractor
tai42_contract.tools.TemplateRefsExtractor
ToolAlreadyRegisteredError
tai42_contract.tools.ToolAlreadyRegisteredError
ToolDeleteCascade
tai42_contract.tools.ToolDeleteCascade
ToolDeleteReferee
tai42_contract.tools.ToolDeleteReferee
ToolInfo
tai42_contract.tools.ToolInfo
name is the registered key; base is the underlying tool it was
bound from (a branch tool names itself, e.g. name_chain).
Attributes
ToolInvocation
tai42_contract.tools.invocation.ToolInvocation
tool_name is the invoked tool’s registered name. Frozen — a deposited invocation is a
fact of the active execution, never mutated in place.
state_binding is the OPTIONAL door-layer binding a door deposits when it
initiates a run (a channel route, a schedule fire, a hook, or none for a bare
run-tool call): it rides the ambient context to the shared dispatch chokepoint,
which carries it forward across its own re-deposit and merges it with the
dispatched preset’s own binding before applying it around the run. The contract
interprets nothing about it — a logic-free carrier.
Attributes
ToolRefsExtractor
tai42_contract.tools.ToolRefsExtractor
ToolRenameCascade
tai42_contract.tools.ToolRenameCascade
ToolRenameReferee
tai42_contract.tools.ToolRenameReferee
ToolRetryBackoff
tai42_contract.tools.retry.ToolRetryBackoff
n waits min(cap_seconds, initial_seconds * multiplier**(n-1)) before attempt
n+1. A server-provided retry_after on the failed attempt’s error WIDENS the wait when
it asks for longer (the medium’s own ask wins, even past the cap — the cap bounds the
platform’s growth, not the server’s explicit request).
Attributes
ToolRetryPolicy
tai42_contract.tools.retry.ToolRetryPolicy
max_attempts is the TOTAL attempt budget, first attempt included
(1 = no retry, just per-attempt monitoring). idempotent is the
author’s explicit claim that re-firing the body is safe — REQUIRED, and a
retrying policy (max_attempts > 1) without it is rejected (the
double-send guard).
retryable is the classification door — an explicit allowlist, never a
blanket:
True— retry theDEFAULT_RETRYABLE_KINDS;- a tuple of
ErrorKind— retry exactly those kinds (NEVER_RETRYABLE_KINDSare rejected at declaration); False— no kind-based retry at all.
retryable verdict (the
ChannelDeliveryError shape) wins in BOTH directions: True admits it
even off-list, False vetoes it even on-list — the raiser knows its
failure better than any kind bucket. An error with neither a verdict nor an
allowlisted kind is never retried.
Attributes
UndeclaredPauseError
tai42_contract.tools.meta.UndeclaredPauseError
TOOL_META_PAUSES returned a park signal.
Stamped unknown: no member of the taxonomy names a registration fault, and unknown
is never retryable, so no retry policy re-fires the tool body whose park already happened.
Attributes
current_call_chain
tai42_contract.tools.call_frame.current_call_chain
current_extras
tai42_contract.tools.call_frame.current_extras
current_tool_invocation
tai42_contract.tools.invocation.current_tool_invocation
None when no tool is executing.
get_run_delivery
tai42_contract.tools.call_frame.get_run_delivery
None when receiver-less or unbound.
get_run_delivery_id
tai42_contract.tools.call_frame.get_run_delivery_id
None outside a bound run.
reset_current_tool_invocation
tai42_contract.tools.invocation.reset_current_tool_invocation
token.
token is the return value of the matching set_current_tool_invocation call.
Parameters
run_delivery
tai42_contract.tools.call_frame.run_delivery
completion_id and a re-park inside stores the same pair. The
chokepoint binds the interaction’s stored RunDelivery here BEFORE the drive, so the
resume’s outermost tool_call_frame finds one already ambient and does NOT re-mint.
None binds nothing (a run that stored no delivery context). ContextVar token discipline:
reset in the finally.
Parameters
set_current_tool_invocation
tai42_contract.tools.invocation.set_current_tool_invocation
invocation as the in-flight tool for the current context.
Pass the returned token to reset_current_tool_invocation to restore the previous
value. Nested deposits (a tool invoking another) re-set for the inner call and restore the
outer value on reset — ContextVar token discipline.
Parameters
tool_call_frame
tai42_contract.tools.call_frame.tool_call_frame
finally.
Parameters

