mycode-sdk 0.9.5__tar.gz → 0.11.0__tar.gz

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycode-sdk
-Version: 0.9.5
+Version: 0.11.0
 Summary: Lightweight Python SDK for building AI agents.
 Project-URL: Homepage, https://github.com/legibet/mycode
 Project-URL: Repository, https://github.com/legibet/mycode
@@ -71,7 +71,7 @@ print(result.text)
 
 ## Multi-turn conversations
 
-Call `achat()` or `run()` again on the same `Agent` — history accumulates automatically:
+Call `achat()` or `run()` again on the same `Agent` to continue the conversation:
 
 ```python
 agent = Agent(model="claude-sonnet-4-6", api_key="...")
@@ -117,7 +117,7 @@ agent = Agent(
 )
 ```
 
-Construct another `Agent` with the same `(session_dir, session_id)` later to resume the conversation — the history is loaded automatically.
+Construct another `Agent` with the same `(session_dir, session_id)` to load the conversation history.
 
 ## Built-in tools
 
@@ -167,6 +167,8 @@ def summarize_file(ctx: ToolContext, path: str) -> str:
     return result.output.splitlines()[0] if result.output else ""
 ```
 
+Async tools use `await ctx.aread()`, `await ctx.awrite()`, `await ctx.aedit()`, and `await ctx.abash()`. Use `await ctx.acall(name, args)` to call another registered tool by name.
+
 ## Tool hooks
 
 Inspect or replace tool calls before they run. Return `None` from `before_tool` to let the tool execute, or a `ToolExecutionResult` to skip it:

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/README.md

@@ -44,7 +44,7 @@ print(result.text)
 
 ## Multi-turn conversations
 
-Call `achat()` or `run()` again on the same `Agent` — history accumulates automatically:
+Call `achat()` or `run()` again on the same `Agent` to continue the conversation:
 
 ```python
 agent = Agent(model="claude-sonnet-4-6", api_key="...")
@@ -90,7 +90,7 @@ agent = Agent(
 )
 ```
 
-Construct another `Agent` with the same `(session_dir, session_id)` later to resume the conversation — the history is loaded automatically.
+Construct another `Agent` with the same `(session_dir, session_id)` to load the conversation history.
 
 ## Built-in tools
 
@@ -140,6 +140,8 @@ def summarize_file(ctx: ToolContext, path: str) -> str:
     return result.output.splitlines()[0] if result.output else ""
 ```
 
+Async tools use `await ctx.aread()`, `await ctx.awrite()`, `await ctx.aedit()`, and `await ctx.abash()`. Use `await ctx.acall(name, args)` to call another registered tool by name.
+
 ## Tool hooks
 
 Inspect or replace tool calls before they run. Return `None` from `before_tool` to let the tool execute, or a `ToolExecutionResult` to skip it:

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mycode-sdk"
-version = "0.9.5"
+version = "0.11.0"
 description = "Lightweight Python SDK for building AI agents."
 readme = "README.md"
 requires-python = ">=3.12"

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/__init__.py

@@ -4,6 +4,7 @@ from importlib import metadata
 
 from mycode.agent import Agent, Event, PersistCallback, RunResult
 from mycode.attachments import Attachment
