klaude-code 1.2.18__py3-none-any.whl → 1.2.20__py3-none-any.whl

klaude_code/core/reminders.py

@@ -1,6 +1,7 @@
 import re
 import shlex
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
 from pathlib import Path
 
 from pydantic import BaseModel
@@ -31,6 +32,45 @@ def get_last_new_user_input(session: Session) -> str | None:
     return "\n\n".join(result)
 
 
+@dataclass
+class AtPatternSource:
+    """Represents an @ pattern with its source file (if from a memory file)."""
+
+    pattern: str
+    mentioned_in: str | None = None
+
+
+def get_at_patterns_with_source(session: Session) -> list[AtPatternSource]:
+    """Get @ patterns from last user input and developer messages, preserving source info."""
+    patterns: list[AtPatternSource] = []
+
+    for item in reversed(session.conversation_history):
+        if isinstance(item, model.ToolResultItem):
+            break
+
+        if isinstance(item, model.UserMessageItem):
+            content = item.content or ""
+            if "@" in content:
+                for match in AT_FILE_PATTERN.finditer(content):
+                    path_str = match.group("quoted") or match.group("plain")
+                    if path_str:
+                        patterns.append(AtPatternSource(pattern=path_str, mentioned_in=None))
+            break
+
+        if isinstance(item, model.DeveloperMessageItem):
+            content = item.content or ""
+            if "@" not in content:
+                continue
+            # Use first memory_path as the source if available
+            source = item.memory_paths[0] if item.memory_paths else None
+            for match in AT_FILE_PATTERN.finditer(content):
+                path_str = match.group("quoted") or match.group("plain")
+                if path_str:
+                    patterns.append(AtPatternSource(pattern=path_str, mentioned_in=source))
+
+    return patterns
+
+
 async def _load_at_file_recursive(
     session: Session,
     pattern: str,
@@ -99,33 +139,22 @@ async def at_file_reader_reminder(
     session: Session,
 ) -> model.DeveloperMessageItem | None:
     """Parse @foo/bar to read, with recursive loading of nested @ references"""
-    last_user_input = get_last_new_user_input(session)
-    if not last_user_input or "@" not in last_user_input:
-        return None
-
-    at_patterns: list[str] = []
-
-    for match in AT_FILE_PATTERN.finditer(last_user_input):
-        quoted = match.group("quoted")
-        plain = match.group("plain")
-        path_str = quoted if quoted is not None else plain
-        if path_str:
-            at_patterns.append(path_str)
-
-    if len(at_patterns) == 0:
+    at_pattern_sources = get_at_patterns_with_source(session)
+    if not at_pattern_sources:
         return None
 
     at_files: dict[str, model.AtPatternParseResult] = {}  # path -> content
     collected_images: list[model.ImageURLPart] = []
     visited: set[str] = set()
 
-    for pattern in at_patterns:
+    for source in at_pattern_sources:
         await _load_at_file_recursive(
             session,
-            pattern,
+            source.pattern,
             at_files,
             collected_images,
             visited,
+            mentioned_in=source.mentioned_in,
         )
 
     if len(at_files) == 0:
@@ -231,9 +260,9 @@ async def file_changed_externally_reminder(
     changed_files: list[tuple[str, str, list[model.ImageURLPart] | None]] = []
     collected_images: list[model.ImageURLPart] = []
     if session.file_tracker and len(session.file_tracker) > 0:
-        for path, mtime in session.file_tracker.items():
+        for path, status in session.file_tracker.items():
             try:
-                if Path(path).stat().st_mtime > mtime:
+                if Path(path).stat().st_mtime > status.mtime:
                     context_token = set_tool_context_from_session(session)
                     try:
                         tool_result = await ReadTool.call_with_args(
@@ -282,6 +311,7 @@ def get_memory_paths() -> list[tuple[Path, str]]:
         ),
         (Path.cwd() / "AGENTS.md", "project instructions, checked into the codebase"),
         (Path.cwd() / "CLAUDE.md", "project instructions, checked into the codebase"),
+        (Path.cwd() / ".claude" / "CLAUDE.md", "project instructions, checked into the codebase"),
     ]
 
 
@@ -313,16 +343,32 @@ async def image_reminder(session: Session) -> model.DeveloperMessageItem | None:
     )
 
 
