deepagents-code 0.1.22__tar.gz → 0.1.23__tar.gz

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/.gitignore

@@ -251,3 +251,6 @@ CLAUDE.md
 libs/cli/frontend/node_modules/
 libs/cli/frontend/dist/
 node_modules/
+
+# Generated at build time by libs/code/hatch_build.py (stamps the release commit)
+libs/code/deepagents_code/_build_info.py

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/AGENTS.md

@@ -69,7 +69,7 @@ Casts are acceptable when the type violation is the point of the test (for examp
 
 ## SDK dependency pin
 
-`deepagents-code` pins an exact `deepagents==X.Y.Z` version in `pyproject.toml`. When developing features that depend on new SDK functionality, bump this pin as part of the same PR. A CI check verifies the pin matches the current SDK version at release time (unless bypassed with `dangerous-skip-sdk-pin-check`).
+`deepagents-code` pins an exact `deepagents==X.Y.Z` version in `pyproject.toml`. When developing features that depend on new SDK functionality, bump this pin as part of the same PR. A CI check verifies the pin is not older than the current SDK version at release time (unless bypassed with `dangerous-skip-sdk-pin-check`); pins ahead of the workspace SDK are allowed for intentional prerelease coordination.
 
 For a persistent editable `dcode-dev` install that stays separate from a released install, see [Local dev installs](./DEVELOPMENT.md#local-dev-installs) in the development guide.
 

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 # Deep Agents Code Changelog
 
+## [0.1.23](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.22...deepagents-code==0.1.23) (2026-06-25)
+
+### Features
+
+* Collect Tavily key during onboarding ([#4233](https://github.com/langchain-ai/deepagents/issues/4233)) ([e321cba](https://github.com/langchain-ai/deepagents/commit/e321cba5701313e974f979069186680f1a39587c))
+* Surface `/auth` in `/trace not-configured` hint ([#4206](https://github.com/langchain-ai/deepagents/issues/4206)) ([392e410](https://github.com/langchain-ai/deepagents/commit/392e410e48639a56fda5e35b6f7f85a5215cce9c))
+* Add Opus 4.8 to recommended models ([#4204](https://github.com/langchain-ai/deepagents/issues/4204)) ([8faf2b0](https://github.com/langchain-ai/deepagents/commit/8faf2b025f8429481a41a3e65544d26614e53589))
+
+### Bug Fixes
+
+* `--reinstall` on `/install` so upgrades rebuild a clean env ([#4196](https://github.com/langchain-ai/deepagents/issues/4196)) ([5e152ac](https://github.com/langchain-ai/deepagents/commit/5e152ac0256d64376f96b293f8844bc8acc993ec))
+* Suppress auto-update migration notice on fresh installs ([#4224](https://github.com/langchain-ai/deepagents/issues/4224)) ([eb8ff80](https://github.com/langchain-ai/deepagents/commit/eb8ff809a1b3130a261083c66a193e532095c6db))
+* Bake release commit into `dcode doctor` ([#4225](https://github.com/langchain-ai/deepagents/issues/4225)) ([6dc0246](https://github.com/langchain-ai/deepagents/commit/6dc0246f5c6e9170e05191e1c82fad6975ac945c))
+* Drop redundant version from "already up to date" message ([#4223](https://github.com/langchain-ai/deepagents/issues/4223)) ([5d080df](https://github.com/langchain-ai/deepagents/commit/5d080df2776d380214bf20ae31266b9628e4e5b0))
+* Note subscription plans unusable for Anthropic in `/auth` ([#4207](https://github.com/langchain-ai/deepagents/issues/4207)) ([28cd19d](https://github.com/langchain-ai/deepagents/commit/28cd19db08bacf981ab2c91195638e66072816fe))
+
 ## [0.1.22](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.21...deepagents-code==0.1.22) (2026-06-24)
 
 ### Features

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/Makefile

@@ -108,7 +108,7 @@ check: lint check_imports test
 	uv lock --check
 	@echo "🔗 Checking SDK pin against workspace SDK (advisory)..."
 	@uv run --all-groups python "$(REPO_ROOT)/.github/scripts/check_sdk_pin.py" || \
-		{ rc=$$?; [ $$rc -eq 1 ] && echo "⚠️  SDK pin drift (advisory, non-fatal)." || exit $$rc; }
+		{ rc=$$?; [ $$rc -eq 1 ] && echo "⚠️  Stale SDK pin (advisory, non-fatal)." || exit $$rc; }
 	@echo "✅ All local CI checks passed!"
 
 ######################

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents-code
-Version: 0.1.22
+Version: 0.1.23
 Summary: Terminal interface for Deep Agents - interactive AI agent with file operations, shell access, and sub-agent capabilities.
 Project-URL: Homepage, https://docs.langchain.com/oss/python/deepagents/overview
 Project-URL: Documentation, https://reference.langchain.com/python/deepagents/
@@ -27,7 +27,7 @@ Classifier: Topic :: Terminals
 Requires-Python: <4.0,>=3.11
 Requires-Dist: aiosqlite<1.0.0,>=0.22.1
 Requires-Dist: deepagents-acp<1.0.0,>=0.0.8
-Requires-Dist: deepagents==0.6.11
+Requires-Dist: deepagents==0.7.0a2
 Requires-Dist: httpx<1.0.0,>=0.28.1
 Requires-Dist: langchain-anthropic<2.0.0,>=1.4.7
 Requires-Dist: langchain-google-genai<5.0.0,>=4.2.5

deepagents_code-0.1.23/deepagents_code/_build_info.py

@@ -0,0 +1,3 @@
+"""Generated at build time. Do not edit or commit."""
+
+BUILD_COMMIT = "649443a"

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/deepagents_code/_version.py

@@ -2,7 +2,7 @@
 
 # Keep the `x-release-please-version` annotation — release-please uses it to
 # bump `__version__` in sync with `pyproject.toml` on every release PR.
-__version__ = "0.1.22"  # x-release-please-version
+__version__ = "0.1.23"  # x-release-please-version
 
 DOCS_URL = "https://docs.langchain.com/oss/python/deepagents/code"
 """URL for `deepagents-code` documentation."""

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/deepagents_code/agent.py

@@ -67,7 +67,6 @@ from deepagents_code.config import (
     settings,
 )
 from deepagents_code.configurable_model import ConfigurableModelMiddleware
-from deepagents_code.filesystem_empty_result import _FilesystemEmptyResultMiddleware
 from deepagents_code.integrations.sandbox_factory import get_default_working_dir
 from deepagents_code.local_context import (
     LocalContextMiddleware,
@@ -1420,7 +1419,6 @@ def create_cli_agent(
     # Build middleware stack based on enabled features
     agent_middleware: list[AgentMiddleware[Any, Any]] = [
         ConfigurableModelMiddleware(),
-        _FilesystemEmptyResultMiddleware(),
     ]
 
     # Resume state: declares the `_context_tokens` and `_model_spec` channels

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/deepagents_code/app.py

@@ -1749,6 +1749,22 @@ class DeepAgentsApp(App):
         self._launch_init_requested = launch_init
         """Whether startup should show onboarding during the initial paint."""
 
+        self._onboarding_session = launch_init
+        """Whether onboarding runs this session (constant for the session).
+
+        Unlike `_launch_init_requested`, which is cleared once the flow starts,
+        this stays set so background workers (e.g. the optional-tools check)
+        can register missing-dependency notices silently instead of toasting
+        over the onboarding modals.
+
+        Intentionally never reset, including on onboarding completion: the
+        optional-tools check is scheduled once at startup and may not have run
+        by the time the flow finishes, so clearing this would let that check
+        toast the very "Web search disabled" notice onboarding means to defer.
+        Leaving it set for the whole session is harmless because the check runs
+        exactly once.
+        """
+
         self._launch_init_running = False
         """Re-entry guard for launch init modals."""
 
@@ -2909,7 +2925,13 @@ class DeepAgentsApp(App):
         # update (already notified within CACHE_TTL) does not open the
         # modal, so toasts must still fire or returning users never
         # see the warning.
-        suppress_toasts = self._update_modal_pending.is_set()
+        # Onboarding suppresses too: the flow covers integrations (and
+        # prompts for a Tavily key) itself, so a "Web search disabled"
+        # toast over the onboarding modals is noise. Entries stay
+        # reachable via ctrl+n.
+        suppress_toasts = (
+            self._update_modal_pending.is_set() or self._onboarding_session
+        )
 
         for tool in missing:
             notification = build_missing_tool_notification(tool)
@@ -3461,11 +3483,18 @@ class DeepAgentsApp(App):
                 )
             else:
                 from deepagents_code.extras_info import ExtrasIntrospectionError
-                from deepagents_code.update_check import install_package_command
+                from deepagents_code.update_check import (
+                    ToolRequirementIntrospectionError,
+                    install_package_command,
+                )
 
                 try:
                     install_cmd = install_package_command(missing.package)
-                except (ValueError, ExtrasIntrospectionError) as exc:
+                except (
+                    ValueError,
+                    ExtrasIntrospectionError,
+                    ToolRequirementIntrospectionError,
+                ) as exc:
                     logger.debug(
                         "install_package_command failed; falling back to "
                         "manual hint: %s",
@@ -4313,7 +4342,8 @@ class DeepAgentsApp(App):
         """Handle the `/install <extra>` slash command.
 
         Adds an optional extra (e.g. `quickjs`, `daytona`) to the installed
-        dcode tool by re-running `uv tool install -U 'deepagents-code[<extra>]'`.
+        dcode tool by re-running
+        `uv tool install --reinstall -U 'deepagents-code[<extra>]'`.
         Refuses unknown extras unless the user passes a `--force` token.
 
         Args:
@@ -6102,6 +6132,7 @@ class DeepAgentsApp(App):
                 return
 
             model_spec, provider = result
+            await self._prompt_launch_tavily()
             if self._connecting:
                 # Bound the wait so a stuck server never traps onboarding.
                 # Server startup typically completes in seconds; a minute is
@@ -6186,6 +6217,59 @@ class DeepAgentsApp(App):
                 return
         await self._switch_model(model_spec, announce_unchanged=False)
 
+    async def _prompt_launch_tavily(self) -> None:
+        """Optionally collect and store a Tavily web-search key during onboarding.
+
+        Skipped when a Tavily key is already configured (env or stored). A
+        blank submission or Escape stores nothing; a non-empty key is persisted
+        via the same `auth_store` path `/auth` uses. The key is also exported to
+        the process environment (`apply_stored_service_credentials`) so a server
+        respawn this session picks it up; the already-running server keeps its
+        spawn-time tools, so web search takes full effect on the next launch (or
+        after a restart).
+        """
+        from deepagents_code.config import settings
+
+        if settings.has_tavily:
+            return
+
+        from deepagents_code.widgets.auth import AuthPromptScreen, AuthResult
+
+        result = await self._push_screen_wait(
+            AuthPromptScreen(
+                "tavily",
+                "TAVILY_API_KEY",
+                reason=(
+                    "Web search is optional but strongly recommended to enhance "
+                    "your agent's capabilities."
+                ),
+                allow_empty_submit=True,
+                input_placeholder="Tavily API key (optional)",
+                submit_label="Enter save/skip",
+            )
+        )
+        if result is not AuthResult.SAVED:
+            return
+
+        from deepagents_code.model_config import apply_stored_service_credentials
+
+        apply_stored_service_credentials()
+
+        # `apply_stored_service_credentials` is best-effort: it swallows a
+        # corrupt-store read with only a `logger.warning`, which is invisible
+        # inside a Textual session. The user just saw the key accepted, so
+        # confirm it actually reached the environment; if not, say so rather
+        # than letting web search silently stay disabled. Reaching this branch
+        # means `has_tavily` was False at bootstrap, so a populated
+        # `TAVILY_API_KEY` here can only come from the export above.
+        if not os.environ.get("TAVILY_API_KEY"):
+            self.notify(
+                "Saved your Tavily key, but couldn't activate it this "
+                "session. Restart Deep Agents Code, or re-add it with /auth.",
+                severity="warning",
+                markup=False,
+            )
+
     async def _finish_launch_init(self, *, name: str | None) -> None:
         """Persist onboarding completion and, when given, mount the welcome.
 
@@ -6956,7 +7040,8 @@ class DeepAgentsApp(App):
             await self._mount_message(
                 AppMessage(
                     "LangSmith tracing is not configured. "
-                    "Set LANGSMITH_API_KEY and LANGSMITH_TRACING=true to enable.",
+                    "Run `/auth` and select LangSmith to enable tracing, or set "
+                    "LANGSMITH_API_KEY and LANGSMITH_TRACING=true.",
                 ),
             )
             return
@@ -6974,7 +7059,8 @@ class DeepAgentsApp(App):
                 AppMessage(
                     "The `langsmith` package is not installed. "
                     "Install it with "
-                    "`uv tool install -U deepagents-code --with langsmith` "
+                    "`uv tool install --reinstall -U deepagents-code "
+                    "--with langsmith` "
                     "to enable `/trace`.",
                 ),
             )
@@ -11798,7 +11884,7 @@ class DeepAgentsApp(App):
     def _ensure_restart_prompt_loaded() -> None:
         """Load the restart-prompt modal before any in-place self-upgrade.
 
-        `/install` runs `uv tool install -U 'deepagents-code[...]'`, which
+        `/install` runs `uv tool install --reinstall -U 'deepagents-code[...]'`, which
         rewrites deepagents-code's own on-disk package tree while this process
         is running. Modules already in `sys.modules` keep working from memory,
         but a *first* import after the rewrite reads the mutated (or
@@ -11835,11 +11921,11 @@ class DeepAgentsApp(App):
         redundant hint:
 
         - Owned + idle: show the prompt (its button is the call to action). If
-          the prompt can't be shown, fall back to a `/restart` hint.
+            the prompt can't be shown, fall back to a `/restart` hint.
         - Owned + busy/connecting: a restart cancels in-flight work, so point
-          at `/restart` for once the current task finishes.
+            at `/restart` for once the current task finishes.
         - No owned subprocess (remote server): `/restart` can't respawn it, so a
-          full relaunch is the only way to load the package.
+            full relaunch is the only way to load the package.
 
         Args:
             label: Installed extra/package name, surfaced in the prompt title.
@@ -11865,8 +11951,9 @@ class DeepAgentsApp(App):
         try:
             from deepagents_code.widgets.restart_prompt import RestartPromptScreen
         except ModuleNotFoundError:
-            # `/install` runs `uv tool install -U 'deepagents-code[...]'`, which
-            # can rewrite deepagents-code's own on-disk package tree mid-session
+            # `/install` runs `uv tool install --reinstall -U
+            # 'deepagents-code[...]'`, which can rewrite deepagents-code's own
+            # on-disk package tree mid-session
             # (see `_ensure_restart_prompt_loaded`). A first import of the modal
             # here may then fail with `ModuleNotFoundError`. Degrade to the
             # manual `/restart` hint instead of crashing the TUI. The catch is

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/deepagents_code/config.py

@@ -3426,11 +3426,18 @@ def _create_model_via_init(
                 )
             else:
                 from deepagents_code.extras_info import ExtrasIntrospectionError
-                from deepagents_code.update_check import install_package_command
+                from deepagents_code.update_check import (
+                    ToolRequirementIntrospectionError,
+                    install_package_command,
+                )
 
                 try:
                     install_cmd = install_package_command(package)
-                except (ValueError, ExtrasIntrospectionError) as exc:
+                except (
+                    ValueError,
+                    ExtrasIntrospectionError,
+                    ToolRequirementIntrospectionError,
+                ) as exc:
                     logger.debug(
                         "install_package_command failed; falling back to "
                         "manual hint: %s",

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/deepagents_code/doctor.py

@@ -75,15 +75,49 @@ def _sdk_version() -> tuple[str, bool]:
     return "unknown", False
 
 
+def _build_commit() -> str | None:
+    """Return the commit stamped into the package at build time, if present.
+
+    Released wheels carry a generated `_build_info.py` (see `hatch_build.py`);
+    editable and local installs do not, so this returns `None` for them.
+    """
+    try:
+        from deepagents_code._build_info import (  # ty: ignore[unresolved-import]  # generated at build time
+            BUILD_COMMIT,
+        )
+    except ImportError:
+        return None
+    except Exception:  # a corrupt stamp must never crash `doctor`
+        logger.debug("Build-info module present but failed to import", exc_info=True)
+        return None
+    commit = (BUILD_COMMIT or "").strip()
+    return commit or None
+
+
 def _commit_hash(path: str) -> str:
-    """Return the short git commit hash for a source path, if available.
+    """Return the short git commit hash for the install, if available.
+
+    Prefers the commit stamped into a released wheel at build time, but only for
+    non-editable installs: an editable install may carry a stale stamp from a
+    prior local build (the generated file is gitignored and survives a failed
+    build), so it always probes the live git working tree, which reflects local
+    changes.
 
     Args:
         path: Directory used as the git command working directory.
 
     Returns:
-        The short commit hash, or `unknown` when git metadata cannot be read.
+        The short commit hash, or `unknown` when no commit can be determined.
     """
+    baked = _build_commit()
+    if baked:
+        from deepagents_code.config import _is_editable_install
+
+        # A baked commit only describes a built wheel; ignore it for editable
+        # installs so a stale stamp can't mask the live working-tree commit.
+        if not _is_editable_install():
+            return baked
+
     import shutil
     import subprocess  # noqa: S404  # fixed-argv git metadata probe
     from pathlib import Path

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/deepagents_code/main.py

@@ -2372,7 +2372,7 @@ def cli_main() -> None:
             except ImportError as exc:
                 msg = (
                     f"ACP dependencies not available: {exc}\n"
-                    "Install with: uv tool install -U deepagents-code "
+                    "Install with: uv tool install --reinstall -U deepagents-code "
                     "--with deepagents-acp\n"
                 )
                 sys.stderr.write(msg)

{deepagents_code-0.1.22 → deepagents_code-0.1.23}/deepagents_code/update_check.py

@@ -291,7 +291,8 @@ def get_latest_version(
     except ImportError:
         logger.warning(
             "requests package not installed — update checks disabled. "
-            "Install with: uv tool install -U deepagents-code --with requests"
+            "Install with: uv tool install --reinstall -U deepagents-code "
+            "--with requests"
         )
         return cached_version
 
@@ -1876,6 +1877,8 @@ def _uv_tool_install_command(
     include_prereleases: bool | None,
     distribution_name: str,
     extras_to_add: Iterable[str] = (),
+    with_packages_to_add: Iterable[str] = (),
+    reinstall: bool = False,
 ) -> str:
     """Return the receipt-preserving `uv tool install -U` command.
 
@@ -1885,6 +1888,19 @@ def _uv_tool_install_command(
             `None`, follows the installed version's channel.
         distribution_name: Name of the installed distribution to inspect.
         extras_to_add: Extra names to merge with already-installed extras.
+        with_packages_to_add: Package names to merge with the receipt's existing
+            `--with` packages. Names already present (compared canonically) are
+            not duplicated; genuinely new names are appended after the preserved
+            ones. Callers must validate these names before passing them — the
+            builder only `shlex.quote`-s them.
+        reinstall: When `True`, add `--reinstall` so uv rebuilds the tool
+            environment from scratch instead of patching it in place. An
+            in-place `-U` upgrade can leave stale files behind (e.g. an old
+            `tools.py` or its cached bytecode), which has been observed to
+            produce a half-updated env that crashes the next server start with
+            an `ImportError`; the preserved `--python` interpreter and `--with`
+            packages still apply, so the rebuild keeps the existing tool
+            context.
 
     Raises:
         ExtrasIntrospectionError: If a metadata-sourced extra name fails PEP 508
@@ -1906,12 +1922,17 @@ def _uv_tool_install_command(
     except ValueError as exc:
         msg = f"Distribution metadata yielded an invalid extra name: {exc}"
         raise ExtrasIntrospectionError(msg) from exc
-    cmd = "uv tool install -U"
+    cmd = "uv tool install --reinstall -U" if reinstall else "uv tool install -U"
     python = _uv_tool_python()
     if python is not None:
         cmd += f" --python {shlex.quote(python)}"
     cmd += f" {requirement}"
-    with_packages = _uv_tool_with_packages(distribution_name=distribution_name)
+    with_packages = list(_uv_tool_with_packages(distribution_name=distribution_name))
+    known = {canonicalize_name(package) for package in with_packages}
+    for package in with_packages_to_add:
+        if canonicalize_name(package) not in known:
+            with_packages.append(package)
+            known.add(canonicalize_name(package))
     for package in with_packages:
         cmd += f" --with {shlex.quote(package)}"
     if _resolve_include_prereleases(include_prereleases):
@@ -2047,30 +2068,42 @@ def install_package_command(
 
     The result is built for *execution* (via `perform_install_package`), not for
     display — surfacing raw `uv tool` invocations to the user is intentionally
-    avoided. `package` is validated and then `shlex.quote`-d: the validation
-    already blocks shell metacharacters, so the quoting is defense in depth that
-    keeps the command safe even if the pattern is later loosened.
-
-    Already-installed extras are folded into the `deepagents-code[...]`
-    requirement via the shared `_dcode_extras_requirement` helper, the same way
-    `install_extras_command` builds its requirement. Without this the reinstall
-    would replace the tool with a plain `deepagents-code`, silently dropping any
-    extras the user added through `/install <extra>`.
+    avoided. `package` is validated here against PEP 508 grammar and then
+    `shlex.quote`-d by the shared builder: the validation already blocks shell
+    metacharacters, so the quoting is defense in depth that keeps the command
+    safe even if the pattern is later loosened.
+
+    Delegates to `_uv_tool_install_command` (the same builder the extras path
+    uses), passing the new package as a `--with` requirement. That builder folds
+    already-installed extras into the `deepagents-code[...]` requirement, and
+    preserves the uv-managed Python interpreter, the receipt's existing `--with`
+    packages, and the installed pre-release channel. Without this, reinstalling
+    to add a second package would replace the tool with a plain `deepagents-code`
+    (dropping extras the user added through `/install <extra>`), rebuild with
+    only the newest `--with` package (dropping previously configured custom
+    providers), or silently downgrade a pre-release install to the latest stable.
+
+    Like the extras path (`_install_extra_uv_tool_command`), passes
+    `reinstall=True` so the upgrade rebuilds the tool environment cleanly; see
+    `_uv_tool_install_command`'s `reinstall` parameter for why an in-place
+    upgrade is unsafe.
 
     Args:
         package: Package name to install into the existing tool environment.
         distribution_name: Name of the installed distribution to inspect for
-            already-installed extras.
+            already-installed extras and uv receipt requirements.
 
     Returns:
         Shell command string suitable for execution via the shell.
 
     Raises:
-        ExtrasIntrospectionError: If installed extras cannot be determined
-            safely from distribution metadata (refused rather than risk
-            dropping them).
-        ValueError: If `package` or any already-installed extra fails PEP 508
-            validation.
+        ValueError: If `package` fails PEP 508 validation.
+
+    Propagates `ExtrasIntrospectionError` if installed extras cannot be
+    determined safely from distribution metadata (or a metadata-sourced extra
+    name fails PEP 508 validation), and `ToolRequirementIntrospectionError` if
+    the uv tool receipt's interpreter or `--with` packages cannot be determined
+    safely.
     """
     if not _PACKAGE_NAME_RE.fullmatch(package):
         msg = (
@@ -2078,19 +2111,14 @@ def install_package_command(
             f"({_PACKAGE_NAME_RE.pattern})"
         )
         raise ValueError(msg)
-    from deepagents_code.extras_info import (
-        ExtrasIntrospectionError,
-        installed_extra_names,
+    return _uv_tool_install_command(
+        version=None,
+        include_prereleases=None,
+        distribution_name=distribution_name,
+        with_packages_to_add=(package,),
+        reinstall=True,
     )
 
-    try:
-        extras = installed_extra_names(distribution_name, strict=True)
-    except ExtrasIntrospectionError as exc:
-        msg = str(exc)
-        raise ExtrasIntrospectionError(msg) from exc
-    requirement = _dcode_extras_requirement(extras)
-    return f"uv tool install -U {requirement} --with {shlex.quote(package)}"
-
 
 def install_extras_command(extras: Iterable[str]) -> str:
     """Return the install-script command that installs dcode extras.
@@ -2183,6 +2211,10 @@ def _install_extra_uv_tool_command(
 ) -> str:
     """Return the receipt-preserving uv command that installs one dcode extra.
 
+    Passes `reinstall=True` so the upgrade rebuilds the tool environment from
+    scratch rather than patching it in place; see `_uv_tool_install_command`'s
+    `reinstall` parameter for why an in-place upgrade is unsafe.
+
     Args:
         extra: The extra name to add. Validated against PEP 508 grammar before
             interpolation into the shell command.
@@ -2208,6 +2240,7 @@ def _install_extra_uv_tool_command(
         include_prereleases=None,
         distribution_name=distribution_name,
         extras_to_add=(extra,),
+        reinstall=True,
     )
 
 
@@ -2248,11 +2281,11 @@ async def perform_install_extra(
 ) -> tuple[bool, str]:
     """Add `extra` to the installed dcode tool environment.
 
-    Runs `uv tool install -U 'deepagents-code[<extras>]'`, preserving any
-    extras that are already installed. Editable installs are refused — the
-    caller should rerun their `uv tool install --editable` command with `--with
-    'deepagents-code[<extra>]'` added so the extra is resolved against the
-    editable source.
+    Runs `uv tool install --reinstall -U 'deepagents-code[<extras>]'`,
+    preserving any extras that are already installed. Editable installs are
+    refused — the caller should rerun their `uv tool install --editable` command
+    with `--with 'deepagents-code[<extra>]'` added so the extra is resolved
+    against the editable source.
 
     Args:
         extra: The extra name to install. Must satisfy `is_valid_extra_name`;
@@ -2319,10 +2352,11 @@ async def perform_install_package(
 ) -> tuple[bool, str]:
     """Add an arbitrary `package` to the installed dcode tool environment.
 
-    Runs `uv tool install -U 'deepagents-code[<extras>]' --with <package>`, the
-    escape hatch for a provider whose package is not a `deepagents-code` extra
-    (e.g. a custom or in-house `class_path` model). Already-installed extras are
-    preserved so the reinstall does not drop them. Editable installs are refused
+    Runs `uv tool install --reinstall -U 'deepagents-code[<extras>]' --with
+    <package>`, the escape hatch for a provider whose package is not a
+    `deepagents-code` extra (e.g. a custom or in-house `class_path` model).
+    Already-installed extras are preserved so the reinstall does not drop them.
+    Editable installs are refused
     — the caller should rerun their `uv tool install --editable` command with
     `--with <package>` added so it resolves against the editable source.
 
@@ -2378,12 +2412,14 @@ async def perform_install_package(
         cmd = install_package_command(package)
     except ValueError as exc:
         return False, f"{type(exc).__name__}: {exc}"
-    except ExtrasIntrospectionError as exc:
+    except (ExtrasIntrospectionError, ToolRequirementIntrospectionError) as exc:
         # Distinct from a malformed package name: the running distribution's own
-        # metadata could not be read or parsed. Leave a breadcrumb so the cause
-        # is recoverable from logs, even though the user message is unchanged.
+        # metadata, or the uv tool receipt, could not be read or parsed. Leave a
+        # breadcrumb so the cause is recoverable from logs, even though the user
+        # message is unchanged.
         logger.warning(
-            "Could not introspect installed extras for package install of %r",
+            "Could not introspect installed extras or uv receipt for package "
+            "install of %r",
             package,
             exc_info=True,
         )
@@ -2583,6 +2619,32 @@ def mark_auto_update_default_acknowledged() -> bool:
     return _write_update_state({"auto_update_default_acknowledged": True})
 
 
+def _note_install_baseline() -> None:
+    """Pre-acknowledge the auto-update default notice for a fresh install.
+
+    The migration notice (`should_announce_auto_update_default`) is intended to
+    warn users who ran dcode *before* auto-update became the opt-out default; a
+    brand-new install never experienced the old behavior, so the notice is
+    meaningless to it. Call this on the first launch ever (see
+    `should_show_whats_new`) so the notice never leaks into a new install — the
+    notice itself fires pre-TUI in `_run_startup_auto_update`.
+
+    Writes nothing when the user already set an explicit preference.
+    """
+    if is_auto_update_explicitly_set():
+        return
+    if not mark_auto_update_default_acknowledged():
+        # Fail-soft: the same unwritable state dir also drops the adjacent
+        # `seen_version` write, so the install stays "first run ever" and the
+        # stamp is retried next launch. Log the operation for context — the
+        # generic write warning in `_write_update_state` can't say which write
+        # failed when both fire back-to-back.
+        logger.debug(
+            "Could not stamp install baseline; the auto-update default notice "
+            "will be re-evaluated on the next launch",
+        )
+
+
 # ---------------------------------------------------------------------------
 # "What's new" tracking
 # ---------------------------------------------------------------------------
@@ -2603,7 +2665,11 @@ def should_show_whats_new() -> bool:
     """Return `True` if this is the first launch on a newer version."""
     seen = get_seen_version()
     if seen is None:
-        # First run ever — mark current as seen, don't show banner.
+        # First run ever — mark current as seen, don't show banner. This is the
+        # canonical fresh-install signal, so also pre-acknowledge the
+        # auto-update default migration notice (which only applies to users who
+        # predate the opt-out default) before it can fire on a later launch.
+        _note_install_baseline()
         mark_version_seen(__version__)
         return False
     try: