lsd-pi 1.1.10 → 1.2.1

package/packages/pi-coding-agent/dist/tests/path-display.test.js

@@ -41,6 +41,19 @@ test("buildSystemPrompt: Unix paths pass through unchanged", () => {
     });
     assert.ok(prompt.includes("/home/user/project"));
 });
+test("buildSystemPrompt: encourages scout-first reconnaissance when subagent is available", () => {
+    const prompt = buildSystemPrompt({
+        cwd: "/home/user/project",
+        selectedTools: ["read", "lsp", "subagent", "edit", "write"],
+    });
+    assert.match(prompt, /delegate reconnaissance to the scout subagent/i);
+    assert.match(prompt, /0 scouts for narrow known-file work, 1 scout for one broad unfamiliar subsystem/i);
+    assert.match(prompt, /For one scout use \{ agent, task \}/i);
+    assert.match(prompt, /Scout is for mapping and reconnaissance only/i);
+    assert.match(prompt, /multiple scout subagents in parallel/i);
+    assert.match(prompt, /broad review or audit requests, use scout only as a prep step/i);
+    assert.match(prompt, /Skip scout only when the task is clearly narrow/i);
+});
 // ─── Regression: no backslash paths in LLM-visible text ────────────────────
 /**
  * Pattern that matches Windows-style absolute paths with backslashes.

package/packages/pi-coding-agent/dist/tests/path-display.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-display.test.js","sourceRoot":"","sources":["../../src/tests/path-display.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,+EAA+E;AAE/E,IAAI,CAAC,kEAAkE,EAAE,GAAG,EAAE;IAC7E,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,0BAA0B,CAAC,EAAE,uBAAuB,CAAC,CAAC;AAChF,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,uCAAuC,EAAE,GAAG,EAAE;IAClD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,6BAA6B,CAAC,EAAE,2BAA2B,CAAC,CAAC;AACvF,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mCAAmC,EAAE,GAAG,EAAE;IAC9C,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC,CAAC;AACvE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mCAAmC,EAAE,GAAG,EAAE;IAC9C,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,wCAAwC,EAAE,GAAG,EAAE;IACnD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,wBAAwB,CAAC,EAAE,oBAAoB,CAAC,CAAC;AAC3E,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;IAChE,MAAM,CAAC,KAAK,CACX,WAAW,CAAC,iDAAiD,CAAC,EAC9D,2CAA2C,CAC3C,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,+EAA+E;AAE/E,IAAI,CAAC,qEAAqE,EAAE,GAAG,EAAE;IAChF,MAAM,MAAM,GAAG,iBAAiB,CAAC;QAChC,GAAG,EAAE,wCAAwC;KAC7C,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,CACR,MAAM,CAAC,QAAQ,CAAC,oCAAoC,CAAC,EACrD,iDAAiD,CACjD,CAAC;IACF,MAAM,CAAC,EAAE,CACR,CAAC,MAAM,CAAC,QAAQ,CAAC,wCAAwC,CAAC,EAC1D,+CAA+C,CAC/C,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,sDAAsD,EAAE,GAAG,EAAE;IACjE,MAAM,MAAM,GAAG,iBAAiB,CAAC;QAChC,GAAG,EAAE,oBAAoB;KACzB,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;AAClD,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAE/C,IAAI,CAAC,yEAAyE,EAAE,GAAG,EAAE;IACpF,8BAA8B;IAC9B,MAAM,MAAM,GAAG,iBAAiB,CAAC;QAChC,GAAG,EAAE,6CAA6C;KAClD,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,MAAM,CAAC,KAAK,CACX,UAAU,CAAC,MAAM,EAAE,CAAC,EACpB,oDAAoD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3E,CAAC;AACH,CAAC,CAAC,CAAC","sourcesContent":["/**\n * Cross-platform path display tests.\n *\n * Verifies that toPosixPath correctly normalizes Windows paths and that\n * the system prompt builder produces forward-slash paths for LLM consumption.\n */\n\nimport test from \"node:test\";\nimport assert from \"node:assert/strict\";\nimport { toPosixPath } from \"../utils/path-display.js\";\nimport { buildSystemPrompt } from \"../core/system-prompt.js\";\n\n// ─── toPosixPath ────────────────────────────────────────────────────────────\n\ntest(\"toPosixPath: converts Windows backslash paths to forward slashes\", () => {\n\tassert.equal(toPosixPath(\"C:\\\\Users\\\\name\\\\project\"), \"C:/Users/name/project\");\n});\n\ntest(\"toPosixPath: handles mixed separators\", () => {\n\tassert.equal(toPosixPath(\"C:\\\\Users/name\\\\project/src\"), \"C:/Users/name/project/src\");\n});\n\ntest(\"toPosixPath: no-op for Unix paths\", () => {\n\tassert.equal(toPosixPath(\"/home/user/project\"), \"/home/user/project\");\n});\n\ntest(\"toPosixPath: handles empty string\", () => {\n\tassert.equal(toPosixPath(\"\"), \"\");\n});\n\ntest(\"toPosixPath: handles Windows UNC paths\", () => {\n\tassert.equal(toPosixPath(\"\\\\\\\\server\\\\share\\\\dir\"), \"//server/share/dir\");\n});\n\ntest(\"toPosixPath: handles .gsd/worktrees path on Windows\", () => {\n\tassert.equal(\n\t\ttoPosixPath(\"C:\\\\Users\\\\name\\\\project\\\\.gsd\\\\worktrees\\\\M001\"),\n\t\t\"C:/Users/name/project/.gsd/worktrees/M001\",\n\t);\n});\n\n// ─── System prompt path normalization ───────────────────────────────────────\n\ntest(\"buildSystemPrompt: cwd uses forward slashes even with Windows input\", () => {\n\tconst prompt = buildSystemPrompt({\n\t\tcwd: \"C:\\\\Users\\\\name\\\\development\\\\app-name\",\n\t});\n\tassert.ok(\n\t\tprompt.includes(\"C:/Users/name/development/app-name\"),\n\t\t\"System prompt should contain forward-slash path\",\n\t);\n\tassert.ok(\n\t\t!prompt.includes(\"C:\\\\Users\\\\name\\\\development\\\\app-name\"),\n\t\t\"System prompt must NOT contain backslash path\",\n\t);\n});\n\ntest(\"buildSystemPrompt: Unix paths pass through unchanged\", () => {\n\tconst prompt = buildSystemPrompt({\n\t\tcwd: \"/home/user/project\",\n\t});\n\tassert.ok(prompt.includes(\"/home/user/project\"));\n});\n\n// ─── Regression: no backslash paths in LLM-visible text ────────────────────\n\n/**\n * Pattern that matches Windows-style absolute paths with backslashes.\n * Catches: C:\\Users\\..., D:\\Projects\\..., \\\\server\\share\\...\n * Does not match: escaped chars in regex, JSON strings, etc.\n */\nconst WINDOWS_ABS_PATH_RE = /[A-Z]:\\\\[A-Za-z]/;\n\ntest(\"buildSystemPrompt: no Windows absolute paths with backslashes in output\", () => {\n\t// Simulate a Windows-like cwd\n\tconst prompt = buildSystemPrompt({\n\t\tcwd: \"D:\\\\Projects\\\\my-app\\\\.gsd\\\\worktrees\\\\M002\",\n\t});\n\tconst lines = prompt.split(\"\\n\");\n\tconst violations = lines.filter(line => WINDOWS_ABS_PATH_RE.test(line));\n\tassert.equal(\n\t\tviolations.length, 0,\n\t\t`System prompt contains Windows backslash paths:\\n${violations.join(\"\\n\")}`,\n\t);\n});\n"]}
+{"version":3,"file":"path-display.test.js","sourceRoot":"","sources":["../../src/tests/path-display.test.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cross-platform path display tests.\n *\n * Verifies that toPosixPath correctly normalizes Windows paths and that\n * the system prompt builder produces forward-slash paths for LLM consumption.\n */\n\nimport test from \"node:test\";\nimport assert from \"node:assert/strict\";\nimport { toPosixPath } from \"../utils/path-display.js\";\nimport { buildSystemPrompt } from \"../core/system-prompt.js\";\n\n// ─── toPosixPath ────────────────────────────────────────────────────────────\n\ntest(\"toPosixPath: converts Windows backslash paths to forward slashes\", () => {\n\tassert.equal(toPosixPath(\"C:\\\\Users\\\\name\\\\project\"), \"C:/Users/name/project\");\n});\n\ntest(\"toPosixPath: handles mixed separators\", () => {\n\tassert.equal(toPosixPath(\"C:\\\\Users/name\\\\project/src\"), \"C:/Users/name/project/src\");\n});\n\ntest(\"toPosixPath: no-op for Unix paths\", () => {\n\tassert.equal(toPosixPath(\"/home/user/project\"), \"/home/user/project\");\n});\n\ntest(\"toPosixPath: handles empty string\", () => {\n\tassert.equal(toPosixPath(\"\"), \"\");\n});\n\ntest(\"toPosixPath: handles Windows UNC paths\", () => {\n\tassert.equal(toPosixPath(\"\\\\\\\\server\\\\share\\\\dir\"), \"//server/share/dir\");\n});\n\ntest(\"toPosixPath: handles .gsd/worktrees path on Windows\", () => {\n\tassert.equal(\n\t\ttoPosixPath(\"C:\\\\Users\\\\name\\\\project\\\\.gsd\\\\worktrees\\\\M001\"),\n\t\t\"C:/Users/name/project/.gsd/worktrees/M001\",\n\t);\n});\n\n// ─── System prompt path normalization ───────────────────────────────────────\n\ntest(\"buildSystemPrompt: cwd uses forward slashes even with Windows input\", () => {\n\tconst prompt = buildSystemPrompt({\n\t\tcwd: \"C:\\\\Users\\\\name\\\\development\\\\app-name\",\n\t});\n\tassert.ok(\n\t\tprompt.includes(\"C:/Users/name/development/app-name\"),\n\t\t\"System prompt should contain forward-slash path\",\n\t);\n\tassert.ok(\n\t\t!prompt.includes(\"C:\\\\Users\\\\name\\\\development\\\\app-name\"),\n\t\t\"System prompt must NOT contain backslash path\",\n\t);\n});\n\ntest(\"buildSystemPrompt: Unix paths pass through unchanged\", () => {\n\tconst prompt = buildSystemPrompt({\n\t\tcwd: \"/home/user/project\",\n\t});\n\tassert.ok(prompt.includes(\"/home/user/project\"));\n});\n\ntest(\"buildSystemPrompt: encourages scout-first reconnaissance when subagent is available\", () => {\n\tconst prompt = buildSystemPrompt({\n\t\tcwd: \"/home/user/project\",\n\t\tselectedTools: [\"read\", \"lsp\", \"subagent\", \"edit\", \"write\"],\n\t});\n\tassert.match(prompt, /delegate reconnaissance to the scout subagent/i);\n\tassert.match(prompt, /0 scouts for narrow known-file work, 1 scout for one broad unfamiliar subsystem/i);\n\tassert.match(prompt, /For one scout use \\{ agent, task \\}/i);\n\tassert.match(prompt, /Scout is for mapping and reconnaissance only/i);\n\tassert.match(prompt, /multiple scout subagents in parallel/i);\n\tassert.match(prompt, /broad review or audit requests, use scout only as a prep step/i);\n\tassert.match(prompt, /Skip scout only when the task is clearly narrow/i);\n});\n\n// ─── Regression: no backslash paths in LLM-visible text ────────────────────\n\n/**\n * Pattern that matches Windows-style absolute paths with backslashes.\n * Catches: C:\\Users\\..., D:\\Projects\\..., \\\\server\\share\\...\n * Does not match: escaped chars in regex, JSON strings, etc.\n */\nconst WINDOWS_ABS_PATH_RE = /[A-Z]:\\\\[A-Za-z]/;\n\ntest(\"buildSystemPrompt: no Windows absolute paths with backslashes in output\", () => {\n\t// Simulate a Windows-like cwd\n\tconst prompt = buildSystemPrompt({\n\t\tcwd: \"D:\\\\Projects\\\\my-app\\\\.gsd\\\\worktrees\\\\M002\",\n\t});\n\tconst lines = prompt.split(\"\\n\");\n\tconst violations = lines.filter(line => WINDOWS_ABS_PATH_RE.test(line));\n\tassert.equal(\n\t\tviolations.length, 0,\n\t\t`System prompt contains Windows backslash paths:\\n${violations.join(\"\\n\")}`,\n\t);\n});\n"]}

package/packages/pi-coding-agent/dist/tests/settings-manager-scout-policy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=settings-manager-scout-policy.test.d.ts.map

package/packages/pi-coding-agent/dist/tests/settings-manager-scout-policy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-manager-scout-policy.test.d.ts","sourceRoot":"","sources":["../../src/tests/settings-manager-scout-policy.test.ts"],"names":[],"mappings":""}

package/packages/pi-coding-agent/dist/tests/settings-manager-scout-policy.test.js

@@ -0,0 +1,15 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SettingsManager } from "../core/settings-manager.js";
+test("SettingsManager defaults scoutUsagePolicy to recommend", () => {
+    const settings = SettingsManager.inMemory();
+    assert.equal(settings.getScoutUsagePolicy(), "recommend");
+});
+test("SettingsManager persists scoutUsagePolicy values", () => {
+    const settings = SettingsManager.inMemory();
+    settings.setScoutUsagePolicy("aggressive");
+    assert.equal(settings.getScoutUsagePolicy(), "aggressive");
+    settings.setScoutUsagePolicy("off");
+    assert.equal(settings.getScoutUsagePolicy(), "off");
+});
+//# sourceMappingURL=settings-manager-scout-policy.test.js.map

package/packages/pi-coding-agent/dist/tests/settings-manager-scout-policy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-manager-scout-policy.test.js","sourceRoot":"","sources":["../../src/tests/settings-manager-scout-policy.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,IAAI,CAAC,wDAAwD,EAAE,GAAG,EAAE;IACnE,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;IAC5C,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,mBAAmB,EAAE,EAAE,WAAW,CAAC,CAAC;AAC3D,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;IAC7D,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;IAE5C,QAAQ,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,mBAAmB,EAAE,EAAE,YAAY,CAAC,CAAC;IAE3D,QAAQ,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,mBAAmB,EAAE,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC","sourcesContent":["import test from \"node:test\";\nimport assert from \"node:assert/strict\";\n\nimport { SettingsManager } from \"../core/settings-manager.js\";\n\ntest(\"SettingsManager defaults scoutUsagePolicy to recommend\", () => {\n\tconst settings = SettingsManager.inMemory();\n\tassert.equal(settings.getScoutUsagePolicy(), \"recommend\");\n});\n\ntest(\"SettingsManager persists scoutUsagePolicy values\", () => {\n\tconst settings = SettingsManager.inMemory();\n\n\tsettings.setScoutUsagePolicy(\"aggressive\");\n\tassert.equal(settings.getScoutUsagePolicy(), \"aggressive\");\n\n\tsettings.setScoutUsagePolicy(\"off\");\n\tassert.equal(settings.getScoutUsagePolicy(), \"off\");\n});\n"]}

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "Coding agent CLI (vendored from pi-mono)",
   "type": "module",
   "piConfig": {

package/packages/pi-coding-agent/src/core/agent-session.ts

@@ -1039,10 +1039,45 @@ export class AgentSession {
 		return this._expandSkillByName(skillName, args);
 	}
 
+	private _isPremiumReconModel(): boolean {
+		const model = this.model;
+		if (!model) return false;
+		const provider = model.provider.toLowerCase();
+		const id = model.id.toLowerCase();
+		return (
+			(provider === "anthropic" && (id.includes("opus") || id.includes("sonnet"))) ||
+			(provider === "openai" && /^gpt-5(\.|-|$)/.test(id)) ||
+			(provider === "google" && id.includes("gemini-2.5-pro"))
+		);
+	}
+
+	private _buildScoutPolicyGuidelines(toolNames: string[]): string[] {
+		if (!toolNames.includes("subagent")) return [];
+
+		const guidelines = [
+			"Recon planning policy: use 0 scouts for narrow known-file work, 1 scout for one broad unfamiliar subsystem, and 2-4 parallel scouts only when the work spans multiple loosely-coupled subsystems.",
+			"Scout-first reconnaissance policy: when you need architecture context across multiple files or folders, do not map the subsystem by reading file-after-file yourself. Launch the scout subagent first, then continue with lsp and targeted reads.",
+			"If your next step would be broad exploration rather than a targeted lookup, prefer scout before doing more read/find/grep sweeps yourself.",
+			"When you choose scout, call subagent directly with valid parameters: { agent, task } for one scout, or { tasks: [{ agent, task }, ...] } for parallel scouts.",
+			"Scout is reconnaissance-only. Do not use it as the reviewer, auditor, or final issue-ranker; use it to map files, ownership, and likely hotspots for later evaluation.",
+			"If the work spans multiple loosely-coupled subsystems, prefer parallel scout subagents so each scout maps one area and the parent model reads the summaries instead of the raw files.",
+			"For broad review or audit requests, use scout only as a prep step to map architecture and hotspots; the parent model or a reviewer should make the final judgments.",
+		];
+
+		if (this._isPremiumReconModel()) {
+			guidelines.push(
+				"You are on a premium model. Spend tokens on synthesis, planning, and edits — not broad reconnaissance. Delegate exploratory reading to scout whenever the scope is not already narrow.",
+			);
+		}
+
+		return guidelines;
+	}
+
 	private _rebuildSystemPrompt(toolNames: string[]): string {
 		const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
 		const toolSnippets: Record<string, string> = {};
 		const promptGuidelines: string[] = [];
+		promptGuidelines.push(...this._buildScoutPolicyGuidelines(validToolNames));
 		for (const name of validToolNames) {
 			const snippet = this._toolPromptSnippets.get(name);
 			if (snippet) {
@@ -1804,7 +1839,7 @@ export class AgentSession {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
 		}
 
-		const thinkingLevel = this._getThinkingLevelForModelSwitch();
+		const thinkingLevel = this._getThinkingLevelForModelSwitch(model);
 		await this._applyModelChange(model, thinkingLevel, "set", options);
 	}
 
@@ -1841,7 +1876,7 @@ export class AgentSession {
 
 		// Explicit scoped model thinking level overrides current session level;
 		// undefined scoped model thinking level inherits the current session preference.
-		const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);
+		const thinkingLevel = this._getThinkingLevelForModelSwitch(next.model, next.thinkingLevel);
 		await this._applyModelChange(next.model, thinkingLevel, "cycle", options);
 
 		return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
@@ -1859,7 +1894,7 @@ export class AgentSession {
 		const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
 		const nextModel = availableModels[nextIndex];
 
-		const thinkingLevel = this._getThinkingLevelForModelSwitch();
+		const thinkingLevel = this._getThinkingLevelForModelSwitch(nextModel);
 		await this._applyModelChange(nextModel, thinkingLevel, "cycle", options);
 
 		return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
@@ -1942,11 +1977,19 @@ export class AgentSession {
 		return !!this.model?.reasoning;
 	}
 
-	private _getThinkingLevelForModelSwitch(explicitLevel?: ThinkingLevel): ThinkingLevel {
+	private _getThinkingLevelForModelSwitch(targetModel: Model<any>, explicitLevel?: ThinkingLevel): ThinkingLevel {
 		if (explicitLevel !== undefined) {
 			return explicitLevel;
 		}
-		if (!this.supportsThinking()) {
+		if (
+			targetModel.provider === "anthropic" &&
+			targetModel.reasoning === true &&
+			this.settingsManager.getAnthropicAdaptiveByDefault() &&
+			supportsAdaptiveThinking(targetModel.id)
+		) {
+			return "adaptive";
+		}
+		if (!targetModel.reasoning) {
 			return this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
 		}
 		return this.thinkingLevel;

package/packages/pi-coding-agent/src/core/resource-loader-lsd-md.test.ts

@@ -7,7 +7,7 @@ import test from "node:test";
 import { DefaultResourceLoader } from "./resource-loader.js";
 import { SettingsManager } from "./settings-manager.js";
 
-test("resource loader reads global lsd.md from the app root", async (t) => {
+test("resource loader reads global LSD.md from the app root", async (t) => {
 	const tmp = mkdtempSync(join(tmpdir(), "resource-loader-lsd-md-"));
 	t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
@@ -16,7 +16,7 @@ test("resource loader reads global lsd.md from the app root", async (t) => {
 	const cwd = join(tmp, "project");
 	mkdirSync(agentDir, { recursive: true });
 	mkdirSync(cwd, { recursive: true });
-	writeFileSync(join(appRoot, "lsd.md"), "# global lsd\n", "utf-8");
+	writeFileSync(join(appRoot, "LSD.md"), "# global lsd\n", "utf-8");
 
 	const loader = new DefaultResourceLoader({
 		cwd,
@@ -31,11 +31,11 @@ test("resource loader reads global lsd.md from the app root", async (t) => {
 
 	const contextFiles = loader.getAgentsFiles().agentsFiles;
 	assert.equal(contextFiles.length, 1);
-	assert.equal(contextFiles[0]?.path, join(appRoot, "lsd.md"));
+	assert.equal(contextFiles[0]?.path, join(appRoot, "LSD.md"));
 	assert.equal(contextFiles[0]?.content, "# global lsd\n");
 });
 
-test("resource loader reads ancestor .lsd/lsd.md before AGENTS.md in the same directory", async (t) => {
+test("resource loader uses project LSD.md before CLAUDE.md or AGENTS.md in the same directory", async (t) => {
 	const tmp = mkdtempSync(join(tmpdir(), "resource-loader-lsd-md-"));
 	t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
@@ -44,9 +44,9 @@ test("resource loader reads ancestor .lsd/lsd.md before AGENTS.md in the same di
 	const projectRoot = join(tmp, "project");
 	const cwd = join(projectRoot, "src", "feature");
 	mkdirSync(agentDir, { recursive: true });
-	mkdirSync(join(projectRoot, ".lsd"), { recursive: true });
 	mkdirSync(cwd, { recursive: true });
-	writeFileSync(join(projectRoot, ".lsd", "lsd.md"), "# project lsd\n", "utf-8");
+	writeFileSync(join(projectRoot, "LSD.md"), "# project lsd\n", "utf-8");
+	writeFileSync(join(projectRoot, "CLAUDE.md"), "# claude fallback\n", "utf-8");
 	writeFileSync(join(projectRoot, "AGENTS.md"), "# agents fallback\n", "utf-8");
 
 	const loader = new DefaultResourceLoader({
@@ -62,6 +62,66 @@ test("resource loader reads ancestor .lsd/lsd.md before AGENTS.md in the same di
 
 	const contextFiles = loader.getAgentsFiles().agentsFiles;
 	assert.equal(contextFiles.length, 1);
-	assert.equal(contextFiles[0]?.path, join(projectRoot, ".lsd", "lsd.md"));
+	assert.equal(contextFiles[0]?.path, join(projectRoot, "LSD.md"));
 	assert.equal(contextFiles[0]?.content, "# project lsd\n");
 });
+
+test("resource loader loads both global and project LSD.md files", async (t) => {
+	const tmp = mkdtempSync(join(tmpdir(), "resource-loader-lsd-md-"));
+	t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+	const appRoot = join(tmp, ".lsd");
+	const agentDir = join(appRoot, "agent");
+	const projectRoot = join(tmp, "project");
+	const cwd = join(projectRoot, "src", "feature");
+	mkdirSync(agentDir, { recursive: true });
+	mkdirSync(cwd, { recursive: true });
+	writeFileSync(join(appRoot, "LSD.md"), "# global lsd\n", "utf-8");
+	writeFileSync(join(projectRoot, "LSD.md"), "# project lsd\n", "utf-8");
+
+	const loader = new DefaultResourceLoader({
+		cwd,
+		agentDir,
+		settingsManager: SettingsManager.inMemory(),
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+	});
+	await loader.reload();
+
+	const contextFiles = loader.getAgentsFiles().agentsFiles;
+	assert.equal(contextFiles.length, 2);
+	assert.equal(contextFiles[0]?.path, join(appRoot, "LSD.md"));
+	assert.equal(contextFiles[1]?.path, join(projectRoot, "LSD.md"));
+});
+
+test("resource loader falls back to CLAUDE.md when no LSD.md exists", async (t) => {
+	const tmp = mkdtempSync(join(tmpdir(), "resource-loader-lsd-md-"));
+	t.after(() => rmSync(tmp, { recursive: true, force: true }));
+
+	const appRoot = join(tmp, ".lsd");
+	const agentDir = join(appRoot, "agent");
+	const projectRoot = join(tmp, "project");
+	const cwd = join(projectRoot, "src", "feature");
+	mkdirSync(agentDir, { recursive: true });
+	mkdirSync(cwd, { recursive: true });
+	writeFileSync(join(projectRoot, "CLAUDE.md"), "# claude fallback\n", "utf-8");
+	writeFileSync(join(projectRoot, "AGENTS.md"), "# agents fallback\n", "utf-8");
+
+	const loader = new DefaultResourceLoader({
+		cwd,
+		agentDir,
+		settingsManager: SettingsManager.inMemory(),
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+	});
+	await loader.reload();
+
+	const contextFiles = loader.getAgentsFiles().agentsFiles;
+	assert.equal(contextFiles.length, 1);
+	assert.equal(contextFiles[0]?.path, join(projectRoot, "CLAUDE.md"));
+	assert.equal(contextFiles[0]?.content, "# claude fallback\n");
+});

package/packages/pi-coding-agent/src/core/resource-loader.ts

@@ -71,14 +71,14 @@ function tryReadContextFile(filePath: string): { path: string; content: string }
 
 function loadContextFileFromDir(dir: string): { path: string; content: string } | null {
 	const candidates = [
-		join(dir, "lsd.md"),
-		join(dir, ".lsd", "lsd.md"),
-		join(dir, CONFIG_DIR_NAME, "lsd.md"),
 		join(dir, "LSD.md"),
 		join(dir, ".lsd", "LSD.md"),
 		join(dir, CONFIG_DIR_NAME, "LSD.md"),
-		join(dir, "AGENTS.md"),
+		join(dir, "lsd.md"),
+		join(dir, ".lsd", "lsd.md"),
+		join(dir, CONFIG_DIR_NAME, "lsd.md"),
 		join(dir, "CLAUDE.md"),
+		join(dir, "AGENTS.md"),
 	];
 	for (const filePath of new Set(candidates)) {
 		const loaded = tryReadContextFile(filePath);

package/packages/pi-coding-agent/src/core/sdk.test.ts

@@ -80,3 +80,103 @@ test("createAgentSession restores last session model even when API key cannot be
 		}
 	}
 });
+
+test("createAgentSession defaults to adaptive for supported Anthropic models when enabled", async () => {
+	const tempDir = join(
+		process.cwd(),
+		".tmp-tests",
+		`sdk-anthropic-adaptive-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tempDir, { recursive: true });
+	tempDirs.push(tempDir);
+
+	const authStorage = AuthStorage.inMemory({
+		anthropic: { type: "api_key", key: "test-anthropic-key" },
+	});
+	const modelRegistry = new ModelRegistry(authStorage, join(tempDir, "models.json"));
+	const settingsManager = SettingsManager.inMemory();
+	settingsManager.setDefaultModelAndProvider("anthropic", "claude-sonnet-4-6");
+	settingsManager.setDefaultThinkingLevel("high");
+	settingsManager.setAnthropicAdaptiveByDefault(true);
+	const sessionManager = SessionManager.inMemory(tempDir);
+	const resourceLoader = new DefaultResourceLoader({
+		cwd: tempDir,
+		agentDir: tempDir,
+		settingsManager,
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+	});
+
+	const { session } = await createAgentSession({
+		cwd: tempDir,
+		agentDir: tempDir,
+		authStorage,
+		modelRegistry,
+		settingsManager,
+		sessionManager,
+		resourceLoader,
+	});
+
+	assert.equal(session.model?.provider, "anthropic");
+	assert.equal(session.model?.id, "claude-sonnet-4-6");
+	assert.equal(session.thinkingLevel, "adaptive");
+	assert.equal(settingsManager.getDefaultThinkingLevel(), "high");
+	session.dispose();
+});
+
+test("AgentSession switches supported Anthropic models to adaptive when the setting is enabled", async () => {
+	const tempDir = join(
+		process.cwd(),
+		".tmp-tests",
+		`sdk-anthropic-switch-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tempDir, { recursive: true });
+	tempDirs.push(tempDir);
+
+	const authStorage = AuthStorage.inMemory({
+		anthropic: { type: "api_key", key: "test-anthropic-key" },
+		openai: { type: "api_key", key: "test-openai-key" },
+	});
+	const modelRegistry = new ModelRegistry(authStorage, join(tempDir, "models.json"));
+	const settingsManager = SettingsManager.inMemory();
+	settingsManager.setDefaultModelAndProvider("openai", "gpt-5.4");
+	settingsManager.setDefaultThinkingLevel("high");
+	settingsManager.setAnthropicAdaptiveByDefault(true);
+	const sessionManager = SessionManager.inMemory(tempDir);
+	const resourceLoader = new DefaultResourceLoader({
+		cwd: tempDir,
+		agentDir: tempDir,
+		settingsManager,
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+	});
+
+	const { session } = await createAgentSession({
+		cwd: tempDir,
+		agentDir: tempDir,
+		authStorage,
+		modelRegistry,
+		settingsManager,
+		sessionManager,
+		resourceLoader,
+	});
+
+	assert.equal(session.model?.provider, "openai");
+	assert.equal(session.thinkingLevel, "high");
+
+	const anthropicModel = modelRegistry.getAvailable().find((model) =>
+		model.provider === "anthropic" && model.id === "claude-sonnet-4-6"
+	);
+	if (!anthropicModel) throw new Error("expected claude-sonnet-4-6 to be available");
+
+	await session.setModel(anthropicModel);
+
+	assert.equal(session.model?.provider, "anthropic");
+	assert.equal(session.model?.id, "claude-sonnet-4-6");
+	assert.equal(session.thinkingLevel, "adaptive");
+	session.dispose();
+});

package/packages/pi-coding-agent/src/core/sdk.ts

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { Agent, type AgentMessage, type ThinkingLevel } from "@gsd/pi-agent-core";
-import type { Message, Model } from "@gsd/pi-ai";
+import { supportsAdaptiveThinking, type Message, type Model } from "@gsd/pi-ai";
 import { getAgentDir, getDocsPath } from "../config.js";
 import { AgentSession } from "./agent-session.js";
 import { AuthStorage } from "./auth-storage.js";
@@ -140,6 +140,17 @@ function getDefaultAgentDir(): string {
     return getAgentDir();
 }
 
+function shouldPreferAdaptiveThinkingByDefault(
+    model: Model<any> | undefined,
+    settingsManager: SettingsManager,
+): boolean {
+    return !!model &&
+        model.provider === "anthropic" &&
+        model.reasoning === true &&
+        settingsManager.getAnthropicAdaptiveByDefault() &&
+        supportsAdaptiveThinking(model.id);
+}
+
 /**
  * Create an AgentSession with the specified options.
  *
@@ -252,6 +263,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
         thinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
     }
 
+    const preferAdaptiveByDefault = shouldPreferAdaptiveThinkingByDefault(model, settingsManager);
+    if (preferAdaptiveByDefault) {
+        thinkingLevel = "adaptive";
+    }
+
     // Clamp to model capabilities
     if (!model || !model.reasoning) {
         thinkingLevel = "off";
@@ -259,13 +275,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
     const editMode = settingsManager.getEditMode();
     const toolProfile = settingsManager.getToolProfile();
-    const defaultActiveToolNames: string[] = toolProfile === "minimal"
-        ? (editMode === "hashline"
-            ? ["hashline_read", "bash", "lsp", "tool_search", "tool_enable"]
-            : ["read", "bash", "lsp", "tool_search", "tool_enable"])
-        : editMode === "hashline"
-            ? ["hashline_read", "bash", "hashline_edit", "write", "lsp", "bg_shell", "tool_search", "tool_enable", "Skill", "subagent", "await_subagent"]
-            : ["read", "bash", "edit", "write", "lsp", "bg_shell", "tool_search", "tool_enable", "Skill", "subagent", "await_subagent"];
+    const balancedToolNames = editMode === "hashline"
+        ? ["hashline_read", "bash", "hashline_edit", "write", "lsp", "bg_shell", "tool_search", "tool_enable", "Skill", "subagent", "await_subagent", "ask_user_questions"]
+        : ["read", "bash", "edit", "write", "lsp", "bg_shell", "tool_search", "tool_enable", "Skill", "subagent", "await_subagent", "ask_user_questions"];
+    const defaultActiveToolNames: string[] = toolProfile === "full"
+        ? Object.keys(allTools)
+        : balancedToolNames;
     const initialActiveToolNames: string[] = options.tools
         ? options.tools.map((t) => t.name).filter((n): n is string => typeof n === "string" && n in allTools)
         : defaultActiveToolNames;

package/packages/pi-coding-agent/src/core/settings-manager.ts

@@ -127,9 +127,12 @@ export interface Settings {
 	planModeReasoningModel?: string;
 	planModeReviewModel?: string;
 	planModeCodingModel?: string;
+	autoSuggestPlanMode?: boolean; // default: false — append a system-prompt instruction so the LLM proposes plan mode for large tasks
+	autoSwitchPlanModel?: boolean; // default: false — enable opusplan-style model switching (auto-switch to reasoning model on entry, new-session option on approval)
 	permissionMode?: "danger-full-access" | "accept-on-edit" | "auto" | "plan";
 	classifierModel?: string;
 	defaultThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive";
+	anthropicAdaptiveByDefault?: boolean; // default: false — prefer adaptive thinking when using supported Anthropic models
 	transport?: TransportSetting; // default: "sse"
 	steeringMode?: "all" | "one-at-a-time";
 	followUpMode?: "all" | "one-at-a-time";
@@ -149,8 +152,8 @@ export interface Settings {
 	prompts?: string[]; // Array of local prompt template paths or directories
 	themes?: string[]; // Array of local theme file paths or directories
 	enableSkillCommands?: boolean; // default: true - register skills as /skill:name commands
-	toolSearch?: boolean; // legacy boolean toggle for lazy tool-search mode; superseded by toolProfile
-	toolProfile?: "minimal" | "balanced"; // default: "balanced"
+	toolSearch?: boolean; // legacy boolean toggle from deprecated minimal profile; retained for migration only
+	toolProfile?: "balanced" | "full"; // default: "balanced"
 	terminal?: TerminalSettings;
 	images?: ImageSettings;
 	enabledModels?: string[]; // Model patterns for cycling (same format as --models CLI flag)
@@ -806,6 +809,22 @@ export class SettingsManager {
 		this.setGlobalSetting("planModeCodingModel", modelRef.trim());
 	}
 
+	getAutoSuggestPlanMode(): boolean {
+		return this.settings.autoSuggestPlanMode ?? false;
+	}
+
+	setAutoSuggestPlanMode(enabled: boolean): void {
+		this.setGlobalSetting("autoSuggestPlanMode", enabled);
+	}
+
+	getAutoSwitchPlanModel(): boolean {
+		return this.settings.autoSwitchPlanModel ?? false;
+	}
+
+	setAutoSwitchPlanModel(enabled: boolean): void {
+		this.setGlobalSetting("autoSwitchPlanModel", enabled);
+	}
+
 	setPermissionMode(mode: "danger-full-access" | "accept-on-edit" | "auto" | "plan"): void {
 		this.setGlobalSetting("permissionMode", mode);
 	}
@@ -882,6 +901,14 @@ export class SettingsManager {
 		this.setGlobalSetting("defaultThinkingLevel", level);
 	}
 
+	getAnthropicAdaptiveByDefault(): boolean {
+		return this.settings.anthropicAdaptiveByDefault ?? false;
+	}
+
+	setAnthropicAdaptiveByDefault(enabled: boolean): void {
+		this.setGlobalSetting("anthropicAdaptiveByDefault", enabled);
+	}
+
 	getTransport(): TransportSetting {
 		return this.settings.transport ?? "sse";
 	}
@@ -1067,24 +1094,18 @@ export class SettingsManager {
 		this.setGlobalSetting("enableSkillCommands", enabled);
 	}
 
-	getToolProfile(): "minimal" | "balanced" {
+	getToolProfile(): "balanced" | "full" {
 		const profile = this.settings.toolProfile;
-		if (profile === "minimal" || profile === "balanced") return profile;
-		if (this.settings.toolSearch !== undefined) return this.settings.toolSearch ? "minimal" : "balanced";
+		if (profile === "balanced" || profile === "full") return profile;
+		// Migrate legacy minimal/toolSearch settings to balanced.
+		if (this.settings.toolSearch !== undefined) return "balanced";
 		return "balanced";
 	}
 
-	setToolProfile(profile: "minimal" | "balanced"): void {
+	setToolProfile(profile: "balanced" | "full"): void {
 		this.setGlobalSetting("toolProfile", profile);
-		this.setGlobalSetting("toolSearch", profile === "minimal");
-	}
-
-	getToolSearch(): boolean {
-		return this.getToolProfile() === "minimal";
-	}
-
-	setToolSearch(enabled: boolean): void {
-		this.setToolProfile(enabled ? "minimal" : "balanced");
+		// Keep legacy field in sync with deprecated minimal mode removal.
+		this.setGlobalSetting("toolSearch", false);
 	}
 
 	getThinkingBudgets(): ThinkingBudgetsSettings | undefined {

package/packages/pi-coding-agent/src/core/system-prompt.ts

@@ -152,6 +152,8 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 	addGuideline("Be concise. Prefer short, direct answers over preamble.");
 	addGuideline("For conceptual, product, or UX questions, answer first; inspect code only if implementation detail is needed.");
 
+	const hasSubagent = tools.includes("subagent");
+
 	if (hasLsp) {
 		addGuideline(
 			"Code navigation in typed codebases: use lsp for symbols (definition, references, implementation, hover, diagnostics, rename, format). Use grep/find/ls for text patterns, filenames, and non-code files.",
@@ -160,6 +162,30 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 		addGuideline("Use grep/find/ls for code search and file exploration (faster than bash, respects .gitignore)");
 	}
 
+	if (hasSubagent) {
+		addGuideline(
+			"Recon planning policy: use 0 scouts for narrow known-file work, 1 scout for one broad unfamiliar subsystem, and 2-4 parallel scouts only when the work spans multiple loosely-coupled subsystems.",
+		);
+		addGuideline(
+			"For broad or unfamiliar codebase exploration, delegate reconnaissance to the scout subagent before reading many files yourself. After scout returns, use lsp and targeted reads for the narrowed file set.",
+		);
+		addGuideline(
+			"Call the subagent tool directly. For one scout use { agent, task }. For several scouts use parallel mode with { tasks: [{ agent, task }, ...] }.",
+		);
+		addGuideline(
+			"Scout is for mapping and reconnaissance only — not for final review, audit, or ranked issue lists. Use it to identify relevant files, subsystems, and likely hotspots for later evaluation.",
+		);
+		addGuideline(
+			"If reconnaissance spans multiple loosely-coupled areas, prefer multiple scout subagents in parallel, each covering one subsystem, instead of one model exploring everything itself.",
+		);
+		addGuideline(
+			"For broad review or audit requests, use scout only as a prep step to map architecture and hotspots; the parent model or a reviewer should make the final judgments.",
+		);
+		addGuideline(
+			"Skip scout only when the task is clearly narrow, the relevant file is already known, or the user explicitly asked for direct inspection of a specific file.",
+		);
+	}
+
 	if (hasRead && hasEdit) {
 		addGuideline("Read files before editing them. Never use cat or sed to inspect or modify files.");
 	}