agent-toggle 0.16.1__tar.gz → 0.16.2__tar.gz

{agent_toggle-0.16.1 → agent_toggle-0.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-toggle
-Version: 0.16.1
+Version: 0.16.2
 Summary: Temporarily disable / re-enable AI-agent skills, agents, commands, rules, plugins and MCP servers across harnesses (Claude Code, Codex, Grok, OpenCode, OpenClaw, Copilot, Vibe, Devin, Antigravity)
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/weskao/agent-toggle
@@ -498,7 +498,7 @@ invalid value in either is ignored with one warning on stderr.
 
 ## Update check
 
-On every invocation (unless disabled) agent-toggle checks PyPI for a newer release. It starts
+On every invocation (unless disabled) agent-toggle checks the repository's release tags for a newer release. It starts
 before the command and is offered after it, on every exit path; it overlaps the command and waits at most 0.8 s afterwards.
 `update` and `completion` skip it.
 
@@ -513,9 +513,9 @@ before the command and is offered after it, on every exit path; it overlaps the
   then `  agent-toggle update`.
 - It never changes the exit code or stdout, so `--json` output stays one document.
 
-It is one `GET https://pypi.org/pypi/agent-toggle/json` on a background thread with a 0.8 s
-timeout, cached for 10 minutes in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a
-normal HTTP request with the User-Agent `agent-toggle-update-check`. See `SECURITY.md`
+The lookup is update-kit's: one `git ls-remote --tags --refs` of the repository on a background
+thread, cached for 10 minutes in `~/.update-kit/state.json`. Only the version you chose to skip is
+kept in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a normal git request. See `SECURITY.md`
 for the hardening. To turn it off, set `AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting
 to off (the settings menu's "Check for updates").
 
@@ -931,7 +931,7 @@ bookkeeping.
 | `parked/<sha8>/` | items parked by `--project` (`<sha8>` = first 8 hex of the SHA-1 of the resolved project dir) |
 | `profiles/` | `<name>.json` profiles (dir `0700`, files `0600`) |
 | `config.json` | [settings](#settings--config-menu) and the Telegram chat id (mode `0600`, atomic write, unknown keys kept) |
-| `update-check.json` | the [update check](#update-check)'s 10-minute cache (mode `0600`, atomic write) |
+| `update-check.json` | the [update check](#update-check)'s skipped version (mode `0600`, atomic write) |
 
 A killed run loses at most the one item in flight. If that was a flag write or a
 dir move (with its companions), its `pending` record (the full entry, a flag's

{agent_toggle-0.16.1 → agent_toggle-0.16.2}/README.md

@@ -464,7 +464,7 @@ invalid value in either is ignored with one warning on stderr.
 
 ## Update check
 
-On every invocation (unless disabled) agent-toggle checks PyPI for a newer release. It starts
+On every invocation (unless disabled) agent-toggle checks the repository's release tags for a newer release. It starts
 before the command and is offered after it, on every exit path; it overlaps the command and waits at most 0.8 s afterwards.
 `update` and `completion` skip it.
 
@@ -479,9 +479,9 @@ before the command and is offered after it, on every exit path; it overlaps the
   then `  agent-toggle update`.
 - It never changes the exit code or stdout, so `--json` output stays one document.
 
-It is one `GET https://pypi.org/pypi/agent-toggle/json` on a background thread with a 0.8 s
-timeout, cached for 10 minutes in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a
-normal HTTP request with the User-Agent `agent-toggle-update-check`. See `SECURITY.md`
+The lookup is update-kit's: one `git ls-remote --tags --refs` of the repository on a background
+thread, cached for 10 minutes in `~/.update-kit/state.json`. Only the version you chose to skip is
+kept in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a normal git request. See `SECURITY.md`
 for the hardening. To turn it off, set `AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting
 to off (the settings menu's "Check for updates").
 
@@ -897,7 +897,7 @@ bookkeeping.
 | `parked/<sha8>/` | items parked by `--project` (`<sha8>` = first 8 hex of the SHA-1 of the resolved project dir) |
 | `profiles/` | `<name>.json` profiles (dir `0700`, files `0600`) |
 | `config.json` | [settings](#settings--config-menu) and the Telegram chat id (mode `0600`, atomic write, unknown keys kept) |
-| `update-check.json` | the [update check](#update-check)'s 10-minute cache (mode `0600`, atomic write) |
+| `update-check.json` | the [update check](#update-check)'s skipped version (mode `0600`, atomic write) |
 
 A killed run loses at most the one item in flight. If that was a flag write or a
 dir move (with its companions), its `pending` record (the full entry, a flag's

{agent_toggle-0.16.1 → agent_toggle-0.16.2}/agent_toggle/__init__.py

@@ -1,3 +1,3 @@
 """agent-toggle: temporarily disable / re-enable AI-agent resources."""
 
-__version__ = "0.16.1"
+__version__ = "0.16.2"

agent_toggle-0.16.2/agent_toggle/update_check.py

@@ -0,0 +1,209 @@
+"""Update check on top of update-kit, plus the "skip this version" memory.
+
+    from agent_toggle.update_check import check
+    found = check("1.0.0", cache_path=Path.home() / ".agent-toggle" / "update-check.json")
+    if found:
+        print(f"{found.latest} is available (you have {found.current})")
+
+The lookup itself -- ``git ls-remote`` of the release tags, the 10-minute cache in
+``~/.update-kit/state.json``, the timeout -- is :func:`update_kit.check`; ``latest`` is
+the tag as it returns it (``v1.2.0``). Only the skipped version lives in *cache_path*.
+
+To overlap the lookup with the command's own work instead of paying for
+it at exit, start it early and collect the result at the end:
+
+    started = start("1.0.0", cache_path=...)
+    ...  # the command's own work
+    found = collect(started)
+
+To ask the user what to do instead of only hinting, hand :func:`offer` the
+UI as a callback -- it owns what each answer does, the UI only picks one:
+
+    offer(started, ask, cache_path=..., upgrade=["uv", "tool", "upgrade", "agent-toggle"])
+
+where ``ask(found)`` returns ``UPDATE_NOW``, ``SKIP`` or ``SKIP_VERSION``.
+When the upgrade depends on the version or takes several steps, pass a
+callable instead: ``upgrade=lambda found: [[...], [...]]`` runs each command
+in order and stops at the first one that fails.
+``SKIP_VERSION`` is remembered in *cache_path*; a newer release asks again.
+
+Nothing here is allowed to raise to the caller: a missing cache, a bad
+payload, or a dead network all become ``None``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import threading
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "REPO",
+    "SKIP",
+    "SKIP_VERSION",
+    "UPDATE_NOW",
+    "UPGRADE_FAILED",
+    "Started",
+    "UpdateAvailable",
+    "check",
+    "collect",
+    "offer",
+    "skip",
+    "start",
+]
+
+REPO = "weskao/agent-toggle"
+#: How long :func:`collect` waits for the background lookup before giving up on it.
+DEFAULT_TIMEOUT = 0.8
+
+#: Answers an ``ask`` callback returns to :func:`offer`.
+UPDATE_NOW = "update-now"
+SKIP = "skip"
+SKIP_VERSION = "skip-version"
+#: What :func:`offer` returns when UPDATE_NOW's command could not run or failed.
+UPGRADE_FAILED = "upgrade-failed"
+
+#: What a skipped version may look like before it is trusted: it is read from a file.
+_VERSION_RE = re.compile(r"v?\d{1,6}(\.\d{1,6}){1,3}([a-zA-Z0-9.+-]{0,20})?")
+
+
+@dataclass(frozen=True)
+class UpdateAvailable:
+    current: str
+    latest: str
+
+
+def check(current: str, *, cache_path: Path) -> UpdateAvailable | None:
+    """Return an update when the latest release is newer than *current* and not the
+    version skipped in *cache_path*, else None. Never raises."""
+    try:
+        import update_kit  # lazy: a checkout run or a stale env lacks it
+
+        latest = update_kit.check(repo=REPO, current=current)
+        if not isinstance(latest, str) or _bare(latest) == _bare(_load_cache(cache_path).get("skipped")):
+            return None
+        return UpdateAvailable(current=current, latest=latest)
+    except Exception:  # noqa: BLE001 - a hint must never fail the command
+        return None
+
+
+@dataclass
+class Started:
+    """A background check in flight; pass to :func:`collect` to get its result."""
+
+    thread: threading.Thread
+    _result: list = field(default_factory=list)
+
+
+def start(current: str, *, cache_path: Path) -> Started:
+    """Run :func:`check` on a daemon thread so it overlaps the caller's own work."""
+    result: list = []
+
+    def run() -> None:
+        result.append(check(current, cache_path=cache_path))
+
+    thread = threading.Thread(target=run, name="agent-toggle-update-check", daemon=True)
+    thread.start()
+    return Started(thread=thread, _result=result)
+
+
+def collect(started: Started | None, *, timeout: float = DEFAULT_TIMEOUT) -> UpdateAvailable | None:
+    """Wait for a :func:`start`-ed check and return its result. Never raises."""
+    if started is None:
+        return None
+    try:
+        # Usually already done: it ran alongside the caller's own work.
+        started.thread.join(timeout)
+        return started._result[0] if started._result else None
+    except Exception:  # noqa: BLE001 - a hint must never fail the command
+        return None
+
+
+def skip(cache_path: Path, version: str) -> None:
+    """Stop reporting *version*; a newer release is reported again. Never raises."""
+    data = _load_cache(cache_path)
+    data["skipped"] = version
+    _write_cache(cache_path, data)
+
+
+def offer(
+    started: Started | None,
+    ask: Callable[[UpdateAvailable], str],
+    *,
+    cache_path: Path,
+    upgrade: Sequence[str] | Callable[[UpdateAvailable], Sequence[Sequence[str]]],
+    run: Callable[..., object] = subprocess.run,
+) -> str | None:
+    """Collect *started*, let *ask* pick an answer, then act on it.
+
+    *upgrade* is one command, or a callable building the commands from the
+    found release, run in order. Returns the answer acted on
+    (``UPGRADE_FAILED`` when a command is missing or exits nonzero — the
+    rest are then skipped), or None when there was nothing to offer. Ctrl+C
+    inside *ask* is ``SKIP``. Never raises.
+    """
+    try:
+        found = collect(started)
+        if found is None:
+            return None
+        try:
+            answer = ask(found)
+        except KeyboardInterrupt:
+            return SKIP
+        if answer == SKIP_VERSION:
+            skip(cache_path, found.latest)
+        elif answer == UPDATE_NOW:
+            steps = upgrade(found) if callable(upgrade) else [upgrade]
+            for step in steps:
+                try:
+                    done = run(list(step), check=False)
+                except OSError:
+                    return UPGRADE_FAILED
+                if getattr(done, "returncode", 1) != 0:
+                    return UPGRADE_FAILED
+        return answer
+    except Exception:  # noqa: BLE001 - an update offer must never fail the command
+        return None
+
+
+def _bare(version: object) -> str | None:
+    """*version* without a leading ``v`` (an old cache holds PyPI's ``0.10.0``, now tags)."""
+    return version.removeprefix("v") if isinstance(version, str) else None
+
+
+def _load_cache(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError, RecursionError):    # RecursionError: a deeply nested file
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    # Only a valid skipped version survives: a hostile file can't smuggle anything
+    # (e.g. a 100k-deep dict that json.dumps can't write back), and old
+    # checked_at/latest keys are dropped on the next write.
+    skipped = data.get("skipped")
+    return {"skipped": skipped} if isinstance(skipped, str) and _VERSION_RE.fullmatch(skipped) else {}
+
+
+def _write_cache(path: Path, data: dict) -> None:
+    # tmp + os.replace never follows a symlink at *path*; 0600 from creation.
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        tmp.unlink(missing_ok=True)
+        fd = os.open(tmp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(json.dumps(data) + "\n")
+            os.replace(tmp, path)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+    except (OSError, RecursionError, ValueError):
+        return

{agent_toggle-0.16.1 → agent_toggle-0.16.2}/agent_toggle/update_prompt.py

@@ -28,7 +28,7 @@ from .output import use_color
 from .ui import theme
 
 DIST = "agent-toggle"
-REPO = "weskao/agent-toggle"
+REPO = update_check.REPO
 PLUGIN = "agent-toggle@agent-toggle"
 UPDATE = [DIST, "update"]
 RELEASE_NOTES = "https://github.com/weskao/agent-toggle/releases/tag/v%s"
@@ -93,12 +93,12 @@ def cache_path() -> Path:
 
 
 def start() -> update_check.Started | None:
-    """Kick off the PyPI check on a daemon thread, unless the `update_check` setting
-    (env AGENT_TOGGLE_UPDATE_CHECK wins) is off. Never raises."""
+    """Kick off the release check (update_kit) on a daemon thread, unless the `update_check`
+    setting (env AGENT_TOGGLE_UPDATE_CHECK wins) is off. Never raises."""
     try:
         if not settings.get("update_check"):
             return None
-        return update_check.start(DIST, __version__, cache_path=cache_path())
+        return update_check.start(__version__, cache_path=cache_path())
     except Exception:  # noqa: BLE001 - a hint must never fail the command
         return None
 
@@ -112,7 +112,7 @@ def is_interactive() -> bool:
 
 def _available(found: update_check.UpdateAvailable) -> str:
     return t("update.available", "agent-toggle %s is available (you have %s)",
-             _clean(found.latest), _clean(found.current))
+             _clean(found.latest).removeprefix("v"), _clean(found.current))
 
 
 def hint(found: update_check.UpdateAvailable) -> str:

{agent_toggle-0.16.1 → agent_toggle-0.16.2}/agent_toggle.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-toggle
-Version: 0.16.1
+Version: 0.16.2
 Summary: Temporarily disable / re-enable AI-agent skills, agents, commands, rules, plugins and MCP servers across harnesses (Claude Code, Codex, Grok, OpenCode, OpenClaw, Copilot, Vibe, Devin, Antigravity)
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/weskao/agent-toggle
@@ -498,7 +498,7 @@ invalid value in either is ignored with one warning on stderr.
 
 ## Update check
 
-On every invocation (unless disabled) agent-toggle checks PyPI for a newer release. It starts
+On every invocation (unless disabled) agent-toggle checks the repository's release tags for a newer release. It starts
 before the command and is offered after it, on every exit path; it overlaps the command and waits at most 0.8 s afterwards.
 `update` and `completion` skip it.
 
@@ -513,9 +513,9 @@ before the command and is offered after it, on every exit path; it overlaps the
   then `  agent-toggle update`.
 - It never changes the exit code or stdout, so `--json` output stays one document.
 
-It is one `GET https://pypi.org/pypi/agent-toggle/json` on a background thread with a 0.8 s
-timeout, cached for 10 minutes in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a
-normal HTTP request with the User-Agent `agent-toggle-update-check`. See `SECURITY.md`
+The lookup is update-kit's: one `git ls-remote --tags --refs` of the repository on a background
+thread, cached for 10 minutes in `~/.update-kit/state.json`. Only the version you chose to skip is
+kept in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a normal git request. See `SECURITY.md`
 for the hardening. To turn it off, set `AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting
 to off (the settings menu's "Check for updates").
 
@@ -931,7 +931,7 @@ bookkeeping.
 | `parked/<sha8>/` | items parked by `--project` (`<sha8>` = first 8 hex of the SHA-1 of the resolved project dir) |
 | `profiles/` | `<name>.json` profiles (dir `0700`, files `0600`) |
 | `config.json` | [settings](#settings--config-menu) and the Telegram chat id (mode `0600`, atomic write, unknown keys kept) |
-| `update-check.json` | the [update check](#update-check)'s 10-minute cache (mode `0600`, atomic write) |
+| `update-check.json` | the [update check](#update-check)'s skipped version (mode `0600`, atomic write) |
 
 A killed run loses at most the one item in flight. If that was a flag write or a
 dir move (with its companions), its `pending` record (the full entry, a flag's

{agent_toggle-0.16.1 → agent_toggle-0.16.2}/tests/test_cli.py

@@ -159,13 +159,13 @@ class SandboxInvariantTest(SandboxCase):
         self.assertEqual(Path(agent_toggle.__file__).resolve().parent, REPO / "agent_toggle")
 
 
-PYPI_99 = json.dumps({"info": {"version": "99.0.0"}})
+TAG_99 = "v99.0.0"     # update_kit.check returns the release tag
 HINT = f"agent-toggle 99.0.0 is available (you have {__version__})"
 
 
 class UpdateCheckTest(CliCase):
     """The update check: started before dispatch, offered in main()'s finally; and `update` /
-    `--update`. No network: fetch_pypi and update_kit.update are patched;
+    `--update`. No network: update_kit.check and update_kit.update are patched;
     AGENT_TOGGLE_UPDATE_CHECK=0 (tests/base.py) is lifted here only."""
 
     def setUp(self) -> None:
@@ -174,9 +174,9 @@ class UpdateCheckTest(CliCase):
         env.start()
         self.addCleanup(env.stop)
         os.environ.pop("AGENT_TOGGLE_UPDATE_CHECK", None)
-        for target, kw in ((update_check, {"fetch_pypi": mock.Mock(return_value=PYPI_99)}),
-                           (update_prompt, {"is_interactive": mock.Mock(return_value=False)}),
-                           (update_kit, {"update": mock.Mock(return_value=0)}),   # never install
+        for target, kw in ((update_prompt, {"is_interactive": mock.Mock(return_value=False)}),
+                           (update_kit, {"check": mock.Mock(return_value=TAG_99),
+                                         "update": mock.Mock(return_value=0)}),   # never install
                            (fs, {"WIN": False})):     # the panel/upgrade flow; Windows has its own test
             patch = mock.patch.multiple(target, **kw)
             patch.start()
@@ -193,7 +193,7 @@ class UpdateCheckTest(CliCase):
             self.assertNotIn("99.0.0", self.run_cli("status")[2])
         settings.set("update_check", False)
         self.assertNotIn("99.0.0", self.run_cli("status")[2])
-        update_check.fetch_pypi.assert_not_called()
+        update_kit.check.assert_not_called()
 
     def test_json_stdout_is_one_document_and_never_prompts(self) -> None:
         update_prompt.is_interactive.return_value = True
@@ -291,7 +291,7 @@ class UpdateCheckTest(CliCase):
             self.assertNotIn("99.0.0", self.run_cli("update")[2])
             self.assertNotIn("99.0.0", self.run_cli("completion", "bash")[2])
         ask.assert_not_called()
-        update_check.fetch_pypi.assert_not_called()
+        update_kit.check.assert_not_called()
 
     def test_update_and_dash_dash_update_exit_with_update_kits_code(self) -> None:
         for argv in (("update",), ("--update",), ("--json", "--update")):

agent_toggle-0.16.2/tests/test_update_check.py

@@ -0,0 +1,240 @@
+"""Update hint on top of update_kit.check.
+
+Never hits the network: every test mocks ``update_kit.check`` (which returns the newer
+release tag, or None) and injects ``run``. The lookup, its TTL and its cache are
+update-kit's; what these cover is the skip-version memory, the background start/collect
+and the offer answers.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+import threading
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import update_kit
+
+from agent_toggle import update_check
+
+
+class _Done:
+    def __init__(self, returncode: int) -> None:
+        self.returncode = returncode
+
+
+class UpdateCheckCase(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp(prefix="agent-toggle-update-"))
+        self.addCleanup(shutil.rmtree, self.tmp, ignore_errors=True)
+        self.cache = self.tmp / "update-check.json"
+
+    def kit(self, latest="v0.10.0", **kw):
+        """Patch update_kit.check to answer *latest* (or raise via side_effect=...)."""
+        patch = mock.patch.object(update_kit, "check", return_value=latest, **kw)
+        self.addCleanup(patch.stop)
+        return patch.start()
+
+    def check(self, latest="v0.10.0", current="0.9.1", **kw):
+        self.kit(latest, **kw)
+        return update_check.check(current, cache_path=self.cache)
+
+    def seed(self, **data) -> None:
+        self.cache.write_text(json.dumps(data), encoding="utf-8")
+
+
+class CheckTest(UpdateCheckCase):
+    def test_a_newer_tag_is_reported_as_update_kit_returns_it(self):
+        found = self.check("v0.10.0")
+        self.assertEqual(found, update_check.UpdateAvailable(current="0.9.1", latest="v0.10.0"))
+
+    def test_the_lookup_is_update_kits_for_this_repo(self):
+        kit = self.kit()
+        update_check.check("0.9.1", cache_path=self.cache)
+        kit.assert_called_once_with(repo="weskao/agent-toggle", current="0.9.1")
+
+    def test_nothing_newer_stays_silent(self):
+        self.assertIsNone(self.check(None))
+
+    def test_a_failing_lookup_stays_silent(self):
+        self.assertIsNone(self.check(side_effect=OSError("offline")))
+
+    def test_a_missing_update_kit_stays_silent(self):
+        with mock.patch.dict("sys.modules", {"update_kit": None}):
+            self.assertIsNone(update_check.check("0.9.1", cache_path=self.cache))
+
+
+class StartCollectTest(UpdateCheckCase):
+    def start(self, latest="v0.10.0", **kw):
+        self.kit(latest, **kw)
+        return update_check.start("0.9.1", cache_path=self.cache)
+
+    def test_start_and_collect_finds_an_update(self):
+        self.assertEqual(update_check.collect(self.start()).latest, "v0.10.0")
+
+    def test_start_and_collect_stays_silent_when_current(self):
+        self.assertIsNone(update_check.collect(self.start(None)))
+
+    def test_start_overlaps_with_the_callers_own_work(self):
+        release = threading.Event()
+
+        def slow(**_kw):
+            release.wait(timeout=1)
+            return "v0.10.0"
+
+        started = self.start(side_effect=slow)
+        time.sleep(0.05)
+        self.assertTrue(started.thread.is_alive())
+        release.set()
+        self.assertEqual(update_check.collect(started).latest, "v0.10.0")
+
+    def test_collect_with_no_started_check_is_silent(self):
+        self.assertIsNone(update_check.collect(None))
+
+
+class SkipTest(UpdateCheckCase):
+    def test_a_skipped_version_stays_silent(self):
+        update_check.skip(self.cache, "v0.10.0")
+        self.assertIsNone(self.check("v0.10.0"))
+
+    def test_a_skip_made_before_tags_still_matches(self):
+        self.seed(skipped="0.10.0")        # what the PyPI-era check stored
+        self.assertIsNone(self.check("v0.10.0"))
+
+    def test_a_release_newer_than_the_skipped_one_is_reported(self):
+        update_check.skip(self.cache, "v0.10.0")
+        self.assertEqual(self.check("v0.11.0").latest, "v0.11.0")
+
+    def test_skip_keeps_only_the_skipped_version(self):
+        self.seed(checked_at=5, latest="0.9.2", extra={"a": [1]})
+        update_check.skip(self.cache, "v0.10.0")
+        self.assertEqual(json.loads(self.cache.read_text(encoding="utf-8")), {"skipped": "v0.10.0"})
+
+
+class SecurityTest(UpdateCheckCase):
+    def test_a_hostile_skipped_value_is_ignored(self):
+        self.seed(skipped="evil\x1b[2J", latest=["1.2.3"])
+        self.assertEqual(update_check._load_cache(self.cache), {})
+
+    def test_the_prompt_prints_no_escape_for_a_hostile_version(self):
+        import io
+        from contextlib import redirect_stderr
+
+        from agent_toggle import update_prompt
+        buf = io.StringIO()
+        with redirect_stderr(buf):
+            update_prompt.hint(update_check.UpdateAvailable(current="1.0", latest="9.9\x1b]52;c;x\x07"))
+        self.assertNotIn("\x1b", buf.getvalue())
+
+    def test_the_prompt_shows_the_tag_without_its_v(self):
+        from agent_toggle import update_prompt
+        text = update_prompt._available(update_check.UpdateAvailable(current="1.0", latest="v2.0.0"))
+        self.assertEqual(text, "agent-toggle 2.0.0 is available (you have 1.0)")
+
+    def test_a_deeply_nested_cache_is_corrupt_and_rewritten_small(self):
+        depth = 100_000        # parses on 3.14; json.dumps of the merged data used to raise
+        self.cache.write_text('{"a":' * depth + "1" + "}" * depth, encoding="utf-8")
+        update_check.skip(self.cache, "v0.10.0")
+        self.assertEqual(json.loads(self.cache.read_text(encoding="utf-8")), {"skipped": "v0.10.0"})
+
+    def test_the_cache_write_replaces_a_symlink_and_is_0600(self):
+        target = self.tmp / "victim"
+        target.write_text("keep", encoding="utf-8")
+        self.cache.symlink_to(target)
+        update_check.skip(self.cache, "v0.10.0")
+        self.assertFalse(self.cache.is_symlink())
+        self.assertEqual(target.read_text(encoding="utf-8"), "keep")
+        if os.name != "nt":                      # Windows has no POSIX modes
+            self.assertEqual(self.cache.stat().st_mode & 0o777, 0o600)
+
+
+class OfferTest(UpdateCheckCase):
+    def offer(self, answer, *, latest="v0.10.0", run=None, upgrade=None):
+        asked: list = []
+
+        def ask(found):
+            asked.append(found)
+            if isinstance(answer, BaseException):
+                raise answer
+            return answer
+
+        self.kit(latest)
+        started = update_check.start("0.9.1", cache_path=self.cache)
+        result = update_check.offer(
+            started, ask, cache_path=self.cache,
+            upgrade=upgrade or ["uv", "tool", "upgrade", "agent-toggle"],
+            run=run or (lambda *_a, **_k: self.fail("upgrade must not run")))
+        return result, asked
+
+    def test_offer_does_not_ask_when_nothing_is_newer(self):
+        result, asked = self.offer(update_check.UPDATE_NOW, latest=None)
+        self.assertIsNone(result)
+        self.assertEqual(asked, [])
+
+    def test_offer_asks_with_the_found_release(self):
+        _result, asked = self.offer(update_check.SKIP)
+        self.assertEqual(asked, [update_check.UpdateAvailable(current="0.9.1", latest="v0.10.0")])
+
+    def test_offer_update_now_runs_the_upgrade_command(self):
+        ran: list = []
+        result, _ = self.offer(update_check.UPDATE_NOW,
+                               run=lambda cmd, **_k: ran.append(cmd) or _Done(0))
+        self.assertEqual(result, update_check.UPDATE_NOW)
+        self.assertEqual(ran, [["uv", "tool", "upgrade", "agent-toggle"]])
+
+    def test_offer_reports_an_upgrade_that_exits_nonzero(self):
+        result, _ = self.offer(update_check.UPDATE_NOW, run=lambda *_a, **_k: _Done(2))
+        self.assertEqual(result, update_check.UPGRADE_FAILED)
+
+    def test_offer_reports_a_missing_upgrade_tool(self):
+        def missing(*_a, **_k):
+            raise FileNotFoundError("uv")
+
+        result, _ = self.offer(update_check.UPDATE_NOW, run=missing)
+        self.assertEqual(result, update_check.UPGRADE_FAILED)
+
+    def test_offer_skip_leaves_the_next_run_asking(self):
+        result, _ = self.offer(update_check.SKIP)
+        self.assertEqual(result, update_check.SKIP)
+        self.assertIsNotNone(self.check("v0.10.0"))
+
+    def test_offer_skip_version_silences_that_version_until_a_newer_one(self):
+        result, _ = self.offer(update_check.SKIP_VERSION)
+        self.assertEqual(result, update_check.SKIP_VERSION)
+        self.assertIsNone(self.check("v0.10.0"))
+        self.assertEqual(self.check("v0.11.0").latest, "v0.11.0")
+
+    def test_offer_never_raises_when_the_ui_does(self):
+        result, _ = self.offer(RuntimeError("broken terminal"))
+        self.assertIsNone(result)
+
+    def test_offer_reads_ctrl_c_in_the_ui_as_skip(self):
+        result, _ = self.offer(KeyboardInterrupt())
+        self.assertEqual(result, update_check.SKIP)
+
+    def steps(self, returncodes):
+        ran: list = []
+        codes = iter(returncodes)
+        result, _ = self.offer(
+            update_check.UPDATE_NOW,
+            upgrade=lambda found: [["install", found.latest], ["reload"]],
+            run=lambda cmd, **_k: ran.append(cmd) or _Done(next(codes)))
+        return result, ran
+
+    def test_offer_builds_upgrade_steps_from_the_found_release(self):
+        result, ran = self.steps([0, 0])
+        self.assertEqual(result, update_check.UPDATE_NOW)
+        self.assertEqual(ran, [["install", "v0.10.0"], ["reload"]])
+
+    def test_offer_stops_at_the_first_failed_step(self):
+        result, ran = self.steps([1])
+        self.assertEqual(result, update_check.UPGRADE_FAILED)
+        self.assertEqual(ran, [["install", "v0.10.0"]])
+
+
+if __name__ == "__main__":
+    unittest.main()