feat(hooks): nudge CLI upgrade when a newer stable release is cached

SessionStart now compares `composio version` against the CLI's own
24h-throttled release cache (~/.composio/update-check.json) and appends
"A newer Composio CLI (X.Y.Z) is available — run `composio upgrade`."
to the cli_status line. Local file read only — never the network
(PRDE-1144; `composio version --check` from ComposioHQ/composio#3944
was ruled out for the hook because it can do a synchronous fetch on a
stale cache, which could blow the 8s hook budget).

Only a plain X.Y.Z install strictly older than a plain X.Y.Z
latestVersion nudges; prereleases on either side, a missing or
malformed cache, or an unparseable version all degrade to silence.
Tests pin HOME so the cache read stays hermetic.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: KJ-11

plugins/composio/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "composio",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Your agent decides what to do — Composio handles the rest. Use just-in-time tool calls across 1,000+ apps with managed auth through the hosted app or local CLI.",
   "author": {
     "name": "Composio",

plugins/composio/hooks/session-start.sh

@@ -32,6 +32,23 @@ else
         '"authenticated"[[:space:]]*:[[:space:]]*false|not[[:space:]-]+logged[[:space:]-]+in'; then
     cli_status="The local Composio CLI is available and signed in."
   fi
+
+  # Upgrade nudge: read the CLI's own 24h-throttled release cache — a local
+  # file only, never the network. Nudge only for a plain X.Y.Z install that is
+  # strictly older than a plain X.Y.Z latestVersion (the anchored closing quote
+  # rejects prereleases instead of truncating them); anything missing or
+  # malformed degrades to silence.
+  update_cache="${HOME:-}/.composio/update-check.json"
+  if [ -f "$update_cache" ]; then
+    latest="$(sed -n 's/.*"latestVersion"[[:space:]]*:[[:space:]]*"\([0-9]\{1,\}\.[0-9]\{1,\}\.[0-9]\{1,\}\)".*/\1/p' "$update_cache" 2>/dev/null | head -n 1)"
+    installed="$(composio version 2>/dev/null | tail -n 1 | tr -d '[:space:]')"
+    if [ -n "$latest" ] && [ "$installed" != "$latest" ] \
+        && printf '%s' "$installed" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' \
+        && [ "$(printf '%s\n%s\n' "$installed" "$latest" \
+              | sort -t. -k1,1n -k2,2n -k3,3n | head -n 1)" = "$installed" ]; then
+      cli_status="${cli_status} A newer Composio CLI (${latest}) is available — run \`composio upgrade\`."
+    fi
+  fi
 fi
 
 [ -n "$cache_pid" ] && wait "$cache_pid" 2>/dev/null

tests/test_package.py

@@ -169,7 +169,9 @@ def test_readme_documents_the_combined_local_flow(self):
 
 class HookBehaviorTests(unittest.TestCase):
     def run_hook(self, script, payload, tmpdir, path=None):
-        env = dict(os.environ, TMPDIR=tmpdir)
+        # HOME is pinned to the sandbox so the upgrade-nudge cache read never
+        # sees the developer's real ~/.composio/update-check.json.
+        env = dict(os.environ, TMPDIR=tmpdir, HOME=tmpdir)
         if path is not None:
             env["PATH"] = path
         return subprocess.run(
@@ -182,11 +184,20 @@ def run_hook(self, script, payload, tmpdir, path=None):
             check=False,
         )
 
-    def fake_composio(self, tmpdir, stdout="", exit_code=0, toolkits=None):
+    def fake_composio(self, tmpdir, stdout="", exit_code=0, toolkits=None, version=None):
         bindir = pathlib.Path(tmpdir) / "bin"
         bindir.mkdir(exist_ok=True)
         script = bindir / "composio"
         lines = ["#!/usr/bin/env bash"]
+        if version is not None:
+            lines.extend(
+                [
+                    'if [ "$1" = "version" ]; then',
+                    f"  printf '%s\\n' {shlex.quote(version)}",
+                    "  exit 0",
+                    "fi",
+                ]
+            )
         if toolkits is not None:
             lines.extend(
                 [
@@ -246,6 +257,61 @@ def test_session_start_offers_cli_install_in_terminal_context(self):
             self.assertNotIn("composio execute", context)
             self.assertNotIn("composio search", context)
 
+    NUDGE = "newer Composio CLI"
+
+    def write_update_cache(self, tmpdir, content):
+        cache_dir = pathlib.Path(tmpdir) / ".composio"
+        cache_dir.mkdir(exist_ok=True)
+        (cache_dir / "update-check.json").write_text(content, encoding="utf-8")
+
+    def session_context(self, tmpdir, path):
+        result = self.run_hook(
+            "session-start.sh", {"hook_event_name": "SessionStart"}, tmpdir, path
+        )
+        self.assertEqual(0, result.returncode, result.stderr)
+        return json.loads(result.stdout)["hookSpecificOutput"]["additionalContext"]
+
+    def test_session_start_nudges_upgrade_for_older_stable_cli(self):
+        # SessionStart compares `composio version` against the CLI's own
+        # ~/.composio/update-check.json release cache (local file, no network).
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self.write_update_cache(
+                tmpdir,
+                json.dumps(
+                    {"lastChecked": "2026-07-24T00:00:00.000Z", "latestVersion": "0.2.32"}
+                ),
+            )
+            path = self.fake_composio(
+                tmpdir, stdout='{"authenticated": true}', version="0.2.30"
+            )
+            context = self.session_context(tmpdir, path)
+            self.assertIn("local Composio CLI is available and signed in", context)
+            self.assertIn("A newer Composio CLI (0.2.32) is available", context)
+            self.assertIn("composio upgrade", context)
+
+    def test_session_start_upgrade_nudge_degrades_to_silence(self):
+        cache = json.dumps(
+            {"lastChecked": "2026-07-24T00:00:00.000Z", "latestVersion": "0.2.32"}
+        )
+        silent_cases = [
+            ("beta-installed", cache, "0.2.32-beta.289"),
+            ("up-to-date", cache, "0.2.32"),
+            ("installed-newer", cache, "0.3.0"),
+            ("prerelease-latest", cache.replace("0.2.32", "0.3.0-beta.1"), "0.2.31"),
+            ("malformed-cache", "not json at all {{{", "0.2.30"),
+            ("cache-missing", None, "0.2.30"),
+        ]
+        for name, cache_content, installed in silent_cases:
+            with self.subTest(name):
+                with tempfile.TemporaryDirectory() as tmpdir:
+                    if cache_content is not None:
+                        self.write_update_cache(tmpdir, cache_content)
+                    path = self.fake_composio(
+                        tmpdir, stdout='{"authenticated": true}', version=installed
+                    )
+                    context = self.session_context(tmpdir, path)
+                    self.assertNotIn(self.NUDGE, context)
+
     def test_prompt_hook_is_surface_aware_for_cached_toolkits(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             cache = pathlib.Path(tmpdir) / "composio-plugin-toolkits.cache"