+def _is_memory_loaded(session: Session, path: str) -> bool:
+    """Check if a memory file has already been loaded (tracked with is_memory=True)."""
+    status = session.file_tracker.get(path)
+    return status is not None and status.is_memory
+
+
+def _mark_memory_loaded(session: Session, path: str) -> None:
+    """Mark a file as loaded memory in file_tracker."""
+    try:
+        mtime = Path(path).stat().st_mtime
+    except (OSError, FileNotFoundError):
+        mtime = 0.0
+    session.file_tracker[path] = model.FileStatus(mtime=mtime, is_memory=True)
+
+
 async def memory_reminder(session: Session) -> model.DeveloperMessageItem | None:
     """CLAUDE.md AGENTS.md"""
     memory_paths = get_memory_paths()
     memories: list[Memory] = []
     for memory_path, instruction in memory_paths:
-        if memory_path.exists() and memory_path.is_file() and str(memory_path) not in session.loaded_memory:
+        path_str = str(memory_path)
+        if memory_path.exists() and memory_path.is_file() and not _is_memory_loaded(session, path_str):
             try:
                 text = memory_path.read_text()
-                session.loaded_memory.append(str(memory_path))
-                memories.append(Memory(path=str(memory_path), instruction=instruction, content=text))
+                _mark_memory_loaded(session, path_str)
+                memories.append(Memory(path=path_str, instruction=instruction, content=text))
             except (PermissionError, UnicodeDecodeError, OSError):
                 continue
     if len(memories) > 0:
