pythinker-code 2.2.1__tar.gz → 2.4.0__tar.gz

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythinker-code
-Version: 2.2.1
+Version: 2.4.0
 Summary: Pythinker Code is your next CLI agent.
 Keywords: cli,agent,ai,coding-assistant,llm,claude,openai,terminal
 Author: Mohamed Elkholy
@@ -33,9 +33,9 @@ Requires-Dist: ripgrepy==2.2.0
 Requires-Dist: streamingjson==0.0.5
 Requires-Dist: trafilatura==2.0.0
 Requires-Dist: lxml==6.0.2
-Requires-Dist: tenacity==9.1.2
+Requires-Dist: tenacity==9.1.4
 Requires-Dist: fastmcp==2.12.5
-Requires-Dist: pydantic==2.12.5
+Requires-Dist: pydantic==2.13.4
 Requires-Dist: httpx[socks]==0.28.1
 Requires-Dist: pythinker-host==1.0.0
 Requires-Dist: batrachian-toad==0.5.23 ; python_full_version >= '3.14'
@@ -110,6 +110,32 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
+## 🆕 What's New in 2.4.0
+
+Subagent roles overhaul, Moonshot/Kimi K2 provider support, and a ripgrep-free Grep fallback.
+
+- **New subagents** — `implementer` (scoped edits + verification), `review` (severity-scored read-only review), and `verifier` (`PASS` / `FAIL` / `FLAKY` validation runner). Join the existing `coder` / `explore` / `plan` roster.
+- **Structured subagent output** — every default agent now answers with `### SUMMARY / EVIDENCE / CHANGES / RISKS / BLOCKERS`, so the parent agent can consume results without re-parsing prose. New recommended flow: **Scout → Plan → Implement → Review → Verify** (review and verify can run in parallel).
+- **Kimi K2.5 / K2.6 (Moonshot) support** — `--thinking` is routed via the provider-specific `thinking.type` body field, and assistant tool-call replays always carry `reasoning_content` so multi-step tool flows stop tripping Moonshot's strict thinking-replay check. Same hardening applied to DeepSeek's strict mode.
+- **`Grep` works without `rg`** — pure-Python fallback honors `pattern` / `glob` / `type` / `ignore_case` / `multiline` / `context` / `output_mode` / `offset` / `head_limit` and respects `.gitignore`. The downloader also retries against the upstream GitHub releases mirror and accepts `PYTHINKER_RG_PATH=/absolute/path` plus extra discovery paths (`~/.cargo/bin`, `~/.local/bin`, `~/.pi/agent/bin`, `/usr/bin`, `/usr/local/bin`).
+- **`AGENTS.md` rewritten** to match the new roster, and `tools/agent/description.md` documents the parallel-review and cross-check patterns.
+
+Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.4.0`.
+
+### What was new in 2.3.0
+
+## 🆕 What's New in 2.3.0
+
+Telemetry & observability audit on top of 2.2.1.
+
+- **38 silent-catch sites instrumented** — tool failures, OAuth errors, MCP hiccups, hook callbacks, subagent crashes now surface in Bugsink + SigNoz.
+- **`/report-error` slash command** — user-invoked complement to automatic capture.
+- **OTel trace sampling tunable** — `PYTHINKER_OTEL_TRACE_SAMPLE_RATE` for operators running their own collector.
+- **`pythinker.mcp.call` span** with `mcp.server` attribute.
+- **`docs/en/reference/telemetry.md`** documents the full contract.
+
+### What was new in 2.2.1
+
 ## 🆕 What's New in 2.2.1
 
 CI hardening on top of 2.2.0.
@@ -117,8 +143,6 @@ CI hardening on top of 2.2.0.
 - **macOS binary build is now optional-codesign** — the release workflow detects whether `APPLE_CERTIFICATE_P12` / `APPLE_NOTARIZATION_KEY_P8` repo secrets are set. When they aren't (the v2.2.0 case), it ships an ad-hoc-signed PyInstaller binary instead of failing the whole release. PyPI install (`pip install pythinker-code`) is unaffected.
 - **PyPI publish is idempotent** — `pypa/gh-action-pypi-publish` now runs with `skip-existing: true`, so re-running the release workflow against an already-published version is a no-op.
 
-Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.2.1`.
-
 ### What was new in 2.2.0
 
 Animated installer + Windows PATH automation, on top of 2.1.2.

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/README.md

