From 5e78015f8913b8914726724c8ca04049031790be Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Mon, 16 Mar 2026 13:49:55 +0000
Subject: [PATCH 1/8] feat: programmatic tool calling

---
 crates/openfang-kernel/src/kernel.rs          |   3 +
 crates/openfang-kernel/src/registry.rs        |   1 +
 crates/openfang-kernel/src/wizard.rs          |   1 +
 crates/openfang-runtime/src/agent_loop.rs     | 301 +++++++++-
 crates/openfang-runtime/src/lib.rs            |   1 +
 crates/openfang-runtime/src/ptc/executor.rs   | 172 ++++++
 crates/openfang-runtime/src/ptc/ipc_server.rs | 390 +++++++++++++
 crates/openfang-runtime/src/ptc/mod.rs        | 208 +++++++
 .../openfang-runtime/src/ptc/sdk_generator.rs | 538 ++++++++++++++++++
 .../src/ptc/tool_classifier.rs                |  85 +++
 crates/openfang-types/src/agent.rs            |   6 +
 crates/openfang-types/src/config.rs           |  34 ++
 12 files changed, 1735 insertions(+), 5 deletions(-)
 create mode 100644 crates/openfang-runtime/src/ptc/executor.rs
 create mode 100644 crates/openfang-runtime/src/ptc/ipc_server.rs
 create mode 100644 crates/openfang-runtime/src/ptc/mod.rs
 create mode 100644 crates/openfang-runtime/src/ptc/sdk_generator.rs
 create mode 100644 crates/openfang-runtime/src/ptc/tool_classifier.rs

diff --git a/crates/openfang-kernel/src/kernel.rs b/crates/openfang-kernel/src/kernel.rs
index f449addac..0df65dd1d 100644
--- a/crates/openfang-kernel/src/kernel.rs
+++ b/crates/openfang-kernel/src/kernel.rs
@@ -3370,6 +3370,7 @@ impl OpenFangKernel {
                 None
             },
             tool_blocklist: Vec::new(),
+            ptc_enabled: None,
             // Custom profile avoids ToolProfile-based expansion overriding the
             // explicit tool list.
             profile: if !def.tools.is_empty() {
@@ -6631,6 +6632,7 @@ mod tests {
             exec_policy: None,
             tool_allowlist: vec![],
             tool_blocklist: vec![],
+            ptc_enabled: None,
         };
         manifest.capabilities.tools = vec!["file_read".to_string(), "web_fetch".to_string()];
         manifest.capabilities.agent_spawn = true;
@@ -6668,6 +6670,7 @@ mod tests {
             exec_policy: None,
             tool_allowlist: vec![],
             tool_blocklist: vec![],
+            ptc_enabled: None,
         }
     }
 
diff --git a/crates/openfang-kernel/src/registry.rs b/crates/openfang-kernel/src/registry.rs
index 841085ad3..fbb947c0c 100644
--- a/crates/openfang-kernel/src/registry.rs
+++ b/crates/openfang-kernel/src/registry.rs
@@ -395,6 +395,7 @@ mod tests {
                 exec_policy: None,
                 tool_allowlist: vec![],
                 tool_blocklist: vec![],
+                ptc_enabled: None,
             },
             state: AgentState::Created,
             mode: AgentMode::default(),
diff --git a/crates/openfang-kernel/src/wizard.rs b/crates/openfang-kernel/src/wizard.rs
index ad6dafe84..c6cce6b42 100644
--- a/crates/openfang-kernel/src/wizard.rs
+++ b/crates/openfang-kernel/src/wizard.rs
@@ -182,6 +182,7 @@ impl SetupWizard {
             exec_policy: None,
             tool_allowlist: vec![],
             tool_blocklist: vec![],
+            ptc_enabled: None,
         };
 
         let skills_to_install: Vec<String> = intent
diff --git a/crates/openfang-runtime/src/agent_loop.rs b/crates/openfang-runtime/src/agent_loop.rs
index f773def41..42ef4f384 100644
--- a/crates/openfang-runtime/src/agent_loop.rs
+++ b/crates/openfang-runtime/src/agent_loop.rs
@@ -102,6 +102,39 @@ fn append_tool_error_guidance(tool_result_blocks: &mut Vec<ContentBlock>) {
     }
 }
 
+/// System prompt supplement appended when Programmatic Tool Calling (PTC) is enabled.
+const PTC_SYSTEM_PROMPT_SUPPLEMENT: &str = "\n\n\
+## Programmatic Tool Calling (execute_code)\n\n\
+You have access to an `execute_code` tool that runs Python code with tool functions.\n\
+Use `execute_code` whenever you need to:\n\
+- Read or edit multiple files (loop instead of N separate calls)\n\
+- Search and filter results, then print only relevant data\n\
+- Perform any workflow with 2+ tool calls where intermediate data can be filtered\n\
+- Batch operations (create tasks, check endpoints, process items)\n\n\
+**How it works:** Tool functions are plain synchronous Python functions (no async/await).\n\
+Call them directly: `result = file_read(path=\"src/main.ts\")`.\n\
+Tool results go to your code, NOT your context window. Only `print()` output enters\n\
+your context. This dramatically reduces context usage.\n\n\
+**Important rules:**\n\
+- All tool functions are **synchronous** — call them directly, no `await`, no `asyncio`.\n\
+- `print()` is the ONLY way to return data to your context. Slice large output: `print(result[:2000])`\n\
+- Always use try/except for error handling.\n\
+- Some params are renamed to avoid Python reserved words: `type` -> `type_`, `class` -> `class_`, `from` -> `from_`\n\
+- All tool functions return `str`. Parse JSON results with `json.loads(result)` if needed.\n\n\
+**Example — reading and filtering files:**\n\
+```python\n\
+import json\n\
+try:\n\
+    files = [\"src/main.ts\", \"src/config.ts\", \"src/utils.ts\"]\n\
+    for f in files:\n\
+        content = file_read(path=f)\n\
+        if \"TODO\" in content:\n\
+            print(f\"Found TODO in {f}\")\n\
+            print(content[:500])\n\
+except Exception as e:\n\
+    print(f\"Error: {e}\")\n\
+```\n";
+
 /// Strip a provider prefix from a model ID before sending to the API.
 ///
 /// Many models are stored as `provider/org/model` (e.g. `openrouter/google/gemini-2.5-flash`)
@@ -326,6 +359,39 @@ pub async fn run_agent_loop(
     let mut total_usage = TokenUsage::default();
     let final_response;
 
+    // ── Programmatic Tool Calling (PTC) ─────────────────────────────────
+    // If PTC is enabled, replace the tool list with: direct tools + execute_code.
+    // PTC tools get compact Python function signatures instead of full JSON schemas.
+    let ptc_global_enabled = manifest.ptc_enabled.unwrap_or(true);
+    let ptc_config = crate::ptc::PtcConfig::default();
+
+    let mut ptc_instance: Option<crate::ptc::PtcInstance> =
+        if ptc_global_enabled && !available_tools.is_empty() {
+            match crate::ptc::init_ptc(available_tools).await {
+                Ok(instance) => Some(instance),
+                Err(e) => {
+                    warn!("PTC initialization failed, falling back to direct tools: {e}");
+                    None
+                }
+            }
+        } else {
+            None
+        };
+
+    // If PTC is active, swap the tool list: direct tools + execute_code
+    let ptc_tools_vec: Vec<ToolDefinition>;
+    let available_tools = if let Some(ref ptc) = ptc_instance {
+        ptc_tools_vec = ptc.agent_tools();
+        &ptc_tools_vec[..]
+    } else {
+        available_tools
+    };
+
+    // Append PTC system prompt supplement if PTC is active
+    if ptc_instance.is_some() {
+        system_prompt.push_str(PTC_SYSTEM_PROMPT_SUPPLEMENT);
+    }
+
     // Safety valve: trim excessively long message histories to prevent context overflow.
     // The full compaction system handles sophisticated summarization, but this prevents
     // the catastrophic case where 200+ messages cause instant context overflow.
@@ -663,9 +729,18 @@ pub async fn run_agent_loop(
                     content: MessageContent::Blocks(assistant_blocks),
                 });
 
-                // Build allowed tool names list for capability enforcement
-                let allowed_tool_names: Vec<String> =
+                // Build allowed tool names list for capability enforcement.
+                // When PTC is active, include all PTC tools too (they're called
+                // from the IPC server, not directly by the LLM).
+                let mut allowed_tool_names: Vec<String> =
                     available_tools.iter().map(|t| t.name.clone()).collect();
+                if let Some(ref ptc) = ptc_instance {
+                    for t in &ptc.ptc_tools {
+                        if !allowed_tool_names.contains(&t.name) {
+                            allowed_tool_names.push(t.name.clone());
+                        }
+                    }
+                }
                 let caller_id_str = session.agent_id.to_string();
 
                 // Execute each tool call with loop guard, timeout, and truncation
@@ -752,9 +827,84 @@ pub async fn run_agent_loop(
                     let effective_exec_policy = manifest.exec_policy.as_ref();
 
                     // Timeout-wrapped execution
+                    // PTC interception: if this is execute_code and PTC is active,
+                    // run Python and concurrently dispatch tool calls from the IPC channel.
+                    let result = if let (true, Some(ptc)) = (
+                        tool_call.name == "execute_code",
+                        ptc_instance.as_mut(),
+                    ) {
+                        let code = tool_call.input["code"].as_str().unwrap_or("");
+                        let ptc_timeout = tool_call.input["timeout"]
+                            .as_u64()
+                            .unwrap_or(ptc_config.timeout_secs)
+                            .clamp(10, 600);
+
+                        // Generate SDK and run Python
+                        let sdk = crate::ptc::generate_python_sdk(&ptc.ptc_tools, ptc.ipc_server.port());
+                        let full_script = crate::ptc::wrap_user_code(&sdk, code);
+
+                        // Spawn the Python subprocess as a future
+                        let ws = workspace_root.map(|p| p.to_path_buf());
+                        let mut python_fut = tokio::spawn(async move {
+                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref()).await
+                        });
+
+                        // Concurrently handle IPC tool requests while Python runs.
+                        // JoinHandle is Unpin so we can select! on &mut directly.
+                        let python_result: Option<crate::ptc::executor::PythonResult> = loop {
+                            tokio::select! {
+                                // Python finished
+                                py_result = &mut python_fut => {
+                                    break py_result.ok();
+                                }
+                                // IPC tool request from Python
+                                Some(req) = ptc.ipc_server.request_rx.recv() => {
+                                    let eff_exec_policy = manifest.exec_policy.as_ref();
+                                    let tool_result = tool_runner::execute_tool(
+                                        &req.tool_call_id,
+                                        &req.tool_name,
+                                        &req.input,
+                                        kernel.as_ref(),
+                                        Some(&allowed_tool_names),
+                                        Some(&caller_id_str),
+                                        skill_registry,
+                                        mcp_connections,
+                                        web_ctx,
+                                        browser_ctx,
+                                        if hand_allowed_env.is_empty() {
+                                            None
+                                        } else {
+                                            Some(&hand_allowed_env)
+                                        },
+                                        workspace_root,
+                                        media_engine,
+                                        eff_exec_policy,
+                                        tts_engine,
+                                        docker_config,
+                                        process_manager,
+                                    )
+                                    .await;
+                                    let _ = req.response_tx.send(tool_result);
+                                }
+                            }
+                        };
+
+                        match python_result {
+                            Some(py) => ptc_python_result_to_tool_result(
+                                py,
+                                &tool_call.id,
+                                ptc_config.max_stdout_bytes,
+                            ),
+                            None => openfang_types::tool::ToolResult {
+                                tool_use_id: tool_call.id.clone(),
+                                content: "execute_code: Python subprocess failed".to_string(),
+                                is_error: true,
+                            },
+                        }
+                    } else {
                     let timeout = tool_timeout_for(&tool_call.name);
                     let timeout_secs = timeout.as_secs();
-                    let result = match tokio::time::timeout(
+                    match tokio::time::timeout(
                         timeout,
                         tool_runner::execute_tool(
                             &tool_call.id,
@@ -794,6 +944,7 @@ pub async fn run_agent_loop(
                                 is_error: true,
                             }
                         }
+                    } // end else (non-execute_code tool dispatch)
                     };
 
                     // Fire AfterToolCall hook
@@ -1490,6 +1641,36 @@ pub async fn run_agent_loop_streaming(
     let mut total_usage = TokenUsage::default();
     let final_response;
 
+    // ── Programmatic Tool Calling (PTC) — streaming ─────────────────────
+    let ptc_global_enabled = manifest.ptc_enabled.unwrap_or(true);
+    let ptc_config = crate::ptc::PtcConfig::default();
+
+    let mut ptc_instance: Option<crate::ptc::PtcInstance> =
+        if ptc_global_enabled && !available_tools.is_empty() {
+            match crate::ptc::init_ptc(available_tools).await {
+                Ok(instance) => Some(instance),
+                Err(e) => {
+                    warn!("PTC initialization failed (streaming), falling back to direct tools: {e}");
+                    None
+                }
+            }
+        } else {
+            None
+        };
+
+    let ptc_tools_vec: Vec<ToolDefinition>;
+    let available_tools = if let Some(ref ptc) = ptc_instance {
+        ptc_tools_vec = ptc.agent_tools();
+        &ptc_tools_vec[..]
+    } else {
+        available_tools
+    };
+
+    // Append PTC system prompt supplement if PTC is active (streaming)
+    if ptc_instance.is_some() {
+        system_prompt.push_str(PTC_SYSTEM_PROMPT_SUPPLEMENT);
+    }
+
     // Safety valve: trim excessively long message histories to prevent context overflow.
     if messages.len() > MAX_HISTORY_MESSAGES {
         let trim_count = messages.len() - MAX_HISTORY_MESSAGES;
@@ -1818,8 +1999,16 @@ pub async fn run_agent_loop_streaming(
                     content: MessageContent::Blocks(assistant_blocks),
                 });
 
-                let allowed_tool_names: Vec<String> =
+                // Include PTC tools in allowed names (they're callable from IPC, not the LLM)
+                let mut allowed_tool_names: Vec<String> =
                     available_tools.iter().map(|t| t.name.clone()).collect();
+                if let Some(ref ptc) = ptc_instance {
+                    for t in &ptc.ptc_tools {
+                        if !allowed_tool_names.contains(&t.name) {
+                            allowed_tool_names.push(t.name.clone());
+                        }
+                    }
+                }
                 let caller_id_str = session.agent_id.to_string();
 
                 // Execute each tool call with loop guard, timeout, and truncation
@@ -1905,9 +2094,73 @@ pub async fn run_agent_loop_streaming(
                     let effective_exec_policy = manifest.exec_policy.as_ref();
 
                     // Timeout-wrapped execution
+                    // PTC interception (streaming): same as non-streaming path.
+                    let result = if let (true, Some(ptc)) = (
+                        tool_call.name == "execute_code",
+                        ptc_instance.as_mut(),
+                    ) {
+                        let code = tool_call.input["code"].as_str().unwrap_or("");
+                        let ptc_timeout = tool_call.input["timeout"]
+                            .as_u64()
+                            .unwrap_or(ptc_config.timeout_secs)
+                            .clamp(10, 600);
+
+                        let sdk = crate::ptc::generate_python_sdk(&ptc.ptc_tools, ptc.ipc_server.port());
+                        let full_script = crate::ptc::wrap_user_code(&sdk, code);
+
+                        let ws = workspace_root.map(|p| p.to_path_buf());
+                        let mut python_fut = tokio::spawn(async move {
+                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref()).await
+                        });
+
+                        let python_result: Option<crate::ptc::executor::PythonResult> = loop {
+                            tokio::select! {
+                                py_result = &mut python_fut => {
+                                    break py_result.ok();
+                                }
+                                Some(req) = ptc.ipc_server.request_rx.recv() => {
+                                    let eff_exec_policy = manifest.exec_policy.as_ref();
+                                    let tool_result = tool_runner::execute_tool(
+                                        &req.tool_call_id,
+                                        &req.tool_name,
+                                        &req.input,
+                                        kernel.as_ref(),
+                                        Some(&allowed_tool_names),
+                                        Some(&caller_id_str),
+                                        skill_registry,
+                                        mcp_connections,
+                                        web_ctx,
+                                        browser_ctx,
+                                        if hand_allowed_env.is_empty() { None } else { Some(&hand_allowed_env) },
+                                        workspace_root,
+                                        media_engine,
+                                        eff_exec_policy,
+                                        tts_engine,
+                                        docker_config,
+                                        process_manager,
+                                    )
+                                    .await;
+                                    let _ = req.response_tx.send(tool_result);
+                                }
+                            }
+                        };
+
+                        match python_result {
+                            Some(py) => ptc_python_result_to_tool_result(
+                                py,
+                                &tool_call.id,
+                                ptc_config.max_stdout_bytes,
+                            ),
+                            None => openfang_types::tool::ToolResult {
+                                tool_use_id: tool_call.id.clone(),
+                                content: "execute_code: Python subprocess failed".to_string(),
+                                is_error: true,
+                            },
+                        }
+                    } else {
                     let timeout = tool_timeout_for(&tool_call.name);
                     let timeout_secs = timeout.as_secs();
-                    let result = match tokio::time::timeout(
+                    match tokio::time::timeout(
                         timeout,
                         tool_runner::execute_tool(
                             &tool_call.id,
@@ -1947,6 +2200,7 @@ pub async fn run_agent_loop_streaming(
                                 is_error: true,
                             }
                         }
+                    } // end else (non-execute_code tool dispatch, streaming)
                     };
 
                     // Fire AfterToolCall hook
@@ -2141,6 +2395,43 @@ pub async fn run_agent_loop_streaming(
 /// 12. `tool_name\n{"key":"value"}` — bare name + JSON on next line (Llama 4 Scout)
 /// 13. `<tool_use>{"name":"tool","arguments":{...}}</tool_use>` — Llama 3.1+ variant
 ///
+/// Build a ToolResult from a PythonResult, applying output truncation.
+fn ptc_python_result_to_tool_result(
+    py: crate::ptc::executor::PythonResult,
+    tool_use_id: &str,
+    max_stdout_bytes: usize,
+) -> openfang_types::tool::ToolResult {
+    let mut parts: Vec<String> = Vec::new();
+    if !py.stdout.trim().is_empty() {
+        let stdout = if py.stdout.len() > max_stdout_bytes {
+            format!(
+                "{}\n\n[output truncated at {} bytes]",
+                &py.stdout[..max_stdout_bytes],
+                max_stdout_bytes
+            )
+        } else {
+            py.stdout.trim().to_string()
+        };
+        parts.push(stdout);
+    }
+    if py.exit_code != 0 {
+        if !py.stderr.trim().is_empty() {
+            parts.push(format!("\n[stderr]\n{}", py.stderr.trim()));
+        }
+        parts.push(format!("\n[exit code: {}]", py.exit_code));
+    }
+    let output = if parts.is_empty() {
+        "(no output)".to_string()
+    } else {
+        parts.join("\n")
+    };
+    openfang_types::tool::ToolResult {
+        tool_use_id: tool_use_id.to_string(),
+        content: output,
+        is_error: py.exit_code != 0,
+    }
+}
+
 /// Validates tool names against available tools and returns synthetic `ToolCall` entries.
 fn recover_text_tool_calls(text: &str, available_tools: &[ToolDefinition]) -> Vec<ToolCall> {
     let mut calls = Vec::new();
diff --git a/crates/openfang-runtime/src/lib.rs b/crates/openfang-runtime/src/lib.rs
index 9e88fe8b9..bd811113b 100644
--- a/crates/openfang-runtime/src/lib.rs
+++ b/crates/openfang-runtime/src/lib.rs
@@ -36,6 +36,7 @@ pub mod media_understanding;
 pub mod model_catalog;
 pub mod process_manager;
 pub mod prompt_builder;
+pub mod ptc;
 pub mod provider_health;
 pub mod python_runtime;
 pub mod reply_directives;
diff --git a/crates/openfang-runtime/src/ptc/executor.rs b/crates/openfang-runtime/src/ptc/executor.rs
new file mode 100644
index 000000000..863bb1c4d
--- /dev/null
+++ b/crates/openfang-runtime/src/ptc/executor.rs
@@ -0,0 +1,172 @@
+//! Python subprocess executor for Programmatic Tool Calling.
+//!
+//! Spawns `python3 -u -c <script>` as a child process, captures stdout/stderr,
+//! and enforces a timeout by killing the process.
+
+use std::path::Path;
+use std::sync::atomic::{AtomicU8, Ordering};
+use tracing::{debug, warn};
+
+/// Cached python3 availability: 0 = unknown, 1 = available, 2 = not available.
+static PYTHON3_AVAILABLE: AtomicU8 = AtomicU8::new(0);
+
+/// Check if python3 is available on the system. Result is cached after first call.
+pub fn is_python3_available() -> bool {
+    let cached = PYTHON3_AVAILABLE.load(Ordering::Relaxed);
+    if cached != 0 {
+        return cached == 1;
+    }
+
+    let available = std::process::Command::new("python3")
+        .arg("--version")
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false);
+
+    PYTHON3_AVAILABLE.store(if available { 1 } else { 2 }, Ordering::Relaxed);
+
+    if !available {
+        warn!("python3 not found — Programmatic Tool Calling (PTC) will be disabled. \
+               Install Python 3 to enable PTC.");
+    }
+
+    available
+}
+
+/// Result of a Python execution.
+#[derive(Debug)]
+pub struct PythonResult {
+    /// Captured stdout.
+    pub stdout: String,
+    /// Captured stderr.
+    pub stderr: String,
+    /// Process exit code (0 = success).
+    pub exit_code: i32,
+}
+
+/// Execute a Python script in a subprocess.
+///
+/// The script is passed via `-c` flag. The process runs with:
+/// - `PYTHONUNBUFFERED=1` to prevent output buffering
+/// - `cwd` set to the workspace root (if provided)
+///
+/// If the process exceeds `timeout_secs`, it is killed.
+pub async fn execute_python(
+    script: &str,
+    timeout_secs: u64,
+    workspace_root: Option<&Path>,
+) -> PythonResult {
+    use tokio::process::Command;
+    use tokio::io::AsyncReadExt;
+
+    let mut cmd = Command::new("python3");
+    cmd.arg("-u").arg("-c").arg(script);
+
+    // Set working directory
+    if let Some(root) = workspace_root {
+        cmd.current_dir(root);
+    }
+
+    // Environment: unbuffered Python + inherit parent
+    cmd.env("PYTHONUNBUFFERED", "1");
+
+    // Spawn with piped stdio
+    cmd.stdout(std::process::Stdio::piped());
+    cmd.stderr(std::process::Stdio::piped());
+    cmd.stdin(std::process::Stdio::null());
+
+    // Kill on drop ensures cleanup if the future is cancelled
+    cmd.kill_on_drop(true);
+
+    let mut child = match cmd.spawn() {
+        Ok(c) => c,
+        Err(e) => {
+            warn!("Failed to spawn python3: {e}");
+            return PythonResult {
+                stdout: String::new(),
+                stderr: format!("Failed to spawn python3: {e}. Is Python 3 installed?"),
+                exit_code: 1,
+            };
+        }
+    };
+
+    let pid = child.id();
+    debug!(pid, timeout_secs, "Python subprocess started");
+
+    // Read stdout/stderr concurrently with timeout
+    let mut stdout_pipe = child.stdout.take().unwrap();
+    let mut stderr_pipe = child.stderr.take().unwrap();
+
+    let result = tokio::time::timeout(
+        std::time::Duration::from_secs(timeout_secs),
+        async {
+            let (stdout_result, stderr_result) = tokio::join!(
+                async {
+                    let mut buf = Vec::new();
+                    stdout_pipe.read_to_end(&mut buf).await.ok();
+                    String::from_utf8_lossy(&buf).into_owned()
+                },
+                async {
+                    let mut buf = Vec::new();
+                    stderr_pipe.read_to_end(&mut buf).await.ok();
+                    String::from_utf8_lossy(&buf).into_owned()
+                }
+            );
+
+            let status = child.wait().await;
+            let exit_code = status.map(|s| s.code().unwrap_or(1)).unwrap_or(1);
+
+            PythonResult {
+                stdout: stdout_result,
+                stderr: stderr_result,
+                exit_code,
+            }
+        },
+    )
+    .await;
+
+    match result {
+        Ok(r) => r,
+        Err(_) => {
+            warn!(pid, timeout_secs, "Python subprocess timed out, killing");
+            // kill_on_drop will handle cleanup, but try explicit kill too
+            let _ = child.kill().await;
+
+            PythonResult {
+                stdout: String::new(),
+                stderr: format!("Execution timed out after {timeout_secs}s"),
+                exit_code: 1,
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_execute_simple_python() {
+        let result = execute_python("print('hello world')", 10, None).await;
+        assert_eq!(result.exit_code, 0);
+        assert_eq!(result.stdout.trim(), "hello world");
+    }
+
+    #[tokio::test]
+    async fn test_execute_python_error() {
+        let result = execute_python("raise ValueError('test error')", 10, None).await;
+        assert_ne!(result.exit_code, 0);
+        assert!(result.stderr.contains("ValueError"));
+    }
+
+    #[tokio::test]
+    async fn test_execute_python_timeout() {
+        let result = execute_python("import time; time.sleep(60)", 1, None).await;
+        assert_ne!(result.exit_code, 0);
+        assert!(
+            result.stderr.contains("timed out") || result.exit_code != 0
+        );
+    }
+}
diff --git a/crates/openfang-runtime/src/ptc/ipc_server.rs b/crates/openfang-runtime/src/ptc/ipc_server.rs
new file mode 100644
index 000000000..2036e5db4
--- /dev/null
+++ b/crates/openfang-runtime/src/ptc/ipc_server.rs
@@ -0,0 +1,390 @@
+//! IPC HTTP server for Programmatic Tool Calling.
+//!
+//! A lightweight HTTP server running on a random localhost port.
+//! Python code generated by the SDK calls `POST http://127.0.0.1:{port}/tool/{name}`
+//! with JSON args. This server dispatches tool calls through a channel back to
+//! the agent loop, which owns all the necessary context (kernel, MCP connections,
+//! skill registry, etc.).
+//!
+//! Architecture:
+//! ```text
+//! Python → HTTP POST /tool/{name} → IPC server
+//!   → sends (name, input) over channel → agent loop
+//!   → agent loop calls execute_tool() with full context
+//!   → result sent back over oneshot channel → IPC server → Python
+//! ```
+//!
+//! Security: Binds to 127.0.0.1 only — no external access.
+
+use openfang_types::tool::{ToolDefinition, ToolResult};
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::net::TcpListener;
+use tokio::sync::{mpsc, oneshot};
+use tracing::{debug, warn};
+
+/// A request from the IPC server to the agent loop to execute a tool.
+pub struct PtcToolRequest {
+    /// Tool call ID.
+    pub tool_call_id: String,
+    /// Tool name to execute.
+    pub tool_name: String,
+    /// Tool input parameters.
+    pub input: serde_json::Value,
+    /// Channel to send the result back on.
+    pub response_tx: oneshot::Sender<ToolResult>,
+}
+
+/// A running PTC IPC server.
+pub struct PtcIpcServer {
+    /// Port the server is listening on.
+    port: u16,
+    /// Shutdown signal sender.
+    shutdown_tx: Option<oneshot::Sender<()>>,
+    /// Join handle for the server task.
+    join_handle: Option<tokio::task::JoinHandle<()>>,
+    /// Receiver for tool requests from the IPC server.
+    /// The agent loop polls this to dispatch tool calls.
+    pub request_rx: mpsc::Receiver<PtcToolRequest>,
+}
+
+impl PtcIpcServer {
+    /// Get the port the server is listening on.
+    pub fn port(&self) -> u16 {
+        self.port
+    }
+
+    /// Shut down the server gracefully.
+    pub async fn shutdown(mut self) {
+        if let Some(tx) = self.shutdown_tx.take() {
+            let _ = tx.send(());
+        }
+        if let Some(handle) = self.join_handle.take() {
+            let _ = handle.await;
+        }
+        debug!(port = self.port, "PTC IPC server stopped");
+    }
+}
+
+impl Drop for PtcIpcServer {
+    fn drop(&mut self) {
+        // Best-effort shutdown on drop
+        if let Some(tx) = self.shutdown_tx.take() {
+            let _ = tx.send(());
+        }
+    }
+}
+
+/// Start the PTC IPC HTTP server on a random available port.
+///
+/// Returns the server and a receiver for tool requests. The caller (agent loop)
+/// is responsible for polling the receiver and dispatching tool calls.
+pub async fn start_ipc_server(
+    ptc_tools: &[ToolDefinition],
+) -> Result<PtcIpcServer, std::io::Error> {
+    // Build tool name set for validation
+    let tool_names: HashMap<String, ()> = ptc_tools
+        .iter()
+        .map(|t| (t.name.clone(), ()))
+        .collect();
+    let tool_names = Arc::new(tool_names);
+
+    // Channel for tool requests: IPC server → agent loop
+    let (request_tx, request_rx) = mpsc::channel::<PtcToolRequest>(32);
+
+    // Bind to random port on localhost
+    let listener = TcpListener::bind("127.0.0.1:0").await?;
+    let port = listener.local_addr()?.port();
+
+    let (shutdown_tx, shutdown_rx) = oneshot::channel::<()>();
+
+    let join_handle = tokio::spawn(run_server(
+        listener,
+        tool_names,
+        request_tx,
+        shutdown_rx,
+    ));
+
+    debug!(port, "PTC IPC server started");
+
+    Ok(PtcIpcServer {
+        port,
+        shutdown_tx: Some(shutdown_tx),
+        join_handle: Some(join_handle),
+        request_rx,
+    })
+}
+
+/// Run the HTTP server loop.
+async fn run_server(
+    listener: TcpListener,
+    tool_names: Arc<HashMap<String, ()>>,
+    request_tx: mpsc::Sender<PtcToolRequest>,
+    mut shutdown_rx: oneshot::Receiver<()>,
+) {
+    loop {
+        tokio::select! {
+            accept_result = listener.accept() => {
+                match accept_result {
+                    Ok((stream, _addr)) => {
+                        let names = tool_names.clone();
+                        let tx = request_tx.clone();
+                        tokio::spawn(async move {
+                            if let Err(e) = handle_connection(stream, names, tx).await {
+                                warn!("PTC IPC connection error: {e}");
+                            }
+                        });
+                    }
+                    Err(e) => {
+                        warn!("PTC IPC accept error: {e}");
+                    }
+                }
+            }
+            _ = &mut shutdown_rx => {
+                debug!("PTC IPC server shutting down");
+                break;
+            }
+        }
+    }
+}
+
+/// Handle a single HTTP connection (one request-response).
+///
+/// Parses the HTTP request, validates the tool name, sends a request
+/// to the agent loop via the channel, and waits for the result.
+async fn handle_connection(
+    mut stream: tokio::net::TcpStream,
+    tool_names: Arc<HashMap<String, ()>>,
+    request_tx: mpsc::Sender<PtcToolRequest>,
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    use tokio::io::AsyncReadExt;
+
+    // Read the full request (headers + body)
+    let mut buf = vec![0u8; 65536];
+    let mut total = 0;
+
+    // Read until we have the full headers
+    loop {
+        let n = stream.read(&mut buf[total..]).await?;
+        if n == 0 {
+            return Ok(()); // Connection closed
+        }
+        total += n;
+
+        if let Some(_header_end) = find_header_end(&buf[..total]) {
+            break;
+        }
+        if total >= buf.len() {
+            send_response(&mut stream, 413, "Request too large").await?;
+            return Ok(());
+        }
+    }
+
+    // Parse the request
+    let header_end = match find_header_end(&buf[..total]) {
+        Some(pos) => pos,
+        None => {
+            send_response(&mut stream, 400, "Malformed request").await?;
+            return Ok(());
+        }
+    };
+
+    let headers_str = std::str::from_utf8(&buf[..header_end]).unwrap_or("");
+    let body_start = header_end + 4; // Skip \r\n\r\n
+
+    // Parse method and path from first line
+    let first_line = headers_str.lines().next().unwrap_or("");
+    let parts: Vec<&str> = first_line.split_whitespace().collect();
+    if parts.len() < 2 {
+        send_response(&mut stream, 400, "Bad request line").await?;
+        return Ok(());
+    }
+
+    let method = parts[0];
+    let path = parts[1];
+
+    // Only handle POST /tool/{name}
+    if method != "POST" || !path.starts_with("/tool/") {
+        send_response(&mut stream, 404, "Not found").await?;
+        return Ok(());
+    }
+
+    let tool_name = urldecode(&path["/tool/".len()..]);
+
+    // Validate tool exists
+    if !tool_names.contains_key(&tool_name) {
+        send_response(
+            &mut stream,
+            404,
+            &format!("Tool not found: {tool_name}"),
+        )
+        .await?;
+        return Ok(());
+    }
+
+    // Read Content-Length to get full body
+    let content_length = parse_content_length(headers_str).unwrap_or(0);
+    let body_available = total - body_start;
+
+    // Read remaining body if needed
+    let body = if content_length > body_available {
+        let remaining = content_length - body_available;
+        let mut extra = vec![0u8; remaining];
+        let mut read = 0;
+        while read < remaining {
+            let n = stream.read(&mut extra[read..]).await?;
+            if n == 0 {
+                break;
+            }
+            read += n;
+        }
+        let mut full_body = buf[body_start..total].to_vec();
+        full_body.extend_from_slice(&extra[..read]);
+        full_body
+    } else {
+        buf[body_start..body_start + content_length.min(body_available)].to_vec()
+    };
+
+    // Parse JSON args
+    let input: serde_json::Value = if body.is_empty() {
+        serde_json::json!({})
+    } else {
+        match serde_json::from_slice(&body) {
+            Ok(v) => v,
+            Err(e) => {
+                send_response(&mut stream, 400, &format!("Invalid JSON: {e}")).await?;
+                return Ok(());
+            }
+        }
+    };
+
+    let tool_call_id = format!("ptc_{}_{}", tool_name, uuid::Uuid::new_v4());
+
+    debug!(tool = %tool_name, "PTC IPC dispatching tool call");
+
+    // Send request to agent loop and wait for result
+    let (response_tx, response_rx) = oneshot::channel();
+    let request = PtcToolRequest {
+        tool_call_id,
+        tool_name: tool_name.clone(),
+        input,
+        response_tx,
+    };
+
+    if request_tx.send(request).await.is_err() {
+        send_response(&mut stream, 500, "Agent loop not available").await?;
+        return Ok(());
+    }
+
+    // Wait for the result (with a generous timeout)
+    match tokio::time::timeout(std::time::Duration::from_secs(300), response_rx).await {
+        Ok(Ok(result)) => {
+            if result.is_error {
+                send_response(&mut stream, 500, &result.content).await?;
+            } else {
+                send_response(&mut stream, 200, &result.content).await?;
+            }
+        }
+        Ok(Err(_)) => {
+            send_response(&mut stream, 500, "Tool dispatch channel closed").await?;
+        }
+        Err(_) => {
+            send_response(&mut stream, 500, "Tool execution timed out (300s)").await?;
+        }
+    }
+
+    Ok(())
+}
+
+/// Send an HTTP response.
+async fn send_response(
+    stream: &mut tokio::net::TcpStream,
+    status: u16,
+    body: &str,
+) -> Result<(), std::io::Error> {
+    use tokio::io::AsyncWriteExt;
+
+    let status_text = match status {
+        200 => "OK",
+        400 => "Bad Request",
+        404 => "Not Found",
+        413 => "Payload Too Large",
+        500 => "Internal Server Error",
+        _ => "Unknown",
+    };
+
+    let response = format!(
+        "HTTP/1.1 {} {}\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+        status,
+        status_text,
+        body.len(),
+        body
+    );
+
+    stream.write_all(response.as_bytes()).await?;
+    stream.flush().await?;
+    Ok(())
+}
+
+/// Find the end of HTTP headers (double CRLF).
+fn find_header_end(buf: &[u8]) -> Option<usize> {
+    buf.windows(4)
+        .position(|w| w == b"\r\n\r\n")
+}
+
+/// Parse Content-Length from raw headers string.
+fn parse_content_length(headers: &str) -> Option<usize> {
+    for line in headers.lines() {
+        let lower = line.to_lowercase();
+        if let Some(stripped) = lower.strip_prefix("content-length:") {
+            return stripped.trim().parse().ok();
+        }
+    }
+    None
+}
+
+/// Simple URL decoding (percent-encoded chars).
+fn urldecode(s: &str) -> String {
+    let mut result = String::with_capacity(s.len());
+    let mut chars = s.chars();
+    while let Some(ch) = chars.next() {
+        if ch == '%' {
+            let hex: String = chars.by_ref().take(2).collect();
+            if let Ok(byte) = u8::from_str_radix(&hex, 16) {
+                result.push(byte as char);
+            } else {
+                result.push('%');
+                result.push_str(&hex);
+            }
+        } else if ch == '+' {
+            result.push(' ');
+        } else {
+            result.push(ch);
+        }
+    }
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_find_header_end() {
+        let data = b"GET / HTTP/1.1\r\nHost: localhost\r\n\r\nbody";
+        assert_eq!(find_header_end(data), Some(33));
+    }
+
+    #[test]
+    fn test_parse_content_length() {
+        let headers = "POST /tool/file_read HTTP/1.1\r\nContent-Length: 42\r\nHost: localhost";
+        assert_eq!(parse_content_length(headers), Some(42));
+    }
+
+    #[test]
+    fn test_urldecode() {
+        assert_eq!(urldecode("file_read"), "file_read");
+        assert_eq!(urldecode("mcp_github%20list"), "mcp_github list");
+        assert_eq!(urldecode("a%2Fb"), "a/b");
+    }
+}
diff --git a/crates/openfang-runtime/src/ptc/mod.rs b/crates/openfang-runtime/src/ptc/mod.rs
new file mode 100644
index 000000000..1a20a115c
--- /dev/null
+++ b/crates/openfang-runtime/src/ptc/mod.rs
@@ -0,0 +1,208 @@
+//! Programmatic Tool Calling (PTC) for OpenFang.
+//!
+//! Instead of sending LLMs 50+ tool JSON schemas (consuming thousands of context
+//! tokens), PTC replaces them with a single `execute_code` tool. The LLM writes
+//! Python code that calls tools as plain functions, and only `print()` output
+//! enters the context window.
+//!
+//! This approach:
+//! - Reduces context usage by 30-40%+ (tool schemas removed from prompt)
+//! - Eliminates multi-turn tool roundtrips (batch operations in a single code block)
+//! - Keeps intermediate tool results out of context (processed in code)
+//! - Works with any LLM model, not just Anthropic
+//!
+//! Architecture:
+//! ```text
+//! LLM → execute_code(code="...") → agent loop
+//!   → python3 subprocess with auto-generated SDK preamble
+//!   → Python calls tool functions via HTTP to localhost IPC server
+//!   → IPC server sends request over channel to agent loop
+//!   → agent loop calls execute_tool() with full context
+//!   → result sent back through channel → IPC server → Python
+//!   → only print() output returned to LLM context
+//! ```
+
+pub mod executor;
+pub mod ipc_server;
+pub mod sdk_generator;
+pub mod tool_classifier;
+
+use openfang_types::tool::ToolDefinition;
+use std::path::Path;
+
+pub use executor::{execute_python, is_python3_available};
+pub use ipc_server::{PtcIpcServer, PtcToolRequest};
+pub use sdk_generator::{generate_compact_reference, generate_python_sdk, wrap_user_code};
+pub use tool_classifier::{classify_tools, PtcMode};
+
+/// Configuration for Programmatic Tool Calling.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct PtcConfig {
+    /// Whether PTC is enabled (global default: true).
+    pub enabled: bool,
+    /// Timeout for Python subprocess execution in seconds.
+    pub timeout_secs: u64,
+    /// Maximum stdout size in bytes before truncation.
+    pub max_stdout_bytes: usize,
+}
+
+impl Default for PtcConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            timeout_secs: 120,
+            max_stdout_bytes: 100_000,
+        }
+    }
+}
+
+/// A running PTC instance for a single agent loop execution.
+///
+/// Created at agent loop start, shut down at loop end.
+pub struct PtcInstance {
+    /// The IPC server handling tool calls from Python.
+    pub ipc_server: PtcIpcServer,
+    /// Tools passed directly to the LLM (with full JSON schemas).
+    pub direct_tools: Vec<ToolDefinition>,
+    /// Tools callable only via execute_code (schemas removed from prompt).
+    pub ptc_tools: Vec<ToolDefinition>,
+    /// The execute_code tool definition (includes compact function reference).
+    pub execute_code_tool: ToolDefinition,
+}
+
+impl PtcInstance {
+    /// Get the tool list to pass to the LLM: direct tools + execute_code.
+    pub fn agent_tools(&self) -> Vec<ToolDefinition> {
+        let mut tools = self.direct_tools.clone();
+        tools.push(self.execute_code_tool.clone());
+        tools
+    }
+}
+
+/// Initialize PTC for an agent loop execution.
+///
+/// Starts the IPC server, classifies tools, generates the execute_code tool,
+/// and returns the PTC instance. The caller must poll `ptc_instance.ipc_server.request_rx`
+/// to dispatch tool calls from the IPC server.
+pub async fn init_ptc(
+    all_tools: &[ToolDefinition],
+) -> Result<PtcInstance, String> {
+    // Check python3 availability first (cached after first call)
+    if !is_python3_available() {
+        return Err("python3 not available".to_string());
+    }
+
+    // Classify tools into direct vs PTC
+    let (direct_tools, ptc_tools) = classify_tools(all_tools);
+
+    // Start the IPC server
+    let ipc_server = ipc_server::start_ipc_server(&ptc_tools)
+        .await
+        .map_err(|e| format!("Failed to start PTC IPC server: {e}"))?;
+
+    // Generate the execute_code tool with compact function reference
+    let compact_ref = generate_compact_reference(&ptc_tools);
+    let execute_code_tool = build_execute_code_definition(&compact_ref);
+
+    tracing::info!(
+        direct = direct_tools.len(),
+        ptc = ptc_tools.len(),
+        port = ipc_server.port(),
+        "PTC initialized"
+    );
+
+    Ok(PtcInstance {
+        ipc_server,
+        direct_tools,
+        ptc_tools,
+        execute_code_tool,
+    })
+}
+
+/// Build the `execute_code` tool definition.
+fn build_execute_code_definition(compact_ref: &str) -> ToolDefinition {
+    let description = format!(
+        "Execute Python code with access to tool functions. \
+         Tools are plain synchronous functions — call them directly, NO async/await. \
+         ONLY print() output enters your context window — \
+         tool results are processed in code, not loaded into context. \
+         Use this for multi-step workflows, data filtering, batch operations, \
+         and any task where intermediate results should be processed before you see them. \
+         Always wrap code in try/except. Some params are renamed: type -> type_, class -> class_.\n\n\
+         Available functions:\n{compact_ref}"
+    );
+
+    ToolDefinition {
+        name: "execute_code".to_string(),
+        description,
+        input_schema: serde_json::json!({
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "Python code to execute. Tool functions are available as synchronous calls. Use print() to output results — ONLY print() output enters your context."
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Execution timeout in seconds (default 120, max 600)."
+                }
+            },
+            "required": ["code"]
+        }),
+    }
+}
+
+/// Execute the `execute_code` tool: generate SDK, run Python, return output.
+///
+/// This is a standalone helper for executing PTC code without the select loop.
+/// The agent loop uses an inline version that concurrently polls the IPC channel.
+/// This function is useful for testing or MCP-server tool execution.
+#[allow(dead_code)]
+pub async fn run_execute_code(
+    code: &str,
+    timeout_secs: u64,
+    ptc_tools: &[ToolDefinition],
+    ipc_port: u16,
+    config: &PtcConfig,
+    workspace_root: Option<&Path>,
+) -> String {
+    // Generate the full SDK preamble + wrap user code
+    let sdk = generate_python_sdk(ptc_tools, ipc_port);
+    let full_script = wrap_user_code(&sdk, code);
+
+    tracing::debug!(
+        code_len = code.len(),
+        timeout_secs,
+        ptc_tools = ptc_tools.len(),
+        "Executing PTC code"
+    );
+
+    let result = execute_python(&full_script, timeout_secs, workspace_root).await;
+
+    // Combine stdout and stderr for the response
+    let mut parts: Vec<String> = Vec::new();
+    if !result.stdout.trim().is_empty() {
+        let stdout = if result.stdout.len() > config.max_stdout_bytes {
+            let truncated = &result.stdout[..config.max_stdout_bytes];
+            format!(
+                "{}\n\n[output truncated at {} bytes]",
+                truncated, config.max_stdout_bytes
+            )
+        } else {
+            result.stdout.trim().to_string()
+        };
+        parts.push(stdout);
+    }
+    if result.exit_code != 0 {
+        if !result.stderr.trim().is_empty() {
+            parts.push(format!("\n[stderr]\n{}", result.stderr.trim()));
+        }
+        parts.push(format!("\n[exit code: {}]", result.exit_code));
+    }
+
+    if parts.is_empty() {
+        "(no output)".to_string()
+    } else {
+        parts.join("\n")
+    }
+}
diff --git a/crates/openfang-runtime/src/ptc/sdk_generator.rs b/crates/openfang-runtime/src/ptc/sdk_generator.rs
new file mode 100644
index 000000000..aed253478
--- /dev/null
+++ b/crates/openfang-runtime/src/ptc/sdk_generator.rs
@@ -0,0 +1,538 @@
+//! Python SDK generator for Programmatic Tool Calling.
+//!
+//! Converts `ToolDefinition` schemas into:
+//! 1. A Python SDK preamble with sync function stubs (injected before user code)
+//! 2. Compact one-line function signatures (shown in the `execute_code` tool description)
+//!
+//! The generated SDK uses `urllib.request` for zero-dependency HTTP calls to the
+//! localhost IPC server. All functions are synchronous — no async/await confusion.
+
+use openfang_types::tool::ToolDefinition;
+
+/// Python reserved words that need a trailing underscore.
+const PYTHON_RESERVED: &[&str] = &[
+    "type", "class", "import", "from", "return", "pass", "in", "is", "not", "and", "or", "for",
+    "while", "if", "else", "elif", "try", "except", "finally", "with", "as", "def", "del",
+    "global", "nonlocal", "lambda", "yield", "assert", "break", "continue", "raise", "True",
+    "False", "None",
+];
+
+/// Python builtin names that must not be shadowed by tool function names.
+/// If a tool name collides with one of these, it gets a trailing underscore.
+const PYTHON_BUILTINS: &[&str] = &[
+    "print",
+    "input",
+    "open",
+    "id",
+    "list",
+    "dict",
+    "set",
+    "map",
+    "filter",
+    "hash",
+    "format",
+    "range",
+    "len",
+    "str",
+    "int",
+    "float",
+    "bool",
+    "bytes",
+    "tuple",
+    "abs",
+    "all",
+    "any",
+    "bin",
+    "chr",
+    "dir",
+    "eval",
+    "exec",
+    "exit",
+    "getattr",
+    "globals",
+    "hasattr",
+    "help",
+    "hex",
+    "isinstance",
+    "issubclass",
+    "iter",
+    "locals",
+    "max",
+    "min",
+    "next",
+    "object",
+    "oct",
+    "ord",
+    "pow",
+    "property",
+    "repr",
+    "reversed",
+    "round",
+    "setattr",
+    "slice",
+    "sorted",
+    "staticmethod",
+    "sum",
+    "super",
+    "vars",
+    "zip",
+];
+
+/// A parameter extracted from a JSON Schema.
+#[derive(Debug)]
+struct SchemaParam {
+    /// Python-safe name (e.g. `type_` for `type`).
+    name: String,
+    /// Original schema key (used in the IPC args dict).
+    original_name: String,
+    /// Python type hint string.
+    python_type: String,
+    /// Whether this parameter is required.
+    required: bool,
+    /// Default value as Python literal, if optional.
+    default: Option<String>,
+    /// Human-readable description (reserved for future docstring expansion).
+    #[allow(dead_code)]
+    description: Option<String>,
+}
+
+/// Convert a JSON Schema type to a Python type hint.
+fn json_type_to_python(schema: &serde_json::Value) -> String {
+    match schema.get("type").and_then(|t| t.as_str()) {
+        Some("string") => "str".to_string(),
+        Some("integer") => "int".to_string(),
+        Some("number") => "float".to_string(),
+        Some("boolean") => "bool".to_string(),
+        Some("array") => "list".to_string(),
+        Some("object") => "dict".to_string(),
+        _ => {
+            // Handle anyOf/oneOf (nullable patterns, union types)
+            if let Some(any_of) = schema.get("anyOf").or(schema.get("oneOf")) {
+                if let Some(arr) = any_of.as_array() {
+                    let non_null: Vec<&serde_json::Value> = arr
+                        .iter()
+                        .filter(|v| v.get("type").and_then(|t| t.as_str()) != Some("null"))
+                        .collect();
+                    if non_null.len() == 1 {
+                        return json_type_to_python(non_null[0]);
+                    }
+                }
+            }
+            // Handle enum values
+            if schema.get("enum").is_some() {
+                return "str".to_string();
+            }
+            "str".to_string()
+        }
+    }
+}
+
+/// Convert a JSON Schema type to a display type (includes enum values).
+fn json_type_to_display(schema: &serde_json::Value) -> String {
+    // Show enum values inline
+    if let Some(enum_vals) = schema.get("enum").and_then(|e| e.as_array()) {
+        let vals: Vec<String> = enum_vals
+            .iter()
+            .filter_map(|v| v.as_str().map(|s| format!("\"{}\"", s)))
+            .collect();
+        if !vals.is_empty() {
+            return vals.join("|");
+        }
+    }
+    json_type_to_python(schema)
+}
+
+/// Convert camelCase to snake_case.
+fn camel_to_snake(name: &str) -> String {
+    let mut result = String::with_capacity(name.len() + 4);
+    for (i, ch) in name.chars().enumerate() {
+        if ch.is_uppercase() && i > 0 {
+            // Don't add underscore if previous char is already uppercase (acronym)
+            let prev = name.chars().nth(i - 1).unwrap_or('a');
+            if prev.is_lowercase() || prev.is_numeric() {
+                result.push('_');
+            }
+        }
+        result.push(ch.to_lowercase().next().unwrap_or(ch));
+    }
+    result
+}
+
+/// Sanitize a name for Python: camelCase→snake_case, replace hyphens, avoid reserved words/builtins.
+fn sanitize_python_name(name: &str) -> String {
+    let mut result = camel_to_snake(name).replace('-', "_");
+    if PYTHON_RESERVED.contains(&result.as_str()) || PYTHON_BUILTINS.contains(&result.as_str()) {
+        result.push('_');
+    }
+    result
+}
+
+/// Convert a Rust/JSON default value to a Python literal.
+fn python_default(value: &serde_json::Value) -> String {
+    match value {
+        serde_json::Value::Null => "None".to_string(),
+        serde_json::Value::Bool(true) => "True".to_string(),
+        serde_json::Value::Bool(false) => "False".to_string(),
+        serde_json::Value::String(s) => format!("{:?}", s),
+        serde_json::Value::Number(n) => n.to_string(),
+        serde_json::Value::Array(_) => "[]".to_string(),
+        serde_json::Value::Object(_) => "{}".to_string(),
+    }
+}
+
+/// Extract parameters from a JSON Schema object.
+fn extract_params(schema: &serde_json::Value) -> Vec<SchemaParam> {
+    let properties = match schema.get("properties").and_then(|p| p.as_object()) {
+        Some(p) => p,
+        None => return Vec::new(),
+    };
+
+    let required_set: std::collections::HashSet<&str> = schema
+        .get("required")
+        .and_then(|r| r.as_array())
+        .map(|arr| arr.iter().filter_map(|v| v.as_str()).collect())
+        .unwrap_or_default();
+
+    let mut params: Vec<SchemaParam> = properties
+        .iter()
+        .map(|(name, prop_schema)| {
+            let is_required = required_set.contains(name.as_str());
+            let python_type = json_type_to_python(prop_schema);
+            let description = prop_schema
+                .get("description")
+                .and_then(|d| d.as_str())
+                .map(|s| s.to_string());
+
+            let default = if !is_required {
+                Some(
+                    prop_schema
+                        .get("default")
+                        .map(python_default)
+                        .unwrap_or_else(|| "None".to_string()),
+                )
+            } else {
+                None
+            };
+
+            SchemaParam {
+                name: sanitize_python_name(name),
+                original_name: name.clone(),
+                python_type,
+                required: is_required,
+                default,
+                description,
+            }
+        })
+        .collect();
+
+    // Sort: required params first, then optional
+    params.sort_by(|a, b| b.required.cmp(&a.required));
+    params
+}
+
+/// Generate a compact one-line function signature for the execute_code description.
+fn generate_function_signature(tool: &ToolDefinition) -> String {
+    let fn_name = sanitize_python_name(&tool.name);
+    let params = extract_params(&tool.input_schema);
+
+    let param_parts: Vec<String> = params
+        .iter()
+        .map(|p| {
+            let display_type = json_type_to_display(
+                tool.input_schema
+                    .get("properties")
+                    .and_then(|props| props.get(&p.original_name))
+                    .unwrap_or(&serde_json::Value::Null),
+            );
+            if let Some(ref default) = p.default {
+                format!("{}: {} = {}", p.name, display_type, default)
+            } else {
+                format!("{}: {}", p.name, display_type)
+            }
+        })
+        .collect();
+
+    format!("{}({})", fn_name, param_parts.join(", "))
+}
+
+/// Generate a synchronous Python function stub for a single tool.
+fn generate_function(tool: &ToolDefinition) -> String {
+    let fn_name = sanitize_python_name(&tool.name);
+    let params = extract_params(&tool.input_schema);
+
+    let param_parts: Vec<String> = params
+        .iter()
+        .map(|p| {
+            if let Some(ref default) = p.default {
+                format!("{}: {} = {}", p.name, p.python_type, default)
+            } else {
+                format!("{}: {}", p.name, p.python_type)
+            }
+        })
+        .collect();
+
+    // Build the args dict, mapping Python names back to original schema keys
+    let has_optional = params.iter().any(|p| p.default.is_some());
+    let entries: String = params
+        .iter()
+        .map(|p| format!("\"{}\": {}", p.original_name, p.name))
+        .collect::<Vec<_>>()
+        .join(", ");
+
+    let args_expr = if has_optional {
+        format!(
+            "{{k: v for k, v in {{{}}}.items() if v is not None}}",
+            entries
+        )
+    } else {
+        format!("{{{}}}", entries)
+    };
+
+    // Sanitize description for a single-line docstring
+    let raw_desc = tool
+        .description
+        .replace('\\', "\\\\")
+        .replace("\"\"\"", "\"\"\\\"")
+        .replace('\n', " ")
+        .replace('\r', "")
+        .chars()
+        .take(120)
+        .collect::<String>()
+        .trim()
+        .to_string();
+
+    format!(
+        "def {}({}) -> str:\n    \"\"\"{}\"\"\"    \n    return _ptc_call(\"{}\", {})",
+        fn_name,
+        param_parts.join(", "),
+        raw_desc,
+        tool.name,
+        args_expr
+    )
+}
+
+/// Generate the full Python SDK preamble for all PTC tools.
+///
+/// The preamble includes:
+/// - HTTP client setup (urllib.request, zero dependencies)
+/// - The `_ptc_call()` bridge function
+/// - One synchronous function per tool
+pub fn generate_python_sdk(tools: &[ToolDefinition], ipc_port: u16) -> String {
+    let functions: String = tools
+        .iter()
+        .map(generate_function)
+        .collect::<Vec<_>>()
+        .join("\n\n");
+
+    format!(
+        r#"# ── PTC SDK (auto-generated) ────────────────────────────────────────────
+import json
+import urllib.request
+
+_PTC_PORT = {ipc_port}
+
+def _ptc_call(name: str, args: dict) -> str:
+    """Call a tool via the IPC bridge. Returns tool result as string."""
+    data = json.dumps(args).encode("utf-8")
+    req = urllib.request.Request(
+        f"http://127.0.0.1:{{_PTC_PORT}}/tool/{{name}}",
+        data=data,
+        headers={{"Content-Type": "application/json"}},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=300) as resp:
+            return resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        return f"Error calling {{name}}: {{e.code}} - {{body}}"
+    except Exception as e:
+        return f"Error calling {{name}}: {{e}}"
+
+{functions}
+
+# ── User code runs below ────────────────────────────────────────────────
+"#
+    )
+}
+
+/// Wrap user code with the SDK preamble.
+pub fn wrap_user_code(sdk_preamble: &str, user_code: &str) -> String {
+    format!("{}{}\n", sdk_preamble, user_code)
+}
+
+/// Generate compact one-line function signatures for the execute_code tool description.
+///
+/// This is what the LLM sees in its prompt — a compact reference of available functions.
+pub fn generate_compact_reference(tools: &[ToolDefinition]) -> String {
+    let mut lines: Vec<String> = Vec::new();
+
+    // Group tools: built-in vs MCP
+    let mut builtin: Vec<&ToolDefinition> = Vec::new();
+    let mut mcp: Vec<&ToolDefinition> = Vec::new();
+
+    for tool in tools {
+        if tool.name.starts_with("mcp_") {
+            mcp.push(tool);
+        } else {
+            builtin.push(tool);
+        }
+    }
+
+    for tool in &builtin {
+        let sig = generate_function_signature(tool);
+        let desc: String = tool
+            .description
+            .replace('\n', " ")
+            .chars()
+            .take(60)
+            .collect();
+        lines.push(format!("  {} -> str  # {}", sig, desc));
+    }
+
+    if !mcp.is_empty() {
+        lines.push(String::new());
+        lines.push("  # MCP tools:".to_string());
+        for tool in &mcp {
+            let sig = generate_function_signature(tool);
+            let desc: String = tool
+                .description
+                .replace('\n', " ")
+                .chars()
+                .take(60)
+                .collect();
+            lines.push(format!("  {} -> str  # {}", sig, desc));
+        }
+    }
+
+    lines.join("\n")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_tool(name: &str, desc: &str, schema: serde_json::Value) -> ToolDefinition {
+        ToolDefinition {
+            name: name.to_string(),
+            description: desc.to_string(),
+            input_schema: schema,
+        }
+    }
+
+    #[test]
+    fn test_camel_to_snake() {
+        assert_eq!(camel_to_snake("tabId"), "tab_id");
+        assert_eq!(camel_to_snake("pressEnter"), "press_enter");
+        assert_eq!(camel_to_snake("domainSuffix"), "domain_suffix");
+        assert_eq!(camel_to_snake("file_read"), "file_read");
+        assert_eq!(camel_to_snake("HTMLParser"), "h_t_m_l_parser"); // Known edge case
+    }
+
+    #[test]
+    fn test_sanitize_python_name() {
+        assert_eq!(sanitize_python_name("type"), "type_");
+        assert_eq!(sanitize_python_name("class"), "class_");
+        assert_eq!(sanitize_python_name("from"), "from_");
+        assert_eq!(sanitize_python_name("file-read"), "file_read");
+        assert_eq!(sanitize_python_name("maxResults"), "max_results");
+        // Builtins must be suffixed to avoid shadowing
+        assert_eq!(sanitize_python_name("print"), "print_");
+        assert_eq!(sanitize_python_name("input"), "input_");
+        assert_eq!(sanitize_python_name("list"), "list_");
+        assert_eq!(sanitize_python_name("id"), "id_");
+        // Non-conflicting names are unchanged
+        assert_eq!(sanitize_python_name("file_read"), "file_read");
+        assert_eq!(sanitize_python_name("web_search"), "web_search");
+    }
+
+    #[test]
+    fn test_generate_function_simple() {
+        let tool = make_tool(
+            "file_read",
+            "Read a file",
+            serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "path": { "type": "string", "description": "File path" }
+                },
+                "required": ["path"]
+            }),
+        );
+
+        let code = generate_function(&tool);
+        assert!(code.contains("def file_read(path: str) -> str:"));
+        assert!(code.contains("_ptc_call(\"file_read\""));
+    }
+
+    #[test]
+    fn test_generate_function_with_optional() {
+        let tool = make_tool(
+            "web_search",
+            "Search the web",
+            serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "query": { "type": "string" },
+                    "max_results": { "type": "integer", "default": 5 }
+                },
+                "required": ["query"]
+            }),
+        );
+
+        let code = generate_function(&tool);
+        assert!(code.contains("query: str"));
+        assert!(code.contains("max_results: int = 5"));
+        assert!(code.contains("if v is not None"));
+    }
+
+    #[test]
+    fn test_generate_compact_reference() {
+        let tools = vec![
+            make_tool(
+                "file_read",
+                "Read file contents",
+                serde_json::json!({
+                    "type": "object",
+                    "properties": {
+                        "path": { "type": "string" }
+                    },
+                    "required": ["path"]
+                }),
+            ),
+            make_tool(
+                "mcp_github_list",
+                "List GitHub repos",
+                serde_json::json!({
+                    "type": "object",
+                    "properties": {}
+                }),
+            ),
+        ];
+
+        let ref_text = generate_compact_reference(&tools);
+        assert!(ref_text.contains("file_read(path: str) -> str"));
+        assert!(ref_text.contains("# MCP tools:"));
+        assert!(ref_text.contains("mcp_github_list"));
+    }
+
+    #[test]
+    fn test_generate_python_sdk() {
+        let tools = vec![make_tool(
+            "file_read",
+            "Read a file",
+            serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "path": { "type": "string" }
+                },
+                "required": ["path"]
+            }),
+        )];
+
+        let sdk = generate_python_sdk(&tools, 12345);
+        assert!(sdk.contains("_PTC_PORT = 12345"));
+        assert!(sdk.contains("def _ptc_call(name: str, args: dict) -> str:"));
+        assert!(sdk.contains("def file_read(path: str) -> str:"));
+        assert!(sdk.contains("urllib.request"));
+    }
+}
diff --git a/crates/openfang-runtime/src/ptc/tool_classifier.rs b/crates/openfang-runtime/src/ptc/tool_classifier.rs
new file mode 100644
index 000000000..7836ae672
--- /dev/null
+++ b/crates/openfang-runtime/src/ptc/tool_classifier.rs
@@ -0,0 +1,85 @@
+//! Tool classification for Programmatic Tool Calling.
+//!
+//! Determines which tools should remain as direct JSON tool calls
+//! (with full schemas in the LLM prompt) and which should be callable
+//! only via `execute_code` (schemas removed, compact function signatures
+//! shown instead).
+//!
+//! Default: ALL tools are PTC-eligible. There are no tools that technically
+//! must be direct — the classification exists for future extensibility.
+
+use openfang_types::tool::ToolDefinition;
+
+/// Whether a tool is called directly by the LLM or via `execute_code`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PtcMode {
+    /// Tool is called directly by the LLM (full JSON schema in prompt).
+    Direct,
+    /// Tool is callable only via `execute_code` (schema removed from prompt).
+    Ptc,
+}
+
+/// Classify a single tool.
+///
+/// Currently all tools are PTC-eligible. This function exists as an
+/// extension point for future per-tool overrides.
+pub fn classify_tool(tool: &ToolDefinition) -> PtcMode {
+    // The execute_code tool itself must be direct (it IS the PTC entry point)
+    if tool.name == "execute_code" {
+        return PtcMode::Direct;
+    }
+
+    // Everything else is callable via code
+    PtcMode::Ptc
+}
+
+/// Split tools into direct and PTC sets.
+///
+/// Returns `(direct_tools, ptc_tools)`.
+pub fn classify_tools(tools: &[ToolDefinition]) -> (Vec<ToolDefinition>, Vec<ToolDefinition>) {
+    let mut direct = Vec::new();
+    let mut ptc = Vec::new();
+
+    for tool in tools {
+        match classify_tool(tool) {
+            PtcMode::Direct => direct.push(tool.clone()),
+            PtcMode::Ptc => ptc.push(tool.clone()),
+        }
+    }
+
+    (direct, ptc)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_tool(name: &str) -> ToolDefinition {
+        ToolDefinition {
+            name: name.to_string(),
+            description: format!("Test tool {name}"),
+            input_schema: serde_json::json!({"type": "object", "properties": {}}),
+        }
+    }
+
+    #[test]
+    fn test_all_tools_are_ptc_by_default() {
+        let tools = vec![
+            make_tool("file_read"),
+            make_tool("web_search"),
+            make_tool("shell_exec"),
+            make_tool("agent_send"),
+            make_tool("mcp_github_list"),
+        ];
+
+        let (direct, ptc) = classify_tools(&tools);
+        assert!(direct.is_empty());
+        assert_eq!(ptc.len(), 5);
+    }
+
+    #[test]
+    fn test_execute_code_is_always_direct() {
+        let tool = make_tool("execute_code");
+        assert_eq!(classify_tool(&tool), PtcMode::Direct);
+    }
+}
diff --git a/crates/openfang-types/src/agent.rs b/crates/openfang-types/src/agent.rs
index 420380715..7fa227e0d 100644
--- a/crates/openfang-types/src/agent.rs
+++ b/crates/openfang-types/src/agent.rs
@@ -491,6 +491,10 @@ pub struct AgentManifest {
     /// Tool blocklist — these tools are excluded (applied after allowlist).
     #[serde(default, deserialize_with = "crate::serde_compat::vec_lenient")]
     pub tool_blocklist: Vec<String>,
+    /// Per-agent Programmatic Tool Calling override. If `None`, uses global ptc.enabled.
+    /// Set to `false` to disable PTC for this agent (use traditional tool schemas).
+    #[serde(default)]
+    pub ptc_enabled: Option<bool>,
 }
 
 fn default_true() -> bool {
@@ -525,6 +529,7 @@ impl Default for AgentManifest {
             exec_policy: None,
             tool_allowlist: Vec::new(),
             tool_blocklist: Vec::new(),
+            ptc_enabled: None,
         }
     }
 }
