From 681a48f3c504d0388de477314289f6f66a239134 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Thu, 11 Jun 2026 23:15:17 -0400
Subject: [PATCH] feat(deps): catalog python3 as a recommended dependency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

python3 is used unguarded by the AI session helpers and (guarded) by the
paru/yay log cleaner, but was absent from the dependency catalog and docs.
uv does not provide python3 on PATH, and Arch's base omits it, so it is
tracked separately rather than assumed via uv.

- Add python3 (recommended tier, pm: python) to _fish_deps_catalog.fish
- Guard python3 calls in save_claude_session/save_antigravity_session with
  `type -q python3`, emitting valid empty JSON when absent (Convention §6)
- Document python3 in docs/fish-config.md (§5.6 tiers + catalog entry)
---
 docs/fish-config.md                     |  8 +++++++-
 functions/_fish_deps_catalog.fish       | 10 +++++-----
 functions/save_antigravity_session.fish |  6 ++++++
 functions/save_claude_session.fish      |  7 +++++++
 4 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/docs/fish-config.md b/docs/fish-config.md
index 1c19733..c739c25 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -855,7 +855,8 @@ Add -i (interactive confirmation) to destructive commands:
                     direnv, paru/yay
       Integrations  wakatime, tailscale
       Recommended   eza, lsd, bat, btop, dust, duf, prettyping, ov,
-                    ripgrep, lazygit, lazydocker, trash, kitty, wezterm
+                    ripgrep, lazygit, lazydocker, trash, kitty, wezterm,
+                    python3
 
     fish-deps
     fish-deps install
@@ -1380,6 +1381,11 @@ fish-deps manages these tools. Run `fish-deps` to check status, or
     trash       Safe delete (trash-cli)
     kitty       GPU-accelerated terminal (primary)
     wezterm     GPU-accelerated terminal (alternative)
+    python3     Standalone interpreter — used by the AI session helpers
+                (save_claude_session / save_antigravity_session) and the
+                paru/yay log cleaner. Note: uv does not provide python3 on
+                PATH, and Arch's base does not include it, so it is listed
+                separately. All consumers degrade gracefully without it.
 
 ## Install Methods
 
diff --git a/functions/_fish_deps_catalog.fish b/functions/_fish_deps_catalog.fish
index 65f69f7..17c2946 100644
--- a/functions/_fish_deps_catalog.fish
+++ b/functions/_fish_deps_catalog.fish
@@ -16,27 +16,27 @@ function _fish_deps_catalog
     set -g _fdc_bins \
         uv cargo fish fisher starship fzf zoxide direnv paru yay \
         wakatime tailscale \
-        eza lsd bat btop dust duf prettyping ov rg lazygit lazydocker trash kitty wezterm
+        eza lsd bat btop dust duf prettyping ov rg lazygit lazydocker trash kitty wezterm python3
 
     set -g _fdc_tiers \
         req req req req req req req req rec rec \
         int int \
-        rec rec rec rec rec rec rec rec rec rec rec rec rec rec
+        rec rec rec rec rec rec rec rec rec rec rec rec rec rec rec
 
     set -g _fdc_cargo \
         "" "" "" "" starship "" zoxide "" "" "" \
         "" "" \
-        eza lsd bat "" du-dust "" "" ov ripgrep "" "" trashy "" ""
+        eza lsd bat "" du-dust "" "" ov ripgrep "" "" trashy "" "" ""
 
     set -g _fdc_pm \
         uv cargo fish "" starship fzf zoxide direnv "" yay \
         wakatime tailscale \
-        eza lsd bat btop dust duf prettyping ov ripgrep lazygit lazydocker trash kitty wezterm
+        eza lsd bat btop dust duf prettyping ov ripgrep lazygit lazydocker trash kitty wezterm python
 
     set -g _fdc_special \
         curl-uv rustup-installer git-cargo-fish fisher-bootstrap curl-installer fzf-update "" "" paru-build yay-build \
         wakatime-binary "" \
-        "" "" "" "" "" "" "" "" "" "" curl-lazydocker "" "" ""
+        "" "" "" "" "" "" "" "" "" "" curl-lazydocker "" "" "" ""
 end
 
 # SYNOPSIS
diff --git a/functions/save_antigravity_session.fish b/functions/save_antigravity_session.fish
index 6344fa6..f3e91bb 100755
--- a/functions/save_antigravity_session.fish
+++ b/functions/save_antigravity_session.fish
@@ -7,6 +7,12 @@
 set -l input (cat)
 
 # 2. Extract session_id using Python
+#    If python3 is unavailable, emit valid empty JSON and skip session
+#    tracking rather than erroring (see AGENTS.md Convention §6).
+if not type -q python3
+    echo '{}'
+    exit 0
+end
 set -l sid (echo $input | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id', ''))")
 set -l session_file ".antigravity_session"
 
diff --git a/functions/save_claude_session.fish b/functions/save_claude_session.fish
index eef53ed..bdbb520 100755
--- a/functions/save_claude_session.fish
+++ b/functions/save_claude_session.fish
@@ -4,7 +4,14 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 # 1. Read input and extract session ID
+#    python3 parses the session_id out of the hook's JSON payload. If it is
+#    unavailable we emit valid empty JSON and skip session tracking rather
+#    than erroring (see AGENTS.md Convention §6).
 set -l input (cat)
+if not type -q python3
+    echo '{}'
+    exit 0
+end
 set -l sid (echo $input | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id', ''))")
 set -l session_file ".claude_session"