Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/integrations/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Every other attribute is the wrapped session's. Only calls made through the wrap
| right before it is sent | `approval_consume` | the same call and arguments, and the approval id when the call waited for one |
| after the server answers | `complete` | `status` `ok`, or `error` for a result with `isError: true`; a `sha256:` commitment to the result (not the result), or the exception type and message |

`list_tools`, `list_resources` and `list_prompts` are recorded as untrusted observed input (`observe`, source `mcp:<server>/tools`, `/resources` or `/prompts`): the model reads the descriptions the server wrote, and the page the caller asked for is what is recorded. A page the signer cannot record is withheld, unless the run fails open for `mcp`, when an unreachable signer returns it with a warning; a refusal is withheld either way. A tool call or prompt that returns an `InputRequiredResult` (MCP 2.3) records each round's input requests as untrusted observed input (`observe`, source `mcp:<server>/input_required`). When the server provides a `request_state` and the call needed no human approval, it is decided and completed once, under its initial decision, when the terminal result arrives. Rounds from a server that returns no `request_state`, or for a decision that required human approval (as the signer refuses to consume a used approval), are decided and completed as separate calls per round.
`list_tools`, `list_resources` and `list_prompts` are recorded as untrusted observed input (`observe`, source `mcp:<server>/tools`, `/resources` or `/prompts`): the model reads the descriptions the server wrote, and the page the caller asked for is what is recorded (a page over half the signer's 1 MiB frame as its `sha256:` digest, as the [MCP gateway](../mcp-gateway.md) records one). The list mcp's `call_tool` makes itself, to check a result against the tool's output schema, never reaches the model and isn't recorded. A page the signer cannot record is withheld, unless the run fails open for `mcp`, when an unreachable signer returns it with a warning; a refusal is withheld either way. A tool call or prompt that returns an `InputRequiredResult` (MCP 2.3) records each round's input requests as untrusted observed input (`observe`, source `mcp:<server>/input_required`). When the server provides a `request_state` and the decision is `allow`, it is decided and completed once, under its initial decision, when the terminal result arrives. A round continues the call its own asyncio task left waiting, as `mcp.Client.call_tool` drives the rounds, so concurrent calls never share a decision even when the server returns the same `request_state` to both; a waiting call whose task calls a tool or gets a prompt on the session first is never completed ([not covered](#not-covered)). Rounds from a server that returns no `request_state`, or under a decision that isn't `allow` (a flag, or an ask, whose approval the signer consumes only once), are decided and completed as separate calls per round.

`<server>` is the name in the server's initialize result, with every character outside `A-Za-z0-9_.-` replaced by `_`
(`unknown` when the server gave none). The policy's `tools` map should map `mcp:*/*` to the `mcp` class (the coding
Expand All @@ -64,7 +64,7 @@ a lost connection) propagates unchanged. Both are recorded as `error`.

## Not covered