@@ -48,6 +48,32 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
+## 🆕 What's New in 2.4.0
+
+Subagent roles overhaul, Moonshot/Kimi K2 provider support, and a ripgrep-free Grep fallback.
+
+- **New subagents** — `implementer` (scoped edits + verification), `review` (severity-scored read-only review), and `verifier` (`PASS` / `FAIL` / `FLAKY` validation runner). Join the existing `coder` / `explore` / `plan` roster.
+- **Structured subagent output** — every default agent now answers with `### SUMMARY / EVIDENCE / CHANGES / RISKS / BLOCKERS`, so the parent agent can consume results without re-parsing prose. New recommended flow: **Scout → Plan → Implement → Review → Verify** (review and verify can run in parallel).
+- **Kimi K2.5 / K2.6 (Moonshot) support** — `--thinking` is routed via the provider-specific `thinking.type` body field, and assistant tool-call replays always carry `reasoning_content` so multi-step tool flows stop tripping Moonshot's strict thinking-replay check. Same hardening applied to DeepSeek's strict mode.
+- **`Grep` works without `rg`** — pure-Python fallback honors `pattern` / `glob` / `type` / `ignore_case` / `multiline` / `context` / `output_mode` / `offset` / `head_limit` and respects `.gitignore`. The downloader also retries against the upstream GitHub releases mirror and accepts `PYTHINKER_RG_PATH=/absolute/path` plus extra discovery paths (`~/.cargo/bin`, `~/.local/bin`, `~/.pi/agent/bin`, `/usr/bin`, `/usr/local/bin`).
+- **`AGENTS.md` rewritten** to match the new roster, and `tools/agent/description.md` documents the parallel-review and cross-check patterns.
+
+Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.4.0`.
+
+### What was new in 2.3.0
+
+## 🆕 What's New in 2.3.0
+
+Telemetry & observability audit on top of 2.2.1.
+
+- **38 silent-catch sites instrumented** — tool failures, OAuth errors, MCP hiccups, hook callbacks, subagent crashes now surface in Bugsink + SigNoz.
+- **`/report-error` slash command** — user-invoked complement to automatic capture.
+- **OTel trace sampling tunable** — `PYTHINKER_OTEL_TRACE_SAMPLE_RATE` for operators running their own collector.
+- **`pythinker.mcp.call` span** with `mcp.server` attribute.
+- **`docs/en/reference/telemetry.md`** documents the full contract.
+
+### What was new in 2.2.1
+
 ## 🆕 What's New in 2.2.1
 
 CI hardening on top of 2.2.0.
@@ -55,8 +81,6 @@ CI hardening on top of 2.2.0.
 - **macOS binary build is now optional-codesign** — the release workflow detects whether `APPLE_CERTIFICATE_P12` / `APPLE_NOTARIZATION_KEY_P8` repo secrets are set. When they aren't (the v2.2.0 case), it ships an ad-hoc-signed PyInstaller binary instead of failing the whole release. PyPI install (`pip install pythinker-code`) is unaffected.
 - **PyPI publish is idempotent** — `pypa/gh-action-pypi-publish` now runs with `skip-existing: true`, so re-running the release workflow against an already-published version is a no-op.
 
-Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.2.1`.
-
 ### What was new in 2.2.0
 
 Animated installer + Windows PATH automation, on top of 2.1.2.

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythinker-code"
-version = "2.2.1"
+version = "2.4.0"
 description = "Pythinker Code is your next CLI agent."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -38,9 +38,9 @@ dependencies = [
     "trafilatura==2.0.0",
     # lxml is used by trafilatura/htmldate/justext; keep pinned for binary wheels.
     "lxml==6.0.2",
-    "tenacity==9.1.2",
+    "tenacity==9.1.4",
     "fastmcp==2.12.5",
-    "pydantic==2.12.5",
+    "pydantic==2.13.4",
     "httpx[socks]==0.28.1",
     "pythinker-host==1.0.0",
     "batrachian-toad==0.5.23; python_version >= \"3.14\"",
@@ -73,7 +73,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.8.5,<0.10.0"]
+requires = ["uv_build>=0.8.5,<0.12.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 2.4.0 (2026-05-11)
+
+Subagent roles overhaul, Moonshot/Kimi K2 provider support, and a ripgrep-free Grep fallback.
+
+- New built-in subagents under `src/pythinker_code/agents/default/`:
+  - `implementer.yaml` — scoped code changes with minimum surrounding edits and a quick verification pass.
+  - `review.yaml` — read-only code review with severity-scored findings (BLOCKER / MAJOR / MINOR / NIT).
+  - `verifier.yaml` — read-only validation runner that reports `PASS` / `FAIL` / `FLAKY` without applying fixes.
+- `coder.yaml`, `explore.yaml`, and `plan.yaml` now emit a standard `### SUMMARY / EVIDENCE / CHANGES / RISKS / BLOCKERS` response contract so the parent agent can consume subagent output without re-parsing prose.
+- `agent.yaml` registers the three new roles; `tools/agent/description.md` documents the Scout → Plan → Implement → Review → Verify workflow and the parallel review/verification pattern.
+- `agents/default/system.md`: adds decomposition guidance (preview → todo list → parallel chunks), enforces post-tool-call verification before acting on results, and tells the agent to cross-check at least one load-bearing subagent finding before editing from it.
+- Kimi K2.5 / K2.6 (Moonshot) and other strict interleaved-thinking providers:
+  - `packages/pythinker-core/.../chat_provider/pythinker.py`: always emit `reasoning_content` on assistant tool-call replays so Moonshot's "thinking is enabled but reasoning_content is missing in assistant tool call message at index N" error no longer trips multi-step tool flows.
+  - `packages/pythinker-core/.../contrib/chat_provider/openai_legacy.py`: replay reasoning metadata on every assistant turn for `kimi-k2*` / `deepseek*` models (falls back to the assistant text or `"[reasoning unavailable]"` when reasoning content was not retained).
+  - `src/pythinker_code/llm.py`: route Kimi K2 thinking through the provider-specific `extra_body={"thinking": {"type": "enabled"|"disabled"}}` body field instead of OpenAI's `reasoning_effort` (which Kimi ignores), and persist `LLM.thinking` across `clone_llm_with_model_alias` so model switches preserve the user's thinking choice.
+- `tools/file/grep_local.py`:
+  - Pure-Python `rg`-free fallback (`_python_grep`) honoring `pattern`, `path`, `glob`, `type` (bash / c / cpp / go / java / js / json / md / py / rust / sh / toml / ts / txt / yaml / zsh), `ignore_case`, `multiline`, `context` / `before_context` / `after_context`, `line_number`, `output_mode` (`content` / `files_with_matches` / `count_matches`), `offset`, `head_limit`, and the standard sensitive-file redaction. `.gitignore` / `.ignore` and the VCS metadata directories (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`) are respected unless `include_ignored=true`.
+  - `_find_existing_rg` now honors `PYTHINKER_RG_PATH` and additionally probes `/usr/bin`, `/usr/local/bin`, `~/.cargo/bin`, `~/.local/bin`, and `~/.pi/agent/bin` before falling through to download.
+  - Downloader retries against the upstream GitHub releases mirror (`https://github.com/BurntSushi/ripgrep/releases/download/<version>/...`) when the CDN mirror is unreachable, and the failure path now degrades into the Python fallback instead of raising.
+- `.gitignore`: ignore `graphify-out*/`, `.graphify_*.json`, `.graphify_*.txt`, and the local `blackbox/` scratch area.
+- `AGENTS.md` rewritten to reflect the new subagent roster and workflow.
+
+## 2.3.0 (2026-05-09)
+
+Telemetry & observability audit.
+
+- New `pythinker_code/telemetry/errors.py` helper `report_handled_error(exc, *, site, tool=None, **attrs)` forwards caught-and-rendered exceptions to both Sentry/Bugsink and the OTel `error` event stream. Both forwarding paths are `contextlib.suppress`-wrapped so monitoring can never break the host program.
+- 38 silent-catch sites instrumented across `tools/`, `auth/`, `soul/`, `acp/`, `hooks/`, `subagents/`. Tool failures, OAuth errors, MCP server hiccups, hook callback failures, and subagent crashes now reach Bugsink and SigNoz.
+- `pythinker_code/telemetry/otel.py`: TracerProvider now uses `ParentBased(TraceIdRatioBased(rate))` driven by `PYTHINKER_OTEL_TRACE_SAMPLE_RATE` (default 1.0).
+- New `pythinker.mcp.call` span around every MCPTool RPC.
+- New `/report-error` slash command (aliases `/report`, `/report-error`).
+- `docs/en/reference/telemetry.md` documents the full telemetry contract.
+- `chore(test)`: updated google-genai snapshot for pydantic 2.13.4 + google-genai 2.0.0.
+
+
 ## 2.2.1 (2026-05-09)
 
 CI hardening: macOS binary build is now optional-codesign.

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/acp/host.py

@@ -148,6 +148,9 @@ class ACPProcess:
             )
             self._feed_output(final_output)
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="acp.host.terminal")
             error_note = f"[acp terminal error] {exc}\n"
             self._stdout.feed_data(error_note.encode("utf-8", "replace"))
             if exit_code is None:

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/acp/session.py

@@ -233,6 +233,9 @@ class ACPSession:
             logger.info("Prompt cancelled by user")
             return acp.PromptResponse(stop_reason="cancelled")
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="acp.session.prompt")
             logger.exception("Unexpected error during prompt:")
             raise acp.RequestError.internal_error({"error": str(e)}) from e
         finally:
