feat(sdks): default to frontal-code command and align SDK flags

cli/src/main.rs

@@ -1810,7 +1810,7 @@ fn reject_flags_in_prompt_text(tokens: &[String]) -> Result<(), String> {
 
 /// Config keys a `prompt --config KEY=VALUE` run may override. Anything else is
 /// rejected up front rather than silently ignored.
-const PROMPT_CONFIG_KEYS: &[&str] = &["frontal_base_url", "skip_git_repo_check"];
+const PROMPT_CONFIG_KEYS: &[&str] = &["frontal_base_url", "skip_git_repo_check", "output_schema"];
 
 /// Parses `prompt [-p TEXT] [--stream] [--resume REF] [--config KEY=VALUE] [TEXT...]`.
 fn parse_prompt_subcommand_args(

sdks/rust/README.md

@@ -18,12 +18,12 @@ Requires the `frontal-code` CLI on `PATH` (or provide a custom `command`).
 ## Quickstart
 
 ```rust
-use frontal_code_sdk::{Frontal Code, ThreadInput, ThreadOptions, ThreadRunOptions};
+use frontal_code_sdk::{FrontalCode, ThreadInput, ThreadOptions, ThreadRunOptions};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let frontal-code = Frontal Code::new(Default::default());
-    let thread = frontal-code.start_thread(ThreadOptions::default());
+    let sdk = FrontalCode::new(Default::default());
+    let thread = sdk.start_thread(ThreadOptions::default());
     let turn = thread
         .run(&ThreadInput::Text("Diagnose the test failure".into()), &ThreadRunOptions::default())
         .await?;
@@ -34,17 +34,23 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 ## Features
 
-- `Frontal Code::start_thread` / `Frontal Code::resume_thread`
+- `FrontalCode::start_thread` / `FrontalCode::resume_thread`
 - `Thread::run` (buffered `TurnResult`) and `Thread::run_streamed` (event stream)
-- Structured input entries (`text`, `local_image`)
+- Structured input entries (`text`; `local_image` is accepted in the protocol but
+  the CLI does not yet forward images)
 - `--config` overrides flattened to dotted TOML literals (incl. `baseUrl` →
-  `frontal_base_url`)
+  `frontal_base_url`, `output_schema`)
 - Multi-turn continuation via `--resume`
+- Permission control: `--permission-mode`, `--dangerously-skip-permissions`
+- Tool restriction: `--allowed-tools` (repeatable)
 
 ## Testing
 
 The SDK's tests are hermetic: they spawn a small mock `frontal-code` script instead of
-the real binary, so no API key or network is required.
+the real binary, so no API key or network is required. Authentication is handled by the
+`frontal-code` CLI through provider-specific environment variables (e.g.
+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `FRONTAL_API_KEY`) that you set in your shell;
+this SDK does not inject any environment variables of its own.
 
 ```bash
 cargo test -p frontal-code-sdk

sdks/rust/docs/ARCHITECTURE.md

@@ -104,11 +104,11 @@ All config overrides are flattened to dotted TOML and passed as repeated
 Tests are hermetic - they spawn a mock `frontal-code` script instead of the real CLI:
 
 ```rust
-// tests/mock_frontal-code.sh - emits predetermined JSONL events
+// path/to/frontal-code - emits predetermined JSONL events
 #[tokio::test]
 async fn test_thread_run() {
     let frontal-code = Frontal Code::new(FrontalCodeConfig {
-        command: Some("tests/mock_frontal-code.sh".into()),
+        command: Some("path/to/frontal-code".into()),
         ..Default::default()
     });
     // ... test assertions

sdks/rust/docs/EXAMPLES.md

@@ -257,7 +257,7 @@ mod tests {
     #[tokio::test]
     async fn test_basic_thread() {
         let frontal-code = Frontal Code::new(FrontalCodeConfig {
-            command: Some("tests/mock_frontal-code.sh".into()),
+            command: Some("path/to/frontal-code".into()),
             env: Some([("REQUEST_TYPE".into(), "basic".into())].into()),
             ..Default::default()
         });

sdks/rust/docs/TESTING.md

@@ -2,144 +2,45 @@
 
 ## Test Architecture
 
-Tests are fully hermetic - they do **not** require:
+Most tests are hermetic. They do **not** require:
 - Network access
-- API keys (`CODEX_API_KEY`)
-- Real `frontal-code` CLI binary
+- Provider API keys
+- The real `frontal-code` CLI
 
-Instead, tests use a mock CLI script (`tests/mock_frontal-code.sh`) that emits
-predefined JSONL events over stdout.
+`tests/common/mod.rs` writes a small fake `frontal-code` executable at runtime. The fake emits predefined JSONL events and records the arguments it was called with, so the tests can assert on the exact flags the SDK passes.
+
+The end-to-end suite (`tests/e2e_test.rs`) is the exception. It runs the real CLI against a live model and is skipped unless `FRONTAL_CODE_E2E_BIN` is set.
 
 ## Running Tests
 
 ```bash
-# Run all tests
-cargo test --package frontal-code-sdk
-
-# Run with output
-cargo test --package frontal-code-sdk -- --nocapture
+# Hermetic tests (no CLI, no network)
+cargo test -p frontal-code-sdk
 
-# Run specific test
-cargo test --package frontal-code-sdk test_thread_run -- --nocapture
+# End-to-end against a local Ollama model (see below)
+FRONTAL_CODE_E2E_BIN=$PWD/target/debug/code \
+  cargo test --manifest-path sdks/rust/Cargo.toml --test e2e_test
 ```
 
 ## Test Structure
 
 ```
 tests/
-├── mock_frontal-code.sh          # Mock CLI - emits JSONL events
-├── test_basic.rs          # Basic thread run tests
-├── test_streaming.rs      # Stream event tests
-├── test_structured.rs     # Structured output / JSON Schema tests
-├── test_resume.rs         # Thread resume tests
-├── test_config.rs         # Config override tests
-└── test_errors.rs         # Error handling tests
-```
-
-## Mock CLI Protocol
-
-The mock CLI (`tests/mock_frontal-code.sh`) reads stdin for the request payload
-and writes JSONL events to stdout. It understands these request fields:
-
-```json
-{
-  "input": "user message",
-  "session_id": "optional-resume-id",
-  "config": { "key": "value" },
-  "output_schema": { ... }
-}
-```
-
-The mock responds with events matching the real CLI format:
-
-```jsonl
-{"type":"item_completed","item":{"id":"msg-1","type":"message","content":"Hello!"}}
-{"type":"turn_completed","result":{"final_response":"Hello!","items":[],"usage":{}}}
+├── common/mod.rs        # Shared fake CLI and helpers
+├── integration_test.rs  # Thread run, streaming, resume, and flag mapping (mocked)
+├── config_test.rs       # --config overrides and env handling (mocked)
+└── e2e_test.rs          # Real CLI against a live model (gated)
 ```
 
-## Writing New Tests
+## End-to-End Suite
 
-### 1. Add test events to `mock_frontal-code.sh`
-
-```bash
-case "$REQUEST_TYPE" in
-  "my_new_scenario")
-    cat <<'EOF'
-    {"type":"item_completed","item":{"id":"msg-1","type":"message","content":"Custom response"}}
-    {"type":"turn_completed","result":{"final_response":"Custom response","items":[],"usage":{}}}
-EOF
-    ;;
-esac
-```
-
-### 2. Create test case
-
-```rust
-#[tokio::test]
-async fn test_my_new_scenario() {
-    let frontal-code = Frontal Code::new(FrontalCodeConfig {
-        command: Some("tests/mock_frontal-code.sh".into()),
-        env: Some([("REQUEST_TYPE".into(), "my_new_scenario".into())].into()),
-        ..Default::default()
-    });
-
-    let thread = frontal-code.start_thread(ThreadOptions::default()).unwrap();
-    let result = thread.run(&ThreadInput::Text("test".into()), &ThreadRunOptions::default()).unwrap();
-
-    assert_eq!(result.final_response, "Custom response");
-}
-```
-
-## Test Utilities
-
-### `TestFrontalCodeBuilder` (in `tests/common.rs`)
-
-```rust
-let frontal-code = TestFrontalCodeBuilder::new()
-    .with_mock_response("my_scenario")
-    .with_env("CUSTOM_VAR", "value")
-    .build();
-```
-
-### Event Assertions
-
-```rust
-use frontal_code_sdk::test_utils::{assert_event_seq, assert_final_response};
-
-let mut stream = thread.run_streamed(&input, &options).unwrap();
-assert_event_seq!(&mut stream, ItemCompleted, TurnCompleted);
-let result = assert_final_response(stream).await;
-```
-
-## Continuous Integration
-
-Tests run in GitHub Actions on every PR:
-
-```yaml
-# .github/workflows/rust-sdk.yml
-- uses: actions-rs/cargo@v1
-  with:
-    command: test
-    args: --package frontal-code-sdk --workspace
-```
-
-## Coverage
-
-```bash
-cargo llvm-cov --package frontal-code-sdk --html
-```
-
-## End-to-end suite (real CLI)
-
-`tests/e2e_test.rs` runs the real `code` binary against a live model. It is skipped unless `FRONTAL_CODE_E2E_BIN` is set. The default provider is a local Ollama server:
+The default provider is a local Ollama server, so no key is needed:
 
 ```bash
 cargo build -p cli
 ollama pull qwen2.5:1.5b
-FRONTAL_CODE_E2E_BIN="$PWD/target/debug/code" \
+FRONTAL_CODE_E2E_BIN=$PWD/target/debug/code \
   cargo test --manifest-path sdks/rust/Cargo.toml --test e2e_test
 ```
 
-Set `FRONTAL_CODE_E2E_PROVIDER=openai` with `OPENAI_API_KEY` (and `OPENAI_BASE_URL`) to run against a cloud gateway instead.
-
-A skipped run reports as passing, so check that the variables are set before you read a green result.
+Set `FRONTAL_CODE_E2E_PROVIDER=openai` with `OPENAI_API_KEY` (and `OPENAI_BASE_URL`) to run against a cloud gateway instead. A skipped run reports as passing, so check that `FRONTAL_CODE_E2E_BIN` is set before you read a green result.

sdks/rust/src/code.rs

@@ -8,8 +8,6 @@ use std::sync::Arc;
 use crate::protocol::{FrontalCodeOptions, ThreadOptions};
 use crate::thread::Thread;
 
-const REQUIRED_ENV_VARS: &[&str] = &["CODEX_API_KEY"];
-
 /// The two names every install channel provides for the same CLI.
 const COMMAND_NAMES: [&str; 2] = ["frontal-code", "code"];
 
@@ -71,22 +69,17 @@ impl FrontalCode {
   }
 
   /// Build the environment for a spawned CLI. Starts from the ambient
-  /// environment, applies the user-provided `env`, then injects any required
-  /// variables (such as `CODEX_API_KEY`) if still missing.
+  /// environment, applies the user-provided `env`.
+  /// The `frontal-code` CLI authenticates via provider-specific environment
+  /// variables (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) which the caller
+  /// is responsible for setting; this SDK does not inject any of its own.
   pub fn build_env(&self) -> HashMap<String, String> {
     let mut env: HashMap<String, String> = std::env::vars().collect();
     if let Some(user_env) = &self.options.env {
       for (key, value) in user_env {
         env.insert(key.clone(), value.clone());
       }
     }
-    for var in REQUIRED_ENV_VARS {
-      if !env.contains_key(*var) {
-        if let Ok(value) = std::env::var(var) {
-          env.insert((*var).to_string(), value);
-        }
-      }
-    }
     env
   }
 }

sdks/rust/src/protocol.rs

@@ -98,6 +98,10 @@ pub struct ThreadOptions {
   pub model: Option<String>,
   /// Permission mode override.
   pub permission_mode: Option<String>,
+  /// Skip all permission checks (maps to `--dangerously-skip-permissions`).
+  pub dangerously_skip_permissions: bool,
+  /// Restrict enabled tools (maps to `--allowed-tools`, repeatable).
+  pub allowed_tools: Option<Vec<String>>,
   /// Thread-level CLI `--config` overrides (precedence over global).
   pub config: Option<serde_json::Value>,
 }

sdks/rust/src/spawn.rs

@@ -182,7 +182,14 @@ pub async fn run_turn_buffered(
         usage = u.clone();
         session_id = sid.clone();
       }
-      _ => {}
+      FrontalCodeEvent::TurnFailed { error } => {
+        let stderr = stderr_buffer.lock().await.clone();
+        return Err(FrontalCodeError::Exit {
+          code: None,
+          stderr: format!("frontal-code turn failed: {error}\n{stderr}"),
+        });
+      }
+      FrontalCodeEvent::TurnStarted => {}
     }
   }
 

sdks/rust/src/thread.rs

@@ -89,10 +89,10 @@ impl Thread {
     let (prompt, images) = input.to_prompt_and_images();
 
     let mut args = vec!["prompt".to_string(), "-p".to_string(), prompt];
-    for image in &images {
-      args.push("--image".to_string());
-      args.push(image.clone());
-    }
+    // `local_image` entries are kept in the protocol for forward compatibility,
+    // but the `frontal-code` CLI does not yet accept `--image`, so only text
+    // entries are concatenated into the prompt.
+    let _ = images;
     if let Some(provider) = &self.options.provider {
       args.push("--provider".to_string());
       args.push(provider.clone());
@@ -105,6 +105,15 @@ impl Thread {
       args.push("--permission-mode".to_string());
       args.push(permission_mode.clone());
     }
+    if self.options.dangerously_skip_permissions {
+      args.push("--dangerously-skip-permissions".to_string());
+    }
+    if let Some(tools) = &self.options.allowed_tools {
+      for tool in tools {
+        args.push("--allowed-tools".to_string());
+        args.push(tool.clone());
+      }
+    }
     if let Some(id) = session_id {
       args.push("--resume".to_string());
       args.push(id.to_string());

sdks/rust/tests/integration_test.rs

@@ -140,7 +140,7 @@ async fn subsequent_turns_pass_resume() {
 }
 
 #[tokio::test]
-async fn images_emit_image_flags() {
+async fn images_do_not_emit_image_flags() {
   let mock = MockFrontalCode::new(SINGLE_TURN, 0);
   let frontal_code = code_for(&mock);
   let entries = vec![
@@ -160,16 +160,49 @@ async fn images_emit_image_flags() {
     .await
     .expect("run");
   let args = mock.captured_args();
-  let image_indexes: Vec<usize> = args
+  assert!(!args.iter().any(|a| a == "--image"));
+  assert!(args.contains(&"describe these".to_string()));
+}
+
+#[tokio::test]
+async fn dangerously_skip_permissions_emits_flag() {
+  let mock = MockFrontalCode::new(SINGLE_TURN, 0);
+  let frontal_code = code_for(&mock);
+  frontal_code
+    .start_thread(ThreadOptions {
+      dangerously_skip_permissions: true,
+      ..Default::default()
+    })
+    .run(&ThreadInput::Text("x".into()), &ThreadRunOptions::default())
+    .await
+    .expect("run");
+  assert!(mock
+    .captured_args()
+    .contains(&"--dangerously-skip-permissions".to_string()));
+}
+
+#[tokio::test]
+async fn allowed_tools_emit_flags() {
+  let mock = MockFrontalCode::new(SINGLE_TURN, 0);
+  let frontal_code = code_for(&mock);
+  frontal_code
+    .start_thread(ThreadOptions {
+      allowed_tools: Some(vec!["read".into(), "bash".into()]),
+      ..Default::default()
+    })
+    .run(&ThreadInput::Text("x".into()), &ThreadRunOptions::default())
+    .await
+    .expect("run");
+  let args = mock.captured_args();
+  let tool_indexes: Vec<usize> = args
     .iter()
     .enumerate()
-    .filter(|(_, a)| *a == "--image")
+    .filter(|(_, a)| *a == "--allowed-tools")
     .map(|(i, _)| i)
     .collect();
-  assert_eq!(image_indexes.len(), 2);
-  assert_eq!(args[image_indexes[0] + 1], "./ui.png");
-  assert_eq!(args[image_indexes[1] + 1], "./diagram.jpg");
-  assert!(args.contains(&"describe these".to_string()));
+  assert_eq!(tool_indexes.len(), 2);
+  assert_eq!(args[tool_indexes[0] + 1], "read");
+  assert_eq!(args[tool_indexes[1] + 1], "bash");
 }
 
 #[tokio::test]