- MCP calls carry no call id, so every `call_tool` is a call of its own (attempt 0); multi-round input-required calls reuse their decision across rounds, while an independent retry is a new decision. A call whose later rounds never reach the session (the elicitation callback fails, or mcp's `input_required_max_rounds` runs out, both inside `mcp.Client`) stays decided and is never completed; at run close the signer records it as a signed `decided_not_completed` gap.
- MCP calls carry no call id, so every `call_tool` is a call of its own (attempt 0); multi-round input-required calls reuse their decision across rounds, while an independent retry is a new decision. A call whose later rounds never reach the session (the elicitation callback fails, mcp's `input_required_max_rounds` runs out, both inside `mcp.Client`, or the task driving it ends or makes another call on the session first) stays decided and is never completed; at run close the signer records it as a signed `decided_not_completed` gap. Rounds you drive yourself from different tasks are decided as calls of their own, so each round of an allowed call before its last is such a gap ([limits](../limits.md#approvals)).
- There is no saved state: a call waiting for an approval does not survive the process.
- Servers the agent reaches without this session (another client, a hosted MCP tool of a model provider) are not seen.
- The server's name in `mcp:<server>/<tool>` is the one the server gives. An mcp 1.x session doesn't keep it:
Expand Down
2 changes: 2 additions & 0 deletions docs/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -358,7 +358,9 @@ What Tracekit guarantees and doesn't, per deployment, on one page: [guarantees](
| **(1.5.1)** A retry uses an earlier call's T2 approval (`executor: t2`) only when its consume names it (`approval_id_hint`): without the hint it is refused `TK-APPROVAL-REQUIRED`. | The signer reads its copy of the approved arguments, which a T2 consume returns, before the writer runs, for the approval it is told. | Pass the `approval_id` that `approval_request` returned, as the shipped hooks do. | [approve, then retry](approvals.md#approve-then-retry) |
| An MCP call is named by the server's own name (`mcp:<server>/<tool>`); an mcp 1.x session whose `initialize()` ran before `tracekit.instrument()`, or one wrapped by hand without `server=`, is recorded as `mcp:unknown/<tool>`, with a warning. | The name comes from the server's initialize result, which an mcp 1.x session doesn't keep. | Call `tracekit.instrument()` before any session initializes, or pass `TracekitSession(..., server="<name>")`; write rules for server-named tools knowing the server picks its name. | [MCP](integrations/mcp.md#not-covered) |
| An adapter without saved state (MCP, Browser Use, the Claude Agent SDK hook) holds a call while waiting; the wait doesn't survive the process, and a long wait ends in a denial. | There is no resumable state to carry the approval. | Answer within the adapter's wait; use a framework with saved state for long waits. | [MCP](integrations/mcp.md#not-covered), [Claude Agent SDK](integrations/claude-agent-sdk.md#not-covered) |
| MCP: an input-required call (MCP 2.3) whose rounds are sent from different asyncio tasks (a web app that keeps the `request_state` and sends the next round in its next HTTP request) is decided again in each round, and each round of an allowed call before its last stays decided and never completed: a signed `decided_not_completed` gap at run close, one per round, counted toward the run's 100 such gaps (past them, one gap counts the rest). | A round continues only the call its own task left waiting, so two calls never share a decision, whatever `request_state` a server returns to both; a round sent from another task can't be told from a new call that reuses the state. | Drive all of a call's rounds in one task, as `mcp.Client.call_tool` does; read such a gap next to the later round with the same tool and arguments. | [MCP](integrations/mcp.md#not-covered) |
| LangGraph: code that catches exceptions around a gated `ToolNode` (a `try`/`except Exception` in a node that invokes it, a middleware outside `TracekitMiddleware` that turns exceptions into messages) ends an `ask`'s pause: the model gets an error, the call doesn't run, and its approval expires. The node's own `handle_tool_errors` and `.with_fallbacks()` let the pause through. | LangGraph pauses by raising `GraphInterrupt` out of the node; code that catches it ends the pause before LangGraph sees it. | Re-raise `langgraph.errors.GraphBubbleUp` before any broad `except`, or put the error handling in the ToolNode (`handle_tool_errors`, `.with_fallbacks()`). | [LangGraph](quickstarts/langchain.md#approvals-wire-it-by-hand) |
| LangGraph: when one model message has more than one call that asks and one `ToolNode` runs them all, as when `tools_condition` routes the message to it (a `tracekit_tool_node`, or a `ToolNode` that `tracekit.instrument()` wired), a resume can reach a call other than the one its pause showed, under `invoke` and `ainvoke` alike. Any of those calls may then be denied (`TK-APPROVAL-UNBOUND`) and never run, even after its own pause was approved. A pause may repeat one already approved, or show a call that already ran under a new approval, which runs it again once approved. A call that ran is gated again on each later resume, so the model may get a denial for a call that ran. An allowed call in the same message may run again on each resume. No asking call runs without an approval a person gave for it. | LangGraph runs the node again from its start on each resume and pairs resume values with the node's `interrupt()` calls by the order they are reached, which the node's parallel calls (threads under `invoke`, tasks under `ainvoke`) reach in no fixed order. | Give each call a task of its own: build the agent with `create_agent`, or route each call to the node with its own `Send("tools", [call])`, and resume every pending pause by its interrupt id (`Command(resume={i.id: {"approval_id": i.value["tracekit"]["approval_id"]} for i in out["__interrupt__"]})`). Or have the model make one call per message (`bind_tools(..., parallel_tool_calls=False)` on a chat model that takes it). Read the run's `tool.result` records, not the messages the model got, for what ran. | [LangChain](integrations/langchain.md#decisions) |
| A Browser Use action waits for an approval at most five sixths of Browser Use's action timeout (150 s of 180 s); then the approval is withdrawn and the action refused. | Browser Use cancels an action that outlives its timeout, approval wait included, with a misleading "dead CDP WebSocket" error. | Answer within the wait, or raise `BROWSER_USE_ACTION_TIMEOUT_S` (and the Agent's `step_timeout`) to give people longer. | [Browser Use](integrations/browser-use.md#decisions) |
| OpenAI Agents' `LocalShellTool` and `ApplyPatchTool` can't wait for an approval: an `ask` for them is refused. | The SDK gives no approval hook for them. | Allow or deny them by policy. | [OpenAI Agents](integrations/openai-agents.md#not-covered) |
| v1 approvals name the held call, not its exact arguments. | v1 approvals predate argument binding. | Use the v2 signer, which binds approvals to the exact arguments. | [laptop threat model](threat-model-laptop.md#open-problems) |
Expand Down
7 changes: 6 additions & 1 deletion docs/mcp-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ answers each request with one JSON response and keeps no session; it serves `ini
untrusted observed input (`mcp:<upstream>/tools`, `/resources`, `/prompts`): the model reads the descriptions the
upstream wrote. A tool named `prompt:...` is neither listed nor called: it would be decided as a prompt.
- An upstream that fails during a tools/call or prompts/get answers an error saying the call may have run, and the
call completes as an error.
call completes as an error. One that went away and can't be opened again answers that nothing was sent to it.

The upstreams' credentials never reach the agent or the signer: the agent's own headers are never forwarded, and each
`env` and `headers` value is cut from the decoded string values of everything the gateway answers or records (never
Expand All @@ -106,6 +106,11 @@ gateway, for the identity it decided the call for, alone; a run closed mid-call
([Kubernetes](deploy-kubernetes.md#custody)).
- Tools, resources and prompts are listed up to 100 pages from each upstream; past that,
the whole listing fails with an error naming the upstream.
- One tools/list, resources/list or prompts/list has 600 s for all the upstreams and their pages together, listed one
after another, so a slow upstream leaves less time for those after it; past that the listing fails with an error
naming the upstream it was waiting for. Opening a new session to an upstream that went away has 600 s of its own,
not capped by what is left of the listing's (the time it takes still counts against the listing), and fails naming
the upstream. A tools/call, prompts/get or resources/read has 600 s of its own.
- A resource is read through the upstream that listed it: list resources before reading one; a URI from a resource
template isn't routed.
- No server-initiated messages: sampling, elicitation, subscriptions and progress notifications from an upstream don't
Expand Down
Loading
Loading