@@ -461,7 +464,10 @@ class ACPSession:
                 # cancelled
                 logger.debug("Permission request cancelled for: {action}", action=request.action)
                 request.resolve("reject")
-        except Exception:
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="acp.session.approval")
             logger.exception("Error handling approval request:")
             # On error, reject the request
             request.resolve("reject")

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/agents/default/agent.yaml

@@ -34,3 +34,12 @@ agent:
     plan:
       path: ./plan.yaml
       description: "Read-only implementation planning and architecture design."
+    review:
+      path: ./review.yaml
+      description: "Read-only code review with severity-scored findings."
+    implementer:
+      path: ./implementer.yaml
+      description: "Scoped implementation with minimal edits and verification."
+    verifier:
+      path: ./verifier.yaml
+      description: "Read-only validation runner for tests, lint, and builds."

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/agents/default/coder.yaml

@@ -4,6 +4,22 @@ agent:
   system_prompt_args:
     ROLE_ADDITIONAL: |
       You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
+
+      Stay tightly scoped to exactly what the parent assigned. Do not expand into adjacent cleanup or refactors. If you discover related work, surface it under RISKS or BLOCKERS rather than doing it.
+
+      Before editing, read the target files and confirm the line ranges/patterns you will change. Prefer the minimum edit that satisfies the brief. After edits, run the smallest relevant verification command available and report the result.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with what you did and the outcome.
+      ### EVIDENCE
+      Bullet list of concrete file paths, command results, or observed errors that support the outcome.
+      ### CHANGES
+      Bullet list of every file you modified, or `None.` if read-only.
+      ### RISKS
+      Bullet list of remaining risks or `None observed.`.
+      ### BLOCKERS
+      Bullet list of anything that stopped completion, or `None.`.
   when_to_use: |
     Use this agent for non-trivial software engineering work that may require reading files, editing code, running commands, and returning a compact but technically complete summary to the parent agent.
   allowed_tools:

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/agents/default/explore.yaml