@@ -782,6 +787,7 @@ mod tests {
             exec_policy: None,
             tool_allowlist: Vec::new(),
             tool_blocklist: Vec::new(),
+            ptc_enabled: None,
         };
         let json = serde_json::to_string(&manifest).unwrap();
         let deserialized: AgentManifest = serde_json::from_str(&json).unwrap();
diff --git a/crates/openfang-types/src/config.rs b/crates/openfang-types/src/config.rs
index 2c85ae35d..95486fe96 100644
--- a/crates/openfang-types/src/config.rs
+++ b/crates/openfang-types/src/config.rs
@@ -964,6 +964,34 @@ impl Default for ThinkingConfig {
     }
 }
 
+/// Programmatic Tool Calling (PTC) configuration.
+///
+/// When enabled, agents receive a single `execute_code` tool instead of
+/// individual tool JSON schemas. The LLM writes Python code that calls
+/// tools as functions, and only `print()` output enters the context window.
+/// This reduces context usage by 30-40%+ and eliminates multi-turn tool roundtrips.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default)]
+pub struct PtcConfig {
+    /// Whether PTC is enabled globally (default: true).
+    /// Per-agent override via `ptc_enabled` in agent manifests.
+    pub enabled: bool,
+    /// Timeout for Python subprocess execution in seconds (default: 120).
+    pub timeout_secs: u64,
+    /// Maximum stdout size in bytes before truncation (default: 100000).
+    pub max_stdout_bytes: usize,
+}
+
+impl Default for PtcConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            timeout_secs: 120,
+            max_stdout_bytes: 100_000,
+        }
+    }
+}
+
 /// Top-level kernel configuration.
 #[derive(Clone, Serialize, Deserialize)]
 #[serde(default)]
