Phase I: update README + docs for new Python SDK API

SteveSandersonMS · Copilot · SteveSandersonMS · commit b80af48a9618 · 2026-05-22T13:15:18.000+01:00
Mirrors PR #1357 Phase K (TypeScript SDK API review): every Python code snippet under \docs/\ and the \python/README.md\ now uses the post-Phase-B/F/G/H public API: * `CopilotClient()` / `CopilotClient(CopilotClientOptions(connection=RuntimeConnection.uri/stdio/tcp(...), ...))` in place of `SubprocessConfig` / `ExternalServerConfig` * `PermissionDecisionApproveOnce()`, `PermissionDecisionReject(feedback=...)`, `PermissionDecisionUserNotAvailable()`, `PermissionNoResult()` in place of `PermissionRequestResult(kind=...)` * `base_directory` (was `copilot_home`) * `enable_remote_sessions` (was `remote`) * `on_exit_plan_mode_request` / `on_auto_mode_switch_request` * `session.get_events()` (was `get_messages`) * `client.on_lifecycle(...)` (was `client.on`) * `max_prompt_tokens` (was `max_input_tokens`) * snake_case dataclass attribute accesses (\session_id\, \start_time\, \modified_time\, \is_remote\, \git_root\, \protocol_version\) TypeScript / Go / C# / Rust / Java snippets in the same files are untouched. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diff --git a/docs/features/custom-agents.md b/docs/features/custom-agents.md
@@ -64,14 +64,13 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
-from copilot.session import PermissionRequestResult
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 
 client = CopilotClient()
 await client.start()
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     model="gpt-4.1",
     custom_agents=[
         {
diff --git a/docs/features/hooks.md b/docs/features/hooks.md
@@ -60,14 +60,13 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
-from copilot.session import PermissionRequestResult
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 
 client = CopilotClient()
 await client.start()
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     hooks={
         "on_session_start": on_session_start,
         "on_pre_tool_use":  on_pre_tool_use,
@@ -262,7 +261,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot.session import PermissionRequestResult
+from copilot import PermissionDecisionApproveOnce
 
 READ_ONLY_TOOLS = ["read_file", "glob", "grep", "view"]
 
@@ -276,7 +275,7 @@ async def on_pre_tool_use(input_data, invocation):
     return {"permissionDecision": "allow"}
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     hooks={"on_pre_tool_use": on_pre_tool_use},
 )
 ```
@@ -578,7 +577,7 @@ const session = await client.createSession({
 <!-- docs-validate: skip -->
 ```python
 import json, aiofiles
-from copilot.session import PermissionRequestResult
+from copilot import PermissionDecisionApproveOnce
 
 audit_log = []
 
@@ -630,7 +629,7 @@ async def on_session_end(input_data, invocation):
     return None
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     hooks={
         "on_session_start": on_session_start,
         "on_user_prompt_submitted": on_user_prompt_submitted,
@@ -709,7 +708,7 @@ const session = await client.createSession({
 
 ```python
 import subprocess
-from copilot.session import PermissionRequestResult
+from copilot import PermissionDecisionApproveOnce
 
 async def on_session_end(input_data, invocation):
     sid = invocation["session_id"][:8]
@@ -728,7 +727,7 @@ async def on_error_occurred(input_data, invocation):
     return None
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     hooks={
         "on_session_end": on_session_end,
         "on_error_occurred": on_error_occurred,
@@ -932,7 +931,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot.session import PermissionRequestResult
+from copilot import PermissionDecisionApproveOnce
 
 session_metrics = {}
 
@@ -963,7 +962,7 @@ async def on_session_end(input_data, invocation):
     return None
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     hooks={
         "on_session_start": on_session_start,
         "on_user_prompt_submitted": on_user_prompt_submitted,
diff --git a/docs/features/image-input.md b/docs/features/image-input.md
@@ -68,14 +68,13 @@ await session.send({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
-from copilot.session import PermissionRequestResult
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 
 client = CopilotClient()
 await client.start()
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     model="gpt-4.1",
 )
 
@@ -286,14 +285,13 @@ await session.send({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
-from copilot.session import PermissionRequestResult
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 
 client = CopilotClient()
 await client.start()
 
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     model="gpt-4.1",
 )
 
diff --git a/docs/features/remote-sessions.md b/docs/features/remote-sessions.md
@@ -38,9 +38,9 @@ session.on("session.info", (event) => {
 
 <!-- docs-validate: skip -->
 ```python
-from copilot import CopilotClient, SubprocessConfig
+from copilot import CopilotClient, CopilotClientOptions
 
-client = CopilotClient(SubprocessConfig(remote=True))
+client = CopilotClient(CopilotClientOptions(enable_remote_sessions=True))
 session = await client.create_session(
     working_directory="/path/to/github-repo",
     on_permission_request=lambda req: {"allowed": True},
diff --git a/docs/features/skills.md b/docs/features/skills.md
@@ -42,15 +42,14 @@ await session.sendAndWait({ prompt: "Review this code for security issues" });
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
-from copilot.session import PermissionRequestResult
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 
 async def main():
     client = CopilotClient()
     await client.start()
 
     session = await client.create_session(
-        on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+        on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
         model="gpt-4.1",
         skill_directories=[
             "./skills/code-review",
diff --git a/docs/features/steering-and-queueing.md b/docs/features/steering-and-queueing.md
@@ -69,15 +69,14 @@ await session.send({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
-from copilot.session import PermissionRequestResult
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 
 async def main():
     client = CopilotClient()
     await client.start()
 
     session = await client.create_session(
-        on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+        on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
         model="gpt-4.1",
     )
 
@@ -261,15 +260,14 @@ await session.send({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
-from copilot.session import PermissionRequestResult
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 
 async def main():
     client = CopilotClient()
     await client.start()
 
     session = await client.create_session(
-        on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+        on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
         model="gpt-4.1",
     )
 
@@ -502,7 +500,7 @@ await session.send({
 
 ```python
 session = await client.create_session(
-    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"),
+    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
     model="gpt-4.1",
 )
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -665,13 +665,12 @@ unsubscribeIdle();
 
 <!-- docs-validate: hidden -->
 ```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionDecisionApproveOnce
 from copilot.generated.session_events import SessionEvent, SessionEventType
-from copilot.session import PermissionRequestResult
 
 client = CopilotClient()
 
-session = await client.create_session(on_permission_request=lambda req, inv: PermissionRequestResult(kind="approve-once"))
+session = await client.create_session(on_permission_request=lambda req, inv: PermissionDecisionApproveOnce())
 
 # Subscribe to all events
 unsubscribe = session.on(lambda event: print(f"Event: {event.type}"))
@@ -1968,12 +1967,12 @@ const session = await client.createSession({ onPermissionRequest: approveAll });
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
+from copilot import CopilotClient, CopilotClientOptions, RuntimeConnection
 from copilot.session import PermissionHandler
 
-client = CopilotClient({
-    "cli_url": "localhost:4321"
-})
+client = CopilotClient(CopilotClientOptions(
+    connection=RuntimeConnection.uri("localhost:4321"),
+))
 await client.start()
 
 # Use the client normally
@@ -2138,9 +2137,9 @@ Optional peer dependency: `@opentelemetry/api`
 
 <!-- docs-validate: skip -->
 ```python
-from copilot import CopilotClient, SubprocessConfig
+from copilot import CopilotClient, CopilotClientOptions
 
-client = CopilotClient(SubprocessConfig(
+client = CopilotClient(CopilotClientOptions(
     telemetry={
         "otlp_endpoint": "http://localhost:4318",
     },
diff --git a/docs/observability/opentelemetry.md b/docs/observability/opentelemetry.md
@@ -27,9 +27,9 @@ const client = new CopilotClient({
 
 <!-- docs-validate: skip -->
 ```python
-from copilot import CopilotClient, SubprocessConfig
+from copilot import CopilotClient, CopilotClientOptions
 
-client = CopilotClient(SubprocessConfig(
+client = CopilotClient(CopilotClientOptions(
     telemetry={
         "otlp_endpoint": "http://localhost:4318",
     },
diff --git a/docs/setup/backend-services.md b/docs/setup/backend-services.md
@@ -144,10 +144,12 @@ res.json({ content: response?.data.content });
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient, ExternalServerConfig
+from copilot import CopilotClient, CopilotClientOptions, RuntimeConnection
 from copilot.session import PermissionHandler
 
-client = CopilotClient(ExternalServerConfig(url="localhost:4321"))
+client = CopilotClient(CopilotClientOptions(
+    connection=RuntimeConnection.uri("localhost:4321"),
+))
 await client.start()
 
 session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", session_id=f"user-{user_id}-{int(time.time())}")
diff --git a/docs/troubleshooting/debugging.md b/docs/troubleshooting/debugging.md
@@ -32,9 +32,9 @@ const client = new CopilotClient({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
+from copilot import CopilotClient, CopilotClientOptions
 
-client = CopilotClient({"log_level": "debug"})
+client = CopilotClient(CopilotClientOptions(log_level="debug"))
 ```
 
 </details>
@@ -131,7 +131,7 @@ const client = new CopilotClient({
 ```
 
 > [!NOTE]
-> Python SDK logging configuration is limited. For advanced logging, run the CLI manually with `--log-dir` and connect via `cli_url`.
+> Python SDK logging configuration is limited. For advanced logging, run the CLI manually with `--log-dir` and connect via `RuntimeConnection.uri(...)`.
 
 </details>
 
diff --git a/python/README.md b/python/README.md
@@ -579,31 +579,27 @@ session = await client.create_session(
 Provide your own function to inspect each request and apply custom logic (sync or async):
 
 ```python
-from copilot.session import PermissionRequestResult
-from copilot.generated.session_events import PermissionRequest
+from copilot import (
+    PermissionDecisionApproveOnce,
+    PermissionDecisionReject,
+    PermissionRequest,
+    PermissionRequestResult,
+    PermissionRequestShell,
+)
+
 
 def on_permission_request(
     request: PermissionRequest, invocation: dict
 ) -> PermissionRequestResult:
-    # request.kind — what type of operation is being requested:
-    #   "shell"       — executing a shell command
-    #   "write"       — writing or editing a file
-    #   "read"        — reading a file
-    #   "mcp"         — calling an MCP tool
-    #   "custom-tool" — calling one of your registered tools
-    #   "url"         — fetching a URL
-    #   "memory"      — accessing or updating session/workspace memory
-    #   "hook"        — invoking a registered hook
-    # request.tool_call_id  — the tool call that triggered this request
-    # request.tool_name     — name of the tool (for custom-tool / mcp)
-    # request.file_name     — file being written (for write)
-    # request.full_command_text — full shell command (for shell)
-
-    if request.kind.value == "shell":
-        # Deny shell commands
-        return PermissionRequestResult(kind="reject")
-
-    return PermissionRequestResult(kind="approve-once")
+    # ``PermissionRequest`` is a discriminated union — pattern-match on
+    # the variant class to access the per-kind fields.
+    match request:
+        case PermissionRequestShell(full_command_text=cmd):
+            # Deny shell commands
+            return PermissionDecisionReject(feedback=f"Shell denied: {cmd}")
+        case _:
+            return PermissionDecisionApproveOnce()
+
 
 session = await client.create_session(
     on_permission_request=on_permission_request,
@@ -619,19 +615,29 @@ async def on_permission_request(
 ) -> PermissionRequestResult:
     # Simulate an async approval check (e.g., prompting a user over a network)
     await asyncio.sleep(0)
-    return PermissionRequestResult(kind="approve-once")
+    return PermissionDecisionApproveOnce()
 ```
 
 ### Permission Result Kinds
 
-The handler must return a `PermissionRequestResult` with one of the kinds declared by the `PermissionRequestResultKind` type. Approval decisions are present-tense — they describe the decision to apply, not the past-tense outcome reported back on `permission.completed` session events.
-
-| `kind` value           | Meaning                                                                                     |
-| ---------------------- | ------------------------------------------------------------------------------------------- |
-| `"approve-once"`       | Allow this single request                                                                   |
-| `"reject"`             | Deny the request                                                                            |
-| `"user-not-available"` | Deny the request because no user is available to confirm it (the default)                   |
-| `"no-result"`          | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+The handler returns a ``PermissionRequestResult``, which is an alias for
+``PermissionDecision | PermissionNoResult`` (the generated wire-level
+union of every decision variant, plus a small sentinel for v1 servers).
+Approval decisions are present-tense — they describe the decision to
+apply, not the past-tense outcome reported back on `permission.completed`
+session events.
+
+| Variant                                       | Meaning                                                                                     |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `PermissionDecisionApproveOnce()`             | Allow this single request                                                                   |
+| `PermissionDecisionReject(feedback="…")`      | Deny the request (optional feedback string forwarded to the LLM)                            |
+| `PermissionDecisionUserNotAvailable()`        | Deny the request because no user is available to confirm it (the default)                   |
+| `PermissionNoResult()`                        | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+
+Several richer variants (``PermissionDecisionApproveForSession``,
+``PermissionDecisionApproveForLocation``, ``PermissionDecisionApprovePermanently``,
+…) are available for granting longer-lived approvals; see the generated
+``copilot.generated.rpc`` module for the full list.
 
 ### Resuming Sessions
 
