feat(api): add agent session review and tool settings

.castiron.stats.yml

@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: 287e1fa6-451c-4f5f-9a80-498c77a0bd65
-openapi_spec_hash: 17689beb6a2da96f6cf9e5ac1e758a99
-openapi_transformed_spec_hash: 75a7f7b19910025d8f8f8aa1556d9b69
+generation_id: 92191688-2814-4240-a392-408609958bf7
+openapi_spec_hash: c3c2cc244c107fdd6e624a7b961015a9
+openapi_transformed_spec_hash: 5b121d4b6cca6573c41db323a7399527
 config_hash: b707b209c892562880c415693d111ad6
-codegen_sha: b79c2ec277007e5a097e73a710864b77338da840
-codegen_hash: 7acc6ff9d93bbfd3be9e38f79d6b509bfd063f80cdd751f997b86e000327b9ae
+codegen_sha: 877cf0eac8dabd1578d463ff47f140c493bd4d1a
+codegen_hash: 78d280346819510f8ed577aad3d2df4df8dab155df63a48d6ae06e50a98111aa

api_reference/openapi.transformed.yml

@@ -33545,7 +33545,7 @@ paths:
     post:
       operationId: updateAgentSession
       summary: Update an agent session
-      description: Updates session metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).
+      description: Updates session tools, metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).
       tags:
       - Agents
       parameters:
@@ -92393,6 +92393,9 @@ components:
           - $ref: '#/components/schemas/TokenUsageResource'
           - type: 'null'
           description: Best-effort token usage for the session, or null if unknown. Recorded usage may change.
+        review:
+          $ref: '#/components/schemas/SessionReviewResource'
+          description: Review applied to eligible actions in this session. Omitted when review is none and automatic review is not enabled. Omission means none.
         spend_control:
           $ref: '#/components/schemas/SessionSpendControlResource'
           description: Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object.
@@ -92511,6 +92514,9 @@ components:
           type: boolean
           default: false
           description: Whether to stream session events as server-sent events. Defaults to `false`.
+        review:
+          $ref: '#/components/schemas/SessionReviewParam'
+          description: Action review mode. Omit to use none.
         spend_control:
           anyOf:
           - $ref: '#/components/schemas/SessionSpendControlParam'
@@ -94121,14 +94127,23 @@ components:
           - type: 'null'
           description: Omit to keep the current tier. Null resets it to auto.
           x-openai-go-optional-enum: true
+        tools:
+          type:
+          - array
+          - 'null'
+          items:
+            $ref: '#/components/schemas/AgentToolConfigParam'
+          minItems: 0
+          maxItems: 16384
+          description: Replaces the session tools. Functions and MCP servers change on the next model call. Built-in tools change by the next turn. Omit to keep the current tools, or pass null or an empty array to clear them.
       additionalProperties: false
-      description: Model settings that can change after session creation.
+      description: Agent settings that can change after session creation.
     UpdateAgentSessionParams:
       type: object
       properties:
         agent:
           $ref: '#/components/schemas/UpdateSessionAgentParam'
-          description: Model settings for subsequent turns. Omitted fields stay unchanged.
+          description: Agent settings to update on this session. Omitted fields stay unchanged.
         metadata:
           type:
           - object
@@ -94144,6 +94159,9 @@ components:
           minProperties: 0
           maxProperties: 16
           description: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.
+        review:
+          $ref: '#/components/schemas/SessionReviewParam'
+          description: Default action review for new root turns. Existing turns and their subagents keep their review mode.
         spend_control:
           anyOf:
           - $ref: '#/components/schemas/SessionSpendControlParam'
@@ -111902,6 +111920,21 @@ components:
       - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent'
       discriminator:
         propertyName: type
+    SessionReviewParam:
+      type: string
+      enum:
+      - none
+      - auto_review
+      x-enumDescriptions:
+      - Keep the existing execution behavior without automatic action review.
+      - Review eligible actions automatically. Deny manual approval fallbacks.
+      description: Review applied to eligible actions in a session.
+    SessionReviewResource:
+      type: string
+      enum:
+      - none
+      - auto_review
+      description: The configured action review mode.
     SessionSpendControlResource:
       type: object
       properties:

scripts/castiron/generated-files.json

@@ -287,7 +287,7 @@
     },
     "src/openai/resources/beta/agents/sessions/sessions.py": {
       "mode": "100644",
-      "sha256": "d1719b767d0b16e9eba1c405a66e9c11874da30a6ba2fa873603d1e6a9f6f7e2"
+      "sha256": "264c1c83bc479591e9b70166208a4384e7266c7176a3fea7971f1d876ef54294"
     },
     "src/openai/resources/beta/agents/sessions/subagents/__init__.py": {
       "mode": "100644",
@@ -1703,7 +1703,7 @@
     },
     "src/openai/types/beta/agent_session.py": {
       "mode": "100644",
-      "sha256": "4dbf44628416d12c8cdf46a6a73e293239736ca23dfb096e39850d68ffe5daa6"
+      "sha256": "c3563e065a7d80a1ee1676d31cd4b835a2363a691db2ac778f8a0c13f265e37b"
     },
     "src/openai/types/beta/agent_session_assistant_message.py": {
       "mode": "100644",
@@ -2019,15 +2019,15 @@
     },
     "src/openai/types/beta/agents/session_create_params.py": {
       "mode": "100644",
-      "sha256": "d4566c2d07b1a1469e929763fa12e626cb1dbeae6dedfd00648f8220b4af8581"
+      "sha256": "89d1618c6a0a6ef4791ee9376bbd8fdd512b8f0c259eb551c0c27281cbf61170"
     },
     "src/openai/types/beta/agents/session_list_params.py": {
       "mode": "100644",
       "sha256": "2de32d51ce2cfdbcf2224acfa8b04a28234717d6c373a3d68ee66bac90f75d2d"
     },
     "src/openai/types/beta/agents/session_update_params.py": {
       "mode": "100644",
-      "sha256": "de3b4a42dfa9591dc07086c3ac888502c8dd0d3c7e77c82969a10a116dcee18e"
+      "sha256": "595ab57453c5678034088224417b1946dc37f4dd11e28c7f6df49d75d7dd3dd0"
     },
     "src/openai/types/beta/agents/sessions/__init__.py": {
       "mode": "100644",
@@ -7715,7 +7715,7 @@
     },
     "tests/api_resources/beta/agents/test_sessions.py": {
       "mode": "100644",
-      "sha256": "8cfecc54a8e76b3714fa35298725eb6b315750fe5a2b112fff6185e14df8f831"
+      "sha256": "3c3b516e8fb4271b93de010045026578ca1f38ba0310491cb6d1a60e61d5de23"
     },
     "tests/api_resources/beta/agents/test_vaults.py": {
       "mode": "100644",

src/openai/resources/beta/agents/sessions/sessions.py

@@ -164,6 +164,7 @@ def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         stream: Literal[False] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
@@ -185,6 +186,7 @@ def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
         extra_headers: Headers | None = None,
@@ -205,6 +207,7 @@ def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
         extra_headers: Headers | None = None,
@@ -224,6 +227,7 @@ def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         stream: Literal[False] | Literal[True] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
@@ -242,6 +246,7 @@ def create(
                 "agent_id": agent_id,
                 "input": input,
                 "metadata": metadata,
+                "review": review,
                 "spend_control": spend_control,
                 "vault_ids": vault_ids,
             },
@@ -318,6 +323,7 @@ def update(
         *,
         agent: session_update_params.Agent | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_update_params.SpendControl] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -326,19 +332,26 @@ def update(
         extra_body: Body | None = None,
         timeout: float | httpx2.Timeout | None | NotGiven = not_given,
     ) -> AgentSession:
-        """Updates session metadata, model, reasoning effort, or service tier.
+        """Updates session tools, metadata, model, reasoning effort, or service tier.
 
         Model
         settings apply to subsequent turns. Omitted fields are unchanged. See
         [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).
 
         Args:
-          agent: Model settings for subsequent turns. Omitted fields stay unchanged.
+          agent: Agent settings to update on this session. Omitted fields stay unchanged.
 
           metadata: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it.
               Up to 16 string key-value pairs, with keys up to 64 and values up to 512
               characters.
 
+          review: Default action review for new root turns. Existing turns and their subagents
+              keep their review mode.
+
+              - `none` - Keep the existing execution behavior without automatic action review.
+              - `auto_review` - Review eligible actions automatically. Deny manual approval
+                fallbacks.
+
           spend_control: Omit to retain the limit; null or a null limit removes it without resetting
               spend.
 
@@ -359,6 +372,7 @@ def update(
                 {
                     "agent": agent,
                     "metadata": metadata,
+                    "review": review,
                     "spend_control": spend_control,
                 },
                 session_update_params.SessionUpdateParams,
@@ -573,6 +587,7 @@ async def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         stream: Literal[False] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
@@ -594,6 +609,7 @@ async def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
         extra_headers: Headers | None = None,
@@ -614,6 +630,7 @@ async def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
         extra_headers: Headers | None = None,
@@ -633,6 +650,7 @@ async def create(
         agent_id: str | Omit = omit,
         input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_create_params.SpendControl] | Omit = omit,
         stream: Literal[False] | Literal[True] | Omit = omit,
         vault_ids: Optional[SequenceNotStr[str]] | Omit = omit,
@@ -651,6 +669,7 @@ async def create(
                 "agent_id": agent_id,
                 "input": input,
                 "metadata": metadata,
+                "review": review,
                 "spend_control": spend_control,
                 "vault_ids": vault_ids,
             },
@@ -727,6 +746,7 @@ async def update(
         *,
         agent: session_update_params.Agent | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
+        review: Literal["none", "auto_review"] | Omit = omit,
         spend_control: Optional[session_update_params.SpendControl] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -735,19 +755,26 @@ async def update(
         extra_body: Body | None = None,
         timeout: float | httpx2.Timeout | None | NotGiven = not_given,
     ) -> AgentSession:
-        """Updates session metadata, model, reasoning effort, or service tier.
+        """Updates session tools, metadata, model, reasoning effort, or service tier.
 
         Model
         settings apply to subsequent turns. Omitted fields are unchanged. See
         [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).
 
         Args:
-          agent: Model settings for subsequent turns. Omitted fields stay unchanged.
+          agent: Agent settings to update on this session. Omitted fields stay unchanged.
 
           metadata: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it.
               Up to 16 string key-value pairs, with keys up to 64 and values up to 512
               characters.
 
+          review: Default action review for new root turns. Existing turns and their subagents
+              keep their review mode.
+
+              - `none` - Keep the existing execution behavior without automatic action review.
+              - `auto_review` - Review eligible actions automatically. Deny manual approval
+                fallbacks.
+
           spend_control: Omit to retain the limit; null or a null limit removes it without resetting
               spend.
 
@@ -768,6 +795,7 @@ async def update(
                 {
                     "agent": agent,
                     "metadata": metadata,
+                    "review": review,
                     "spend_control": spend_control,
                 },
                 session_update_params.SessionUpdateParams,

src/openai/types/beta/agent_session.py

@@ -287,6 +287,13 @@ class AgentSession(BaseModel):
     vault_ids: List[str]
     """The IDs of vaults made available to the session."""
 
+    review: Optional[Literal["none", "auto_review"]] = None
+    """Review applied to eligible actions in this session.
+
+    Omitted when review is none and automatic review is not enabled. Omission means
+    none.
+    """
+
     spend_control: Optional[SpendControl] = None
     """Configured spending limit and best-effort consumption, in USD cents.
 

src/openai/types/beta/agents/session_create_params.py

@@ -57,6 +57,14 @@ class SessionCreateParamsBase(TypedDict, total=False):
     characters. Omission or null defaults to an empty map.
     """
 
+    review: Literal["none", "auto_review"]
+    """Action review mode. Omit to use none.
+
+    - `none` - Keep the existing execution behavior without automatic action review.
+    - `auto_review` - Review eligible actions automatically. Deny manual approval
+      fallbacks.
+    """
+
     spend_control: Optional[SpendControl]
     """Optional spending limit in USD cents.