kolega-code 0.26.1__tar.gz → 0.26.3__tar.gz

{kolega_code-0.26.1 → kolega_code-0.26.3}/CHANGELOG.md

@@ -6,6 +6,47 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.26.3 - 2026-08-02
+
+### Added
+
+- `kolega-code ask --no-memory-tools` disables the persistent project-memory
+  tools (read/list/write/edit/delete memory) and their prompt guidance for a
+  run — useful for headless or benchmark use where there is no durable memory
+  store.
+- `search_codebase` accepts `path` to restrict the search to a subdirectory and
+  `max_results` to cap how many files are returned.
+
+### Changed
+
+- `eval` now defaults `language` to `py`, so a call that omits the language runs
+  Python instead of failing.
+- A tool call made with the wrong arguments now returns a clear message naming
+  the expected signature (for example `Usage: eval(code, language='py', …)`) and
+  no longer exposes internal class or method names.
+- "Memory off" now has a single, consistent representation: a non-local host,
+  the new `--no-memory-tools` flag, and the memory toggle all behave the same
+  way, hiding both the memory tools and the memory prompt section.
+- The browser agent's dispatch tool is now hidden when the model configured for
+  the browser agent cannot accept images, instead of failing only when invoked.
+
+## 0.26.2 - 2026-07-31
+
+### Added
+
+- `kolega-code ask --gigacode` enables gigacode workflow orchestration in
+  headless runs, matching the TUI's `/gigacode` toggle: the `run_workflow` and
+  `list_workflow_runs` tools are exposed and the authoring guide is injected.
+  The setting persists with the session, so `ask --session <id>` resumes with
+  gigacode still on.
+
+### Changed
+
+- Gigacode's concurrent-worker cap is now a flat 8 instead of being derived from
+  the host's core count. Workers wait on provider responses rather than CPU, so
+  the old formula only made fan-out width vary with the machine — and collapse to
+  a single serial worker on a one-CPU host or container.
+
 ## 0.26.1 - 2026-07-31
 
 ### Fixed

{kolega_code-0.26.1 → kolega_code-0.26.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.26.1
+Version: 0.26.3
 Summary: Multi-agent coding in the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/__init__.py

@@ -151,4 +151,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.26.1"
+__version__ = "0.26.3"

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/__init__.py

@@ -51,4 +51,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.26.1"
+__version__ = "0.26.3"

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/baseagent.py

@@ -170,6 +170,7 @@ class BaseAgent(LogMixin):
         custom_agent_catalog: Optional[Any] = None,
         memory_manager: Optional[Any] = None,
         memory_project_path: Optional[Path] = None,
+        memory_enabled: bool = True,
     ) -> None:
         """
         Initialize a new BaseAgent instance.
@@ -308,15 +309,21 @@ class BaseAgent(LogMixin):
             from kolega_code.memory import MemoryAccessScope
 
             self.memory_manager = self.memory_manager.with_scope(MemoryAccessScope.SUBAGENT)
-        if self.memory_manager is None and not sub_agent and isinstance(self.filesystem, LocalFileSystem):
-            # Keep non-local/sandbox hosts unchanged unless they inject a manager.
+        elif self.memory_manager is None and not sub_agent:
             from kolega_code.cli.session_store import default_state_dir
             from kolega_code.memory import ProjectMemoryManager
 
-            self.memory_manager = ProjectMemoryManager(
-                memory_project_path if memory_project_path is not None else self.project_path,
-                default_state_dir(),
-            )
+            project = memory_project_path if memory_project_path is not None else self.project_path
+            # "Memory off" has one representation everywhere: a present-but-disabled
+            # manager, never a None. Memory is live only for a local project with the
+            # per-run opt-out unset; a non-local/sandbox host (whose storage would be a
+            # local state dir, disconnected from the remote project) or an explicit
+            # `--no-memory-tools` opt-out gets an inert, storage-inert manager that
+            # writes nothing. Dispatched sub-agents inherit whichever it is.
+            if memory_enabled and isinstance(self.filesystem, LocalFileSystem):
+                self.memory_manager = ProjectMemoryManager(project, default_state_dir())
+            else:
+                self.memory_manager = ProjectMemoryManager.disabled(project, default_state_dir())
             self.context.services.memory_manager = self.memory_manager
             self._owns_memory_manager = True
 

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/browseragent.py

@@ -19,13 +19,30 @@ class BrowserAgent(BaseAgent):
 
     agent_name = "browser-agent"
 
+    @classmethod
+    def resolved_model_supports_vision(cls, config: AgentConfig) -> bool:
+        """True if the model resolved for the browser-agent role accepts image input.
+
+        The browser agent may run on its own ``agent_models`` override, so this is
+        deliberately keyed on the browser-agent's resolved model — not the main
+        coding model, which can differ in either direction.
+        """
+        model_config = config.model_config_for_agent(cls.agent_name)
+        provider = getattr(model_config.provider, "value", model_config.provider)
+        try:
+            return model_supports_vision(provider, model_config.model)
+        except ValueError:
+            # Unknown model → can't confirm image support → treat as no vision.
+            # This runs on every tool-list build, so it must never raise.
+            return False
+
     @classmethod
     def validate_model_capabilities(cls, config: AgentConfig) -> None:
         """Require the resolved browser-agent model to accept image input."""
+        if cls.resolved_model_supports_vision(config):
+            return
         model_config = config.model_config_for_agent(cls.agent_name)
         provider = getattr(model_config.provider, "value", model_config.provider)
-        if model_supports_vision(provider, model_config.model):
-            return
         raise ValueError(
             "BrowserAgent requires a vision-capable model, but "
             f"{provider}/{model_config.model} does not support image input. "

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/coder.py

@@ -53,6 +53,7 @@ class CoderAgent(BaseAgent, LogMixin):
         custom_agent_catalog: Optional[Any] = None,
         memory_manager: Optional[Any] = None,
         memory_project_path: Optional[Path] = None,
+        memory_enabled: bool = True,
     ) -> None:
         """
         Initialize a new CoderAgent instance.
