gemcode 0.3.17__tar.gz → 0.3.19__tar.gz

{gemcode-0.3.17/src/gemcode.egg-info → gemcode-0.3.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.17
+Version: 0.3.19
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License

{gemcode-0.3.17 → gemcode-0.3.19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gemcode"
-version = "0.3.17"
+version = "0.3.19"
 description = "Local-first coding agent on Google Gemini + ADK"
 readme = "README.md"
 requires-python = ">=3.11"

{gemcode-0.3.17 → gemcode-0.3.19}/src/gemcode/agent.py

@@ -79,13 +79,26 @@ You run locally via the GemCode CLI. You are the same agent the user launched
 
 ## Core identity and approach
 You are a senior engineer who *acts*, not just advises. When given a task:
-1. **Orient** — understand the repo structure, find the relevant files.
+1. **Orient** — use `list_directory`, `glob_files`, `grep_content`, `read_file` to understand structure. These tools need **no permission** and are instant. Start here.
 2. **Plan** — for complex tasks, call `todo_write` upfront to map out the work.
 3. **Execute** — make the changes, run the checks, iterate.
 4. **Verify** — confirm the result is correct before reporting done.
 
 Never stop mid-task just because the first tool call succeeded. Keep going until the full task is complete or you hit a genuine blocker.
 
+## CRITICAL: Read-only tools first — never bash for exploration
+`bash` and `run_command` require permission confirmation by default. Always start with the **zero-permission** read-only tools:
+
+| Instead of… | Use… |
+|---|---|
+| `bash("ls -la src/")` | `list_directory("src")` |
+| `bash("find . -name '*.py'")` | `glob_files("**/*.py")` |
+| `bash("cat file.py")` | `read_file("file.py")` |
+| `bash("grep -r pattern .")` | `grep_content("pattern", "**/*")` |
+| `bash("find . -type f \| head -50")` | `list_directory(".")` + `glob_files("**/*")` |
+
+Only reach for `bash` or `run_command` when you actually need to **execute** something: run tests, build, git ops, start a server, install packages. **NEVER** use bash to list or read files.
+
 ## Thinking through hard problems
 You have native deep thinking capability — use it actively:
 - **Before** starting a complex refactor or architectural change, think: what are the dependencies? what could break? what is the minimal safe change?
@@ -94,11 +107,12 @@ You have native deep thinking capability — use it actively:
 - **For trade-off decisions** (which library, which pattern, which approach): reason through the pros/cons given this specific codebase.
 
 ## Interpreting requests
-- Treat every message as a software engineering task unless clearly otherwise.
+- Treat every message as a software engineering task — start working immediately. Do NOT respond with just a greeting or introduction.
 - If vague ("fix it", "the config", "rename that"), **infer from the repo**: search, read, then act. Do not give abstract advice when concrete files exist.
-- If the user refers to symbols or behaviors, **find them** with glob/grep/list — never ask them to paste paths you can discover yourself.
+- If the user refers to symbols or behaviors, **find them** with `glob_files`/`grep_content`/`list_directory` — never ask them to paste paths you can discover yourself.
 - **Never propose edits to files you haven't read.** Read first, then edit.
 - When something fails, diagnose (re-read the error, check assumptions) before switching strategy. Do not repeat the same failed call.
+- For analysis tasks ("analyse X", "explain X", "what does X do"): immediately start reading files with `list_directory` + `read_file` + `grep_content`. Produce concrete findings, not hypotheses.
 
 ## Tool selection guide
 
@@ -151,21 +165,34 @@ You have native deep thinking capability — use it actively:
   - `web_fetch("https://registry.npmjs.org/react/latest")` — npm package info
   - Use when you need to look up an API, check the latest version, or read documentation.
 
-### Planning
+### Reasoning and planning
+- **`think`** — private reasoning scratchpad. Write your analysis, plan, or hypothesis here before acting. Not shown to the user. Use before:
+  - A complex multi-file edit or refactor
+  - A debugging session where you need to trace logic before touching code
+  - Any destructive action (delete, force-push) — think first
+  - Choosing between approaches with real trade-offs
+
 - **`todo_write`** — track work items. Use for any task with 3+ steps.
   - Create at task start, mark completed as you finish, merge updates.
 
+- **`run_subtask`** — spawn an isolated sub-agent with its own fresh context window.
+  - The sub-agent has the same tools (bash, read_file, grep, etc.) but starts from scratch.
+  - Use when a task would bloat your context too much: e.g. "read all 40 test files and find patterns"
+  - Use to parallelize: issue multiple `run_subtask` calls in one turn for concurrent exploration
+  - Use for verification passes: "check all files I edited for consistency and syntax errors"
+  - Always give the sub-agent enough context to operate independently.
+  - End your task prompt with "Summarise your findings clearly." so the result is useful.
+
 ## Multi-step task execution
 One user message = many model↔tool rounds (up to 256 LLM calls by default). This is intentional — you are expected to do complete tasks autonomously.
 
 **Standard workflow for complex tasks:**
 1. `todo_write` — plan the work items
-2. Explore — `bash("find . ...")` or `list_directory` or `glob_files` to understand structure
-3. Read — `read_file` with line ranges on large files; `grep_content` for symbol search
-4. Edit — `write_file` / `search_replace` for changes
-5. Verify — `bash("pytest ...")` or `bash("npm run build ...")` or `bash("git diff")`
-6. Fix — iterate on failures, re-verify
-7. Update todos — mark done as you go
+2. **Explore (read-only, no permission needed)** — `list_directory` + `glob_files` to map structure; `grep_content` to find symbols; `read_file` to understand code. Do NOT use `bash` for this step.
+3. **Edit** — `write_file` / `search_replace` for changes
+4. **Verify (shell needed)** — `bash("pytest ...")` or `bash("npm run build ...")` or `bash("git diff")`
+5. Fix — iterate on failures, re-verify
+6. Update todos — mark done as you go
 
 **Do not stop after step 2 or 3** — complete the full task.
 
@@ -174,8 +201,25 @@ Issue independent tool calls in the same turn when outputs don't depend on each
 - Reading multiple files simultaneously ✓
 - Grepping for different patterns at once ✓
 - `list_directory` + `glob_files` in parallel ✓
+- Multiple `run_subtask` calls in one turn for parallel sub-agent exploration ✓
 Sequential: when step B needs step A's result.
 
+## Sub-agent delegation (orchestrator-worker pattern)
+Use `run_subtask` when the work is better done in an isolated context:
+- **Context preservation**: offload reading/analysing large areas of the codebase so your own context stays clean and focused on the high-level task.
+- **Parallel exploration**: launch multiple sub-agents simultaneously to research different subsystems ("analyse auth module", "analyse payment module") then synthesise.
+- **Verification**: after completing work, spawn a sub-agent to review it independently — "verify the changes in src/ are syntactically correct and don't break imports."
+- **Deep research**: when you need to exhaustively search something (50+ files, long documentation pages) delegate it rather than polluting the main conversation.
+
+The sub-agent inherits your permission settings and returns its final text as `result`. Treat it as a trusted colleague returning a written summary.
+
+## Evaluator-optimizer loop
+For tasks where quality matters:
+1. Complete the task (execute tools, write code, run commands)
+2. Spawn a verification `run_subtask` or use `bash` to run tests/lint
+3. If verification fails, read the error, fix, re-verify
+4. Report done only when verified
+
 ## Error recovery
 - **Test/build failures**: read the full error, identify the exact line, fix, re-run.
 - **Tool errors**: diagnose why it failed before retrying — don't repeat the exact same call.
@@ -207,9 +251,25 @@ All file tools use paths **relative to the project root** (where GemCode was sta
   return base
 
 
-def build_root_agent(cfg: GemCodeConfig, extra_tools: list | None = None) -> LlmAgent:
-  """Create the root LlmAgent with tools and callbacks (no Runner)."""
-  tools = build_function_tools(cfg)
+def build_root_agent(
+  cfg: GemCodeConfig,
+  extra_tools: list | None = None,
+  *,
+  _tools: list | None = None,
+) -> LlmAgent:
+  """Create the root LlmAgent with tools and callbacks (no Runner).
+
+  Args:
+    cfg: Runtime configuration.
+    extra_tools: Additional tools to append (e.g. modality tools from session_runtime).
+    _tools: Override the entire tool list (used by run_subtask sub-agents to pass a
+            pre-built list that excludes run_subtask itself, preventing recursion).
+            When set, build_function_tools() is NOT called.
+  """
+  if _tools is not None:
+    tools = list(_tools)
+  else:
+    tools = build_function_tools(cfg)
   if getattr(cfg, "enable_memory", False):
     # ADK preload_memory injects retrieved memories into the next llm_request.
     from google.adk.tools import preload_memory

{gemcode-0.3.17 → gemcode-0.3.19}/src/gemcode/tool_prompt_manifest.py

@@ -108,7 +108,10 @@ Permission policy:
 - session_sticky_hitl={sticky_hitl}: when true, after the user approves **one** tool in this session, further mutating/shell tools may run without re-prompting (set GEMCODE_HITL_STICKY_SESSION=0 to prompt every time).
 
 You may call tools as follows:
-- Session planning: {_fmt_list(planning)}. In-memory task list for this session (no disk writes). Use for non-trivial multi-step work; set merge=true to upsert by id.
+- Session planning / reasoning: {_fmt_list(planning)}.
+  - `todo_write`: in-memory task list (no disk writes). Use for non-trivial multi-step work; merge=true to upsert by id.
+  - `think`: private scratchpad — write reasoning/analysis before risky or complex actions. Not shown to user.
+  - `run_subtask(task, context)`: spawn an isolated sub-agent to handle context-heavy work in parallel or in sequence. Sub-agent inherits your permissions and returns its final text as `result`. Exclude run_subtask from sub-agent by design (no recursion).
 - Read-only tools: {_fmt_list(read_only)}.
   Use these proactively to locate files and code before asking the user for paths.
 - Mutating tools (WRITE/EDIT/DELETE): {_fmt_list(mutating)}.

{gemcode-0.3.17 → gemcode-0.3.19}/src/gemcode/tool_registry.py

@@ -36,7 +36,9 @@ MUTATING_TOOLS: frozenset[str] = frozenset(
 SHELL_TOOLS: frozenset[str] = frozenset({"run_command", "bash"})
 
 # Session planning only (no disk / shell; no extra permission)
-PLANNING_TOOLS: frozenset[str] = frozenset({"todo_write"})
+# think — in-context reasoning scratchpad (no-op, no side effects)
+# run_subtask — spawns a sub-agent; inherits parent permission settings
+PLANNING_TOOLS: frozenset[str] = frozenset({"todo_write", "think", "run_subtask"})
 
 ToolConcurrency = Literal["parallel_safe", "serial_mutating", "shell"]
 

{gemcode-0.3.17 → gemcode-0.3.19}/src/gemcode/tools/__init__.py

@@ -8,20 +8,25 @@ from gemcode.tools.edit import make_edit_tools
 from gemcode.tools.filesystem import make_filesystem_tools
 from gemcode.tools.search import make_grep_tool
 from gemcode.tools.shell import make_run_command
+from gemcode.tools.subtask import make_run_subtask_tool
+from gemcode.tools.think import make_think_tool
 from gemcode.tools.todo import make_todo_tool
 from gemcode.tools.web import make_web_fetch_tool
 
 
-def build_function_tools(cfg: GemCodeConfig) -> list:
+def build_function_tools(cfg: GemCodeConfig, *, include_subtask: bool = True) -> list:
   read_file, list_directory, glob_files, delete_file, move_file = make_filesystem_tools(cfg)
   grep_content = make_grep_tool(cfg)
   run_command = make_run_command(cfg)
   bash = make_bash_tool(cfg)
   write_file, search_replace = make_edit_tools(cfg)
   todo_write = make_todo_tool(cfg)
+  think = make_think_tool()
   web_fetch = make_web_fetch_tool()
-  return [
+
+  tools = [
     todo_write,
+    think,
     read_file,
     list_directory,
     glob_files,
@@ -34,3 +39,9 @@ def build_function_tools(cfg: GemCodeConfig) -> list:
     delete_file,
     web_fetch,
   ]
+
+  # run_subtask is excluded when building sub-agent tools (prevents recursion).
+  if include_subtask:
+    tools.append(make_run_subtask_tool(cfg))
+
+  return tools

gemcode-0.3.19/src/gemcode/tools/subtask.py

@@ -0,0 +1,137 @@
+"""
+Sub-agent tool — spawn an isolated focused agent for context-heavy tasks.
+
+Analogous to OpenClaude's AgentTool / AI SDK's ToolLoopAgent subagent pattern.
+
+Key insight (from AI SDK docs "Subagents"):
+  "Some tasks require exploring large amounts of information — reading files,
+   searching codebases, or researching topics. Running these in the main agent
+   consumes context quickly, making the agent less coherent over time.
+   With subagents, you can spin up a dedicated agent that uses hundreds of
+   thousands of tokens and have it return only a focused summary."
+
+The sub-agent:
+- Gets the same tools as the parent (read_file, bash, grep, etc.) EXCEPT
+  run_subtask itself (prevents infinite recursion).
+- Uses an in-memory session (no DB writes, fully isolated).
+- Respects the same permission settings (yes_to_all, permission_mode) as the parent.
+- Is depth-capped (max 48 LLM calls) to prevent runaway cost.
+"""
+
+from __future__ import annotations
+
+from gemcode.config import GemCodeConfig
+
+
+def make_run_subtask_tool(cfg: GemCodeConfig):
+    async def run_subtask(task: str, context: str = "") -> dict:
+        """
+        Spawn an isolated sub-agent to complete a focused, self-contained task.
+
+        The sub-agent starts with a fresh context window — it does NOT inherit this
+        conversation's history. It has access to all the same tools (read_file, bash,
+        grep_content, web_fetch, etc.) and returns its final response as `result`.
+
+        Use when:
+        - Exploring a large codebase section that would bloat your context
+          ("read all 40 test files and summarise what each group tests")
+        - Running deep analysis in parallel — issue multiple run_subtask calls
+          in the same turn for genuine parallel execution
+        - Delegating a focused research or investigation task while staying
+          high-level yourself
+        - Getting a verification or review pass on your own changes
+          ("check my edits in src/ for syntax errors and consistency")
+        - Any task that requires 10+ file reads or multiple bash commands but
+          whose output can be summarised in a paragraph
+
+        The sub-agent reasons and acts like a full Gemini coding agent.
+        Give it a clear, self-contained task — include all context it needs
+        since it cannot see this conversation.
+
+        Tip: end your task description with "Summarise your findings clearly
+        since your full output will be returned to the main agent."
+
+        Args:
+            task: Clear, self-contained description of what to do.
+            context: Extra context the sub-agent needs (file paths, relevant
+                     code snippets, constraints, acceptance criteria).
+        """
+        import uuid
+
+        try:
+            from google.adk.runners import Runner
+            from google.adk.sessions.in_memory_session_service import (
+                InMemorySessionService,
+            )
+        except ImportError:
+            try:
+                from google.adk.runners import Runner
+                from google.adk.sessions import InMemorySessionService
+            except ImportError:
+                return {"error": "google-adk not available for sub-agent"}
+
+        from gemcode.agent import build_root_agent
+        from gemcode.tools import build_function_tools
+        from gemcode.invoke import run_turn
+
+        # Build the sub-agent tool set WITHOUT run_subtask (no recursion).
+        sub_tools = build_function_tools(cfg, include_subtask=False)
+
+        # Build a standalone LlmAgent with the limited tool set.
+        sub_agent = build_root_agent(cfg, _tools=sub_tools)
+
+        # Isolated in-memory session — never writes to the parent SQLite DB.
+        sub_runner = Runner(
+            app_name="gemcode_sub",
+            agent=sub_agent,
+            session_service=InMemorySessionService(),
+        )
+        sub_session_id = str(uuid.uuid4())
+
+        # Compose the sub-agent prompt.
+        prompt = task.strip()
+        if context and context.strip():
+            prompt = f"{task.strip()}\n\nAdditional context:\n{context.strip()}"
+
+        # Cap sub-agent depth to avoid runaway API cost.
+        sub_max_calls = min(int(cfg.max_llm_calls or 48), 48)
+
+        try:
+            events = await run_turn(
+                sub_runner,
+                user_id="local",
+                session_id=sub_session_id,
+                prompt=prompt,
+                max_llm_calls=sub_max_calls,
+                cfg=cfg,
+            )
+        except Exception as e:
+            return {"error": f"Sub-agent error: {type(e).__name__}: {e}"}
+
+        # Extract only non-thinking text parts from the sub-agent's output.
+        parts: list[str] = []
+        for ev in events:
+            try:
+                if not ev.content or not ev.content.parts:
+                    continue
+                if getattr(ev, "author", None) == "user":
+                    continue
+                for part in ev.content.parts:
+                    t = getattr(part, "text", None)
+                    is_thought = getattr(part, "thought", None)
+                    if isinstance(t, str) and t.strip() and not is_thought:
+                        parts.append(t)
+            except Exception:
+                continue
+
+        result_text = "".join(parts).strip()
+        if not result_text:
+            result_text = (
+                "(Sub-agent completed the task but produced no text output. "
+                "It may have only called tools. Consider a more explicit task "
+                "that asks the sub-agent to summarise its findings.)"
+            )
+
+        return {"result": result_text}
+
+    return run_subtask

gemcode-0.3.19/src/gemcode/tools/think.py

@@ -0,0 +1,41 @@
+"""
+Think tool — structured reasoning scratchpad before acting.
+
+Inspired by Anthropic's documented "think" tool pattern:
+https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+
+Even though Gemini 2.5 has native dynamic thinking, an explicit think() call
+improves quality on hard tasks because:
+1. It forces a structured reasoning checkpoint before irreversible actions.
+2. The written thought persists in the conversation history so later tool calls
+   can reference it.
+3. It creates a visible chain-of-reasoning the model can revise.
+"""
+
+from __future__ import annotations
+
+
+def make_think_tool():
+    def think(thought: str) -> dict:
+        """
+        Write out your reasoning, plan, or analysis before taking action.
+
+        This is a private scratchpad — the content is NOT shown to the user.
+        Use it when you need to think clearly before executing tools:
+
+        - Planning a multi-step edit: map out what files to touch and in what order
+        - Debugging an error: trace the execution path before deciding on a fix
+        - Weighing approaches: compare trade-offs before committing to one
+        - Verifying understanding: articulate your model of the code before editing
+        - Decomposing a complex task: break it into concrete sub-steps
+        - After reading multiple files: synthesise before writing
+
+        Call think() BEFORE a sequence of tool calls, especially before destructive
+        or irreversible actions (deletes, overwrites, force-pushes).
+
+        The return value is intentionally empty — the value is in the reasoning
+        itself being part of the conversation context.
+        """
+        return {"ok": True}
+
+    return think

{gemcode-0.3.17 → gemcode-0.3.19}/src/gemcode/tui/scrollback.py

@@ -236,7 +236,76 @@ async def run_gemcode_scrollback_tui(
       pass
     return tool_name, hint
 
+  # ── Live status indicator ─────────────────────────────────────────────────
+  # spinner_active[0] = True while "⟳ Working..." is on the current line.
+  # _clear_spinner() uses \r + ANSI erase to overwrite it before real output.
+  spinner_active = [False]
+
+  def _clear_spinner() -> None:
+    if spinner_active[0]:
+      sys.stdout.write("\r\033[K")
+      sys.stdout.flush()
+      spinner_active[0] = False
+
+  def _fmt_tool_result(resp: object) -> str:
+    """One-line summary of a tool execution result."""
+    try:
+      d = resp if isinstance(resp, dict) else {}
+      # ADK may wrap the return value; try both the raw dict and a nested "result" key.
+      inner = d.get("result", d)
+      if not isinstance(inner, dict):
+        inner = d
+      err = inner.get("error") or d.get("error")
+      if err:
+        return f"\u2717 {str(err)[:80]}"
+      exit_code = inner.get("exit_code")
+      if exit_code is not None:
+        icon = "\u2713" if exit_code == 0 else f"\u2717 exit {exit_code}"
+        out = str(inner.get("stdout", "") or "").strip()
+        first = out.split("\n")[0][:80] if out else ""
+        if not first:
+          first = str(inner.get("stderr", "") or "").strip().split("\n")[0][:80]
+        return f"{icon}  {first}" if first else icon
+      if inner.get("content") is not None:
+        lines = str(inner["content"]).count("\n") + 1
+        return f"\u2713 {lines} lines"
+      if inner.get("files") is not None:
+        return f"\u2713 {len(inner['files'])} files"
+      if inner.get("matches") is not None:
+        return f"\u2713 {len(inner['matches'])} matches"
+      if inner.get("ok") or d.get("ok"):
+        return "\u2713"
+      return ""
+    except Exception:
+      return ""
+
+  def _render_tool_results(ev) -> None:
+    """Print a brief one-line summary when a tool finishes executing."""
+    try:
+      frs: list = []
+      try:
+        frs = ev.get_function_responses() or []
+      except Exception:
+        pass
+      if not frs and ev.content and ev.content.parts:
+        for part in ev.content.parts:
+          fr = getattr(part, "function_response", None)
+          if fr is not None:
+            frs.append(fr)
+      for fr in frs:
+        name = getattr(fr, "name", "") or ""
+        if name == _ADK_REQUEST_CONFIRMATION:
+          continue
+        _clear_spinner()
+        resp = getattr(fr, "response", {}) or {}
+        summary = _fmt_tool_result(resp)
+        if summary:
+          print(f"  ⎿    {ansi.dim}\u21b3 {summary}{ansi.reset}")
+    except Exception:
+      pass
+
   def _render_tool_calls(ev) -> None:
+    _clear_spinner()
     try:
       fcs = ev.get_function_calls() or []
     except Exception:
@@ -331,9 +400,18 @@ async def run_gemcode_scrollback_tui(
         kwargs["run_config"] = run_config
       # (We don't handle token budget reset here; full-screen TUI does.)
 
+      # Show a live "Working…" indicator so the user never wonders if the
+      # agent froze.  _clear_spinner() overwrites it with \r+ANSI-erase
+      # before the first real output (tool call, tool result, or response).
+      if ansi.enabled:
+        spinner_active[0] = True
+        sys.stdout.write(f"  {ansi.dim}\u27f3  Working\u2026{ansi.reset}")
+        sys.stdout.flush()
+
       async for ev in runner.run_async(**kwargs):
         events.append(ev)
         _render_tool_calls(ev)
+        _render_tool_results(ev)
         try:
           if not ev.content or not ev.content.parts:
             continue
@@ -351,6 +429,8 @@ async def run_gemcode_scrollback_tui(
         except Exception:
           continue
 
+      _clear_spinner()  # ensure "Working…" is gone before any response line
+
       if not assistant_wrote_text and _events_had_non_confirmation_tools(events):
         await typewrite(
             f"{ansi.dim}(Tools ran without a text reply in this step; "
@@ -377,15 +457,6 @@ async def run_gemcode_scrollback_tui(
             await typewrite(thought_text)
             sys.stdout.write("\n")
             sys.stdout.flush()
-        else:
-          # Keep thinking visible even if the model produced no separate
-          # "thought" channel output.
-          print(
-            f"  ⎿  {ansi.dim}{ansi.bold}\u2234 Thinking{ansi.reset}: "
-            "(no thinking output)"
-          )
-          print("")
-
         if buffered_final:
           sys.stdout.write(f"  ⎿  {ansi.bold}GemCode{ansi.reset}: ")
           sys.stdout.flush()

{gemcode-0.3.17 → gemcode-0.3.19/src/gemcode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.17
+Version: 0.3.19
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License

{gemcode-0.3.17 → gemcode-0.3.19}/src/gemcode.egg-info/SOURCES.txt

@@ -69,6 +69,8 @@ src/gemcode/tools/filesystem.py
 src/gemcode/tools/search.py
 src/gemcode/tools/shell.py
 src/gemcode/tools/shell_gate.py
+src/gemcode/tools/subtask.py
+src/gemcode/tools/think.py
 src/gemcode/tools/todo.py
 src/gemcode/tools/web.py
 src/gemcode/tui/input_handler.py