@lincoln504/pi-research 1.7.0 → 1.7.1

package/agent-skill/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.7.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.7.1", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/agent-skill/pi-research/references/configuration.md

@@ -27,7 +27,7 @@ over `config.env` for the CLI only. Precedence:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PI_RESEARCH_MODEL` | _(required)_ | The `provider/model-id` all research runs on. |
-| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` | `1` | Default depth (0–3) when `--depth` omitted. `0` is quick (single-pass, no researcher team) and requires `PI_RESEARCH_QUICK_RESEARCH` on the pi extension. |
+| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` | `1` | Default depth (0–3) when `--depth` omitted. `0` is quick (single-pass, no researcher team) and requires `PI_RESEARCH_QUICK_RESEARCH` on the pi extension. The agent-facing `research` tool's depth guidance renders relative to this setting — when quick is the configured default, depth 0 is the ordinary choice and 1+ is the escalation; keeping the default (1) renders byte-identically. |
 | `PI_RESEARCH_QUICK_MAX_QUERIES` | `5` | Max queries per `search` call in quick (depth 0) research (1–10). Applies to the CLI and SDK `--depth 0` runs too. |
 | `PI_RESEARCH_MAX_RESEARCHERS` | `3` | Parallel researchers (1–5). |
 | `PI_RESEARCH_TIMEOUT_MS` | `300000` | Per-researcher timeout (180000–1800000). |

package/dist/prompts/research-depth-guidance.ts

@@ -0,0 +1,159 @@
+/**
+ * Renders the DEPTH PARAMETER guidance for the agent-facing `research` tool,
+ * relative to the user's configured `DEFAULT_RESEARCH_DEPTH`.
+ *
+ * Background (PR #16, discussion point 2): the tool-usage prompt says
+ * "Always specify a depth" and mapped ~95% of queries to `depth: 1`, so a
+ * user-configured default (e.g. quick/0) was effectively never honored for
+ * agent-initiated research — even with quick set as the default the agent
+ * still sent `depth: 1`. This builder renders the guidance relative to the
+ * configured default: when quick is the configured default, depth 0 becomes
+ * the ordinary choice and depth 1+ reads as the escalation. A user who keeps
+ * the default (1) sees byte-identical guidance — quality-first behavior is
+ * unchanged.
+ *
+ * The anchor is the *effective* default — the depth `execute()` actually
+ * resolves an omitted depth to:
+ *
+ *     effectiveDefault = quickEnabled ? defaultDepth : Math.max(1, defaultDepth)
+ *
+ * Depth 0 is only reachable when quick mode is enabled; otherwise a
+ * configured 0 clamps to 1 at runtime, so the guidance must not advertise it.
+ *
+ * This is a pure function of the two session-static snapshots the tool schema
+ * was built from (see quickResearchEnabledAtRegistration /
+ * defaultDepthAtRegistration in index.ts) so the rendered guidance can never
+ * advertise a depth the registered schema rejects.
+ */
+
+/**
+ * The depth `execute()` applies when the agent omits depth — `Math.max(depthMin,
+ * configured)` where `depthMin = quickEnabled ? 0 : 1` (see
+ * research-tool-definition.ts). This is "the ordinary choice" every rendered
+ * surface steers to, and the value the tool schema's `default` annotation must
+ * match.
+ */
+export function resolveEffectiveDefault(quickEnabled: boolean, defaultDepth: number): number {
+  return quickEnabled ? defaultDepth : Math.max(1, defaultDepth);
+}
+
+/**
+ * Build the DEPTH PARAMETER guidance block (everything between the
+ * "Always specify a depth." lead-in and the "How depth works internally:"
+ * section). The returned string has no leading or trailing newlines; the
+ * caller's template supplies the surrounding blank lines.
+ *
+ * @param quickEnabled Whether quick mode (depth 0) is enabled — the same
+ *   session-static snapshot the tool schema was built from.
+ * @param defaultDepth The user-configured `DEFAULT_RESEARCH_DEPTH` (0–3).
+ */
+export function buildResearchDepthGuidance(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+
+  if (!quickEnabled) {
+    return wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+  }
+  return quickDoc(effectiveDefault) + '\n' + wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+}
+
+/**
+ * The "user says a depth word" mapping. Byte-identical for effectiveDefault in
+ * {1,2,3}; only the "quick" line moves — to 0 — when the configured default IS
+ * 0. "normal" stays 1: the words form a shallow→max scale
+ * (quick < normal < deep < ultra = 0 < 1 < 2 < 3), so "normal" is always the
+ * standard orchestrated run.
+ */
+function wordBlock(effectiveDefault: number): string {
+  const quickTarget = effectiveDefault === 0 ? 0 : 1;
+  return [
+    '**User says a depth word (highest priority):**',
+    '- "quick" / "brief" / "simple" → `depth: ' + quickTarget + '`',
+    '- "normal" / "moderate" / "standard" → `depth: 1`',
+    '- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)',
+    '- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`',
+  ].join('\n');
+}
+
+/**
+ * The "user says nothing about depth — judge complexity:" section. Positions
+ * the effective default as the ordinary choice. effectiveDefault === 1
+ * reproduces the prior static text byte-for-byte.
+ */
+function nothingBlock(effectiveDefault: number): string {
+  const header = '**User says nothing about depth — judge complexity:**';
+  const never = '- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research".';
+  switch (effectiveDefault) {
+    case 0:
+      return [
+        header,
+        '- `depth: 0` — the ordinary choice: a single verifiable fact, a URL, a price, a version number, or a yes/no with a source. One search-and-read pass, no researcher team.',
+        '- `depth: 1` — Coordinated, thorough research: simple facts with sources, lookups, overviews, background research. Escalate here when the question needs more than a single verifiable fact.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 0, 1, or 2.',
+      ].join('\n');
+    case 2:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — the ordinary choice (your configured default): complex multi-faceted topics, policy analysis, tech evaluations, academic-style research.',
+        never,
+      ].join('\n');
+    case 3:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        '- `depth: 3` — the ordinary choice (your configured default): comprehensive, multi-round, exhaustive research.',
+      ].join('\n');
+    case 1:
+    default:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 1 or depth 2.',
+      ].join('\n');
+  }
+}
+
+/**
+ * The quick-mode intro, rendered only when quick mode is enabled. The first
+ * paragraph (what depth 0 is) is constant; the second names the ordinary
+ * choice, relative to the effective default.
+ */
+function quickDoc(effectiveDefault: number): string {
+  const first =
+    '**Depth 0 (quick) is available on this host.** Use `depth: 0` for a single verifiable fact, a URL, a price, a version number, or a yes/no with a source — or when the user says "just check", "one-liner", or "don\'t overdo it". It runs one search-and-read pass with no researcher team and answers concisely.';
+  let second: string;
+  switch (effectiveDefault) {
+    case 0:
+      second = '`depth: 0` is the ordinary choice; `depth: 1` is the escalation for coordinated research, `depth: 2` for complex or multi-faceted topics, `depth: 3` only on explicit request.';
+      break;
+    case 2:
+      second = '`depth: 2` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 3` only on explicit request.';
+      break;
+    case 3:
+      second = '`depth: 3` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 2` for complex topics.';
+      break;
+    case 1:
+    default:
+      second = '`depth: 1` remains the normal choice. `depth: 2` is the escalation for complex or multi-faceted questions; `depth: 3` only on explicit request.';
+      break;
+  }
+  return first + '\n\n' + second;
+}
+
+/**
+ * The closing escalation nudge — the tail of the "Do NOT escalate depth just
+ * because a topic is broad" line in the MULTIPLE RESEARCH CALLS section,
+ * rendered relative to the effective default the same way the DEPTH PARAMETER
+ * block is. effectiveDefault === 1 reproduces the prior static text
+ * byte-for-byte, so a user who keeps the default (1) — quick on or off — sees
+ * an unchanged prompt.
+ */
+export function buildEscalationNudge(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+  return effectiveDefault === 1
+    ? 'depth 1 handles most cases well, and the higher depths have their own internal decomposition.'
+    : 'your configured default handles most cases well, and the higher depths have their own internal decomposition.';
+}

package/dist/prompts/research-tool-usage.md

@@ -49,17 +49,7 @@ The `research` tool retrieves from the internet. Do NOT use it when the answer c
 
 **Always specify a depth.** Judge it from the user's language and task complexity.
 
-{{QUICK_MODE_DOC}}
-**User says a depth word (highest priority):**
-- "quick" / "brief" / "simple" → `depth: 1`
-- "normal" / "moderate" / "standard" → `depth: 1`
-- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)
-- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`
-
-**User says nothing about depth — judge complexity:**
-- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.
-- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.
-- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research". If the user does not explicitly request this level, use depth 1 or depth 2.
+{{DEPTH_GUIDANCE}}
 
 **How depth works internally:**
 - `depth: 1-3` — AI-orchestrated: coordinator plans a team, researchers execute, a research lead decides whether to continue deeper and writes the final report. Team size and number of rounds scale with complexity. The coordinator and the lead dynamically determine how many researchers are needed each round — it's not a fixed number.
@@ -92,4 +82,4 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.
 
-**Do NOT escalate depth just because a topic is broad** — depth 1 handles most cases well, and the higher depths have their own internal decomposition.
+**Do NOT escalate depth just because a topic is broad** — {{ESCALATION_NUDGE}}

package/docs/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.1] - 2026-09-27
+
+### Changed
+
+- **The remaining static `depth: 1` references in the agent-facing surface now follow the configured default too.** Two spots still said `1` where the runtime applies the configured default: the tool schema's model-facing `default` annotation on the `depth` parameter (hardcoded `default: 1`, so a user who configured default 2 saw `"default": 1` in the schema while the prompt said depth 2 is the ordinary choice), and the closing "Do NOT escalate depth just because a topic is broad" line ("depth 1 handles most cases well"). Both are now rendered against the same effective default the DEPTH PARAMETER block uses — `Math.max(depthMin, configured)` where `depthMin = quickEnabled ? 0 : 1` — via `resolveEffectiveDefault` / `buildEscalationNudge` in `src/prompts/research-depth-guidance.ts`. A user whose effective default is 1 (the default install, quick on or off) sees byte-identical prompt and schema; the tests pin that.
+- **The agent-facing `research` tool-usage prompt now renders its depth guidance relative to the user's configured `DEFAULT_RESEARCH_DEPTH`.** The DEPTH PARAMETER block was static and always steered to `depth: 1` — the "Always specify a depth" prompt mapped ~95% of queries there — so a user-configured default (e.g. quick/0) was effectively never honored for agent-initiated research: even with quick set as the default the agent still sent `depth: 1` (only `/research` and the CLI honored it). The block is now rendered by `buildResearchDepthGuidance` (new `src/prompts/research-depth-guidance.ts`) against the same session-static snapshots the tool schema is built from, so it can never advertise a depth the registered schema rejects. When quick is the configured default, depth 0 becomes the ordinary choice and depth 1+ reads as the escalation — a real cost lever. A user who keeps the default (1) sees **byte-identical** guidance, for both the quick-on and quick-off renderings (the green-light condition on PR #16); `test/unit/prompts/research-depth-guidance.test.ts` pins that byte-identity and the `effectiveDefault` the guidance anchors on (`quickEnabled ? defaultDepth : max(1, defaultDepth)`, the depth `execute()` applies to an omitted depth).
+
 ## [1.7.0] - 2026-09-22
 
 ### Added

package/docs/CONFIGURATION.md

@@ -73,7 +73,7 @@ Research
 |----------|---------|-------|-------------|
 | `PI_RESEARCH_TIMEOUT_MS` (TUI) | `300000` | 180000–1800000 | Per-researcher timeout (3–30 min). |
 | `PI_RESEARCH_MAX_RESEARCHERS` (TUI) | `3` | 1–5 | Parallel researchers. |
-| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` (TUI) `[project]` | `1` | 0–3 | Depth for `/research` and the CLI when `--depth` is omitted (0=quick single-pass — requires `PI_RESEARCH_QUICK_RESEARCH` —, 1=normal, 2=deep, 3=ultra). |
+| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` (TUI) `[project]` | `1` | 0–3 | Depth for `/research` and the CLI when `--depth` is omitted (0=quick single-pass — requires `PI_RESEARCH_QUICK_RESEARCH` —, 1=normal, 2=deep, 3=ultra). The agent-facing `research` tool-usage prompt renders its depth guidance relative to this setting too: when quick is the configured default, depth 0 is the ordinary choice; a user who keeps the default (1) gets byte-identical guidance. |
 | `PI_RESEARCH_QUICK_RESEARCH` (TUI) `[project]` | `false` | `true` · `false` | Opt-in gate for depth-0 (quick) research. When `false` (default), the agent-facing `research` tool keeps its upstream `minimum: 1` schema — agents can neither see nor send depth 0 — and a `DEFAULT_RESEARCH_DEPTH` of 0 resolves to 1. Toggling applies on the next session. |
 | `PI_RESEARCH_QUICK_MAX_QUERIES` | `5` | 1–10 | Max queries per `search` call in quick (depth 0) research. Applies to every quick run — the pi extension tool, the CLI, and the SDK's `--depth 0` — since they share the same researcher session factory. Deliberately below deep research's 30-query cap; the ceiling of 10 keeps quick mode from ever exceeding the old 5–10 prompt guidance. |
 | `PI_RESEARCH_MAX_SCRAPE_BATCHES` (TUI) | `2` | 0–99 | Scrape batches per researcher (0 = unlimited). When prompt caching is known to be active for the resolved research model (Anthropic API models, or a provider route explicitly configured for Anthropic-style cache control), the effective limit is this value plus one — the cached prompt prefix makes the extra batch cheap. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/src/index.ts

@@ -20,6 +20,7 @@ import { getConfig, validateConfig } from './config.ts';
 import { metrics } from './utils/metrics.ts';
 import { handleResearchConfigCommand } from './research-config.ts';
 import { loadPrompt } from './core/llm/prompts.ts';
+import { buildResearchDepthGuidance, buildEscalationNudge } from './prompts/research-depth-guidance.ts';
 import { clearAllSessionState, addSteeringMessage, getSteeringMessages, normalizeSessionId, getActiveSessionCount, popQueuedMessages, requeuePoppedMessage, getAllTrackedSessions, getPiActiveSessionOrder, getPiActivePanels } from './orchestration/session-state.ts';
 import { initGlobalTuiController, disposeGlobalTuiController } from './tui/tui-controller.ts';
 import { registerCoreServices, initializeCoreServices, disposeCoreServices } from './core/service-initialization.ts';
@@ -332,6 +333,10 @@ export default async function (pi: ExtensionAPI) {
   // live config here would tell the agent depth 0 exists while the tool still
   // rejects it with invalid_parameters until restart.
   const quickResearchEnabledAtRegistration = getConfig(process.cwd(), 'pi').QUICK_RESEARCH === true;
+  // Session-static snapshot of the user's configured DEFAULT_RESEARCH_DEPTH, taken
+  // at the same moment as quickResearchEnabledAtRegistration so the depth guidance
+  // (rendered relative to it) agrees with the schema the session was built with.
+  const defaultDepthAtRegistration = getConfig(process.cwd(), 'pi').DEFAULT_RESEARCH_DEPTH;
 
   // Create and register the health check tool
   const healthTool: ToolDefinition = createHealthTool();
@@ -612,17 +617,16 @@ export default async function (pi: ExtensionAPI) {
       (!event.systemPromptOptions || event.systemPromptOptions.selectedTools?.includes(researchKnowledgeSearchTool.name));
 
     if (isResearchToolAvailable || isKnowledgeSearchAvailable) {
-      // Quick-mode (depth 0) prompt documentation is gated on the SAME session-
-      // static snapshot the tool schema was built from (see
-      // quickResearchEnabledAtRegistration) — not live config — so the prompt can
-      // never advertise a depth the registered schema rejects. A mid-session
-      // QUICK_RESEARCH toggle therefore fully applies on the next session, both
-      // schema and prompt together.
-      const quickModeDoc = quickResearchEnabledAtRegistration
-        ? '**Depth 0 (quick) is available on this host.** Use `depth: 0` for a single verifiable fact, a URL, a price, a version number, or a yes/no with a source — or when the user says "just check", "one-liner", or "don\'t overdo it". It runs one search-and-read pass with no researcher team and answers concisely.\n\n`depth: 1` remains the normal choice. `depth: 2` is the escalation for complex or multi-faceted questions; `depth: 3` only on explicit request.\n'
-        : '';
+      // The DEPTH PARAMETER guidance is rendered relative to the user's configured
+      // DEFAULT_RESEARCH_DEPTH (buildResearchDepthGuidance), gated on the SAME
+      // session-static snapshots the tool schema was built from (see
+      // quickResearchEnabledAtRegistration / defaultDepthAtRegistration) — not live
+      // config — so the prompt can never advertise a depth the registered schema
+      // rejects. A mid-session config toggle therefore fully applies on the next
+      // session, both schema and prompt together.
       let researchPrompt = loadPrompt('research-tool-usage')
-        .replace(/\n?\{\{QUICK_MODE_DOC\}\}\n?/, '\n' + quickModeDoc)
+        .replace('{{DEPTH_GUIDANCE}}', buildResearchDepthGuidance(quickResearchEnabledAtRegistration, defaultDepthAtRegistration))
+        .replace('{{ESCALATION_NUDGE}}', buildEscalationNudge(quickResearchEnabledAtRegistration, defaultDepthAtRegistration))
         .replace('{{max_team_size_l1}}', MAX_TEAM_SIZE_LEVEL_1.toString())
         .replace('{{max_team_size_l2}}', MAX_TEAM_SIZE_LEVEL_2.toString())
         .replace('{{max_team_size_l3}}', MAX_TEAM_SIZE_LEVEL_3.toString());

package/src/prompts/research-depth-guidance.ts

@@ -0,0 +1,159 @@
+/**
+ * Renders the DEPTH PARAMETER guidance for the agent-facing `research` tool,
+ * relative to the user's configured `DEFAULT_RESEARCH_DEPTH`.
+ *
+ * Background (PR #16, discussion point 2): the tool-usage prompt says
+ * "Always specify a depth" and mapped ~95% of queries to `depth: 1`, so a
+ * user-configured default (e.g. quick/0) was effectively never honored for
+ * agent-initiated research — even with quick set as the default the agent
+ * still sent `depth: 1`. This builder renders the guidance relative to the
+ * configured default: when quick is the configured default, depth 0 becomes
+ * the ordinary choice and depth 1+ reads as the escalation. A user who keeps
+ * the default (1) sees byte-identical guidance — quality-first behavior is
+ * unchanged.
+ *
+ * The anchor is the *effective* default — the depth `execute()` actually
+ * resolves an omitted depth to:
+ *
+ *     effectiveDefault = quickEnabled ? defaultDepth : Math.max(1, defaultDepth)
+ *
+ * Depth 0 is only reachable when quick mode is enabled; otherwise a
+ * configured 0 clamps to 1 at runtime, so the guidance must not advertise it.
+ *
+ * This is a pure function of the two session-static snapshots the tool schema
+ * was built from (see quickResearchEnabledAtRegistration /
+ * defaultDepthAtRegistration in index.ts) so the rendered guidance can never
+ * advertise a depth the registered schema rejects.
+ */
+
+/**
+ * The depth `execute()` applies when the agent omits depth — `Math.max(depthMin,
+ * configured)` where `depthMin = quickEnabled ? 0 : 1` (see
+ * research-tool-definition.ts). This is "the ordinary choice" every rendered
+ * surface steers to, and the value the tool schema's `default` annotation must
+ * match.
+ */
+export function resolveEffectiveDefault(quickEnabled: boolean, defaultDepth: number): number {
+  return quickEnabled ? defaultDepth : Math.max(1, defaultDepth);
+}
+
+/**
+ * Build the DEPTH PARAMETER guidance block (everything between the
+ * "Always specify a depth." lead-in and the "How depth works internally:"
+ * section). The returned string has no leading or trailing newlines; the
+ * caller's template supplies the surrounding blank lines.
+ *
+ * @param quickEnabled Whether quick mode (depth 0) is enabled — the same
+ *   session-static snapshot the tool schema was built from.
+ * @param defaultDepth The user-configured `DEFAULT_RESEARCH_DEPTH` (0–3).
+ */
+export function buildResearchDepthGuidance(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+
+  if (!quickEnabled) {
+    return wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+  }
+  return quickDoc(effectiveDefault) + '\n' + wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+}
+
+/**
+ * The "user says a depth word" mapping. Byte-identical for effectiveDefault in
+ * {1,2,3}; only the "quick" line moves — to 0 — when the configured default IS
+ * 0. "normal" stays 1: the words form a shallow→max scale
+ * (quick < normal < deep < ultra = 0 < 1 < 2 < 3), so "normal" is always the
+ * standard orchestrated run.
+ */
+function wordBlock(effectiveDefault: number): string {
+  const quickTarget = effectiveDefault === 0 ? 0 : 1;
+  return [
+    '**User says a depth word (highest priority):**',
+    '- "quick" / "brief" / "simple" → `depth: ' + quickTarget + '`',
+    '- "normal" / "moderate" / "standard" → `depth: 1`',
+    '- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)',
+    '- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`',
+  ].join('\n');
+}
+
+/**
+ * The "user says nothing about depth — judge complexity:" section. Positions
+ * the effective default as the ordinary choice. effectiveDefault === 1
+ * reproduces the prior static text byte-for-byte.
+ */
+function nothingBlock(effectiveDefault: number): string {
+  const header = '**User says nothing about depth — judge complexity:**';
+  const never = '- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research".';
+  switch (effectiveDefault) {
+    case 0:
+      return [
+        header,
+        '- `depth: 0` — the ordinary choice: a single verifiable fact, a URL, a price, a version number, or a yes/no with a source. One search-and-read pass, no researcher team.',
+        '- `depth: 1` — Coordinated, thorough research: simple facts with sources, lookups, overviews, background research. Escalate here when the question needs more than a single verifiable fact.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 0, 1, or 2.',
+      ].join('\n');
+    case 2:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — the ordinary choice (your configured default): complex multi-faceted topics, policy analysis, tech evaluations, academic-style research.',
+        never,
+      ].join('\n');
+    case 3:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        '- `depth: 3` — the ordinary choice (your configured default): comprehensive, multi-round, exhaustive research.',
+      ].join('\n');
+    case 1:
+    default:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 1 or depth 2.',
+      ].join('\n');
+  }
+}
+
+/**
+ * The quick-mode intro, rendered only when quick mode is enabled. The first
+ * paragraph (what depth 0 is) is constant; the second names the ordinary
+ * choice, relative to the effective default.
+ */
+function quickDoc(effectiveDefault: number): string {
+  const first =
+    '**Depth 0 (quick) is available on this host.** Use `depth: 0` for a single verifiable fact, a URL, a price, a version number, or a yes/no with a source — or when the user says "just check", "one-liner", or "don\'t overdo it". It runs one search-and-read pass with no researcher team and answers concisely.';
+  let second: string;
+  switch (effectiveDefault) {
+    case 0:
+      second = '`depth: 0` is the ordinary choice; `depth: 1` is the escalation for coordinated research, `depth: 2` for complex or multi-faceted topics, `depth: 3` only on explicit request.';
+      break;
+    case 2:
+      second = '`depth: 2` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 3` only on explicit request.';
+      break;
+    case 3:
+      second = '`depth: 3` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 2` for complex topics.';
+      break;
+    case 1:
+    default:
+      second = '`depth: 1` remains the normal choice. `depth: 2` is the escalation for complex or multi-faceted questions; `depth: 3` only on explicit request.';
+      break;
+  }
+  return first + '\n\n' + second;
+}
+
+/**
+ * The closing escalation nudge — the tail of the "Do NOT escalate depth just
+ * because a topic is broad" line in the MULTIPLE RESEARCH CALLS section,
+ * rendered relative to the effective default the same way the DEPTH PARAMETER
+ * block is. effectiveDefault === 1 reproduces the prior static text
+ * byte-for-byte, so a user who keeps the default (1) — quick on or off — sees
+ * an unchanged prompt.
+ */
+export function buildEscalationNudge(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+  return effectiveDefault === 1
+    ? 'depth 1 handles most cases well, and the higher depths have their own internal decomposition.'
+    : 'your configured default handles most cases well, and the higher depths have their own internal decomposition.';
+}

package/src/prompts/research-tool-usage.md

@@ -49,17 +49,7 @@ The `research` tool retrieves from the internet. Do NOT use it when the answer c
 
 **Always specify a depth.** Judge it from the user's language and task complexity.
 
-{{QUICK_MODE_DOC}}
-**User says a depth word (highest priority):**
-- "quick" / "brief" / "simple" → `depth: 1`
-- "normal" / "moderate" / "standard" → `depth: 1`
-- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)
-- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`
-
-**User says nothing about depth — judge complexity:**
-- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.
-- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.
-- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research". If the user does not explicitly request this level, use depth 1 or depth 2.
+{{DEPTH_GUIDANCE}}
 
 **How depth works internally:**
 - `depth: 1-3` — AI-orchestrated: coordinator plans a team, researchers execute, a research lead decides whether to continue deeper and writes the final report. Team size and number of rounds scale with complexity. The coordinator and the lead dynamically determine how many researchers are needed each round — it's not a fixed number.
@@ -92,4 +82,4 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.
 
-**Do NOT escalate depth just because a topic is broad** — depth 1 handles most cases well, and the higher depths have their own internal decomposition.
+**Do NOT escalate depth just because a topic is broad** — {{ESCALATION_NUDGE}}

package/src/tools/research-tool-definition.ts

@@ -93,8 +93,16 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
   // a mid-session QUICK_RESEARCH toggle takes effect on the next session. When
   // disabled (the default) the schema is byte-identical to the upstream
   // minimum: 1 surface — agents can neither see nor send depth 0.
-  const quickEnabled = getConfig(undefined, iface).QUICK_RESEARCH === true;
+  const toolConfig = getConfig(undefined, iface);
+  const quickEnabled = toolConfig.QUICK_RESEARCH === true;
   const depthMin = quickEnabled ? 0 : 1;
+  // The depth execute() applies to an omitted depth: Math.max(depthMin,
+  // configured DEFAULT_RESEARCH_DEPTH) — the same value the agent-facing DEPTH
+  // guidance renders relative to (buildResearchDepthGuidance). The annotation
+  // must match it, or a user who configured e.g. default 2 sees `default: 1`
+  // in the model-facing schema while the prompt says "depth 2 is the ordinary
+  // choice (your configured default)".
+  const effectiveDefault = Math.max(depthMin, toolConfig.DEFAULT_RESEARCH_DEPTH);
 
   const parameters = Type.Object({
     query: Type.String({
@@ -110,7 +118,7 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
         '2: Deep (multi-round, exhaustive).',
         '3: Ultra (maximum depth, extreme rigor).',
       ].join('\n'),
-      default: 1,
+      default: effectiveDefault,
     })),
     model: Type.Optional(Type.String({
       description: 'Optional model ID override for coordination.',