document output schema behavior

Co-authored-by: Codex <noreply@openai.com>

Author: charley-oai

codex-rs/app-server-protocol/schema/json/ClientRequest.json

@@ -2570,7 +2570,7 @@
           ]
         },
         "outputSchema": {
-          "description": "Optional JSON Schema used to constrain the final assistant message for this turn."
+          "description": "Optional JSON Schema used to constrain the final assistant message for this turn.\n\nWhen set, Codex requests a strict JSON response matching this schema. This applies only to the final assistant message for the current turn; it does not constrain tool calls or become the default for later turns."
         },
         "personality": {
           "anyOf": [

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json

@@ -15250,7 +15250,7 @@
             ]
           },
           "outputSchema": {
-            "description": "Optional JSON Schema used to constrain the final assistant message for this turn."
+            "description": "Optional JSON Schema used to constrain the final assistant message for this turn.\n\nWhen set, Codex requests a strict JSON response matching this schema. This applies only to the final assistant message for the current turn; it does not constrain tool calls or become the default for later turns."
           },
           "personality": {
             "anyOf": [

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json

@@ -14044,7 +14044,7 @@
           ]
         },
         "outputSchema": {
-          "description": "Optional JSON Schema used to constrain the final assistant message for this turn."
+          "description": "Optional JSON Schema used to constrain the final assistant message for this turn.\n\nWhen set, Codex requests a strict JSON response matching this schema. This applies only to the final assistant message for the current turn; it does not constrain tool calls or become the default for later turns."
         },
         "personality": {
           "anyOf": [

codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json

@@ -527,7 +527,7 @@
       ]
     },
     "outputSchema": {
-      "description": "Optional JSON Schema used to constrain the final assistant message for this turn."
+      "description": "Optional JSON Schema used to constrain the final assistant message for this turn.\n\nWhen set, Codex requests a strict JSON response matching this schema. This applies only to the final assistant message for the current turn; it does not constrain tool calls or become the default for later turns."
     },
     "personality": {
       "anyOf": [

codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts

@@ -36,7 +36,11 @@ summary?: ReasoningSummary | null, /**
  * Override the personality for this turn and subsequent turns.
  */
 personality?: Personality | null, /**
- * Optional JSON Schema used to constrain the final assistant message for this turn.
+ * Optional JSON Schema used to constrain the final assistant message for
+ * this turn.
+ *
+ * When set, Codex requests a strict JSON response matching this schema.
+ * This applies only to the final assistant message for the current turn, * it does not constrain tool calls or become the default for later turns.
  */
 outputSchema?: JsonValue | null, /**
  * EXPERIMENTAL - Set a pre-set collaboration mode.

codex-rs/app-server-protocol/src/protocol/v1.rs

@@ -429,7 +429,12 @@ pub struct SendUserTurnParams {
     pub service_tier: Option<Option<ServiceTier>>,
     pub effort: Option<ReasoningEffort>,
     pub summary: ReasoningSummary,
-    /// Optional JSON Schema used to constrain the final assistant message for this turn.
+    /// Optional JSON Schema used to constrain the final assistant message for
+    /// this turn.
+    ///
+    /// When set, Codex requests a strict JSON response matching this schema.
+    /// This applies only to the final assistant message for the current turn.
+    /// It does not constrain tool calls or become the default for later turns.
     pub output_schema: Option<serde_json::Value>,
 }
 

codex-rs/app-server-protocol/src/protocol/v2.rs

@@ -2985,7 +2985,12 @@ pub struct TurnStartParams {
     /// Override the personality for this turn and subsequent turns.
     #[ts(optional = nullable)]
     pub personality: Option<Personality>,
-    /// Optional JSON Schema used to constrain the final assistant message for this turn.
+    /// Optional JSON Schema used to constrain the final assistant message for
+    /// this turn.
+    ///
+    /// When set, Codex requests a strict JSON response matching this schema.
+    /// This applies only to the final assistant message for the current turn;
+    /// it does not constrain tool calls or become the default for later turns.
     #[ts(optional = nullable)]
     pub output_schema: Option<JsonValue>,
 

codex-rs/app-server/README.md

@@ -401,7 +401,9 @@ Turns attach user input (text or images) to a thread and trigger Codex generatio
 - `{"type":"image","url":"https://…png"}`
 - `{"type":"localImage","path":"/tmp/screenshot.png"}`
 
-You can optionally specify config overrides on the new turn. If specified, these settings become the default for subsequent turns on the same thread. `outputSchema` applies only to the current turn.
+You can optionally specify config overrides on the new turn. If specified, these settings become the default for subsequent turns on the same thread. `outputSchema` is the exception: it applies only to the current turn.
+
+When `outputSchema` is set, Codex asks the model for a strict JSON final answer matching that schema. This constrains only the final assistant message for the turn. It does not affect tool-call arguments or outputs, and it does not persist as the default for later turns.
 
 ```json
 { "method": "turn/start", "id": 30, "params": {

codex-rs/core/src/tools/handlers/shell.rs

@@ -343,10 +343,14 @@ impl ShellHandler {
         .map_err(FunctionCallError::RespondToModel)?;
 
         // Approval policy guard for the sandboxed additional-permissions flow.
-        if exec_params.sandbox_permissions.uses_additional_permissions() && !matches!(
-            turn.approval_policy.value(),
-            codex_protocol::protocol::AskForApproval::OnRequest
-        ) {
+        if exec_params
+            .sandbox_permissions
+            .uses_additional_permissions()
+            && !matches!(
+                turn.approval_policy.value(),
+                codex_protocol::protocol::AskForApproval::OnRequest
+            )
+        {
             let approval_policy = turn.approval_policy.value();
             return Err(FunctionCallError::RespondToModel(format!(
                 "approval policy is {approval_policy:?}; reject command — you should not ask for additional sandbox permissions if the approval policy is {approval_policy:?}"

codex-rs/core/src/tools/handlers/unified_exec.rs

@@ -171,10 +171,12 @@ impl ToolHandler for UnifiedExecHandler {
                 let request_permission_enabled =
                     session.features().enabled(Feature::RequestPermissions);
 
-                if sandbox_permissions.uses_additional_permissions() && !matches!(
-                    context.turn.approval_policy.value(),
-                    codex_protocol::protocol::AskForApproval::OnRequest
-                ) {
+                if sandbox_permissions.uses_additional_permissions()
+                    && !matches!(
+                        context.turn.approval_policy.value(),
+                        codex_protocol::protocol::AskForApproval::OnRequest
+                    )
+                {
                     let approval_policy = context.turn.approval_policy.value();
                     manager.release_process_id(&process_id).await;
                     return Err(FunctionCallError::RespondToModel(format!(