Skip to content

Fix permission handler kinds in SDK docs and samples (#1133) #1315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stephentoub wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Fix permission handler kinds in SDK docs and samples (#1133) #1315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f0821a
Fix permission handler kinds in SDK docs and samples (#1133)
Copilot May 17, 2026
498fff8
Return PermissionRequestResult in Python permission samples
Copilot May 17, 2026
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
6 changes: 3 additions & 3 deletions docs/features/custom-agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ const session = await client.createSession({
prompt: "You are a code editor. Make minimal, surgical changes to files as requested.",
},
],
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -71,7 +71,7 @@ client = CopilotClient()
await client.start()

session = await client.create_session(
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
model="gpt-4.1",
custom_agents=[
{
Expand Down Expand Up @@ -284,7 +284,7 @@ const session = await client.createSession({
skills: ["markdown-lint"],
},
],
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand Down
51 changes: 29 additions & 22 deletions docs/features/hooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ const session = await client.createSession({
onPostToolUse: async (input, invocation) => { /* ... */ },
// ... add only the hooks you need
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -61,12 +61,13 @@ const session = await client.createSession({

```python
from copilot import CopilotClient
from copilot.session import PermissionRequestResult

client = CopilotClient()
await client.start()

session = await client.create_session(
on_permission_request=lambda req, inv: {"kind": "approved"},
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
hooks={
"on_session_start": on_session_start,
"on_pre_tool_use": on_pre_tool_use,
Expand Down Expand Up @@ -113,7 +114,7 @@ func main() {
OnPostToolUse: onPostToolUse,
},
OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
return copilot.PermissionRequestResult{Kind: "approved"}, nil
return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
},
})
_ = session
Expand All @@ -133,7 +134,7 @@ session, err := client.CreateSession(ctx, &copilot.SessionConfig{
// ... add only the hooks you need
},
OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
return copilot.PermissionRequestResult{Kind: "approved"}, nil
return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
},
})
```
Expand Down Expand Up @@ -251,7 +252,7 @@ const session = await client.createSession({
return { permissionDecision: "allow" };
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -261,6 +262,8 @@ const session = await client.createSession({
<summary><strong>Python</strong></summary>

```python
from copilot.session import PermissionRequestResult

READ_ONLY_TOOLS = ["read_file", "glob", "grep", "view"]

async def on_pre_tool_use(input_data, invocation):
Expand All @@ -273,7 +276,7 @@ async def on_pre_tool_use(input_data, invocation):
return {"permissionDecision": "allow"}

session = await client.create_session(
on_permission_request=lambda req, inv: {"kind": "approved"},
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
hooks={"on_pre_tool_use": on_pre_tool_use},
)
```
Expand Down Expand Up @@ -463,7 +466,7 @@ const session = await client.createSession({
return { permissionDecision: "allow" };
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -481,7 +484,7 @@ const session = await client.createSession({
return { permissionDecision: "allow" };
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand Down Expand Up @@ -563,7 +566,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -575,6 +578,7 @@ const session = await client.createSession({
<!-- docs-validate: skip -->
```python
import json, aiofiles
from copilot.session import PermissionRequestResult

audit_log = []

Expand Down Expand Up @@ -626,7 +630,7 @@ async def on_session_end(input_data, invocation):
return None

session = await client.create_session(
on_permission_request=lambda req, inv: {"kind": "approved"},
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
hooks={
"on_session_start": on_session_start,
"on_user_prompt_submitted": on_user_prompt_submitted,
Expand Down Expand Up @@ -661,7 +665,7 @@ const session = await client.createSession({
: null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand Down Expand Up @@ -694,7 +698,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -705,6 +709,7 @@ const session = await client.createSession({

```python
import subprocess
from copilot.session import PermissionRequestResult

async def on_session_end(input_data, invocation):
sid = invocation["session_id"][:8]
Expand All @@ -723,7 +728,7 @@ async def on_error_occurred(input_data, invocation):
return None

session = await client.create_session(
on_permission_request=lambda req, inv: {"kind": "approved"},
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
hooks={
"on_session_end": on_session_end,
"on_error_occurred": on_error_occurred,
Expand All @@ -750,7 +755,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -774,7 +779,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -800,7 +805,7 @@ const session = await client.createSession({
};
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -826,7 +831,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -850,7 +855,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -871,7 +876,7 @@ const session = await client.createSession({
};
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand Down Expand Up @@ -917,7 +922,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand All @@ -927,6 +932,8 @@ const session = await client.createSession({
<summary><strong>Python</strong></summary>

```python
from copilot.session import PermissionRequestResult

session_metrics = {}

async def on_session_start(input_data, invocation):
Expand Down Expand Up @@ -956,7 +963,7 @@ async def on_session_end(input_data, invocation):
return None

session = await client.create_session(
on_permission_request=lambda req, inv: {"kind": "approved"},
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
hooks={
"on_session_start": on_session_start,
"on_user_prompt_submitted": on_user_prompt_submitted,
Expand Down Expand Up @@ -999,7 +1006,7 @@ const session = await client.createSession({
return null;
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand Down
8 changes: 4 additions & 4 deletions docs/features/image-input.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ await client.start();

const session = await client.createSession({
model: "gpt-4.1",
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});

await session.send({
Expand All @@ -75,7 +75,7 @@ client = CopilotClient()
await client.start()

session = await client.create_session(
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
model="gpt-4.1",
)

Expand Down Expand Up @@ -263,7 +263,7 @@ await client.start();

const session = await client.createSession({
model: "gpt-4.1",
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});

const base64ImageData = "..."; // your base64-encoded image
Expand Down Expand Up @@ -293,7 +293,7 @@ client = CopilotClient()
await client.start()

session = await client.create_session(
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
model="gpt-4.1",
)

Expand Down
8 changes: 4 additions & 4 deletions docs/features/skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ const session = await client.createSession({
"./skills/code-review",
"./skills/documentation",
],
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});

// Copilot now has access to skills in those directories
Expand All @@ -50,7 +50,7 @@ async def main():
await client.start()

session = await client.create_session(
on_permission_request=lambda req, inv: {"kind": "approved"},
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
model="gpt-4.1",
skill_directories=[
"./skills/code-review",
Expand Down Expand Up @@ -375,7 +375,7 @@ const session = await client.createSession({
prompt: "Focus on OWASP Top 10 vulnerabilities",
skills: ["security-scan", "dependency-check"],
}],
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```
> [!NOTE]
Expand All @@ -396,7 +396,7 @@ const session = await client.createSession({
tools: ["*"],
},
},
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```

Expand Down
12 changes: 6 additions & 6 deletions docs/features/steering-and-queueing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ await client.start();

const session = await client.createSession({
model: "gpt-4.1",
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});

// Start a long-running task
Expand Down Expand Up @@ -77,7 +77,7 @@ async def main():
await client.start()

session = await client.create_session(
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
model="gpt-4.1",
)

Expand Down Expand Up @@ -235,7 +235,7 @@ await client.start();

const session = await client.createSession({
model: "gpt-4.1",
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});

// Send an initial task
Expand Down Expand Up @@ -269,7 +269,7 @@ async def main():
await client.start()

session = await client.create_session(
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
model="gpt-4.1",
)

Expand Down Expand Up @@ -476,7 +476,7 @@ You can use both patterns together in a single session. Steering affects the cur
```typescript
const session = await client.createSession({
model: "gpt-4.1",
onPermissionRequest: async () => ({ kind: "approved" }),
onPermissionRequest: async () => ({ kind: "approve-once" }),
});

// Start a task
Expand All @@ -502,7 +502,7 @@ await session.send({

```python
session = await client.create_session(
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
model="gpt-4.1",
)

Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -671,7 +671,7 @@ from copilot.session import PermissionRequestResult

client = CopilotClient()

session = await client.create_session(on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"))
session = await client.create_session(on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"))

# Subscribe to all events
unsubscribe = session.on(lambda event: print(f"Event: {event.type}"))
Expand Down
Loading
Loading