From e05cc4a18d4317284b3b156bee3ae95e2ddd2775 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Wed, 14 Oct 2026 18:08:45 -0500 Subject: [PATCH] docs(plugin): document permission assert and fix session rules example (#55526) --- .../src/docs/content/build/plugins/index.mdx | 28 ++++++++++++++++++- services/www/src/docs/content/tools.mdx | 4 +-- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/services/www/src/docs/content/build/plugins/index.mdx b/services/www/src/docs/content/build/plugins/index.mdx index 06ff5174812..80705a86f94 100644 --- a/services/www/src/docs/content/build/plugins/index.mdx +++ b/services/www/src/docs/content/build/plugins/index.mdx @@ -738,6 +738,32 @@ const review = await ctx.generate.text({ ### Permissions +Ask for permission before performing an action. `assert` evaluates the session's [permission rules](/permissions), +including saved approvals, and prompts the user when a rule resolves to `ask`. It resolves once the action is allowed. + +```ts +execute: async (input, context) => { + await ctx.permission.assert({ + sessionID: context.sessionID, + agent: context.agent, + source: { type: "tool", messageID: context.messageID, id: context.id }, + action: "deploy", + resources: [input.environment], + save: [input.environment], + }) + return { content: await deploy(input.environment) } +} +``` + +- `action` and `resources` are matched against the rules. Any `deny` blocks the action; otherwise any `ask` prompts. +- `save` lists the patterns stored when the user chooses to always allow. +- `agent` selects whose rules apply and defaults to the session's agent. `source` attaches the prompt to a tool call. +- `metadata` passes extra detail to permission prompts and `evaluate` hooks. + +A deny rule or a rejection with feedback rejects with a `Tool.Error` that carries the reason, so the model sees it and +continues. A plain rejection ends the current step. Let these errors propagate rather than returning them as tool +output. + Inspect or resolve pending permission requests. ```ts @@ -750,7 +776,7 @@ Replace the session-scoped permission rules. They are evaluated after the agent' last matching rule wins. Child sessions inherit the rules in effect when they are created. ```ts -await ctx.permission.rules({ +await ctx.session.update({ sessionID, permissions: [{ action: "edit", resource: "/path/to/original/checkout/**", effect: "deny" }], }) diff --git a/services/www/src/docs/content/tools.mdx b/services/www/src/docs/content/tools.mdx index 884119a2908..5cde00bf60a 100644 --- a/services/www/src/docs/content/tools.mdx +++ b/services/www/src/docs/content/tools.mdx @@ -214,8 +214,8 @@ Read package.json and README.md in parallel, then return their relevant setup de The runtime has no direct filesystem access, imports, timers, or `fetch`; it can only call tools in its catalog. Permission `execute` with resource `*` controls -whether Code Mode is available. Every nested tool still enforces its own -permission. +whether Code Mode is available. Nested built-in and MCP tools still enforce +their own permissions, and plugin tools enforce the permissions they assert. ### Sessions