+from mycode.compact import NothingToCompactError
 from mycode.hooks import AfterToolHook, BeforeToolHook, HookResult, Hooks, ToolHookContext
 from mycode.messages import (
     ContentBlock,
@@ -45,6 +46,7 @@ __all__ = [
     "BeforeToolHook",
     "HookResult",
     "Hooks",
+    "NothingToCompactError",
     "PersistCallback",
     "RunResult",
     "SessionStore",

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/agent.py

@@ -23,7 +23,9 @@ from mycode.attachments import AttachmentLike, build_attachment_blocks
 from mycode.compact import (
     COMPACT_SUMMARY_PROMPT,
     DEFAULT_COMPACT_THRESHOLD,
+    NothingToCompactError,
     build_compact_event,
+    has_compactable_history,
     should_compact,
 )
 from mycode.hooks import Hooks, ToolHookContext
@@ -129,7 +131,9 @@ class Agent:
         self.system = system
         self.hooks = hooks or Hooks()
         self._cancel_event = asyncio.Event()
+        self._event_loop: asyncio.AbstractEventLoop | None = None
         self._provider_event_task: asyncio.Future[ProviderStreamEvent] | None = None
+        self._active_tool_task: asyncio.Task[ToolExecutionResult] | None = None
 
         # History resolution:
         # - messages is None → auto-resume from disk if the session exists
@@ -199,10 +203,24 @@ class Agent:
     def cancel(self) -> None:
         """Request cancellation of the in-flight turn."""
 
+        try:
+            running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            running_loop = None
+
+        loop = self._event_loop
+        if loop is not None and loop.is_running() and running_loop is not loop:
+            loop.call_soon_threadsafe(self._cancel_in_loop)
+            return
+        self._cancel_in_loop()
+
+    def _cancel_in_loop(self) -> None:
         self._cancel_event.set()
         self.tools.cancel_active()
         if self._provider_event_task and not self._provider_event_task.done():
             self._provider_event_task.cancel()
+        if self._active_tool_task and not self._active_tool_task.done():
+            self._active_tool_task.cancel()
 
     def clear(self) -> None:
         """Drop the in-memory conversation history."""
@@ -213,6 +231,23 @@ class Agent:
     # Tool execution
     # ------------------------------------------------------------------
 
+    async def _execute_tool(
+        self,
+        spec: ToolSpec,
+        args: dict[str, Any],
+        ctx: ToolContext,
+    ) -> ToolExecutionResult:
+        if not spec.is_async:
+            return await self.tools.aexecute(spec.name, args, ctx)
+
+        task = asyncio.create_task(self.tools.aexecute(spec.name, args, ctx))
+        self._active_tool_task = task
+        try:
+            return await task
+        finally:
+            if self._active_tool_task is task:
+                self._active_tool_task = None
+
     async def _run_tool_call(self, tool_use: dict[str, Any]) -> AsyncIterator[Event]:
         """Run one tool call and emit the standard tool events."""
 
@@ -259,13 +294,23 @@ class Agent:
             return
 
         if spec.streams_output:
-            async for event in self._run_streaming_tool(tool_id=tool_id, name=name, args=args, hook_ctx=hook_ctx):
+            async for event in self._run_streaming_tool(
+                tool_id=tool_id,
+                spec=spec,
+                args=args,
+                hook_ctx=hook_ctx,
+            ):
                 yield event
             return
 
         try:
             ctx = self._ctx_for_call(tool_id)
-            result = await asyncio.to_thread(self.tools.execute, name, args, ctx)
+            result = await self._execute_tool(spec, args, ctx)
+        except asyncio.CancelledError:
+            if self._cancel_event.is_set():
+                yield self._error_done(tool_id, "error: cancelled")
+                return
+            raise
         except Exception as exc:  # pragma: no cover - defensive
             result = ToolExecutionResult(output=f"error: {exc}", is_error=True)
 
@@ -275,7 +320,7 @@ class Agent:
         self,
         *,
         tool_id: str,
-        name: str,
+        spec: ToolSpec,
         args: dict[str, Any],
         hook_ctx: ToolHookContext,
     ) -> AsyncIterator[Event]:
@@ -289,13 +334,13 @@ class Agent:
 
         ctx = self._ctx_for_call(tool_id, emit=on_output)
 
-        async def run_in_thread() -> ToolExecutionResult:
+        async def run_tool() -> ToolExecutionResult:
             try:
-                return await asyncio.to_thread(self.tools.execute, name, args, ctx)
+                return await self._execute_tool(spec, args, ctx)
             finally:
                 loop.call_soon_threadsafe(output_queue.put_nowait, None)
 
-        task = asyncio.create_task(run_in_thread())
+        task = asyncio.create_task(run_tool())
         was_cancelled = False
         output_parts: list[str] = []
 
@@ -317,8 +362,8 @@ class Agent:
                 output_parts.append(output)
                 yield Event("tool_output", {"tool_use_id": tool_id, "output": output})
 
-        if was_cancelled:
-            with suppress(Exception):
+        if was_cancelled or (self._cancel_event.is_set() and task.cancelled()):
+            with suppress(asyncio.CancelledError, Exception):
                 await task
             output = "\n".join([*output_parts, "error: cancelled"]) if output_parts else "error: cancelled"
             yield self._error_done(tool_id, output)
@@ -455,6 +500,23 @@ class Agent:
             block["meta"] = {**meta, "duration_ms": duration_ms}
             return
 
+    async def _persist_message(
+        self,
+        message: ConversationMessage,
+        on_persist: PersistCallback | None,
+    ) -> None:
+        """Persist one message: caller callback first, then the SDK session store."""
+
+        if on_persist is not None:
+            # Callers may need to write related records before the SDK
+            # appends this message to its own session log.
+            await on_persist(message)
+        if self._store is None:
+            return
+        if not self._store.session_exists(self.session_id):
+            await self._store.create_session(self.session_id, cwd=self.cwd)
+        await self._store.append_message(self.session_id, message)
+
     # ------------------------------------------------------------------
     # Public entry points
     # ------------------------------------------------------------------
@@ -469,16 +531,9 @@ class Agent:
         """Run the full agent loop for one user message."""
 
         async def persist(message: ConversationMessage) -> None:
-            if on_persist is not None:
-                # Callers may need to write related records before the SDK
-                # appends this message to its own session log.
-                await on_persist(message)
-            if self._store is None:
-                return
-            if not self._store.session_exists(self.session_id):
-                await self._store.create_session(self.session_id, cwd=self.cwd)
-            await self._store.append_message(self.session_id, message)
+            await self._persist_message(message, on_persist)
 
+        self._event_loop = asyncio.get_running_loop()
         self._cancel_event.clear()
 
         user_message: ConversationMessage
@@ -671,7 +726,7 @@ class Agent:
                 return
             if should_compact(total_tokens, self.context_window, self.compact_threshold):
                 try:
-                    await self._compact(adapter, persist)
+                    await self._compact(adapter, on_persist)
                     yield Event("compact", {})
                 except asyncio.CancelledError:
                     yield Event("error", {"message": "cancelled"})
@@ -719,12 +774,48 @@ class Agent:
     # Context compaction
     # ------------------------------------------------------------------
 
+    async def acompact(
+        self,
+        *,
+        on_persist: PersistCallback | None = None,
+    ) -> ConversationMessage:
+        """Compact the conversation now and return the persisted compact marker.
+
+        Raises :class:`NothingToCompactError` when no new context follows the
+        latest compact marker, and :class:`asyncio.CancelledError` when
+        :meth:`cancel` stops the summary request.
+        """
+
+        self._event_loop = asyncio.get_running_loop()
+        self._cancel_event.clear()
+        adapter = get_provider_adapter(self.provider)
+        return await self._compact(adapter, on_persist)
+
+    def compact(
+        self,
+        *,
+        on_persist: PersistCallback | None = None,
+    ) -> ConversationMessage:
+        """Compact the conversation synchronously; see :meth:`acompact`."""
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+        else:
+            raise RuntimeError("Agent.compact() cannot run inside an active event loop; use Agent.acompact() instead")
+
+        return asyncio.run(self.acompact(on_persist=on_persist))
+
     async def _compact(
         self,
         adapter: ProviderAdapter,
-        persist: PersistCallback,
-    ) -> None:
-        """Ask the provider for a summary, persist the compact event, append it."""
+        on_persist: PersistCallback | None,
+    ) -> ConversationMessage:
+        """Ask the provider for a summary, persist and append the compact marker."""
+
+        if not has_compactable_history(self.messages):
+            raise NothingToCompactError("nothing to compact")
 
         request = self._build_request(
             tools=[],
@@ -746,6 +837,9 @@ class Agent:
         if not summary_text:
             raise ValueError("compaction produced empty summary")
 
+        if self._cancel_event.is_set():
+            raise asyncio.CancelledError
+
         summary_total_tokens = (summary_message.get("meta") or {}).get("total_tokens")
         compact_event = build_compact_event(
             summary_text,
@@ -754,5 +848,6 @@ class Agent:
             total_tokens=summary_total_tokens,
         )
 
-        await persist(compact_event)
+        await self._persist_message(compact_event, on_persist)
         self.messages.append(compact_event)
+        return compact_event

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/compact.py

@@ -8,6 +8,11 @@ from mycode.messages import ConversationMessage, build_message, text_block
 
 DEFAULT_COMPACT_THRESHOLD = 0.8
 
+
+class NothingToCompactError(ValueError):
+    """Raised when there is no new context to compact past the latest marker."""
+
+
 COMPACT_SUMMARY_PROMPT = """\
 Summarize this conversation to create a continuation document. \
 This summary will replace the full conversation history, so it must \
@@ -65,6 +70,20 @@ def should_compact(
     return last_total_tokens >= context_window * threshold
 
 
+def has_compactable_history(messages: list[ConversationMessage]) -> bool:
+    """True when at least one non-empty user/assistant message follows the latest compact marker."""
+
+    last_compact = -1
+    for i, message in enumerate(messages):
+        if message.get("role") == "compact":
+            last_compact = i
+
+    return any(
+        message.get("role") in ("user", "assistant") and message.get("content")
+        for message in messages[last_compact + 1 :]
+    )
+
+
 def build_compact_event(
     summary_text: str,
     *,

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/messages.py

@@ -165,8 +165,8 @@ def flatten_message_text(message: ConversationMessage, *, include_thinking: bool
             continue
         raw_meta = block.get("meta")
         meta = raw_meta if isinstance(raw_meta, dict) else {}
-        # Attached file snapshots should not become session titles or history labels.
-        if meta.get("attachment"):
+        # Local payload blocks should not become session titles or history labels.
+        if meta.get("attachment") or meta.get("skill_snapshot"):
             continue
         btype = block.get("type")
         if btype == "text" or (include_thinking and btype == "thinking"):

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/models.py

@@ -2,9 +2,9 @@
 
 from __future__ import annotations
 
-import functools
 import json
 from dataclasses import dataclass, replace
+from functools import cache
 from pathlib import Path
 from typing import Any
 
@@ -30,14 +30,14 @@ class ModelMetadata:
     supports_pdf_input: bool | None = None
 
 
-@functools.cache
+@cache
 def load_models_catalog() -> dict[str, Any] | None:
     """Load the bundled model catalog from disk once per process."""
 
     try:
         data = json.loads(_MODELS_CATALOG_PATH.read_text(encoding="utf-8"))
-    except Exception:
-        data = None
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return None
     return data if isinstance(data, dict) else None
 
 

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/providers/anthropic_like.py

@@ -111,8 +111,9 @@ class AnthropicLikeAdapter(ProviderAdapter):
             if not isinstance(content, list):
                 return
 
-            blocks: list[dict[str, Any]] = [cast(dict[str, Any], block) for block in content if isinstance(block, dict)]
-            for block in reversed(blocks):
+            for block in reversed(content):
+                if not isinstance(block, dict):
+                    continue
                 block_type = str(block.get("type") or "")
                 if block_type not in {"text", "image", "document", "tool_result"}:
                     continue

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/providers/base.py

@@ -88,7 +88,7 @@ def parse_tool_call_input(raw_arguments: str) -> tuple[dict[str, Any], dict[str,
     try:
         parsed = json.loads(raw_arguments)
     except json.JSONDecodeError:
-        parsed = None
+        return {}, {"raw_arguments": raw_arguments}
     if isinstance(parsed, dict):
         return parsed, {}
     return {}, {"raw_arguments": raw_arguments}

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/providers/gemini.py

@@ -84,7 +84,7 @@ class GoogleGeminiAdapter(ProviderAdapter):
                 finish_message = getattr(candidate, "finish_message", None) or finish_message
 
                 for part in getattr(getattr(candidate, "content", None), "parts", None) or []:
-                    for event in self._consume_part(blocks, part):
+                    if event := self._consume_part(blocks, part):
                         yield event
         except APIError as exc:
             raise ValueError(str(exc)) from exc
@@ -223,7 +223,7 @@ class GoogleGeminiAdapter(ProviderAdapter):
         return contents
 
     def _build_config(self, request: ProviderRequest) -> types.GenerateContentConfig:
-        tools: list[types.Tool | Any] | None = None
+        tools: list[types.Tool] | None = None
         if request.tools:
             tools = [
                 types.Tool(
@@ -262,7 +262,7 @@ class GoogleGeminiAdapter(ProviderAdapter):
             thinking_config=thinking_config,
         )
 
-    def _consume_part(self, blocks: list[dict[str, Any]], part: Any) -> list[ProviderStreamEvent]:
+    def _consume_part(self, blocks: list[dict[str, Any]], part: Any) -> ProviderStreamEvent | None:
         native_part = _to_json(part) or {}
         if native_part.get("thought") is False:
             native_part.pop("thought", None)
@@ -278,12 +278,12 @@ class GoogleGeminiAdapter(ProviderAdapter):
                     meta={"native": {"part": native_part}},
                 )
             )
-            return []
+            return None
 
         text = getattr(part, "text", None)
         if text is None or text == "":
             if not native_part.get("thought_signature"):
-                return []
+                return None
 
             # Gemini may put the final thought signature into an empty-text part.
             # Keep it as a separate empty block so replay preserves the original
@@ -291,7 +291,7 @@ class GoogleGeminiAdapter(ProviderAdapter):
             part_meta = {"native": {"part": native_part}}
             is_thought = getattr(part, "thought", False)
             blocks.append(thinking_block("", meta=part_meta) if is_thought else text_block("", meta=part_meta))
-            return []
+            return None
 
         is_thought = bool(getattr(part, "thought", False))
         event = ProviderStreamEvent("thinking_delta" if is_thought else "text_delta", {"text": str(text)})
@@ -310,10 +310,10 @@ class GoogleGeminiAdapter(ProviderAdapter):
                     last_part["text"] = f"{last_part.get('text') or ''}{text}"
                     if current_signature and not last_signature:
                         last_part["thought_signature"] = current_signature
-                    return [event]
+                    return event
 
         part_meta = {"native": {"part": native_part}}
         blocks.append(
             thinking_block(str(text), meta=part_meta) if is_thought else text_block(str(text), meta=part_meta)
         )
-        return [event]
+        return event

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/providers/openai_chat.py

@@ -9,7 +9,7 @@ from typing import Any, override
 
 from openai import APIError, AsyncOpenAI
 
-from mycode.messages import assistant_message, text_block, thinking_block, tool_use_block
+from mycode.messages import ConversationMessage, assistant_message, text_block, thinking_block, tool_use_block
 from mycode.providers.base import (
     DEFAULT_REQUEST_TIMEOUT,
     ProviderAdapter,
@@ -174,7 +174,7 @@ class OpenAIChatAdapter(ProviderAdapter):
             },
         }
 
-    def _serialize_message(self, message: dict[str, Any]) -> list[dict[str, Any]]:
+    def _serialize_message(self, message: ConversationMessage) -> list[dict[str, Any]]:
         """Convert one canonical message into Chat Completions wire messages."""
 
         role = str(message.get("role") or "user")

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/providers/openai_responses.py

@@ -102,9 +102,8 @@ class OpenAIResponsesAdapter(ProviderAdapter):
             raise ValueError(str(exc)) from exc
 
     def _build_request_payload(self, request: ProviderRequest) -> dict[str, Any]:
-        prepared_messages = self.prepare_messages(request)
         input_items: list[dict[str, Any]] = []
-        for message in prepared_messages:
+        for message in self.prepare_messages(request):
             role = message.get("role")
             if role == "user":
                 input_items.extend(self._serialize_user_message(message))
@@ -262,7 +261,7 @@ class OpenAIResponsesAdapter(ProviderAdapter):
         response: Any,
         *,
         output_items: list[Any] | None = None,
-    ) -> dict[str, Any]:
+    ) -> ConversationMessage:
         raw_output = output_items if output_items is not None else (getattr(response, "output", None) or [])
         dumped_output_items = dump_model(raw_output)
         blocks: list[dict[str, Any]] = []
@@ -357,8 +356,8 @@ def _normalize_strict_schema(schema: Any) -> None:
 
     properties = schema.get("properties")
     if isinstance(properties, dict):
-        required_names = {str(name) for name in schema.get("required", []) if isinstance(name, str)}
-        for name, property_schema in list(properties.items()):
+        required_names = {name for name in schema.get("required", []) if isinstance(name, str)}
+        for name, property_schema in properties.items():
             _normalize_strict_schema(property_schema)
             if name not in required_names:
                 properties[name] = _nullable_schema(property_schema)

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/session.py

@@ -139,7 +139,7 @@ class SessionStore:
         meta = _project_meta(meta)
         self.meta_path(session_id).write_text(json.dumps(meta, indent=2, ensure_ascii=False), encoding="utf-8")
         index = self._read_index()
-        index[session_id] = dict(meta)
+        index[session_id] = meta
         self._write_index(index)
 
     def _read_index(self) -> SessionIndex:
@@ -161,7 +161,7 @@ class SessionStore:
                 continue
             meta = self._read_meta(entry.name)
             if meta is not None:
-                index[entry.name] = dict(meta)
+                index[entry.name] = meta
         self._write_index(index)
         return index
 
@@ -246,9 +246,7 @@ class SessionStore:
 
     async def delete_session(self, session_id: str) -> None:
         def delete() -> None:
-            sdir = self.session_dir(session_id)
-            if sdir.exists():
-                shutil.rmtree(sdir, ignore_errors=True)
+            shutil.rmtree(self.session_dir(session_id), ignore_errors=True)
             index = self._read_index()
             index.pop(session_id, None)
             self._write_index(index)
@@ -285,8 +283,7 @@ class SessionStore:
 
         def append() -> None:
             with self.messages_path(session_id).open("a", encoding="utf-8") as handle:
-                handle.write(json.dumps(message, ensure_ascii=False))
-                handle.write("\n")
+                handle.write(json.dumps(message, ensure_ascii=False) + "\n")
 
             meta = self._read_meta(session_id)
             if meta is None:

{mycode_sdk-0.9.5 → mycode_sdk-0.11.0}/src/mycode/tools.py

@@ -13,6 +13,7 @@ facades on :class:`ToolContext`::
 from __future__ import annotations
 
 import asyncio
+import functools
 import inspect
 import json
 import os
@@ -25,7 +26,7 @@ import time
 import typing
 from base64 import b64encode
 from collections import deque
-from collections.abc import Callable, Mapping, Sequence
+from collections.abc import Callable, Coroutine, Mapping, Sequence
 from contextlib import suppress
 from dataclasses import dataclass
 from difflib import SequenceMatcher, unified_diff
@@ -71,7 +72,19 @@ class ToolExecutionResult:
     is_error: bool = False
 
 
-ToolRunner = Callable[["ToolContext", dict[str, Any]], ToolExecutionResult]
+SyncToolRunner = Callable[["ToolContext", dict[str, Any]], ToolExecutionResult]
+AsyncToolRunner = Callable[["ToolContext", dict[str, Any]], Coroutine[Any, Any, ToolExecutionResult]]
+ToolRunner = SyncToolRunner | AsyncToolRunner
+
+
+def _is_async_callable(runner: ToolRunner) -> bool:
+    current: Any = runner
+    while True:
+        current = inspect.unwrap(current)
+        if isinstance(current, functools.partial):
+            current = current.func
+            continue
+        return inspect.iscoroutinefunction(current) or inspect.iscoroutinefunction(type(current).__call__)
 
 
 @dataclass(frozen=True)
@@ -85,6 +98,10 @@ class ToolSpec:
     # Streaming tools push incremental output through ToolContext.emit.
     streams_output: bool = False
 
+    @property
+    def is_async(self) -> bool:
+        return _is_async_callable(self.runner)
+
 
 # ---------------------------------------------------------------------------
 # ToolContext
@@ -115,25 +132,47 @@ class ToolContext:
     ) -> ToolExecutionResult:
         return self.call("read", {"path": path, "offset": offset, "limit": limit})
 
+    async def aread(
+        self,
+        path: str,
+        *,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> ToolExecutionResult:
+        return await self.acall("read", {"path": path, "offset": offset, "limit": limit})
+
     def write(self, path: str, content: str) -> ToolExecutionResult:
         return self.call("write", {"path": path, "content": content})
 
+    async def awrite(self, path: str, content: str) -> ToolExecutionResult:
+        return await self.acall("write", {"path": path, "content": content})
+
     def edit(self, path: str, edits: list[dict[str, str]]) -> ToolExecutionResult:
         return self.call("edit", {"path": path, "edits": edits})
 
+    async def aedit(self, path: str, edits: list[dict[str, str]]) -> ToolExecutionResult:
+        return await self.acall("edit", {"path": path, "edits": edits})
+
     def bash(self, command: str, *, timeout: int | None = None) -> ToolExecutionResult:
         return self.call("bash", {"command": command, "timeout": timeout})
 
+    async def abash(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,  # noqa: ASYNC109
+    ) -> ToolExecutionResult:
+        return await self.acall("bash", {"command": command, "timeout": timeout})
+
     def call(self, name: str, args: dict[str, Any]) -> ToolExecutionResult:
         """Dispatch through the registry, including from custom tool wrappers."""
 
         return self.executor.execute(name, args, self)
 
-    def track_proc(self, proc: subprocess.Popen[str]) -> None:
-        self.executor.track_proc(proc)
+    async def acall(self, name: str, args: dict[str, Any]) -> ToolExecutionResult:
+        """Asynchronously dispatch through the registry."""
 
-    def untrack_proc(self, proc: subprocess.Popen[str]) -> None:
-        self.executor.untrack_proc(proc)
+        return await self.executor.aexecute(name, args, self)
 
 
 # ---------------------------------------------------------------------------
@@ -166,7 +205,21 @@ class ToolExecutor:
         spec = self._tools.get(name)
         if spec is None:
             return ToolExecutionResult(output=f"error: unknown tool: {name}", is_error=True)
-        return spec.runner(ctx, args)
+        if spec.is_async:
+            runner = cast(AsyncToolRunner, spec.runner)
+            return asyncio.run(runner(ctx, args))
+        runner = cast(SyncToolRunner, spec.runner)
+        return runner(ctx, args)
+
+    async def aexecute(self, name: str, args: dict[str, Any], ctx: ToolContext) -> ToolExecutionResult:
+        spec = self._tools.get(name)
+        if spec is None:
+            return ToolExecutionResult(output=f"error: unknown tool: {name}", is_error=True)
+        if spec.is_async:
+            runner = cast(AsyncToolRunner, spec.runner)
+            return await runner(ctx, args)
+        runner = cast(SyncToolRunner, spec.runner)
+        return await asyncio.to_thread(runner, ctx, args)
 
     # Subprocess tracking: register with both this executor (per-session
     # cancel) and the process-global set (shutdown cleanup).
@@ -202,6 +255,9 @@ class ToolExecutor:
 # agents may run concurrently in the same process); this module-level set is
 # a shutdown-time safety net exposed as ``cancel_all_tools``.
 
+_ACTIVE_PROCS: set[subprocess.Popen[str]] = set()
+_ACTIVE_PROCS_LOCK = threading.Lock()
+
 
 def cancel_all_tools() -> None:
     """Terminate every running bash subprocess in the current process."""
@@ -213,10 +269,6 @@ def cancel_all_tools() -> None:
         _kill_proc_tree(proc)
 
 
-_ACTIVE_PROCS: set[subprocess.Popen[str]] = set()
-_ACTIVE_PROCS_LOCK = threading.Lock()
-
-
 def _kill_proc_tree(proc: subprocess.Popen[str]) -> None:
     try:
         if os.name == "posix":
@@ -326,7 +378,7 @@ def tool(
 
         is_async = inspect.iscoroutinefunction(fn)
 
-        def runner(context: ToolContext, args: dict[str, Any]) -> ToolExecutionResult:
+        def prepare_args(args: dict[str, Any]) -> dict[str, Any] | ToolExecutionResult:
             # Strict providers send explicit null for an omitted optional field;
             # drop it so the parameter default applies instead of failing validation.
             validation_args = {
@@ -339,14 +391,29 @@ def tool(
             except ValidationError as exc:
                 return ToolExecutionResult(output=f"error: invalid tool input: {exc}", is_error=True)
 
-            call_args = {name: getattr(parsed_args, name) for name in tool_param_names}
-            if is_async:
-                # The executor runs on a worker thread, so spinning a fresh
-                # event loop here is safe.
-                value = asyncio.run(fn(context, **call_args) if wants_context else fn(**call_args))
-            else:
+            return {name: getattr(parsed_args, name) for name in tool_param_names}
+
+        if is_async:
+
+            async def async_runner(context: ToolContext, args: dict[str, Any]) -> ToolExecutionResult:
+                call_args = prepare_args(args)
+                if isinstance(call_args, ToolExecutionResult):
+                    return call_args
+                value = await (fn(context, **call_args) if wants_context else fn(**call_args))
+                return _coerce_tool_result(value)
+
+            runner: ToolRunner = async_runner
+
+        else:
+
+            def sync_runner(context: ToolContext, args: dict[str, Any]) -> ToolExecutionResult:
+                call_args = prepare_args(args)
+                if isinstance(call_args, ToolExecutionResult):
+                    return call_args
                 value = fn(context, **call_args) if wants_context else fn(**call_args)
-            return _coerce_tool_result(value)
+                return _coerce_tool_result(value)
+
+            runner = sync_runner
 
         return ToolSpec(
             name=tool_name,
@@ -479,8 +546,8 @@ def read_tool(
             ],
         )
 
-    start_line = offset if isinstance(offset, int) and offset > 0 else 1
-    line_limit = limit if isinstance(limit, int) and limit > 0 else DEFAULT_MAX_LINES
+    start_line = offset if offset is not None and offset > 0 else 1
+    line_limit = limit if limit is not None and limit > 0 else DEFAULT_MAX_LINES
     lines: list[str] = []
     total_lines = 0
     next_offset: int | None = None
@@ -764,7 +831,7 @@ def bash_tool(ctx: ToolContext, command: str, timeout: int | None = None) -> Too
     again by :func:`truncate_text` to the display limits.
     """
 
-    timeout_seconds = int(timeout) if isinstance(timeout, int) and timeout > 0 else BASH_TIMEOUT_SECONDS
+    timeout_seconds = timeout if timeout is not None and timeout > 0 else BASH_TIMEOUT_SECONDS
 
     proc: subprocess.Popen[str] | None = None
     log_path = ctx.tool_output_dir / f"bash-{ctx.tool_call_id or 'call'}.log"
@@ -787,7 +854,7 @@ def bash_tool(ctx: ToolContext, command: str, timeout: int | None = None) -> Too
             bufsize=1,
             start_new_session=os.name == "posix",
         )
-        ctx.track_proc(proc)
+        ctx.executor.track_proc(proc)
 
         stdout = cast(TextIO, proc.stdout)
         output_queue: queue.Queue[str | None] = queue.Queue()
@@ -903,7 +970,7 @@ def bash_tool(ctx: ToolContext, command: str, timeout: int | None = None) -> Too
             with suppress(Exception):
                 log_file.close()
         if proc is not None:
-            ctx.untrack_proc(proc)
+            ctx.executor.untrack_proc(proc)
             if proc.poll() is None:
                 _kill_proc_tree(proc)