klaude-code 1.2.15__py3-none-any.whl → 1.2.16__py3-none-any.whl

klaude_code/cli/main.py

@@ -13,7 +13,7 @@ from klaude_code.cli.debug import DEBUG_FILTER_HELP, open_log_file_in_editor, re
 from klaude_code.cli.session_cmd import register_session_commands
 from klaude_code.config import load_config
 from klaude_code.session import Session, resume_select_session
-from klaude_code.trace import prepare_debug_log_file
+from klaude_code.trace import DebugType, prepare_debug_log_file
 
 
 def set_terminal_title(title: str) -> None:
@@ -22,6 +22,63 @@ def set_terminal_title(title: str) -> None:
     sys.stdout.flush()
 
 
+def setup_terminal_title() -> None:
+    """Set terminal title to current folder name."""
+    folder_name = os.path.basename(os.getcwd())
+    set_terminal_title(f"{folder_name}: klaude")
+
+
+def prepare_debug_logging(debug: bool, debug_filter: str | None) -> tuple[bool, set[DebugType] | None, Path | None]:
+    """Resolve debug settings and prepare log file if debugging is enabled.
+
+    Returns:
+        A tuple of (debug_enabled, debug_filters, log_path).
+        log_path is None if debugging is disabled.
+    """
+    debug_enabled, debug_filters = resolve_debug_settings(debug, debug_filter)
+    log_path: Path | None = None
+    if debug_enabled:
+        log_path = prepare_debug_log_file()
+    return debug_enabled, debug_filters, log_path
+
+
+def read_input_content(cli_argument: str) -> str | None:
+    """Read and merge input from stdin and CLI argument.
+
+    Args:
+        cli_argument: The input content passed as CLI argument.
+
+    Returns:
+        The merged input content, or None if no input was provided.
+    """
+    from klaude_code.trace import log
+
+    parts: list[str] = []
+
+    # Handle stdin input
+    if not sys.stdin.isatty():
+        try:
+            stdin = sys.stdin.read().rstrip("\n")
+            if stdin:
+                parts.append(stdin)
+        except (OSError, ValueError) as e:
+            # Expected I/O-related errors when reading from stdin (e.g. broken pipe, closed stream).
+            log((f"Error reading from stdin: {e}", "red"))
+        except Exception as e:
+            # Unexpected errors are still reported but kept from crashing the CLI.
+            log((f"Unexpected error reading from stdin: {e}", "red"))
+
+    if cli_argument:
+        parts.append(cli_argument)
+
+    content = "\n".join(parts)
+    if len(content) == 0:
+        log(("Error: No input content provided", "red"))
+        return None
+
+    return content
+
+
 def _version_callback(value: bool) -> None:
     """Show version and exit."""
     if value:
@@ -90,33 +147,10 @@ def exec_command(
     ),
 ) -> None:
     """Execute non-interactively with provided input."""
-    from klaude_code.trace import log
-
-    # Set terminal title with current folder name
-    folder_name = os.path.basename(os.getcwd())
-    set_terminal_title(f"{folder_name}: klaude")
-
-    parts: list[str] = []
+    setup_terminal_title()
 
-    # Handle stdin input
-    if not sys.stdin.isatty():
-        try:
-            stdin = sys.stdin.read().rstrip("\n")
-            if stdin:
-                parts.append(stdin)
-        except (OSError, ValueError) as e:
-            # Expected I/O-related errors when reading from stdin (e.g. broken pipe, closed stream).
-            log((f"Error reading from stdin: {e}", "red"))
-        except Exception as e:
-            # Unexpected errors are still reported but kept from crashing the CLI.
-            log((f"Unexpected error reading from stdin: {e}", "red"))
-
-    if input_content:
-        parts.append(input_content)
-
-    input_content = "\n".join(parts)
-    if len(input_content) == 0:
-        log(("Error: No input content provided", "red"))
+    merged_input = read_input_content(input_content)
+    if merged_input is None:
         raise typer.Exit(1)
 
     from klaude_code.cli.runtime import AppInitConfig, run_exec
@@ -133,11 +167,7 @@ def exec_command(
         if chosen_model is None:
             return
 
-    debug_enabled, debug_filters = resolve_debug_settings(debug, debug_filter)
-
-    log_path: Path | None = None
-    if debug_enabled:
-        log_path = prepare_debug_log_file()
+    debug_enabled, debug_filters, log_path = prepare_debug_logging(debug, debug_filter)
 
     init_config = AppInitConfig(
         model=chosen_model,
@@ -154,7 +184,7 @@ def exec_command(
     asyncio.run(
         run_exec(
             init_config=init_config,
-            input_content=input_content,
+            input_content=merged_input,
         )
     )
 
@@ -210,10 +240,8 @@ def main_callback(
         from klaude_code.cli.runtime import AppInitConfig, run_interactive
         from klaude_code.config.select_model import select_model_from_config
 
-        # Set terminal title with current folder name
-        folder_name = os.path.basename(os.getcwd())
-        set_terminal_title(f"{folder_name}: klaude")
-        # Interactive mode
+        setup_terminal_title()
+
         chosen_model = model
         if select_model:
             chosen_model = select_model_from_config(preferred=model)
@@ -232,11 +260,7 @@ def main_callback(
             session_id = Session.most_recent_session_id()
         # If still no session_id, leave as None to create a new session
 
-        debug_enabled, debug_filters = resolve_debug_settings(debug, debug_filter)
-
-        log_path: Path | None = None
-        if debug_enabled:
-            log_path = prepare_debug_log_file()
+        debug_enabled, debug_filters, log_path = prepare_debug_logging(debug, debug_filter)
 
         init_config = AppInitConfig(
             model=chosen_model,

klaude_code/cli/runtime.py

@@ -127,6 +127,28 @@ async def initialize_app_components(init_config: AppInitConfig) -> AppComponents
     )
 
 
+async def initialize_session(
+    executor: Executor,
+    event_queue: asyncio.Queue[events.Event],
+    session_id: str | None = None,
+) -> str | None:
+    """Initialize a session and return the active session ID.
+
+    Args:
+        executor: The executor to submit operations to.
+        event_queue: The event queue for synchronization.
+        session_id: Optional session ID to resume. If None, creates a new session.
+
+    Returns:
+        The active session ID, or None if no session is active.
+    """
+    await executor.submit_and_wait(op.InitAgentOperation(session_id=session_id))
+    await event_queue.join()
+
+    active_session_ids = executor.context.agent_manager.active_session_ids()
+    return active_session_ids[0] if active_session_ids else session_id
+
+
 async def cleanup_app_components(components: AppComponents) -> None:
     """Clean up all application components."""
     try:
@@ -167,13 +189,7 @@ async def run_exec(init_config: AppInitConfig, input_content: str) -> None:
     components = await initialize_app_components(init_config)
 
     try:
-        # Initialize a new session (session_id=None means create new)
-        await components.executor.submit_and_wait(op.InitAgentOperation())
-        await components.event_queue.join()
-
-        # Get the session_id from the newly created agent
-        session_ids = components.executor.context.agent_manager.active_session_ids()
-        session_id = session_ids[0] if session_ids else None
+        session_id = await initialize_session(components.executor, components.event_queue)
 
         # Submit the input content directly
         await components.executor.submit_and_wait(
@@ -245,12 +261,7 @@ async def run_interactive(init_config: AppInitConfig, session_id: str | None = N
     restore_sigint = install_sigint_double_press_exit(_show_toast_once, _hide_progress)
 
     try:
-        await components.executor.submit_and_wait(op.InitAgentOperation(session_id=session_id))
-        await components.event_queue.join()
-
-        # Get the actual session_id (may have been auto-generated if None was passed)
-        active_session_ids = components.executor.context.agent_manager.active_session_ids()
-        active_session_id = active_session_ids[0] if active_session_ids else session_id
+        active_session_id = await initialize_session(components.executor, components.event_queue, session_id=session_id)
 
         # Input
         await input_provider.start()

klaude_code/command/export_cmd.py

@@ -25,7 +25,7 @@ class ExportCommand(CommandABC):
 
     @property
     def support_addition_params(self) -> bool:
-        return True
+        return False
 
     @property
     def is_interactive(self) -> bool:
@@ -33,7 +33,7 @@ class ExportCommand(CommandABC):
 
     async def run(self, raw: str, agent: Agent) -> CommandResult:
         try:
-            output_path = self._resolve_output_path(raw, agent)
+            output_path = self._resolve_output_path("", agent)
             html_doc = self._build_html(agent)
             output_path.parent.mkdir(parents=True, exist_ok=True)
             output_path.write_text(html_doc, encoding="utf-8")

klaude_code/command/prompt-handoff.md

@@ -0,0 +1,33 @@
+---
+description: Write a HANDOFF.md for another agent to continue the conversation
+from: amp-cli https://ampcode.com/manual#handoff
+---
+
+Write a HANDOFF.md file in the current working directory for another agent to continue this conversation.
+
+Extract relevant context from the conversation above to facilitate continuing this work. Write from my perspective (first person: "I did...", "I told you...").
+
+Consider what would be useful to know based on my request below. Relevant questions include:
+- What did I just do or implement?
+- What instructions did I give you that are still relevant (e.g., follow patterns in the codebase)?
+- Did I provide a plan or spec that should be included?
+- What important information did I share (certain libraries, patterns, constraints, preferences)?
+- What key technical details did I discover (APIs, methods, patterns)?
+- What caveats, limitations, or open questions remain?
+
+Extract only what matters for the specific request below. Skip irrelevant questions. Choose an appropriate length based on the complexity of the request.
+
+Focus on capabilities and behavior, not file-by-file changes. Avoid excessive implementation details (variable names, storage keys, constants) unless critical.
+
+Format: Plain text with bullets. No markdown headers, no bold/italic, no code fences. Use workspace-relative paths for files.
+
+List file or directory paths (workspace-relative) relevant to accomplishing the goal in the following format:
+<example>
+@src/project/main.py
+@src/project/llm/
+</example>
+
+My request:
+$ARGUMENTS
+
+<system>If the request section is empty, ask for clarification about the goal</system>

klaude_code/command/thinking_cmd.py

@@ -211,7 +211,11 @@ class ThinkingCommand(CommandABC):
                         content=f"Thinking changed: {current} -> {new_status}",
                         command_output=model.CommandOutput(command_name=self.name),
                     ),
-                )
+                ),
+                events.WelcomeEvent(
+                    work_dir=str(agent.session.work_dir),
+                    llm_config=config,
+                ),
             ]
         )
 

klaude_code/config/config.py

@@ -23,20 +23,20 @@ class Config(BaseModel):
     provider_list: list[llm_param.LLMConfigProviderParameter]
     model_list: list[ModelConfig]
     main_model: str
-    subagent_models: dict[str, str] = Field(default_factory=dict)
+    sub_agent_models: dict[str, str] = Field(default_factory=dict)
     theme: str | None = None
 
     @model_validator(mode="before")
     @classmethod
-    def _normalize_subagent_models(cls, data: dict[str, Any]) -> dict[str, Any]:
-        raw_val: Any = data.get("subagent_models") or {}
+    def _normalize_sub_agent_models(cls, data: dict[str, Any]) -> dict[str, Any]:
+        raw_val: Any = data.get("sub_agent_models") or {}
         raw_models: dict[str, Any] = cast(dict[str, Any], raw_val) if isinstance(raw_val, dict) else {}
         normalized: dict[str, str] = {}
         key_map = {p.name.lower(): p.name for p in iter_sub_agent_profiles()}
         for key, value in dict(raw_models).items():
             canonical = key_map.get(str(key).lower(), str(key))
             normalized[canonical] = str(value)
-        data["subagent_models"] = normalized
+        data["sub_agent_models"] = normalized
         return data
 
     def get_main_model_config(self) -> llm_param.LLMConfigParameter:
@@ -80,7 +80,7 @@ class Config(BaseModel):
 def get_example_config() -> Config:
     return Config(
         main_model="gpt-5.1",
-        subagent_models={"explore": "haiku", "oracle": "gpt-5.1-high"},
+        sub_agent_models={"explore": "haiku", "oracle": "gpt-5.1-high"},
         provider_list=[
             llm_param.LLMConfigProviderParameter(
                 provider_name="openai",

klaude_code/config/list_model.py

@@ -198,7 +198,7 @@ def display_models_and_providers(config: Config):
     )
 
     for profile in iter_sub_agent_profiles():
-        sub_model_name = config.subagent_models.get(profile.name)
+        sub_model_name = config.sub_agent_models.get(profile.name)
         if not sub_model_name:
             continue
         console.print(

klaude_code/const/__init__.py

@@ -105,6 +105,9 @@ UI_REFRESH_RATE_FPS = 20
 # Number of lines to keep visible at bottom of markdown streaming window
 MARKDOWN_STREAM_LIVE_WINDOW = 20
 
+# Status hint text shown after spinner status
+STATUS_HINT_TEXT = " (esc to interrupt)"
+
 # Status shimmer animation
 # Horizontal padding used when computing shimmer band position
 STATUS_SHIMMER_PADDING = 10

klaude_code/core/executor.py

@@ -96,7 +96,7 @@ class ExecutorContext:
         # Delegate responsibilities to helper components
         self.agent_manager = AgentManager(event_queue, llm_clients, resolved_profile_provider)
         self.task_manager = TaskManager()
-        self.subagent_manager = SubAgentManager(event_queue, llm_clients, resolved_profile_provider)
+        self.sub_agent_manager = SubAgentManager(event_queue, llm_clients, resolved_profile_provider)
 
     async def emit_event(self, event: events.Event) -> None:
         """Emit an event to the UI display system."""
@@ -240,7 +240,7 @@ class ExecutorContext:
 
             # Inject subtask runner into tool context for nested Task tool usage
             async def _runner(state: model.SubAgentState) -> SubAgentResult:
-                return await self.subagent_manager.run_subagent(agent, state)
+                return await self.sub_agent_manager.run_sub_agent(agent, state)
 
             token = current_run_subtask_callback.set(_runner)
             try:

klaude_code/core/manager/llm_clients_builder.py

@@ -32,7 +32,7 @@ def build_llm_clients(
     sub_clients: dict[SubAgentType, LLMClientABC] = {}
 
     for profile in iter_sub_agent_profiles():
-        model_name = config.subagent_models.get(profile.name)
+        model_name = config.sub_agent_models.get(profile.name)
         if not model_name:
             continue
 

klaude_code/core/manager/sub_agent_manager.py

@@ -9,8 +9,9 @@ from __future__ import annotations
 
 import asyncio
 
-from klaude_code.core.agent import Agent, ModelProfileProvider
+from klaude_code.core.agent import Agent, AgentProfile, ModelProfileProvider
 from klaude_code.core.manager.llm_clients import LLMClients
+from klaude_code.core.tool import ReportBackTool
 from klaude_code.protocol import events, model
 from klaude_code.protocol.sub_agent import SubAgentResult
 from klaude_code.session.session import Session
@@ -35,7 +36,7 @@ class SubAgentManager:
 
         await self._event_queue.put(event)
 
-    async def run_subagent(self, parent_agent: Agent, state: model.SubAgentState) -> SubAgentResult:
+    async def run_sub_agent(self, parent_agent: Agent, state: model.SubAgentState) -> SubAgentResult:
         """Run a nested sub-agent task and return its result."""
 
         # Create a child session under the same workdir
@@ -47,6 +48,25 @@ class SubAgentManager:
             self._llm_clients.get_client(state.sub_agent_type),
             state.sub_agent_type,
         )
+
+        # Inject report_back tool if output_schema is provided
+        if state.output_schema:
+            report_back_tool_class = ReportBackTool.for_schema(state.output_schema)
+            report_back_prompt = """\
+
+# Structured Output
+You have a `report_back` tool available. When you complete the task,\
+you MUST call `report_back` with the structured result matching the required schema.\
+This will end the task and return the structured data to the caller.
+"""
+            base_prompt = child_profile.system_prompt or ""
+            child_profile = AgentProfile(
+                llm_client=child_profile.llm_client,
+                system_prompt=base_prompt + report_back_prompt,
+                tools=[*child_profile.tools, report_back_tool_class.schema()],
+                reminders=child_profile.reminders,
+            )
+
         child_agent = Agent(session=child_session, profile=child_profile)
 
         log_debug(
@@ -68,23 +88,27 @@ class SubAgentManager:
                 elif isinstance(event, events.TaskMetadataEvent):
                     task_metadata = event.metadata.main
                 await self.emit_event(event)
-            return SubAgentResult(task_result=result, session_id=child_session.id, task_metadata=task_metadata)
+            return SubAgentResult(
+                task_result=result,
+                session_id=child_session.id,
+                task_metadata=task_metadata,
+            )
         except asyncio.CancelledError:
             # Propagate cancellation so tooling can treat it as user interrupt
             log_debug(
-                f"Subagent task for {state.sub_agent_type} was cancelled",
+                f"Sub-agent task for {state.sub_agent_type} was cancelled",
                 style="yellow",
                 debug_type=DebugType.EXECUTION,
             )
             raise
         except Exception as exc:  # pragma: no cover - defensive logging
             log_debug(
-                f"Subagent task failed: [{exc.__class__.__name__}] {exc!s}",
+                f"Sub-agent task failed: [{exc.__class__.__name__}] {exc!s}",
                 style="red",
                 debug_type=DebugType.EXECUTION,
             )
             return SubAgentResult(
-                task_result=f"Subagent task failed: [{exc.__class__.__name__}] {exc!s}",
+                task_result=f"Sub-agent task failed: [{exc.__class__.__name__}] {exc!s}",
                 session_id="",
                 error=True,
             )

klaude_code/core/prompt.py

@@ -5,6 +5,7 @@ from importlib.resources import files
 from pathlib import Path
 
 from klaude_code.protocol import llm_param
+from klaude_code.protocol.sub_agent import get_sub_agent_profile
 
 COMMAND_DESCRIPTIONS: dict[str, str] = {
     "rg": "ripgrep - fast text search",
@@ -19,15 +20,15 @@ PROMPT_FILES: dict[str, str] = {
     "main_gpt_5_1_codex_max": "prompts/prompt-codex-gpt-5-1-codex-max.md",
     "main": "prompts/prompt-claude-code.md",
     "main_gemini": "prompts/prompt-gemini.md",  # https://ai.google.dev/gemini-api/docs/prompting-strategies?hl=zh-cn#agentic-si-template
-    # Sub-agent prompts keyed by their name
-    "Task": "prompts/prompt-subagent.md",
-    "Oracle": "prompts/prompt-subagent-oracle.md",
-    "Explore": "prompts/prompt-subagent-explore.md",
-    "WebFetchAgent": "prompts/prompt-subagent-webfetch.md",
 }
 
 
 @cache
+def _load_prompt_by_path(prompt_path: str) -> str:
+    """Load and cache prompt content from a file path relative to core package."""
+    return files(__package__).joinpath(prompt_path).read_text(encoding="utf-8").strip()
+
+
 def _load_base_prompt(file_key: str) -> str:
     """Load and cache the base prompt content from file."""
     try:
@@ -35,14 +36,11 @@ def _load_base_prompt(file_key: str) -> str:
     except KeyError as exc:
         raise ValueError(f"Unknown prompt key: {file_key}") from exc
 
-    return files(__package__).joinpath(prompt_path).read_text(encoding="utf-8").strip()
+    return _load_prompt_by_path(prompt_path)
 
 
-def _get_file_key(model_name: str, protocol: llm_param.LLMClientProtocol, sub_agent_type: str | None) -> str:
-    """Determine which prompt file to use based on model and agent type."""
-    if sub_agent_type is not None:
-        return sub_agent_type
-
+def _get_file_key(model_name: str, protocol: llm_param.LLMClientProtocol) -> str:
+    """Determine which prompt file to use based on model."""
     match model_name:
         case name if "gpt-5.1-codex-max" in name:
             return "main_gpt_5_1_codex_max"
@@ -90,8 +88,12 @@ def load_system_prompt(
     model_name: str, protocol: llm_param.LLMClientProtocol, sub_agent_type: str | None = None
 ) -> str:
     """Get system prompt content for the given model and sub-agent type."""
-    file_key = _get_file_key(model_name, protocol, sub_agent_type)
-    base_prompt = _load_base_prompt(file_key)
+    if sub_agent_type is not None:
+        profile = get_sub_agent_profile(sub_agent_type)
+        base_prompt = _load_prompt_by_path(profile.prompt_file)
+    else:
+        file_key = _get_file_key(model_name, protocol)
+        base_prompt = _load_base_prompt(file_key)
 
     if protocol == llm_param.LLMClientProtocol.CODEX:
         # Do not append environment info for Codex protocol

klaude_code/core/prompts/{prompt-subagent-explore.md → prompt-sub-agent-explore.md}

@@ -22,7 +22,6 @@ Guidelines:
 
 Complete the user's search request efficiently and report your findings clearly.
 
-
 Notes:
 - Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.
 - In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.

klaude_code/core/prompts/{prompt-subagent-oracle.md → prompt-sub-agent-oracle.md}

@@ -1,7 +1,7 @@
 You are the Oracle - an expert AI advisor with advanced reasoning capabilities
 
 Your role is to provide high-quality technical guidance, code reviews, architectural advice, and strategic planning for software engineering tasks.
-You are running inside an AI coding system in which you act as a subagent that's used when the main agent needs a smarter, more capable model to help out.
+You are running inside an AI coding system in which you act as a sub-agent that's used when the main agent needs a smarter, more capable model to help out.
 
 
 Key responsibilities:

klaude_code/core/reminders.py

@@ -14,7 +14,8 @@ from klaude_code.session import Session
 type Reminder = Callable[[Session], Awaitable[model.DeveloperMessageItem | None]]
 
 
-AT_FILE_PATTERN = re.compile(r'(?<!\S)@("(?P<quoted>[^\"]+)"|(?P<plain>\S+))')
+# Match @ preceded by whitespace, start of line, or → (ReadTool line number arrow)
+AT_FILE_PATTERN = re.compile(r'(?:(?<!\S)|(?<=\u2192))@("(?P<quoted>[^\"]+)"|(?P<plain>\S+))')
 
 
 def get_last_new_user_input(session: Session) -> str | None:
@@ -31,10 +32,74 @@ def get_last_new_user_input(session: Session) -> str | None:
     return "\n\n".join(result)
 
 
+async def _load_at_file_recursive(
+    session: Session,
+    pattern: str,
+    at_files: dict[str, model.AtPatternParseResult],
+    collected_images: list[model.ImageURLPart],
+    visited: set[str],
+    base_dir: Path | None = None,
+    mentioned_in: str | None = None,
+) -> None:
+    """Recursively load @ file references."""
+    path = (base_dir / pattern).resolve() if base_dir else Path(pattern).resolve()
+    path_str = str(path)
+
+    if path_str in visited:
+        return
+    visited.add(path_str)
+
+    context_token = set_tool_context_from_session(session)
+    try:
+        if path.exists() and path.is_file():
+            args = ReadTool.ReadArguments(file_path=path_str)
+            tool_result = await ReadTool.call_with_args(args)
+            at_files[path_str] = model.AtPatternParseResult(
+                path=path_str,
+                tool_name=tools.READ,
+                result=tool_result.output or "",
+                tool_args=args.model_dump_json(exclude_none=True),
+                operation="Read",
+                images=tool_result.images,
+                mentioned_in=mentioned_in,
+            )
+            if tool_result.images:
+                collected_images.extend(tool_result.images)
+
+            # Recursively parse @ references from ReadTool output
+            output = tool_result.output or ""
+            if "@" in output:
+                for match in AT_FILE_PATTERN.finditer(output):
+                    nested = match.group("quoted") or match.group("plain")
+                    if nested:
+                        await _load_at_file_recursive(
+                            session,
+                            nested,
+                            at_files,
+                            collected_images,
+                            visited,
+                            base_dir=path.parent,
+                            mentioned_in=path_str,
+                        )
+        elif path.exists() and path.is_dir():
+            quoted_path = shlex.quote(path_str)
+            args = BashTool.BashArguments(command=f"ls {quoted_path}")
+            tool_result = await BashTool.call_with_args(args)
+            at_files[path_str] = model.AtPatternParseResult(
+                path=path_str + "/",
+                tool_name=tools.BASH,
+                result=tool_result.output or "",
+                tool_args=args.model_dump_json(exclude_none=True),
+                operation="List",
+            )
+    finally:
+        reset_tool_context(context_token)
+
+
 async def at_file_reader_reminder(
     session: Session,
 ) -> model.DeveloperMessageItem | None:
-    """Parse @foo/bar to read"""
+    """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
@@ -53,38 +118,16 @@ async def at_file_reader_reminder(
 
     at_files: dict[str, model.AtPatternParseResult] = {}  # path -> content
     collected_images: list[model.ImageURLPart] = []
+    visited: set[str] = set()
 
     for pattern in at_patterns:
-        path = Path(pattern).resolve()
-        context_token = set_tool_context_from_session(session)
-        try:
-            if path.exists() and path.is_file():
-                args = ReadTool.ReadArguments(file_path=str(path))
-                tool_result = await ReadTool.call_with_args(args)
-                at_result = model.AtPatternParseResult(
-                    path=str(path),
-                    tool_name=tools.READ,
-                    result=tool_result.output or "",
-                    tool_args=args.model_dump_json(exclude_none=True),
-                    operation="Read",
-                    images=tool_result.images,
-                )
-                at_files[str(path)] = at_result
-                if tool_result.images:
-                    collected_images.extend(tool_result.images)
-            elif path.exists() and path.is_dir():
-                quoted_path = shlex.quote(str(path))
-                args = BashTool.BashArguments(command=f"ls {quoted_path}")
-                tool_result = await BashTool.call_with_args(args)
-                at_files[str(path)] = model.AtPatternParseResult(
-                    path=str(path) + "/",
-                    tool_name=tools.BASH,
-                    result=tool_result.output or "",
-                    tool_args=args.model_dump_json(exclude_none=True),
-                    operation="List",
-                )
-        finally:
-            reset_tool_context(context_token)
+        await _load_at_file_recursive(
+            session,
+            pattern,
+            at_files,
+            collected_images,
+            visited,
+        )
 
     if len(at_files) == 0:
         return None