[python] Refactor CopilotClient.create_session() and resume_session() to have parameters (#587)

* Refactor `CopilotClient.create_session()` to have parameters

* Address PR review comments for create_session refactor

- Add validation for on_permission_request in create_session to fail fast
  when handler is missing/invalid
- Fix lambda signatures to accept two args (request, invocation) in test
  scenario and docs
- Fix permissionDecision key to use camelCase in pre_tool_use hook

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

* Add test for None permission handler validation

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

* Merge with main

* Fix test to use SubprocessConfig instead of dict

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

* Change the call signature of `resume_session()`

* Fix formatting

* Make on_permission_request and model keyword-only in Python SDK

Update create_session() and resume_session() signatures so that
on_permission_request and model are keyword-only parameters (after *).
Update all call sites across test scenarios, unit tests, E2E tests,
samples, and documentation to use keyword argument syntax.

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

* Fix Python E2E tests for keyword-only create_session parameters

- Restore accidentally deleted custom_agents dict entries in test_agent_and_compact_rpc.py
- Convert positional on_permission_request to keyword arg in test_compaction.py

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

* Fix formatting

* Format docstrings

* Fix a merge mistake

---------

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

Author: brettcannon

docs/auth/byok.md

@@ -23,7 +23,7 @@ Azure AI Foundry (formerly Azure OpenAI) is a common BYOK deployment target for
 ```python
 import asyncio
 import os
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
 
 FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/"
 # Set FOUNDRY_API_KEY environment variable
@@ -32,14 +32,11 @@ async def main():
     client = CopilotClient()
     await client.start()
 
-    session = await client.create_session({
-        "model": "gpt-5.2-codex",  # Your deployment name
-        "provider": {
-            "type": "openai",
-            "base_url": FOUNDRY_MODEL_URL,
-            "wire_api": "responses",  # Use "completions" for older models
-            "api_key": os.environ["FOUNDRY_API_KEY"],
-        },
+    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", provider={
+        "type": "openai",
+        "base_url": FOUNDRY_MODEL_URL,
+        "wire_api": "responses",  # Use "completions" for older models
+        "api_key": os.environ["FOUNDRY_API_KEY"],
     })
 
     done = asyncio.Event()

docs/features/custom-agents.md

@@ -70,9 +70,10 @@ from copilot.types import PermissionRequestResult
 client = CopilotClient()
 await client.start()
 
-session = await client.create_session({
-    "model": "gpt-4.1",
-    "custom_agents": [
+session = await client.create_session(
+    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+    model="gpt-4.1",
+    custom_agents=[
         {
             "name": "researcher",
             "display_name": "Research Agent",
@@ -88,8 +89,7 @@ session = await client.create_session({
             "prompt": "You are a code editor. Make minimal, surgical changes to files as requested.",
         },
     ],
-    "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
-})
+)
 ```
 
 </details>
@@ -258,8 +258,9 @@ const session = await client.createSession({
 
 <!-- docs-validate: skip -->
 ```python
-session = await client.create_session({
-    "custom_agents": [
+session = await client.create_session(
+    on_permission_request=PermissionHandler.approve_all,
+    custom_agents=[
         {
             "name": "researcher",
             "prompt": "You are a research assistant. Analyze code and answer questions.",
@@ -269,8 +270,8 @@ session = await client.create_session({
             "prompt": "You are a code editor. Make minimal, surgical changes.",
         },
     ],
-    "agent": "researcher",  # Pre-select the researcher agent
-})
+    agent="researcher",  # Pre-select the researcher agent
+)
 ```
 
 </details>

docs/features/hooks.md

@@ -65,15 +65,15 @@ from copilot import CopilotClient
 client = CopilotClient()
 await client.start()
 
-session = await client.create_session({
-    "hooks": {
+session = await client.create_session(
+    on_permission_request=lambda req, inv: {"kind": "approved"},
+    hooks={
         "on_session_start": on_session_start,
         "on_pre_tool_use":  on_pre_tool_use,
         "on_post_tool_use": on_post_tool_use,
         # ... add only the hooks you need
     },
-    "on_permission_request": lambda req, inv: {"kind": "approved"},
-})
+)
 ```
 
 </details>
@@ -245,10 +245,10 @@ async def on_pre_tool_use(input_data, invocation):
         }
     return {"permissionDecision": "allow"}
 
-session = await client.create_session({
-    "hooks": {"on_pre_tool_use": on_pre_tool_use},
-    "on_permission_request": lambda req, inv: {"kind": "approved"},
-})
+session = await client.create_session(
+    on_permission_request=lambda req, inv: {"kind": "approved"},
+    hooks={"on_pre_tool_use": on_pre_tool_use},
+)
 ```
 
 </details>
@@ -567,16 +567,16 @@ async def on_session_end(input_data, invocation):
         await f.write(json.dumps(audit_log, indent=2))
     return None
 
-session = await client.create_session({
-    "hooks": {
+session = await client.create_session(
+    on_permission_request=lambda req, inv: {"kind": "approved"},
+    hooks={
         "on_session_start": on_session_start,
         "on_user_prompt_submitted": on_user_prompt_submitted,
         "on_pre_tool_use": on_pre_tool_use,
         "on_post_tool_use": on_post_tool_use,
         "on_session_end": on_session_end,
     },
-    "on_permission_request": lambda req, inv: {"kind": "approved"},
-})
+)
 ```
 
 </details>
@@ -666,13 +666,13 @@ async def on_error_occurred(input_data, invocation):
     ])
     return None
 
-session = await client.create_session({
-    "hooks": {
+session = await client.create_session(
+    on_permission_request=lambda req, inv: {"kind": "approved"},
+    hooks={
         "on_session_end": on_session_end,
         "on_error_occurred": on_error_occurred,
     },
-    "on_permission_request": lambda req, inv: {"kind": "approved"},
-})
+)
 ```
 
 </details>
@@ -905,15 +905,15 @@ async def on_session_end(input_data, invocation):
     )
     return None
 
-session = await client.create_session({
-    "hooks": {
+session = await client.create_session(
+    on_permission_request=lambda req, inv: {"kind": "approved"},
+    hooks={
         "on_session_start": on_session_start,
         "on_user_prompt_submitted": on_user_prompt_submitted,
         "on_pre_tool_use": on_pre_tool_use,
         "on_session_end": on_session_end,
     },
-    "on_permission_request": lambda req, inv: {"kind": "approved"},
-})
+)
 ```
 
 </details>

docs/features/image-input.md

@@ -74,10 +74,10 @@ from copilot.types import PermissionRequestResult
 client = CopilotClient()
 await client.start()
 
-session = await client.create_session({
-    "model": "gpt-4.1",
-    "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
-})
+session = await client.create_session(
+    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+    model="gpt-4.1",
+)
 
 await session.send(
     "Describe what you see in this image",

docs/features/mcp.md

@@ -59,32 +59,29 @@ const session = await client.createSession({
 
 ```python
 import asyncio
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
 
 async def main():
     client = CopilotClient()
     await client.start()
 
-    session = await client.create_session({
-        "model": "gpt-5",
-        "mcp_servers": {
-            # Local MCP server (stdio)
-            "my-local-server": {
-                "type": "local",
-                "command": "python",
-                "args": ["./mcp_server.py"],
-                "env": {"DEBUG": "true"},
-                "cwd": "./servers",
-                "tools": ["*"],
-                "timeout": 30000,
-            },
-            # Remote MCP server (HTTP)
-            "github": {
-                "type": "http",
-                "url": "https://api.githubcopilot.com/mcp/",
-                "headers": {"Authorization": "Bearer ${TOKEN}"},
-                "tools": ["*"],
-            },
+    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5", mcp_servers={
+        # Local MCP server (stdio)
+        "my-local-server": {
+            "type": "local",
+            "command": "python",
+            "args": ["./mcp_server.py"],
+            "env": {"DEBUG": "true"},
+            "cwd": "./servers",
+            "tools": ["*"],
+            "timeout": 30000,
+        },
+        # Remote MCP server (HTTP)
+        "github": {
+            "type": "http",
+            "url": "https://api.githubcopilot.com/mcp/",
+            "headers": {"Authorization": "Bearer ${TOKEN}"},
+            "tools": ["*"],
         },
     })
 

docs/features/session-persistence.md

@@ -46,16 +46,13 @@ await session.sendAndWait({ prompt: "Analyze my codebase" });
 ### Python
 
 ```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
 
 client = CopilotClient()
 await client.start()
 
 # Create a session with a meaningful ID
-session = await client.create_session({
-    "session_id": "user-123-task-456",
-    "model": "gpt-5.2-codex",
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", session_id="user-123-task-456")
 
 # Do some work...
 await session.send_and_wait({"prompt": "Analyze my codebase"})
@@ -160,7 +157,7 @@ await session.sendAndWait({ prompt: "What did we discuss earlier?" });
 
 ```python
 # Resume from a different client instance (or after restart)
-session = await client.resume_session("user-123-task-456")
+session = await client.resume_session("user-123-task-456", on_permission_request=PermissionHandler.approve_all)
 
 # Continue where you left off
 await session.send_and_wait({"prompt": "What did we discuss earlier?"})

docs/features/skills.md

@@ -49,14 +49,14 @@ async def main():
     client = CopilotClient()
     await client.start()
 
-    session = await client.create_session({
-        "model": "gpt-4.1",
-        "skill_directories": [
+    session = await client.create_session(
+        on_permission_request=lambda req, inv: {"kind": "approved"},
+        model="gpt-4.1",
+        skill_directories=[
             "./skills/code-review",
             "./skills/documentation",
         ],
-        "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
-    })
+    )
 
     # Copilot now has access to skills in those directories
     await session.send_and_wait({"prompt": "Review this code for security issues"})
@@ -160,10 +160,13 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-session = await client.create_session({
-    "skill_directories": ["./skills"],
-    "disabled_skills": ["experimental-feature", "deprecated-tool"],
-})
+from copilot import PermissionHandler
+
+session = await client.create_session(
+    on_permission_request=PermissionHandler.approve_all,
+    skill_directories=["./skills"],
+    disabled_skills=["experimental-feature", "deprecated-tool"],
+)
 ```
 
 </details>

docs/features/steering-and-queueing.md

@@ -76,10 +76,10 @@ async def main():
     client = CopilotClient()
     await client.start()
 
-    session = await client.create_session({
-        "model": "gpt-4.1",
-        "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
-    })
+    session = await client.create_session(
+        on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+        model="gpt-4.1",
+    )
 
     # Start a long-running task
     msg_id = await session.send({
@@ -235,10 +235,10 @@ async def main():
     client = CopilotClient()
     await client.start()
 
-    session = await client.create_session({
-        "model": "gpt-4.1",
-        "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
-    })
+    session = await client.create_session(
+        on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+        model="gpt-4.1",
+    )
 
     # Send an initial task
     await session.send({"prompt": "Set up the project structure"})
@@ -431,10 +431,10 @@ await session.send({
 <summary><strong>Python</strong></summary>
 
 ```python
-session = await client.create_session({
-    "model": "gpt-4.1",
-    "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
-})
+session = await client.create_session(
+    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+    model="gpt-4.1",
+)
 
 # Start a task
 await session.send({"prompt": "Refactor the database layer"})