@bacnh85/pi-subagent 0.4.1 → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.6.0 (2026-07-12)
+
+### Security (breaking changes)
+
+- **Project-agent confirmation removed from tool schema.** The `confirmProjectAgents` parameter is no longer exposed to the LLM. Project-agent approval is enforced via trusted configuration only. Interactive sessions prompt for confirmation; headless sessions fail closed unless `allowUnconfirmedProjectAgents` is explicitly enabled through trusted configuration (environment variable `PI_SUBAGENT_ALLOW_UNCONFIRMED_PROJECT_AGENTS=true` or pi settings).
+
+- **Child working directories confined to the workspace.** Tool-specified `cwd` values are validated against the workspace root. Relative paths are resolved within the workspace; `..` traversal, absolute paths outside the workspace, and symlink escapes are rejected. A trusted `allowExternalCwd` setting (env `PI_SUBAGENT_ALLOW_EXTERNAL_CWD=true` or pi settings) can opt out.
+
+- **Tool allowlist enforced.** Child agent tools are validated against a fixed allowlist: `read`, `grep`, `find`, `ls`, `bash`, `edit`, `write`. The `subagent` tool is always rejected. Unknown or misspelled tool names produce clear errors. Read-only service execution cannot gain `bash`, `edit`, or `write`.
+
+- **Default timeout added.** Every child execution receives a default 10-minute timeout (`DEFAULT_TIMEOUT_MS`). Maximum allowed timeout is 60 minutes (`MAX_TIMEOUT_MS`). Timeout errors are distinguishable from parent cancellation.
+
+### Reliability
+
+- **Abort signal composition fixed.** `createCombinedAbortSignal()` correctly combines multiple abort signals with proper listener cleanup. Works without `AbortSignal.any()` via a manual fallback that removes all listeners after the first abort.
+
+- **Parallel abort listeners cleaned up.** Parent-signal listeners attached during parallel execution are removed in a `finally` block after completion.
+
+- **Canonical result status.** `SubAgentResult.status` classifies outcomes as `"success"`, `"partial"`, `"error"`, `"aborted"`, or `"timeout"`. Known Pi SDK stop reasons are classified explicitly; unknown reasons default conservatively to `"error"`.
+
+- **Validation hardened.** Numeric and collection limits (timeout, max parallel tasks, concurrency, chain length, output cap, instructions length) are enforced at both schema and runtime levels.
+
+- **Parallel result ordering preserved.** Results remain in input-task order regardless of completion order.
+
+- **`abortOnFailure` behavior deterministic.** First canonical failure aborts running siblings; queued tasks never start; completed tasks retain their results.
+
+### Agent discovery
+
+- **Malformed agent files produce diagnostics.** Missing name, missing description, empty name, invalid model, invalid thinking levels, and unreadable files are reported with file path and severity. Valid agents continue to load.
+
+### Packaging
+
+- **Peer dependency ranges constrained.** `@earendil-works/pi-*` dependencies use `>=0.80.0 <0.81.0`; `typebox` uses `>=1.3.0 <2.0.0`.
+
+- **Node engine requirement added.** `engines.node: ">=20.18"`.
+
+- **Scripts fixed.** `npm test` uses locally installed `mocha` (no `npx`). Added `npm run check` (typecheck + test).
+
+- **Package metadata updated.** `homepage` points to the package subdirectory.
+
+- **`security.ts` added to published files.**
+
+- **`CHANGELOG.md` added to published files.**
+
+### Documentation
+
+- **Security model section** added to README covering project-agent trust, cwd confinement, tool validation, timeout defaults, cancellation, result status, and compatibility.
+
+### Backward compatibility
+
+- `SubAgentResult.status` is a new field; existing consumers that ignore unknown fields remain compatible.
+- Tool schema no longer accepts `confirmProjectAgents`; model-generated calls using it will be silently ignored (the field is fully removed from the schema, not just deprecated).
+- Child `cwd` values that previously worked outside the workspace are now rejected unless the trusted `allowExternalCwd` setting is enabled.
+- `combineAbortSignals()` is still exported from `runner.ts` but delegates to `createCombinedAbortSignal()` internally.

package/README.md

@@ -1,100 +1,175 @@
 # pi-subagent
 
-Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agents with isolated context — running in-process via the pi SDK for zero spawn overhead and ~10x fewer tokens than process-spawning.
-
-## Features
-
-- **In-process execution**: Uses `createAgentSession()` directly — no `spawn("pi")` overhead
-- **Minimal token budget**: Only the agent's system prompt (no AGENTS.md, no extensions, no thinking)
-- **Streaming progress**: Real-time tool-call and text updates during execution
-- **Three modes**: single, parallel (max 8 tasks, 4 concurrent), chain (sequential with `{previous}`)
-- **Abort support**: Esc propagates to all sub-agents
-- **TUI rendering**: Collapsed/expanded views with tool-call formatting and usage stats
-- **Bundled agents**: scout, reviewer, worker — overridable with your own
-- **Thread viewing**: `/agent` slash command to view subagent threads in isolation
+Isolated in-process subagents for Pi. The `subagent` tool supports single, parallel (8 tasks, 4 concurrent), and chained execution; `/agent` opens inspectable child threads.
 
 ## Install
 
 ```bash
-cd extensions/pi-subagent
-npm install
-cd ../..
-pi install ./extensions/pi-subagent
+pi install npm:@bacnh85/pi-subagent
+# local checkout
+pi install ./pi-subagent
 ```
 
-Or test directly:
+Requires Node.js >= 20.18.
 