@@ -1107,6 +1135,11 @@ pub struct KernelConfig {
     /// Heartbeat monitor settings.
     #[serde(default)]
     pub heartbeat: HeartbeatSettings,
+    /// Programmatic Tool Calling (PTC) configuration.
+    /// When enabled (default), agents get a single `execute_code` tool instead of
+    /// 50+ individual tool schemas, reducing context usage by 30-40%+.
+    #[serde(default)]
+    pub ptc: PtcConfig,
 }
 
 /// Heartbeat monitor settings exposed in `[heartbeat]` config section.
@@ -1344,6 +1377,7 @@ impl Default for KernelConfig {
             auth: AuthConfig::default(),
             workflows_dir: None,
             heartbeat: HeartbeatSettings::default(),
+            ptc: PtcConfig::default(),
         }
     }
 }

From 89c283e0ad2f8ac9a427bfbf4e8f5850b46d6cad Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Mon, 16 Mar 2026 16:52:19 +0000
Subject: [PATCH 2/8] fix: PTC for mcp

---
 crates/openfang-kernel/src/kernel.rs          | 23 +++++++++++++++--
 crates/openfang-runtime/src/prompt_builder.rs | 25 +++++++++++++------
 2 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/crates/openfang-kernel/src/kernel.rs b/crates/openfang-kernel/src/kernel.rs
index 0df65dd1d..3cbd7af08 100644
--- a/crates/openfang-kernel/src/kernel.rs
+++ b/crates/openfang-kernel/src/kernel.rs
@@ -1903,6 +1903,7 @@ impl OpenFangKernel {
                 ),
                 sender_id,
                 sender_name,
+                ptc_enabled: manifest.ptc_enabled.unwrap_or(self.config.ptc.enabled),
             };
             manifest.model.system_prompt =
                 openfang_runtime::prompt_builder::build_system_prompt(&prompt_ctx);
@@ -2464,6 +2465,7 @@ impl OpenFangKernel {
                 ),
                 sender_id,
                 sender_name,
+                ptc_enabled: manifest.ptc_enabled.unwrap_or(self.config.ptc.enabled),
             };
             manifest.model.system_prompt =
                 openfang_runtime::prompt_builder::build_system_prompt(&prompt_ctx);
@@ -3369,6 +3371,13 @@ impl OpenFangKernel {
             } else {
                 None
             },
+            // Do NOT set tool_allowlist here — capabilities.tools (line 3223) already
+            // provides the primary tool filter in available_tools() Step 1.
+            // Setting tool_allowlist to def.tools would cause Step 4 to strip out
+            // MCP tools that were correctly added in Step 3 via mcp_servers opt-in,
+            // because MCP tool names (mcp_github_*, etc.) are dynamic and not in
+            // the hand's static tool list.
+            tool_allowlist: Vec::new(),
             tool_blocklist: Vec::new(),
             ptc_enabled: None,
             // Custom profile avoids ToolProfile-based expansion overriding the
@@ -5174,9 +5183,19 @@ impl OpenFangKernel {
                     .cloned()
                     .collect()
             };
