Documentation
¶
Overview ¶
Package mcpmeta hints.go — calibrated next-call hint helpers.
Calibration philosophy (CLAUDE.md mcpmeta rule):
"Hint populated only when a clear next-call is cheap and obvious. A noisy hint trains the calling agent to ignore the field."
All helpers default to "" (silent) and only fire on tight conditions.
Package mcpmeta provides a small response-envelope helper used by MCP tools to carry timing, optional next-call hints, and optional staleness warnings without forcing every tool to repeat boilerplate.
The envelope is intentionally minimal: a tool may emit zero or more fields. Empty fields are omitted from the JSON payload so the caller sees only what is signal.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractSymbolFromHit ¶
ExtractSymbolFromHit returns the identifier from a declaration-style match line like "foo.go:42:func Bar(...)". Returns "" for non-declaration lines (call sites, string literals, comments, control flow) so HintAfterCodeSearch stays silent rather than suggesting a bogus understand(symbol=...) call.
func HintAfterCodeSearch ¶
HintAfterCodeSearch returns a calibrated chaining hint for a code_search response, or "" when no hint is warranted.
Rules:
- explain-class query → silent (caller wants prose, not chaining)
- exactly 1 hit → suggest understand(symbol=...) on that symbol
- 0 or >1 hits → silent (too many to pin one symbol)
func HintAfterDeadCode ¶
HintAfterDeadCode returns a hint to call get_file_health when the worst offender file has more dead symbols than the hotspot threshold, or "" otherwise.
func LiveHead ¶
LiveHead returns the on-disk HEAD SHA for a git repo without spawning git.
It handles both primary checkouts (where .git is a directory) and linked worktrees created by "git worktree add" (where .git is a file containing a "gitdir: <path>" pointer). The algorithm:
- Resolve the real gitdir via gitDir (file or directory).
- Read <gitdir>/HEAD — if detached, return the SHA directly.
- If symbolic ("ref: refs/…"), look up the loose ref file under gitdir.
- Fall back to packed-refs from commonDir(gitdir), since worktrees share the main repo's packed refs via the commondir pointer.
Returns "" + error if none of the above resolves.
Types ¶
type Envelope ¶
type Envelope struct {
DurationMS int64 `json:"duration_ms"`
Hint string `json:"hint,omitempty"`
StaleWarning string `json:"stale_warning,omitempty"`
IndexedSHA string `json:"indexed_sha,omitempty"`
LiveSHA string `json:"live_sha,omitempty"`
}
Envelope is the meta block attached to a tool response.
Convention:
- DurationMS is always populated.
- Hint is populated only when a clear next-call is cheap and obvious. A noisy hint trains the calling agent to ignore the field.
- StaleWarning is populated only when the indexed commit no longer matches the on-disk HEAD. Silence is the calibrated signal.
func WithFreshness ¶
WithFreshness annotates an envelope with staleness fields when the caller-supplied indexedSHA does not match the on-disk HEAD.
Silent on match: silence is the calibrated signal.
func Wrap ¶
Wrap builds an Envelope from a measured tool duration and an optional hint. Pass hint == "" when no next-call is obvious. Sub-millisecond durations are clamped to 1 so the envelope's "always populated" contract holds.
func (Envelope) MarshalJSON ¶
MarshalJSON omits empty optional fields so callers see only signal.
Source Files