tools / execute.py

Sandboxed code execution with multiple validation guards and stateful Jupyter support.

Tool: execute

Three execution modes selected from arguments:

1. Bash command (line 32-117)

• Auto-strips invalid cd /sandbox / cd /home/user prefixes.
• Blocks substantive inline -c scripts (≥120 chars, 2+ statements, has import) and forces the file+execute pattern.
• Acquired-skill invocation nudge (2026-04-24). When the blocked body looks like a failed attempt to call an acquired skill — from X import X where module and symbol names match, or acquired_skills/X.py in a subprocess call — the SYSTEM BLOCK error appends a targeted HINT: pointing at the canonical invocation: "Acquired skills are TOP-LEVEL TOOLS. Invoke it directly as X(...)." This shortcut exists because after the skill-storage relocation (skills live under $GHOST_HOME/system/memory/acquired_skills/, not inside the sandbox), the LLM can no longer see the skill via ls and its first instinct is often to wrap the call in python -c / subprocess. Hint fires only on the narrow patterns above — unrelated inline bodies keep the generic message. Covered by tests/test_acquired_skill_invocation_nudge.py.
• Executes via sandbox_manager.execute(bash -c ...) with 300 s timeout.

2. File execution (line 119-494)

• Validates extension: only .py, .sh, .js.
• Syntax check via sanitize_code().
• Forbidden module guard: rejects imports of native tool modules (knowledge_base, execute, postgres_admin, …).
• HTML guard: HTML/CSS detected in a .py file → redirect user to file_system.
• "Stubbornness" guard: skip rewriting an unchanged file.

3. Stateful Jupyter (line 198-306)

• Boots persistent ipykernel_launcher if not running.
• Wraps via jupyter_client.BlockingKernelClient.
• Calls kc.wait_for_ready(timeout=10) BEFORE kc.execute() — without this, is_alive() false-negatives for ~1 s after start_channels() while the heartbeat channel hasn't exchanged yet. The runner's except queue.Empty branch reads is_alive() as a "kernel died?" probe, so every FIRST stateful execute of a session used to emit [SYSTEM ERROR: Kernel Terminated Abruptly (Did the script call os._exit()?)] even though the script hadn't run. wait_for_ready closes the race; a genuine launch failure surfaces as a distinct [SYSTEM ERROR: Kernel did not become ready within 10s] message so reflection can distinguish launch failure from runtime crash. Covered by tests/test_execute_jupyter_wait_for_ready.py.
• Streams stdout / stderr; detects 5-min timeout or mid-execution kernel death.

Output handling

Truncates output at 512 KB (head 100 KB + tail 400 KB). Extracts error line numbers and produces snippet context for tracebacks. Diagnostic mode shows the surrounding lines around an error.

Return shape

--- EXECUTION RESULT ---
EXIT CODE: {code}
STDOUT/STDERR:
{output}

Safety guards summary

• Forbidden imports — regex rejection in Python source.
• HTML/CSS guard — detects and rejects.
• SQL injection — out of scope (database tool uses parameterised queries).
• Inline script block — rejects substantive -c usage.
• Output truncation — head + tail capping.