[halindrome]

Summary

Tell subagents that have no MCP tools how to reach the graph through the CLI.

Closes #2837

The installed SubagentStart hook matches every agent type ("*"), but many agents are defined with an explicit tool list that has no MCP tools (e.g. tools: Read, Grep, Glob, Bash). The SubagentStart input carries no tool list, so the hook can't detect this. Those agents can still use the graph through codebase-memory-mcp cli <tool>, but the reminder never said so.

Change

• ha_lifecycle_json_from_root (src/cli/hook_augment.c): for SubagentStart only, append one sentence to both the indexed-project and no-project context variants:

  If the codebase-memory MCP tools are not available to you, run the same tools from the shell: codebase-memory-mcp cli <tool> --help shows each tool's flags.

• Other lifecycle events (SessionStart, compaction) are unchanged. The same context reaches every dialect (Claude Code, Copilot, Hermes, Kimi, Cline).
• The longest variant is 1068 bytes, well inside the 2048-byte context buffer.

Acceptance criteria

1. The SubagentStart context (with and without an indexed project) contains the CLI fallback sentence naming codebase-memory-mcp cli <tool> --help.
2. The SessionStart and compaction contexts do not contain it.
3. The context is never truncated: the longest variant stays under the buffer size.
4. Existing hook tests stay green.

Testing

• tests/test_cli.c: new assertions on the SubagentStart outputs (indexed and unindexed), plus a negative assertion on SessionStart. Red before the change, green after.
• The 38 cli_hook* tests pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CDDUoWEZMNZ9fLvzp2pPGT

[halindrome]

QA round 1 for this change. It ran on the fork PR (halindrome#5) before the commits were squashed into 7f2fd10, so any commit SHAs below refer to the pre-squash history. The QA was performed by Claude Opus 5.5 (Anthropic) in Claude Code.

QA Round 1

Round 1 · PR #5 · Reviewer: Claude Opus 5.5 (qa-panel, sequential single-reviewer path: tiny diff) · Contract source: upstream issue #2837 + PR acceptance criteria

Verdict: clean. The change is correct; no findings.

Contract Verification

Criterion	Status	Evidence
SubagentStart context (indexed + no-project) contains the CLI fallback sentence naming codebase-memory-mcp cli <tool> --help	satisfied	src/cli/hook_augment.c 1709–1716: cli_hint set only when event == "SubagentStart", appended via a trailing %s to both snprintf formats (1733–1734 indexed, 1745–1746 no-project). Covered by cli_hook_session_resolves_custom_named_index_by_root_path (indexed) and cli_hook_augment_lifecycle_output_contract (unindexed).
SessionStart and compaction contexts do NOT contain it	satisfied	Exact match on "SubagentStart"; every other event (SessionStart, PreCompact, PostCompaction, pre_llm_call, TaskStart, UserPromptSubmit) gets "". Tests assert absence on SessionStart (indexed + unindexed). Compaction is untested but takes the same "" branch.
Never truncated: longest variant < 2048 bytes for every dialect	satisfied	Worst case computed from the format literals: indexed with a 191-byte project name (HA_METADATA_CAP 192) + Tier 3 + hint = 1066 bytes; no-project = 804 bytes. Hint goes into the shared context[2048] before dialect selection, so the bound holds for every wrapper.
Output remains valid JSON for every dialect	satisfied	Builders serialise via yyjson_mut_obj_add_str (escaping). The hint has no " or \. Hermes, Kimi and Cline never accept SubagentStart (ha_dialect_event_supported, 1133–1161), so they never receive it. Tests parse the output with yyjson_read.
Tests red before / green after; existing tests stay green	satisfied	New assertions match a backticked string that exists only in the new literal (red before). Test run below.

Schema Change

No schema change (hook context string + tests). Schema gate not configured — did not run.

Security

SAST not applicable: no CI security stage is configured for this target, so no scan ran.

Notes

• The hint is accurate: run_cli handles --help after the tool name and calls cbm_cli_print_tool_help.
• All three callers of ha_lifecycle_json_from_root take back an opaque string; there is no downstream impact.
• Findings were not attributed on this path (sequential); there were none to attribute.

Test run

• scripts/test.sh --suites "<all 191 suites from build/c/test-runner --list-suites>" on 7f2fd10: 9933 passed, 118 failed, 12 skipped.
  • The failures were all in incremental (one cascade from its first fastapi full index returning NULL) and one grammar_probe_f assertion.
  • The full run was on a shared, heavily loaded machine.
  • Every cli suite test, including the new hook assertions, passed.
• Re-run in isolation: scripts/test.sh --suites "incremental grammar_probe_f" gives 348 passed, 0 failed on this branch, and the same 348 passed, 0 failed on unmodified upstream/main. The earlier failures were load-induced, not caused by this PR, which changes only a hook context string.
• The default scripts/test.sh stops at contract Step 0t (tests/test_runtime_isolation_contract.sh, inside scripts/security-install.sh) in this local environment. Unmodified main fails the same way, so it is environmental. CI runs the full default leg.

Navigation: cmm+ctx

---

Posted by the developer account (QA-agent token unavailable). Review performed by Claude Opus 5.5 (Anthropic) in Claude Code via qa-panel.

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

[DeusData]

Thank you, Shane! This is a small change with a real payoff: subagents defined with a fixed tool list (Read, Grep, Bash and similar) were being pointed at graph tools they could not call, and one sentence naming codebase-memory-mcp cli <tool> --help fixes that without any agent-type detection. Keeping the hint to SubagentStart only, checking the 2 KB context bound, and pinning both the positive and the negative cases in the existing hook tests made this very easy to review - and it follows nicely on your subagent reminder work from #632.

We pushed two commits to your branch (maintainer edits are on):

1. fix(hooks): state the CLI fallback for subagents as a fact (3a869ee). We keep hook context phrased as plain facts rather than instructions, so the sentence now reads "The same tools are also available from the shell: codebase-memory-mcp cli <tool> --help lists each tool's flags." The command your tests match is unchanged.
2. A signed-off merge of current main (395763c), so CI covers today's tree. Its message names the branch slightly wrong (fix/subagent-cli-hint) - only the message; the merge itself is correct.

The cli suite passes on the merged tree (372 passed, 1 skipped), including your new assertions. We will merge once the required checks are green. Please pull before pushing again.

[DeusData]

Merged as 85a38ed - thank you, Shane! Subagents defined with a fixed tool list now learn from their SubagentStart context that the same graph tools are available through codebase-memory-mcp cli <tool> --help, instead of being pointed at tools they cannot call. Thank you for the focused change and for following up on your subagent reminder work.