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

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

The SDKs distinguish two permission types that look similar but mean
different things:

* PermissionDecision (present tense) is what an onPermissionRequest
  handler returns: approve-once, approve-for-session,
  approve-for-location, approve-permanently, reject, user-not-available,
  no-result.
* PermissionResult (past tense) is what shows up in permission.completed
  session events: approved, denied-by-rules,
  denied-interactively-by-user, etc.

The READMEs, shared docs, and several test scenario samples were
documenting and returning past-tense PermissionResult strings from
onPermissionRequest handlers. That is wrong: those handlers must return
PermissionDecision. This change updates every handler-return reference
to use valid PermissionDecision kinds, while leaving event-payload
documentation (which is legitimately past-tense) untouched.

Files touched include the Node, Python, Go, and .NET READMEs, the .NET
PermissionRequestResult.Kind XML doc, nodejs/docs/examples.md, the
shared docs/ markdown (hooks, skills, image-input, steering-and-queueing,
custom-agents, getting-started, microsoft-agent-framework), and the
Python + TypeScript sample programs under test/scenarios/.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Return PermissionRequestResult in Python permission samples

Python permission request handlers return PermissionRequestResult objects,
not raw dictionaries. Update the docs and scenario samples that were still
using dict-shaped examples so readers and scenario runs get the intended
approve-once behavior instead of falling back to user-not-available.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: stephentoub

docs/features/custom-agents.md

@@ -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" }),
 });
 ```
 
@@ -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=[
         {
@@ -284,7 +284,7 @@ const session = await client.createSession({
             skills: ["markdown-lint"],
         },
     ],
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 

docs/features/hooks.md

@@ -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" }),
 });
 ```
 
@@ -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,
@@ -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
@@ -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
     },
 })
 ```
@@ -251,7 +252,7 @@ const session = await client.createSession({
             return { permissionDecision: "allow" };
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -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):
@@ -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},
 )
 ```
@@ -463,7 +466,7 @@ const session = await client.createSession({
             return { permissionDecision: "allow" };
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -481,7 +484,7 @@ const session = await client.createSession({
             return { permissionDecision: "allow" };
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -563,7 +566,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -575,6 +578,7 @@ const session = await client.createSession({
 <!-- docs-validate: skip -->
 ```python
 import json, aiofiles
+from copilot.session import PermissionRequestResult
 
 audit_log = []
 
@@ -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,
@@ -661,7 +665,7 @@ const session = await client.createSession({
                 : null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -694,7 +698,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -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]
@@ -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,
@@ -750,7 +755,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -774,7 +779,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -800,7 +805,7 @@ const session = await client.createSession({
             };
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -826,7 +831,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -850,7 +855,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -871,7 +876,7 @@ const session = await client.createSession({
             };
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -917,7 +922,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 
@@ -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):
@@ -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,
@@ -999,7 +1006,7 @@ const session = await client.createSession({
             return null;
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 

docs/features/image-input.md

@@ -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({
@@ -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",
 )
 
@@ -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
@@ -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",
 )
 

docs/features/skills.md

@@ -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
@@ -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",
@@ -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]
@@ -396,7 +396,7 @@ const session = await client.createSession({
             tools: ["*"],
         },
     },
-    onPermissionRequest: async () => ({ kind: "approved" }),
+    onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 ```
 

docs/features/steering-and-queueing.md

@@ -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
@@ -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",
     )
 
@@ -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
@@ -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",
     )
 
@@ -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
@@ -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",
 )
 

docs/getting-started.md

@@ -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}"))