fix(ai-detection): match binary tokens, not loose substrings (#239)

* fix(ai-detection): match binary tokens, not loose substrings

`AIToolService.detectToolFromArgs` was using `.includes('claude'|'codex'|'gemini')`
on the full `ps args=` string, with claude checked first, which mis-detected codex
(or gemini) as claude whenever the args string contained "claude" anywhere — a
quoted prompt, a worktree slug like `agent-shows-claude-not-codex`, or an install
path under `~/.claude*`.

Strict pass first: strip shell-quoted spans (single + double-quoted argument
bodies), then match each tool name only at a token boundary
(`(?:^|[\s/])name(?=\s|$)`). The original `.includes()` chain is kept as a
fallback for legacy invocation shapes the strict regex may not recognize.
Token regexes are built once at module load from `AI_TOOLS` keys, so a new tool
added to the config is detected automatically.

Adds 13 table-driven cases under `detectAllSessionAITools`: codex/gemini on a
claude-bearing slug, codex/gemini with a claude-bearing prompt (quoted by
shellQuote), codex/gemini under a claude-bearing install path, the bash-wrapper
resume/fresh shape, case-insensitive variants, and the legacy fallback path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Address PR review comments

Trim multi-paragraph JSDoc on `detectToolFromArgs` and the `what`-describing
lines from the module-level comment block, per AGENTS.md ("Multi-paragraph
JSDoc... should be rare", "Don't explain WHAT the code does"). Keep the
load-bearing notes: the bug context, the shellQuote/quote-stripping rationale,
and the iteration-order dependency.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Address PR review: escape tool names in regex builder

Defensive: regex-escape the tool name before interpolation in TOOL_TOKEN_RES.
All current tool names (claude, codex, gemini) are regex-safe, but a future
addition with `.`, `+`, `(`, etc. would silently change the strict-match
semantics without it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Address PR review: drop task/branch references in comments

Per AGENTS.md: don't reference the current task, fix, or callers in code
comments. Trim function comment to the timeless invariant; rename test cases
to short stand-alone labels and consolidate two WHY notes into one header
covering shellQuote behaviour for the table.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: agent-era-ai

src/services/AIToolService.ts

@@ -12,6 +12,15 @@ const CLAUDE_WAITING_RE = /❯\s+\d+\.\s+\w+/m;
 // for long-running operations, broaden to `/…\s*\(\d+(s|m)/`.
 const CLAUDE_WORKING_RE = /…\s*\(\d+s/;
 
+// Iteration order is load-bearing for the loose fallback below: when args contains
+// substrings of multiple tool names, the first hit wins. Object.keys preserves insertion
+// order, so reordering AI_TOOLS in constants.ts changes that priority silently.
+const TOOL_NAMES = Object.keys(AI_TOOLS) as Array<keyof typeof AI_TOOLS>;
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const TOOL_TOKEN_RES: Record<keyof typeof AI_TOOLS, RegExp> = Object.fromEntries(
+  TOOL_NAMES.map(name => [name, new RegExp(`(?:^|[\\s/])${escapeRe(name)}(?=\\s|$)`)])
+) as Record<keyof typeof AI_TOOLS, RegExp>;
+
 export class AIToolService {
   /**
    * Get tool name for display
@@ -80,22 +89,21 @@ export class AIToolService {
     return toolsMap;
   }
 
-  /**
-   * Detect AI tool from process arguments
-   */
+  // Strict pass first: a tool name inside a prompt, slug, or install path must not
+  // outrank the actually-running binary. Falls back to loose `.includes()` for legacy
+  // invocation shapes the strict pass may not recognize.
   private detectToolFromArgs(args: string): AITool {
     const argsLower = args.toLowerCase();
-    
-    if (argsLower.includes('/claude') || argsLower.includes('claude')) {
-      return 'claude';
-    }
-    if (argsLower.includes('/codex') || argsLower.includes('codex')) {
-      return 'codex';
+    // shellQuote uses single quotes for non-safe args; strip those plus double-quoted spans
+    // so prompt/display text can't be mistaken for a binary token.
+    const stripped = argsLower.replace(/'[^']*'/g, '').replace(/"[^"]*"/g, '');
+
+    for (const tool of TOOL_NAMES) {
+      if (TOOL_TOKEN_RES[tool].test(stripped)) return tool;
     }
-    if (argsLower.includes('/gemini') || argsLower.includes('gemini')) {
-      return 'gemini';
+    for (const tool of TOOL_NAMES) {
+      if (argsLower.includes(tool)) return tool;
     }
-    
     return 'none';
   }
 

tests/unit/AIToolService.test.ts

@@ -1,5 +1,6 @@
 import {AIToolService} from '../../src/services/AIToolService.js';
 import {AI_TOOLS} from '../../src/constants.js';
+import type {AITool} from '../../src/models.js';
 
 // Mock the command execution functions
 jest.mock('../../src/shared/utils/commandExecutor.js', () => ({
@@ -82,11 +83,48 @@ random-session:33333`);
       });
 
       const result = await aiToolService.detectAllSessionAITools();
-      
+
       expect(result.get('dev-project-feature')).toBe('claude');
       expect(result.has('other-session')).toBe(false);
       expect(result.has('random-session')).toBe(false);
     });
+
+    describe('disambiguates tool when args mention another tool name', () => {
+      // shellQuote leaves chars like `[A-Za-z0-9_\-./=:]+` bare; anything with spaces or
+      // special chars is wrapped in single quotes. Both shapes appear in the cases below.
+      const cases: Array<[string, string, AITool]> = [
+        ['codex: claude in worktree slug (unquoted)', `bash -c codex resume --last agent-shows-claude-not-codex || codex agent-shows-claude-not-codex`, 'codex'],
+        ['codex: claude in quoted prompt', `bash -c codex resume --last 'fix the claude bug' || codex 'fix the claude bug'`, 'codex'],
+        ['codex: claude in install path', `node /home/user/.claude-tools/codex/bin/codex resume --last`, 'codex'],
+        ['gemini: claude in quoted prompt', `bash -c gemini --resume latest 'tame the claude noise' || gemini 'tame the claude noise'`, 'gemini'],
+        ['gemini: claude in install path', `node /home/user/.claude-tools/gemini/bin/gemini --resume latest`, 'gemini'],
+        ['claude: quoted display name', `claude -n 'feature - project' --dangerously-skip-permissions`, 'claude'],
+        ['claude: bash-wrapper resume/fresh', `bash -c claude --continue -n 'foo' || claude -n 'foo'`, 'claude'],
+        ['case-insensitive: uppercase CLAUDE', 'CLAUDE', 'claude'],
+        ['case-insensitive: uppercase path codex', '/USR/BIN/CODEX', 'codex'],
+        ['non-tool: bash', 'bash', 'none'],
+        ['non-tool: vim', 'vim', 'none'],
+        // Loose fallback path: no token boundary present, but the substring still resolves
+        // the way it did before strict matching was introduced.
+        ['legacy embedded substring', 'someweirdtoolnameclaudethingembedded', 'claude'],
+      ];
+
+      for (const [name, argsLine, expected] of cases) {
+        test(name, async () => {
+          (runCommandQuickAsync as jest.Mock).mockImplementation((cmdArgs: string[]) => {
+            if (cmdArgs.includes('list-panes') && cmdArgs.includes('-a')) {
+              return Promise.resolve('dev-p-f:99999');
+            }
+            if (cmdArgs.includes('-p') && cmdArgs.includes('99999')) {
+              return Promise.resolve(` 99999 ${argsLine}`);
+            }
+            return Promise.resolve('');
+          });
+          const result = await aiToolService.detectAllSessionAITools();
+          expect(result.get('dev-p-f')).toBe(expected);
+        });
+      }
+    });
   });
 
   describe('getStatusForTool', () => {

tracker/items/agent-shows-claude-not-codex/implementation.md

@@ -0,0 +1,52 @@
+# Implementation — agent-shows-claude-not-codex
+
+## What was built
+
+Tightened `AIToolService.detectToolFromArgs` (`src/services/AIToolService.ts:86-117`) so that tool names inside a prompt, slug, or install path no longer outrank the actually-running binary.
+
+**Two-pass detection:**
+1. **Strict pass** — strip shell-quoted spans (`'...'`, `"..."`) from the lowercased args, then for each tool match a word-boundary regex `(?:^|[\s/])${tool}(?=\s|$)`. The binary is recognized only when it appears as a standalone token (start of string, after `/`, or after whitespace, and followed by whitespace or end of string).
+2. **Loose fallback** — if the strict pass returns `'none'`, fall back to the original `.includes()` chain. Preserves any historically-correct legacy detection forms; latent bugs in the loose path were already there before this change.
+
+**Non-changes:**
+- `isAIPaneCommand` left as-is — it sees only the process command name (not full args), and its coarseness is intentional for pane shortlisting.
+- `getStatusForTool`, `isWorking`, `isWaitingForTool`, and `AI_TOOLS` config unchanged.
+- No tmux launch, fallback chain, or `aiSessionMemory` changes.
+
+## Tests
+
+Added 13 table-driven cases under `detectAllSessionAITools › disambiguates tool when args mention another tool name` in `tests/unit/AIToolService.test.ts`:
+
+- Codex on a worktree slug containing "claude" (the live repro for this branch).
+- Codex with a quoted prompt containing "claude" (shellQuote single-quotes any prompt with spaces).
+- Codex installed under a path containing "claude".
+- Gemini parallels (claude-bearing prompt; claude-bearing install path).
+- Claude with quoted display name.
+- Claude bash-wrapper resume/fresh shape.
+- Case-insensitive variants (`CLAUDE`, `/USR/BIN/CODEX`).
+- Non-tool processes (`bash`, `vim`) → `'none'`.
+- Legacy fallback path (`someweirdtoolnameclaudethingembedded`) still resolves to `'claude'`.
+
+Existing cases (`claude`, `/usr/bin/claude`, `node /usr/bin/codex`, `node /usr/bin/gemini`, the `detects AI tools across multiple sessions` fixture) all continue to pass.
+
+## Key decisions
+
+- **Quote stripping in the strict pass.** `shellQuote` always wraps args containing spaces in single quotes, so a prompt like `'fix the claude bug'` would otherwise space-border "claude" and the strict regex would still match it. Stripping `'...'` (and defensively `"..."`) in the strict-pass input cleanly removes prompt/display content from tool detection while leaving the binary tokens intact.
+- **Strict-then-loose, not strict-only.** Per requirements decision: any quietly-correct legacy detection form (e.g. `someweirdtoolnameclaudethingembedded`) keeps resolving as it did. The fallback also gives us a safety net if the args shape ever changes in unexpected ways across platforms or tmux versions.
+- **Test through `detectAllSessionAITools`.** `detectToolFromArgs` is private; rather than expose it for tests, the new cases drive it via the public path with mocked `tmux list-panes` + `ps` output. The existing test file already established that pattern.
+
+## Test/typecheck status
+
+- `npx jest tests/unit/AIToolService.test.ts` → 38/38 pass (13 new).
+- `npx jest` (full suite) → 78 suites, 801/801 pass.
+- `npx tsc -p tsconfig.test.json` → clean.
+
+## Notes for cleanup
+
+- Comment in the new function explains *why* (the bug) without restating *what* (the regex). Should survive a review pass.
+- No documentation files reference `detectToolFromArgs`. README/AGENTS.md don't need updates.
+- No new exports or public API surface — change is internal to `AIToolService`.
+
+## Stage review
+
+Strict-then-loose detection in `AIToolService.detectToolFromArgs`, single fix point. 13 new table-driven cases plus the original 9 still green; full suite (801 tests) and typecheck clean. No commits made yet — leaving that for cleanup so the user can decide on commit granularity.

tracker/items/agent-shows-claude-not-codex/notes.md

@@ -0,0 +1,55 @@
+# Discovery — agent-shows-claude-not-codex
+
+## Problem
+
+When a worktree is running Codex (or Gemini), the kanban / status UI sometimes labels the agent as "Claude" instead of the tool that is actually attached. This was hit on this very branch: a Codex session launched with the tracker prompt for slug `agent-shows-claude-not-codex` is misdetected as `claude`.
+
+## Findings
+
+**Root cause** — `AIToolService.detectToolFromArgs` uses a loose substring match:
+
+```ts
+// src/services/AIToolService.ts:86-100
+const argsLower = args.toLowerCase();
+if (argsLower.includes('/claude') || argsLower.includes('claude')) return 'claude';
+if (argsLower.includes('/codex')  || argsLower.includes('codex'))  return 'codex';
+if (argsLower.includes('/gemini') || argsLower.includes('gemini')) return 'gemini';
+```
+
+The bare `.includes('claude')` matches any occurrence of the literal string anywhere in the process command line — not just the binary name. Claude is also checked first, so any string containing "claude" wins over "codex" / "gemini".
+
+**Where args comes from** — `detectAllSessionAITools` reads `pane_pid` for each `dev-*` tmux session, then `ps -p <pid> -o args=` returns that process's command line (`AIToolService.ts:37-81`). For the resume-or-fresh chain (`WorktreeCore.launchAISessionWithFallback`, line 620), `tmux new-session ... '<resume> || <fresh>'` causes the pane's first process to be `/bin/sh -c "<resume> || <fresh>"`. So the args string includes the full resume + fresh commands, all flags, and `initialPrompt` if any — and any of those substrings can contain "claude".
+
+**Reproduction** — verified with the exact detection function:
+
+```
+detectToolFromArgs("bash -c codex resume --last 'fix claude bug' || codex 'fix claude bug'")
+  → "claude"   (BUG: actual tool is codex)
+
+detectToolFromArgs("bash -c codex resume --last 'agent-shows-claude-not-codex' || codex 'agent-shows-claude-not-codex'")
+  → "claude"   (BUG: this is the live scenario for this branch)
+
+detectToolFromArgs("node /home/user/.claude-tools/codex/bin/codex")
+  → "claude"   (BUG: codex installed under a path containing 'claude')
+```
+
+The opposite direction (claude misdetected as codex) doesn't trigger, because the `claude` binary name virtually always appears in a Claude pane's args before any `codex`/`gemini` substring.
+
+**Triggers in practice**
+1. `initialPrompt` passed to `launchAISessionWithFallback` (line 615) when the prompt text contains "claude" — common for tracker items whose slug or description mentions Claude (e.g. this branch).
+2. `displayName` for Claude is set to `${feature} - ${project}` (`WorktreeCore.ts:403`); it's only attached for claude (`-n` flag), so it can't poison codex args. But fragments of feature/project names that contain "claude" can still arrive via `initialPrompt`.
+3. Codex/Gemini installed under a path that contains "claude" (less common but possible — e.g. a `~/.claude*` shared tools directory).
+
+**Test coverage gap** — `tests/unit/AIToolService.test.ts` only exercises clean fixtures (`node /usr/bin/codex`, `claude`, `node /usr/bin/gemini`). No test covers args strings that mix tool names or include prompt text.
+
+## Recommendation
+
+Tighten `detectToolFromArgs` to match the *binary*, not any substring. Two viable approaches:
+
+**A. Word-boundary regex on the executable basename.** Match `claude`, `codex`, `gemini` only when they appear as a standalone token (start of string, after `/`, after whitespace) and are followed by whitespace or end-of-string. That excludes occurrences inside `agent-shows-claude-not-codex` or `--prompt 'fix claude'`.
+
+**B. Parse the executable token explicitly.** Strip a leading `bash -c "..."` / `sh -c "..."` wrapper, take the first non-`node` token, and `path.basename()` it. Compare against the known set.
+
+Recommendation: **A**. It's a one-line change to a single regex per tool, keeps the existing structure, and is robust against the `bash -c "<resume> || <fresh>"` shape without us having to faithfully tokenize the inner command line. A quote-unaware parser (B) gets brittle around prompt text with embedded quotes, whereas a regex like `/(?:^|[\s/])claude(?=\s|$)/` cleanly says "the binary, anywhere it might appear, but never as a substring inside another token". Order independence falls out of this for free.
+
+Tests to add alongside the fix: codex launched with claude-bearing prompt; codex installed at a claude-bearing path; the bash-wrapper resume/fallback shape; gemini in the same scenarios.

tracker/items/agent-shows-claude-not-codex/requirements.md

@@ -0,0 +1,38 @@
+# Requirements — agent-shows-claude-not-codex
+
+## Problem
+
+When a worktree is running Codex (or Gemini), the kanban / status UI sometimes labels the agent as "Claude" instead of the tool that is actually attached. This was hit on this very branch: a Codex session launched with the tracker prompt for slug `agent-shows-claude-not-codex` is misdetected as `claude`.
+
+## Why
+
+`AIToolService.detectToolFromArgs` (`src/services/AIToolService.ts:86-100`) decides the tool by `argsLower.includes('claude' | 'codex' | 'gemini')` against the full `ps -o args=` output, with `claude` checked first. The args string for a fallback-chain pane is `/bin/sh -c "<resume> || <fresh>"`, so any `initialPrompt`, slug, install-path, or display fragment containing "claude" wins over the actually-running binary. Triggers seen: tracker prompts that quote a claude-bearing slug, codex installed under a path containing "claude", or any prompt text mentioning Claude.
+
+## Summary
+
+Replace the loose substring match in `detectToolFromArgs` with a binary-aware match — a word-boundary regex anchored on the executable token, so `claude` / `codex` / `gemini` are recognized only when they appear as a standalone token (start of string, after `/`, or after whitespace) and are followed by whitespace or end-of-string. Preserve the existing `.includes()` behaviour as a final fallback only when the strict pass returns `'none'`, so any quietly-correct legacy detections aren't regressed. Keep `isAIPaneCommand` unchanged. Add unit tests covering the broken cases and the bash-wrapper fallback shape.
+
+## Acceptance criteria
+
+### Detection correctness
+
+1. Given `ps args` of `bash -c "codex resume --last 'agent-shows-claude-not-codex' || codex 'agent-shows-claude-not-codex'"`, `detectToolFromArgs` returns `'codex'`.
+2. Given `ps args` of `bash -c "codex resume --last 'fix the claude bug' || codex 'fix the claude bug'"`, `detectToolFromArgs` returns `'codex'`.
+3. Given `ps args` of `node /home/user/.claude-tools/codex/bin/codex resume --last`, `detectToolFromArgs` returns `'codex'`.
+4. Given `ps args` of `bash -c "gemini --resume latest 'tame the claude noise' || gemini 'tame the claude noise'"`, `detectToolFromArgs` returns `'gemini'`.
+5. Existing positive cases keep returning the same tool: `claude`, `/usr/bin/claude`, `node /usr/bin/codex`, `node /usr/bin/gemini` (matching today's `AIToolService.test.ts:43-67`).
+6. When the strict pass finds no binary token, the function falls back to today's `.includes()` behaviour (claude → codex → gemini → none) and returns the same answer it does today, so any legacy invocation forms still resolve.
+7. Args that match no tool — `bash`, `vim`, empty string — return `'none'`.
+8. Matching is case-insensitive (e.g. `CLAUDE`, `/USR/BIN/CODEX` resolve correctly).
+
+### Scope and non-changes
+
+9. `isAIPaneCommand` is unchanged — its substring behaviour is intentional and used only for coarse pane shortlisting.
+10. `getStatusForTool`, `isWorking`, `isWaitingForTool`, and `AI_TOOLS` config are unchanged.
+11. No change to tmux launch, fallback chain, or `aiSessionMemory` behaviour.
+
+### Tests
+
+12. `tests/unit/AIToolService.test.ts` adds table-driven cases for ACs 1–4 and 7–8, plus an explicit case asserting that the legacy fallback path still resolves a "weird but historically-OK" args string (AC 6). Gemini gets parallel coverage to Codex: claude-in-prompt, claude-in-install-path, and the bash-wrapper resume-or-fresh shape.
+13. The existing `detectAllSessionAITools` test continues to pass with no fixture changes.
+14. `npm run typecheck` and `npm test` are green.