docs(plugins): say native-tool agents keep launch-time tools until the reopen

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
paseo-bot[bot]
2026-11-18 10:54:21 +00:00
co-authored by Claude Opus 5.5
parent b3eb076539
commit 1f00a8115b
+6 -6
View File
@@ -496,12 +496,12 @@ tool or another plugin's tool on the same agent fails the session open and names
A duplicate name within one plugin also fails the session open. Agents the callback does not
target are unaffected.
| Change | When the agent receives it |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Start, stop, or reload a plugin declaring `agent.open.before` | Open sessions become stale. Each reopens before its next idle prompt; a running turn continues without interruption. The next prompt after that reopen reuses the session. Until then, a restarted plugin's tools stay available over the agent's MCP: Paseo reruns only that plugin's callback with the session's open request, with `reason: "refresh"`, and keeps the tools it returns. If that callback throws or times out, Paseo does not rerun it for the same plugin instance; the next restart tries again. If one of those tools collides with a Paseo tool or another plugin's tool, that plugin's tools stay off until the reopen, which fails with the collision. |
| Change which agents the callback targets | Run `paseo plugin reload agent-tools` after editing this example, then send the agent a prompt when it is idle. |
| Apply immediately | Call `await paseo.agents.ref(id).reload({ requestId: "reload-notes" })`. `requestId` is optional. This reopens the provider session, reruns hooks with `reason: "refresh"`, and interrupts a running turn. |
| Read the current snapshot | Call `await paseo.agents.ref(id).refresh()`. This reads state without reopening the session. |
| Change | When the agent receives it |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Start, stop, or reload a plugin declaring `agent.open.before` | Open sessions become stale. Each reopens before its next idle prompt; a running turn continues without interruption. The next prompt after that reopen reuses the session. Until then, a restarted plugin's tools stay available over the agent's MCP: Paseo reruns only that plugin's callback with the session's open request, with `reason: "refresh"`, and keeps the tools it returns. If that callback throws or times out, Paseo does not rerun it for the same plugin instance; the next restart tries again. Agents that receive Paseo tools natively (OpenCode with the bridge, OMP) keep their launch-time tools until the reopen, so a restarted plugin's tools fail for them until then. If one of those tools collides with a Paseo tool or another plugin's tool, that plugin's tools stay off until the reopen, which fails with the collision. |
| Change which agents the callback targets | Run `paseo plugin reload agent-tools` after editing this example, then send the agent a prompt when it is idle. |
| Apply immediately | Call `await paseo.agents.ref(id).reload({ requestId: "reload-notes" })`. `requestId` is optional. This reopens the provider session, reruns hooks with `reason: "refresh"`, and interrupts a running turn. |
| Read the current snapshot | Call `await paseo.agents.ref(id).refresh()`. This reads state without reopening the session. |
If an automatic reopen fails, the triggering prompt fails with that error. See the
[complete agent-tools example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools).