pythinker-code 0.45.0__py3-none-any.whl → 0.47.0__py3-none-any.whl

pythinker_code/CHANGELOG.md

@@ -15,6 +15,104 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+## 0.47.0 (2026-06-16)
+
+- **Plugin marketplaces and activation policy.** `pythinker plugin marketplace` can add,
+  refresh, install, and uninstall Claude/Codex-compatible marketplace plugins. Plugins
+  installed for Claude Code or Codex are auto-detected (no symlink): their safe artifacts
+  (skills, commands, agents) activate by default, while executable artifacts (hooks, MCP
+  servers) stay opt-in. Config `plugins.discover_external`, `plugins.external_exec`,
+  `plugins.enabled`, and `plugins.disabled` — plus `pythinker plugin enable/disable <name>`
+  — control which installed plugins contribute artifacts. Hook and MCP commands
+  expand `${CLAUDE_PLUGIN_ROOT}`/`${PYTHINKER_PLUGIN_ROOT}` and
+  `${CLAUDE_PLUGIN_DATA}`/`${PYTHINKER_PLUGIN_DATA}`.
+- **Plugin dependencies.** Plugins may declare `dependencies`; installing one pulls its
+  transitive dependencies from the same marketplace (cross-marketplace deps are blocked),
+  and a plugin whose dependencies aren't present+enabled is disabled at load instead of
+  half-activating.
+- **Plugin options (`userConfig`).** `${user_config.KEY}` in a plugin's MCP server configs
+  and hook commands is filled from `[plugins.options.<plugin>]` config; an artifact that
+  references an unconfigured option is skipped rather than run blank. (Content substitution,
+  `PYTHINKER_PLUGIN_OPTION_*` hook env vars, and keychain-backed sensitive storage are not
+  yet implemented.)
+- **MCP tool lists refresh automatically when servers change.** Connected MCP
+  sessions stay open for `tools/list_changed` (and resources/prompts) notifications;
+  inventory is re-published without a manual `/mcp refresh`.
+- **Shell live token readouts track output throughput.** The spinner and background
+  status line show session-wide output tokens produced during the current turn or
+  background stretch instead of the context-size snapshot.
+- **MCP servers can be managed without a full reload.** `/mcp disconnect`, `/mcp reconnect`, and
+  `/mcp refresh` (or `retry`) update the live toolset for one server; disconnect unregisters its
+  tools and marks the server failed until reconnect.
+- **Recall search matches session ids and plan slugs.** Prior-session keyword search now indexes
+  `session_id` and `plan_slug` in addition to titles so agents can find plan-linked sessions by slug.
+- **Wire and ACP surfaces now get max-steps handoff summaries.** When a turn hits the step ceiling,
+  wire clients receive a streamed handoff event plus a `handoff` field on the `max_steps_reached`
+  result; ACP sessions emit the same summary text before returning `max_turn_requests`.
+- **MCP CLI commands resolve normalized server names.** `mcp remove`, `mcp auth`, `mcp test`, and
+  `reset-auth` accept display names with spaces or slashes and map them to stored config keys; config
+  load applies the same normalization as add.
+- **Compaction failure circuit breaker respects thresholds above one.** A proactive compaction
+  failure below `max_compaction_failures` no longer aborts the turn; the handoff fires only after
+  the configured number of consecutive failures.
+- **AI eval gate schema is self-contained under `tests_ai/`.** Shared eval-case types live in
+  `tests_ai/eval_schema.py` so isolated `tests_ai` runs do not import from `tests_e2e`.
+- **Softer TUI chrome in the dark theme.** Panel borders (welcome banner, menus) and the input-area
+  rules now render in a mid grey (`#8a8d91`) instead of near-white, for a less glaring look.
+- **Stop-time memory extraction can now be enabled explicitly.** Added an opt-in
+  `memory.harvest_on_stop` setting that stages safe assistant decisions, blockers, evidence, and
+  next steps into the existing scratchpad recall flow at turn end without writing directly to
+  durable `MEMORY.md`.
+- **Agents can now discover visible tools and temporarily work from a session worktree.** Added
+  `ToolSearch` plus root-session `EnterWorktree` and `ExitWorktree` tools so agents can find
+  currently available capabilities by keyword and isolate a session's operational working directory
+  in a git worktree without deleting user work on exit.
+- **Root sessions now get a bounded git snapshot in the prompt.** When `git_status_injection` is
+  enabled (default), the agent receives branch, dirty-file summary, and recent commits as an
+  explicitly stale point-in-time reminder; disable via config or set `git_status_injection = false`.
+- **Context compaction and MCP tool registration now fail more predictably.** Proactive compaction
+  failures hand back with an explicit `compaction_failed` stop instead of bubbling an unstructured
+  loop error, and MCP duplicate tool-name resolution now follows configured server order instead of
+  connection completion order. Tool hooks also retain the original model input even if a tool
+  mutates a nested argument object during execution.
+- **Recall can now read bounded transcript windows.** `Recall(mode="read")` accepts
+  `message_offset` and `max_messages` so agents can inspect a precise, sanitized slice of a prior
+  workspace session without pulling the whole transcript into context.
+- **MCP prompt templates can now be invoked from connected servers.** `InvokeMcpPrompt` renders a
+  server-published prompt with structured arguments and wraps the returned messages as untrusted
+  input for the model.
+- **Telemetry, MCP config, and shell UX hardening.** Tool spans and metrics sanitize MCP/plugin
+  names; `mcp.json` load paths inject docker `--rm` and normalize server keys with collision
+  errors; shell suggestions accept via Alt+S into the prompt; markdown agent frontmatter maps
+  `max_turns`/`disallowed_tools`; `ReadMediaFile` enforces per-kind byte/pixel caps; written plans
+  without a Verification section get a soft warning; AI eval budgets can gate `tests_ai` reports.
+- **Plan-mode exit guidance now requires verification.** The `ExitPlanMode` tool now tells agents
+  that written plans must include a Verification section with the smallest command, test, or check
+  for each meaningful change.
+- **Agent-loop observability now emits explicit Wire events for key runtime state.** Added
+  `TodoListUpdated`, `SubagentToolFallback`, `AgentListDelta`, `ToolUseSkipped`, and
+  `ContextOverflowRecovered` events, with todo updates, subagent launch fallbacks, same-step tool
+  reuse/policy skips for tools that explicitly opt in, agent-list injections, and
+  context-overflow recovery now surfaced best-effort over Wire without changing existing tool
+  results.
+- **Spend ceilings now warn before they stop a session.** When `max_session_cost_usd` is configured,
+  the loop appends a bounded system reminder after a turn crosses `budget_nudge_ratio` of the
+  ceiling, nudging the agent to conserve budget without auto-continuing or hiding a later
+  `budget_exhausted` stop.
+- **The Agent tool description now gives clearer prompt-briefing guidance.** Fresh subagents should
+  receive the goal, scope, expected output contract, and verification criteria; the Haiku-style
+  tool-use summary from the blackbox reference was deliberately not ported.
+
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.47.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
+
+## 0.46.0 (2026-06-14)
+
+- **Startup auto-update now picks up new releases within half an hour instead of up to a day.** The background update check was throttled to once every 24h, so a freshly published release could go unnoticed for a full day after the last check; the interval is now 30 minutes. The silent installer also no longer marks the throttle *before* the network call — a transient startup network error returns `FAILED` and is retried on the next launch instead of suppressing updates for the whole window.
+- **The welcome banner now keeps the robot mark visible in compact terminals.** Below ~68 columns the robot was dropped (it could not sit beside the welcome copy); it now stacks centered above the copy instead, so the mark stays on screen at any width that can render its Unicode glyphs. ASCII-only terminals are unaffected.
+- **A persistent update notice now sits directly under the prompt input.** When a newer release is available the footer shows a yellow `↑ Update available — vX · /update` line; once a release has been installed in the background it switches to a restart-to-apply message instead of pointing at `/update`, and it clears after you restart onto the new version. The line is suppressed for dismissed versions, disabled auto-update, and source checkouts.
+
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.46.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
+
 ## 0.45.0 (2026-06-14)
 
 - **Agent-tracing dashboard.** Added `pythinker dashboard` — a local web UI for inspecting sessions, wire events, context messages, tool statistics, and usage over time. It is also reachable from the interactive shell via the `/reports` slash command (aliased `/dashboard`).

pythinker_code/acp/session.py

@@ -17,6 +17,7 @@ from pythinker_code.acp.convert import (
 from pythinker_code.acp.types import ACPContentBlock
 from pythinker_code.app import PythinkerCLI
 from pythinker_code.soul import LLMNotSet, LLMNotSupported, MaxStepsReached, RunCancelled
+from pythinker_code.soul.btw import generate_max_steps_handoff
 from pythinker_code.tools import extract_key_argument
 from pythinker_code.utils.logging import logger
 from pythinker_code.wire.types import (
@@ -242,6 +243,13 @@ class ACPSession:
             raise acp.RequestError.internal_error({"error": str(e)}) from e
         except MaxStepsReached as e:
             logger.warning("Max steps reached: {n_steps}", n_steps=e.n_steps)
+            try:
+                handoff = await generate_max_steps_handoff(self._cli.soul)
+            except Exception:
+                logger.warning("Max-steps handoff failed", exc_info=True)
+                handoff = None
+            if handoff:
+                await self._send_text(f"\n── handoff ──\n{handoff}")
             return acp.PromptResponse(stop_reason="max_turn_requests")
         except RunCancelled:
             logger.info("Prompt cancelled by user")

pythinker_code/agents/default/agent.yaml

@@ -12,6 +12,9 @@ agent:
     # - "pythinker_code.tools.think:Think"
     - "pythinker_code.tools.ask_user:AskUserQuestion"
     - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.tool_search:ToolSearch"
+    - "pythinker_code.tools.worktree:EnterWorktree"
+    - "pythinker_code.tools.worktree:ExitWorktree"
     - "pythinker_code.tools.goal:UpdateGoal"
     - "pythinker_code.tools.progress:Progress"
     - "pythinker_code.tools.suggest:Suggest"
@@ -35,6 +38,7 @@ agent:
     - "pythinker_code.tools.web:FetchURL"
     - "pythinker_code.tools.mcp_resource:ListMcpResources"
     - "pythinker_code.tools.mcp_resource:ReadMcpResource"
+    - "pythinker_code.tools.mcp_resource:InvokeMcpPrompt"
     - "pythinker_code.tools.plan:ExitPlanMode"
     - "pythinker_code.tools.plan.enter:EnterPlanMode"
   subagents:

pythinker_code/app.py

@@ -254,6 +254,21 @@ class PythinkerCLI:
             config.loop_control.max_ralph_iterations = max_ralph_iterations
         logger.info("Loaded config: {config}", config=config)
 
+        # Install the plugin activation policy for this session so artifact
+        # collectors (skills/agents/commands/hooks/mcp) honor config-configured
+        # enable-state and the external (Claude/Codex) opt-in.
+        from pythinker_code.plugin.policy import policy_from_config, set_plugin_policy
+
+        set_plugin_policy(
+            policy_from_config(
+                config.plugins.discover_external,
+                config.plugins.external_exec,
+                config.plugins.enabled,
+                config.plugins.disabled,
+                config.plugins.options,
+            )
+        )
+
         _phase_t = time.monotonic()
         oauth = OAuthManager(config)
 
@@ -392,10 +407,12 @@ class PythinkerCLI:
             # Already in plan mode from restored session, trigger activation reminder
             soul.schedule_plan_activation_reminder()
 
-        # Create and inject hook engine
+        # Create and inject hook engine. Enabled plugins contribute lifecycle
+        # hooks; config hooks come first so a project hook is never shadowed.
         from pythinker_code.hooks.engine import HookEngine
+        from pythinker_code.plugin.integration import plugin_hook_defs
 
-        hook_engine = HookEngine(config.hooks, cwd=str(session.work_dir))
+        hook_engine = HookEngine([*config.hooks, *plugin_hook_defs()], cwd=str(session.work_dir))
         if config.disabled_project_hooks:
             # The load-time logger.warning only reaches shell users; publish a
             # notification so web/ACP frontends also learn why their project

pythinker_code/cli/__init__.py

@@ -270,9 +270,13 @@ def _load_mcp_configs_from_cli_inputs(
             file_configs.append(project_mcp_file)
 
     configs: list[Any] = []
+    from pythinker_code.exception import MCPConfigError
+
+    from .mcp import prepare_mcp_config_dict
+
     for conf in file_configs:
         try:
-            configs.append(json.loads(conf.read_text(encoding="utf-8")))
+            configs.append(prepare_mcp_config_dict(json.loads(conf.read_text(encoding="utf-8"))))
         except json.JSONDecodeError as e:
             raise typer.BadParameter(
                 f"Invalid JSON in MCP config file {conf}: {e}",
@@ -283,12 +287,19 @@ def _load_mcp_configs_from_cli_inputs(
                 f"Cannot read MCP config file {conf}: {e}",
                 param_hint="--mcp-config-file",
             ) from e
+        except MCPConfigError as e:
+            raise typer.BadParameter(
+                f"Invalid MCP config in file {conf}: {e}",
+                param_hint="--mcp-config-file",
+            ) from e
 
     for conf in raw_mcp_config:
         try:
-            configs.append(json.loads(conf))
+            configs.append(prepare_mcp_config_dict(json.loads(conf)))
         except json.JSONDecodeError as e:
             raise typer.BadParameter(f"Invalid JSON: {e}", param_hint="--mcp-config") from e
+        except MCPConfigError as e:
+            raise typer.BadParameter(f"Invalid MCP config: {e}", param_hint="--mcp-config") from e
 
     for path in _yaml_files_with_misplaced_mcp_servers():
         from pythinker_code.utils.logging import logger

pythinker_code/cli/mcp.py

@@ -2,7 +2,7 @@ import contextlib
 import json
 import os
 from pathlib import Path, PurePath
-from typing import Annotated, Any, Literal
+from typing import Annotated, Any, Literal, cast
 
 import typer
 
@@ -27,6 +27,35 @@ def ensure_docker_rm(command: str, args: list[str]) -> list[str]:
     return [args[0], "--rm", *args[1:]]
 
 
+def apply_docker_rm_to_mcp_config_dict(config: dict[str, Any]) -> dict[str, Any]:
+    """Inject ``--rm`` into stdio docker/podman servers when loading mcp.json (mcpext-3)."""
+    servers = config.get("mcpServers")
+    if not isinstance(servers, dict):
+        return config
+    typed_servers = cast(dict[str, Any], servers)
+    for raw_server in typed_servers.values():
+        if not isinstance(raw_server, dict):
+            continue
+        server = cast(dict[str, Any], raw_server)
+        command = server.get("command")
+        if not isinstance(command, str):
+            continue
+        raw_args = server.get("args")
+        args: list[str] = []
+        if isinstance(raw_args, list):
+            args = [str(item) for item in cast(list[object], raw_args)]
+        server["args"] = ensure_docker_rm(command, args)
+    return config
+
+
+def prepare_mcp_config_dict(config: dict[str, Any]) -> dict[str, Any]:
+    """Apply portable MCP config fixes before validation (docker ``--rm``, name normalization)."""
+    from pythinker_code.utils.mcp_names import normalize_mcp_servers_in_config
+
+    config = apply_docker_rm_to_mcp_config_dict(config)
+    return normalize_mcp_servers_in_config(config)
+
+
 def get_global_mcp_config_file() -> Path:
     """Get the global MCP config file path."""
     from pythinker_code.share import get_share_dir
@@ -39,6 +68,8 @@ def _load_mcp_config() -> dict[str, Any]:
     from fastmcp.mcp_config import MCPConfig
     from pydantic import ValidationError
 
+    from pythinker_code.exception import MCPConfigError
+
     mcp_file = get_global_mcp_config_file()
     if not mcp_file.exists():
         return {"mcpServers": {}}
@@ -52,7 +83,30 @@ def _load_mcp_config() -> dict[str, Any]:
     except ValidationError as e:
         raise typer.BadParameter(f"Invalid MCP config in '{mcp_file}': {e}") from e
 
-    return config
+    try:
+        return prepare_mcp_config_dict(config)
+    except MCPConfigError as e:
+        raise typer.BadParameter(str(e)) from e
+
+
+def _resolve_mcp_server_key(name: str, servers: dict[str, Any]) -> str:
+    """Resolve a user-supplied MCP server name to the stored config key."""
+    from pythinker_code.exception import MCPConfigError
+    from pythinker_code.utils.mcp_names import normalize_mcp_server_name
+
+    if name in servers:
+        return name
+    try:
+        normalized = normalize_mcp_server_name(name)
+    except MCPConfigError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    if normalized in servers:
+        if normalized != name:
+            typer.echo(f"Resolved MCP server '{name}' to '{normalized}'.")
+        return normalized
+    typer.echo(f"MCP server '{name}' not found.", err=True)
+    raise typer.Exit(code=1)
 
 
 def _save_mcp_config(config: dict[str, Any]) -> None:
@@ -71,18 +125,23 @@ def _save_mcp_config(config: dict[str, Any]) -> None:
         fh.write(payload)
 
 
-def _get_mcp_server(name: str, *, require_remote: bool = False) -> dict[str, Any]:
-    """Get MCP server config by name."""
+def _mcp_servers_from_config(config: dict[str, Any]) -> dict[str, Any]:
+    raw_servers = config.get("mcpServers", {})
+    if isinstance(raw_servers, dict):
+        return cast(dict[str, Any], raw_servers)
+    return {}
+
+
+def _get_mcp_server(name: str, *, require_remote: bool = False) -> tuple[str, dict[str, Any]]:
+    """Get MCP server config by name (accepts raw or normalized keys)."""
     config = _load_mcp_config()
-    servers = config.get("mcpServers", {})
-    if name not in servers:
-        typer.echo(f"MCP server '{name}' not found.", err=True)
-        raise typer.Exit(code=1)
-    server = servers[name]
+    servers = _mcp_servers_from_config(config)
+    stored_name = _resolve_mcp_server_key(name, servers)
+    server = cast(dict[str, Any], servers[stored_name])
     if require_remote and "url" not in server:
-        typer.echo(f"MCP server '{name}' is not a remote server.", err=True)
+        typer.echo(f"MCP server '{stored_name}' is not a remote server.", err=True)
         raise typer.Exit(code=1)
-    return server
+    return stored_name, server
 
 
 def _parse_key_value_pairs(
@@ -171,8 +230,18 @@ def mcp_add(
     ] = None,
 ):
     """Add an MCP server."""
+    from pythinker_code.exception import MCPConfigError
+    from pythinker_code.utils.mcp_names import normalize_mcp_server_name
+
     config = _load_mcp_config()
     server_args = server_args or []
+    try:
+        stored_name = normalize_mcp_server_name(name)
+    except MCPConfigError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    if stored_name != name:
+        typer.echo(f"Normalized MCP server name '{name}' to '{stored_name}'.")
 
     if transport not in {"stdio", "http"}:
         typer.echo(f"Unsupported transport: {transport}.", err=True)
@@ -221,9 +290,12 @@ def mcp_add(
 
     if "mcpServers" not in config:
         config["mcpServers"] = {}
-    config["mcpServers"][name] = server_config
+    if stored_name in config["mcpServers"]:
+        typer.echo(f"MCP server '{stored_name}' already exists.", err=True)
+        raise typer.Exit(code=1)
+    config["mcpServers"][stored_name] = server_config
     _save_mcp_config(config)
-    typer.echo(f"Added MCP server '{name}' to {get_global_mcp_config_file()}.")
+    typer.echo(f"Added MCP server '{stored_name}' to {get_global_mcp_config_file()}.")
 
 
 @cli.command("remove")
@@ -234,11 +306,12 @@ def mcp_remove(
     ],
 ):
     """Remove an MCP server."""
-    _get_mcp_server(name)
     config = _load_mcp_config()
-    del config["mcpServers"][name]
+    servers = _mcp_servers_from_config(config)
+    stored_name = _resolve_mcp_server_key(name, servers)
+    del config["mcpServers"][stored_name]
     _save_mcp_config(config)
-    typer.echo(f"Removed MCP server '{name}' from {get_global_mcp_config_file()}.")
+    typer.echo(f"Removed MCP server '{stored_name}' from {get_global_mcp_config_file()}.")
 
 
 def _oauth_token_storage(server_url: str) -> Any:
@@ -306,21 +379,25 @@ def mcp_auth(
     import asyncio
 
     server = _get_mcp_server(name, require_remote=True)
-    if server.get("auth") != "oauth":
-        typer.echo(f"MCP server '{name}' does not use OAuth. Add with --auth oauth.", err=True)
+    stored_name, server_config = server
+    if server_config.get("auth") != "oauth":
+        typer.echo(
+            f"MCP server '{stored_name}' does not use OAuth. Add with --auth oauth.",
+            err=True,
+        )
         raise typer.Exit(code=1)
 
     async def _auth() -> None:
         import fastmcp
 
-        typer.echo(f"Authorizing with '{name}'...")
+        typer.echo(f"Authorizing with '{stored_name}'...")
         typer.echo("A browser window will open for authorization.")
 
-        client = fastmcp.Client({"mcpServers": {name: server}})
+        client = fastmcp.Client({"mcpServers": {stored_name: server_config}})
         try:
             async with client:
                 tools = await client.list_tools()
-                typer.echo(f"Successfully authorized with '{name}'.")
+                typer.echo(f"Successfully authorized with '{stored_name}'.")
                 typer.echo(f"Available tools: {len(tools)}")
         except Exception as e:
             typer.echo(f"Authorization failed: {type(e).__name__}: {e}", err=True)
@@ -337,7 +414,7 @@ def mcp_reset_auth(
     ],
 ):
     """Reset OAuth authorization for an MCP server (clear cached tokens)."""
-    server = _get_mcp_server(name, require_remote=True)
+    stored_name, server = _get_mcp_server(name, require_remote=True)
 
     try:
         import asyncio
@@ -349,7 +426,7 @@ def mcp_reset_auth(
                 await result
 
         asyncio.run(_clear())
-        typer.echo(f"OAuth tokens cleared for '{name}'.")
+        typer.echo(f"OAuth tokens cleared for '{stored_name}'.")
     except ImportError:
         typer.echo("OAuth support not available.", err=True)
         raise typer.Exit(code=1) from None
@@ -368,18 +445,18 @@ def mcp_test(
     """Test connection to an MCP server and list available tools."""
     import asyncio
 
-    server = _get_mcp_server(name)
+    stored_name, server = _get_mcp_server(name)
 
     async def _test() -> None:
         import fastmcp
 
-        typer.echo(f"Testing connection to '{name}'...")
-        client = fastmcp.Client({"mcpServers": {name: server}})
+        typer.echo(f"Testing connection to '{stored_name}'...")
+        client = fastmcp.Client({"mcpServers": {stored_name: server}})
 
         try:
             async with client:
                 tools = await client.list_tools()
-                typer.echo(f"✓ Connected to '{name}'")
+                typer.echo(f"✓ Connected to '{stored_name}'")
                 typer.echo(f"  Available tools: {len(tools)}")
                 if tools:
                     typer.echo("  Tools:")