codex-python-sdk 0.1.0__tar.gz → 0.2.0__tar.gz

{codex_python_sdk-0.1.0 → codex_python_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-python-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python wrapper for Codex app-server JSON-RPC interface
 Author: Henry_spdcoding
 License-Expression: MIT
@@ -98,8 +98,8 @@ codex-python-sdk-demo --mode demo
 codex-python-sdk-demo --mode full
 ```
 
-Note: the demo runner uses permissive hooks (`accept` for command/file approvals and empty tool-input answers) so it can run unattended.
-Use stricter hooks or policy engines in production.
+Note: the demo runner uses explicit permissive hooks (`accept` for command/file approvals and empty tool-input answers) so it can run unattended.
+The SDK defaults are now fail-closed; keep permissive behavior explicit in demos and automation.
 
 ## Mental Model: How It Works
 
@@ -118,40 +118,53 @@ For a deeper walkthrough, see `docs/core_mechanism.md`.
 ## Safety Defaults (Important)
 
 Default behavior without hooks/policy:
-- Command approval: `accept`
-- File change approval: `accept`
+- Command approval: `decline`
+- File change approval: `decline`
+- Permissions approval: empty grant with `turn` scope
+- MCP elicitation: `decline`
 - Tool user input: empty answers
 - Tool call: failure response with explanatory text
 
-This is convenient for unattended demos, but not production-safe.
+This is production-safer by default, but may block unattended workflows unless you opt into looser hooks.
 
-Recommended safer setup: enable LLM-judge policy with strict fallback decisions.
+Recommended setup: rely on native automatic approval review and keep local policy deterministic.
 
 ```python
-from codex_python_sdk import PolicyJudgeConfig, create_client
-
-rubric = {
-    "system_rubric": "Allow read-only operations. Decline unknown write operations.",
-    "use_llm_judge": True,
-}
-
-judge_cfg = PolicyJudgeConfig(
-    timeout_seconds=8.0,
-    model="gpt-5",
-    effort="low",
-    fallback_command_decision="decline",
-    fallback_file_change_decision="decline",
+from codex_python_sdk import RuleBasedPolicyEngine, create_client
+
+engine = RuleBasedPolicyEngine(
+    {
+        "system_rubric": "Allow read-only operations. Decline unknown write operations.",
+        "command_rules": [
+            {"name": "readonly-shell", "when": {"command_regex": r"^(pwd|ls|cat|rg)\\b"}, "decision": "accept"}
+        ],
+        "defaults": {"command": "decline", "file_change": "decline", "tool_input": "auto_empty"},
+    }
 )
 
 with create_client(
-    policy_rubric=rubric,
-    policy_judge_config=judge_cfg,
+    automatic_approval_review=True,
+    policy_engine=engine,
 ) as client:
     result = client.responses_create(prompt="Show git status.")
     print(result.text)
 ```
 
-Note: LLM-judge requires a real Codex runtime/account; for deterministic local tests, use `RuleBasedPolicyEngine`.
+`automatic_approval_review=True` enables the runtime's native approval reviewer (`guardian_approval`).
+
+Recommended default operating mode for most repository automation:
+- `automatic_approval_review=True`
+- thread sandbox remains `workspace-write`
+- thread approval policy remains `on-request`
+
+This gives the agent writable access inside the workspace while keeping sandboxing and approval flows intact.
+It is usually the right default for coding agents that only need to read and write within the current repo.
+
+Do not treat this as equivalent to bypass mode:
+- `danger-full-access` removes sandbox restrictions for command execution
+- `--dangerously-bypass-approvals-and-sandbox` skips both approvals and sandbox protections
+
+Those higher-permission modes should stay explicit opt-ins for externally sandboxed or highly trusted environments.
 
 ## Install
 
@@ -190,6 +203,11 @@ Factory:
 - `create_client(**kwargs) -> CodexAgenticClient`
 - `create_async_client(**kwargs) -> AsyncCodexAgenticClient`
 
+Important runtime kwargs:
+- `automatic_approval_review=True`
+- `enabled_features=[...]` / `disabled_features=[...]`
+- `enable_web_search` as a compatibility alias for `web_search="live"`
+
 High-frequency response APIs:
 - `responses_create(...) -> AgentResponse`
 - `responses_events(...) -> Iterator[ResponseEvent] / AsyncIterator[ResponseEvent]`
@@ -198,6 +216,9 @@ High-frequency response APIs:
 Thread basics:
 - `thread_start`, `thread_read`, `thread_list`, `thread_archive`
 
+Runtime discovery:
+- `experimental_feature_list(limit=None, cursor=None)`
+
 Account basics:
 - `account_read`, `account_rate_limits_read`
 
@@ -223,8 +244,7 @@ English:
 
 - After `AppServerConnectionError`, recreate the client instead of relying on implicit reconnect behavior.
 - Internal app-server `stderr` buffering keeps only the latest 500 lines in SDK-captured diagnostics.
-- When using low-level server request handlers, method names must be exactly `item`, `tool`, or `requestUserInput`.
-- Policy LLM-judge parsing is strict JSON-only: judge output must be a pure JSON object; embedded JSON snippets in free text are rejected.
+- `review_start(...)` is for code review flows; it is not the same feature as runtime approval review.
 - Invalid command/file policy decision values (allowed: `accept`, `acceptForSession`, `decline`, `cancel`) raise `CodexAgenticError`.
 
 ## Development

{codex_python_sdk-0.1.0 → codex_python_sdk-0.2.0}/README.md

@@ -67,8 +67,8 @@ codex-python-sdk-demo --mode demo
 codex-python-sdk-demo --mode full
 ```
 
-Note: the demo runner uses permissive hooks (`accept` for command/file approvals and empty tool-input answers) so it can run unattended.
-Use stricter hooks or policy engines in production.
+Note: the demo runner uses explicit permissive hooks (`accept` for command/file approvals and empty tool-input answers) so it can run unattended.
+The SDK defaults are now fail-closed; keep permissive behavior explicit in demos and automation.
 
 ## Mental Model: How It Works
 
@@ -87,40 +87,53 @@ For a deeper walkthrough, see `docs/core_mechanism.md`.
 ## Safety Defaults (Important)
 
 Default behavior without hooks/policy:
-- Command approval: `accept`
-- File change approval: `accept`
+- Command approval: `decline`
+- File change approval: `decline`
+- Permissions approval: empty grant with `turn` scope
+- MCP elicitation: `decline`
 - Tool user input: empty answers
 - Tool call: failure response with explanatory text
 
-This is convenient for unattended demos, but not production-safe.
+This is production-safer by default, but may block unattended workflows unless you opt into looser hooks.
 
-Recommended safer setup: enable LLM-judge policy with strict fallback decisions.
+Recommended setup: rely on native automatic approval review and keep local policy deterministic.
 
 ```python
-from codex_python_sdk import PolicyJudgeConfig, create_client
-
-rubric = {
-    "system_rubric": "Allow read-only operations. Decline unknown write operations.",
-    "use_llm_judge": True,
-}
-
-judge_cfg = PolicyJudgeConfig(
-    timeout_seconds=8.0,
-    model="gpt-5",
-    effort="low",
-    fallback_command_decision="decline",
-    fallback_file_change_decision="decline",
+from codex_python_sdk import RuleBasedPolicyEngine, create_client
+
+engine = RuleBasedPolicyEngine(
+    {
+        "system_rubric": "Allow read-only operations. Decline unknown write operations.",
+        "command_rules": [
+            {"name": "readonly-shell", "when": {"command_regex": r"^(pwd|ls|cat|rg)\\b"}, "decision": "accept"}
+        ],
+        "defaults": {"command": "decline", "file_change": "decline", "tool_input": "auto_empty"},
+    }
 )
 
 with create_client(
-    policy_rubric=rubric,
-    policy_judge_config=judge_cfg,
+    automatic_approval_review=True,
+    policy_engine=engine,
 ) as client:
     result = client.responses_create(prompt="Show git status.")
     print(result.text)
 ```
 
-Note: LLM-judge requires a real Codex runtime/account; for deterministic local tests, use `RuleBasedPolicyEngine`.
+`automatic_approval_review=True` enables the runtime's native approval reviewer (`guardian_approval`).
+
+Recommended default operating mode for most repository automation:
+- `automatic_approval_review=True`
+- thread sandbox remains `workspace-write`
+- thread approval policy remains `on-request`
+
+This gives the agent writable access inside the workspace while keeping sandboxing and approval flows intact.
+It is usually the right default for coding agents that only need to read and write within the current repo.
+
+Do not treat this as equivalent to bypass mode:
+- `danger-full-access` removes sandbox restrictions for command execution
+- `--dangerously-bypass-approvals-and-sandbox` skips both approvals and sandbox protections
+
+Those higher-permission modes should stay explicit opt-ins for externally sandboxed or highly trusted environments.
 
 ## Install
 
@@ -159,6 +172,11 @@ Factory:
 - `create_client(**kwargs) -> CodexAgenticClient`
 - `create_async_client(**kwargs) -> AsyncCodexAgenticClient`
 
+Important runtime kwargs:
+- `automatic_approval_review=True`
+- `enabled_features=[...]` / `disabled_features=[...]`
+- `enable_web_search` as a compatibility alias for `web_search="live"`
+
 High-frequency response APIs:
 - `responses_create(...) -> AgentResponse`
 - `responses_events(...) -> Iterator[ResponseEvent] / AsyncIterator[ResponseEvent]`
@@ -167,6 +185,9 @@ High-frequency response APIs:
 Thread basics:
 - `thread_start`, `thread_read`, `thread_list`, `thread_archive`
 
+Runtime discovery:
+- `experimental_feature_list(limit=None, cursor=None)`
+
 Account basics:
 - `account_read`, `account_rate_limits_read`
 
@@ -192,8 +213,7 @@ English:
 
 - After `AppServerConnectionError`, recreate the client instead of relying on implicit reconnect behavior.
 - Internal app-server `stderr` buffering keeps only the latest 500 lines in SDK-captured diagnostics.
-- When using low-level server request handlers, method names must be exactly `item`, `tool`, or `requestUserInput`.
-- Policy LLM-judge parsing is strict JSON-only: judge output must be a pure JSON object; embedded JSON snippets in free text are rejected.
+- `review_start(...)` is for code review flows; it is not the same feature as runtime approval review.
 - Invalid command/file policy decision values (allowed: `accept`, `acceptForSession`, `decline`, `cancel`) raise `CodexAgenticError`.
 
 ## Development

{codex_python_sdk-0.1.0 → codex_python_sdk-0.2.0}/codex_python_sdk/__init__.py

@@ -17,10 +17,8 @@ from .factory import create_async_client, create_client
 from .policy import (
     DEFAULT_POLICY_RUBRIC,
     DefaultPolicyEngine,
-    LlmRubricPolicyEngine,
     PolicyContext,
     PolicyEngine,
-    PolicyJudgeConfig,
     PolicyRubric,
     RuleBasedPolicyEngine,
     build_policy_engine_from_rubric,
@@ -40,11 +38,9 @@ __all__ = [
     "ExecStyleRenderer",
     "DEFAULT_POLICY_RUBRIC",
     "DefaultPolicyEngine",
-    "LlmRubricPolicyEngine",
     "NotAuthenticatedError",
     "PolicyContext",
     "PolicyEngine",
-    "PolicyJudgeConfig",
     "PolicyRubric",
     "ResponseEvent",
     "RuleBasedPolicyEngine",

{codex_python_sdk-0.1.0 → codex_python_sdk-0.2.0}/codex_python_sdk/async_client.py

@@ -21,13 +21,21 @@ from .errors import (
 from .types import AgentResponse, ResponseEvent
 
 if TYPE_CHECKING:
-    from .policy import PolicyContext, PolicyEngine, PolicyJudgeConfig, PolicyRubric
+    from .policy import PolicyContext, PolicyEngine, PolicyRubric
 
 DEFAULT_CLI_COMMAND = "codex"
 DEFAULT_APP_SERVER_ARGS = ["app-server"]
 DEFAULT_NOTIFICATION_BUFFER_LIMIT = 1024
 DEFAULT_STDERR_BUFFER_LIMIT = 500
 DEFAULT_STREAM_IDLE_TIMEOUT_SECONDS = 60.0
+DEFAULT_MCP_ELICITATION_RESULT = {"action": "decline"}
+DEFAULT_PERMISSIONS_APPROVAL_RESULT = {"permissions": {}, "scope": "turn"}
+DEFAULT_FILE_CHANGE_APPROVAL_RESULT = {"decision": "decline"}
+DEFAULT_COMMAND_APPROVAL_RESULT = {"decision": "decline"}
+DEFAULT_THREAD_BASELINE = {
+    "approvalPolicy": "on-request",
+    "sandbox": "workspace-write",
+}
 
 
 class AsyncCodexAgenticClient:
@@ -42,16 +50,20 @@ class AsyncCodexAgenticClient:
         process_cwd: str | None = None,
         default_thread_params: dict[str, Any] | None = None,
         default_turn_params: dict[str, Any] | None = None,
+        automatic_approval_review: bool = True,
+        enabled_features: list[str] | None = None,
+        disabled_features: list[str] | None = None,
         enable_web_search: bool = True,
         server_config_overrides: dict[str, Any] | None = None,
         stream_idle_timeout_seconds: float | None = DEFAULT_STREAM_IDLE_TIMEOUT_SECONDS,
         on_command_approval: Callable[[dict[str, Any]], dict[str, Any] | Awaitable[dict[str, Any]]] | None = None,
         on_file_change_approval: Callable[[dict[str, Any]], dict[str, Any] | Awaitable[dict[str, Any]]] | None = None,
+        on_permissions_approval: Callable[[dict[str, Any]], dict[str, Any] | Awaitable[dict[str, Any]]] | None = None,
         on_tool_request_user_input: Callable[[dict[str, Any]], dict[str, Any] | Awaitable[dict[str, Any]]] | None = None,
+        on_mcp_elicitation_request: Callable[[dict[str, Any]], dict[str, Any] | Awaitable[dict[str, Any]]] | None = None,
         on_tool_call: Callable[[dict[str, Any]], dict[str, Any] | Awaitable[dict[str, Any]]] | None = None,
         policy_engine: "PolicyEngine | None" = None,
         policy_rubric: "PolicyRubric | dict[str, Any] | None" = None,
-        policy_judge_config: "PolicyJudgeConfig | None" = None,
     ) -> None:
         """Create an async app-server client.
 
@@ -62,18 +74,23 @@ class AsyncCodexAgenticClient:
             process_cwd: Working directory used when launching app-server.
             default_thread_params: Baseline params for thread-level requests.
             default_turn_params: Baseline params for turn-level requests.
-            enable_web_search: If true, appends ``--enable web_search`` at launch.
+            automatic_approval_review: If true, enables native runtime approval review via
+                ``guardian_approval``.
+            enabled_features: Extra app-server feature flags passed as ``--enable``.
+            disabled_features: Feature flags passed as ``--disable``.
+            enable_web_search: Compatibility alias for ``web_search="live"``.
             server_config_overrides: Config key-values serialized to ``-c key=value``.
             stream_idle_timeout_seconds: Max consecutive seconds without matching turn events
                 before stream wait fails. Set ``None`` to disable this guard.
             on_command_approval: Handler for ``item/commandExecution/requestApproval``.
             on_file_change_approval: Handler for ``item/fileChange/requestApproval``.
+            on_permissions_approval: Handler for ``item/permissions/requestApproval``.
             on_tool_request_user_input: Handler for ``item/tool/requestUserInput``.
+            on_mcp_elicitation_request: Handler for ``mcpServer/elicitation/request``.
             on_tool_call: Handler for ``item/tool/call``.
             policy_engine: Optional policy engine used when explicit hooks are absent.
-            policy_rubric: Optional rubric used to auto-build a policy engine when
+            policy_rubric: Optional rubric used to auto-build a rule-based policy engine when
                 ``policy_engine`` is not provided.
-            policy_judge_config: Optional LLM-judge settings when rubric builds an LLM policy.
         """
 
         self.codex_command = codex_command
@@ -81,28 +98,32 @@ class AsyncCodexAgenticClient:
         self.env = os.environ.copy() if env is None else env.copy()
 
         self.process_cwd = os.path.abspath(process_cwd or os.getcwd())
-        self.default_thread_params = dict(default_thread_params or {})
+        self.default_thread_params = self._with_thread_baseline(default_thread_params)
         self.default_turn_params = dict(default_turn_params or {})
+        self.automatic_approval_review = automatic_approval_review
+        self.enabled_features = self._normalize_feature_flags(enabled_features)
+        self.disabled_features = self._normalize_feature_flags(disabled_features)
+        if self.automatic_approval_review:
+            if "guardian_approval" in self.disabled_features:
+                raise CodexAgenticError(
+                    "automatic_approval_review=True conflicts with disabled feature 'guardian_approval'."
+                )
+            if "guardian_approval" not in self.enabled_features:
+                self.enabled_features.append("guardian_approval")
         self.enable_web_search = enable_web_search
         self.server_config_overrides = dict(server_config_overrides or {})
         self.stream_idle_timeout_seconds = stream_idle_timeout_seconds
         self.on_command_approval = on_command_approval
         self.on_file_change_approval = on_file_change_approval
+        self.on_permissions_approval = on_permissions_approval
         self.on_tool_request_user_input = on_tool_request_user_input
+        self.on_mcp_elicitation_request = on_mcp_elicitation_request
         self.on_tool_call = on_tool_call
         self.policy_engine = policy_engine
         if self.policy_engine is None and policy_rubric is not None:
             from .policy import build_policy_engine_from_rubric
 
-            self.policy_engine = build_policy_engine_from_rubric(
-                policy_rubric,
-                judge_config=policy_judge_config,
-                codex_command=codex_command,
-                app_server_args=app_server_args,
-                env=env,
-                process_cwd=self.process_cwd,
-                server_config_overrides=server_config_overrides,
-            )
+            self.policy_engine = build_policy_engine_from_rubric(policy_rubric)
 
         self._proc: asyncio.subprocess.Process | None = None
         self._reader_task: asyncio.Task[None] | None = None
@@ -201,7 +222,7 @@ class AsyncCodexAgenticClient:
                 init_result = await self._request(
                     "initialize",
                     {
-                        "clientInfo": {"name": "codex-python-sdk", "version": "0.1"},
+                        "clientInfo": {"name": "codex-python-sdk", "version": "0.2.0"},
                         "capabilities": {"experimentalApi": True},
                     },
                     ensure_connected=False,
@@ -277,12 +298,39 @@ class AsyncCodexAgenticClient:
 
     def _build_server_args(self) -> list[str]:
         args = self.app_server_args[:]
+        for feature in self.enabled_features:
+            args.extend(["--enable", feature])
+        for feature in self.disabled_features:
+            args.extend(["--disable", feature])
         if self.enable_web_search:
-            args.extend(["--enable", "web_search"])
+            args.extend(["-c", 'web_search="live"'])
         for key, value in self.server_config_overrides.items():
             args.extend(["-c", f"{key}={self._to_toml_literal(value)}"])
         return args
 
+    @staticmethod
+    def _normalize_feature_flags(features: list[str] | None) -> list[str]:
+        if not features:
+            return []
+        normalized: list[str] = []
+        seen: set[str] = set()
+        for raw in features:
+            feature = str(raw).strip()
+            if not feature or feature in seen:
+                continue
+            seen.add(feature)
+            normalized.append(feature)
+        return normalized
+
+    @staticmethod
+    def _with_thread_baseline(params: dict[str, Any] | None) -> dict[str, Any]:
+        merged = dict(DEFAULT_THREAD_BASELINE)
+        if params:
+            for key, value in params.items():
+                if value is not None:
+                    merged[key] = value
+        return merged
+
     @staticmethod
     def _to_toml_literal(value: Any) -> str:
         if isinstance(value, bool):
@@ -443,7 +491,9 @@ class AsyncCodexAgenticClient:
         handlers: dict[str, Callable[[str, dict[str, Any]], Awaitable[dict[str, Any]]]] = {
             "item/commandExecution/requestApproval": self._handle_command_approval_request,
             "item/fileChange/requestApproval": self._handle_file_change_request,
+            "item/permissions/requestApproval": self._handle_permissions_approval_request,
             "item/tool/requestUserInput": self._handle_tool_user_input_request,
+            "mcpServer/elicitation/request": self._handle_mcp_elicitation_request,
             "item/tool/call": self._handle_tool_call_request,
         }
         handler = handlers.get(method)
@@ -475,7 +525,7 @@ class AsyncCodexAgenticClient:
             "item/commandExecution/requestApproval",
             params,
             handler,
-            {"decision": "accept"},
+            DEFAULT_COMMAND_APPROVAL_RESULT,
         )
 
     async def _handle_file_change_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
@@ -493,7 +543,16 @@ class AsyncCodexAgenticClient:
             "item/fileChange/requestApproval",
             params,
             handler,
-            {"decision": "accept"},
+            DEFAULT_FILE_CHANGE_APPROVAL_RESULT,
+        )
+
+    async def _handle_permissions_approval_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        del method
+        return await self._resolve_server_request(
+            "item/permissions/requestApproval",
+            params,
+            self.on_permissions_approval,
+            DEFAULT_PERMISSIONS_APPROVAL_RESULT,
         )
 
     async def _handle_tool_user_input_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
@@ -514,6 +573,15 @@ class AsyncCodexAgenticClient:
             {"answers": {}},
         )
 
+    async def _handle_mcp_elicitation_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        del method
+        return await self._resolve_server_request(
+            "mcpServer/elicitation/request",
+            params,
+            self.on_mcp_elicitation_request,
+            DEFAULT_MCP_ELICITATION_RESULT,
+        )
+
     async def _handle_tool_call_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
         del method
         return await self._resolve_server_request(
@@ -873,7 +941,7 @@ class AsyncCodexAgenticClient:
             ``ResponseEvent`` objects in arrival order.
         """
 
-        merged_thread_params = self._merge_params(self.default_thread_params, thread_params)
+        merged_thread_params = self._with_thread_baseline(self._merge_params(self.default_thread_params, thread_params))
         merged_turn_params = self._merge_params(self.default_turn_params, turn_params)
 
         if session_id is None:
@@ -1067,7 +1135,7 @@ class AsyncCodexAgenticClient:
     ) -> dict[str, Any]:
         """Create a new thread via ``thread/start``."""
 
-        return await self._request("thread/start", self._merge_params(self.default_thread_params, params))
+        return await self._request("thread/start", self._with_thread_baseline(self._merge_params(self.default_thread_params, params)))
 
     async def thread_read(self, thread_id: str, *, include_turns: bool = False) -> dict[str, Any]:
         """Read one thread by id."""
@@ -1098,7 +1166,7 @@ class AsyncCodexAgenticClient:
         *,
         params: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        merged = self._merge_params(self.default_thread_params, params)
+        merged = self._with_thread_baseline(self._merge_params(self.default_thread_params, params))
         return await self._request("thread/fork", {**merged, "threadId": thread_id})
 
     async def thread_name_set(self, thread_id: str, name: str) -> dict[str, Any]:
@@ -1179,6 +1247,19 @@ class AsyncCodexAgenticClient:
             params["delivery"] = delivery
         return await self._request("review/start", params)
 
+    async def experimental_feature_list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        return await self._request("experimentalFeature/list", params)
+
     async def model_list(self, *, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]:
         params: dict[str, Any] = {}
         if limit is not None: