feat(api): add reasoning-effort registry with fail-fast validation and settings/env/CLI precedence

- Introduce ReasoningEffort enum and per-provider level/wire registry
- Fail-fast validation in preflight rejects unsupported/unknown levels
- Wire translation: Anthropic thinking budgets, OpenAI reasoning_effort (off omits field)
- Propagate settings.json plugins.reasoningEffort with env/CLI precedence
- Document CLAW_REASONING_EFFORT in .env.example

Author: huagusam

rust/clawcode/claw/.env.example

@@ -21,6 +21,15 @@
 # Sampling temperature (0.0–2.0). Overridden by --temperature flag and /temperature.
 # CLAW_TEMPERATURE=0.7
 
+# Reasoning effort level: off | low | medium | high | max.
+# Low=4096,medium=8192,max=32000
+# Default when unset: Anthropic=high (thinking budget 16384), OpenAI-compat=off
+# (field omitted, server default applies). Overridden by --reasoning-effort and
+# agent frontmatter `reasoning_effort:`. Unsupported levels fail fast before
+# the request is sent (e.g. `max` on native OpenAI, any level but `off` on a
+# non-reasoning model).
+# CLAW_REASONING_EFFORT=high
+
 # --- Paths -------------------------------------------------------------------
 # Custom config directory (default: ~/.claw or ~/.config/claw)
 # CLAW_CONFIG_HOME=/path/to/.claw

rust/clawcode/rust/crates/agents/src/types.rs

@@ -183,10 +183,11 @@ pub struct AgentInput {
     /// reporting parity with the definition.
     #[serde(default)]
     pub mode: Option<String>,
-    /// Optional reasoning-effort level (e.g. `low`/`medium`/`high`) forwarded
-    /// to the provider's `MessageRequest`. When present, the spawned sub-agent
-    /// runs with the agent definition's configured effort instead of the
-    /// provider default.
+    /// Optional reasoning-effort level (`off`/`low`/`medium`/`high`/`max`)
+    /// forwarded to the provider's `MessageRequest`. When present, the spawned
+    /// sub-agent runs with the agent definition's configured effort instead of
+    /// the provider default. `off` disables reasoning; the rest map to a
+    /// provider-specific wire spelling via the reasoning registry.
     #[serde(default)]
     pub reasoning_effort: Option<String>,
     /// Optional `permission:` directives from the agent file frontmatter

rust/clawcode/rust/crates/api/src/error.rs

@@ -76,6 +76,15 @@ pub enum ApiError {
         max_bytes: usize,
         provider: &'static str,
     },
+    /// The requested reasoning-effort level is not supported by the resolved
+    /// model, or the level string is not a recognised level. Produced before
+    /// any network I/O so a stale, mistyped, or model-unsupported level fails
+    /// fast instead of being silently ignored by the backend.
+    UnsupportedReasoningEffort {
+        model: String,
+        level: String,
+        supported: Vec<String>,
+    },
 }
 
 impl ApiError {
@@ -157,7 +166,8 @@ impl ApiError {
             | Self::Json { .. }
             | Self::InvalidSseFrame(_)
             | Self::BackoffOverflow { .. }
-            | Self::RequestBodySizeExceeded { .. } => false,
+            | Self::RequestBodySizeExceeded { .. }
+            | Self::UnsupportedReasoningEffort { .. } => false,
         }
     }
 
@@ -177,7 +187,8 @@ impl ApiError {
             | Self::Json { .. }
             | Self::InvalidSseFrame(_)
             | Self::BackoffOverflow { .. }
-            | Self::RequestBodySizeExceeded { .. } => None,
+            | Self::RequestBodySizeExceeded { .. }
+            | Self::UnsupportedReasoningEffort { .. } => None,
         }
     }
 
@@ -203,6 +214,7 @@ impl ApiError {
             }
             Self::InvalidApiKeyEnv(_) | Self::Io(_) | Self::Json { .. } => "runtime_io",
             Self::RequestBodySizeExceeded { .. } => "request_size",
+            Self::UnsupportedReasoningEffort { .. } => "invalid_request",
         }
     }
 
@@ -227,7 +239,8 @@ impl ApiError {
             | Self::Json { .. }
             | Self::InvalidSseFrame(_)
             | Self::BackoffOverflow { .. }
-            | Self::RequestBodySizeExceeded { .. } => false,
+            | Self::RequestBodySizeExceeded { .. }
+            | Self::UnsupportedReasoningEffort { .. } => false,
         }
     }
 
@@ -258,7 +271,8 @@ impl ApiError {
             | Self::Json { .. }
             | Self::InvalidSseFrame(_)
             | Self::BackoffOverflow { .. }
-            | Self::RequestBodySizeExceeded { .. } => false,
+            | Self::RequestBodySizeExceeded { .. }
+            | Self::UnsupportedReasoningEffort { .. } => false,
         }
     }
 }
@@ -374,6 +388,15 @@ impl Display for ApiError {
                 f,
                 "request body size ({estimated_bytes} bytes) exceeds {provider} limit ({max_bytes} bytes); reduce prompt length or context before retrying"
             ),
+            Self::UnsupportedReasoningEffort {
+                model,
+                level,
+                supported,
+            } => write!(
+                f,
+                "model \"{model}\" does not support reasoning effort \"{level}\"; supported: {}",
+                supported.join(", ")
+            ),
         }
     }
 }

rust/clawcode/rust/crates/api/src/incremental_body.rs

@@ -181,9 +181,10 @@ fn serialise_base(request: &MessageRequest) -> Map<String, Value> {
             map.insert("stop_sequences".into(), serde_json::to_value(v).unwrap_or_default());
         }
     }
-    if let Some(ref v) = request.reasoning_effort {
-        map.insert("reasoning_effort".into(), Value::String(v.clone()));
-    }
+    // `reasoning_effort` is intentionally absent from the Anthropic body: the
+    // level is translated to a `thinking` budget (see `render_anthropic_body`
+    // and `effective_thinking_config`), never carried through as the raw
+    // OpenAI-style field.
     if let Some(ref v) = request.thinking {
         map.insert("thinking".into(), serde_json::to_value(v).unwrap_or_default());
     }

rust/clawcode/rust/crates/api/src/lib.rs

@@ -35,10 +35,15 @@ pub use sse::{parse_frame, SseParser};
 pub use types::{
     ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
     InputContentBlock, InputMessage, MessageDelta, MessageDeltaEvent, MessageRequest,
-    MessageResponse, MessageStartEvent, MessageStopEvent, OutputContentBlock, StreamEvent,
-    ThinkingConfig, ToolChoice, ToolDefinition, ToolResultContentBlock, Usage,
+    MessageResponse, MessageStartEvent, MessageStopEvent, OutputContentBlock, ReasoningEffort,
+    StreamEvent, ThinkingConfig, ToolChoice, ToolDefinition, ToolResultContentBlock, Usage,
 };
 pub use types::render_tools_block;
+pub use providers::reasoning::{
+    anthropic_thinking_budget, default_reasoning_effort, effective_thinking_config,
+    openai_wire_effort, reasoning_levels, supports_level, validate_reasoning_effort,
+    UnsupportedReasoningEffort,
+};
 
 pub use telemetry::{
     AnalyticsEvent, AnthropicRequestProfile, ClientIdentity, JsonlTelemetrySink,

rust/clawcode/rust/crates/api/src/providers/mod.rs

@@ -5,10 +5,12 @@ use std::pin::Pin;
 use serde::Serialize;
 
 use crate::error::ApiError;
-use crate::types::{MessageRequest, MessageResponse};
+use crate::types::{MessageRequest, MessageResponse, ReasoningEffort};
+use crate::providers::reasoning::reasoning_levels;
 
 pub mod anthropic;
 pub mod openai_compat;
+pub mod reasoning;
 
 #[allow(dead_code)]
 pub type ProviderFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, ApiError>> + Send + 'a>>;
@@ -242,7 +244,45 @@ pub fn is_local_inference() -> bool {
     false
 }
 
+/// Fail-fast reasoning-effort validation: reject a level the resolved model
+/// does not support, or a level string that is not a recognised level, before
+/// the request leaves the process. Mirrors the dsh `resolveReasoningLevel`
+/// posture — a stale or mistyped level fails here instead of being silently
+/// ignored by the backend.
+///
+/// `None` (no level requested) always passes: the provider's own server
+/// default applies (the `reasoning_effort` field is omitted from the wire).
+fn validate_reasoning_effort_for_request(request: &MessageRequest) -> Result<(), ApiError> {
+    let Some(level_str) = request.reasoning_effort.as_deref() else {
+        return Ok(());
+    };
+    let canonical = resolve_model_alias(&request.model);
+    let provider = detect_provider_kind(&canonical);
+    let supported = reasoning_levels(provider, &canonical);
+    let supported_names: Vec<String> = supported
+        .iter()
+        .map(|level| level.as_str().to_string())
+        .collect();
+    let level = ReasoningEffort::from_name(level_str).ok_or_else(|| {
+        ApiError::UnsupportedReasoningEffort {
+            model: canonical.clone(),
+            level: level_str.to_string(),
+            supported: supported_names.clone(),
+        }
+    })?;
+    if supported.contains(&level) {
+        Ok(())
+    } else {
+        Err(ApiError::UnsupportedReasoningEffort {
+            model: canonical,
+            level: level_str.to_string(),
+            supported: supported_names,
+        })
+    }
+}
+
 pub fn preflight_message_request(request: &MessageRequest) -> Result<(), ApiError> {
+    validate_reasoning_effort_for_request(request)?;
     let Some(limit) = model_token_limit(&request.model) else {
         return Ok(());
     };
@@ -648,6 +688,72 @@ mod tests {
             .expect("models without context metadata should skip the guarded preflight");
     }
 
+    #[test]
+    fn preflight_rejects_unsupported_reasoning_effort() {
+        // `max` is not a level native OpenAI exposes (`off/low/medium/high`
+        // only), so it must fail before any network I/O. The `openai/` prefix
+        // makes provider detection environment-independent.
+        let request = MessageRequest {
+            model: "openai/o4-mini".to_string(),
+            max_tokens: 1024,
+            messages: Arc::new(vec![InputMessage::user_text("think")]),
+            reasoning_effort: Some("max".to_string()),
+            ..Default::default()
+        };
+        let err = preflight_message_request(&request)
+            .expect_err("max must be rejected for native OpenAI reasoning models");
+        assert!(err.to_string().contains("o4-mini"));
+        assert!(err.to_string().contains("max"));
+        assert!(err.to_string().contains("off, low, medium, high"));
+    }
+
+    #[test]
+    fn preflight_rejects_high_against_non_reasoning_model() {
+        // A non-reasoning model exposes only `off`; `high` must fail fast.
+        let request = MessageRequest {
+            model: "gpt-4o".to_string(),
+            max_tokens: 1024,
+            messages: Arc::new(vec![InputMessage::user_text("hi")]),
+            reasoning_effort: Some("high".to_string()),
+            ..Default::default()
+        };
+        let err = preflight_message_request(&request)
+            .expect_err("high must be rejected for non-reasoning models");
+        assert!(err.to_string().contains("gpt-4o"));
+        assert!(err.to_string().contains("high"));
+    }
+
+    #[test]
+    fn preflight_rejects_unrecognised_level_string() {
+        let request = MessageRequest {
+            model: "o4-mini".to_string(),
+            max_tokens: 1024,
+            messages: Arc::new(vec![InputMessage::user_text("hi")]),
+            reasoning_effort: Some("turbo".to_string()),
+            ..Default::default()
+        };
+        let err = preflight_message_request(&request)
+            .expect_err("an unrecognised level string must fail fast");
+        assert!(err.to_string().contains("turbo"));
+    }
+
+    #[test]
+    fn preflight_accepts_off_for_every_model() {
+        let reasoning = |model: &str| MessageRequest {
+            model: model.to_string(),
+            max_tokens: 1024,
+            messages: Arc::new(vec![InputMessage::user_text("hi")]),
+            reasoning_effort: Some("off".to_string()),
+            ..Default::default()
+        };
+        preflight_message_request(&reasoning("gpt-4o"))
+            .expect("off is always supported");
+        preflight_message_request(&reasoning("o4-mini"))
+            .expect("off is always supported");
+        preflight_message_request(&reasoning("claude-sonnet-4-6"))
+            .expect("off is always supported");
+    }
+
     #[test]
     fn parse_dotenv_extracts_keys_handles_comments_quotes_and_export_prefix() {
         // given

rust/clawcode/rust/crates/api/src/providers/openai_compat.rs

@@ -10,10 +10,12 @@ use crate::http_client::build_http_client_or_default;
 use crate::types::{
     ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
     InputContentBlock, InputMessage, MessageDelta, MessageDeltaEvent, MessageRequest,
-    MessageResponse, MessageStartEvent, MessageStopEvent, OutputContentBlock, StreamEvent,
-    ToolChoice, ToolDefinition, ToolResultContentBlock, Usage,
+    MessageResponse, MessageStartEvent, MessageStopEvent, OutputContentBlock, ReasoningEffort,
+    StreamEvent, ToolChoice, ToolDefinition, ToolResultContentBlock, Usage,
 };
 
+use super::reasoning::openai_wire_effort;
+
 use super::{preflight_message_request, Provider, ProviderFuture};
 
 pub const DEFAULT_OPENAI_BASE_URL: &str = "https://api.openai.com/v1";
@@ -951,9 +953,17 @@ pub fn build_chat_completion_request_with_options(
             payload["stop"] = json!(stop);
         }
     }
-    // reasoning_effort for OpenAI-compatible reasoning models (o4-mini, o3, etc.)
-    if let Some(effort) = &request.reasoning_effort {
-        payload["reasoning_effort"] = json!(effort);
+    // reasoning_effort for OpenAI-compatible reasoning models (o4-mini, o3, etc.).
+    // Translate the level string via the registry: `off` omits the field (OpenAI
+    // has no `off` spelling) and other levels emit their wire spelling. An
+    // unrecognised string is omitted here as a defensive fallback — the
+    // preflight validator rejects it before the request reaches this point.
+    if let Some(level_str) = &request.reasoning_effort {
+        if let Some(level) = ReasoningEffort::from_name(level_str) {
+            if let Some(wire) = openai_wire_effort(level) {
+                payload["reasoning_effort"] = json!(wire);
+            }
+        }
     }
 
     payload
@@ -1657,6 +1667,46 @@ mod tests {
         assert!(payload.get("reasoning_effort").is_none());
     }
 
+    #[test]
+    fn reasoning_effort_off_omits_the_field() {
+        // `off` is the "disable reasoning" level: OpenAI has no `off` wire
+        // spelling, so the registry translates it to `None` and the field is
+        // omitted — the provider's own server default (no reasoning) applies.
+        let payload = build_chat_completion_request(
+            &MessageRequest {
+                model: "o4-mini".to_string(),
+                max_tokens: 1024,
+                messages: Arc::new(vec![InputMessage::user_text("skip thinking")]),
+                reasoning_effort: Some("off".to_string()),
+                ..Default::default()
+            },
+            OpenAiCompatConfig::openai(),
+        );
+        assert!(
+            payload.get("reasoning_effort").is_none(),
+            "off must omit reasoning_effort, got: {payload}"
+        );
+    }
+
+    #[test]
+    fn reasoning_effort_unrecognised_string_is_omitted() {
+        // An unrecognised level string is omitted at the emit layer as a
+        // defensive fallback; the preflight validator rejects it before this
+        // point, so a `None` here only signals the request never carried a
+        // valid wire spelling.
+        let payload = build_chat_completion_request(
+            &MessageRequest {
+                model: "o4-mini".to_string(),
+                max_tokens: 1024,
+                messages: Arc::new(vec![InputMessage::user_text("oops")]),
+                reasoning_effort: Some("turbo".to_string()),
+                ..Default::default()
+            },
+            OpenAiCompatConfig::openai(),
+        );
+        assert!(payload.get("reasoning_effort").is_none());
+    }
+
     #[test]
     fn openai_streaming_requests_include_usage_opt_in() {
         let payload = build_chat_completion_request(