docs(plugin): document permission assert and fix session rules example (#55526)

This commit is contained in:
Aiden Cline
2026-10-14 18:08:45 -05:00
committed by GitHub
Unverified
parent 3943b84ef0
commit e05cc4a18d
2 changed files with 29 additions and 3 deletions
@@ -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" }],
})
+2 -2
View File
@@ -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