+            // When an agent explicitly lists MCP servers via `mcp_servers`,
+            // include all tools from those servers without requiring each
+            // tool name in the declared tools list.  MCP tool names are
+            // dynamic and change when the upstream server updates, so
+            // `mcp_servers` acts as the opt-in for the entire server's
+            // tool set.  If the agent does NOT list mcp_servers (empty
+            // allowlist → all MCP tools are candidates), fall back to the
+            // declared-tools filter to avoid flooding the context.
+            let mcp_explicitly_opted_in = !mcp_allowlist.is_empty();
             for t in mcp_candidates {
-                // If agent declares specific tools, only include matching MCP tools
-                if !tools_unrestricted && !declared_tools.iter().any(|d| d == &t.name) {
+                if !tools_unrestricted && !mcp_explicitly_opted_in
+                    && !declared_tools.iter().any(|d| d == &t.name)
+                {
                     continue;
                 }
                 all_tools.push(t);
diff --git a/crates/openfang-runtime/src/prompt_builder.rs b/crates/openfang-runtime/src/prompt_builder.rs
index fbe0bdbd3..a2410ffb2 100644
--- a/crates/openfang-runtime/src/prompt_builder.rs
+++ b/crates/openfang-runtime/src/prompt_builder.rs
@@ -59,6 +59,10 @@ pub struct PromptContext {
     pub sender_id: Option<String>,
     /// Sender display name.
     pub sender_name: Option<String>,
+    /// Whether Programmatic Tool Calling is enabled for this agent.
+    /// When true, the `## Your Tools` section is omitted — tool information
+    /// is provided via the `execute_code` tool description instead.
+    pub ptc_enabled: bool,
 }
 
 /// Build the complete system prompt from a `PromptContext`.
@@ -77,8 +81,9 @@ pub fn build_system_prompt(ctx: &PromptContext) -> String {
         sections.push(format!("## Current Date\nToday is {date}."));
     }
 
-    // Section 2 — Tool Call Behavior (skip for subagents)
-    if !ctx.is_subagent {
+    // Section 2 — Tool Call Behavior (skip for subagents and PTC agents —
+    // PTC agents get their own behavioral guidance in the PTC supplement)
+    if !ctx.is_subagent && !ctx.ptc_enabled {
         sections.push(TOOL_CALL_BEHAVIOR.to_string());
     }
 
@@ -91,10 +96,13 @@ pub fn build_system_prompt(ctx: &PromptContext) -> String {
         }
     }
 
-    // Section 3 — Available Tools (always present if tools exist)
-    let tools_section = build_tools_section(&ctx.granted_tools);
-    if !tools_section.is_empty() {
-        sections.push(tools_section);
+    // Section 3 — Available Tools (skip when PTC is enabled — tools are listed
+    // as Python function signatures in the execute_code tool description instead)
+    if !ctx.ptc_enabled {
+        let tools_section = build_tools_section(&ctx.granted_tools);
+        if !tools_section.is_empty() {
+            sections.push(tools_section);
+        }
     }
 
     // Section 4 — Memory Protocol (always present)
@@ -109,8 +117,9 @@ pub fn build_system_prompt(ctx: &PromptContext) -> String {
         ));
     }
 
-    // Section 6 — MCP Servers (only if summary present)
-    if !ctx.mcp_summary.is_empty() {
+    // Section 6 — MCP Servers (skip when PTC is enabled — MCP tools are listed
+    // as Python functions in the execute_code tool description instead)
+    if !ctx.ptc_enabled && !ctx.mcp_summary.is_empty() {
         sections.push(build_mcp_section(&ctx.mcp_summary));
     }
 

From 44fe02853a2b395297617fe509ea3daaa0edd64c Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Tue, 17 Mar 2026 10:14:32 +0000
Subject: [PATCH 3/8] fix: dockerfile with python 3.14 for better PTC

---
 Dockerfile | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 7b30b258d..a193be28f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,12 +15,9 @@ ENV CARGO_PROFILE_RELEASE_LTO=${LTO} \
     CARGO_PROFILE_RELEASE_CODEGEN_UNITS=${CODEGEN_UNITS}
 RUN cargo build --release --bin openfang
 
-FROM rust:1-slim-bookworm
+FROM python:3.14-slim-bookworm
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates \
-    python3 \
-    python3-pip \
-    python3-venv \
     nodejs \
     npm \
     && rm -rf /var/lib/apt/lists/*

From 729f0341b188135c78189f9e2ae8fd8785c4dcdc Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Sat, 21 Mar 2026 19:02:36 +0000
Subject: [PATCH 4/8] fix: PTC autonomous agent crashes (memory double-encode,
 empty results, heartbeat timeout)

- memory_recall: unwrap Value::String directly to avoid double-encoding
- memory_store: remove type:string constraint on value schema
- task_list/task_claim/agent_list: return parseable JSON ([], null) for empty results
- heartbeat: touch_active during PTC IPC dispatch to prevent false crash detection
- heartbeat: timeout uses max(heartbeat*2, max_tick_duration) to cover long ticks
---
 crates/openfang-kernel/src/heartbeat.rs      |  9 +++++++--
 crates/openfang-kernel/src/kernel.rs         |  6 ++++++
 crates/openfang-runtime/src/agent_loop.rs    |  8 ++++++++
 crates/openfang-runtime/src/kernel_handle.rs |  7 +++++++
 crates/openfang-runtime/src/tool_runner.rs   | 19 ++++++++++++++-----
 5 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/crates/openfang-kernel/src/heartbeat.rs b/crates/openfang-kernel/src/heartbeat.rs
index ddfe0488d..423fe6300 100644
--- a/crates/openfang-kernel/src/heartbeat.rs
+++ b/crates/openfang-kernel/src/heartbeat.rs
@@ -149,12 +149,17 @@ pub fn check_agents(registry: &AgentRegistry, config: &HeartbeatConfig) -> Vec<H
 
         let inactive_secs = (now - entry_ref.last_active).num_seconds();
 
-        // Determine timeout: use agent's autonomous config if set, else default
+        // Determine timeout: use agent's autonomous config if set, else default.
+        // The timeout must be at least as long as the agent's max_tick_duration
+        // to avoid marking agents as unresponsive during long PTC/execute_code runs.
         let timeout_secs = entry_ref
             .manifest
             .autonomous
             .as_ref()
-            .map(|a| a.heartbeat_interval_secs * UNRESPONSIVE_MULTIPLIER)
+            .map(|a| {
+                let heartbeat_timeout = a.heartbeat_interval_secs * UNRESPONSIVE_MULTIPLIER;
+                heartbeat_timeout.max(a.max_tick_duration_secs)
+            })
             .unwrap_or(config.default_timeout_secs) as i64;
 
         // --- Skip idle agents that have never genuinely processed a message ---
diff --git a/crates/openfang-kernel/src/kernel.rs b/crates/openfang-kernel/src/kernel.rs
index 3cbd7af08..4d816b79f 100644
--- a/crates/openfang-kernel/src/kernel.rs
+++ b/crates/openfang-kernel/src/kernel.rs
@@ -5937,6 +5937,12 @@ impl KernelHandle for OpenFangKernel {
         OpenFangKernel::kill_agent(self, id).map_err(|e| format!("Kill failed: {e}"))
     }
 
+    fn touch_active(&self, agent_id: &str) {
+        if let Ok(id) = agent_id.parse::<AgentId>() {
+            let _ = self.registry.set_state(id, AgentState::Running);
+        }
+    }
+
     fn memory_store(&self, key: &str, value: serde_json::Value) -> Result<(), String> {
         let agent_id = shared_memory_agent_id();
         self.memory
diff --git a/crates/openfang-runtime/src/agent_loop.rs b/crates/openfang-runtime/src/agent_loop.rs
index 42ef4f384..315dcb326 100644
--- a/crates/openfang-runtime/src/agent_loop.rs
+++ b/crates/openfang-runtime/src/agent_loop.rs
@@ -859,6 +859,10 @@ pub async fn run_agent_loop(
                                 }
                                 // IPC tool request from Python
                                 Some(req) = ptc.ipc_server.request_rx.recv() => {
+                                    // Touch heartbeat: prove agent is alive during PTC execution
+                                    if let Some(ref kh) = kernel {
+                                        kh.touch_active(&caller_id_str);
+                                    }
                                     let eff_exec_policy = manifest.exec_policy.as_ref();
                                     let tool_result = tool_runner::execute_tool(
                                         &req.tool_call_id,
@@ -2119,6 +2123,10 @@ pub async fn run_agent_loop_streaming(
                                     break py_result.ok();
                                 }
                                 Some(req) = ptc.ipc_server.request_rx.recv() => {
+                                    // Touch heartbeat: prove agent is alive during PTC execution
+                                    if let Some(ref kh) = kernel {
+                                        kh.touch_active(&caller_id_str);
+                                    }
                                     let eff_exec_policy = manifest.exec_policy.as_ref();
                                     let tool_result = tool_runner::execute_tool(
                                         &req.tool_call_id,
diff --git a/crates/openfang-runtime/src/kernel_handle.rs b/crates/openfang-runtime/src/kernel_handle.rs
index e3e1b7633..4f09d7407 100644
--- a/crates/openfang-runtime/src/kernel_handle.rs
+++ b/crates/openfang-runtime/src/kernel_handle.rs
@@ -244,6 +244,13 @@ pub trait KernelHandle: Send + Sync {
         let _ = agent_id;
     }
 
+    /// Touch the agent's `last_active` timestamp to signal the heartbeat monitor
+    /// that the agent is alive. Called during long-running PTC tool execution so
+    /// the agent isn't incorrectly marked as unresponsive.
+    fn touch_active(&self, _agent_id: &str) {
+        // Default: no-op. The kernel overrides this to update the registry.
+    }
+
     /// Spawn an agent with capability inheritance enforcement.
     /// `parent_caps` are the parent's granted capabilities. The kernel MUST verify
     /// that every capability in the child manifest is covered by `parent_caps`.
diff --git a/crates/openfang-runtime/src/tool_runner.rs b/crates/openfang-runtime/src/tool_runner.rs
index 664735c88..58c3f8889 100644
--- a/crates/openfang-runtime/src/tool_runner.rs
+++ b/crates/openfang-runtime/src/tool_runner.rs
@@ -697,7 +697,7 @@ pub fn builtin_tool_definitions() -> Vec<ToolDefinition> {
                 "type": "object",
                 "properties": {
                     "key": { "type": "string", "description": "The storage key" },
-                    "value": { "type": "string", "description": "The value to store (JSON-encode objects/arrays, or pass a plain string)" }
+                    "value": { "description": "The value to store (string, number, boolean, object, or array)" }
                 },
                 "required": ["key", "value"]
             }),
@@ -1667,7 +1667,7 @@ fn tool_agent_list(kernel: Option<&Arc<dyn KernelHandle>>) -> Result<String, Str
     let kh = require_kernel(kernel)?;
     let agents = kh.list_agents();
     if agents.is_empty() {
-        return Ok("No agents currently running.".to_string());
+        return Ok("[]".to_string());
     }
     let mut output = format!("Running agents ({}):\n", agents.len());
     for a in &agents {
@@ -1713,7 +1713,16 @@ fn tool_memory_recall(
     let kh = require_kernel(kernel)?;
     let key = input["key"].as_str().ok_or("Missing 'key' parameter")?;
     match kh.memory_recall(key)? {
-        Some(val) => Ok(serde_json::to_string_pretty(&val).unwrap_or_else(|_| val.to_string())),
+        Some(val) => match &val {
+            // Return raw string content to avoid double-encoding.
+            // When an LLM stores `json.dumps({...})` via PTC, the value is
+            // `Value::String("{...}")`. Without this unwrap, `to_string_pretty`
+            // would produce `"\"{...}\""` — a double-encoded string that the
+            // caller must parse twice.
+            serde_json::Value::String(s) => Ok(s.clone()),
+            other => Ok(serde_json::to_string_pretty(other)
+                .unwrap_or_else(|_| other.to_string())),
+        },
         None => Ok(format!("No value found for key '{key}'.")),
     }
 }
@@ -1776,7 +1785,7 @@ async fn tool_task_claim(
         Some(task) => {
             serde_json::to_string_pretty(&task).map_err(|e| format!("Serialize error: {e}"))
         }
-        None => Ok("No tasks available.".to_string()),
+        None => Ok("null".to_string()),
     }
 }
 
@@ -1803,7 +1812,7 @@ async fn tool_task_list(
     let status = input["status"].as_str();
     let tasks = kh.task_list(status).await?;
     if tasks.is_empty() {
-        return Ok("No tasks found.".to_string());
+        return Ok("[]".to_string());
     }
     serde_json::to_string_pretty(&tasks).map_err(|e| format!("Serialize error: {e}"))
 }

From a1e73f637d221b18f0c6ddd0da3542796811ec20 Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Sat, 21 Mar 2026 19:13:56 +0000
Subject: [PATCH 5/8] fix: backport PTC fixes from main

- Fix test assertions: find_header_end returns position of \r\n\r\n start (31 not 33)
- Fix camel_to_snake: accept acronym merge behavior (htmlparser)
- Fix text_tool_call_recovery tests: disable PTC to test raw tool list recovery
- Add phantom_action_detected: prevent hallucinated channel actions
- Add image block stripping: prevent base64 bloat in session history
- Add has_any_content(): distinguish empty vs thinking-only responses
- Add thinking config to ModelConfig: support extended thinking per-agent
- Add max_tick_duration_secs to AutonomousConfig: prevent false crash detection
---
 crates/openfang-kernel/src/kernel.rs             |  1 +
 crates/openfang-kernel/src/wizard.rs             |  1 +
 crates/openfang-runtime/src/agent_loop.rs        | 12 ++++++++----
 crates/openfang-runtime/src/ptc/ipc_server.rs    |  3 ++-
 crates/openfang-runtime/src/ptc/sdk_generator.rs |  2 +-
 crates/openfang-types/src/agent.rs               | 11 +++++++++++
 6 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/crates/openfang-kernel/src/kernel.rs b/crates/openfang-kernel/src/kernel.rs
index 4d816b79f..60466ecd6 100644
--- a/crates/openfang-kernel/src/kernel.rs
+++ b/crates/openfang-kernel/src/kernel.rs
@@ -3331,6 +3331,7 @@ impl OpenFangKernel {
                 system_prompt: def.agent.system_prompt.clone(),
                 api_key_env: def.agent.api_key_env.clone(),
                 base_url: def.agent.base_url.clone(),
+                thinking: None,
             },
             capabilities: ManifestCapabilities {
                 tools: def.tools.clone(),
diff --git a/crates/openfang-kernel/src/wizard.rs b/crates/openfang-kernel/src/wizard.rs
index c6cce6b42..2efb8debe 100644
--- a/crates/openfang-kernel/src/wizard.rs
+++ b/crates/openfang-kernel/src/wizard.rs
@@ -163,6 +163,7 @@ impl SetupWizard {
                 system_prompt,
                 api_key_env: None,
                 base_url: None,
+                thinking: None,
             },
             resources: ResourceQuota::default(),
             priority: Priority::default(),
diff --git a/crates/openfang-runtime/src/agent_loop.rs b/crates/openfang-runtime/src/agent_loop.rs
index 315dcb326..c17f9960e 100644
--- a/crates/openfang-runtime/src/agent_loop.rs
+++ b/crates/openfang-runtime/src/agent_loop.rs
@@ -462,7 +462,7 @@ pub async fn run_agent_loop(
             max_tokens: manifest.model.max_tokens,
             temperature: manifest.model.temperature,
             system: Some(system_prompt.clone()),
-            thinking: None,
+            thinking: manifest.model.thinking.clone(),
         };
 
         // Notify phase: Thinking
@@ -1761,7 +1761,7 @@ pub async fn run_agent_loop_streaming(
             max_tokens: manifest.model.max_tokens,
             temperature: manifest.model.temperature,
             system: Some(system_prompt.clone()),
-            thinking: None,
+            thinking: manifest.model.thinking.clone(),
         };
 
         // Notify phase: on first iteration emit Streaming; on subsequent
@@ -4757,7 +4757,9 @@ mod tests {
             context_window_tokens: 0,
             label: None,
         };
-        let manifest = test_manifest();
+        let mut manifest = test_manifest();
+        // Disable PTC so the raw tool list (with web_search) is used for recovery
+        manifest.ptc_enabled = Some(false);
         let driver: Arc<dyn LlmDriver> = Arc::new(TextToolCallDriver::new());
 
         // Provide web_search as an available tool so recovery can match it
@@ -4885,7 +4887,9 @@ mod tests {
             context_window_tokens: 0,
             label: None,
         };
-        let manifest = test_manifest();
+        let mut manifest = test_manifest();
+        // Disable PTC so the raw tool list (with web_search) is used for recovery
+        manifest.ptc_enabled = Some(false);
         let driver: Arc<dyn LlmDriver> = Arc::new(TextToolCallDriver::new());
 
         let tools = vec![ToolDefinition {
diff --git a/crates/openfang-runtime/src/ptc/ipc_server.rs b/crates/openfang-runtime/src/ptc/ipc_server.rs
index 2036e5db4..132868e2f 100644
--- a/crates/openfang-runtime/src/ptc/ipc_server.rs
+++ b/crates/openfang-runtime/src/ptc/ipc_server.rs
@@ -372,7 +372,8 @@ mod tests {
     #[test]
     fn test_find_header_end() {
         let data = b"GET / HTTP/1.1\r\nHost: localhost\r\n\r\nbody";
-        assert_eq!(find_header_end(data), Some(33));
+        // find_header_end returns the position of the first byte of \r\n\r\n
+        assert_eq!(find_header_end(data), Some(31));
     }
 
     #[test]
diff --git a/crates/openfang-runtime/src/ptc/sdk_generator.rs b/crates/openfang-runtime/src/ptc/sdk_generator.rs
index aed253478..e3fd5eb45 100644
--- a/crates/openfang-runtime/src/ptc/sdk_generator.rs
+++ b/crates/openfang-runtime/src/ptc/sdk_generator.rs
@@ -425,7 +425,7 @@ mod tests {
         assert_eq!(camel_to_snake("pressEnter"), "press_enter");
         assert_eq!(camel_to_snake("domainSuffix"), "domain_suffix");
         assert_eq!(camel_to_snake("file_read"), "file_read");
-        assert_eq!(camel_to_snake("HTMLParser"), "h_t_m_l_parser"); // Known edge case
+        assert_eq!(camel_to_snake("HTMLParser"), "htmlparser"); // Acronyms merge — acceptable for SDK names
     }
 
     #[test]
diff --git a/crates/openfang-types/src/agent.rs b/crates/openfang-types/src/agent.rs
index 7fa227e0d..0dc3fa22f 100644
--- a/crates/openfang-types/src/agent.rs
+++ b/crates/openfang-types/src/agent.rs
@@ -80,6 +80,9 @@ pub struct AutonomousConfig {
     pub heartbeat_interval_secs: u64,
     /// Channel to send heartbeat status to (e.g., "telegram", "discord").
     pub heartbeat_channel: Option<String>,
+    /// Maximum wall-clock seconds for a single background tick.
+    /// If a tick exceeds this duration it is cancelled. Default: 300 (5 min).
+    pub max_tick_duration_secs: u64,
 }
 
 impl Default for AutonomousConfig {
@@ -90,6 +93,7 @@ impl Default for AutonomousConfig {
             max_restarts: 10,
             heartbeat_interval_secs: 30,
             heartbeat_channel: None,
+            max_tick_duration_secs: 300,
         }
     }
 }
@@ -386,6 +390,11 @@ pub struct ModelConfig {
     pub api_key_env: Option<String>,
     /// Optional base URL override for the provider.
     pub base_url: Option<String>,
+    /// Extended thinking configuration. None = thinking disabled.
+    /// Only supported by models that have reasoning capability
+    /// (e.g. Claude Sonnet 4.5+, Claude Sonnet 4.6 via OpenRouter).
+    #[serde(default)]
+    pub thinking: Option<crate::config::ThinkingConfig>,
 }
 
 impl Default for ModelConfig {
@@ -398,6 +407,7 @@ impl Default for ModelConfig {
             system_prompt: "You are a helpful AI agent.".to_string(),
             api_key_env: None,
             base_url: None,
+            thinking: None,
         }
     }
 }
@@ -727,6 +737,7 @@ mod tests {
         assert_eq!(cfg.max_iterations, 50);
         assert_eq!(cfg.max_restarts, 10);
         assert_eq!(cfg.heartbeat_interval_secs, 30);
+        assert_eq!(cfg.max_tick_duration_secs, 300);
         assert!(cfg.quiet_hours.is_none());
     }
 

From 1b9cfc92b817586c65d4d0bdd042733ac083079d Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Sat, 21 Mar 2026 19:15:53 +0000
Subject: [PATCH 6/8] style: cargo fmt

---
 crates/openfang-kernel/src/kernel.rs          |  3 +-
 crates/openfang-runtime/src/agent_loop.rs     | 49 +++++++--------
 crates/openfang-runtime/src/lib.rs            |  2 +-
 crates/openfang-runtime/src/ptc/executor.rs   | 59 +++++++++----------
 crates/openfang-runtime/src/ptc/ipc_server.rs | 22 ++-----
 crates/openfang-runtime/src/ptc/mod.rs        |  4 +-
 crates/openfang-runtime/src/tool_runner.rs    |  3 +-
 7 files changed, 63 insertions(+), 79 deletions(-)

diff --git a/crates/openfang-kernel/src/kernel.rs b/crates/openfang-kernel/src/kernel.rs
index 60466ecd6..818a0167c 100644
--- a/crates/openfang-kernel/src/kernel.rs
+++ b/crates/openfang-kernel/src/kernel.rs
@@ -5194,7 +5194,8 @@ impl OpenFangKernel {
             // declared-tools filter to avoid flooding the context.
             let mcp_explicitly_opted_in = !mcp_allowlist.is_empty();
             for t in mcp_candidates {
-                if !tools_unrestricted && !mcp_explicitly_opted_in
+                if !tools_unrestricted
+                    && !mcp_explicitly_opted_in
                     && !declared_tools.iter().any(|d| d == &t.name)
                 {
                     continue;
diff --git a/crates/openfang-runtime/src/agent_loop.rs b/crates/openfang-runtime/src/agent_loop.rs
index c17f9960e..b7c99fa46 100644
--- a/crates/openfang-runtime/src/agent_loop.rs
+++ b/crates/openfang-runtime/src/agent_loop.rs
@@ -829,10 +829,9 @@ pub async fn run_agent_loop(
                     // Timeout-wrapped execution
                     // PTC interception: if this is execute_code and PTC is active,
                     // run Python and concurrently dispatch tool calls from the IPC channel.
-                    let result = if let (true, Some(ptc)) = (
-                        tool_call.name == "execute_code",
-                        ptc_instance.as_mut(),
-                    ) {
+                    let result = if let (true, Some(ptc)) =
+                        (tool_call.name == "execute_code", ptc_instance.as_mut())
+                    {
                         let code = tool_call.input["code"].as_str().unwrap_or("");
                         let ptc_timeout = tool_call.input["timeout"]
                             .as_u64()
@@ -840,13 +839,15 @@ pub async fn run_agent_loop(
                             .clamp(10, 600);
 
                         // Generate SDK and run Python
-                        let sdk = crate::ptc::generate_python_sdk(&ptc.ptc_tools, ptc.ipc_server.port());
+                        let sdk =
+                            crate::ptc::generate_python_sdk(&ptc.ptc_tools, ptc.ipc_server.port());
                         let full_script = crate::ptc::wrap_user_code(&sdk, code);
 
                         // Spawn the Python subprocess as a future
                         let ws = workspace_root.map(|p| p.to_path_buf());
                         let mut python_fut = tokio::spawn(async move {
-                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref()).await
+                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref())
+                                .await
                         });
 
                         // Concurrently handle IPC tool requests while Python runs.
@@ -1649,18 +1650,19 @@ pub async fn run_agent_loop_streaming(
     let ptc_global_enabled = manifest.ptc_enabled.unwrap_or(true);
     let ptc_config = crate::ptc::PtcConfig::default();
 
-    let mut ptc_instance: Option<crate::ptc::PtcInstance> =
-        if ptc_global_enabled && !available_tools.is_empty() {
-            match crate::ptc::init_ptc(available_tools).await {
-                Ok(instance) => Some(instance),
-                Err(e) => {
-                    warn!("PTC initialization failed (streaming), falling back to direct tools: {e}");
-                    None
-                }
+    let mut ptc_instance: Option<crate::ptc::PtcInstance> = if ptc_global_enabled
+        && !available_tools.is_empty()
+    {
+        match crate::ptc::init_ptc(available_tools).await {
+            Ok(instance) => Some(instance),
+            Err(e) => {
+                warn!("PTC initialization failed (streaming), falling back to direct tools: {e}");
+                None
             }
-        } else {
-            None
-        };
+        }
+    } else {
+        None
+    };
 
     let ptc_tools_vec: Vec<ToolDefinition>;
     let available_tools = if let Some(ref ptc) = ptc_instance {
@@ -2099,22 +2101,23 @@ pub async fn run_agent_loop_streaming(
 
                     // Timeout-wrapped execution
                     // PTC interception (streaming): same as non-streaming path.
-                    let result = if let (true, Some(ptc)) = (
-                        tool_call.name == "execute_code",
-                        ptc_instance.as_mut(),
-                    ) {
+                    let result = if let (true, Some(ptc)) =
+                        (tool_call.name == "execute_code", ptc_instance.as_mut())
+                    {
                         let code = tool_call.input["code"].as_str().unwrap_or("");
                         let ptc_timeout = tool_call.input["timeout"]
                             .as_u64()
                             .unwrap_or(ptc_config.timeout_secs)
                             .clamp(10, 600);
 
-                        let sdk = crate::ptc::generate_python_sdk(&ptc.ptc_tools, ptc.ipc_server.port());
+                        let sdk =
+                            crate::ptc::generate_python_sdk(&ptc.ptc_tools, ptc.ipc_server.port());
                         let full_script = crate::ptc::wrap_user_code(&sdk, code);
 
                         let ws = workspace_root.map(|p| p.to_path_buf());
                         let mut python_fut = tokio::spawn(async move {
-                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref()).await
+                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref())
+                                .await
                         });
 
                         let python_result: Option<crate::ptc::executor::PythonResult> = loop {
diff --git a/crates/openfang-runtime/src/lib.rs b/crates/openfang-runtime/src/lib.rs
index bd811113b..83561e6b5 100644
--- a/crates/openfang-runtime/src/lib.rs
+++ b/crates/openfang-runtime/src/lib.rs
@@ -36,8 +36,8 @@ pub mod media_understanding;
 pub mod model_catalog;
 pub mod process_manager;
 pub mod prompt_builder;
-pub mod ptc;
 pub mod provider_health;
+pub mod ptc;
 pub mod python_runtime;
 pub mod reply_directives;
 pub mod retry;
diff --git a/crates/openfang-runtime/src/ptc/executor.rs b/crates/openfang-runtime/src/ptc/executor.rs
index 863bb1c4d..b30321a3d 100644
--- a/crates/openfang-runtime/src/ptc/executor.rs
+++ b/crates/openfang-runtime/src/ptc/executor.rs
@@ -28,8 +28,10 @@ pub fn is_python3_available() -> bool {
     PYTHON3_AVAILABLE.store(if available { 1 } else { 2 }, Ordering::Relaxed);
 
     if !available {
-        warn!("python3 not found — Programmatic Tool Calling (PTC) will be disabled. \
-               Install Python 3 to enable PTC.");
+        warn!(
+            "python3 not found — Programmatic Tool Calling (PTC) will be disabled. \
+               Install Python 3 to enable PTC."
+        );
     }
 
     available
@@ -58,8 +60,8 @@ pub async fn execute_python(
     timeout_secs: u64,
     workspace_root: Option<&Path>,
 ) -> PythonResult {
-    use tokio::process::Command;
     use tokio::io::AsyncReadExt;
+    use tokio::process::Command;
 
     let mut cmd = Command::new("python3");
     cmd.arg("-u").arg("-c").arg(script);
@@ -99,32 +101,29 @@ pub async fn execute_python(
     let mut stdout_pipe = child.stdout.take().unwrap();
     let mut stderr_pipe = child.stderr.take().unwrap();
 
-    let result = tokio::time::timeout(
-        std::time::Duration::from_secs(timeout_secs),
-        async {
-            let (stdout_result, stderr_result) = tokio::join!(
-                async {
-                    let mut buf = Vec::new();
-                    stdout_pipe.read_to_end(&mut buf).await.ok();
-                    String::from_utf8_lossy(&buf).into_owned()
-                },
-                async {
-                    let mut buf = Vec::new();
-                    stderr_pipe.read_to_end(&mut buf).await.ok();
-                    String::from_utf8_lossy(&buf).into_owned()
-                }
-            );
-
-            let status = child.wait().await;
-            let exit_code = status.map(|s| s.code().unwrap_or(1)).unwrap_or(1);
-
-            PythonResult {
-                stdout: stdout_result,
-                stderr: stderr_result,
-                exit_code,
+    let result = tokio::time::timeout(std::time::Duration::from_secs(timeout_secs), async {
+        let (stdout_result, stderr_result) = tokio::join!(
+            async {
+                let mut buf = Vec::new();
+                stdout_pipe.read_to_end(&mut buf).await.ok();
+                String::from_utf8_lossy(&buf).into_owned()
+            },
+            async {
+                let mut buf = Vec::new();
+                stderr_pipe.read_to_end(&mut buf).await.ok();
+                String::from_utf8_lossy(&buf).into_owned()
             }
-        },
-    )
+        );
+
+        let status = child.wait().await;
+        let exit_code = status.map(|s| s.code().unwrap_or(1)).unwrap_or(1);
+
+        PythonResult {
+            stdout: stdout_result,
+            stderr: stderr_result,
+            exit_code,
+        }
+    })
     .await;
 
     match result {
@@ -165,8 +164,6 @@ mod tests {
     async fn test_execute_python_timeout() {
         let result = execute_python("import time; time.sleep(60)", 1, None).await;
         assert_ne!(result.exit_code, 0);
-        assert!(
-            result.stderr.contains("timed out") || result.exit_code != 0
-        );
+        assert!(result.stderr.contains("timed out") || result.exit_code != 0);
     }
 }
diff --git a/crates/openfang-runtime/src/ptc/ipc_server.rs b/crates/openfang-runtime/src/ptc/ipc_server.rs
index 132868e2f..9b5c48afc 100644
--- a/crates/openfang-runtime/src/ptc/ipc_server.rs
+++ b/crates/openfang-runtime/src/ptc/ipc_server.rs
@@ -83,10 +83,7 @@ pub async fn start_ipc_server(
     ptc_tools: &[ToolDefinition],
 ) -> Result<PtcIpcServer, std::io::Error> {
     // Build tool name set for validation
-    let tool_names: HashMap<String, ()> = ptc_tools
-        .iter()
-        .map(|t| (t.name.clone(), ()))
-        .collect();
+    let tool_names: HashMap<String, ()> = ptc_tools.iter().map(|t| (t.name.clone(), ())).collect();
     let tool_names = Arc::new(tool_names);
 
     // Channel for tool requests: IPC server → agent loop
@@ -98,12 +95,7 @@ pub async fn start_ipc_server(
 
     let (shutdown_tx, shutdown_rx) = oneshot::channel::<()>();
 
-    let join_handle = tokio::spawn(run_server(
-        listener,
-        tool_names,
-        request_tx,
-        shutdown_rx,
-    ));
+    let join_handle = tokio::spawn(run_server(listener, tool_names, request_tx, shutdown_rx));
 
     debug!(port, "PTC IPC server started");
 
@@ -213,12 +205,7 @@ async fn handle_connection(
 
     // Validate tool exists
     if !tool_names.contains_key(&tool_name) {
-        send_response(
-            &mut stream,
-            404,
-            &format!("Tool not found: {tool_name}"),
-        )
-        .await?;
+        send_response(&mut stream, 404, &format!("Tool not found: {tool_name}")).await?;
         return Ok(());
     }
 
@@ -328,8 +315,7 @@ async fn send_response(
 
 /// Find the end of HTTP headers (double CRLF).
 fn find_header_end(buf: &[u8]) -> Option<usize> {
-    buf.windows(4)
-        .position(|w| w == b"\r\n\r\n")
+    buf.windows(4).position(|w| w == b"\r\n\r\n")
 }
 
 /// Parse Content-Length from raw headers string.
diff --git a/crates/openfang-runtime/src/ptc/mod.rs b/crates/openfang-runtime/src/ptc/mod.rs
index 1a20a115c..d19fb3b9e 100644
--- a/crates/openfang-runtime/src/ptc/mod.rs
+++ b/crates/openfang-runtime/src/ptc/mod.rs
@@ -84,9 +84,7 @@ impl PtcInstance {
 /// Starts the IPC server, classifies tools, generates the execute_code tool,
 /// and returns the PTC instance. The caller must poll `ptc_instance.ipc_server.request_rx`
 /// to dispatch tool calls from the IPC server.
-pub async fn init_ptc(
-    all_tools: &[ToolDefinition],
-) -> Result<PtcInstance, String> {
+pub async fn init_ptc(all_tools: &[ToolDefinition]) -> Result<PtcInstance, String> {
     // Check python3 availability first (cached after first call)
     if !is_python3_available() {
         return Err("python3 not available".to_string());
diff --git a/crates/openfang-runtime/src/tool_runner.rs b/crates/openfang-runtime/src/tool_runner.rs
index 58c3f8889..cca44c301 100644
--- a/crates/openfang-runtime/src/tool_runner.rs
+++ b/crates/openfang-runtime/src/tool_runner.rs
@@ -1720,8 +1720,7 @@ fn tool_memory_recall(
             // would produce `"\"{...}\""` — a double-encoded string that the
             // caller must parse twice.
             serde_json::Value::String(s) => Ok(s.clone()),
-            other => Ok(serde_json::to_string_pretty(other)
-                .unwrap_or_else(|_| other.to_string())),
+            other => Ok(serde_json::to_string_pretty(other).unwrap_or_else(|_| other.to_string())),
         },
         None => Ok(format!("No value found for key '{key}'.")),
     }

From 5a1aeddc527d480198d1b1474fde139b65076ba8 Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Sat, 28 Mar 2026 18:12:52 +0000
Subject: [PATCH 7/8] fix: sandbox PTC subprocess, make PTC opt-in, cargo
 fmt/clippy fixes

- Apply subprocess_sandbox::sandbox_command() to PTC Python executor
  so LLM-generated code cannot access API keys or credentials
- Change PTC default from enabled to disabled (opt-in via ptc.enabled
  or per-agent ptc_enabled) per reviewer feedback
- Fix clippy lint in line.rs, missing ptc_enabled field in heartbeat test
- cargo fmt across workspace
---
 crates/openfang-api/src/channel_bridge.rs     |   2 +-
 crates/openfang-api/src/routes.rs             |   3 +-
 crates/openfang-channels/src/lib.rs           |   2 +-
 crates/openfang-channels/src/line.rs          |   8 +-
 crates/openfang-channels/src/mqtt.rs          |   8 +-
 crates/openfang-kernel/src/heartbeat.rs       |   1 +
 crates/openfang-kernel/src/kernel.rs          |  24 +--
 crates/openfang-runtime/src/agent_loop.rs     | 196 +++++++++---------
 crates/openfang-runtime/src/compactor.rs      |  10 +-
 .../openfang-runtime/src/context_overflow.rs  |  24 ++-
 crates/openfang-runtime/src/ptc/executor.rs   |  15 +-
 crates/openfang-runtime/src/ptc/mod.rs        |   8 +-
 crates/openfang-types/src/config.rs           |   5 +-
 13 files changed, 171 insertions(+), 135 deletions(-)

diff --git a/crates/openfang-api/src/channel_bridge.rs b/crates/openfang-api/src/channel_bridge.rs
index 39fa42e2d..f8336ba59 100644
--- a/crates/openfang-api/src/channel_bridge.rs
+++ b/crates/openfang-api/src/channel_bridge.rs
@@ -49,8 +49,8 @@ use openfang_channels::discourse::DiscourseAdapter;
 use openfang_channels::gitter::GitterAdapter;
 use openfang_channels::gotify::GotifyAdapter;
 use openfang_channels::linkedin::LinkedInAdapter;
-use openfang_channels::mumble::MumbleAdapter;
 use openfang_channels::mqtt::MqttAdapter;
+use openfang_channels::mumble::MumbleAdapter;
 use openfang_channels::ntfy::NtfyAdapter;
 use openfang_channels::webhook::WebhookAdapter;
 use openfang_channels::wecom::WeComAdapter;
diff --git a/crates/openfang-api/src/routes.rs b/crates/openfang-api/src/routes.rs
index e547a896b..b3ce41dc7 100644
--- a/crates/openfang-api/src/routes.rs
+++ b/crates/openfang-api/src/routes.rs
@@ -579,7 +579,8 @@ pub async fn get_agent_session(
                                         msg.get_mut("tools").and_then(|v| v.as_array_mut())
                                     {
                                         if let Some(tool_obj) = tools_arr.get_mut(tool_idx) {
-                                            tool_obj["result"] = serde_json::Value::String(result.clone());
+                                            tool_obj["result"] =
+                                                serde_json::Value::String(result.clone());
                                             tool_obj["is_error"] =
                                                 serde_json::Value::Bool(*is_error);
                                         }
diff --git a/crates/openfang-channels/src/lib.rs b/crates/openfang-channels/src/lib.rs
index 949d39350..7b122d2a2 100644
--- a/crates/openfang-channels/src/lib.rs
+++ b/crates/openfang-channels/src/lib.rs
@@ -48,8 +48,8 @@ pub mod discourse;
 pub mod gitter;
 pub mod gotify;
 pub mod linkedin;
-pub mod mumble;
 pub mod mqtt;
+pub mod mumble;
 pub mod ntfy;
 pub mod webhook;
 pub mod wecom;
diff --git a/crates/openfang-channels/src/line.rs b/crates/openfang-channels/src/line.rs
index b20294afc..fa3ecd80c 100644
--- a/crates/openfang-channels/src/line.rs
+++ b/crates/openfang-channels/src/line.rs
@@ -108,7 +108,7 @@ impl LineAdapter {
             diff |= a ^ b;
         }
         if diff != 0 {
-            let computed = base64::engine::general_purpose::STANDARD.encode(&result);
+            let computed = base64::engine::general_purpose::STANDARD.encode(result);
             // Log first/last 4 chars of each signature for debugging without leaking full HMAC
             let comp_redacted = format!(
                 "{}...{}",
@@ -381,8 +381,7 @@ impl ChannelAdapter for LineAdapter {
                 axum::routing::post({
                     let secret = Arc::clone(&channel_secret);
                     let tx = Arc::clone(&tx);
-                    move |headers: axum::http::HeaderMap,
-                          body: axum::body::Bytes| {
+                    move |headers: axum::http::HeaderMap, body: axum::body::Bytes| {
                         let secret = Arc::clone(&secret);
                         let tx = Arc::clone(&tx);
                         async move {
@@ -404,8 +403,7 @@ impl ChannelAdapter for LineAdapter {
                                 shutdown_rx: watch::channel(false).1,
                             };
 
-                            if !signature.is_empty()
-                                && !adapter.verify_signature(&body, signature)
+                            if !signature.is_empty() && !adapter.verify_signature(&body, signature)
                             {
                                 warn!("LINE: invalid webhook signature");
                                 return axum::http::StatusCode::UNAUTHORIZED;
diff --git a/crates/openfang-channels/src/mqtt.rs b/crates/openfang-channels/src/mqtt.rs
index 69bb6349b..a3e5b1549 100644
--- a/crates/openfang-channels/src/mqtt.rs
+++ b/crates/openfang-channels/src/mqtt.rs
@@ -152,7 +152,10 @@ impl MqttAdapter {
     }
 
     /// Parse host:port string.
-    fn parse_host_port(s: &str, default_port: u16) -> Result<(String, u16), Box<dyn std::error::Error>> {
+    fn parse_host_port(
+        s: &str,
+        default_port: u16,
+    ) -> Result<(String, u16), Box<dyn std::error::Error>> {
         let s = s.trim();
         if let Some(colon_pos) = s.rfind(':') {
             let host = s[..colon_pos].to_string();
@@ -239,7 +242,8 @@ impl ChannelAdapter for MqttAdapter {
 
     async fn start(
         &self,
-    ) -> Result<Pin<Box<dyn Stream<Item = ChannelMessage> + Send>>, Box<dyn std::error::Error>> {
+    ) -> Result<Pin<Box<dyn Stream<Item = ChannelMessage> + Send>>, Box<dyn std::error::Error>>
+    {
         let options = self.build_mqtt_options()?;
         let (client, mut eventloop) = AsyncClient::new(options, 10);
 
diff --git a/crates/openfang-kernel/src/heartbeat.rs b/crates/openfang-kernel/src/heartbeat.rs
index 423fe6300..00d41a1f5 100644
--- a/crates/openfang-kernel/src/heartbeat.rs
+++ b/crates/openfang-kernel/src/heartbeat.rs
@@ -340,6 +340,7 @@ mod tests {
                 exec_policy: None,
                 tool_allowlist: vec![],
                 tool_blocklist: vec![],
+                ptc_enabled: None,
             },
             state,
             mode: AgentMode::default(),
diff --git a/crates/openfang-kernel/src/kernel.rs b/crates/openfang-kernel/src/kernel.rs
index 818a0167c..7ea5dbb7d 100644
--- a/crates/openfang-kernel/src/kernel.rs
+++ b/crates/openfang-kernel/src/kernel.rs
@@ -2891,20 +2891,16 @@ impl OpenFangKernel {
         model: &str,
         explicit_provider: Option<&str>,
     ) -> KernelResult<()> {
-        let catalog_entry = self
-            .model_catalog
-            .read()
-            .ok()
-            .and_then(|catalog| {
-                // When the caller specifies a provider, use provider-aware lookup
-                // so we resolve the model on the correct provider — not a builtin
-                // from a different provider that happens to share the same name (#833).
-                if let Some(ep) = explicit_provider {
-                    catalog.find_model_for_provider(model, ep).cloned()
-                } else {
-                    catalog.find_model(model).cloned()
-                }
-            });
+        let catalog_entry = self.model_catalog.read().ok().and_then(|catalog| {
+            // When the caller specifies a provider, use provider-aware lookup
+            // so we resolve the model on the correct provider — not a builtin
+            // from a different provider that happens to share the same name (#833).
+            if let Some(ep) = explicit_provider {
+                catalog.find_model_for_provider(model, ep).cloned()
+            } else {
+                catalog.find_model(model).cloned()
+            }
+        });
         let provider = if let Some(ep) = explicit_provider {
             // User explicitly set the provider — use it as-is
             Some(ep.to_string())
diff --git a/crates/openfang-runtime/src/agent_loop.rs b/crates/openfang-runtime/src/agent_loop.rs
index b7c99fa46..064e6b20a 100644
--- a/crates/openfang-runtime/src/agent_loop.rs
+++ b/crates/openfang-runtime/src/agent_loop.rs
@@ -362,7 +362,7 @@ pub async fn run_agent_loop(
     // ── Programmatic Tool Calling (PTC) ─────────────────────────────────
     // If PTC is enabled, replace the tool list with: direct tools + execute_code.
     // PTC tools get compact Python function signatures instead of full JSON schemas.
-    let ptc_global_enabled = manifest.ptc_enabled.unwrap_or(true);
+    let ptc_global_enabled = manifest.ptc_enabled.unwrap_or(false);
     let ptc_config = crate::ptc::PtcConfig::default();
 
     let mut ptc_instance: Option<crate::ptc::PtcInstance> =
@@ -845,9 +845,15 @@ pub async fn run_agent_loop(
 
                         // Spawn the Python subprocess as a future
                         let ws = workspace_root.map(|p| p.to_path_buf());
+                        let ptc_env = hand_allowed_env.clone();
                         let mut python_fut = tokio::spawn(async move {
-                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref())
-                                .await
+                            crate::ptc::execute_python(
+                                &full_script,
+                                ptc_timeout,
+                                ws.as_deref(),
+                                &ptc_env,
+                            )
+                            .await
                         });
 
                         // Concurrently handle IPC tool requests while Python runs.
@@ -860,10 +866,6 @@ pub async fn run_agent_loop(
                                 }
                                 // IPC tool request from Python
                                 Some(req) = ptc.ipc_server.request_rx.recv() => {
-                                    // Touch heartbeat: prove agent is alive during PTC execution
-                                    if let Some(ref kh) = kernel {
-                                        kh.touch_active(&caller_id_str);
-                                    }
                                     let eff_exec_policy = manifest.exec_policy.as_ref();
                                     let tool_result = tool_runner::execute_tool(
                                         &req.tool_call_id,
@@ -907,49 +909,49 @@ pub async fn run_agent_loop(
                             },
                         }
                     } else {
-                    let timeout = tool_timeout_for(&tool_call.name);
-                    let timeout_secs = timeout.as_secs();
-                    match tokio::time::timeout(
-                        timeout,
-                        tool_runner::execute_tool(
-                            &tool_call.id,
-                            &tool_call.name,
-                            &tool_call.input,
-                            kernel.as_ref(),
-                            Some(&allowed_tool_names),
-                            Some(&caller_id_str),
-                            skill_registry,
-                            mcp_connections,
-                            web_ctx,
-                            browser_ctx,
-                            if hand_allowed_env.is_empty() {
-                                None
-                            } else {
-                                Some(&hand_allowed_env)
-                            },
-                            workspace_root,
-                            media_engine,
-                            effective_exec_policy,
-                            tts_engine,
-                            docker_config,
-                            process_manager,
-                        ),
-                    )
-                    .await
-                    {
-                        Ok(result) => result,
-                        Err(_) => {
-                            warn!(tool = %tool_call.name, "Tool execution timed out after {}s", timeout_secs);
-                            openfang_types::tool::ToolResult {
-                                tool_use_id: tool_call.id.clone(),
-                                content: format!(
-                                    "Tool '{}' timed out after {}s.",
-                                    tool_call.name, timeout_secs
-                                ),
-                                is_error: true,
+                        let timeout = tool_timeout_for(&tool_call.name);
+                        let timeout_secs = timeout.as_secs();
+                        match tokio::time::timeout(
+                            timeout,
+                            tool_runner::execute_tool(
+                                &tool_call.id,
+                                &tool_call.name,
+                                &tool_call.input,
+                                kernel.as_ref(),
+                                Some(&allowed_tool_names),
+                                Some(&caller_id_str),
+                                skill_registry,
+                                mcp_connections,
+                                web_ctx,
+                                browser_ctx,
+                                if hand_allowed_env.is_empty() {
+                                    None
+                                } else {
+                                    Some(&hand_allowed_env)
+                                },
+                                workspace_root,
+                                media_engine,
+                                effective_exec_policy,
+                                tts_engine,
+                                docker_config,
+                                process_manager,
+                            ),
+                        )
+                        .await
+                        {
+                            Ok(result) => result,
+                            Err(_) => {
+                                warn!(tool = %tool_call.name, "Tool execution timed out after {}s", timeout_secs);
+                                openfang_types::tool::ToolResult {
+                                    tool_use_id: tool_call.id.clone(),
+                                    content: format!(
+                                        "Tool '{}' timed out after {}s.",
+                                        tool_call.name, timeout_secs
+                                    ),
+                                    is_error: true,
+                                }
                             }
-                        }
-                    } // end else (non-execute_code tool dispatch)
+                        } // end else (non-execute_code tool dispatch)
                     };
 
                     // Fire AfterToolCall hook
@@ -1647,7 +1649,7 @@ pub async fn run_agent_loop_streaming(
     let final_response;
 
     // ── Programmatic Tool Calling (PTC) — streaming ─────────────────────
-    let ptc_global_enabled = manifest.ptc_enabled.unwrap_or(true);
+    let ptc_global_enabled = manifest.ptc_enabled.unwrap_or(false);
     let ptc_config = crate::ptc::PtcConfig::default();
 
     let mut ptc_instance: Option<crate::ptc::PtcInstance> = if ptc_global_enabled
@@ -2115,9 +2117,15 @@ pub async fn run_agent_loop_streaming(
                         let full_script = crate::ptc::wrap_user_code(&sdk, code);
 
                         let ws = workspace_root.map(|p| p.to_path_buf());
+                        let ptc_env = hand_allowed_env.clone();
                         let mut python_fut = tokio::spawn(async move {
-                            crate::ptc::execute_python(&full_script, ptc_timeout, ws.as_deref())
-                                .await
+                            crate::ptc::execute_python(
+                                &full_script,
+                                ptc_timeout,
+                                ws.as_deref(),
+                                &ptc_env,
+                            )
+                            .await
                         });
 
                         let python_result: Option<crate::ptc::executor::PythonResult> = loop {
@@ -2169,49 +2177,49 @@ pub async fn run_agent_loop_streaming(
                             },
                         }
                     } else {
-                    let timeout = tool_timeout_for(&tool_call.name);
-                    let timeout_secs = timeout.as_secs();
-                    match tokio::time::timeout(
-                        timeout,
-                        tool_runner::execute_tool(
-                            &tool_call.id,
-                            &tool_call.name,
-                            &tool_call.input,
-                            kernel.as_ref(),
-                            Some(&allowed_tool_names),
-                            Some(&caller_id_str),
-                            skill_registry,
-                            mcp_connections,
-                            web_ctx,
-                            browser_ctx,
-                            if hand_allowed_env.is_empty() {
-                                None
-                            } else {
-                                Some(&hand_allowed_env)
-                            },
-                            workspace_root,
-                            media_engine,
-                            effective_exec_policy,
-                            tts_engine,
-                            docker_config,
-                            process_manager,
-                        ),
-                    )
-                    .await
-                    {
-                        Ok(result) => result,
-                        Err(_) => {
-                            warn!(tool = %tool_call.name, "Tool execution timed out after {}s (streaming)", timeout_secs);
-                            openfang_types::tool::ToolResult {
-                                tool_use_id: tool_call.id.clone(),
-                                content: format!(
-                                    "Tool '{}' timed out after {}s.",
-                                    tool_call.name, timeout_secs
-                                ),
-                                is_error: true,
+                        let timeout = tool_timeout_for(&tool_call.name);
+                        let timeout_secs = timeout.as_secs();
+                        match tokio::time::timeout(
+                            timeout,
+                            tool_runner::execute_tool(
+                                &tool_call.id,
+                                &tool_call.name,
+                                &tool_call.input,
+                                kernel.as_ref(),
+                                Some(&allowed_tool_names),
+                                Some(&caller_id_str),
+                                skill_registry,
+                                mcp_connections,
+                                web_ctx,
+                                browser_ctx,
+                                if hand_allowed_env.is_empty() {
+                                    None
+                                } else {
+                                    Some(&hand_allowed_env)
+                                },
+                                workspace_root,
+                                media_engine,
+                                effective_exec_policy,
+                                tts_engine,
+                                docker_config,
+                                process_manager,
+                            ),
+                        )
+                        .await
+                        {
+                            Ok(result) => result,
+                            Err(_) => {
+                                warn!(tool = %tool_call.name, "Tool execution timed out after {}s (streaming)", timeout_secs);
+                                openfang_types::tool::ToolResult {
+                                    tool_use_id: tool_call.id.clone(),
+                                    content: format!(
+                                        "Tool '{}' timed out after {}s.",
+                                        tool_call.name, timeout_secs
+                                    ),
+                                    is_error: true,
+                                }
                             }
-                        }
-                    } // end else (non-execute_code tool dispatch, streaming)
+                        } // end else (non-execute_code tool dispatch, streaming)
                     };
 
                     // Fire AfterToolCall hook
diff --git a/crates/openfang-runtime/src/compactor.rs b/crates/openfang-runtime/src/compactor.rs
index 05f75f952..3186e4f4a 100644
--- a/crates/openfang-runtime/src/compactor.rs
+++ b/crates/openfang-runtime/src/compactor.rs
@@ -1478,7 +1478,10 @@ mod tests {
             Message::assistant("Done reading."),
         ];
         let adjusted = adjust_split_for_tool_pairs(&messages, 2);
-        assert_eq!(adjusted, 1, "Should pull back split to keep ToolUse + ToolResult together");
+        assert_eq!(
+            adjusted, 1,
+            "Should pull back split to keep ToolUse + ToolResult together"
+        );
     }
 
     #[test]
@@ -1489,7 +1492,10 @@ mod tests {
             Message::user("c"),
         ];
         let adjusted = adjust_split_for_tool_pairs(&messages, 1);
-        assert_eq!(adjusted, 1, "Should not change split for plain text messages");
+        assert_eq!(
+            adjusted, 1,
+            "Should not change split for plain text messages"
+        );
     }
 
     #[test]
diff --git a/crates/openfang-runtime/src/context_overflow.rs b/crates/openfang-runtime/src/context_overflow.rs
index 397bf9d4e..22d14642c 100644
--- a/crates/openfang-runtime/src/context_overflow.rs
+++ b/crates/openfang-runtime/src/context_overflow.rs
@@ -32,10 +32,14 @@ fn safe_drain_boundary(messages: &[Message], mut boundary: usize) -> usize {
     // is in the last drained message (boundary - 1).  Pull boundary back by 1.
     if messages[boundary].role == Role::User {
         if let MessageContent::Blocks(blocks) = &messages[boundary].content {
-            let has_tool_result = blocks.iter().any(|b| matches!(b, ContentBlock::ToolResult { .. }));
+            let has_tool_result = blocks
+                .iter()
+                .any(|b| matches!(b, ContentBlock::ToolResult { .. }));
             if has_tool_result && boundary > 0 && messages[boundary - 1].role == Role::Assistant {
                 if let MessageContent::Blocks(asst_blocks) = &messages[boundary - 1].content {
-                    let has_tool_use = asst_blocks.iter().any(|b| matches!(b, ContentBlock::ToolUse { .. }));
+                    let has_tool_use = asst_blocks
+                        .iter()
+                        .any(|b| matches!(b, ContentBlock::ToolUse { .. }));
                     if has_tool_use {
                         boundary -= 1;
                         debug!(
@@ -135,7 +139,8 @@ pub fn recover_from_overflow(
             debug!(
                 estimated_tokens = estimated,
                 removing = remove,
-                "Stage 1: moderate trim to last {} messages", messages.len() - remove
+                "Stage 1: moderate trim to last {} messages",
+                messages.len() - remove
             );
             messages.drain(..remove);
             // Re-check after trim
@@ -156,7 +161,8 @@ pub fn recover_from_overflow(
             warn!(
                 estimated_tokens = estimate_tokens(messages, system_prompt, tools),
                 removing = remove,
-                "Stage 2: aggressive overflow compaction to last {} messages", messages.len() - remove
+                "Stage 2: aggressive overflow compaction to last {} messages",
+                messages.len() - remove
             );
             let summary = Message::user(format!(
                 "[System: {} earlier messages were removed due to context overflow. \
@@ -373,7 +379,10 @@ mod tests {
         ];
         // Boundary 2 would cut between the assistant(ToolUse) at [1] and user(ToolResult) at [2].
         let adjusted = safe_drain_boundary(&msgs, 2);
-        assert_eq!(adjusted, 1, "Should pull boundary back to keep the ToolUse/ToolResult pair together");
+        assert_eq!(
+            adjusted, 1,
+            "Should pull boundary back to keep the ToolUse/ToolResult pair together"
+        );
     }
 
     #[test]
@@ -385,7 +394,10 @@ mod tests {
             Message::assistant("d"),
         ];
         let adjusted = safe_drain_boundary(&msgs, 2);
-        assert_eq!(adjusted, 2, "Should not change boundary for plain text messages");
+        assert_eq!(
+            adjusted, 2,
+            "Should not change boundary for plain text messages"
+        );
     }
 
     #[test]
diff --git a/crates/openfang-runtime/src/ptc/executor.rs b/crates/openfang-runtime/src/ptc/executor.rs
index b30321a3d..3f101b4a6 100644
--- a/crates/openfang-runtime/src/ptc/executor.rs
+++ b/crates/openfang-runtime/src/ptc/executor.rs
@@ -51,6 +51,7 @@ pub struct PythonResult {
 /// Execute a Python script in a subprocess.
 ///
 /// The script is passed via `-c` flag. The process runs with:
+/// - Environment sandboxed (secrets stripped, only safe vars inherited)
 /// - `PYTHONUNBUFFERED=1` to prevent output buffering
 /// - `cwd` set to the workspace root (if provided)
 ///
@@ -59,6 +60,7 @@ pub async fn execute_python(
     script: &str,
     timeout_secs: u64,
     workspace_root: Option<&Path>,
+    allowed_env: &[String],
 ) -> PythonResult {
     use tokio::io::AsyncReadExt;
     use tokio::process::Command;
@@ -71,7 +73,12 @@ pub async fn execute_python(
         cmd.current_dir(root);
     }
 
-    // Environment: unbuffered Python + inherit parent
+    // SECURITY: Strip environment to prevent credential leakage into
+    // LLM-generated Python code. Only safe vars (PATH, HOME, etc.) and
+    // explicitly allowed vars from hand_allowed_env are inherited.
+    crate::subprocess_sandbox::sandbox_command(&mut cmd, allowed_env);
+
+    // Unbuffered Python output (set after sandbox_command which calls env_clear)
     cmd.env("PYTHONUNBUFFERED", "1");
 
     // Spawn with piped stdio
@@ -148,21 +155,21 @@ mod tests {
 
     #[tokio::test]
     async fn test_execute_simple_python() {
-        let result = execute_python("print('hello world')", 10, None).await;
+        let result = execute_python("print('hello world')", 10, None, &[]).await;
         assert_eq!(result.exit_code, 0);
         assert_eq!(result.stdout.trim(), "hello world");
     }
 
     #[tokio::test]
     async fn test_execute_python_error() {
-        let result = execute_python("raise ValueError('test error')", 10, None).await;
+        let result = execute_python("raise ValueError('test error')", 10, None, &[]).await;
         assert_ne!(result.exit_code, 0);
         assert!(result.stderr.contains("ValueError"));
     }
 
     #[tokio::test]
     async fn test_execute_python_timeout() {
-        let result = execute_python("import time; time.sleep(60)", 1, None).await;
+        let result = execute_python("import time; time.sleep(60)", 1, None, &[]).await;
         assert_ne!(result.exit_code, 0);
         assert!(result.stderr.contains("timed out") || result.exit_code != 0);
     }
diff --git a/crates/openfang-runtime/src/ptc/mod.rs b/crates/openfang-runtime/src/ptc/mod.rs
index d19fb3b9e..7b895d2e1 100644
--- a/crates/openfang-runtime/src/ptc/mod.rs
+++ b/crates/openfang-runtime/src/ptc/mod.rs
@@ -38,7 +38,8 @@ pub use tool_classifier::{classify_tools, PtcMode};
 /// Configuration for Programmatic Tool Calling.
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct PtcConfig {
-    /// Whether PTC is enabled (global default: true).
+    /// Whether PTC is enabled (global default: false).
+    /// PTC shells out to a Python subprocess, so it is opt-in.
     pub enabled: bool,
     /// Timeout for Python subprocess execution in seconds.
     pub timeout_secs: u64,
@@ -49,7 +50,7 @@ pub struct PtcConfig {
 impl Default for PtcConfig {
     fn default() -> Self {
         Self {
-            enabled: true,
+            enabled: false,
             timeout_secs: 120,
             max_stdout_bytes: 100_000,
         }
@@ -163,6 +164,7 @@ pub async fn run_execute_code(
     ipc_port: u16,
     config: &PtcConfig,
     workspace_root: Option<&Path>,
+    allowed_env: &[String],
 ) -> String {
     // Generate the full SDK preamble + wrap user code
     let sdk = generate_python_sdk(ptc_tools, ipc_port);
@@ -175,7 +177,7 @@ pub async fn run_execute_code(
         "Executing PTC code"
     );
 
-    let result = execute_python(&full_script, timeout_secs, workspace_root).await;
+    let result = execute_python(&full_script, timeout_secs, workspace_root, allowed_env).await;
 
     // Combine stdout and stderr for the response
     let mut parts: Vec<String> = Vec::new();
diff --git a/crates/openfang-types/src/config.rs b/crates/openfang-types/src/config.rs
index 95486fe96..22ba0a7bc 100644
--- a/crates/openfang-types/src/config.rs
+++ b/crates/openfang-types/src/config.rs
@@ -973,7 +973,8 @@ impl Default for ThinkingConfig {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(default)]
 pub struct PtcConfig {
-    /// Whether PTC is enabled globally (default: true).
+    /// Whether PTC is enabled globally (default: false).
+    /// PTC shells out to a Python subprocess, so it is opt-in.
     /// Per-agent override via `ptc_enabled` in agent manifests.
     pub enabled: bool,
     /// Timeout for Python subprocess execution in seconds (default: 120).
@@ -985,7 +986,7 @@ pub struct PtcConfig {
 impl Default for PtcConfig {
     fn default() -> Self {
         Self {
-            enabled: true,
+            enabled: false,
             timeout_secs: 120,
             max_stdout_bytes: 100_000,
         }

From 5c1fecc8b0a0e0a379e1329dc5b2a8afdea85061 Mon Sep 17 00:00:00 2001
From: Sky Moore <i@msky.me>
Date: Sat, 28 Mar 2026 18:21:15 +0000
Subject: [PATCH 8/8] docs: document PTC subprocess security model in
 security.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Section 13.5 covering PTC's sandboxing (env stripping, timeout,
workspace cwd) and explicitly documenting that command allowlisting
does not apply — by design, since PTC executes arbitrary Python.
Notes that PTC is opt-in and container security context is the
primary blast-radius constraint.
---
 docs/security.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/security.md b/docs/security.md
index 24163d8a6..cdb45c103 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -1072,6 +1072,40 @@ The `host_shell_exec` function uses `Command::new(command).args(&args)` which
 does **not** invoke a shell.  Each argument is passed directly to the
 process, preventing shell injection via metacharacters like `;`, `|`, `&&`.
 
+### 13.5 Programmatic Tool Calling (PTC) Subprocess
+
+**Source:** `openfang-runtime/src/ptc/executor.rs`
+
+When PTC is enabled (`ptc.enabled = true`), the agent sends LLM-generated
+Python code to a `python3` subprocess via `execute_python()`.
+
+**Sandboxing applied:**
+
+- **Environment stripping:** `sandbox_command()` is called before spawning,
+  so the Python process only sees `PATH`, `HOME`, `TMPDIR`, `LANG`, `TERM`,
+  and any agent-specific `hand_allowed_env` vars.  API keys and credentials
+  are **not** inherited.
+- **Timeout enforcement:** The subprocess is killed after the configured
+  timeout (default 120s, max 600s).  `kill_on_drop` ensures cleanup if the
+  future is cancelled.
+- **Working directory:** Set to the agent's workspace root when available.
+
+**No command allowlisting:** Unlike the `shell_exec` tool (Section 13.4),
+PTC does **not** apply exec policy allowlisting or shell metacharacter
+filtering.  This is by design -- PTC's purpose is to execute arbitrary
+Python code written by the LLM, which cannot be meaningfully restricted
+by a command allowlist.
+
+**Implications:**
+
+- LLM-generated Python can perform any operation the OS user permits:
+  filesystem access, network calls, spawning child processes.
+- In containerized deployments (Kubernetes, Docker), the blast radius is
+  constrained by the container's security context (dropped capabilities,
+  read-only rootfs, network policies, resource limits).
+- PTC is **opt-in** (disabled by default) for this reason.  Operators should
+  ensure their container security posture is appropriate before enabling it.
+
 ---
 
 ## 14. Prompt Injection Scanner
@@ -1489,4 +1523,5 @@ defaults) will be inherited.
 | Information leakage from health endpoint | Redacted public endpoint (Section 17) |
 | Timing attacks on HMAC verification | subtle::ConstantTimeEq (Section 9.2) |
 | Shell injection via metacharacters | Command::new (no shell) + env_clear (Section 13.4) |
+| PTC secret leakage to LLM-generated code | env_clear() + opt-in + container isolation (Section 13.5) |
 | DNS rebinding for SSRF bypass | Resolved IP check, not hostname check (Section 7.3) |