pythinker-code 2.2.0__tar.gz → 2.3.0__tar.gz

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythinker-code
-Version: 2.2.0
+Version: 2.3.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,7 +110,30 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
-## 🆕 What's New in 2.2.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.
+
+Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.3.0`.
+
+### What was new in 2.2.1
+
+## 🆕 What's New in 2.2.1
+
+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.3.0`.
+
+### What was new in 2.2.0
 
 Animated installer + Windows PATH automation, on top of 2.1.2.
 
@@ -148,7 +171,6 @@ A focused refresh of the TUI and slash-command UX.
 - **Prompt templates** — discovery is now `~/.pythinker/prompts` and `<project>/.pythinker/prompts`. The legacy directory lookup has been retired.
 - **TUI style flag** — only `card` (default) and `pythinker` are accepted; the legacy alias has been dropped.
 
-Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.2.0`.
 
 ---
 

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/README.md

@@ -48,7 +48,30 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
-## 🆕 What's New in 2.2.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.
+
+Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.3.0`.
+
+### What was new in 2.2.1
+
+## 🆕 What's New in 2.2.1
+
+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.3.0`.
+
+### What was new in 2.2.0
 
 Animated installer + Windows PATH automation, on top of 2.1.2.
 
@@ -86,7 +109,6 @@ A focused refresh of the TUI and slash-command UX.
 - **Prompt templates** — discovery is now `~/.pythinker/prompts` and `<project>/.pythinker/prompts`. The legacy directory lookup has been retired.
 - **TUI style flag** — only `card` (default) and `pythinker` are accepted; the legacy alias has been dropped.
 
-Upgrade with `pythinker update` or `pip install --upgrade pythinker-code==2.2.0`.
 
 ---
 

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythinker-code"
-version = "2.2.0"
+version = "2.3.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.0 → pythinker_code-2.3.0}/src/pythinker_code/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## 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.
+
+- `.github/workflows/release-pythinker-cli.yml`: detect whether `APPLE_CERTIFICATE_P12` and `APPLE_NOTARIZATION_KEY_P8` repo secrets are configured. When they aren't, skip the keychain setup, codesign, and notarization steps and ship an ad-hoc-signed PyInstaller binary instead of failing the whole release. The 2.2.0 release run failed because those secrets were empty in CI; this makes the release matrix all-green even without an Apple Developer cert.
+- `.github/workflows/release-pythinker-cli.yml`: add `skip-existing: true` to `pypa/gh-action-pypi-publish` so re-runs of the release workflow against an already-published version are no-ops instead of HTTP 400 errors.
+- macOS-arm64 binary downloads from the GitHub Release page will now show a Gatekeeper warning on first launch when the secrets aren't configured. Users can clear it with `xattr -d com.apple.quarantine ./pythinker`. PyPI install (`pip install pythinker-code`) is unaffected.
+
 ## 2.2.0 (2026-05-09)
 
 Installer UX: animated logo + Windows PATH automation.

{pythinker_code-2.2.0 → pythinker_code-2.3.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.0 → pythinker_code-2.3.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.0 → pythinker_code-2.3.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.0 → pythinker_code-2.3.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.0 → pythinker_code-2.3.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

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/src/pythinker_code/hooks/engine.py

@@ -237,7 +237,10 @@ class HookEngine:
             results = await self._execute_hooks(
                 event, matcher_value, server_matched, wire_matched, input_data
             )
-        except Exception:
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="hooks.engine.run")
             logger.warning("Hook engine error for {}, failing open", event)
             return []
 
@@ -278,6 +281,9 @@ class HookEngine:
             try:
                 self._on_triggered(event, matcher_value, total)
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="hooks.engine.triggered_cb")
                 logger.warning(
                     "HookTriggered callback failed for {event}: {error}, continuing",
                     event=event,
@@ -328,6 +334,9 @@ class HookEngine:
             try:
                 self._on_resolved(event, matcher_value, action, reason, duration_ms)
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="hooks.engine.resolved_cb")
                 logger.warning(
                     "HookResolved callback failed for {event}: {error}, continuing",
                     event=event,
@@ -366,6 +375,9 @@ class HookEngine:
             logger.warning("Wire hook timed out: {} {}", event, target)
             return HookResult(action="allow", timed_out=True)
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="hooks.engine.wire")
             hook_task.cancel()
             logger.warning("Wire hook failed: {} {}: {}", event, target, e)
             return HookResult(action="allow")

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/src/pythinker_code/hooks/runner.py

@@ -51,6 +51,9 @@ async def run_hook(
             await proc.wait()
             raise
     except Exception as e:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(e, site="hooks.runner")
         logger.warning("Hook failed: {}: {}", command, e)
         return HookResult(action="allow", stderr=str(e))
 

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/src/pythinker_code/soul/btw.py

@@ -176,6 +176,9 @@ async def execute_side_question(
 
         return None, "No response received."
     except Exception as e:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(e, site="soul.btw.execute")
         logger.warning("Side question failed: {error}", error=e)
         return None, str(e)
 
@@ -210,5 +213,8 @@ async def run_side_question(soul: PythinkerSoul, question: str) -> None:
         else:
             wire_send(BtwEnd(id=btw_id, error=error or "No response received."))
     except Exception as e:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(e, site="soul.btw.run_wire")
         logger.warning("Side question failed: {error}", error=e)
         wire_send(BtwEnd(id=btw_id, error=str(e)))

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/src/pythinker_code/soul/pythinkersoul.py

@@ -286,7 +286,14 @@ class PythinkerSoul:
             try:
                 result = await provider.get_injections(self._context.history, self)
                 injections.extend(result)
-            except Exception:
+            except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(
+                    exc,
+                    site="soul.injection.get",
+                    provider=type(provider).__name__,
+                )
                 logger.warning(
                     "injection provider %s failed",
                     type(provider).__name__,
@@ -304,7 +311,14 @@ class PythinkerSoul:
         for provider in self._injection_providers:
             try:
                 await provider.on_context_compacted()
-            except Exception:
+            except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(
+                    exc,
+                    site="soul.injection.on_context_compacted",
+                    provider=type(provider).__name__,
+                )
                 logger.warning(
                     "injection provider %s on_context_compacted failed",
                     type(provider).__name__,
@@ -316,7 +330,14 @@ class PythinkerSoul:
         for provider in self._injection_providers:
             try:
                 await provider.on_auto_changed(enabled)
-            except Exception:
+            except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(
+                    exc,
+                    site="soul.injection.on_auto_changed",
+                    provider=type(provider).__name__,
+                )
                 logger.warning(
                     "injection provider %s on_auto_changed failed",
                     type(provider).__name__,
@@ -937,6 +958,9 @@ class PythinkerSoul:
                     try:
                         await self.compact_context()
                     except Exception as compact_err:
+                        from pythinker_code.telemetry.errors import report_handled_error
+
+                        report_handled_error(compact_err, site="soul.context.compact")
                         logger.error(
                             "Context compaction failed at step {step_no}: {error_type}: {error}",
                             step_no=step_no,
@@ -952,6 +976,9 @@ class PythinkerSoul:
             except BackToTheFuture as e:
                 back_to_the_future = e
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="soul.step.error")
                 # any other exception should interrupt the step
                 req_id = getattr(e, "request_id", None)
                 logger.error(
@@ -1453,7 +1480,10 @@ class PythinkerSoul:
                 raise
             try:
                 recovered = chat_provider.on_retryable_error(error)
-            except Exception:
+            except Exception as recover_exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(recover_exc, site="soul.chat.recover")
                 logger.exception(
                     "Failed to recover chat provider during {name} after {error_type}.",
                     name=name,

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/src/pythinker_code/soul/toolset.py

@@ -319,6 +319,9 @@ class PythinkerToolset:
                 parameters=parameters,
             )
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="soul.toolset.register_external")
             return False, str(e)
         self.add(tool)
         return True, None
@@ -490,6 +493,9 @@ class PythinkerToolset:
                 logger.info("Connected MCP server: {server_name}", server_name=server_name)
                 return server_name, None
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="soul.toolset.mcp.connect")
                 logger.error(
                     "Failed to connect MCP server: {server_name}, error: {error}",
                     server_name=server_name,
@@ -608,6 +614,7 @@ class MCPTool[T: ClientTransport](CallableTool):
             **kwargs,
         )
         self._mcp_tool = mcp_tool
+        self._mcp_server_name = server_name
         self._client = client
         self._runtime = runtime
         self._timeout = timedelta(milliseconds=runtime.config.mcp.client.tool_call_timeout_ms)
@@ -619,25 +626,43 @@ class MCPTool[T: ClientTransport](CallableTool):
         if not result:
             return result.rejection_error()
 
+        from pythinker_code.telemetry import otel as _otel
+
+        # `start_span` returns a sync context manager (the OTel SDK uses
+        # `_AgnosticContextManager`, which intentionally has no __aenter__).
+        # Keep it as a sync `with` and use `async with` only on the fastmcp
+        # client.
         try:
-            async with self._client as client:
-                result = await client.call_tool(
-                    self._mcp_tool.name,
-                    kwargs,
-                    timeout=self._timeout,
-                    raise_on_error=False,
-                )
-                if result.is_error:
-                    logger.warning(
-                        "MCP tool returned error: {tool_name}: {content}",
-                        tool_name=self._mcp_tool.name,
-                        content=[str(p) for p in result.content][:3],
+            with _otel.start_span(
+                "pythinker.mcp.call",
+                {
+                    "mcp.server": self._mcp_server_name,
+                    "mcp.tool": self._mcp_tool.name,
+                    "mcp.timeout_ms": int(self._timeout.total_seconds() * 1000),
+                },
+            ) as span:
+                async with self._client as client:
+                    result = await client.call_tool(
+                        self._mcp_tool.name,
+                        kwargs,
+                        timeout=self._timeout,
+                        raise_on_error=False,
                     )
-                return convert_mcp_tool_result(result)
+                    span.set_attribute("mcp.is_error", bool(result.is_error))
+                    if result.is_error:
+                        logger.warning(
+                            "MCP tool returned error: {tool_name}: {content}",
+                            tool_name=self._mcp_tool.name,
+                            content=[str(p) for p in result.content][:3],
+                        )
+                    return convert_mcp_tool_result(result)
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
             # fastmcp raises `RuntimeError` on timeout and we cannot tell it from other errors
             exc_msg = str(e).lower()
             if "timeout" in exc_msg or "timed out" in exc_msg:
+                report_handled_error(e, site="soul.toolset.mcp.call.timeout", tool="MCP")
                 logger.warning(
                     "MCP tool call timed out: {tool_name}: {error}",
                     tool_name=self._mcp_tool.name,
@@ -650,6 +675,7 @@ class MCPTool[T: ClientTransport](CallableTool):
                     ),
                     brief="Timeout",
                 )
+            report_handled_error(e, site="soul.toolset.mcp.call", tool="MCP")
             logger.error(
                 "MCP tool call failed: {tool_name}: {error}",
                 tool_name=self._mcp_tool.name,
@@ -693,6 +719,9 @@ class WireExternalTool(CallableTool):
         except asyncio.CancelledError:
             raise
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="soul.toolset.external_tool", tool="External")
             logger.exception("External tool call failed: {tool_name}:", tool_name=self.name)
             return ToolError(
                 message=f"External tool call failed: {e}",

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/src/pythinker_code/subagents/runner.py

@@ -124,6 +124,9 @@ async def run_soul_checked(
             brief="LLM provider error",
         )
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="subagents.run.soul")
         logger.exception("Subagent soul run failed when {phase}", phase=phase)
         return SoulRunFailure(
             message=f"Unexpected error when {phase}: {exc}",
@@ -316,7 +319,10 @@ class ForegroundSubagentRunner:
             self._store.update_instance(agent_id, status="killed")
             output_writer.stage("cancelled")
             raise RunCancelled("Subagent run was cancelled.") from exc
-        except Exception:
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="subagents.run.background")
             self._store.update_instance(agent_id, status="failed")
             output_writer.stage("failed_exception")
             raise

{pythinker_code-2.2.0 → pythinker_code-2.3.0}/src/pythinker_code/telemetry/config.py

@@ -52,3 +52,32 @@ def is_disabled() -> bool:
     Sentry and OTel emission for the process."""
     raw = os.environ.get("PYTHINKER_DISABLE_TELEMETRY", "").strip().lower()
     return raw in {"1", "true", "yes", "on"}
+
+
+# ---------------------------------------------------------------------------
+# Sampling
+# ---------------------------------------------------------------------------
+
+DEFAULT_OTEL_TRACE_SAMPLE_RATE = 1.0
+"""Default fraction of root-trace spans to record. 1.0 = always-on; 0.0 = none."""
+
+
+def otel_trace_sample_rate() -> float:
+    """Resolve the OTel trace sampling rate.
+
+    Honors ``PYTHINKER_OTEL_TRACE_SAMPLE_RATE``. Clamped to ``[0.0, 1.0]``.
+    Malformed input falls back to the default rather than disabling tracing
+    or raising — telemetry config must never break the host program.
+    """
+    raw = os.environ.get("PYTHINKER_OTEL_TRACE_SAMPLE_RATE", "").strip()
+    if not raw:
+        return DEFAULT_OTEL_TRACE_SAMPLE_RATE
+    try:
+        rate = float(raw)
+    except ValueError:
+        return DEFAULT_OTEL_TRACE_SAMPLE_RATE
+    if rate < 0.0:
+        return 0.0
+    if rate > 1.0:
+        return 1.0
+    return rate