Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(claude): steer tool selection to cut ask over-asking
Shrish Dwivedibd94cd8d6ce4
diff --git a/package-lock.json b/package-lock.jsonindex 49ae5a35..31a15d84 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,12 +1,12 @@{"name": "@nanonets/graft",- "version": "0.5.0",+ "version": "0.5.1","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@nanonets/graft",- "version": "0.5.0",+ "version": "0.5.1","hasInstallScript": true,"license": "MIT","dependencies": {diff --git a/package.json b/package.jsonindex 93b559aa..dee23492 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "@nanonets/graft",- "version": "0.5.0",+ "version": "0.5.1","description": "Build a repo's context graph as a folder of linked markdown files that live in the repo and stay in sync with the code through git.","keywords": ["ai",diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex ac6a82b0..f08af6c2 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -707,7 +707,7 @@ export function formatAsk(r: AskResult): string {.join("\n"): "";if (r.hits.length === 0) {- return `${head}\n\n${noteBlock || "no matches."}`;+ return `${head}\n\n${noteBlock || "no matches."}${escalationNudge(r)}\n`;}const lines = noteBlock ? [head, "", noteBlock, ""] : [head, ""];if (r.mode === "structural") {@@ -727,7 +727,21 @@ export function formatAsk(r: AskResult): string {});}const body = lines.join("\n").trimEnd();- return body + savingsFooter(r, body) + "\n";+ return body + savingsFooter(r, body) + escalationNudge(r) + "\n";+}++/** When a lexical `ask` returns thin/no results, the productive next move is a+ * different TOOL, not a re-phrased ask — re-asking is the "over-ask" trap that+ * inflates cost. Surface the escalation in the output so the agent switches to+ * grep/skeleton/callers instead. Silent when the result is already rich (>3+ * hits) or in structural mode (a resolved who-calls IS the answer). */+function escalationNudge(r: AskResult): string {+ if ((r.mode !== "lexical" && r.mode !== "empty") || r.hits.length > 3) return "";+ const n = r.hits.length;+ return (+ `\n\n[graft] ${n === 0 ? "no hits" : `only ${n} hit${n === 1 ? "" : "s"}`} — don't re-ask with new wording; switch tool: ` ++ "`graft grep \"<literal>\"` for every occurrence · `graft skeleton <file>` for a file's full API · `graft callers <symbol>` for who-uses."+ );}/** The one-line token-saving estimate `ask` appends in retriever mode, so thediff --git a/src/claude/format.ts b/src/claude/format.tsindex 569e1a08..deb05052 100644--- a/src/claude/format.ts+++ b/src/claude/format.ts@@ -103,7 +103,7 @@ function retrievalBody(hits: AskJson['hits']): string {// tokens are always fresh full-price input, so the pack stays tiny).const header = hits.some((h) => h.code)? '[graft] retrieved context — read these spans, do not re-open the files:'- : '[graft] likely starting points — if relevant, open the pointer or run `graft ask "<task>" --source` for the code:';+ : '[graft] starting points for this task — pull the code inline with `graft ask "<what you need>" --source`, trace impact with `graft callers <symbol>`, or search with `graft grep "<literal>"`:';return `${header}\n${blocks.join('\n')}`;}@@ -163,7 +163,16 @@ export function relevantRetrieval(ask: AskJson, s: SessionState, cap = 3): strin}export function formatOrientation(indexMd: string, budgetBytes = 1500): string {- return `[graft] repo map (graft/INDEX.md):\n${indexMd.slice(0, budgetBytes)}`;+ // Always-on directive (cached, seen turn 0) so the agent reaches for graft's+ // commands without waiting for the discretionary skill to load. Positive only+ // — names the tools, forbids nothing.+ const directive =+ `[graft] This repo is indexed by graft. To find or understand code, reach for graft first — it cites exact file:line and is faster than grep/read:\n` ++ ` • graft ask "<task>" --source — the relevant code, inline (skip the file read)\n` ++ ` • graft callers <sym> · graft impact <sym> — who/what breaks if it changes\n` ++ ` • graft grep "<literal>" — exhaustive search, grouped by enclosing symbol\n` ++ ` • graft skeleton <file> · graft map — a file's API · whole-repo orientation\n`;+ return `${directive}\nrepo map (graft/INDEX.md):\n${indexMd.slice(0, budgetBytes)}`;}export function renderSubagent(agentName: string, session: SessionState | null): string {diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.tsindex b413137e..57d31e92 100644--- a/src/claude/skill-template.ts+++ b/src/claude/skill-template.ts@@ -18,24 +18,29 @@ explaining one part in plain prose and naming the exact files and line-spans itcovers. Reading a node costs a few hundred tokens; reading source to rebuild thesame understanding costs thousands.-**Get context from graft first — two ways, both land here:**+**Choose the graft tool by task shape — pick the one that answers in a single call:**-- Ask: \`graft ask "<your task, in plain words>"\` — returns the relevant nodes,- ranked, with file:line pointers. Add \`--source\` to inline the actual code at- each span, so the result IS the code you need — no separate file read. By- default \`--source\` inlines each hit's crux (the ≤8-line core of the- definition, marked as such); add \`--full\` only when the crux isn't enough.- Ask is cheap (<1s) — re-ask with different phrasings for each sub-question,- and use structural forms too: \`graft ask "who calls <symbol>"\`.-- Skim a file's API without reading it: \`graft skeleton <file>\` — every- definition's signature + span in ~200 tokens, ~10× cheaper than the file.-- Or explore as usual: grep / ls / cat inside \`graft/\`. A grep for any concept,- symbol, or filename hits the node that covers it; \`graft/INDEX.md\` lists them- all.+- **Locate / understand / "how does X work"** → \`graft ask "<task>" --source\` —+ ranked nodes with the code inlined (\`--source\` gives each hit's ≤8-line crux;+ add \`--full\` only if the crux isn't enough). For a genuinely multi-part+ question, ask once per distinct sub-aspect. **But if an ask returns few or+ weak hits, do NOT re-ask with reworded phrasings — switch tool** (below). The+ ask output tells you when to switch.+- **Every occurrence / "all the X" / a symbol or literal everywhere** →+ \`graft grep "<literal>"\` — exhaustive, grouped by enclosing symbol. Ranked+ ask is top-N and WILL miss instances; grep is the tool for "find them all".+- **A file's whole API surface** → \`graft skeleton <file>\` — every signature in+ ~200 tokens. One call beats several asks when you just need "what's in here".+- **Who uses / what breaks if I change X** → \`graft callers <symbol>\` or+ \`graft impact <symbol>\`; what X itself depends on → \`graft callees <symbol>\`.+ Run one of these before editing a symbol.+- **First contact with an unfamiliar repo** → \`graft map\` — token-budgeted+ orientation (dir clusters, hubs, hotspots). Read the hub cards it names rather+ than asking per subsystem.-**First contact with an unfamiliar repo:** run \`graft map\` before exploring —-a token-budgeted orientation (dir clusters, hubs, hotspots) built straight from-the wiring graph, no LLM, no key.+You can also grep / ls / cat inside \`graft/\` directly (the nodes are plain+markdown; \`graft/INDEX.md\` lists them) — but the commands above are faster and+exhaustive where it matters, so reach for them first.**Match the tool to the task shape:**diff --git a/test/claude-format.test.ts b/test/claude-format.test.tsindex 99d662d6..942a1f86 100644--- a/test/claude-format.test.ts+++ b/test/claude-format.test.ts@@ -68,7 +68,7 @@ test('formatRetrieval renders top hits, trims snippet, first pointer only', () ={ kind: 'concept', title: 'PKCE', pointer: 'src/pkce.ts, src/client.ts', snippet: 'Validates the challenge.', score: 1 },] } as any;const txt = strip(formatRetrieval(ask)!);- assert.match(txt, /likely starting points/); // pointers-only header (no inlined code)+ assert.match(txt, /starting points for this task/); // pointers-only header (no inlined code)assert.match(txt, /PKCE — src\/pkce\.ts/);assert.match(txt, /Validates the challenge\./); // snippet trimmed, own lineassert.doesNotMatch(txt, /client\.ts/); // only the first pointer segment@@ -139,7 +139,9 @@ test('formatOrientation labels and truncates to budget', () => {const md = 'X'.repeat(3000);const out = strip(formatOrientation(md, 1500));assert.match(out, /repo map/);- assert.ok(out.length < 1600, 'trimmed to budget + short header');+ assert.match(out, /reach for graft first/, 'always-on usage directive present');+ // index truncated to budget (1500) + the fixed usage directive header (~500).+ assert.ok(out.length < 2200, 'index trimmed to budget; only the fixed directive adds to it');});test('renderSubagent shows agent name and its last query', () => {