feat(agents-init): scaffold .version + commit-time version hooks, pull before commit

functions/_agents_init_install_tools.fish

@@ -0,0 +1,47 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# SYNOPSIS
+#   _agents_init_install_tools <agents_dir>
+#
+# DESCRIPTION
+#   Copies the canonical version-bump script and git hook shims from
+#   fish-config's scripts/agents-tools/ into <agents_dir>/.agents-tools/,
+#   refreshing them when the shipped `agents-tools-version:` marker is newer
+#   than the installed copy. Files are made executable. Idempotent: prints
+#   nothing when the installed tooling is already current, or a short summary
+#   line when it installed or updated the tooling.
+#
+# ARGUMENTS
+#   agents_dir  Absolute path to the AGENTS/ sub-repo root
+#
+# RETURNS
+#   0  Tooling is current or was installed/updated successfully
+#   1  Canonical source missing or a copy failed
+#
+# EXAMPLE
+#   set -l msg (_agents_init_install_tools /path/to/AGENTS)
+#   test -n "$msg"; and echo $msg
+function _agents_init_install_tools --argument-names agents_dir
+    set -l src (path resolve (status dirname)/../scripts/agents-tools)
+    test -d "$src"; or return 1
+    set -l dest "$agents_dir/.agents-tools"
+
+    set -l want (command grep -m1 -oE 'agents-tools-version: *[0-9]+' "$src/version-bump" 2>/dev/null | command grep -oE '[0-9]+$')
+    set -l have ""
+    test -f "$dest/version-bump"; and set have (command grep -m1 -oE 'agents-tools-version: *[0-9]+' "$dest/version-bump" 2>/dev/null | command grep -oE '[0-9]+$')
+
+    test "$want" = "$have"; and return 0
+
+    mkdir -p "$dest/hooks"; or return 1
+    command cp "$src/version-bump" "$dest/version-bump"; or return 1
+    command cp "$src/hooks/pre-commit" "$dest/hooks/pre-commit"; or return 1
+    command cp "$src/hooks/prepare-commit-msg" "$dest/hooks/prepare-commit-msg"; or return 1
+    chmod +x "$dest/version-bump" "$dest/hooks/pre-commit" "$dest/hooks/prepare-commit-msg"
+
+    if test -z "$have"
+        echo "→ Installed AGENTS/.agents-tools/ (version-bump v$want)"
+    else
+        echo "→ Updated AGENTS/.agents-tools/ (v$have → v$want)"
+    end
+end

functions/agents-init.fish

@@ -134,6 +134,26 @@ function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec fi
         test $verbose -eq 1; and echo "$c_ok→ Initialized git repo in AGENTS/$c_reset"
     end
 
+    #   ─────────────── Always: version tracking (.version + hooks) ───────────────
+    if not test -f "$agents_dir/.version"
+        echo 1.0.0 >"$agents_dir/.version"
+        set changed 1
+        test $verbose -eq 1; and echo "$c_ok→ Created AGENTS/.version (1.0.0)$c_reset"
+    end
+
+    set -l _tools (_agents_init_install_tools "$agents_dir")
+    if test -n "$_tools"
+        set changed 1
+        test $verbose -eq 1; and echo "$c_ok$_tools$c_reset"
+    end
+
+    set -l _hp (git -C "$agents_dir" config --local core.hooksPath 2>/dev/null)
+    if test "$_hp" != .agents-tools/hooks
+        git -C "$agents_dir" config --local core.hooksPath .agents-tools/hooks
+        set changed 1
+        test $verbose -eq 1; and echo "$c_ok→ Set core.hooksPath → .agents-tools/hooks$c_reset"
+    end
+
     #   ──────────────────────────── --agents mode ──────────────────────────────
     if test $do_agents -eq 1
         # Detect which root-level files are real (not symlinks)
@@ -417,6 +437,11 @@ function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec fi
     end
 
     #   ──────────────────────── Auto-commit AGENTS/ ────────────────────────────
+    # Pull first when an upstream is configured so the local .version reflects
+    # any remote bumps before we add to it (no-op for local-only repos).
+    if git -C "$agents_dir" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1
+        git -C "$agents_dir" pull --rebase --autostash -q 2>/dev/null
+    end
     git -C "$agents_dir" add -A 2>/dev/null
     set -l status_out (git -C "$agents_dir" status --porcelain 2>/dev/null)
     if test -n "$status_out"
@@ -426,7 +451,8 @@ function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec fi
             set changed 1
             if test $verbose -eq 1
                 set -l sha (git -C "$agents_dir" rev-parse --short HEAD 2>/dev/null)
-                echo "$c_ok→ Committed AGENTS/ ($sha) $c_dim$msg$c_reset"
+                set -l realmsg (git -C "$agents_dir" log -1 --pretty=%s 2>/dev/null)
+                echo "$c_ok→ Committed AGENTS/ ($sha) $c_dim$realmsg$c_reset"
             end
         end
     end