fix(python): async custom_builtins work inside Jupyter / running event loop

.github/workflows/python.yml

@@ -11,6 +11,7 @@ on:
       - "crates/bashkit-python/**"
       - "crates/bashkit/**"
       - "examples/*.py"
+      - "examples/*.ipynb"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/python.yml"
@@ -20,6 +21,7 @@ on:
       - "crates/bashkit-python/**"
       - "crates/bashkit/**"
       - "examples/*.py"
+      - "examples/*.ipynb"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/python.yml"
@@ -120,7 +122,7 @@ jobs:
       - name: Install local wheel
         run: |
           pip install bashkit --no-index --find-links crates/bashkit-python/dist --force-reinstall
-          pip install langchain-core langgraph fastapi httpx uvicorn
+          pip install langchain-core langgraph fastapi httpx uvicorn nbconvert jupyter-client ipykernel
 
       - name: Run examples
         run: |
@@ -131,6 +133,11 @@ jobs:
           python crates/bashkit-python/examples/langgraph_async_tool.py
           python crates/bashkit-python/examples/fastapi_async_tool.py
 
+      - name: Run notebooks
+        run: |
+          jupyter nbconvert --to notebook --execute --ExecutePreprocessor.timeout=120 \
+            examples/jupyter_basics.ipynb --output /tmp/jupyter_basics_out.ipynb
+
   # Verify wheel builds and passes twine check
   build-wheel:
     name: Build wheel

crates/bashkit-python/bashkit/_bashkit.pyi

@@ -424,6 +424,10 @@ class Bash:
         Not supported when ``external_handler`` is configured — use
         ``execute()`` (async) instead. ``on_output`` must be synchronous.
         Async ``custom_builtins`` callbacks run on a private loop here.
+        When called from inside a running event loop (e.g. Jupyter / IPython),
+        callbacks are dispatched to a background thread with their own loop so
+        that asyncio's "cannot run while another loop is running" restriction
+        is not triggered.
 
         Example::
 
@@ -778,6 +782,10 @@ class BashTool:
         """Execute bash commands synchronously (blocking).
 
         Async ``custom_builtins`` callbacks run on a private loop here.
+        When called from inside a running event loop (e.g. Jupyter / IPython),
+        callbacks are dispatched to a background thread with their own loop so
+        that asyncio's "cannot run while another loop is running" restriction
+        is not triggered.
 
         ``on_output`` must be synchronous.