Mode B: symbi run spawns a governed Claude Code subprocess (executor=claude_code path via CliExecutor with the SYMBIONT_* env handshake, stdio symbi mcp back-channel, max-turns primary bound + graceful SIGTERM/SIGKILL timeout); add code_reviewer agent, cli-executor on by default, and Mode B docs

Author: symbibot

AGENTS.md

@@ -132,6 +132,29 @@ E2B is a separate hosted-cloud backend, **not** a peer of Tier 1/2/3. Code runs
 |---------|-----------|---------------|-----------|
 | E2B (hosted) | `with { sandbox = "e2b" }` (DSL only — no `--sandbox` flag) | `E2B_API_KEY` env var | Quick-start demos, evaluation without setting up a sandbox host. **Not for production workloads with privacy or compliance requirements.** |
 
+## Managed CLI agents (Mode B)
+
+An agent whose metadata declares `executor = "claude_code"` is run by spawning a
+governed Claude Code subprocess via `crates/runtime/src/cli_executor` (the
+`cli-executor` feature, on by default) instead of the ORGA reasoning loop. The
+reference agent is `agents/code_reviewer.symbi`; the path lives in
+`src/commands/managed_cli.rs`.
+
+`symbi run code_reviewer --target <dir>`:
+- passes the spawn through the policy Gate (fail-closed; allow via Cedar or
+  `SYMBI_INSECURE_ALLOW_ALL=1`);
+- injects the env handshake `SYMBIONT_MANAGED=true`, `SYMBIONT_SESSION_ID`,
+  `SYMBIONT_BUDGET_TOKENS`, `SYMBIONT_BUDGET_TIMEOUT`, `CLAUDE_PROJECT_DIR` (the
+  symbi-claude-code plugin defers its hooks to the outer Gate on `SYMBIONT_MANAGED`);
+- loads the plugin via `--plugin-dir` (resolve order: `--plugin-dir` flag,
+  `SYMBIONT_CLAUDE_PLUGIN_DIR`, then sibling-repo autodetect) and wires the stdio
+  `symbi mcp` back-channel via `--mcp-config --strict-mcp-config`;
+- bounds the run with `--max-turns` (primary, cooperative) and `--budget-timeout`
+  (hard wall-clock backstop; `CliExecutor` kills with graceful SIGTERM → SIGKILL).
+
+Do **not** pass `--bare` to the spawned `claude` — it skips reading `~/.claude`
+(credentials included) and breaks subscription auth.
+
 ## ToolClad Tools
 
 Tools live in `tools/<name>.clad.toml` and are auto-discovered at startup by `symbi up`, the HTTP Input server, and `symbi tools`. The watcher (`crates/runtime/src/toolclad/watcher.rs`) hot-reloads on file changes — no restart needed.

CLAUDE.md

@@ -132,6 +132,29 @@ E2B is a separate hosted-cloud backend, **not** a peer of Tier 1/2/3. Code runs
 |---------|-----------|---------------|-----------|
 | E2B (hosted) | `with { sandbox = "e2b" }` (DSL only — no `--sandbox` flag) | `E2B_API_KEY` env var | Quick-start demos, evaluation without setting up a sandbox host. **Not for production workloads with privacy or compliance requirements.** |
 
+## Managed CLI agents (Mode B)
+
+An agent whose metadata declares `executor = "claude_code"` is run by spawning a
+governed Claude Code subprocess via `crates/runtime/src/cli_executor` (the
+`cli-executor` feature, on by default) instead of the ORGA reasoning loop. The
+reference agent is `agents/code_reviewer.symbi`; the path lives in
+`src/commands/managed_cli.rs`.
+
+`symbi run code_reviewer --target <dir>`:
+- passes the spawn through the policy Gate (fail-closed; allow via Cedar or
+  `SYMBI_INSECURE_ALLOW_ALL=1`);
+- injects the env handshake `SYMBIONT_MANAGED=true`, `SYMBIONT_SESSION_ID`,
+  `SYMBIONT_BUDGET_TOKENS`, `SYMBIONT_BUDGET_TIMEOUT`, `CLAUDE_PROJECT_DIR` (the
+  symbi-claude-code plugin defers its hooks to the outer Gate on `SYMBIONT_MANAGED`);
+- loads the plugin via `--plugin-dir` (resolve order: `--plugin-dir` flag,
+  `SYMBIONT_CLAUDE_PLUGIN_DIR`, then sibling-repo autodetect) and wires the stdio
+  `symbi mcp` back-channel via `--mcp-config --strict-mcp-config`;
+- bounds the run with `--max-turns` (primary, cooperative) and `--budget-timeout`
+  (hard wall-clock backstop; `CliExecutor` kills with graceful SIGTERM → SIGKILL).
+
+Do **not** pass `--bare` to the spawned `claude` — it skips reading `~/.claude`
+(credentials included) and breaks subscription auth.
+
 ## ToolClad Tools
 
 Tools live in `tools/<name>.clad.toml` and are auto-discovered at startup by `symbi up`, the HTTP Input server, and `symbi tools`. The watcher (`crates/runtime/src/toolclad/watcher.rs`) hot-reloads on file changes — no restart needed.

Cargo.toml

@@ -72,7 +72,7 @@ name = "native-execution-example"
 required-features = ["native-sandbox"]
 
 [features]
-default = ["cron", "interactive"]
+default = ["cron", "interactive", "cli-executor"]
 interactive = ["dep:dialoguer"]
 cron = ["symbi-runtime/cron", "dep:cron", "dep:chrono", "dep:chrono-tz"]
 cedar = ["symbi-runtime/cedar", "dep:cedar-policy"]

agents/README.md

@@ -20,6 +20,26 @@ This directory contains ten reusable agent examples that demonstrate core Symbio
 | [SchemaPin Researcher](#schemapin-researcher) | Supply-chain secure research | Only executes cryptographically verified tools and sources |
 | [HITL DevOps](#hitl-devops) | Human-in-the-loop infra | Read-only with cryptographic approval for privilege escalation |
 | [Code Review Pipeline](#code-review-pipeline) | Multi-agent trust boundary | Untrusted developer + AgentPin-authenticated reviewer |
+| [Code Reviewer (Mode B)](#code-reviewer-mode-b) | Governed Claude Code subprocess | `executor = "claude_code"`; spawns Claude Code under CliExecutor with the `SYMBIONT_*` handshake |
+
+### Mode B: Governed Claude Code
+
+**Code Reviewer** (`code_reviewer.symbi`) is the reference *managed-CLI* agent. Its
+metadata declares `executor = "claude_code"`, so `symbi run code_reviewer` spawns
+a governed Claude Code subprocess via the runtime's `CliExecutor` instead of the
+LLM reasoning loop. The spawn passes the policy Gate, sets the `SYMBIONT_MANAGED`
+handshake (the symbi-claude-code plugin then defers its hooks to the outer Gate),
+and wires the stdio `symbi mcp` back-channel.
+
+```bash
+# Allow the spawn at the Gate via a Cedar policy, or for local dev:
+SYMBI_INSECURE_ALLOW_ALL=1 symbi run code_reviewer --target /path/to/repo \
+  --max-turns 12 --budget-timeout 15m
+```
+
+`--max-turns` is the primary cooperative bound; `--budget-timeout` is a hard
+wall-clock backstop. See the "Mode B" section of `docs/getting-started.md` for the
+full env handshake and flag reference.
 
 ### v1.8.0 Governance Examples
 

agents/code_reviewer.symbi

@@ -0,0 +1,51 @@
+metadata {
+    version = "0.1.0"
+    author = "Symbiont Community"
+    description = "Governed code reviewer that runs Claude Code as a Mode B managed subprocess"
+    tags = ["code-review", "claude-code", "mode-b", "managed", "cli-executor"]
+    executor = "claude_code"
+    model = "claude-sonnet-4-5"
+    allowed_tools = "Read,Grep,Glob,Bash(git diff:*),Bash(git log:*),Bash(git status:*)"
+    system_prompt = "You are a senior code reviewer running under Symbiont governance. Review the working tree (prefer the staged and unstaged diff) for correctness bugs, security issues, and clarity problems. Do NOT modify files. Produce a concise, severity-tagged list of findings with file:line references and a one-line summary verdict."
+}
+
+# Mode B (ORGA-managed) agent.
+#
+# `symbi run code_reviewer` reads `executor = "claude_code"` from the metadata
+# above and takes the deterministic CliExecutor path instead of the ORGA
+# reasoning loop. It spawns one governed Claude Code subprocess with:
+#   - the SYMBIONT_* env handshake (SYMBIONT_MANAGED=true + budgets + session id)
+#   - the symbi-claude-code plugin loaded via --plugin-dir, so its hooks detect
+#     managed mode and defer hard enforcement to the outer Gate
+#   - the stdio `symbi mcp` back-channel via --mcp-config (--strict-mcp-config)
+#   - --max-turns as the primary (cooperative) bound; the wall-clock budget
+#     timeout is a hard backstop with graceful SIGTERM -> SIGKILL termination
+#
+# The agent body below documents the intended governance; the managed path
+# enforces it through the policy Gate + the spawned subprocess flags.
+
+agent code_reviewer(target: String) -> Review {
+    capabilities = ["read", "analyze"]
+
+    policy review_only {
+        allow: ["read", "analyze"] if true
+        deny: ["write_data", "execute_code", "network_access"]
+
+        require: {
+            input_sanitization: true
+        }
+
+        audit: {
+            log_level: "info",
+            include_findings: true
+        }
+    }
+
+    with
+        memory = "ephemeral",
+        security = "high",
+        sandbox = "Tier1"
+    {
+        return review(target);
+    }
+}

crates/runtime/src/cli_executor/adapters/claude_code.rs

@@ -18,14 +18,55 @@ use crate::sandbox::ExecutionResult;
 pub struct ClaudeCodeAdapter {
     /// Path or name of the Claude Code executable.
     pub executable_path: String,
-    /// Maximum number of agentic turns before stopping.
+    /// Maximum number of agentic turns before stopping. This is the *primary*
+    /// cooperative bound for managed runs — Claude Code exits cleanly with its
+    /// JSON result when the limit is hit (vs. the wall-clock timeout, which is a
+    /// hard backstop).
     pub max_turns: Option<u32>,
     /// Model to use (e.g. "claude-sonnet-4-5-20250929").
     pub model: Option<String>,
     /// Tools explicitly allowed for this invocation.
     pub allowed_tools: Vec<String>,
     /// Tools explicitly disallowed for this invocation.
     pub disallowed_tools: Vec<String>,
+
+    // ── Mode B (governed subprocess) wiring ───────────────────────────────
+    /// Local plugin directories to load (`--plugin-dir`, repeatable). For Mode B
+    /// this points at the symbi-claude-code plugin so its hooks fire and defer.
+    #[serde(default)]
+    pub plugin_dirs: Vec<String>,
+    /// MCP config passed via `--mcp-config` (a file path or inline JSON).
+    #[serde(default)]
+    pub mcp_config: Option<String>,
+    /// Emit `--strict-mcp-config` so only `mcp_config` is used.
+    #[serde(default)]
+    pub strict_mcp_config: bool,
+    /// Emit `--bare` to skip auto-discovery (plugins/MCP load only via flags).
+    #[serde(default)]
+    pub bare: bool,
+    /// Permission mode for unattended runs (`--permission-mode`, e.g. "dontAsk").
+    #[serde(default)]
+    pub permission_mode: Option<String>,
+    /// Extra system prompt appended via `--append-system-prompt`.
+    #[serde(default)]
+    pub append_system_prompt: Option<String>,
+
+    // ── Mode B env handshake (emitted via non_interactive_env) ────────────
+    /// When true, set `SYMBIONT_MANAGED=true` so the plugin defers enforcement.
+    #[serde(default)]
+    pub managed: bool,
+    /// Correlation id exported as `SYMBIONT_SESSION_ID`.
+    #[serde(default)]
+    pub session_id: Option<String>,
+    /// Token budget exported as `SYMBIONT_BUDGET_TOKENS` (awareness only today).
+    #[serde(default)]
+    pub budget_tokens: Option<u64>,
+    /// Time budget (seconds) exported as `SYMBIONT_BUDGET_TIMEOUT`.
+    #[serde(default)]
+    pub budget_timeout_secs: Option<u64>,
+    /// Project dir exported as `CLAUDE_PROJECT_DIR` so hooks find `.symbiont/`.
+    #[serde(default)]
+    pub project_dir: Option<String>,
 }
 
 impl Default for ClaudeCodeAdapter {
@@ -36,6 +77,17 @@ impl Default for ClaudeCodeAdapter {
             model: None,
             allowed_tools: Vec::new(),
             disallowed_tools: Vec::new(),
+            plugin_dirs: Vec::new(),
+            mcp_config: None,
+            strict_mcp_config: false,
+            bare: false,
+            permission_mode: None,
+            append_system_prompt: None,
+            managed: false,
+            session_id: None,
+            budget_tokens: None,
+            budget_timeout_secs: None,
+            project_dir: None,
         }
     }
 }
@@ -57,6 +109,28 @@ impl AiCliAdapter for ClaudeCodeAdapter {
             "json".to_string(),
         ];
 
+        if self.bare {
+            args.push("--bare".to_string());
+        }
+
+        for dir in &self.plugin_dirs {
+            args.push("--plugin-dir".to_string());
+            args.push(dir.clone());
+        }
+
+        if let Some(ref cfg) = self.mcp_config {
+            args.push("--mcp-config".to_string());
+            args.push(cfg.clone());
+        }
+        if self.strict_mcp_config {
+            args.push("--strict-mcp-config".to_string());
+        }
+
+        if let Some(ref mode) = self.permission_mode {
+            args.push("--permission-mode".to_string());
+            args.push(mode.clone());
+        }
+
         if let Some(turns) = self.max_turns {
             args.push("--max-turns".to_string());
             args.push(turns.to_string());
@@ -84,6 +158,11 @@ impl AiCliAdapter for ClaudeCodeAdapter {
             args.push(ctx.clone());
         }
 
+        if let Some(ref extra) = self.append_system_prompt {
+            args.push("--append-system-prompt".to_string());
+            args.push(extra.clone());
+        }
+
         // The prompt is the final positional argument
         args.push(request.prompt.clone());
 
@@ -93,6 +172,27 @@ impl AiCliAdapter for ClaudeCodeAdapter {
     fn non_interactive_env(&self) -> HashMap<String, String> {
         let mut env = HashMap::new();
         env.insert("CI".to_string(), "true".to_string());
+
+        // Mode B handshake. These are injected here (the executor merges
+        // adapter env *unfiltered*, unlike the caller-env ENV_ALLOWLIST) so the
+        // symbi-claude-code plugin detects managed mode and defers enforcement
+        // to the outer Gate.
+        if self.managed {
+            env.insert("SYMBIONT_MANAGED".to_string(), "true".to_string());
+        }
+        if let Some(ref id) = self.session_id {
+            env.insert("SYMBIONT_SESSION_ID".to_string(), id.clone());
+        }
+        if let Some(tokens) = self.budget_tokens {
+            env.insert("SYMBIONT_BUDGET_TOKENS".to_string(), tokens.to_string());
+        }
+        if let Some(secs) = self.budget_timeout_secs {
+            env.insert("SYMBIONT_BUDGET_TIMEOUT".to_string(), secs.to_string());
+        }
+        if let Some(ref dir) = self.project_dir {
+            env.insert("CLAUDE_PROJECT_DIR".to_string(), dir.clone());
+        }
+
         env
     }
 
@@ -324,6 +424,66 @@ mod tests {
         let adapter = ClaudeCodeAdapter::default();
         let env = adapter.non_interactive_env();
         assert_eq!(env.get("CI"), Some(&"true".to_string()));
+        // Unmanaged adapter emits no handshake vars.
+        assert!(!env.contains_key("SYMBIONT_MANAGED"));
+    }
+
+    #[test]
+    fn test_build_args_mode_b_flags() {
+        let adapter = ClaudeCodeAdapter {
+            bare: true,
+            plugin_dirs: vec!["/plugins/symbi-claude-code".to_string()],
+            mcp_config: Some("/tmp/mcp.json".to_string()),
+            strict_mcp_config: true,
+            permission_mode: Some("dontAsk".to_string()),
+            max_turns: Some(12),
+            append_system_prompt: Some("Review rules.".to_string()),
+            ..Default::default()
+        };
+        let args = adapter.build_args(&sample_request());
+
+        assert!(args.contains(&"--bare".to_string()));
+        let pd = args.iter().position(|a| a == "--plugin-dir").unwrap();
+        assert_eq!(args[pd + 1], "/plugins/symbi-claude-code");
+        let mc = args.iter().position(|a| a == "--mcp-config").unwrap();
+        assert_eq!(args[mc + 1], "/tmp/mcp.json");
+        assert!(args.contains(&"--strict-mcp-config".to_string()));
+        let pm = args.iter().position(|a| a == "--permission-mode").unwrap();
+        assert_eq!(args[pm + 1], "dontAsk");
+        let asp = args
+            .iter()
+            .position(|a| a == "--append-system-prompt")
+            .unwrap();
+        assert_eq!(args[asp + 1], "Review rules.");
+        // Prompt stays the final positional arg.
+        assert_eq!(*args.last().unwrap(), "Fix the bug in main.rs");
+    }
+
+    #[test]
+    fn test_mode_b_env_handshake() {
+        let adapter = ClaudeCodeAdapter {
+            managed: true,
+            session_id: Some("sess-123".to_string()),
+            budget_tokens: Some(100_000),
+            budget_timeout_secs: Some(900),
+            project_dir: Some("/work/target".to_string()),
+            ..Default::default()
+        };
+        let env = adapter.non_interactive_env();
+        assert_eq!(env.get("SYMBIONT_MANAGED"), Some(&"true".to_string()));
+        assert_eq!(
+            env.get("SYMBIONT_SESSION_ID"),
+            Some(&"sess-123".to_string())
+        );
+        assert_eq!(
+            env.get("SYMBIONT_BUDGET_TOKENS"),
+            Some(&"100000".to_string())
+        );
+        assert_eq!(env.get("SYMBIONT_BUDGET_TIMEOUT"), Some(&"900".to_string()));
+        assert_eq!(
+            env.get("CLAUDE_PROJECT_DIR"),
+            Some(&"/work/target".to_string())
+        );
     }
 
     #[tokio::test]

crates/runtime/src/cli_executor/executor.rs

@@ -23,6 +23,11 @@ use super::watchdog::OutputWatchdog;
 /// sensitive host variables (e.g. credentials, session tokens, internal paths)
 /// into spawned AI CLI tool processes. Only variables needed for basic
 /// operation and explicitly-required API keys are allowed through.
+/// Grace period after SIGTERM before escalating to SIGKILL when terminating a
+/// spawned CLI tool. Lets the child (e.g. Claude Code) flush its JSON result
+/// and clean up the working tree instead of being hard-killed mid-write.
+const KILL_GRACE_PERIOD: Duration = Duration::from_secs(5);
+
 const ENV_ALLOWLIST: &[&str] = &[
     "PATH",
     "HOME",
@@ -358,10 +363,24 @@ impl CliExecutor {
         #[cfg(unix)]
         {
             if let Some(id) = child.id() {
+                // Graceful escalation: SIGTERM the process group first so the
+                // child can flush output and clean up, wait a grace period, then
+                // SIGKILL only if it is still alive.
                 // SAFETY: `id` is the PID of a child we spawned (from
                 // `child.id()`), so the process-group id is valid and owned by
                 // this process. `killpg` is a plain libc syscall wrapper; a stale
                 // PID just yields ESRCH, which is harmless here.
+                unsafe {
+                    libc::killpg(id as i32, libc::SIGTERM);
+                }
+                if tokio::time::timeout(KILL_GRACE_PERIOD, child.wait())
+                    .await
+                    .is_ok()
+                {
+                    return; // exited cleanly after SIGTERM
+                }
+                // SAFETY: same invariant as the SIGTERM above; escalate to
+                // SIGKILL because the child ignored the graceful signal.
                 unsafe {
                     libc::killpg(id as i32, libc::SIGKILL);
                 }