@@ -358,7 +404,7 @@ async def last_path_memory_reminder(
     """Load CLAUDE.md/AGENTS.md from directories containing files in file_tracker.
 
     Uses session.file_tracker to detect accessed paths (works for both tool calls
-    and @ file references). Uses session.loaded_memory to avoid duplicate loading.
+    and @ file references). Checks is_memory flag to avoid duplicate loading.
     """
     if not session.file_tracker:
         return None
@@ -367,7 +413,6 @@ async def last_path_memory_reminder(
     memories: list[Memory] = []
 
     cwd = Path.cwd().resolve()
-    loaded_set: set[str] = set(session.loaded_memory)
     seen_memory_files: set[str] = set()
 
     for p_str in paths:
@@ -395,15 +440,14 @@ async def last_path_memory_reminder(
             for fname in MEMORY_FILE_NAMES:
                 mem_path = current_dir / fname
                 mem_path_str = str(mem_path)
-                if mem_path_str in seen_memory_files or mem_path_str in loaded_set:
+                if mem_path_str in seen_memory_files or _is_memory_loaded(session, mem_path_str):
                     continue
                 if mem_path.exists() and mem_path.is_file():
                     try:
                         text = mem_path.read_text()
                     except (PermissionError, UnicodeDecodeError, OSError):
                         continue
-                    session.loaded_memory.append(mem_path_str)
-                    loaded_set.add(mem_path_str)
+                    _mark_memory_loaded(session, mem_path_str)
                     seen_memory_files.add(mem_path_str)
                     memories.append(
                         Memory(

klaude_code/core/task.py

@@ -2,13 +2,13 @@ from __future__ import annotations
 
 import asyncio
 import time
-from collections.abc import AsyncGenerator, Callable, MutableMapping, Sequence
+from collections.abc import AsyncGenerator, Callable, Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from klaude_code import const
 from klaude_code.core.reminders import Reminder
-from klaude_code.core.tool import TodoContext, ToolABC
+from klaude_code.core.tool import FileTracker, TodoContext, ToolABC
 from klaude_code.core.turn import TurnError, TurnExecutionContext, TurnExecutor
 from klaude_code.protocol import events, model
 from klaude_code.trace import DebugType, log_debug
@@ -29,6 +29,8 @@ class MetadataAccumulator:
         self._sub_agent_metadata: list[model.TaskMetadata] = []
         self._throughput_weighted_sum: float = 0.0
         self._throughput_tracked_tokens: int = 0
+        self._first_token_latency_sum: float = 0.0
+        self._first_token_latency_count: int = 0
         self._turn_count: int = 0
 
     def add(self, turn_metadata: model.ResponseMetadataItem) -> None:
@@ -51,13 +53,8 @@ class MetadataAccumulator:
                 acc_usage.context_limit = usage.context_limit
 
             if usage.first_token_latency_ms is not None:
-                if acc_usage.first_token_latency_ms is None:
-                    acc_usage.first_token_latency_ms = usage.first_token_latency_ms
-                else:
-                    acc_usage.first_token_latency_ms = min(
-                        acc_usage.first_token_latency_ms,
-                        usage.first_token_latency_ms,
-                    )
+                self._first_token_latency_sum += usage.first_token_latency_ms
+                self._first_token_latency_count += 1
 
             if usage.throughput_tps is not None:
                 current_output = usage.output_tokens
@@ -83,6 +80,11 @@ class MetadataAccumulator:
             else:
                 main.usage.throughput_tps = None
 
+            if self._first_token_latency_count > 0:
+                main.usage.first_token_latency_ms = self._first_token_latency_sum / self._first_token_latency_count
+            else:
+                main.usage.first_token_latency_ms = None
+
         main.task_duration_s = task_duration_s
         main.turn_count = self._turn_count
         return model.TaskMetadataItem(main=main, sub_agent_task_metadata=self._sub_agent_metadata)
@@ -98,7 +100,7 @@ class SessionContext:
     session_id: str
     get_conversation_history: Callable[[], list[model.ConversationItem]]
     append_history: Callable[[Sequence[model.ConversationItem]], None]
-    file_tracker: MutableMapping[str, float]
+    file_tracker: FileTracker
     todo_context: TodoContext
 
 
@@ -147,8 +149,7 @@ class TaskExecutor:
             session_id=session_ctx.session_id,
             sub_agent_state=ctx.sub_agent_state,
         )
-
-        session_ctx.append_history([model.UserMessageItem(content=user_input.text, images=user_input.images)])
+        del user_input  # Persisted by the operation handler before launching the task.
 
         profile = ctx.profile
         metadata_accumulator = MetadataAccumulator(model_name=profile.llm_client.model_name)

klaude_code/core/tool/__init__.py

@@ -15,6 +15,7 @@ from .todo.todo_write_tool import TodoWriteTool
 from .todo.update_plan_tool import UpdatePlanTool
 from .tool_abc import ToolABC
 from .tool_context import (
+    FileTracker,
     TodoContext,
     ToolContextToken,
     build_todo_context,
@@ -36,6 +37,7 @@ __all__ = [
     "BashTool",
     "DiffError",
     "EditTool",
+    "FileTracker",
     "MemoryTool",
     "MermaidTool",
     "MultiEditTool",

klaude_code/core/tool/file/apply_patch_tool.py

@@ -80,7 +80,9 @@ class ApplyPatchHandler:
 
             if file_tracker is not None:
                 with contextlib.suppress(Exception):  # pragma: no cover - file tracker best-effort
-                    file_tracker[resolved] = Path(resolved).stat().st_mtime
+                    existing = file_tracker.get(resolved)
+                    is_mem = existing.is_memory if existing else False
+                    file_tracker[resolved] = model.FileStatus(mtime=Path(resolved).stat().st_mtime, is_memory=is_mem)
 
         def remove_fn(path: str) -> None:
             resolved = resolve_path(path)

klaude_code/core/tool/file/edit_tool.py

@@ -119,8 +119,8 @@ class EditTool(ToolABC):
                 output=("File has not been read yet. Read it first before writing to it."),
             )
         if file_tracker is not None:
-            tracked = file_tracker.get(file_path)
-            if tracked is None:
+            tracked_status = file_tracker.get(file_path)
+            if tracked_status is None:
                 return model.ToolResultItem(
                     status="error",
                     output=("File has not been read yet. Read it first before writing to it."),
@@ -128,8 +128,8 @@ class EditTool(ToolABC):
             try:
                 current_mtime = Path(file_path).stat().st_mtime
             except Exception:
-                current_mtime = tracked
-            if current_mtime != tracked:
+                current_mtime = tracked_status.mtime
+            if current_mtime != tracked_status.mtime:
                 return model.ToolResultItem(
                     status="error",
                     output=(
@@ -193,7 +193,9 @@ class EditTool(ToolABC):
         # Update tracker with new mtime
         if file_tracker is not None:
             with contextlib.suppress(Exception):
-                file_tracker[file_path] = Path(file_path).stat().st_mtime
+                existing = file_tracker.get(file_path)
+                is_mem = existing.is_memory if existing else False
+                file_tracker[file_path] = model.FileStatus(mtime=Path(file_path).stat().st_mtime, is_memory=is_mem)
 
         # Build output message
         if args.replace_all:

klaude_code/core/tool/file/multi_edit_tool.py

@@ -92,8 +92,8 @@ class MultiEditTool(ToolABC):
         # FileTracker check:
         if file_exists(file_path):
             if file_tracker is not None:
-                tracked = file_tracker.get(file_path)
-                if tracked is None:
+                tracked_status = file_tracker.get(file_path)
+                if tracked_status is None:
                     return model.ToolResultItem(
                         status="error",
                         output=("File has not been read yet. Read it first before writing to it."),
@@ -101,8 +101,8 @@ class MultiEditTool(ToolABC):
                 try:
                     current_mtime = Path(file_path).stat().st_mtime
                 except Exception:
-                    current_mtime = tracked
-                if current_mtime != tracked:
+                    current_mtime = tracked_status.mtime
+                if current_mtime != tracked_status.mtime:
                     return model.ToolResultItem(
                         status="error",
                         output=(
@@ -164,7 +164,9 @@ class MultiEditTool(ToolABC):
         # Update tracker
         if file_tracker is not None:
             with contextlib.suppress(Exception):
-                file_tracker[file_path] = Path(file_path).stat().st_mtime
+                existing = file_tracker.get(file_path)
+                is_mem = existing.is_memory if existing else False
+                file_tracker[file_path] = model.FileStatus(mtime=Path(file_path).stat().st_mtime, is_memory=is_mem)
 
         # Build output message
         lines = [f"Applied {len(args.edits)} edits to {file_path}:"]

klaude_code/core/tool/file/read_tool.md

@@ -1,5 +1,6 @@
 Reads a file from the local filesystem. You can access any file directly by using this tool.
 Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+When you need to read an image, use this tool.
 
 Usage:
 - The file_path parameter must be an absolute path, not a relative path
@@ -11,4 +12,3 @@ Usage:
 - This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
 - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful. 
 - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
-- This tool does NOT support reading PDF files. Use a Python script with `pdfplumber` (for text/tables) or `pypdf` (for basic operations) to extract content from PDFs.

klaude_code/core/tool/file/read_tool.py

@@ -106,12 +106,15 @@ def _read_segment(options: ReadOptions) -> ReadSegmentResult:
     )
 
 
-def _track_file_access(file_path: str) -> None:
+def _track_file_access(file_path: str, *, is_memory: bool = False) -> None:
     file_tracker = get_current_file_tracker()
     if file_tracker is None or not file_exists(file_path) or is_directory(file_path):
         return
     with contextlib.suppress(Exception):
-        file_tracker[file_path] = Path(file_path).stat().st_mtime
+        existing = file_tracker.get(file_path)
+        # Preserve is_memory flag if already set
+        is_mem = is_memory or (existing.is_memory if existing else False)
+        file_tracker[file_path] = model.FileStatus(mtime=Path(file_path).stat().st_mtime, is_memory=is_mem)
 
 
 def _is_supported_image_file(file_path: str) -> bool:
@@ -209,8 +212,9 @@ class ReadTool(ToolABC):
             return model.ToolResultItem(
                 status="error",
                 output=(
-                    "<tool_use_error>PDF files are not supported by this tool. "
-                    "Please use a Python script with `pdfplumber` to extract text/tables:\n\n"
+                    "<tool_use_error>PDF files are not supported by this tool.\n"
+                    "If there's an available skill for PDF, use it.\n"
+                    "Or use a Python script with `pdfplumber` to extract text/tables:\n\n"
                     "```python\n"
                     "# /// script\n"
                     '# dependencies = ["pdfplumber"]\n'

klaude_code/core/tool/file/write_tool.py

@@ -64,10 +64,10 @@ class WriteTool(ToolABC):
         exists = file_exists(file_path)
 
         if exists:
-            tracked_mtime: float | None = None
+            tracked_status: model.FileStatus | None = None
             if file_tracker is not None:
-                tracked_mtime = file_tracker.get(file_path)
-            if tracked_mtime is None:
+                tracked_status = file_tracker.get(file_path)
+            if tracked_status is None:
                 return model.ToolResultItem(
                     status="error",
                     output=("File has not been read yet. Read it first before writing to it."),
@@ -75,8 +75,8 @@ class WriteTool(ToolABC):
             try:
                 current_mtime = Path(file_path).stat().st_mtime
             except Exception:
-                current_mtime = tracked_mtime
-            if current_mtime != tracked_mtime:
+                current_mtime = tracked_status.mtime
+            if current_mtime != tracked_status.mtime:
                 return model.ToolResultItem(
                     status="error",
                     output=(
@@ -100,7 +100,9 @@ class WriteTool(ToolABC):
 
         if file_tracker is not None:
             with contextlib.suppress(Exception):
-                file_tracker[file_path] = Path(file_path).stat().st_mtime
+                existing = file_tracker.get(file_path)
+                is_mem = existing.is_memory if existing else False
+                file_tracker[file_path] = model.FileStatus(mtime=Path(file_path).stat().st_mtime, is_memory=is_mem)
 
         # Build diff between previous and new content
         after = args.content

klaude_code/core/tool/memory/skill_loader.py

@@ -132,20 +132,22 @@ class SkillLoader:
         for user_dir in self.USER_SKILLS_DIRS:
             expanded_dir = user_dir.expanduser()
             if expanded_dir.exists():
-                for skill_file in expanded_dir.rglob("SKILL.md"):
-                    skill = self.load_skill(skill_file, location="user")
-                    if skill:
-                        skills.append(skill)
-                        self.loaded_skills[skill.name] = skill
+                for pattern in ("SKILL.md", "skill.md"):
+                    for skill_file in expanded_dir.rglob(pattern):
+                        skill = self.load_skill(skill_file, location="user")
+                        if skill:
+                            skills.append(skill)
+                            self.loaded_skills[skill.name] = skill
 
         # Load project-level skills (override user skills if same name)
         project_dir = self.PROJECT_SKILLS_DIR.resolve()
         if project_dir.exists():
-            for skill_file in project_dir.rglob("SKILL.md"):
-                skill = self.load_skill(skill_file, location="project")
-                if skill:
-                    skills.append(skill)
-                    self.loaded_skills[skill.name] = skill
+            for pattern in ("SKILL.md", "skill.md"):
+                for skill_file in project_dir.rglob(pattern):
+                    skill = self.load_skill(skill_file, location="project")
+                    if skill:
+                        skills.append(skill)
+                        self.loaded_skills[skill.name] = skill
 
         # Log discovery summary
         if skills:

klaude_code/core/tool/shell/bash_tool.py

@@ -1,5 +1,8 @@
 import asyncio
+import contextlib
+import os
 import re
+import signal
 import subprocess
 from pathlib import Path
 
@@ -87,22 +90,94 @@ class BashTool(ToolABC):
 
         # Run the command using bash -lc so shell semantics work (pipes, &&, etc.)
         # Capture stdout/stderr, respect timeout, and return a ToolMessage.
+        #
+        # Important: this tool is intentionally non-interactive.
+        # - Always detach stdin (DEVNULL) so interactive programs can't steal REPL input.
+        # - Always disable pagers/editors to avoid launching TUI subprocesses that can
+        #   leave the terminal in a bad state.
         cmd = ["bash", "-lc", args.command]
         timeout_sec = max(0.0, args.timeout_ms / 1000.0)
 
+        env = os.environ.copy()
+        env.update(
+            {
+                # Avoid blocking on git/jj prompts.
+                "GIT_TERMINAL_PROMPT": "0",
+                # Avoid pagers.
+                "PAGER": "cat",
+                "GIT_PAGER": "cat",
+                # Avoid opening editors.
+                "EDITOR": "true",
+                "VISUAL": "true",
+                "GIT_EDITOR": "true",
+                "JJ_EDITOR": "true",
+                # Encourage non-interactive output.
+                "TERM": "dumb",
+            }
+        )
+
+        async def _terminate_process(proc: asyncio.subprocess.Process) -> None:
+            # Best-effort termination. Ensure we don't hang on cancellation.
+            if proc.returncode is not None:
+                return
+
+            try:
+                if os.name == "posix" and proc.pid is not None:
+                    os.killpg(proc.pid, signal.SIGTERM)
+                else:
+                    proc.terminate()
+            except ProcessLookupError:
+                return
+            except Exception:
+                # Fall back to kill below.
+                pass
+
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(proc.wait(), timeout=1.0)
+                return
+
+            # Escalate to hard kill if it didn't exit quickly.
+            with contextlib.suppress(Exception):
+                if os.name == "posix" and proc.pid is not None:
+                    os.killpg(proc.pid, signal.SIGKILL)
+                else:
+                    proc.kill()
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(proc.wait(), timeout=1.0)
+
         try:
-            completed = await asyncio.to_thread(
-                subprocess.run,
-                cmd,
-                capture_output=True,
-                text=True,
-                timeout=timeout_sec,
-                check=False,
-            )
+            # Create a dedicated process group so we can terminate the whole tree.
+            # (macOS/Linux support start_new_session; Windows does not.)
+            kwargs: dict[str, object] = {
+                "stdin": asyncio.subprocess.DEVNULL,
+                "stdout": asyncio.subprocess.PIPE,
+                "stderr": asyncio.subprocess.PIPE,
+                "env": env,
+            }
+            if os.name == "posix":
+                kwargs["start_new_session"] = True
+            elif os.name == "nt":  # pragma: no cover
+                kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
 
-            stdout = _ANSI_ESCAPE_RE.sub("", completed.stdout or "")
-            stderr = _ANSI_ESCAPE_RE.sub("", completed.stderr or "")
-            rc = completed.returncode
+            proc = await asyncio.create_subprocess_exec(*cmd, **kwargs)
+            try:
+                stdout_b, stderr_b = await asyncio.wait_for(proc.communicate(), timeout=timeout_sec)
+            except TimeoutError:
+                with contextlib.suppress(Exception):
+                    await _terminate_process(proc)
+                return model.ToolResultItem(
+                    status="error",
+                    output=f"Timeout after {args.timeout_ms} ms running: {args.command}",
+                )
+            except asyncio.CancelledError:
+                # Ensure subprocess is stopped and propagate cancellation.
+                with contextlib.suppress(Exception):
+                    await asyncio.shield(_terminate_process(proc))
+                raise
+
+            stdout = _ANSI_ESCAPE_RE.sub("", (stdout_b or b"").decode(errors="replace"))
+            stderr = _ANSI_ESCAPE_RE.sub("", (stderr_b or b"").decode(errors="replace"))
+            rc = proc.returncode
 
             if rc == 0:
                 output = stdout if stdout else ""
@@ -125,17 +200,14 @@ class BashTool(ToolABC):
                     status="error",
                     output=combined.strip(),
                 )
-
-        except subprocess.TimeoutExpired:
-            return model.ToolResultItem(
-                status="error",
-                output=f"Timeout after {args.timeout_ms} ms running: {args.command}",
-            )
         except FileNotFoundError:
             return model.ToolResultItem(
                 status="error",
                 output="bash not found on system path",
             )
+        except asyncio.CancelledError:
+            # Propagate cooperative cancellation so outer layers can handle interrupts correctly.
+            raise
         except Exception as e:  # safeguard against unexpected failures
             return model.ToolResultItem(
                 status="error",

klaude_code/core/tool/sub_agent_tool.py

@@ -10,7 +10,7 @@ import asyncio
 import json
 from typing import TYPE_CHECKING, ClassVar
 
-from klaude_code.core.tool.tool_abc import ToolABC
+from klaude_code.core.tool.tool_abc import ToolABC, ToolConcurrencyPolicy, ToolMetadata
 from klaude_code.core.tool.tool_context import current_run_subtask_callback
 from klaude_code.protocol import llm_param, model
 
@@ -36,6 +36,10 @@ class SubAgentTool(ToolABC):
             {"_profile": profile},
         )
 
+    @classmethod
+    def metadata(cls) -> ToolMetadata:
+        return ToolMetadata(concurrency_policy=ToolConcurrencyPolicy.CONCURRENT, has_side_effects=True)
+
     @classmethod
     def schema(cls) -> llm_param.ToolSchema:
         profile = cls._profile

klaude_code/core/tool/tool_abc.py

@@ -1,5 +1,7 @@
 import string
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
 from pathlib import Path
 
 from klaude_code.protocol import llm_param, model
@@ -14,6 +16,10 @@ def load_desc(path: Path, substitutions: dict[str, str] | None = None) -> str:
 
 
 class ToolABC(ABC):
+    @classmethod
+    def metadata(cls) -> "ToolMetadata":
+        return ToolMetadata()
+
     @classmethod
     @abstractmethod
     def schema(cls) -> llm_param.ToolSchema:
@@ -23,3 +29,15 @@ class ToolABC(ABC):
     @abstractmethod
     async def call(cls, arguments: str) -> model.ToolResultItem:
         raise NotImplementedError
+
+
+class ToolConcurrencyPolicy(str, Enum):
+    SEQUENTIAL = "sequential"
+    CONCURRENT = "concurrent"
+
+
+@dataclass(frozen=True)
+class ToolMetadata:
+    concurrency_policy: ToolConcurrencyPolicy = ToolConcurrencyPolicy.SEQUENTIAL
+    has_side_effects: bool = False
+    requires_tool_context: bool = True