@@ -5,7 +5,7 @@ agent:
     ROLE_ADDITIONAL: |
       You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
 
-      You are a codebase exploration specialist. Your role is EXCLUSIVELY to search, read, and analyze existing code and resources. You do NOT have access to file editing tools.
+      You are a codebase exploration specialist. Your role is EXCLUSIVELY to search, read, and analyze existing code and resources. You do NOT have access to file editing tools. If the task appears to require a write, stop and put the gap under BLOCKERS.
 
       Your strengths:
       - Rapidly finding files using glob patterns
@@ -24,7 +24,19 @@ agent:
 
       If the prompt includes a <git-context> block, use it to orient yourself about the repository state before starting your investigation.
 
-      You are meant to be a fast agent. Complete the search request efficiently and report your findings clearly in a structured format.
+      You are meant to be a fast agent. Complete the search request efficiently and report your findings clearly in a structured format. EVIDENCE is the load-bearing section: cite each important finding as `path:line-range` when possible, and stop once you have enough evidence rather than exhaustively reading the whole repository.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with the headline answer.
+      ### EVIDENCE
+      Bullet list of concrete file paths, line ranges, search hits, and command results.
+      ### CHANGES
+      Always write `None.`.
+      ### RISKS
+      Bullet list of uncertainties or `None observed.`.
+      ### BLOCKERS
+      Bullet list of missing context/capabilities or `None.`.
   when_to_use: |
     Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (e.g. "src/**/*.yaml"), search code for keywords (e.g. "database connection"), or answer questions about the codebase (e.g. "how does the auth module work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "thorough" for comprehensive analysis across multiple locations and naming conventions. Use this agent for any read-only exploration that will clearly require more than 3 tool calls. Prefer launching multiple explore agents concurrently when investigating independent questions.
   allowed_tools:

pythinker_code-2.4.0/src/pythinker_code/agents/default/implementer.yaml

@@ -0,0 +1,45 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. Treat the parent agent as your caller. Do not directly ask the end user questions.
+
+      You are an implementation specialist. Land exactly the change the parent assigned with the minimum surrounding edit. Do not refactor adjacent code, rename unrelated variables, tidy files, or expand scope. Put related follow-up work under RISKS or BLOCKERS instead.
+
+      Method:
+      - Read target files before editing.
+      - Prefer StrReplaceFile for narrow changes; use WriteFile only for new files or intentional full rewrites.
+      - Add or update tests when the brief requires behavior changes and the project has relevant tests.
+      - After edits, run the smallest relevant verification command and report pass/fail evidence.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with what changed and the verification outcome.
+      ### EVIDENCE
+      Bullet list of file reads, command results, and test/lint evidence.
+      ### CHANGES
+      Bullet list of every modified path with a one-line reason.
+      ### RISKS
+      Bullet list of remaining risks or `None observed.`.
+      ### BLOCKERS
+      Bullet list of anything that stopped completion, or `None.`.
+  when_to_use: |
+    Use this agent when the required code change is already specified and should be implemented with minimal edits and a quick verification pass.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+  subagents:

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/agents/default/plan.yaml

@@ -5,10 +5,21 @@ agent:
     ROLE_ADDITIONAL: |
       You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
 
-      Before designing your implementation plan, consider whether you fully understand the codebase areas relevant to the task. If not, recommend the parent agent to use the explore agent (subagent_type="explore") to investigate key questions first. In your response, clearly state:
-      1. What you already know from the information provided
-      2. What questions remain unanswered that would benefit from explore agent investigation
-      3. Your implementation plan (either preliminary if questions remain, or final if sufficient context exists)
+      Before designing your implementation plan, consider whether you fully understand the codebase areas relevant to the task. If not, recommend the parent agent to use the explore agent (subagent_type="explore") to investigate key questions first.
+
+      Ground the plan in evidence. Read enough files to avoid guessing, name the trade-offs, and choose one path with a reason. Each step should name the artifact it changes and the verification that proves it worked. Order steps by dependency first, then by risk reduced per effort.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with the recommended plan and why.
+      ### EVIDENCE
+      Bullet list of concrete file paths, line ranges, docs, or search hits that shaped the plan.
+      ### CHANGES
+      Always write `None.` unless you wrote a plan artifact.
+      ### RISKS
+      Bullet list of trade-offs, unknowns, or rollout risks.
+      ### BLOCKERS
+      Bullet list of questions that must be answered before execution, or `None.`.
   when_to_use: |
     Use this agent when the parent agent needs a step-by-step implementation plan, key file identification, and architectural trade-off analysis before code changes are made.
   allowed_tools:

pythinker_code-2.4.0/src/pythinker_code/agents/default/review.yaml

@@ -0,0 +1,46 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. Treat the parent agent as your caller. Do not directly ask the end user questions.
+
+      You are a code review specialist. Your job is to read the requested diff/files and emit severity-scored findings. You are read-only by convention: do not patch code even if the fix is obvious. Describe the fix so the parent can dispatch an implementer.
+
+      Method:
+      - Read the diff or target files before scoring.
+      - Use Grep/Glob to check sibling call sites, similar patterns, and existing tests.
+      - Score each finding as BLOCKER, MAJOR, MINOR, or NIT.
+      - Order findings by severity, BLOCKER first.
+      - Be constructive: cite failure modes and evidence, not author intent.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph. If there are no MAJOR/BLOCKER issues, say that plainly.
+      ### EVIDENCE
+      Bullet list. Format review findings as `[SEVERITY] path:line-range — issue; suggested fix`.
+      ### CHANGES
+      Always write `None.`.
+      ### RISKS
+      Bullet list of residual review limitations or `None observed.`.
+      ### BLOCKERS
+      Bullet list of missing context/capabilities or `None.`.
+  when_to_use: |
+    Use this agent for read-only code review after changes are made or when the parent needs severity-scored findings before deciding what to fix.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+  subagents:

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/agents/default/system.md

@@ -10,10 +10,26 @@ The user's messages may contain questions and/or task descriptions in natural la
 
 When handling the user's request, if it involves creating, modifying, or running code or files, you MUST use the appropriate tools (e.g., `WriteFile`, `Shell`) to make actual changes — do not just describe the solution in text. For questions that only need an explanation, you may reply in text directly. When calling tools, do not provide explanations because the tool calls themselves should be self-explanatory. You MUST follow the description of each tool and its parameters when calling tools.
 
-If the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. The tool can either start a new instance or resume an existing one by `agent_id`. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context because a newly created subagent instance does not automatically see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it instead of creating a new instance. Default to foreground subagents. Use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes, and you do not need the result immediately to decide your next step.
+If the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. Treat subagents as focused roles, not just extra capacity: use `explore` for read-only mapping, `plan` for strategy, `coder` or `implementer` for scoped edits, `review` for severity-scored critique, and `verifier` for validation gates. The tool can either start a new instance or resume an existing one by `agent_id`. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context because a newly created subagent instance does not automatically see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it instead of creating a new instance. Default to foreground subagents. Use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes, and you do not need the result immediately to decide your next step. Spawn multiple subagents in the same turn when they can investigate independent regions concurrently.
 
 You have the capability to output any number of tool calls in a single response. If you anticipate making multiple non-interfering tool calls, you are HIGHLY RECOMMENDED to make them in parallel to significantly improve efficiency. This is very important to your performance.
 
+For any non-trivial request, decompose before acting:
+
+- Preview the terrain first: scan the directory structure, file headers, and relevant module boundaries before choosing an implementation path.
+- Use `SetTodoList` for multi-step work so the user can see the active plan and progress.
+- Split broad work into independent chunks; use parallel tool calls or focused subagents for chunks that do not depend on each other.
+- Re-read the plan after each phase and adjust it when new evidence changes the approach.
+
+Before every tool response, ask whether another independent read/search/check can run in the same turn. Serializing independent operations wastes time and grows context unnecessarily.
+
+After every tool call whose result you will act on, verify the result before proceeding:
+
+- File reads: confirm the path and line range you are about to modify match what you read.
+- Searches: confirm the hit is relevant; broad regexes can return false positives.
+- Shell commands: inspect stdout/stderr, not just the exit code.
+- Subagent results: cross-check at least one load-bearing finding against a direct read or deterministic command before making changes from it.
+
 The results of the tool calls will be returned to you in a tool message. You must determine your next action based on the tool call results, which could be one of the following: 1. Continue working on the task, 2. Inform the user that the task is completed or has failed, or 3. Ask the user for more information.
 
 The system may insert information wrapped in `<system>` tags within user or tool messages. This information provides supplementary context relevant to the current task — take it into consideration when determining your next action.

pythinker_code-2.4.0/src/pythinker_code/agents/default/verifier.yaml

@@ -0,0 +1,45 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. Treat the parent agent as your caller. Do not directly ask the end user questions.
+
+      You are a verification specialist. Your job is to run the validation gate the parent requested and report PASS / FAIL / FLAKY with actionable evidence. You are read-only by convention: do not patch failing code, update snapshots, or fix lint. If a fix is obvious, describe it under RISKS.
+
+      Method:
+      - Run the narrowest relevant gate when the parent gives one; otherwise choose the standard project command from AGENTS.md.
+      - Capture exact failing assertions, stack traces, and file:line references.
+      - Do not run expensive full suites unless requested or clearly necessary.
+      - If a result looks flaky, mention how many runs were attempted.
+
+      Final response contract:
+      ### SUMMARY
+      Start with `PASS`, `FAIL`, or `FLAKY`, then one paragraph explaining the outcome.
+      ### EVIDENCE
+      Bullet list of commands, exit codes, important stdout/stderr, and file:line failures.
+      ### CHANGES
+      Always write `None.`.
+      ### RISKS
+      Bullet list of likely causes or follow-up fixes, or `None observed.`.
+      ### BLOCKERS
+      Bullet list of missing dependencies, unavailable commands, or `None.`.
+  when_to_use: |
+    Use this agent when the parent needs tests, lint, type checks, builds, or other validation gates run and reported without applying fixes.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  subagents:

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/auth/oauth.py

@@ -358,6 +358,9 @@ def _load_from_keyring(key: str) -> OAuthToken | None:
     try:
         raw = keyring.get_password(KEYRING_SERVICE, key)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.keyring.read")
         logger.warning("Failed to read token from keyring: {error}", error=exc)
         return None
     if not raw:
@@ -632,6 +635,9 @@ async def login_pythinker_code(
         try:
             auth = await request_device_authorization()
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="auth.oauth.device_authorize")
             yield OAuthEvent("error", f"Login failed: {exc}")
             return
 
@@ -680,6 +686,9 @@ async def login_pythinker_code(
             yield OAuthEvent("info", "Device code expired, restarting login...")
             continue
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="auth.oauth.device_poll")
             yield OAuthEvent("error", f"Login failed: {exc}")
             return
         break
@@ -692,6 +701,9 @@ async def login_pythinker_code(
     try:
         models = await list_models(platform, token.access_token)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.models.fetch")
         logger.error("Failed to get models: {error}", error=exc)
         yield OAuthEvent("error", f"Failed to get models: {exc}")
         return
@@ -947,6 +959,9 @@ class OAuthManager:
                     try:
                         await self.ensure_fresh(runtime, force=force)
                     except Exception as exc:
+                        from pythinker_code.telemetry.errors import report_handled_error
+
+                        report_handled_error(exc, site="auth.oauth.refresh.background")
                         logger.warning(
                             "Failed to refresh OAuth token in background: {error}",
                             error=exc,
@@ -1071,6 +1086,9 @@ class OAuthManager:
                 except Exception as exc:
                     if force:
                         raise
+                    from pythinker_code.telemetry.errors import report_handled_error
+
+                    report_handled_error(exc, site="auth.oauth.refresh")
                     logger.warning("Failed to refresh OAuth token: {error}", error=exc)
                     from pythinker_code.telemetry import track
 

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/auth/openai.py

@@ -612,6 +612,9 @@ async def _finish_chatgpt_login(
         models = await _discover_chatgpt_models(token.access_token)
         selected_model, thinking = _select_default_openai_model(models)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.discover_chatgpt_models")
         yield OAuthEvent("error", f"Failed to discover OpenAI ChatGPT models: {exc}")
         return
 
@@ -649,6 +652,9 @@ async def login_openai_browser(
         code, verifier, redirect_uri = await _wait_for_browser_code(open_browser=open_browser)
         token_payload = await _exchange_code_for_tokens(code, verifier, redirect_uri)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.browser_login")
         yield OAuthEvent("error", f"OpenAI browser login failed: {exc}")
         return
 
@@ -667,6 +673,9 @@ async def login_openai_headless(config: Config) -> AsyncIterator[OAuthEvent]:
     try:
         device_code = await _request_device_code()
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.device_start")
         yield OAuthEvent("error", f"Failed to start OpenAI device login: {exc}")
         return
 
@@ -688,6 +697,9 @@ async def login_openai_headless(config: Config) -> AsyncIterator[OAuthEvent]:
             OPENAI_DEVICE_REDIRECT_URI,
         )
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.device_poll")
         yield OAuthEvent("error", f"OpenAI device login failed: {exc}")
         return
 

{pythinker_code-2.2.1 → pythinker_code-2.4.0}/src/pythinker_code/auth/platforms.py

@@ -248,6 +248,9 @@ async def refresh_managed_models(config: Config) -> bool:
             try:
                 await oauth_manager.ensure_fresh()
             except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(exc, site="auth.platforms.refresh.pre_sync")
                 logger.warning(
                     "Failed to refresh OAuth token before model sync for {platform}: {error}",
                     platform=platform_id,
@@ -281,6 +284,9 @@ async def refresh_managed_models(config: Config) -> bool:
             try:
                 await oauth_manager.ensure_fresh(force=True)
             except Exception as exc2:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(exc2, site="auth.platforms.refresh.after_401")
                 refresh_exc = exc2
                 logger.warning(
                     "Failed to refresh OAuth token after 401 for {platform}: {error}",
@@ -323,6 +329,9 @@ async def refresh_managed_models(config: Config) -> bool:
                         changed = True
                 continue
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="auth.platforms.sync")
             fallback_models = _fallback_or_log(platform_id=platform_id, error=exc)
             if fallback_models is None:
                 continue