-```bash
-pi -e ./extensions/pi-subagent
+## Bundled roles
+
+| Role | Model | Thinking | Tools |
+| --- | --- | --- | --- |
+| `scout` | parent model | low | read, grep, find, ls |
+| `reviewer` | parent model | high | read, grep, find, ls |
+| `worker` | parent model | medium | read, bash, edit, write, grep, find, ls |
+| `general-purpose` | parent model | off | read, bash, edit, write, grep, find, ls |
+
+Bundled roles inherit the parent model so they work with the account already active in Pi. User/project agent files may override `model` and `thinking`.
+
+## Agent files
+
+Create `~/.pi/agent/agents/*.md` or `.pi/agents/*.md`:
+
+```markdown
+---
+name: scout-fast
+description: Locate relevant files and symbols
+tools: read, grep, find, ls
+model: optional-provider/optional-model
+---
+
+Return concise evidence with file/symbol anchors.
 ```
 
-## Usage
+Agent definitions are cached with file-signature invalidation; `/subagent reload` clears the cache.
 
-### Thread Viewing (`/agent`)
+## Context and limits
 
-After running subagents, type `/agent` to view individual subagent threads:
+Children use in-memory SDK sessions with no extensions, skills, prompt templates, or automatic `AGENTS.md` loading. The optional `instructions` argument passes a bounded 16 KB task/repository contract. Only Pi built-in tools are available; Serena, FFF, web, and Munin are not available in lean children.
 
-1. A picker shows `Main [default]` + all subagent threads with status icons
-2. Select a thread to view its full output (task, tool calls, final result, usage stats)
-3. Within the viewer: `Esc` to close, `Alt+←`/`Alt+→` to cycle between threads, `↑/↓` to scroll
+Threads are session-memory only and are cleared when Pi replaces or reloads the session. Timeout and parent cancellation propagate to child sessions. Subagents cannot recursively invoke `subagent`.
 
-This is useful when running many parallel subagents — instead of Ctrl+O to
-see all output at once, you can focus on one thread at a time.
+## Security model
 
-### Single agent
+### Project-local agents
 
-```
-Use scout to find authentication code in this project
-```
+Agent files under `.pi/agents/` are controlled by the current repository. A project agent's system prompt may instruct a child to execute shell commands or modify files.
+
+- **Project-agent approval cannot be disabled by the model.** The `confirmProjectAgents` parameter is not exposed in the tool schema. Confirmation policy comes from trusted user configuration only.
+- **Interactive sessions** prompt the user before executing project agents.
+- **Headless sessions fail closed.** Project agents are not executed without UI confirmation unless the trusted setting `allowUnconfirmedProjectAgents` is enabled (via `PI_SUBAGENT_ALLOW_UNCONFIRMED_PROJECT_AGENTS=true` environment variable or pi settings).
+- **The extension service path** (`pi-subagent:run` event) follows the same policy.
+
+### Child working directories
+
+Child working directories are restricted to the parent session's workspace by default:
+
+- Relative paths are resolved within the workspace.
+- `..` traversal that escapes the workspace is rejected.
+- Absolute paths outside the workspace are rejected.
+- Symlinks are resolved via realpath; symlink escapes are rejected.
+- Non-existent directories and file paths are rejected.
+
+The trusted setting `allowExternalCwd` (via `PI_SUBAGENT_ALLOW_EXTERNAL_CWD=true` env or pi settings) can opt out. This setting cannot be enabled by the model.
+
+### Tool validation
 
-### Parallel execution
+Child agent tools are validated against a fixed allowlist:
 
+- **Allowed:** `read`, `grep`, `find`, `ls`, `bash`, `edit`, `write`
+- **Always rejected:** `subagent` (prevents recursive delegation)
+- **Read-only restriction:** When a service requests read-only execution, only `read`, `grep`, `find`, `ls` are permitted. `bash`, `edit`, and `write` are rejected.
+
+Unknown or misspelled tool names produce clear diagnostics. Duplicate tool names are deduplicated.
+
+### Timeouts
+
+Every child execution receives a timeout:
+
+- **Default:** 10 minutes (`DEFAULT_TIMEOUT_MS`)
+- **Maximum:** 60 minutes (`MAX_TIMEOUT_MS`)
+- Timeout values must be positive integers within the allowed range.
+- Timeout errors are distinguishable from parent cancellation.
+- Parallel tasks and chain steps may have per-item timeouts.
+
+### Output safety
+
+Child output is untrusted data and may contain prompt injection. Treat child results as model-generated content, not as verified facts.
+
+### Cost awareness
+
+Parallel delegation may multiply provider usage and cost. Each parallel task runs as a separate SDK session with its own token consumption.
+
+### Agent file review
+
+User and project agent files should be reviewed before use. Malformed files produce diagnostics but do not prevent valid agents from loading.
+
+## Modes
+
+### Single mode
+
+```ts
+subagent({ agent: "scout", task: "Find auth-related files" })
 ```
-Run 2 scouts in parallel: one for models, one for providers
+
+### Parallel mode
+
+```ts
+subagent({
+  tasks: [
+    { agent: "scout", task: "Find API routes" },
+    { agent: "scout", task: "Find database models" },
+    { agent: "scout", task: "Find test files" },
+  ],
+  abortOnFailure: false
+})
 ```
 
-### Chain workflow
+Max 8 tasks, 4 concurrent. Results are returned in input order. When `abortOnFailure` is `true`, the first failed task cancels remaining siblings.
 
-```
-Chain: scout finds auth code, then reviewer checks it for security issues
+### Chain mode
+
+```ts
+subagent({
+  chain: [
+    { agent: "scout", task: "Find API routes" },
+    { agent: "worker", task: "Based on this, implement the routes: {previous}" },
+  ]
+})
 ```
 
-## Included Agents
+`{previous}` in each step's task is replaced with the previous step's output. The chain stops on the first failed step.
 
-| Agent | Model | Tools | Purpose |
-|-------|-------|-------|---------|
-| `scout` | Haiku | read, grep, find, ls | Fast codebase recon |
-| `reviewer` | Sonnet | read, grep, find, ls, bash | Code review |
-| `worker` | Sonnet | all | General implementation |
+## Result status
 
-## Custom Agents
+Each `SubAgentResult` includes a canonical `status` field:
 
-Create Markdown files with YAML frontmatter in `~/.pi/agent/agents/` (user-level) or `.pi/agents/` (project-level):
+| Status | Meaning |
+|--------|---------|
+| `success` | Completed normally |
+| `partial` | Truncated (max_tokens, length, context_limit) |
+| `error` | Provider error, tool error, or unknown stop reason |
+| `aborted` | Cancelled by parent or sibling |
+| `timeout` | Exceeded the allowed timeout |
 
-```markdown
----
-name: my-agent
-description: When to use this agent
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
----
+The raw `stopReason` from the Pi SDK is preserved in the result.
 
-Your system prompt here. This is the ONLY prompt the sub-agent sees.
-```
+## Timeout and cancellation
 
-See `agent-format.md` for the full format specification.
+- **Default timeout:** 10 minutes per child.
+- **Per-task/step override:** Use `timeout` in task/step params.
+- **Parent cancellation:** Aborting the parent tool call cancels all children.
+- **Sibling cancellation:** In parallel mode with `abortOnFailure: true`, the first failed task cancels running siblings.
+- **Timeout vs. abort:** Timeout errors set `status: "timeout"` and `stopReason: "timeout"`; parent cancellation sets `status: "aborted"`.
 
-## Architecture
+## Extension contract
 
-Sub-agents run in-process via the pi SDK. Compared to the process-spawn approach (spawning `pi --mode json`), this saves ~4-11K tokens per sub-agent invocation by:
+`pi-subagent` owns the `pi-subagent:run` event contract for one named-agent request. `pi-review` uses it for isolated review. Requests use an immediate boolean `accept()` claim and exactly one `respond()` callback; this suppresses duplicate responders while missing services and timeouts remain caller-controlled.
 
-- Using only the agent's system prompt (no pi defaults)
-- Skipping AGENTS.md, extensions, skills, prompt templates
-- Disabling thinking, compaction, retry
-- Using in-memory sessions (no disk I/O)
-- Sharing the parent's auth/model infrastructure
+## Compatibility
 
-## Requirements
+- Requires `@earendil-works/pi-coding-agent >=0.80.0 <0.81.0`
+- Requires `@earendil-works/pi-ai >=0.80.0 <0.81.0`
+- Requires `@earendil-works/pi-agent-core >=0.80.0 <0.81.0`
+- Requires `@earendil-works/pi-tui >=0.80.0 <0.81.0`
+- Requires `typebox >=1.3.0 <2.0.0`
+- Requires Node.js >= 20.18
 
-- pi coding agent with configured API keys
-- Peer dependencies satisfied by the pi runtime (no extra npm install needed)
+See [`agent-format.md`](./agent-format.md) for all frontmatter fields.

package/agent-format.md

@@ -8,7 +8,7 @@ Sub-agents are defined as Markdown files with YAML frontmatter.
 |----------|-------|
 | `~/.pi/agent/agents/*.md` | User-level (all projects) |
 | `.pi/agents/*.md` | Project-level |
-| `<skill>/agents/*.md` | Bundled with pi-sugagents |
+| `<package>/agents/*.md` | Bundled with pi-subagent |
 
 Project agents override user agents with the same name when `agentScope: "both"`.
 
@@ -19,7 +19,8 @@ Project agents override user agents with the same name when `agentScope: "both"`
 name: my-agent          # Required. Unique identifier (kebab-case).
 description: ...        # Required. When to use this agent.
 tools: read, grep, ...  # Optional. Comma-separated tool names. Defaults to all.
-model: claude-haiku-4-5 # Optional. Model ID. Defaults to parent's model.
+model: provider/model     # Optional. Defaults to parent's model.
+thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
 ---
 ```
 
@@ -31,12 +32,22 @@ The body after frontmatter becomes the agent's **entire system prompt**. No pi d
 
 ## Available Tools
 
-Built-in pi tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
+Child agent tools are validated against a fixed allowlist:
 
-The `subagent` tool is never available to sub-agents (prevents accidental recursion). Sub-agents run at one level of delegation only; they cannot spawn further sub-agents.
+| Category | Tools |
+|----------|-------|
+| Read-only | `read`, `grep`, `find`, `ls` |
+| Mutation | `edit`, `write` |
+| Execution | `bash` |
+
+The `subagent` tool is always rejected to prevent recursive delegation.
+Unknown or misspelled tool names produce a clear error.
+Duplicate names are deduplicated automatically.
 
 Custom/extension tools are NOT available to sub-agents by default (each runs in an isolated in-memory session with no extensions).
 
+Read-only service execution (used by `pi-review`) restricts tools to the read-only category.
+
 ## Model Resolution
 
 Model IDs are resolved via `getModel("provider", "id")`. Common values:
@@ -47,13 +58,17 @@ Model IDs are resolved via `getModel("provider", "id")`. Common values:
 
 If not specified, defaults to the parent session's model.
 
+## Instruction handoff
+
+Children do not automatically load repository instructions. Callers may pass an `instructions` task contract, truncated to 16 KB. Use this for relevant repository rules or review contracts rather than copying the parent transcript.
+
 ## Token Budget
 
 Each sub-agent runs with:
 - **System prompt**: agent body only (~200-1K tokens typical)
 - **No AGENTS.md**: saves 500-5K tokens
 - **No extensions/skills loaded**: saves 200-1K tokens
-- **Thinking off**: saves reasoning overhead
+- **Thinking per role**: defaults off; bundled scout/reviewer/worker choose low/high/medium
 - **No compaction**: avoids compaction token cost
 
 This is ~10x leaner than spawning a full `pi` process.

package/agents/reviewer.md

@@ -1,30 +1,36 @@
 ---
 name: reviewer
-description: Code review specialist. Use for reviewing changes, finding bugs, suggesting improvements.
-tools: read, grep, find, ls, bash
-model: openai-codex/gpt-5.5
+description: Code review specialist. Use for correctness, security, regression, and meaningful test-gap review.
+tools: read, grep, find, ls
+thinking: high
 ---
 
-You are a senior code reviewer. Review code changes and provide specific, actionable feedback.
+You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.
 
-Focus on:
-1. **Correctness**: Logic errors, edge cases, off-by-one
-2. **Security**: Injection risks, auth bypasses, data leaks
-3. **Performance**: N+1 queries, unnecessary allocations, blocking calls
-4. **Maintainability**: Unclear naming, missing error handling, tight coupling
-5. **Best practices**: Idiomatic patterns, testability, documentation
+Focus only on actionable issues introduced by the reviewed change:
+1. Correctness and edge cases
+2. Security and data loss
+3. Regressions and API compatibility
+4. Missing tests that allow a likely bug to escape
 
-Output format:
+Avoid style noise, praise, and speculative redesign. Every finding needs code evidence.
 
-## Summary
-Brief assessment (1-2 sentences)
+Return JSON only:
+```json
+{
+  "summary": "compact scope/result summary",
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "file": "relative/path",
+      "line": 1,
+      "issue": "what is wrong and why it matters",
+      "evidence": "specific inspected code evidence",
+      "suggestedFix": "smallest safe fix",
+      "blocking": true
+    }
+  ]
+}
+```
 
-## Issues Found
-For each issue:
-- **Severity**: critical | high | medium | low
-- **File**: path with line numbers
-- **Problem**: What's wrong
-- **Fix**: Suggested change (code block)
-
-## Overall Assessment
-Green/yellow/red with reasoning.
+Use an empty `findings` array when clean. Do not modify files or Git state.

package/agents/scout.md

@@ -2,7 +2,7 @@
 name: scout
 description: Fast codebase recon that returns compressed context for handoff. Use for finding files, understanding structure, locating symbols.
 tools: read, grep, find, ls
-model: opencode-go/deepseek-v4-flash
+thinking: low
 ---
 
 You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
@@ -22,8 +22,8 @@ Strategy:
 
 Output format:
 
-## Files Retrieved
-List with exact line ranges:
+## Evidence
+List exact file/symbol anchors and relevant line ranges:
 1. `path/to/file.ts` (lines 10-50) - Description of what's here
 2. `path/to/other.ts` (lines 100-150) - Description
 3. ...

package/agents/worker.md

@@ -1,7 +1,7 @@
 ---
 name: worker
-description: General-purpose coding agent with full tool access. Use for implementation, refactoring, debugging, and complex multi-step tasks.
-model: opencode-go/deepseek-v4-pro
+description: General-purpose coding agent with full tool access. Use only when explicitly requested for isolated implementation.
+thinking: medium
 ---
 
 You are a skilled software engineer. Implement the requested task with care and precision.

package/{agents.ts → extensions/agents.ts}

@@ -1,5 +1,5 @@
 /**
- * Agent discovery and configuration for pi-sugagents.
+ * Agent discovery and configuration for pi-subagent.
  *
  * Loads agent definitions from Markdown files with YAML frontmatter.
  * Discovers from user-level (~/.pi/agent/agents/), project-level
@@ -18,6 +18,7 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	systemPrompt: string;
 	source: "user" | "project" | "bundled";
 	filePath: string;
@@ -26,6 +27,14 @@ export interface AgentConfig {
 export interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
+	diagnostics: AgentDiscoveryDiagnostic[];
+}
+
+export interface AgentDiscoveryDiagnostic {
+	filePath: string;
+	issue: string;
+	/** 'warn' for recoverable issues, 'error' for file-skip issues. */
+	severity: "warn" | "error";
 }
 
 interface AgentCache {
@@ -46,7 +55,11 @@ export function invalidateAgentCache(): void {
 	_cache = null;
 }
 
-function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"): AgentConfig[] {
+function loadAgentsFromDir(
+	dir: string,
+	source: "user" | "project" | "bundled",
+	diagnostics: AgentDiscoveryDiagnostic[],
+): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
 	if (!fs.existsSync(dir)) return agents;
@@ -54,25 +67,72 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 	let entries: fs.Dirent[];
 	try {
 		entries = fs.readdirSync(dir, { withFileTypes: true });
-	} catch {
+	} catch (err) {
+		diagnostics.push({
+			filePath: dir,
+			issue: `Cannot read directory: ${err instanceof Error ? err.message : String(err)}`,
+			severity: "warn",
+		});
 		return agents;
 	}
 
 	for (const entry of entries) {
 		if (!entry.name.endsWith(".md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) {
+			diagnostics.push({
+				filePath: path.join(dir, entry.name),
+				issue: `Not a regular file or symlink, skipping.`,
+				severity: "warn",
+			});
+			continue;
+		}
 
 		const filePath = path.join(dir, entry.name);
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
-		} catch {
+		} catch (err) {
+			diagnostics.push({
+				filePath,
+				issue: `Cannot read file: ${err instanceof Error ? err.message : String(err)}`,
+				severity: "error",
+			});
 			continue;
 		}
 
 		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
 
-		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
+			if (typeof frontmatter.name !== "string" && typeof frontmatter.description !== "string") {
+				diagnostics.push({
+					filePath,
+					issue: `Missing both "name" and "description" in frontmatter. Agent file skipped.`,
+					severity: "error",
+				});
+			} else if (typeof frontmatter.name !== "string") {
+				diagnostics.push({
+					filePath,
+					issue: `Missing "name" in frontmatter. Agent file skipped.`,
+					severity: "error",
+				});
+			} else {
+				diagnostics.push({
+					filePath,
+					issue: `Missing "description" in frontmatter. Agent file skipped.`,
+					severity: "error",
+				});
+			}
+			continue;
+		}
+
+		if (!frontmatter.name.trim()) {
+			diagnostics.push({
+				filePath,
+				issue: `"name" in frontmatter is empty. Agent file skipped.`,
+				severity: "error",
+			});
+			continue;
+		}
 
 		const tools =
 			typeof frontmatter.tools === "string"
@@ -81,11 +141,33 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 					? (frontmatter.tools as unknown[]).filter((t): t is string => typeof t === "string")
 					: undefined;
 
+		if (typeof frontmatter.model === "string" && frontmatter.model && !frontmatter.model.includes("/")) {
+			diagnostics.push({
+				filePath,
+				issue: `Model "${frontmatter.model}" does not include a provider prefix (e.g., "anthropic/claude-sonnet-4-20250514"). Resolution may fail.`,
+				severity: "warn",
+			});
+		}
+
+		if (typeof frontmatter.thinking === "string" && frontmatter.thinking) {
+			const validLevels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+			if (!validLevels.includes(frontmatter.thinking)) {
+				diagnostics.push({
+					filePath,
+					issue: `Invalid thinking level "${frontmatter.thinking}". Valid values: ${validLevels.join(", ")}. Using default.`,
+					severity: "warn",
+				});
+			}
+		}
+
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
 			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+			thinking: typeof frontmatter.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(frontmatter.thinking)
+				? frontmatter.thinking as AgentConfig["thinking"]
+				: undefined,
 			systemPrompt: body,
 			source,
 			filePath,
@@ -165,16 +247,18 @@ export function discoverAgents(
 			}
 		}
 		if (!stale) {
-			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir };
+			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir, diagnostics: [] };
 		}
 		// Cache is stale — rebuild below
 		_cache = null;
 	}
 
-	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const diagnostics: AgentDiscoveryDiagnostic[] = [];
+
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user", diagnostics);
 	const projectAgents =
-		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
-	const bundledAgents = loadAgentsFromDir(bundledAgentsDir, "bundled");
+		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project", diagnostics);
+	const bundledAgents = loadAgentsFromDir(bundledAgentsDir, "bundled", diagnostics);
 
 	const agentMap = new Map<string, AgentConfig>();
 
@@ -205,7 +289,7 @@ export function discoverAgents(
 		dirSignatures,
 	};
 
-	return { agents, projectAgentsDir };
+	return { agents, projectAgentsDir, diagnostics };
 }
 
 export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {