feat(hooks+llm): turn-based memory injection on UserPromptSubmit + Claude CLI HyDE provider

[Huntehhh]

Summary

Three coupled changes targeting Pro-tier subscription users on Windows.

Turn-based injection (UserPromptSubmit) — fires once per session when user-turn count ≥ 13 OR current prompt length > 333 chars (whichever first). Query = last 6 user turns concatenated, separated by \n---\n, giving the vector pipeline richer semantic context than the existing raw-prompt path. Marker file at ~/.truememory/turn_injected/<safe_session_id> dedupes re-fires; pattern mirrors should_extract_session / mark_session_extracted. The existing _detect_recall regex path is untouched and still fires every turn for explicit recall questions — both paths can emit on the same prompt, combined into one additionalContext JSON line.

Claude CLI priority-1 _build_llm_fn provider — _build_claude_cli_llm wraps the existing truememory.ingest.models._complete_claude_cli helper into the (prompt) -> str shape search_deep expects. Pro tier now gets HyDE for free on subscription auth — no API key required. Opt out via TRUEMEMORY_DISABLE_CLAUDE_CLI=1.

Sub-agent hook skip — new is_subagent_invocation() helper in _shared.py; all 3 hooks early-return for Claude Code Task-tool sub-agents (detected via agent_id field in stdin OR /subagents/ in transcript_path). Stops per-sub-agent terminal flash + orchestrator-prompt memory pollution.

Depends on #345 (fcntl Windows portability) — cherry-picked into this branch; will dedupe on rebase once #345 merges.

Changes

File	Change
truememory/mcp_server.py	+_build_claude_cli_llm, prepend claude_cli to _LLM_PROVIDERS, add no-key path + TRUEMEMORY_DISABLE_CLAUDE_CLI kill-switch in _build_llm_fn
truememory/ingest/hooks/_shared.py	+is_subagent_invocation, +TURN_INJECTED_DIR, +count_user_turns, +already_injected, +mark_injected
truememory/ingest/hooks/user_prompt_submit.py	+_build_turn_based_query, +_try_turn_based_injection, sub-agent guard in main(), single-emit restructure so explicit-recall + turn-based combine into one additionalContext line
truememory/ingest/hooks/session_start.py	Sub-agent guard at top of main()
truememory/ingest/hooks/stop.py	Sub-agent guard at top of main()
tests/test_llm_fn_init.py	+6 Claude CLI cases; fixture defaults TRUEMEMORY_DISABLE_CLAUDE_CLI=1 so legacy API-key tests don't pick up the new priority-1 provider
tests/test_turn_based_injection.py	NEW — 19 cases covering helpers, gate logic, marker dedup, kill switch, search-exception graceful-degrade
tests/ingest/test_hooks_windows_portability.py	From #345 cherry-pick — will dedupe on rebase

New env vars (all overridable, sensible defaults)

Var	Default	Effect
TRUEMEMORY_INJECT_AFTER_TURNS	13	Turn-count trigger threshold
TRUEMEMORY_INJECT_AFTER_CHARS	333	Prompt-length trigger threshold
TRUEMEMORY_INJECT_QUERY_TURNS	6	Recent turns concatenated into the query
TRUEMEMORY_INJECT_QUERY_TURN_CHARS	500	Per-turn truncation in the query (prevents pasted code blowing up the embedding input)
TRUEMEMORY_INJECT_RECALL_LIMIT	15	Memories fetched
TRUEMEMORY_INJECT_BULLET_CHARS	300	Per-bullet truncation in the emitted block
TRUEMEMORY_INJECT_DISABLED	unset	Kill switch — disables turn-based injection entirely
TRUEMEMORY_DISABLE_CLAUDE_CLI	unset	Force _build_llm_fn to skip Claude CLI and fall through to API-key providers
TRUEMEMORY_HYDE_CLAUDE_MODEL	claude-haiku-4-5	Model used for HyDE doc generation via Claude CLI

Test plan

• pytest tests/test_llm_fn_init.py tests/test_turn_based_injection.py tests/ingest/test_hooks_windows_portability.py -v → 37 pass / 1 skip (fcntl.flock path, Linux-only)
• Sub-agent detection: 6/6 cases pass (agent_id, agent_type, /subagents/ path, mixed-slash Windows paths, empty input)
• In-process smoke of _try_turn_based_injection with stubbed Memory — emits <truememory-context> block at trigger=turns, writes marker, re-fire returns None
• On a machine with claude.exe + OPENROUTER_API_KEY set: truememory_search_deep selects claude_cli provider; verify _current_llm_provider_name == "claude_cli" and zero OpenRouter spend
• End-to-end manual smoke in a fresh Claude Code session: type a 350-char prompt → <truememory-context> emitted (~500ms HyDE pause); subsequent prompts → no re-fire; marker at ~/.truememory/turn_injected/<session_id> exists with trigger, query_chars, n_results, timestamp
• Sub-agent Task spawn: hooks exit in <10ms, no recall / buffer write / ingestion side effects, no terminal flash

Breaking changes

Provider priority shift for users with both Claude CLI on PATH and an API key set:

- _LLM_PROVIDERS = (
-     ("anthropic", "ANTHROPIC_API_KEY", ...),
-     ("openrouter", "OPENROUTER_API_KEY", ...),
-     ("openai", "OPENAI_API_KEY", ...),
- )
+ _LLM_PROVIDERS = (
+     ("claude_cli", "", "", "_build_claude_cli_llm"),   # NEW — priority 1
+     ("anthropic", "ANTHROPIC_API_KEY", ...),
+     ("openrouter", "OPENROUTER_API_KEY", ...),
+     ("openai", "OPENAI_API_KEY", ...),
+ )

Old behavior: API key wins → user pays per HyDE call.
New behavior: Claude CLI wins → user pays nothing (subscription auth).

Users who deliberately want the API-key path (e.g., centralized billing, rate-limit isolation, paid Anthropic plan for HyDE consistency) set TRUEMEMORY_DISABLE_CLAUDE_CLI=1. Documented in the new env-var table above.

Users without claude.exe on PATH see identical behavior — the new provider falls through to the existing API-key chain.

Co-Authored-By: claude-opus-4-7 wontreply@getfucked.ai