@therocketcode/gsd-core 1.4.0

package/hooks/dist/gsd-update-banner.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// SessionStart banner that surfaces GSD update availability when GSD's
+// statusline isn't installed. Reads the cache that
+// gsd-check-update-worker.js writes to ~/.cache/gsd/<updateCacheFileName> (per-package).
+//
+// Opt-in by design: bin/install.js only registers this hook when the user
+// declines to install (or replace) the GSD statusline. The presence of the
+// SessionStart entry IS the opt-in — there is no separate runtime flag.
+//
+// See issue #2795 for the rationale.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
+
+// Suppress repeat parse-error banners for 24 hours so a genuinely broken
+// cache file doesn't nag the user every session.
+const RATE_LIMIT_SECONDS = 24 * 60 * 60;
+
+/**
+ * Build the SessionStart JSON envelope to emit, given parsed cache state.
+ * Pure function — no I/O. Returns null when the hook should print nothing.
+ *
+ * @param {object} state
+ * @param {object|null} state.cache                  Parsed cache, or null if missing/unreadable.
+ * @param {boolean}     state.parseError             True iff cache file existed but JSON.parse failed.
+ * @param {boolean}     state.suppressFailureWarning True when a recent failure warning already fired.
+ * @returns {{systemMessage: string}|null}           JSON envelope, or null for silent exit.
+ */
+function buildBannerOutput(state) {
+  const { cache, parseError, suppressFailureWarning } = state || {};
+  if (parseError) {
+    if (suppressFailureWarning) return null;
+    return { systemMessage: 'GSD update check failed.' };
+  }
+  if (!cache) return null;
+  // Lineage guard: package_name must be present and match this package.
+  // Absent package_name means the cache predates lineage tracking — treat as untrusted.
+  if (!cache.package_name || cache.package_name !== PACKAGE_NAME) return null;
+  if (!cache.update_available) return null;
+  const installed = cache.installed || 'unknown';
+  const latest = cache.latest || 'unknown';
+  return {
+    systemMessage: `GSD update available: ${installed} → ${latest}. Run /gsd:update.`,
+  };
+}
+
+/**
+ * Read and parse the update-check cache file.
+ *
+ * @param {string} cacheFile
+ * @returns {{cache: object|null, parseError: boolean}}
+ */
+function readCache(cacheFile) {
+  let cache = null;
+  let parseError = false;
+  try {
+    if (fs.existsSync(cacheFile)) {
+      const raw = fs.readFileSync(cacheFile, 'utf8');
+      cache = JSON.parse(raw);
+    }
+  } catch (e) {
+    // Distinguish "file unreadable" from "JSON malformed": both fail-open to
+    // null cache, but a JSON parse error becomes a one-time diagnostic.
+    parseError = e instanceof SyntaxError;
+  }
+  return { cache, parseError };
+}
+
+/**
+ * Has a failure warning been emitted within the rate-limit window?
+ *
+ * @param {string} sentinelFile
+ * @param {number} nowSeconds
+ * @returns {boolean}
+ */
+function shouldSuppressFailureWarning(sentinelFile, nowSeconds) {
+  try {
+    if (!fs.existsSync(sentinelFile)) return false;
+    const last = parseInt(fs.readFileSync(sentinelFile, 'utf8').trim(), 10);
+    if (!Number.isFinite(last)) return false;
+    return nowSeconds - last < RATE_LIMIT_SECONDS;
+  } catch (e) {
+    return false;
+  }
+}
+
+function recordFailureWarning(sentinelFile, nowSeconds) {
+  try {
+    fs.writeFileSync(sentinelFile, String(nowSeconds));
+  } catch (e) {
+    // Best-effort: a non-writable cache dir means we'll re-warn next session,
+    // which is no worse than the un-instrumented baseline.
+  }
+}
+
+function main() {
+  const cacheDir = path.join(os.homedir(), '.cache', 'gsd');
+  const cacheFile = path.join(cacheDir, updateCacheFileName);
+  const sentinelFile = path.join(cacheDir, 'banner-failure-warned-at');
+  const now = Math.floor(Date.now() / 1000);
+
+  const { cache, parseError } = readCache(cacheFile);
+  const suppressFailureWarning = parseError
+    ? shouldSuppressFailureWarning(sentinelFile, now)
+    : false;
+  const output = buildBannerOutput({ cache, parseError, suppressFailureWarning });
+
+  if (parseError && !suppressFailureWarning) {
+    // Ensure cache dir exists before writing the sentinel — first-run case
+    // where ~/.cache/gsd was created by check-update but the parent dir got
+    // wiped between runs.
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+    } catch (e) {
+      // Best-effort: failure to create the dir means we'll re-warn next
+      // session, which is no worse than the un-instrumented baseline.
+    }
+    recordFailureWarning(sentinelFile, now);
+  }
+
+  if (output) {
+    process.stdout.write(JSON.stringify(output));
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  buildBannerOutput,
+  readCache,
+  shouldSuppressFailureWarning,
+  RATE_LIMIT_SECONDS,
+};

package/hooks/dist/gsd-validate-commit.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# gsd-hook-version: {{GSD_VERSION}}
+# gsd-validate-commit.sh — PreToolUse hook: enforce Conventional Commits format
+# Blocks git commit commands with non-conforming messages (exit 2).
+# Allows conforming messages and all non-commit commands (exit 0).
+# Uses Node.js for JSON parsing (always available in GSD projects, no jq dependency).
+#
+# OPT-IN: This hook is a no-op unless config.json has hooks.community: true.
+# Enable with: "hooks": { "community": true } in .planning/config.json
+
+# Check opt-in config — exit silently if not enabled
+if [ -f .planning/config.json ]; then
+  ENABLED=$(node -e "try{const c=require('./.planning/config.json');process.stdout.write(c.hooks?.community===true?'1':'0')}catch{process.stdout.write('0')}" 2>/dev/null)
+  if [ "$ENABLED" != "1" ]; then exit 0; fi
+else
+  exit 0
+fi
+
+INPUT=$(cat)
+
+# Extract command from JSON using Node (handles escaping correctly, no jq needed)
+CMD=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.command||'')}catch{}})" 2>/dev/null)
+
+# Only check git commit commands.
+# Delegates to hooks/lib/git-cmd.js isGitSubcommand() — the canonical token-walk
+# classifier that handles env-prefix, -C path, and full-path git invocations.
+# A naive `^git\s+commit` regex misses all three; this guard fixes that (#3129).
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+if GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
+  const {isGitSubcommand}=require(process.env.GIT_CMD_LIB);
+  process.exit(isGitSubcommand(process.argv[1],'commit')?0:1);
+" "$CMD" 2>/dev/null; then
+  # Extract message from -m flag
+  MSG=""
+  if [[ "$CMD" =~ -m[[:space:]]+\"([^\"]+)\" ]]; then
+    MSG="${BASH_REMATCH[1]}"
+  elif [[ "$CMD" =~ -m[[:space:]]+\'([^\']+)\' ]]; then
+    MSG="${BASH_REMATCH[1]}"
+  fi
+
+  if [ -n "$MSG" ]; then
+    SUBJECT=$(echo "$MSG" | head -1)
+    # Validate Conventional Commits format
+    if ! [[ "$SUBJECT" =~ ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.+\))?:[[:space:]].+ ]]; then
+      # Emit a typed `code` field alongside `reason` (#2974). Tests assert
+      # on the stable code string; the reason is the human-readable copy.
+      echo '{"decision": "block", "code": "CONVENTIONAL_COMMITS_VIOLATION", "reason": "Commit message must follow Conventional Commits: <type>(<scope>): <subject>. Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore. Subject must be <=72 chars, lowercase, imperative mood, no trailing period."}'
+      exit 2
+    fi
+    if [ ${#SUBJECT} -gt 72 ]; then
+      echo '{"decision": "block", "code": "COMMIT_SUBJECT_TOO_LONG", "reason": "Commit subject must be 72 characters or less."}'
+      exit 2
+    fi
+  fi
+fi
+
+exit 0

package/hooks/dist/gsd-workflow-guard.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// GSD Workflow Guard — PreToolUse hook
+// Detects when Claude attempts file edits outside a GSD workflow context
+// (no active /gsd- skill or Task subagent) and injects an advisory warning.
+//
+// This is a SOFT guard — it advises, not blocks. The edit still proceeds.
+// The warning nudges Claude to use /gsd:quick or /gsd:fast instead of
+// making direct edits that bypass state tracking.
+//
+// Enable via config: hooks.workflow_guard: true (default: false)
+// Only triggers on Write/Edit tool calls to non-.planning/ files.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { tokenize } = require('./lib/git-cmd.js');
+
+function forceGitAddCwds(command, defaultCwd) {
+  const tokens = tokenize(command || '');
+  const separators = new Set(['&&', '||', ';', '|']);
+  const cwdList = [];
+  for (let i = 0; i < tokens.length; i++) {
+    if (path.basename(tokens[i]) !== 'git') continue;
+
+    let j = i + 1;
+    let gitCwd = defaultCwd;
+    while (j < tokens.length) {
+      const token = tokens[j];
+      const flagName = token.includes('=') ? token.slice(0, token.indexOf('=')) : token;
+      if (token === '-C' && tokens[j + 1]) {
+        gitCwd = path.resolve(gitCwd, tokens[j + 1]);
+        j += 2;
+        continue;
+      }
+      if (['-C', '--git-dir', '--work-tree'].includes(flagName) && !token.includes('=')) {
+        j += 2;
+        continue;
+      }
+      if (['--git-dir', '--work-tree', '--no-pager', '-p', '-P'].includes(flagName)) {
+        j++;
+        continue;
+      }
+      break;
+    }
+
+    if (tokens[j] !== 'add') continue;
+    for (let k = j + 1; k < tokens.length && !separators.has(tokens[k]); k++) {
+      if (tokens[k] === '--') break;
+      if (tokens[k] === '--force' || tokens[k] === '-f' || /^-[A-Za-z]*f[A-Za-z]*$/.test(tokens[k])) {
+        cwdList.push(gitCwd);
+        break;
+      }
+    }
+  }
+  return cwdList;
+}
+
+function currentBranch(cwd) {
+  const result = spawnSync('git', ['branch', '--show-current'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    windowsHide: true,
+  });
+  if (result.status !== 0) return '';
+  return result.stdout.trim();
+}
+
+function workflowGuardEnabled(cwd) {
+  const configPath = path.join(cwd, '.planning', 'config.json');
+  if (!fs.existsSync(configPath)) return false;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return Boolean(config.hooks?.workflow_guard);
+  } catch (e) {
+    return false;
+  }
+}
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+    const cwd = data.cwd || process.cwd();
+    const isWorkflowGuardEnabled = workflowGuardEnabled(cwd);
+
+    if (toolName === 'Bash') {
+      if (!isWorkflowGuardEnabled) {
+        process.exit(0);
+      }
+      const command = data.tool_input?.command || '';
+      for (const gitCwd of forceGitAddCwds(command, cwd)) {
+        const branch = currentBranch(gitCwd);
+        if (branch.startsWith('worktree-agent-')) {
+          process.stdout.write(JSON.stringify({
+            decision: 'block',
+            code: 'WORKTREE_AGENT_FORCE_ADD_FORBIDDEN',
+            reason: 'worktree-agent branches must not run git add -f or git add --force. Respect the SDK skipped_gitignored/skipped_commit_docs_false contract and leave gitignored files untracked.',
+          }));
+          process.exit(2);
+        }
+      }
+      process.exit(0);
+    }
+
+    // Only guard Write, Edit, and MultiEdit tool calls
+    if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+      process.exit(0);
+    }
+
+    // Check if we're inside a GSD workflow (Task subagent or /gsd- skill)
+    // Subagents have a session_id that differs from the parent
+    // and typically have a description field set by the orchestrator
+    if (data.tool_input?.is_subagent || data.session_type === 'task') {
+      process.exit(0);
+    }
+
+    // Check the file being edited
+    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+    // Allow edits to .planning/ files (GSD state management)
+    if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {
+      process.exit(0);
+    }
+
+    // Allow edits to common config/docs files that don't need GSD tracking
+    const allowedPatterns = [
+      /\.gitignore$/,
+      /\.env/,
+      /CLAUDE\.md$/,
+      /AGENTS\.md$/,
+      /GEMINI\.md$/,
+      /settings\.json$/,
+    ];
+    if (allowedPatterns.some(p => p.test(filePath))) {
+      process.exit(0);
+    }
+
+    if (!isWorkflowGuardEnabled) {
+      process.exit(0); // Guard disabled (default) or no GSD project
+    }
+
+    // If we get here: GSD project, guard enabled, file edit outside .planning/,
+    // not in a subagent context. Inject advisory warning.
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: `⚠️ WORKFLOW ADVISORY: You're editing ${path.basename(filePath)} directly without a GSD command. ` +
+          'This edit will not be tracked in STATE.md or produce a SUMMARY.md. ' +
+          'Consider using /gsd:fast for trivial fixes or /gsd:quick for larger changes ' +
+          'to maintain project state tracking. ' +
+          'If this is intentional (e.g., user explicitly asked for a direct edit), proceed normally.'
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail — never block tool execution
+    process.exit(0);
+  }
+});

package/hooks/dist/gsd-worktree-path-guard.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// GSD Worktree Path Guard — PreToolUse hook
+// Blocks Edit/Write/MultiEdit tool calls that target absolute paths outside the worktree root.
+//
+// Problem: gsd-executor agents spawned with isolation="worktree" sometimes issue
+// Edit/Write calls with absolute paths rooted at the MAIN repository instead of
+// the worktree (issue #260). The prose guard in agents/gsd-executor.md step 0b
+// is never enforced because the model under load skips it.
+//
+// This hook enforces the constraint at the tooling layer, making it HARD-BLOCKING.
+//
+// Triggers on: Edit, Write, and MultiEdit tool calls
+// Action: BLOCK (exit 2) if file_path is absolute and outside the worktree root
+// No-op: relative paths, non-worktree CWDs, hook errors (silent fail)
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, windowsHide: true };
+
+function git(args, cwd) {
+  return spawnSync('git', args, { ...SPAWNOPT, cwd });
+}
+
+// Walk up from `start` to find the nearest existing directory.
+// Returns null if we reach the filesystem root without finding one.
+function nearestExistingDir(start) {
+  let dir = start;
+  let prev;
+  do {
+    prev = dir;
+    try { fs.accessSync(dir, fs.constants.F_OK); return dir; } catch { /* keep walking */ }
+    dir = path.dirname(dir);
+  } while (dir !== prev);
+  return null;
+}
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+
+    // Only guard Edit, Write, and MultiEdit tool calls
+    if (toolName !== 'Edit' && toolName !== 'Write' && toolName !== 'MultiEdit') {
+      process.exit(0);
+    }
+
+    const cwd = data.cwd || process.cwd();
+
+    // Detect whether CWD is inside a linked git worktree by inspecting
+    // the git-dir path. In a linked worktree, git rev-parse --git-dir
+    // returns a path containing .git/worktrees/ as a component.
+    // In the main repo or a submodule it returns .git (or a path without /worktrees/).
+    // This approach works even when cwd is a subdirectory of the worktree.
+    const gitDirResult = git(['rev-parse', '--git-dir'], cwd);
+    if (gitDirResult.status !== 0 || !gitDirResult.stdout) {
+      process.exit(0); // not a git repo — pass through
+    }
+
+    const gitDir = gitDirResult.stdout.trim();
+    // A linked worktree's --git-dir contains .git/worktrees/ as a path component
+    const isLinkedWorktree = /[/\\]\.git[/\\]worktrees[/\\]/.test(gitDir);
+    if (!isLinkedWorktree) {
+      process.exit(0); // main repo, submodule, or separate-git-dir — no-op
+    }
+
+    // Get the raw --show-toplevel output for the worktree (cwd).
+    // We keep it raw (not path.resolve'd) to compare directly with the
+    // file's toplevel — same git binary, same format, no normalization needed.
+    const wtTopResult = git(['rev-parse', '--show-toplevel'], cwd);
+    if (wtTopResult.status !== 0 || !wtTopResult.stdout) {
+      process.exit(0); // can't determine root — fail open
+    }
+    const wtTopRaw = wtTopResult.stdout.trim();
+
+    const rawFilePath = data.tool_input?.file_path || '';
+    if (!rawFilePath) {
+      process.exit(0);
+    }
+
+    // Relative paths are always safe — they resolve relative to CWD inside the worktree
+    if (!path.isAbsolute(rawFilePath)) {
+      process.exit(0);
+    }
+
+    // Normalise .. traversal so /worktree/src/../../../main/file
+    // resolves to its true location before we check containment.
+    const filePath = path.resolve(rawFilePath);
+
+    // Find the nearest existing ancestor of filePath so we can ask git
+    // for its toplevel. The file itself may not exist yet (Write creates
+    // new files), but at least one ancestor directory must exist.
+    // We check the file itself first in case it already exists.
+    const checkDir = nearestExistingDir(
+      (() => {
+        try {
+          return fs.statSync(filePath).isDirectory() ? filePath : path.dirname(filePath);
+        } catch {
+          return path.dirname(filePath);
+        }
+      })()
+    );
+
+    if (!checkDir) {
+      // Walked to root without finding any directory — path is synthetic.
+      // Block conservatively.
+      const output = {
+        decision: 'block',
+        reason:
+          `Worktree path guard: '${filePath}' has no existing ancestor directory — ` +
+          `cannot verify it is inside the worktree '${wtTopRaw}'. Use a relative path instead.`,
+      };
+      process.stdout.write(JSON.stringify(output));
+      process.exit(2);
+    }
+
+    // Ask git for the toplevel of the file's location.
+    // Comparing two raw git --show-toplevel outputs avoids every
+    // platform-specific path normalisation pitfall (Windows 8.3 short names,
+    // case differences between realpathSync and path.resolve, forward- vs
+    // back-slash inconsistencies) — both values come from the same git binary
+    // in the same format by definition.
+    const fileTopResult = git(['rev-parse', '--show-toplevel'], checkDir);
+
+    if (fileTopResult.status !== 0 || !fileTopResult.stdout) {
+      // checkDir is not inside any git repo → cannot be inside the worktree.
+      const output = {
+        decision: 'block',
+        reason:
+          `Worktree path guard: '${filePath}' is not inside any git repository — ` +
+          `it cannot be inside the worktree at '${wtTopRaw}'. Use a relative path instead.`,
+      };
+      process.stdout.write(JSON.stringify(output));
+      process.exit(2);
+    }
+
+    const fileTopRaw = fileTopResult.stdout.trim();
+
+    // Same git toplevel → file is inside the worktree → allow
+    if (fileTopRaw === wtTopRaw) {
+      process.exit(0);
+    }
+
+    // BLOCK: file resolves to a different git root than the active worktree
+    const output = {
+      decision: 'block',
+      reason:
+        `Worktree path guard: '${filePath}' resolves to git root '${fileTopRaw}' which ` +
+        `differs from the active worktree root '${wtTopRaw}'. This likely means an ` +
+        `absolute path was derived from the orchestrator's main repository instead of ` +
+        `the active worktree. To fix: use a relative path, or re-derive the base ` +
+        `directory with \`git rev-parse --show-toplevel\` from within the worktree ` +
+        `(hook cwd: '${cwd}').`,
+    };
+
+    process.stdout.write(JSON.stringify(output));
+    process.exit(2);
+  } catch {
+    // Silent fail — never block valid tool calls due to hook errors
+    process.exit(0);
+  }
+});

package/hooks/dist/lib/git-cmd.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * git-cmd.js — token-walk git command classifier.
+ *
+ * Determines whether a shell command string invokes a specific git
+ * subcommand. Handles the four forms that a naive `^git\s+commit` regex
+ * misses:
+ *
+ *   bare:         git commit -m "..."                 ✓
+ *   -C path:      git -C /some/path commit -m "..."   ✓ (missed by regex)
+ *   env-prefix:   GIT_AUTHOR_NAME=x git commit "..."  ✓ (missed by regex)
+ *   full-path:    /usr/bin/git commit -m "..."         ✓ (missed by regex)
+ *
+ * This module is the single source of truth for git-commit detection so all
+ * hooks that need to gate on git commits share one implementation.
+ *
+ * Exported by the hooks/lib/ directory — require via a path relative to the
+ * hook's own __dirname:
+ *
+ *   const { isGitSubcommand } = require(path.join(__dirname, 'lib', 'git-cmd.js'));
+ */
+
+const path = require('path');
+
+/**
+ * Git global options that take a following argument.
+ * These must be consumed as (option, argument) pairs when walking tokens.
+ */
+const ARGUMENT_TAKING_FLAGS = new Set([
+  '-C',                // working directory
+  '--git-dir',         // path to git repository
+  '--work-tree',       // path to working tree
+  '--namespace',       // git namespace
+  '--super-prefix',    // superproject-relative prefix
+  '--exec-path',       // path to core git programs (when given an arg)
+  '--html-path',
+  '--man-path',
+  '--info-path',
+  '--list-cmds',
+]);
+
+/**
+ * Git global flags that consume no extra argument.
+ */
+const BOOLEAN_FLAGS = new Set([
+  '-p', '--paginate', '--no-pager',
+  '--no-replace-objects', '--bare',
+  '--literal-pathspecs', '--glob-pathspecs', '--noglob-pathspecs',
+  '--icase-pathspecs', '--no-optional-locks',
+  '-P', '--no-lazy-fetch',
+  '--version', '--help',
+]);
+
+/**
+ * Tokenize a shell command string.
+ * Handles single-quoted strings, double-quoted strings, and unquoted tokens.
+ * Does NOT perform variable expansion or brace expansion.
+ *
+ * @param {string} cmd
+ * @returns {string[]}
+ */
+function tokenize(cmd) {
+  const tokens = [];
+  let i = 0;
+  const len = cmd.length;
+
+  while (i < len) {
+    // Skip whitespace
+    while (i < len && /\s/.test(cmd[i])) i++;
+    if (i >= len) break;
+
+    let token = '';
+    while (i < len && !/\s/.test(cmd[i])) {
+      if (cmd[i] === "'") {
+        // Single-quoted string: take everything until closing '
+        i++;
+        while (i < len && cmd[i] !== "'") token += cmd[i++];
+        if (i < len) i++; // consume closing '
+      } else if (cmd[i] === '"') {
+        // Double-quoted string: take everything until closing " (no escape handling)
+        i++;
+        while (i < len && cmd[i] !== '"') token += cmd[i++];
+        if (i < len) i++; // consume closing "
+      } else {
+        token += cmd[i++];
+      }
+    }
+    if (token) tokens.push(token);
+  }
+
+  return tokens;
+}
+
+/**
+ * Return true if `cmd` invokes the git subcommand `sub`.
+ *
+ * @param {string} cmd  - Full shell command string (may include env vars, full paths)
+ * @param {string} sub  - Subcommand to test for, e.g. 'commit'
+ * @returns {boolean}
+ */
+function isGitSubcommand(cmd, sub) {
+  if (!cmd || !sub) return false;
+
+  const tokens = tokenize(cmd);
+  let i = 0;
+
+  // Phase 1: skip leading VAR=VALUE environment assignments
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) {
+    i++;
+  }
+
+  // Phase 2: the next token must be the git executable
+  if (i >= tokens.length) return false;
+  const gitToken = tokens[i++];
+  if (path.basename(gitToken) !== 'git') return false;
+
+  // Phase 3: consume git global options
+  while (i < tokens.length) {
+    const t = tokens[i];
+
+    // --flag=value form for argument-taking flags
+    const eqIdx = t.indexOf('=');
+    const flagName = eqIdx !== -1 ? t.slice(0, eqIdx) : t;
+    if (ARGUMENT_TAKING_FLAGS.has(flagName)) {
+      if (eqIdx !== -1) {
+        // consumed as one token: --git-dir=.git
+        i++;
+      } else {
+        // consumed as two tokens: -C /path
+        i += 2;
+      }
+      continue;
+    }
+
+    if (BOOLEAN_FLAGS.has(t)) {
+      i++;
+      continue;
+    }
+
+    // Not a global option — this is the subcommand
+    break;
+  }
+
+  // Phase 4: check the subcommand
+  if (i >= tokens.length) return false;
+  return tokens[i] === sub;
+}
+
+module.exports = { isGitSubcommand, tokenize };