@@ -117,6 +118,7 @@ class CoderAgent(BaseAgent, LogMixin):
             custom_agent_catalog=custom_agent_catalog,
             memory_manager=memory_manager,
             memory_project_path=memory_project_path,
+            memory_enabled=memory_enabled,
         )
 
         # Configure tool collection with custom coder agent tools

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/orchestration/__init__.py

@@ -20,7 +20,7 @@ from .errors import (
 )
 from .executor import DEFAULT_MAX_AGENT_DEPTH, MAX_AGENT_DEPTH, extract_meta, run_script, safe_builtins
 from .journal import ResumeCache, RunJournal, saved_workflows_dir, workflows_root
-from .runtime import DEFAULT_AGENT_CAP, MAX_FANOUT, WorkflowRuntime, default_concurrency
+from .runtime import DEFAULT_AGENT_CAP, DEFAULT_WORKFLOW_CONCURRENCY, MAX_FANOUT, WorkflowRuntime
 from .types import AgentRunResult, AgentRunSpec, DispatchFn, EmitFn
 
 __all__ = [
@@ -39,7 +39,7 @@ __all__ = [
     "workflows_root",
     "saved_workflows_dir",
     "WorkflowRuntime",
-    "default_concurrency",
+    "DEFAULT_WORKFLOW_CONCURRENCY",
     "MAX_FANOUT",
     "DEFAULT_AGENT_CAP",
     "AgentRunSpec",

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/orchestration/guide.py

@@ -5,6 +5,8 @@ it in sync with the primitives in :mod:`runtime` and the tool in
 ``tool_backend/workflow_tool.py``.
 """
 
+from ..prompt_provider import PromptExtension
+
 GIGACODE_AUTHORING_GUIDE = """\
 ## gigacode — dynamic workflow orchestration
 
@@ -299,3 +301,21 @@ id as `resume_from_run_id` — every agent call it completed replays from the jo
 no cost. `list_workflow_runs` shows only this session's runs; a run still listed as
 "running" when no workflow is in flight died mid-run and is resumable the same way.
 """
+
+
+def gigacode_prompt_extension() -> PromptExtension:
+    """The authoring guide as a prompt extension, for every frontend that enables gigacode.
+
+    The TUI's ``/gigacode`` toggle and ``kolega-code ask --gigacode`` share this
+    so a headless run sees exactly the guidance an interactive session does.
+    """
+    return PromptExtension(
+        id="gigacode",
+        title="gigacode — workflow orchestration",
+        markdown=GIGACODE_AUTHORING_GUIDE,
+        agent_types=None,
+        modes=None,
+        # Sub-agents can't run workflows (run_workflow is gated off for them),
+        # so the authoring guide is just prompt bloat for a sub-agent.
+        propagate_to_sub_agents=False,
+    )

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/orchestration/runtime.py

@@ -13,7 +13,6 @@ from __future__ import annotations
 
 import asyncio
 import inspect
-import os
 import random
 from typing import Any, Awaitable, Callable, Dict, Iterable, List, Optional
 
@@ -43,14 +42,12 @@ DROPPED_ITEM_LOG_LIMIT = 10
 START_STAGGER_SECONDS = 0.75
 
 
-def default_concurrency() -> int:
-    """Concurrent-agent cap: a few below the core count, clamped to [1, 8].
-
-    Kept modest so a fan-out doesn't burst enough simultaneous LLM requests to trip
-    account-level rate limits; the jittered start-stagger further de-correlates them.
-    """
-    cpus = os.cpu_count() or 4
-    return max(1, min(8, cpus - 2))
+# Concurrent-agent cap for one workflow. A worker spends nearly all its wall-clock
+# waiting on a provider response, so the binding constraint is the account's rate
+# limit, not the host's core count — deriving this from cores only made the fan-out
+# width vary arbitrarily with the machine (and collapse to 1 in a single-CPU
+# container). The jittered start-stagger de-correlates the burst on top of this cap.
+DEFAULT_WORKFLOW_CONCURRENCY = 8
 
 
 def _call_with_arity(fn: Callable[..., Any], *args: Any) -> Any:
@@ -97,7 +94,7 @@ class WorkflowRuntime:
         if self._accounting.budget is not budget:
             raise ValueError("workflow accounting must own the runtime budget")
         self.budget = self._accounting.budget
-        self._sem = asyncio.Semaphore(concurrency or default_concurrency())
+        self._sem = asyncio.Semaphore(concurrency or DEFAULT_WORKFLOW_CONCURRENCY)
         self._max_agent_depth = max_agent_depth
         self._resolver = workflow_resolver
         self._routing_fingerprint = routing_fingerprint

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/planningagent.py

@@ -47,6 +47,7 @@ class PlanningAgent(BaseAgent):
         max_iterations: Optional[int] = None,
         custom_agent_catalog: Optional[Any] = None,
         memory_manager: Optional[Any] = None,
+        memory_enabled: bool = True,
     ) -> None:
         if custom_agent_catalog is not None:
             custom_agent_catalog = custom_agent_catalog.for_mode("plan")
@@ -81,6 +82,7 @@ class PlanningAgent(BaseAgent):
             max_iterations=max_iterations,
             custom_agent_catalog=custom_agent_catalog,
             memory_manager=memory_manager,
+            memory_enabled=memory_enabled,
         )
 
         self._completed_plan: Optional[str] = None

{kolega_code-0.26.1 → kolega_code-0.26.3}/kolega_code/agent/tool_backend/search_codebase_tool.py

@@ -22,6 +22,8 @@ _RC_MARKER = "__KOLEGA_RG_RC"
 
 # Display caps (shared by every engine via the single formatter).
 _MAX_FILES = 128
+# Ceiling for a caller-supplied ``max_results`` so a huge request can't flood context.
+_MAX_FILES_CEILING = 512
 _MAX_LINES_PER_FILE = 5
 _MAX_LINE_LENGTH = 200
 _MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
@@ -46,6 +48,10 @@ class _EngineUnavailable(Exception):
     flag, non-regex error) so the caller falls back to the next engine tier."""
 
 
+class _InvalidSearchPath(Exception):
+    """A caller-supplied ``path`` that escapes the project or isn't a directory."""
+
+
 class _SearchTimedOut(Exception):
     """Raised when an otherwise valid search exceeds its execution budget."""
 
@@ -147,6 +153,31 @@ class SearchCodebaseTool(BaseTool):
             excluded.update(_BROAD_ROOT_EXCLUDE_DIRS)
         return excluded
 
+    def _resolve_search_target(self, path: Optional[str]) -> str:
+        """Validate a caller-supplied ``path`` and return a project-relative search
+        root (``.`` for the whole project). Rejects absolute paths, parent escapes,
+        and non-directories so the search can never wander outside the project."""
+        if not path or path.strip() in ("", ".", "./"):
+            return "."
+        candidate = Path(path.strip())
+        if candidate.is_absolute() or ".." in candidate.parts:
+            raise _InvalidSearchPath(f"path must be a relative directory inside the project, got '{path}'")
+        rel = candidate.as_posix().strip("/")
+        if not rel:
+            return "."
+        try:
+            exists = self.filesystem.exists(rel)
+            is_dir = exists and self.filesystem.is_dir(rel)
+        except Exception:
+            # If the filesystem can't answer (e.g. an exotic sandbox), let the
+            # engine handle the path rather than blocking a legitimate search.
+            return rel
+        if not exists:
+            raise _InvalidSearchPath(f"path '{path}' was not found in the project")
+        if not is_dir:
+            raise _InvalidSearchPath(f"path '{path}' is not a directory; use file_pattern to filter files")
+        return rel
+
     async def search_codebase(
         self,
         pattern: str,
@@ -154,6 +185,8 @@ class SearchCodebaseTool(BaseTool):
         case_sensitive: bool = False,
         literal: bool = False,
         *,
+        path: Optional[str] = None,
+        max_results: int = _MAX_FILES,
         line_formatter: Optional[Callable[[int, str], str]] = None,
     ) -> str:
         """
@@ -170,9 +203,11 @@ class SearchCodebaseTool(BaseTool):
             file_pattern: Optional glob to filter which files to search (default: all files)
             case_sensitive: Whether the search is case-sensitive (default: False)
             literal: Treat the pattern as plain text instead of a regular expression (default: False)
+            path: Optional directory (relative to the project root) to restrict the search to; searches the whole project when omitted
+            max_results: Maximum number of matching files to return (default 128, capped at 512)
 
         Returns:
-            Markdown formatted list of files and matches, limited to 128 results
+            Markdown formatted list of files and matches, capped at ``max_results`` files
 
         Raises:
             Exception: If any error occurs during the search operation
@@ -198,10 +233,16 @@ class SearchCodebaseTool(BaseTool):
                 await self.log_error(error_msg, sender=self.caller.agent_name)
                 return f"Error: {error_msg}"
 
+            limit = max(1, min(int(max_results), _MAX_FILES_CEILING))
+            try:
+                search_target = self._resolve_search_target(path)
+            except _InvalidSearchPath as exc:
+                return f"Error: {exc}"
+
             # Run the first available engine; fall back down the tiers on failure.
             for runner in await self._engine_chain():
                 try:
-                    run = await runner(pattern, file_pattern, case_sensitive, literal, regex)
+                    run = await runner(pattern, file_pattern, case_sensitive, literal, regex, search_target, limit)
                 except _EngineUnavailable:
                     continue
                 except _SearchTimedOut:
@@ -213,7 +254,7 @@ class SearchCodebaseTool(BaseTool):
                         f"elapsed={run.elapsed_seconds:.2f}s)",
                         sender=self.caller.agent_name,
                     )
-                return self._format_results(run, pattern, line_formatter=line_formatter)
+                return self._format_results(run, pattern, limit=limit, line_formatter=line_formatter)
 
             # The Python tier never raises _EngineUnavailable, so this is unreachable.
             return f"No matches found for pattern '{pattern}'"
@@ -266,7 +307,9 @@ class SearchCodebaseTool(BaseTool):
     # ripgrep engine
     # ------------------------------------------------------------------
 
-    def _rg_args(self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool) -> List[str]:
+    def _rg_args(
+        self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool, search_target: str = "."
+    ) -> List[str]:
         args = [
             "--json",
             "--no-config",
@@ -297,17 +340,25 @@ class SearchCodebaseTool(BaseTool):
         if file_pattern != "*":
             glob = file_pattern if "/" not in file_pattern else f"**/{file_pattern}"
             args += ["-g", glob]
-        # Pattern as its own argv element (after -e) and an explicit search path so
-        # ripgrep never reads stdin in a headless context.
-        args += ["-e", pattern, "."]
+        # Pattern as its own argv element (after -e) and an explicit search path
+        # (the whole tree, or the caller's ``path`` subtree) so ripgrep never reads
+        # stdin in a headless context.
+        args += ["-e", pattern, search_target]
         return args
 
     async def _run_rg_local(
-        self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool, regex
+        self,
+        pattern: str,
+        file_pattern: str,
+        case_sensitive: bool,
+        literal: bool,
+        regex,
+        search_target: str = ".",
+        limit: int = _MAX_FILES,
     ) -> SearchRun:
         if shutil.which("rg") is None:
             raise _EngineUnavailable()
-        args = self._rg_args(pattern, file_pattern, case_sensitive, literal)
+        args = self._rg_args(pattern, file_pattern, case_sensitive, literal, search_target)
         env = {**os.environ, "RIPGREP_CONFIG_FILE": ""}
         try:
             proc = await asyncio.create_subprocess_exec(
@@ -329,9 +380,16 @@ class SearchCodebaseTool(BaseTool):
         return SearchRun(self._parse_rg_json(stdout.decode("utf-8", "replace")))
 
     async def _run_rg_sandbox(
-        self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool, regex
+        self,
+        pattern: str,
+        file_pattern: str,
+        case_sensitive: bool,
+        literal: bool,
+        regex,
+        search_target: str = ".",
+        limit: int = _MAX_FILES,
     ) -> SearchRun:
-        args = self._rg_args(pattern, file_pattern, case_sensitive, literal)
+        args = self._rg_args(pattern, file_pattern, case_sensitive, literal, search_target)
         cmd = "RIPGREP_CONFIG_FILE= rg " + " ".join(shlex.quote(a) for a in args)
         full_cmd = f"cd {shlex.quote(self._fs_root)} && {cmd} ; echo {_RC_MARKER}=$?"
         try:
@@ -390,7 +448,9 @@ class SearchCodebaseTool(BaseTool):
     # grep engine
     # ------------------------------------------------------------------
 
-    def _grep_argv(self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool) -> List[str]:
+    def _grep_argv(
+        self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool, search_target: str = "."
+    ) -> List[str]:
         argv = ["grep", "-r", "-n", "--binary-files=without-match"]
         if not case_sensitive:
             argv.append("-i")
@@ -403,16 +463,24 @@ class SearchCodebaseTool(BaseTool):
             argv.append("--exclude-dir=.*")
         for ext in sorted(self.BINARY_EXTENSIONS):
             argv.append(f"--exclude=*{ext}")
-        # -e guards a pattern that starts with '-'; '.' is the search root.
-        argv += ["-e", pattern, "."]
+        # -e guards a pattern that starts with '-'; search_target is the search
+        # root (the whole tree, or the caller's ``path`` subtree).
+        argv += ["-e", pattern, search_target]
         return argv
 
     async def _run_grep_local(
-        self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool, regex
+        self,
+        pattern: str,
+        file_pattern: str,
+        case_sensitive: bool,
+        literal: bool,
+        regex,
+        search_target: str = ".",
+        limit: int = _MAX_FILES,
     ) -> SearchRun:
         if shutil.which("grep") is None:
             raise _EngineUnavailable()
-        argv = self._grep_argv(pattern, file_pattern, case_sensitive, literal)
+        argv = self._grep_argv(pattern, file_pattern, case_sensitive, literal, search_target)
         try:
             proc = await asyncio.create_subprocess_exec(
                 *argv,
@@ -431,9 +499,16 @@ class SearchCodebaseTool(BaseTool):
         return SearchRun(self._drop_oversize_local(records))
 
     async def _run_grep_sandbox(
-        self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool, regex
+        self,
+        pattern: str,
+        file_pattern: str,
+        case_sensitive: bool,
+        literal: bool,
+        regex,
+        search_target: str = ".",
+        limit: int = _MAX_FILES,
     ) -> SearchRun:
-        argv = self._grep_argv(pattern, file_pattern, case_sensitive, literal)
+        argv = self._grep_argv(pattern, file_pattern, case_sensitive, literal, search_target)
         cmd = " ".join(shlex.quote(a) for a in argv)
         full_cmd = f"cd {shlex.quote(self._fs_root)} && {cmd} ; echo {_RC_MARKER}=$?"
         try:
@@ -524,15 +599,23 @@ class SearchCodebaseTool(BaseTool):
     # ------------------------------------------------------------------
 
     async def _run_python(
-        self, pattern: str, file_pattern: str, case_sensitive: bool, literal: bool, regex
+        self,
+        pattern: str,
+        file_pattern: str,
+        case_sensitive: bool,
+        literal: bool,
+        regex,
+        search_target: str = ".",
+        limit: int = _MAX_FILES,
     ) -> SearchRun:
         if hasattr(self.filesystem, "sandbox"):
-            return await self._run_python_sandbox_fallback(file_pattern, regex)
+            return await self._run_python_sandbox_fallback(file_pattern, regex, search_target, limit)
 
         normalized_pattern = "**/*" if file_pattern == "*" else f"**/{file_pattern}"
         self._load_gitignore_patterns()
+        scan_root = Path(self._fs_root) if search_target == "." else Path(self._fs_root) / search_target
         scan = await scan_workspace(
-            Path(self._fs_root),
+            scan_root,
             pattern=normalized_pattern,
             include_files=True,
             include_directories=False,
@@ -543,9 +626,9 @@ class SearchCodebaseTool(BaseTool):
             ignore_spec=getattr(self, "_gitignore_spec", None),
             limits=ScanLimits(timeout_seconds=_SCAN_TIMEOUT_SECONDS, max_entries=_SCAN_MAX_ENTRIES),
         )
-        return await self._search_scanned_files(scan, regex)
+        return await self._search_scanned_files(scan, regex, limit)
 
-    async def _search_scanned_files(self, scan: ScanOutcome, regex) -> SearchRun:
+    async def _search_scanned_files(self, scan: ScanOutcome, regex, limit: int = _MAX_FILES) -> SearchRun:
         cancel_event = threading.Event()
         started = time.monotonic()
         remaining = max(0.01, _SEARCH_TIMEOUT_SECONDS - scan.elapsed_seconds)
@@ -570,7 +653,7 @@ class SearchCodebaseTool(BaseTool):
                     if regex.search(line):
                         records.append((norm, line_num, line))
                         matched_files.add(norm)
-                if len(matched_files) > _MAX_FILES:
+                if len(matched_files) > limit:
                     return SearchRun(
                         records,
                         False,
@@ -598,28 +681,37 @@ class SearchCodebaseTool(BaseTool):
             task.cancel()
             return SearchRun([], False, "deadline", scan.visited_entries, _SEARCH_TIMEOUT_SECONDS)
 
-    async def _run_python_sandbox_fallback(self, file_pattern: str, regex) -> SearchRun:
+    async def _run_python_sandbox_fallback(
+        self, file_pattern: str, regex, search_target: str = ".", limit: int = _MAX_FILES
+    ) -> SearchRun:
         """Keep the legacy remote-files fallback off-loop and time bounded."""
         cancel_event = threading.Event()
         started = time.monotonic()
+        prefix = "" if search_target == "." else search_target.rstrip("/") + "/"
 
         def search() -> SearchRun:
             records: List[Record] = []
+            matched_files: set[str] = set()
             for file_path, file_size in self._get_files_batch_sync(file_pattern):
                 if cancel_event.is_set() or time.monotonic() - started >= _SEARCH_TIMEOUT_SECONDS:
                     return SearchRun(records, False, "deadline", elapsed_seconds=time.monotonic() - started)
                 if file_size > _MAX_FILE_SIZE or self._is_likely_binary_by_extension(file_path):
                     continue
+                norm = self._normalize_path(file_path)
+                if prefix and not norm.startswith(prefix):
+                    continue
                 try:
                     content = self.filesystem.read_text(file_path)
                     if "\x00" in content[:1024]:
                         continue
                 except Exception:
                     continue
-                norm = self._normalize_path(file_path)
                 for line_num, line in enumerate(content.splitlines(), start=1):
                     if regex.search(line):
                         records.append((norm, line_num, line))
+                        matched_files.add(norm)
+                if len(matched_files) > limit:
+                    return SearchRun(records, False, "result_limit", elapsed_seconds=time.monotonic() - started)
             return SearchRun(records, elapsed_seconds=time.monotonic() - started)
 
         task = asyncio.create_task(asyncio.to_thread(search))
@@ -643,6 +735,7 @@ class SearchCodebaseTool(BaseTool):
         run: SearchRun,
         original_pattern: str,
         *,
+        limit: int = _MAX_FILES,
         line_formatter: Optional[Callable[[int, str], str]] = None,
     ) -> str:
         """Group records by file (first-seen order), apply the display caps, and
@@ -652,7 +745,7 @@ class SearchCodebaseTool(BaseTool):
         for path, line_num, raw in run.records:
             if path in files:
                 files[path].append((line_num, raw))
-            elif len(files) < _MAX_FILES:
+            elif len(files) < limit:
                 files[path] = [(line_num, raw)]
             else:
                 limit_hit = True
@@ -690,9 +783,7 @@ class SearchCodebaseTool(BaseTool):
 
         output = f"# Search Results for '{original_pattern}'\n\n"
         if limit_hit or run.stop_reason == "result_limit":
-            output += (
-                f"⚠️ **Note:** Showing only the first {_MAX_FILES} results. There are more matches in the codebase.\n\n"
-            )
+            output += f"⚠️ **Note:** Showing only the first {limit} results. There are more matches in the codebase.\n\n"
         elif not run.complete:
             output += (
                 f"⚠️ **Incomplete search:** stopped because of {run.stop_reason or 'a search limit'}. "