Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(claude): steer tool selection to cut ask over-asking

Shrish Dwivedibd94cd8d6ce4
diff --git a/package-lock.json b/package-lock.json
index 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.json
index 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.ts
index 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 the
diff --git a/src/claude/format.ts b/src/claude/format.ts
index 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.ts
index 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 it
covers. Reading a node costs a few hundred tokens; reading source to rebuild the
same 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.ts
index 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 line
assert.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', () => {