Documentation
¶
Overview ¶
Package nudge is the harness-neutral core of the PreToolUse nudge (Phase 6, D-01a): it decides whether a tool call qualifies for the codegraph pointer and holds the pinned pointer text. It knows nothing about any harness's stdin/stdout envelope and imports nothing from this module, so the Codex nudge (CODEX-05) reuses it behind its own adapter.
Index ¶
Constants ¶
const CooldownWindow = 60 * time.Second
CooldownWindow is the minimum gap between two fires for one (session, agent) key: fire on the first matched call, then at most once per window (D-05). It is the one place the window is defined.
const Text = "" /* 170-byte string literal not displayed */
Text is the PreToolUse nudge sentence (D-14): a factual one-liner, not an imperative, naming only the codegraph_explore MCP tool and its `codegraph explore` CLI fallback. Its bytes are pinned — by hand-typed oracles in the adapter tests here, and by the text drift guards 06-02 adds — so any edit is a deliberate, test-visible change.
Variables ¶
This section is empty.
Functions ¶
func DefaultDir ¶
func DefaultDir() string
DefaultDir is the per-user sentinel directory under os.TempDir(), which honours TMPDIR (D-08).
func Qualifies ¶
Qualifies reports whether a call to tool with input should receive the nudge. It is the authoritative layer of a two-layer check and is shared, with the D-15 corpora in testdata/, by the Codex nudge (CODEX-05).
Shell (D-02): the harness pre-filter (Claude's `if` rules such as `Bash(grep *)`) also matches pipe tails like `git log | grep x`, so only the command's first word counts here: after skipping leading NAME=value assignments it must be exactly grep, egrep, fgrep, rg or find. Any parse doubt stays silent — an assignment carrying a quote, backtick, `$` or backslash, an empty command, or one made only of assignments.
Grep and Glob always qualify; Read qualifies unless the path is empty or an obvious non-code file by extension (D-03). Any other tool never does.
func SessionKey ¶
SessionKey builds the cooldown key for one harness session and agent (D-06, D-07): the main thread keys on the literal "main", each subagent on its own id, so a subagent's fresh context gets its own nudge. An empty session id yields ok=false — the nudge never fires unkeyed.
Types ¶
type Gate ¶
Gate decides whether the nudge fires for a key, recording each fire as the mtime of a zero-byte sentinel file in Dir. Now is the injectable clock (D-17); nil means time.Now.
func (Gate) Due ¶
Due reports whether the nudge should fire for key now, and records the fire when it should. It returns true only when the key is outside its cooldown AND the fire was recorded; every failure — an unusable or foreign directory, a symlinked or foreign sentinel, any stat, open or time-setting error — resolves to false, i.e. silence (D-08). Two parallel callers may both see a key as due; D-08 accepts that rare double fire.
Source Files