codex-app-server-sdk 0.3.1__tar.gz → 0.3.2__tar.gz

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-app-server-sdk
-Version: 0.3.1
+Version: 0.3.2
 Summary: Async Python client for Codex app-server over stdio and websocket.
 Project-URL: Documentation, https://emsi.github.io/codex-app-server-sdk/
 Project-URL: Repository, https://github.com/emsi/codex-app-server-sdk

codex_app_server_sdk-0.3.2/docs/approvals-and-sandbox.md

@@ -0,0 +1,117 @@
+# Approval requests and sandbox policies
+
+## Related API
+
+- [`ThreadConfig`](api/models.md#codex_app_server_sdk.models.ThreadConfig)
+- [`TurnOverrides`](api/models.md#codex_app_server_sdk.models.TurnOverrides)
+- [`SandboxMode`](api/models.md#codex_app_server_sdk.models.SandboxMode)
+- [`SandboxPolicy`](api/models.md#codex_app_server_sdk.models.SandboxPolicy)
+- [`ApprovalPolicy`](api/models.md#codex_app_server_sdk.models.ApprovalPolicy)
+- [`CodexClient.set_approval_handler(...)`](api/client.md#codex_app_server_sdk.client.CodexClient.set_approval_handler)
+- [`CodexClient.approval_requests(...)`](api/client.md#codex_app_server_sdk.client.CodexClient.approval_requests)
+- [`CodexClient.respond_approval(...)`](api/client.md#codex_app_server_sdk.client.CodexClient.respond_approval)
+- [`CodexClient.approve_approval(...)`](api/client.md#codex_app_server_sdk.client.CodexClient.approve_approval)
+- [`CodexClient.decline_approval(...)`](api/client.md#codex_app_server_sdk.client.CodexClient.decline_approval)
+- [`CodexClient.cancel_approval(...)`](api/client.md#codex_app_server_sdk.client.CodexClient.cancel_approval)
+
+## Thread-level policy and sandbox mode
+
+`ThreadConfig` controls defaults persisted for subsequent turns on that thread.
+
+```python
+from codex_app_server_sdk import ThreadConfig
+
+cfg = ThreadConfig(
+    approval_policy="on-request",
+    sandbox="workspace-write",
+)
+```
+
+`approval_policy` values:
+
+- `untrusted`
+- `on-failure` (deprecated by protocol, still accepted)
+- `on-request`
+- `never`
+
+`sandbox` values:
+
+- `read-only`
+- `workspace-write`
+- `danger-full-access`
+
+## Turn-level sandbox policy
+
+Use `TurnOverrides.sandbox_policy` for per-turn policy payloads.
+
+```python
+from codex_app_server_sdk import TurnOverrides
+
+turn = TurnOverrides(
+    sandbox_policy={
+        "type": "workspaceWrite",
+        "networkAccess": False,
+        "writableRoots": ["/tmp"],
+    },
+    approval_policy="on-request",
+)
+```
+
+`TurnOverrides.sandbox_policy` accepts either:
+
+- typed `SandboxPolicy` structures, or
+- raw mapping payloads (for compatibility with server extensions).
+
+## Approval request handling
+
+The client handles v2 server-initiated approval requests:
+
+- `item/commandExecution/requestApproval`
+- `item/fileChange/requestApproval`
+
+If no handler is registered, the SDK auto-responds with `decline` (continue turn).
+
+### Callback mode
+
+```python
+from codex_app_server_sdk import (
+    CodexClient,
+    CommandApprovalRequest,
+    CommandApprovalWithExecpolicyAmendment,
+    FileChangeApprovalRequest,
+)
+
+
+async def handler(req):
+    if isinstance(req, CommandApprovalRequest):
+        if req.reason and "network" in req.reason.lower():
+            return "decline"
+        return CommandApprovalWithExecpolicyAmendment(["uv", "run"])
+
+    if isinstance(req, FileChangeApprovalRequest):
+        return "accept_for_session"
+
+    return "decline"
+
+
+async with CodexClient.connect_stdio() as client:
+    client.set_approval_handler(handler)
+    result = await client.chat_once("Run a command that may request approval.")
+    print(result.final_text)
+```
+
+### Stream mode (manual response)
+
+```python
+from codex_app_server_sdk import CodexClient, CommandApprovalRequest
+
+
+async with CodexClient.connect_stdio() as client:
+    async for req in client.approval_requests():
+        if isinstance(req, CommandApprovalRequest):
+            await client.approve_approval(req, for_session=True)
+        else:
+            await client.decline_approval(req)
+```
+
+`approval_requests()` is observational. If a callback is configured, callback handling remains authoritative.

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/docs/index.md

@@ -20,16 +20,40 @@ This documentation is organized around:
 
 ## Install
 
+Install `uv` (if needed):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Install the package from PyPI:
+
 ```bash
-uv sync
+uv add codex-app-server-sdk
 ```
 
-## Local docs workflow
+Or pip-compatible install in the active environment:
+
+```bash
+uv pip install codex-app-server-sdk
+```
+
+## Contributor docs workflow
+
+Install development dependencies:
+
+```bash
+uv sync --group dev
+```
+
+Serve docs locally:
 
 ```bash
 uv run zensical serve
 ```
 
+Build docs:
+
 ```bash
 uv run zensical build
 ```

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/docs/recipes/index.md

@@ -14,6 +14,7 @@ Task-oriented guides for common usage patterns.
 
 - [Conversation APIs](../conversation.md)
 - [Transports](../transports.md)
+- [Approval requests and sandbox policies](../approvals-and-sandbox.md)
 - [Timeouts, continuation, cancel](../timeouts-continuation-cancel.md)
 - [Threads and configuration](../threads-and-config.md)
 - [Examples](../examples.md)

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/mkdocs.yml

@@ -42,6 +42,7 @@ nav:
       - Overview: recipes/index.md
       - Conversation APIs: conversation.md
       - Transports: transports.md
+      - Approvals and sandbox: approvals-and-sandbox.md
       - Timeouts, continuation, cancel: timeouts-continuation-cancel.md
       - Threads and configuration: threads-and-config.md
       - Examples: examples.md

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codex-app-server-sdk"
-version = "0.3.1"
+version = "0.3.2"
 description = "Async Python client for Codex app-server over stdio and websocket."
 readme = "README.md"
 license = { file = "LICENSE" }

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/src/codex_app_server_sdk/__init__.py

@@ -7,12 +7,20 @@ from .errors import (
     CodexTurnInactiveError,
 )
 from .models import (
+    ApprovalRequest,
     ApprovalPolicy,
     CancelResult,
     ChatContinuation,
     ChatResult,
+    CommandApprovalDecision,
+    CommandApprovalRequest,
+    CommandApprovalWithExecpolicyAmendment,
     ConversationStep,
+    FileChangeApprovalDecision,
+    FileChangeApprovalRequest,
     InitializeResult,
+    SandboxMode,
+    SandboxPolicy,
     ReasoningEffort,
     ReasoningSummary,
     ThreadConfig,
@@ -22,9 +30,13 @@ from .models import (
 
 __all__ = [
     "CancelResult",
+    "ApprovalRequest",
     "ApprovalPolicy",
     "ChatContinuation",
     "ChatResult",
+    "CommandApprovalDecision",
+    "CommandApprovalRequest",
+    "CommandApprovalWithExecpolicyAmendment",
     "CodexClient",
     "CodexError",
     "CodexProtocolError",
@@ -32,7 +44,11 @@ __all__ = [
     "CodexTransportError",
     "CodexTurnInactiveError",
     "ConversationStep",
+    "FileChangeApprovalDecision",
+    "FileChangeApprovalRequest",
     "InitializeResult",
+    "SandboxMode",
+    "SandboxPolicy",
     "ReasoningEffort",
     "ReasoningSummary",
     "ThreadConfig",

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/src/codex_app_server_sdk/client.py

@@ -6,7 +6,7 @@ import os
 import shlex
 from collections.abc import AsyncIterator, Mapping, Sequence
 from dataclasses import dataclass, field
-from typing import Any, Literal
+from typing import Any, Awaitable, Callable, Coroutine, Literal
 
 from .errors import (
     CodexProtocolError,
@@ -15,10 +15,16 @@ from .errors import (
     CodexTurnInactiveError,
 )
 from .models import (
+    ApprovalRequest,
     CancelResult,
     ChatContinuation,
     ChatResult,
+    CommandApprovalDecision,
+    CommandApprovalRequest,
+    CommandApprovalWithExecpolicyAmendment,
     ConversationStep,
+    FileChangeApprovalDecision,
+    FileChangeApprovalRequest,
     InitializeResult,
     ThreadConfig,
     TurnOverrides,
@@ -32,7 +38,9 @@ from .protocol import (
     CONFIG_VALUE_WRITE_METHOD,
     DEFAULT_OPT_OUT_NOTIFICATION_METHODS,
     INITIALIZE_METHOD,
+    ITEM_COMMAND_EXECUTION_REQUEST_APPROVAL_METHOD,
     ITEM_COMPLETED_METHOD,
+    ITEM_FILE_CHANGE_REQUEST_APPROVAL_METHOD,
     MODEL_LIST_METHOD,
     REVIEW_START_METHOD,
     THREAD_ARCHIVE_METHOD,
@@ -53,6 +61,7 @@ from .protocol import (
     is_turn_completed,
     is_turn_failed,
     make_error_response,
+    make_result_response,
     make_request,
 )
 from .transport import StdioTransport, Transport, WebSocketTransport
@@ -79,6 +88,9 @@ class _TurnSession:
     interrupted: bool = False
 
 
+_APPROVAL_QUEUE_STOP = object()
+
+
 class ThreadHandle:
     """Thread-scoped high-level API wrapper bound to one `thread_id`."""
 
@@ -318,6 +330,16 @@ class CodexClient:
         self._notifications: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
         self._deferred_notifications: list[dict[str, Any]] = []
         self._turn_sessions: dict[str, _TurnSession] = {}
+        self._approval_requests: asyncio.Queue[ApprovalRequest | object] = asyncio.Queue()
+        self._pending_approval_requests: dict[int | str, ApprovalRequest] = {}
+        self._approval_handler: (
+            Callable[
+                [ApprovalRequest],
+                Awaitable[CommandApprovalDecision | FileChangeApprovalDecision],
+            ]
+            | None
+        ) = None
+        self._background_tasks: set[asyncio.Task[Any]] = set()
 
         self._send_lock = asyncio.Lock()
         self._receiver_task: asyncio.Task[None] | None = None
@@ -457,8 +479,18 @@ class CodexClient:
                 future.set_exception(CodexTransportError("client is closing"))
         self._pending.clear()
 
+        for task in list(self._background_tasks):
+            task.cancel()
+        if self._background_tasks:
+            await asyncio.gather(*self._background_tasks, return_exceptions=True)
+        self._background_tasks.clear()
+
+        self._pending_approval_requests.clear()
+        self._approval_handler = None
+
         self._turn_sessions.clear()
         self._deferred_notifications.clear()
+        self._approval_requests.put_nowait(_APPROVAL_QUEUE_STOP)
 
         await self._transport.close()
         self._started = False
@@ -557,6 +589,94 @@ class CodexClient:
             )
         return response.get("result")
 
+    def set_approval_handler(
+        self,
+        handler: (
+            Callable[
+                [ApprovalRequest],
+                Awaitable[CommandApprovalDecision | FileChangeApprovalDecision],
+            ]
+            | None
+        ),
+    ) -> None:
+        """Set or clear async handler for v2 approval requests.
+
+        The handler is invoked for:
+        - `item/commandExecution/requestApproval`
+        - `item/fileChange/requestApproval`
+
+        If no handler is configured, requests are auto-declined.
+        """
+        self._approval_handler = handler
+
+    async def approval_requests(self) -> AsyncIterator[ApprovalRequest]:
+        """Yield parsed approval requests from the server.
+
+        This stream is observational; automatic callback handling (or auto-decline
+        default) still applies.
+        """
+        while True:
+            item = await self._approval_requests.get()
+            if item is _APPROVAL_QUEUE_STOP:
+                self._approval_requests.put_nowait(_APPROVAL_QUEUE_STOP)
+                return
+            if isinstance(item, (CommandApprovalRequest, FileChangeApprovalRequest)):
+                yield item
+
+    async def respond_approval(
+        self,
+        request: ApprovalRequest,
+        decision: CommandApprovalDecision | FileChangeApprovalDecision,
+    ) -> None:
+        """Respond to one pending approval request."""
+        pending = self._pending_approval_requests.get(request.request_id)
+        if pending is None:
+            raise CodexProtocolError("approval request is no longer pending")
+
+        if type(pending) is not type(request):
+            raise CodexProtocolError("approval request type mismatch")
+
+        self._pending_approval_requests.pop(request.request_id, None)
+        result_payload = _encode_approval_result(request, decision)
+        response = make_result_response(request.request_id, result_payload)
+        async with self._send_lock:
+            await self._transport.send(response)
+
+    async def approve_approval(
+        self,
+        request: ApprovalRequest,
+        *,
+        for_session: bool = False,
+        execpolicy_amendment: Sequence[str] | None = None,
+    ) -> None:
+        """Convenience helper to approve an approval request."""
+        if isinstance(request, FileChangeApprovalRequest):
+            if execpolicy_amendment is not None:
+                raise ValueError(
+                    "execpolicy_amendment is not applicable to file-change approvals"
+                )
+            decision: FileChangeApprovalDecision = (
+                "accept_for_session" if for_session else "accept"
+            )
+            await self.respond_approval(request, decision)
+            return
+
+        if execpolicy_amendment is not None:
+            decision_cmd: CommandApprovalDecision = CommandApprovalWithExecpolicyAmendment(
+                execpolicy_amendment=list(execpolicy_amendment)
+            )
+        else:
+            decision_cmd = "accept_for_session" if for_session else "accept"
+        await self.respond_approval(request, decision_cmd)
+
+    async def decline_approval(self, request: ApprovalRequest) -> None:
+        """Convenience helper to decline an approval request and continue turn."""
+        await self.respond_approval(request, "decline")
+
+    async def cancel_approval(self, request: ApprovalRequest) -> None:
+        """Convenience helper to decline an approval request and cancel turn."""
+        await self.respond_approval(request, "cancel")
+
     async def start_thread(self, config: ThreadConfig | None = None) -> ThreadHandle:
         """Create a new thread and return a bound handle.
 
@@ -1612,6 +1732,9 @@ class CodexClient:
 
     def _cleanup_turn_state(self, turn_id: str) -> None:
         self._turn_sessions.pop(turn_id, None)
+        for request_id, request in list(self._pending_approval_requests.items()):
+            if request.turn_id == turn_id:
+                self._pending_approval_requests.pop(request_id, None)
         self._drop_deferred_for_turn(turn_id)
 
     def _drop_deferred_for_turn(self, turn_id: str) -> None:
@@ -1666,6 +1789,14 @@ class CodexClient:
                 if "id" in payload and payload.get("id") is not None:
                     request_id = payload["id"]
                     if isinstance(request_id, (int, str)):
+                        handled = await self._handle_server_request(
+                            request_id=request_id,
+                            method=method,
+                            payload=payload,
+                        )
+                        if handled:
+                            await self._notifications.put(payload)
+                            continue
                         error_response = make_error_response(
                             request_id,
                             -32601,
@@ -1693,6 +1824,83 @@ class CodexClient:
                 }
             )
 
+    async def _handle_server_request(
+        self,
+        *,
+        request_id: int | str,
+        method: str,
+        payload: dict[str, Any],
+    ) -> bool:
+        if method not in {
+            ITEM_COMMAND_EXECUTION_REQUEST_APPROVAL_METHOD,
+            ITEM_FILE_CHANGE_REQUEST_APPROVAL_METHOD,
+        }:
+            return False
+
+        params = payload.get("params")
+        if not isinstance(params, Mapping):
+            error = make_error_response(
+                request_id,
+                -32602,
+                f"{method} received invalid params",
+            )
+            async with self._send_lock:
+                await self._transport.send(error)
+            return True
+
+        try:
+            request = _parse_approval_request(
+                request_id=request_id,
+                method=method,
+                params=params,
+            )
+        except CodexProtocolError as exc:
+            error = make_error_response(request_id, -32602, str(exc))
+            async with self._send_lock:
+                await self._transport.send(error)
+            return True
+
+        self._pending_approval_requests[request_id] = request
+        await self._approval_requests.put(request)
+
+        if self._approval_handler is None:
+            self._spawn_background_task(self._auto_decline_approval(request))
+        else:
+            self._spawn_background_task(self._run_approval_handler(request))
+        return True
+
+    def _spawn_background_task(self, coro: Coroutine[Any, Any, Any]) -> None:
+        task: asyncio.Task[Any] = asyncio.create_task(coro)
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+
+    async def _auto_decline_approval(self, request: ApprovalRequest) -> None:
+        with contextlib.suppress(CodexProtocolError, CodexTransportError):
+            await self.respond_approval(request, "decline")
+
+    async def _run_approval_handler(self, request: ApprovalRequest) -> None:
+        handler = self._approval_handler
+        if handler is None:
+            await self._auto_decline_approval(request)
+            return
+
+        decision: CommandApprovalDecision | FileChangeApprovalDecision
+        try:
+            decision = await handler(request)
+        except Exception:
+            decision = "decline"
+
+        try:
+            await self.respond_approval(request, decision)
+        except ValueError:
+            with contextlib.suppress(CodexProtocolError, CodexTransportError):
+                await self.respond_approval(request, "decline")
+        except CodexProtocolError:
+            # Already handled (for example by explicit caller response).
+            return
+        except CodexTransportError:
+            return
+
 
 def _is_unset(value: Any) -> bool:
     return isinstance(value, UnsetType)
@@ -2050,6 +2258,100 @@ def _extract_item_text(item: Mapping[str, Any]) -> str | None:
     return None
 
 
+def _parse_approval_request(
+    *,
+    request_id: int | str,
+    method: str,
+    params: Mapping[str, Any],
+) -> ApprovalRequest:
+    if method == ITEM_COMMAND_EXECUTION_REQUEST_APPROVAL_METHOD:
+        command_actions_value = params.get("commandActions")
+        command_actions: list[dict[str, Any]] | None = None
+        if isinstance(command_actions_value, list):
+            command_actions = [
+                dict(action) for action in command_actions_value if isinstance(action, Mapping)
+            ]
+
+        amendment_value = params.get("proposedExecpolicyAmendment")
+        proposed_execpolicy_amendment: list[str] | None = None
+        if isinstance(amendment_value, list):
+            proposed_execpolicy_amendment = [
+                token for token in amendment_value if isinstance(token, str)
+            ]
+
+        return CommandApprovalRequest(
+            request_id=request_id,
+            thread_id=_require_string_field(params, "threadId", method),
+            turn_id=_require_string_field(params, "turnId", method),
+            item_id=_require_string_field(params, "itemId", method),
+            approval_id=_optional_string(params.get("approvalId")),
+            reason=_optional_string(params.get("reason")),
+            command=_optional_string(params.get("command")),
+            cwd=_optional_string(params.get("cwd")),
+            command_actions=command_actions,
+            proposed_execpolicy_amendment=proposed_execpolicy_amendment,
+        )
+
+    if method == ITEM_FILE_CHANGE_REQUEST_APPROVAL_METHOD:
+        return FileChangeApprovalRequest(
+            request_id=request_id,
+            thread_id=_require_string_field(params, "threadId", method),
+            turn_id=_require_string_field(params, "turnId", method),
+            item_id=_require_string_field(params, "itemId", method),
+            grant_root=_optional_string(params.get("grantRoot")),
+            reason=_optional_string(params.get("reason")),
+        )
+
+    raise CodexProtocolError(f"unsupported server request method: {method}")
+
+
+def _encode_approval_result(
+    request: ApprovalRequest,
+    decision: CommandApprovalDecision | FileChangeApprovalDecision,
+) -> dict[str, Any]:
+    if isinstance(request, CommandApprovalRequest):
+        if isinstance(decision, CommandApprovalWithExecpolicyAmendment):
+            encoded_decision: Any = {
+                "acceptWithExecpolicyAmendment": {
+                    "execpolicy_amendment": list(decision.execpolicy_amendment),
+                }
+            }
+        else:
+            encoded_decision = _encode_simple_approval_decision(decision)
+        return {"decision": encoded_decision}
+
+    if isinstance(decision, CommandApprovalWithExecpolicyAmendment):
+        raise ValueError("execpolicy amendment decision is invalid for file-change approvals")
+
+    return {"decision": _encode_simple_approval_decision(decision)}
+
+
+def _encode_simple_approval_decision(
+    decision: str,
+) -> str:
+    mapping = {
+        "accept": "accept",
+        "accept_for_session": "acceptForSession",
+        "decline": "decline",
+        "cancel": "cancel",
+    }
+    mapped = mapping.get(decision)
+    if mapped is None:
+        raise ValueError(f"unsupported approval decision: {decision!r}")
+    return mapped
+
+
+def _require_string_field(params: Mapping[str, Any], key: str, method: str) -> str:
+    value = params.get(key)
+    if not isinstance(value, str) or not value:
+        raise CodexProtocolError(f"{method} missing required string field: {key}")
+    return value
+
+
+def _optional_string(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
 def _event_mentions_turn_id(payload: Any, turn_id: str) -> bool:
     """Return True when payload references target turn id."""
     if not isinstance(payload, (dict, list)):

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/src/codex_app_server_sdk/models.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Literal, TypeAlias
+from typing import Any, Literal, TypeAlias, TypedDict
 
 from pydantic import BaseModel, Field
 
@@ -122,6 +122,65 @@ UNSET = UnsetType()
 #: - ``"never"``: never request approval.
 ApprovalPolicy: TypeAlias = Literal["untrusted", "on-failure", "on-request", "never"]
 
+#: Thread-level sandbox mode accepted by thread/start|resume|fork methods.
+SandboxMode: TypeAlias = Literal["read-only", "workspace-write", "danger-full-access"]
+
+
+class RestrictedReadOnlyAccess(TypedDict, total=False):
+    """Restricted read-only access policy."""
+
+    type: Literal["restricted"]
+    includePlatformDefaults: bool
+    readableRoots: list[str]
+
+
+class FullAccessReadOnlyAccess(TypedDict):
+    """Unrestricted read-only access policy."""
+
+    type: Literal["fullAccess"]
+
+
+ReadOnlyAccess: TypeAlias = RestrictedReadOnlyAccess | FullAccessReadOnlyAccess
+
+
+class DangerFullAccessSandboxPolicy(TypedDict):
+    """No sandbox restrictions."""
+
+    type: Literal["dangerFullAccess"]
+
+
+class ReadOnlySandboxPolicy(TypedDict, total=False):
+    """Read-only sandbox policy."""
+
+    type: Literal["readOnly"]
+    access: ReadOnlyAccess
+
+
+class ExternalSandboxPolicy(TypedDict, total=False):
+    """External sandbox policy with explicit network mode."""
+
+    type: Literal["externalSandbox"]
+    networkAccess: Literal["restricted", "enabled"]
+
+
+class WorkspaceWriteSandboxPolicy(TypedDict, total=False):
+    """Workspace-write sandbox policy."""
+
+    type: Literal["workspaceWrite"]
+    networkAccess: bool
+    readOnlyAccess: ReadOnlyAccess
+    writableRoots: list[str]
+    excludeSlashTmp: bool
+    excludeTmpdirEnvVar: bool
+
+
+SandboxPolicy: TypeAlias = (
+    DangerFullAccessSandboxPolicy
+    | ReadOnlySandboxPolicy
+    | ExternalSandboxPolicy
+    | WorkspaceWriteSandboxPolicy
+)
+
 #: Reasoning effort level for per-turn/model behavior.
 #:
 #: Values are ordered from lowest to highest: ``none``, ``minimal``, ``low``,
@@ -153,7 +212,8 @@ class ThreadConfig:
         model_provider: Optional model provider name/identifier.
         approval_policy: Approval policy mode (`untrusted`, `on-failure`,
             `on-request`, `never`).
-        sandbox: Sandbox mode/policy selector accepted by the server.
+        sandbox: Sandbox mode selector accepted by the server (`read-only`,
+            `workspace-write`, `danger-full-access`).
         personality: Optional personality profile name.
         ephemeral: Optional ephemeral-thread flag.
         config: Optional thread-level config map forwarded to the server.
@@ -165,7 +225,7 @@ class ThreadConfig:
     model: str | None | UnsetType = UNSET
     model_provider: str | None | UnsetType = UNSET
     approval_policy: ApprovalPolicy | None | UnsetType = UNSET
-    sandbox: str | None | UnsetType = UNSET
+    sandbox: SandboxMode | None | UnsetType = UNSET
     personality: str | None | UnsetType = UNSET
     ephemeral: bool | None | UnsetType = UNSET
     config: dict[str, Any] | None | UnsetType = UNSET
@@ -194,7 +254,55 @@ class TurnOverrides:
     model: str | None | UnsetType = UNSET
     effort: ReasoningEffort | None | UnsetType = UNSET
     summary: ReasoningSummary | None | UnsetType = UNSET
-    sandbox_policy: dict[str, Any] | None | UnsetType = UNSET
+    sandbox_policy: SandboxPolicy | dict[str, Any] | None | UnsetType = UNSET
     personality: str | None | UnsetType = UNSET
     approval_policy: ApprovalPolicy | None | UnsetType = UNSET
     output_schema: dict[str, Any] | None | UnsetType = UNSET
+
+
+RequestId: TypeAlias = int | str
+
+
+@dataclass(slots=True)
+class CommandApprovalRequest:
+    """Server-initiated approval request for one command execution item."""
+
+    request_id: RequestId
+    thread_id: str
+    turn_id: str
+    item_id: str
+    approval_id: str | None = None
+    reason: str | None = None
+    command: str | None = None
+    cwd: str | None = None
+    command_actions: list[dict[str, Any]] | None = None
+    proposed_execpolicy_amendment: list[str] | None = None
+
+
+@dataclass(slots=True)
+class FileChangeApprovalRequest:
+    """Server-initiated approval request for one file-change item."""
+
+    request_id: RequestId
+    thread_id: str
+    turn_id: str
+    item_id: str
+    grant_root: str | None = None
+    reason: str | None = None
+
+
+ApprovalRequest: TypeAlias = CommandApprovalRequest | FileChangeApprovalRequest
+
+
+@dataclass(slots=True)
+class CommandApprovalWithExecpolicyAmendment:
+    """Approval decision carrying an execpolicy amendment prefix rule."""
+
+    execpolicy_amendment: list[str]
+
+
+CommandApprovalDecision: TypeAlias = (
+    Literal["accept", "accept_for_session", "decline", "cancel"]
+    | CommandApprovalWithExecpolicyAmendment
+)
+FileChangeApprovalDecision: TypeAlias = Literal["accept", "accept_for_session", "decline", "cancel"]

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/src/codex_app_server_sdk/protocol.py

@@ -28,6 +28,8 @@ CONFIG_VALUE_WRITE_METHOD = "config/value/write"
 CONFIG_BATCH_WRITE_METHOD = "config/batchWrite"
 CONFIG_REQUIREMENTS_READ_METHOD = "configRequirements/read"
 ITEM_COMPLETED_METHOD = "item/completed"
+ITEM_COMMAND_EXECUTION_REQUEST_APPROVAL_METHOD = "item/commandExecution/requestApproval"
+ITEM_FILE_CHANGE_REQUEST_APPROVAL_METHOD = "item/fileChange/requestApproval"
 
 DEFAULT_OPT_OUT_NOTIFICATION_METHODS = (
     "codex/event/agent_message_content_delta",
@@ -92,6 +94,18 @@ def make_error_response(
     }
 
 
+def make_result_response(
+    request_id: int | str,
+    result: Any,
+) -> dict[str, Any]:
+    """Build a JSON-RPC success response envelope."""
+    return {
+        "jsonrpc": JSONRPC_VERSION,
+        "id": request_id,
+        "result": result,
+    }
+
+
 def is_response_message(payload: dict[str, Any]) -> bool:
     """Return True when payload is a response (has id, no method)."""
     return "id" in payload and "method" not in payload

codex_app_server_sdk-0.3.2/tests/test_approval_requests.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any
+
+from codex_app_server_sdk import (
+    CodexClient,
+    CommandApprovalDecision,
+    CommandApprovalRequest,
+    CommandApprovalWithExecpolicyAmendment,
+    FileChangeApprovalDecision,
+    FileChangeApprovalRequest,
+)
+from codex_app_server_sdk.transport import Transport
+
+
+class ApprovalTransport(Transport):
+    def __init__(self) -> None:
+        self._incoming: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self.sent: list[dict[str, Any]] = []
+
+    async def connect(self) -> None:
+        return None
+
+    async def send(self, payload: Mapping[str, Any]) -> None:
+        self.sent.append(dict(payload))
+
+    async def recv(self) -> dict[str, Any]:
+        return await self._incoming.get()
+
+    async def close(self) -> None:
+        return None
+
+
+async def _wait_for_sent_message(
+    transport: ApprovalTransport,
+    *,
+    timeout: float = 1.0,
+) -> dict[str, Any]:
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    while loop.time() < deadline:
+        if transport.sent:
+            return transport.sent[-1]
+        await asyncio.sleep(0.01)
+    raise AssertionError("timed out waiting for transport.send()")
+
+
+def test_approval_request_auto_declines_when_no_handler() -> None:
+    async def _run() -> None:
+        transport = ApprovalTransport()
+        client = await CodexClient(transport, request_timeout=1.0).start()
+        try:
+            await transport._incoming.put(
+                {
+                    "jsonrpc": "2.0",
+                    "id": 101,
+                    "method": "item/commandExecution/requestApproval",
+                    "params": {
+                        "threadId": "thread-1",
+                        "turnId": "turn-1",
+                        "itemId": "item-1",
+                        "command": "rg TODO",
+                        "cwd": "/tmp/project",
+                    },
+                }
+            )
+
+            req = await asyncio.wait_for(anext(client.approval_requests()), timeout=1.0)
+            assert isinstance(req, CommandApprovalRequest)
+            assert req.thread_id == "thread-1"
+            assert req.turn_id == "turn-1"
+            assert req.item_id == "item-1"
+
+            response = await _wait_for_sent_message(transport)
+            assert response["id"] == 101
+            result = response.get("result")
+            assert isinstance(result, dict)
+            assert result["decision"] == "decline"
+        finally:
+            await client.close()
+
+    asyncio.run(_run())
+
+
+def test_approval_request_uses_async_handler_decision() -> None:
+    async def _run() -> None:
+        transport = ApprovalTransport()
+        client = await CodexClient(transport, request_timeout=1.0).start()
+        try:
+            async def _handler(request: Any) -> FileChangeApprovalDecision:
+                assert isinstance(request, FileChangeApprovalRequest)
+                return "accept_for_session"
+
+            client.set_approval_handler(_handler)
+
+            await transport._incoming.put(
+                {
+                    "jsonrpc": "2.0",
+                    "id": 202,
+                    "method": "item/fileChange/requestApproval",
+                    "params": {
+                        "threadId": "thread-2",
+                        "turnId": "turn-2",
+                        "itemId": "item-2",
+                        "reason": "needs write access",
+                    },
+                }
+            )
+
+            response = await _wait_for_sent_message(transport)
+            assert response["id"] == 202
+            result = response.get("result")
+            assert isinstance(result, dict)
+            assert result["decision"] == "acceptForSession"
+        finally:
+            await client.close()
+
+    asyncio.run(_run())
+
+
+def test_approval_request_encodes_execpolicy_amendment_decision() -> None:
+    async def _run() -> None:
+        transport = ApprovalTransport()
+        client = await CodexClient(transport, request_timeout=1.0).start()
+        try:
+            async def _handler(request: Any) -> CommandApprovalDecision:
+                assert isinstance(request, CommandApprovalRequest)
+                return CommandApprovalWithExecpolicyAmendment(["uv", "run"])
+
+            client.set_approval_handler(_handler)
+
+            await transport._incoming.put(
+                {
+                    "jsonrpc": "2.0",
+                    "id": "approval-303",
+                    "method": "item/commandExecution/requestApproval",
+                    "params": {
+                        "threadId": "thread-3",
+                        "turnId": "turn-3",
+                        "itemId": "item-3",
+                    },
+                }
+            )
+
+            response = await _wait_for_sent_message(transport)
+            assert response["id"] == "approval-303"
+            result = response.get("result")
+            assert isinstance(result, dict)
+            decision = result.get("decision")
+            assert isinstance(decision, dict)
+            amendment = decision.get("acceptWithExecpolicyAmendment")
+            assert isinstance(amendment, dict)
+            assert amendment["execpolicy_amendment"] == ["uv", "run"]
+        finally:
+            await client.close()
+
+    asyncio.run(_run())
+
+
+def test_unknown_server_request_still_returns_method_not_found_error() -> None:
+    async def _run() -> None:
+        transport = ApprovalTransport()
+        client = await CodexClient(transport, request_timeout=1.0).start()
+        try:
+            await transport._incoming.put(
+                {
+                    "jsonrpc": "2.0",
+                    "id": 404,
+                    "method": "unknown/request",
+                    "params": {},
+                }
+            )
+            response = await _wait_for_sent_message(transport)
+            assert response["id"] == 404
+            error = response.get("error")
+            assert isinstance(error, dict)
+            assert error["code"] == -32601
+        finally:
+            await client.close()
+
+    asyncio.run(_run())

{codex_app_server_sdk-0.3.1 → codex_app_server_sdk-0.3.2}/uv.lock

@@ -186,7 +186,7 @@ wheels = [
 
 [[package]]
 name = "codex-app-server-sdk"
-version = "0.3.0"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },