bug(plugin): SessionStart bootstrap and stale global UserPromptSubmit hook leave mode workflow behavior inconsistent in v5.3.0

[JeremyDev87]

Summary

CodingBuddy's keyword-mode experience in v5.3.0 is not uniformly broken, but it is inconsistent across installation states because the plugin currently relies on a split bootstrap design:

• hooks/hooks.json does not include UserPromptSubmit
• session-start.py bootstraps a global UserPromptSubmit hook into ~/.claude/settings.json
• upgraded installs can keep running an older global hook instead of converging on the current self-contained hook

The result is that fresh installs and upgraded installs can behave differently, and stale global hook state can mask or override the intended standalone-capable path.

What this issue is really about

This is a parent issue for the plugin's mode-bootstrap architecture and legacy-hook migration gap.

It is not an assertion that every v5.3.0 user always gets raw Claude with no mode behavior. Fresh installs can still bootstrap correctly via SessionStart. The more accurate failure boundary is:

• bootstrap behavior is split between plugin-local metadata and global settings mutation
• upgraded installs can retain stale global hook state
• users may see inconsistent behavior across environments

Scope

In scope:

• SessionStart-based bootstrap of the global UserPromptSubmit hook
• stale legacy global hook migration
• investigation of plugin install/cache artifacts that affect MCP-mode discovery
• fallback and diagnostic hardening for mode-detection behavior

Out of scope:

• unrelated TUI behavior
• cosmetic documentation changes with no effect on bootstrap or migration

Acceptance criteria

• fresh installs and upgraded installs converge on the same current self-contained mode-detection behavior
• stale legacy global hook state no longer overrides or masks the intended path
• plugin install/bootstrap behavior is clearly diagnosable
• parent and child issues describe the actual current architecture accurately

Related sub-issues

• bug(plugin): Stale global ~/.claude/hooks/codingbuddy-mode-detect.py from prior version not cleaned up during v5.3.0 install #1381 stale global hook migration / refresh
• refactor(plugin): clarify or simplify the UserPromptSubmit bootstrap architecture #1380 bootstrap architecture clarification or simplification
• investigate(plugin/install): installed plugin cache may drop .mcp.json even when the package tarball includes it #1382 install-path or marketplace-path investigation for .mcp.json
• investigate(cli/install): some environments may still expose a codingbuddy binary that does not advertise mcp #1383 environment or binary mismatch investigation for codingbuddy mcp
• hardening(plugin): eliminate stale mandatory-MCP hook behavior and make standalone fallback more visible #1384 stale mandatory-MCP hook behavior hardening

Notes

• current session-start.py intentionally installs a global UserPromptSubmit hook into ~/.claude/settings.json
• the highest-confidence concrete bug in this family is the stale-hook migration problem, not a universal total failure of the keyword workflow

[JeremyDev87]

Rewriting this issue because the current framing overstates the failure mode and mixes several different root causes together.

What the current code actually does today:

• hooks/hooks.json does not register UserPromptSubmit, but session-start.py intentionally bootstraps a global UserPromptSubmit hook into ~/.claude/settings.json
• fresh installs can therefore still acquire keyword-mode handling after SessionStart/bootstrap
• the most concrete bug is that upgraded installs can retain a stale legacy global hook instead of converging on the new self-contained hook

So the right parent issue is not "the entire mode workflow is completely broken for everyone" but "the bootstrap architecture plus stale-hook migration leaves behavior inconsistent across fresh and upgraded installs."

Rewriting the issue to reflect the actual current design and the real failure boundary, so follow-up fixes target the right layer.

[JeremyDev87]

Parent Closure — All Sub-Issues Resolved

Acceptance Criteria Verification

• Fresh installs and upgraded installs converge on same behavior
  • Resolved via bug(plugin): Stale global ~/.claude/hooks/codingbuddy-mode-detect.py from prior version not cleaned up during v5.3.0 install #1381 + hardening(plugin): eliminate stale mandatory-MCP hook behavior and make standalone fallback more visible #1384 (bundled in PR fix(plugin): migrate stale global codingbuddy-mode-detect.py on install #1389, merged aab1fd4): postinstall migration removes stale ~/.claude/hooks/codingbuddy-mode-detect.py and cleans legacy UserPromptSubmit entries from ~/.claude/settings.json
• Stale legacy global hook state no longer overrides or masks intended path
  • Resolved via bug(plugin): Stale global ~/.claude/hooks/codingbuddy-mode-detect.py from prior version not cleaned up during v5.3.0 install #1381 (PR fix(plugin): migrate stale global codingbuddy-mode-detect.py on install #1389): scripts/migrate-legacy-hooks.js runs idempotently on every install, backs up settings.json, preserves unrelated entries
• Plugin install/bootstrap behavior is clearly diagnosable
  • Resolved via refactor(plugin): clarify or simplify the UserPromptSubmit bootstrap architecture #1380 (PR refactor(plugin): clarify UserPromptSubmit bootstrap architecture #1388, merged e9480ee): docs/bootstrap-architecture.md documents the hooks/hooks.json vs session-start.py split, regression tests guard the architecture
  • Resolved via hardening(plugin): eliminate stale mandatory-MCP hook behavior and make standalone fallback more visible #1384 (PR fix(plugin): migrate stale global codingbuddy-mode-detect.py on install #1389): standalone fallback diagnostic markers (# Backend: mcp-enhanced | standalone | standalone-minimal) in hooks/user-prompt-submit.py
• Parent and child issues accurately describe current architecture
  • Achieved through body rewrites during Wave 1 (investigate/hardening/refactor retargeting)

Sub-Issue Resolution Summary

#	Type	PR	Merge	Status
#1380	refactor	#1388	e9480ee	✅ Merged
#1381	bug	#1389	aab1fd4	✅ Merged (bundled)
#1382	investigate	—	—	✅ Investigation complete, root cause identified (comment) — npm pack drops gitignored build artifact. Follow-up: git-track .mcp.json or add release.yml verify step
#1383	investigate	—	—	✅ Investigation complete, stale global npm install confirmed as root cause (comment) — current source fully supports codingbuddy mcp
#1384	hardening	#1389	aab1fd4	✅ Merged (bundled with #1381)

Post-Merge Verification

• yarn workspace codingbuddy-claude-plugin typecheck: clean
• yarn workspace codingbuddy-claude-plugin build: success
• Review cycle: both PRs approved via dedicated EVAL review panel (0 Critical / 0 High)

Follow-ups (not blocking this closure)

• investigate(plugin/install): installed plugin cache may drop .mcp.json even when the package tarball includes it #1382 fix path: git-track .mcp.json + namespace-manifest.json or add release.yml tarball verify step (new issue can be created)
• investigate(cli/install): some environments may still expose a codingbuddy binary that does not advertise mcp #1383 fix path: add support guidance to issue body advising npm uninstall -g codingbuddy && npm install -g codingbuddy@latest (or close issue as environment-only)

Closing as all acceptance criteria met.