feat(cancel): add cancellation support via AtomicBool token

Adds cooperative cancellation to the interpreter. A shared
Arc<AtomicBool> token can be set from any thread to abort execution
at the next command boundary with Error::Cancelled.

Rust API: Bash::cancellation_token() returns the shared token.
JS API: Bash.cancel() / BashTool.cancel() + AbortSignal support.
Python API: Bash.cancel() / BashTool.cancel().

Closes #541

Author: chaliy

crates/bashkit-js/src/lib.rs

@@ -10,6 +10,7 @@ use bashkit::tool::VERSION;
 use bashkit::{Bash as RustBash, BashTool as RustBashTool, ExecutionLimits, Tool};
 use napi_derive::napi;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 use tokio::sync::Mutex;
 
 // ============================================================================
@@ -51,6 +52,7 @@ pub struct BashOptions {
 pub struct Bash {
     inner: Arc<Mutex<RustBash>>,
     rt: tokio::runtime::Runtime,
+    cancelled: Arc<AtomicBool>,
     username: Option<String>,
     hostname: Option<String>,
     max_commands: Option<u32>,
@@ -74,6 +76,7 @@ impl Bash {
             opts.max_commands,
             opts.max_loop_iterations,
         );
+        let cancelled = bash.cancellation_token();
 
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
@@ -83,6 +86,7 @@ impl Bash {
         Ok(Self {
             inner: Arc::new(Mutex::new(bash)),
             rt,
+            cancelled,
             username: opts.username,
             hostname: opts.hostname,
             max_commands: opts.max_commands,
@@ -93,6 +97,7 @@ impl Bash {
     /// Execute bash commands synchronously.
     #[napi]
     pub fn execute_sync(&self, commands: String) -> napi::Result<ExecResult> {
+        self.cancelled.store(false, Ordering::Relaxed);
         let inner = self.inner.clone();
         self.rt.block_on(async move {
             let mut bash = inner.lock().await;
@@ -113,6 +118,15 @@ impl Bash {
         })
     }
 
+    /// Cancel the currently running execution.
+    ///
+    /// Safe to call from any thread. Execution will abort at the next
+    /// command boundary.
+    #[napi]
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::Relaxed);
+    }
+
     /// Reset interpreter to fresh state, preserving configuration.
     #[napi]
     pub fn reset(&self) -> napi::Result<()> {
@@ -124,12 +138,13 @@ impl Bash {
 
         self.rt.block_on(async move {
             let mut bash = inner.lock().await;
-            *bash = build_bash(
+            let new_bash = build_bash(
                 username.as_deref(),
                 hostname.as_deref(),
                 max_commands,
                 max_loop_iterations,
             );
+            *bash = new_bash;
             Ok(())
         })
     }
@@ -147,6 +162,7 @@ impl Bash {
 pub struct BashTool {
     inner: Arc<Mutex<RustBash>>,
     rt: tokio::runtime::Runtime,
+    cancelled: Arc<AtomicBool>,
     username: Option<String>,
     hostname: Option<String>,
     max_commands: Option<u32>,
@@ -193,6 +209,7 @@ impl BashTool {
             opts.max_commands,
             opts.max_loop_iterations,
         );
+        let cancelled = bash.cancellation_token();
 
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
@@ -202,6 +219,7 @@ impl BashTool {
         Ok(Self {
             inner: Arc::new(Mutex::new(bash)),
             rt,
+            cancelled,
             username: opts.username,
             hostname: opts.hostname,
             max_commands: opts.max_commands,
@@ -212,6 +230,7 @@ impl BashTool {
     /// Execute bash commands synchronously.
     #[napi]
     pub fn execute_sync(&self, commands: String) -> napi::Result<ExecResult> {
+        self.cancelled.store(false, Ordering::Relaxed);
         let inner = self.inner.clone();
         self.rt.block_on(async move {
             let mut bash = inner.lock().await;
@@ -232,6 +251,12 @@ impl BashTool {
         })
     }
 
+    /// Cancel the currently running execution.
+    #[napi]
+    pub fn cancel(&self) {
+        self.cancelled.store(true, Ordering::Relaxed);
+    }
+
     /// Reset interpreter to fresh state, preserving configuration.
     #[napi]
     pub fn reset(&self) -> napi::Result<()> {
@@ -243,12 +268,13 @@ impl BashTool {
 
         self.rt.block_on(async move {
             let mut bash = inner.lock().await;
-            *bash = build_bash(
+            let new_bash = build_bash(
                 username.as_deref(),
                 hostname.as_deref(),
                 max_commands,
                 max_loop_iterations,
             );
+            *bash = new_bash;
             Ok(())
         })
     }

crates/bashkit-js/wrapper.ts

@@ -58,22 +58,45 @@ export class Bash {
 
   /**
    * Execute bash commands synchronously and return the result.
+   *
+   * If `signal` is provided, the execution will be cancelled when the signal
+   * is aborted. The result will have `error: "execution cancelled"`.
    */
-  executeSync(commands: string): ExecResult {
+  executeSync(commands: string, options?: { signal?: AbortSignal }): ExecResult {
+    if (options?.signal) {
+      const signal = options.signal;
+      if (signal.aborted) {
+        return { stdout: "", stderr: "", exitCode: 1, error: "execution cancelled" };
+      }
+      const onAbort = () => this.native.cancel();
+      signal.addEventListener("abort", onAbort, { once: true });
+      try {
+        return this.native.executeSync(commands);
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
     return this.native.executeSync(commands);
   }
 
   /**
    * Execute bash commands synchronously. Throws `BashError` on non-zero exit.
    */
-  executeSyncOrThrow(commands: string): ExecResult {
-    const result = this.native.executeSync(commands);
+  executeSyncOrThrow(commands: string, options?: { signal?: AbortSignal }): ExecResult {
+    const result = this.executeSync(commands, options);
     if (result.exitCode !== 0) {
       throw new BashError(result);
     }
     return result;
   }
 
+  /**
+   * Cancel the currently running execution.
+   */
+  cancel(): void {
+    this.native.cancel();
+  }
+
   /**
    * Reset interpreter to fresh state, preserving configuration.
    */
@@ -110,21 +133,41 @@ export class BashTool {
   /**
    * Execute bash commands synchronously and return the result.
    */
-  executeSync(commands: string): ExecResult {
+  executeSync(commands: string, options?: { signal?: AbortSignal }): ExecResult {
+    if (options?.signal) {
+      const signal = options.signal;
+      if (signal.aborted) {
+        return { stdout: "", stderr: "", exitCode: 1, error: "execution cancelled" };
+      }
+      const onAbort = () => this.native.cancel();
+      signal.addEventListener("abort", onAbort, { once: true });
+      try {
+        return this.native.executeSync(commands);
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
     return this.native.executeSync(commands);
   }
 
   /**
    * Execute bash commands synchronously. Throws `BashError` on non-zero exit.
    */
-  executeSyncOrThrow(commands: string): ExecResult {
-    const result = this.native.executeSync(commands);
+  executeSyncOrThrow(commands: string, options?: { signal?: AbortSignal }): ExecResult {
+    const result = this.executeSync(commands, options);
     if (result.exitCode !== 0) {
       throw new BashError(result);
     }
     return result;
   }
 
+  /**
+   * Cancel the currently running execution.
+   */
+  cancel(): void {
+    this.native.cancel();
+  }
+
   /**
    * Reset interpreter to fresh state, preserving configuration.
    */

crates/bashkit-python/src/lib.rs

@@ -15,6 +15,7 @@ use pyo3::prelude::*;
 use pyo3::types::{PyDict, PyList};
 use pyo3_async_runtimes::tokio::future_into_py;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 use tokio::sync::Mutex;
 
 // ============================================================================
@@ -193,6 +194,7 @@ pub struct PyBash {
     /// Shared tokio runtime — reused across all sync calls to avoid
     /// per-call OS thread/fd exhaustion (issue #414).
     rt: tokio::runtime::Runtime,
+    cancelled: Arc<AtomicBool>,
     username: Option<String>,
     hostname: Option<String>,
     max_commands: Option<u64>,
@@ -228,6 +230,7 @@ impl PyBash {
         builder = builder.limits(limits);
 
         let bash = builder.build();
+        let cancelled = bash.cancellation_token();
 
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
@@ -237,13 +240,22 @@ impl PyBash {
         Ok(Self {
             inner: Arc::new(Mutex::new(bash)),
             rt,
+            cancelled,
             username,
             hostname,
             max_commands,
             max_loop_iterations,
         })
     }
 
+    /// Cancel the currently running execution.
+    ///
+    /// Safe to call from any thread. Execution will abort at the next
+    /// command boundary.
+    fn cancel(&self) {
+        self.cancelled.store(true, Ordering::Relaxed);
+    }
+
     /// Execute commands asynchronously.
     fn execute<'py>(&self, py: Python<'py>, commands: String) -> PyResult<Bound<'py, PyAny>> {
         let inner = self.inner.clone();
@@ -371,6 +383,7 @@ pub struct BashTool {
     /// Shared tokio runtime — reused across all sync calls to avoid
     /// per-call OS thread/fd exhaustion (issue #414).
     rt: tokio::runtime::Runtime,
+    cancelled: Arc<AtomicBool>,
     username: Option<String>,
     hostname: Option<String>,
     max_commands: Option<u64>,
@@ -429,6 +442,7 @@ impl BashTool {
         builder = builder.limits(limits);
 
         let bash = builder.build();
+        let cancelled = bash.cancellation_token();
 
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
@@ -438,13 +452,19 @@ impl BashTool {
         Ok(Self {
             inner: Arc::new(Mutex::new(bash)),
             rt,
+            cancelled,
             username,
             hostname,
             max_commands,
             max_loop_iterations,
         })
     }
 
+    /// Cancel the currently running execution.
+    fn cancel(&self) {
+        self.cancelled.store(true, Ordering::Relaxed);
+    }
+
     fn execute<'py>(&self, py: Python<'py>, commands: String) -> PyResult<Bound<'py, PyAny>> {
         let inner = self.inner.clone();
         future_into_py(py, async move {

crates/bashkit/src/error.rs

@@ -53,6 +53,10 @@ pub enum Error {
     #[error("regex error: {0}")]
     Regex(#[from] regex::Error),
 
+    /// Execution was cancelled via the cancellation token.
+    #[error("execution cancelled")]
+    Cancelled,
+
     /// Internal error for unexpected failures.
     ///
     /// THREAT[TM-INT-002]: Unexpected internal failures should not crash the interpreter.

crates/bashkit/src/interpreter/mod.rs

@@ -22,7 +22,7 @@ use std::collections::{HashMap, HashSet};
 use std::panic::AssertUnwindSafe;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
-use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 
 /// Monotonic counter for unique process substitution file paths
 static PROC_SUB_COUNTER: AtomicU64 = AtomicU64::new(0);
@@ -304,6 +304,9 @@ pub struct Interpreter {
     /// Aliases currently being expanded (prevents infinite recursion).
     /// When alias `foo` expands to `foo bar`, the inner `foo` is not re-expanded.
     expanding_aliases: HashSet<String>,
+    /// Cancellation token: when set to `true`, execution aborts at the next
+    /// command boundary with `Error::Cancelled`.
+    cancelled: Arc<AtomicBool>,
 }
 
 impl Interpreter {
@@ -560,6 +563,22 @@ impl Interpreter {
             pipestatus: Vec::new(),
             aliases: HashMap::new(),
             expanding_aliases: HashSet::new(),
+            cancelled: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    /// Return a shared cancellation token. Set it to `true` from any thread
+    /// to abort execution at the next command boundary.
+    pub fn cancellation_token(&self) -> Arc<AtomicBool> {
+        Arc::clone(&self.cancelled)
+    }
+
+    /// Check if cancellation has been requested.
+    fn check_cancelled(&self) -> Result<()> {
+        if self.cancelled.load(Ordering::Relaxed) {
+            Err(crate::error::Error::Cancelled)
+        } else {
+            Ok(())
         }
     }
 
@@ -716,6 +735,7 @@ impl Interpreter {
         let mut exit_code = 0;
 
         for command in &script.commands {
+            self.check_cancelled()?;
             let emit_before = self.output_emit_count;
             let result = self.execute_command(command).await?;
             self.maybe_emit_output(&result.stdout, &result.stderr, emit_before);
@@ -805,6 +825,7 @@ impl Interpreter {
         command: &'a Command,
     ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<ExecResult>> + Send + 'a>> {
         Box::pin(async move {
+            self.check_cancelled()?;
             // Update current line for $LINENO
             self.current_line = Self::command_line(command);
 

crates/bashkit/src/lib.rs

@@ -679,6 +679,17 @@ impl Bash {
         result
     }
 
+    /// Return a shared cancellation token.
+    ///
+    /// Set the token to `true` from any thread to abort execution at the next
+    /// command boundary with [`Error::Cancelled`].
+    ///
+    /// The caller is responsible for resetting the flag to `false` before
+    /// calling `exec()` again.
+    pub fn cancellation_token(&self) -> Arc<std::sync::atomic::AtomicBool> {
+        self.interpreter.cancellation_token()
+    }
+
     /// Get a clone of the underlying filesystem.
     ///
     /// Provides direct access to the virtual filesystem for: