pi-subagents-j0k3r 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.1.0 - 2026-06-27
+
+### Added
+- Added support for loading markdown-defined subagents from both `agents` and `subagents` directories globally and project-locally.
+- Added startup warnings when duplicate names exist in `agents` and `subagents` at the same scope, while preserving `subagents` as the winning source.
+- Enabled project Skill Registry configuration and ignored generated registry cache outputs.
+
+### Fixed
+- Made `model_profiles` global-only so project-local `.pi/subagents.json` cannot override per-agent model/effort routing.
+
+### Documentation
+- Updated README and Subagents configuration skill guidance for `agents`/`subagents` source precedence and global-only model profiles.
+
 ## 1.0.1 - 2026-06-27
 
 ### Fixed

package/README.md

@@ -67,10 +67,14 @@ Subagents are markdown files with optional YAML-like frontmatter.
 
 Load order:
 
-1. Global user subagents from `$PI_CODING_AGENT_DIR/subagents/*.md`.
-2. Project subagents from `.pi/subagents/*.md`.
+1. Global user agents from `$PI_CODING_AGENT_DIR/agents/*.md`.
+2. Global user subagents from `$PI_CODING_AGENT_DIR/subagents/*.md`.
+3. Project agents from `.pi/agents/*.md`.
+4. Project subagents from `.pi/subagents/*.md`.
 
-Project definitions override global definitions with the same normalized name.
+Project definitions override global definitions with the same normalized name. Within the same scope, `subagents` definitions override `agents` definitions with the same normalized name and Pi shows a startup warning so the duplicate can be cleaned up.
+
+The npm package is the extension runtime only. It does not ship or load subagent definitions from `node_modules/pi-subagents-j0k3r/agents`; use the directories above, or run `subagent_list_agents` / `subagent({ action: "list" })` to inspect the definitions Pi actually loaded.
 
 Default global agent directory:
 
@@ -127,7 +131,7 @@ Config files:
 .pi/subagents.json              # project
 ```
 
-Config resolves as a cascade: project `.pi/subagents.json` overrides global `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. Model profiles are merged by normalized lowercase agent name, with project profile fields overriding global profile fields.
+Config resolves as a cascade: project `.pi/subagents.json` overrides global `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. `model_profiles` are scoped to the definition source: project-local definitions use `.pi/subagents.json`, while global definitions use the global `subagents.json`. If a project definition overrides a global definition with the same name, the project definition and its project-local profile win.
 
 Example:
 
@@ -168,7 +172,7 @@ Example:
 |---|---:|---|
 | `default_model` | current orchestrator model | Fallback model for all subagents. Format: `provider/model-id`. |
 | `default_effort` | current orchestrator effort | Fallback thinking effort. Also accepts `default_thinking_level` or `thinkingLevel`. |
-| `model_profiles` | `{}` | Per-agent model/effort overrides. |
+| `model_profiles` | `{}` | Per-agent model/effort overrides scoped to matching definitions. Project-local profiles apply to project-local definitions; global profiles apply to global definitions. |
 | `timeout_ms` | `600000` | Total timeout per subagent task. |
 | `stall_timeout_ms` | `120000` | Inactivity timeout for a subagent session. |
 | `max_concurrency` | `5` | Max concurrent subagent tasks per cwd/config pair. |
@@ -200,7 +204,7 @@ any tool starting with subagent_
 
 Effective model resolution order:
 
-1. `model_profiles[agent].model`
+1. `model_profiles[agent].model` from the config matching the selected definition scope: project-local for project definitions, global for global definitions
 2. subagent frontmatter `model`
 3. `default_model`
 4. current orchestrator model
@@ -208,7 +212,7 @@ Effective model resolution order:
 
 Effective effort resolution order:
 
-1. `model_profiles[agent].effort`
+1. `model_profiles[agent].effort` from the config matching the selected definition scope: project-local for project definitions, global for global definitions
 2. subagent frontmatter `effort` / `thinking_level` / `thinkingLevel`
 3. `default_effort`
 4. current orchestrator thinking level
@@ -282,20 +286,14 @@ Behavior:
 | Entry point | Description |
 |---|---|
 | `/subagents` | Open the session-focused TUI subagent history panel. |
-| `/subagent-models` | Configure global subagent and SDD phase model profiles. |
+| `/subagent-models` | Configure subagent and SDD phase model profiles in the matching local or global config. |
 | `ctrl+,` | Open the TUI subagent history panel in OpenCode mode by default. Configurable via `history_panel_shortcut` in `subagents.json`. |
 | `x` | Cancel the currently selected queued/running subagent from the open history/detail panel by default. Configurable via `detail_cancel_shortcut` in `subagents.json`. |
 | `ctrl+h` | Send the running Claude-mode subagent task to the background by default. Configurable via `background_handoff_shortcut` in `subagents.json`. |
 
-`/subagent-models` writes global profile changes to:
-
-```txt
-~/.pi/agent/subagents.json
-```
-
-or `$PI_CODING_AGENT_DIR/subagents.json` when `PI_CODING_AGENT_DIR` is set.
+`/subagent-models` writes profile changes to the config that matches each selected definition: project-local subagents write to `.pi/subagents.json`, while global subagents and synthetic SDD phase rows write to `~/.pi/agent/subagents.json` or `$PI_CODING_AGENT_DIR/subagents.json` when `PI_CODING_AGENT_DIR` is set.
 
-In non-TUI environments, edit `model_profiles` manually in that JSON file.
+In non-TUI environments, edit `model_profiles` manually in the matching local or global JSON file.
 
 ## Task history
 
@@ -392,7 +390,7 @@ This package bundles:
 - `index.ts` and `src/**` — the Pi extension runtime.
 - `skills/subagents-configuration/SKILL.md` — configuration guidance for agents that need to create or edit subagent definitions.
 
-Subagent definitions are intentionally user/project configuration, not hard-coded package behavior. Add them globally in `$PI_CODING_AGENT_DIR/subagents/*.md` or project-locally in `.pi/subagents/*.md`.
+Subagent definitions are intentionally user/project configuration, not hard-coded package behavior. Add them globally in `$PI_CODING_AGENT_DIR/agents/*.md` or `$PI_CODING_AGENT_DIR/subagents/*.md`, or project-locally in `.pi/agents/*.md` or `.pi/subagents/*.md`. Do not inspect `node_modules/pi-subagents-j0k3r/agents` for definitions; that path is not part of the package design and may not exist.
 
 ## Development
 

package/index.ts

@@ -1,5 +1,5 @@
 import { SubagentManager } from './src/manager.js';
-import { readSubagentsConfig } from './src/config.js';
+import { readSubagentsConfig, subagentSourceWarnings } from './src/config.js';
 import { registerSubagentTools, triggerClaudeBackgroundHandoff } from './src/tools.js';
 import { runSubagentModelsCommand } from './src/model-profiles-ui.js';
 import { SubagentsHistoryPanel } from './src/ui.js';
@@ -412,6 +412,8 @@ export default function subagentsExtension(pi: any): void {
 
   pi.on?.('session_start', (_event: unknown, ctx: any) => {
     clearClaudeBackgroundWidget();
+    const cwd = ctx?.cwd ?? process.cwd();
+    for (const warning of subagentSourceWarnings(cwd)) ctx?.ui?.notify?.(warning, 'warning');
     if (typeof ctx?.ui?.setWidget !== 'function') return;
     widgetCtx = ctx;
     if (!installClaudeBackgroundWidget(ctx)) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-j0k3r",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Installable Pi package that adds markdown-defined subagents, delegated task tools, history, and model profiles.",
   "type": "module",
   "license": "MIT",

package/skills/subagents-configuration/SKILL.md

@@ -19,10 +19,13 @@ Use this block as the machine-readable source for `.pi/skill-registry.json` gene
   "domains": ["subagents-configuration", "subagent-config", "model-profile-config", "tool-allowlist-config", "subagent-history-config", "subagent-shortcut-config"],
   "triggers": {
     "paths": [
+      ".pi/agents/**/*.md",
       ".pi/subagents/**/*.md",
       ".pi/subagents.json",
+      "agents/**/*.md",
       "subagents/**/*.md",
       "subagents.json",
+      "~/.pi/agent/agents/**/*.md",
       "~/.pi/agent/subagents/**/*.md",
       "~/.pi/agent/subagents.json"
     ],
@@ -88,11 +91,12 @@ Do not load this skill for ordinary subagent delegation/use (`subagent_run`, tas
 - Prefer narrow tool allowlists per subagent. Do not grant write/bash tools unless the subagent purpose requires them.
 - For SDD/PRD phase agents, prefer deterministic active-flow memory tools only: `memory_search`, `memory_get`, `memory_add`, and `memory_update`; avoid `memory_context` and `memory_recall` in subagent allowlists unless there is a specific reviewed need.
 - For SDD phase agents, memory write tools may be allowed only for active SDD flow memory/artifacts according to `sdd-workflow`.
-- Project subagents live in `.pi/subagents/*.md`; global user subagents live in `$PI_CODING_AGENT_DIR/subagents/*.md` or `~/.pi/agent/subagents/*.md`.
-- Project definitions override global definitions with the same normalized name.
+- Project subagent definitions live in `.pi/agents/*.md` and `.pi/subagents/*.md`; global user definitions live in `$PI_CODING_AGENT_DIR/agents/*.md`, `$PI_CODING_AGENT_DIR/subagents/*.md`, `~/.pi/agent/agents/*.md`, or `~/.pi/agent/subagents/*.md`.
+- The npm package is the extension runtime only; do not tell users or future agents to inspect `node_modules/pi-subagents-j0k3r/agents` for subagent definitions. Use the real global/project definition directories above, or runtime listing via `subagent_list_agents` / `subagent({ action: "list" })`.
+- Project definitions override global definitions with the same normalized name. Within the same scope, definitions in `subagents` override definitions in `agents` with the same normalized name, and Pi should warn at session startup so users can clean up the duplicate.
 - Subagents config resolves as a cascade: project `.pi/subagents.json` overrides global `$PI_CODING_AGENT_DIR/subagents.json` or `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. Communicate this precedence to users when explaining config behavior.
-- `model_profiles` are deep-merged by agent name with project-local profile fields taking precedence over global profile fields.
-- Prefer configuring subagent `model` and `effort` in global or project `subagents.json` under `model_profiles`, not in the subagent markdown frontmatter. Markdown definitions should usually contain identity, description, tool allowlist, and behavioral instructions only.
+- `model_profiles` are scoped to the matching subagent definition source: project-local profile entries in `.pi/subagents.json` apply to project-local definitions, while global profile entries apply to global definitions. If a project definition overrides a global definition with the same normalized name, the project definition and its project-local profile win.
+- Prefer configuring subagent `model` and `effort` under `model_profiles` in the config matching the definition scope: project-local definitions use `.pi/subagents.json`; global definitions use `$PI_CODING_AGENT_DIR/subagents.json` or `~/.pi/agent/subagents.json`. Markdown definitions should usually contain identity, description, tool allowlist, and behavioral instructions only.
 - Nested subagent sessions should use `session_resources: "lean"` by default so the subagent markdown body becomes the nested session system prompt, the delegated user prompt contains only orchestrator context/task, and workflow skills, prompt templates, themes, context files, and startup context injections are not auto-loaded.
 - In lean mode, extensions are loaded for allowlisted tools and tool-safety hooks only; prompt/context lifecycle hooks such as `before_agent_start` and `context` must not inject hidden messages into subagent turns.
 - Subagent task history is stored globally under data storage, but rows remain project-scoped by `cwd`; history stores delegated prompt and subagent system prompt separately.
@@ -151,7 +155,7 @@ tools:
 Instructions...
 ```
 
-Configure routing separately in `subagents.json` when needed. If no profile/default is configured, the subagent inherits the current orchestrator model and thinking effort.
+Configure model/effort routing separately in the matching local or global `subagents.json` when needed. If no matching profile/default is configured, the subagent inherits the current orchestrator model and thinking effort.
 
 ```json
 {
@@ -166,9 +170,9 @@ Configure routing separately in `subagents.json` when needed. If no profile/defa
 
 Model/effort resolution order:
 
-1. `model_profiles[agentName]` in `subagents.json`.
+1. `model_profiles[agentName]` from the config matching the selected definition scope: `.pi/subagents.json` for project-local definitions, or `$PI_CODING_AGENT_DIR/subagents.json` / `~/.pi/agent/subagents.json` for global definitions.
 2. Markdown frontmatter `model` / `effort` only for explicit per-file overrides.
-3. `default_model` / `default_effort` in `subagents.json`.
+3. `default_model` / `default_effort` from effective `subagents.json` config.
 4. Current orchestrator model / effort.
 
 ## Decision Gates
@@ -176,16 +180,16 @@ Model/effort resolution order:
 - If the subagent will modify files, run bash, or write memory, ask whether a full SDD workflow or stricter review is required.
 - If the subagent needs human input, require a structured `interaction_required` request with enough prompt, payload, and expected-response data for the parent to answer.
 - If a project wants many subagents or broad tools, recommend starting with read-only discovery agents and expanding deliberately.
-- If model profiles are global, confirm the user wants global behavior rather than project-only config.
+- If the user asks for model profiles, choose the config that matches the subagent definition scope: project-local profiles for project-local definitions and global profiles for global definitions or synthetic SDD phase rows.
 
 ## Execution Steps
 
 1. Identify target scope: npm package install/update, global subagent, project subagent, global config, or project config, and explain the cascade when relevant: project-local config first, then global config for missing fields, then built-in defaults.
 2. For package setup, inspect settings before editing; use `pi install npm:pi-subagents-j0k3r` when possible, or edit `~/.pi/agent/settings.json` only when the CLI is unavailable/broken. Prefer unpinned `npm:pi-subagents-j0k3r` unless the user asks for a fixed version.
-3. Read existing subagent markdown/config before editing.
-4. For new subagents, choose lowercase kebab-case names and clear trigger-focused descriptions.
+3. Read existing subagent markdown/config before editing, checking both `agents` and `subagents` directories for the requested scope. Check optional directories for existence before listing them so missing user/project definition directories do not produce confusing `Path not found` messages.
+4. For new subagents, choose lowercase kebab-case names and clear trigger-focused descriptions. Write subagent markdown definitions in English by default; use another language only when the user explicitly requests it. Prefer `subagents` for new definitions unless the user explicitly needs compatibility with an `agents` harness.
 5. Set minimal tool allowlists; remove any `subagent_*` entries.
-6. Configure `model_profiles`, `default_model`, and `default_effort` in `subagents.json` only when the user wants explicit routing; do not put model routing in subagent markdown unless the user explicitly asks for per-file overrides. Explain that unconfigured fields inherit from the orchestrator.
+6. Configure `model_profiles` in the matching local/global `subagents.json` when the user wants explicit per-agent routing. Configure `default_model` and `default_effort` in effective `subagents.json` only when the user wants defaults. Do not put model routing in subagent markdown unless the user explicitly asks for per-file overrides. Explain that unconfigured fields inherit from the orchestrator.
 7. Configure `debug: true` only for temporary diagnostics; keep `debug: false` by default and remember logs are written under the executing project's `.pi` directory.
 8. Validate JSON syntax for settings/subagents config and frontmatter/body structure for markdown agents.
 9. When configuring OpenCode-mode history opening, prefer `history_panel_shortcut` with `ctrl+<letter>` or `ctrl+,` values and document any built-in shortcut conflicts.
@@ -200,7 +204,7 @@ Model/effort resolution order:
 Return:
 
 - Skill applied: `subagents-configuration`.
-- Scope/path configured or reviewed.
+- Scope/path configured or reviewed, including whether definitions came from `agents` or `subagents`.
 - Package settings and subagents/config fields added, changed, or preserved.
 - Tool allowlist, system-prompt isolation, Context7 scope, memory-tool scope, debug logging, model/effort decisions, and inheritance behavior.
 - Runtime behavior explained when relevant: task vs background, automatic notifications, `/subagents`, `ctrl+o`, and `subagent_result`.

package/src/config.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import type { ModelRef, SubagentDefinition, SubagentModelProfile, SubagentModelProfiles, SubagentSessionResources, SubagentsConfig, SubagentUiMode, ThinkingEffort } from './types.js';
+import type { ModelRef, SubagentDefinition, SubagentDefinitionScope, SubagentModelProfile, SubagentModelProfiles, SubagentSessionResources, SubagentsConfig, SubagentUiMode, ThinkingEffort } from './types.js';
 
 const DEFAULT_TOOLS = ['read', 'memory_context', 'memory_search', 'memory_recall', 'memory_get'];
 const DEFAULT_MAX_CONCURRENCY = 5;
@@ -155,7 +155,7 @@ function parseModelProfiles(value: unknown): SubagentModelProfiles {
   if (!isPlainObject(value)) return {};
   const profiles: SubagentModelProfiles = {};
   for (const [name, rawProfile] of Object.entries(value)) {
-    const normalizedName = name.trim();
+    const normalizedName = name.trim().toLowerCase();
     if (!normalizedName) continue;
     const profile = parseModelProfile(rawProfile);
     if (profile) profiles[normalizedName] = profile;
@@ -163,16 +163,6 @@ function parseModelProfiles(value: unknown): SubagentModelProfiles {
   return profiles;
 }
 
-function mergeModelProfiles(globalRaw: unknown, projectRaw: unknown): SubagentModelProfiles {
-  const globalProfiles = parseModelProfiles(globalRaw);
-  const projectProfiles = parseModelProfiles(projectRaw);
-  const merged: SubagentModelProfiles = { ...globalProfiles };
-  for (const [name, projectProfile] of Object.entries(projectProfiles)) {
-    merged[name] = { ...(merged[name] ?? {}), ...projectProfile };
-  }
-  return merged;
-}
-
 function serializeModelRef(model: ModelRef): string {
   return `${model.provider}/${model.id}`;
 }
@@ -188,10 +178,14 @@ export function readSubagentsConfig(cwd: string): SubagentsConfig {
   const globalRaw = readJson(subagentsConfigPath());
   const projectRaw = readJson(path.join(cwd, '.pi', 'subagents.json'));
   const raw = { ...globalRaw, ...projectRaw };
+  const globalModelProfiles = parseModelProfiles(globalRaw.model_profiles);
+  const projectModelProfiles = parseModelProfiles(projectRaw.model_profiles);
   return {
     default_model: parseModel(raw.default_model),
     default_effort: parseEffort(raw.default_effort ?? raw.default_thinking_level ?? raw.thinkingLevel),
-    model_profiles: mergeModelProfiles(globalRaw.model_profiles, projectRaw.model_profiles),
+    model_profiles: { ...globalModelProfiles, ...projectModelProfiles },
+    global_model_profiles: globalModelProfiles,
+    project_model_profiles: projectModelProfiles,
     timeout_ms: positiveInteger(raw.timeout_ms, DEFAULT_TIMEOUT_MS),
     stall_timeout_ms: positiveInteger(raw.stall_timeout_ms, DEFAULT_STALL_TIMEOUT_MS),
     max_concurrency: positiveInteger(raw.max_concurrency, DEFAULT_MAX_CONCURRENCY),
@@ -205,8 +199,16 @@ export function readSubagentsConfig(cwd: string): SubagentsConfig {
   };
 }
 
-export function saveGlobalSubagentModelProfile(input: { agentName: string; profile: SubagentModelProfile; agentDir?: string }): void {
-  const file = subagentsConfigPath(input.agentDir);
+function projectSubagentsConfigPath(cwd: string): string {
+  return path.join(cwd, '.pi', 'subagents.json');
+}
+
+function subagentsConfigPathForScope(input: { scope?: SubagentDefinitionScope; cwd?: string; agentDir?: string }): string {
+  return input.scope === 'project' && input.cwd ? projectSubagentsConfigPath(input.cwd) : subagentsConfigPath(input.agentDir);
+}
+
+export function saveSubagentModelProfile(input: { agentName: string; profile: SubagentModelProfile; scope?: SubagentDefinitionScope; cwd?: string; agentDir?: string }): void {
+  const file = subagentsConfigPathForScope(input);
   const root = readJson(file);
   const writableRoot: Record<string, unknown> = isPlainObject(root) ? { ...root } : {};
   const modelProfiles = isPlainObject(writableRoot.model_profiles) ? { ...writableRoot.model_profiles } : {};
@@ -219,8 +221,12 @@ export function saveGlobalSubagentModelProfile(input: { agentName: string; profi
   fs.writeFileSync(file, `${JSON.stringify(writableRoot, null, 2)}\n`, 'utf8');
 }
 
-export function resetGlobalSubagentModelProfileField(input: { agentName: string; field: 'model' | 'effort'; agentDir?: string }): void {
-  const file = subagentsConfigPath(input.agentDir);
+export function saveGlobalSubagentModelProfile(input: { agentName: string; profile: SubagentModelProfile; agentDir?: string }): void {
+  saveSubagentModelProfile({ ...input, scope: 'global' });
+}
+
+export function resetSubagentModelProfileField(input: { agentName: string; field: 'model' | 'effort'; scope?: SubagentDefinitionScope; cwd?: string; agentDir?: string }): void {
+  const file = subagentsConfigPathForScope(input);
   const root = readJson(file);
   const writableRoot: Record<string, unknown> = isPlainObject(root) ? { ...root } : {};
   const modelProfiles = isPlainObject(writableRoot.model_profiles) ? { ...writableRoot.model_profiles } : {};
@@ -235,7 +241,11 @@ export function resetGlobalSubagentModelProfileField(input: { agentName: string;
   fs.writeFileSync(file, `${JSON.stringify(writableRoot, null, 2)}\n`, 'utf8');
 }
 
-function loadSubagentsFromDir(dir: string): SubagentDefinition[] {
+export function resetGlobalSubagentModelProfileField(input: { agentName: string; field: 'model' | 'effort'; agentDir?: string }): void {
+  resetSubagentModelProfileField({ ...input, scope: 'global' });
+}
+
+function loadSubagentsFromDir(dir: string, scope: SubagentDefinitionScope): SubagentDefinition[] {
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir)
     .filter((f) => f.endsWith('.md'))
@@ -246,14 +256,43 @@ function loadSubagentsFromDir(dir: string): SubagentDefinition[] {
       const name = String(data.name || path.basename(file, '.md')).trim().toLowerCase();
       const description = String(data.description || `${name} subagent`).trim();
       const tools = sanitizeTools(Array.isArray(data.tools) ? data.tools.map(String) : DEFAULT_TOOLS);
-      return { name, description, filePath, instructions: body.trim(), model: parseModel(data.model), effort: parseEffort(data.effort ?? data.thinking_level ?? data.thinkingLevel), tools };
+      return { name, description, filePath, instructions: body.trim(), model: parseModel(data.model), effort: parseEffort(data.effort ?? data.thinking_level ?? data.thinkingLevel), tools, scope };
     });
 }
 
+function agentsDirSources(cwd: string): Array<{ scope: 'global' | 'project'; kind: 'agents' | 'subagents'; dir: string }> {
+  const globalAgentDir = agentDir();
+  return [
+    { scope: 'global', kind: 'agents', dir: path.join(globalAgentDir, 'agents') },
+    { scope: 'global', kind: 'subagents', dir: path.join(globalAgentDir, 'subagents') },
+    { scope: 'project', kind: 'agents', dir: path.join(cwd, '.pi', 'agents') },
+    { scope: 'project', kind: 'subagents', dir: path.join(cwd, '.pi', 'subagents') },
+  ];
+}
+
+export function subagentSourceWarnings(cwd: string): string[] {
+  const warnings: string[] = [];
+  for (const scope of ['global', 'project'] as const) {
+    const sources = agentsDirSources(cwd).filter((source) => source.scope === scope);
+    const agentsSource = sources.find((source) => source.kind === 'agents')!;
+    const subagentsSource = sources.find((source) => source.kind === 'subagents')!;
+    const agents = loadSubagentsFromDir(agentsSource.dir, agentsSource.scope);
+    const subagents = loadSubagentsFromDir(subagentsSource.dir, subagentsSource.scope);
+    const subagentNames = new Map(subagents.map((definition) => [definition.name, definition]));
+    for (const agent of agents) {
+      const subagent = subagentNames.get(agent.name);
+      if (!subagent) continue;
+      warnings.push(`Duplicate subagent name "${agent.name}" found in ${scope} agents and subagents directories; using subagents definition (${subagent.filePath}).`);
+    }
+  }
+  return warnings;
+}
+
 export function loadSubagents(cwd: string): SubagentDefinition[] {
   const byName = new Map<string, SubagentDefinition>();
-  for (const agent of loadSubagentsFromDir(path.join(agentDir(), 'subagents'))) byName.set(agent.name, agent);
-  for (const agent of loadSubagentsFromDir(path.join(cwd, '.pi', 'subagents'))) byName.set(agent.name, agent);
+  for (const source of agentsDirSources(cwd)) {
+    for (const agent of loadSubagentsFromDir(source.dir, source.scope)) byName.set(agent.name, agent);
+  }
   return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 

package/src/model-profiles-ui.ts

@@ -1,8 +1,8 @@
 import os from 'node:os';
 import path from 'node:path';
-import { loadSubagents, readSubagentsConfig, resetGlobalSubagentModelProfileField, saveGlobalSubagentModelProfile } from './config.js';
+import { loadSubagents, readSubagentsConfig, resetSubagentModelProfileField, saveSubagentModelProfile } from './config.js';
 import { resolveEffectiveSubagentProfile } from './profile-resolver.js';
-import type { ModelRef, SubagentDefinition, SubagentModelProfile, SubagentModelProfiles, SubagentsConfig, ThinkingEffort } from './types.js';
+import type { ModelRef, SubagentDefinition, SubagentDefinitionScope, SubagentModelProfile, SubagentModelProfiles, SubagentsConfig, ThinkingEffort } from './types.js';
 
 export const KNOWN_SDD_PHASES = [
   'sdd-explore',
@@ -28,12 +28,17 @@ export type ModelProfileRow = {
   effectiveModel?: ModelRef;
   effectiveEffort?: ThinkingEffort;
   explicitProfile: SubagentModelProfile;
+  scope?: SubagentDefinitionScope;
 };
 
 export function globalSubagentsConfigPath(agentDir = path.join(os.homedir(), '.pi', 'agent')): string {
   return path.join(agentDir, 'subagents.json');
 }
 
+export function projectSubagentsConfigPath(cwd: string): string {
+  return path.join(cwd, '.pi', 'subagents.json');
+}
+
 function modelKey(model: ModelRef): string {
   return `${model.provider}/${model.id}`;
 }
@@ -101,7 +106,8 @@ export function buildModelProfileRows(input: {
         effortLabel: resolved.effort.label,
         effectiveModel: resolved.model.value,
         effectiveEffort: resolved.effort.value,
-        explicitProfile: { ...(input.config.model_profiles[definition.name] ?? {}) },
+        explicitProfile: { ...((definition.scope === 'project' ? input.config.project_model_profiles?.[definition.name] : input.config.global_model_profiles?.[definition.name]) ?? {}) },
+        scope: definition.scope ?? 'global',
       };
     });
 }
@@ -156,16 +162,25 @@ export function applyDirtyProfileEdit(input: {
   return nextDirtyProfiles;
 }
 
-export function commitStagedModelProfiles(input: { stagedProfiles: SubagentModelProfiles; save: boolean; agentDir?: string }): string {
-  if (!input.save) return `Cancelled. No changes written to ${globalSubagentsConfigPath(input.agentDir)}.`;
+export function commitStagedModelProfiles(input: { stagedProfiles: SubagentModelProfiles; save: boolean; agentDir?: string; cwd?: string; profileScopes?: Record<string, SubagentDefinitionScope> }): string {
+  const globalPath = globalSubagentsConfigPath(input.agentDir);
+  const projectPath = input.cwd ? projectSubagentsConfigPath(input.cwd) : undefined;
+  if (!input.save) return `Cancelled. No changes written to ${globalPath}.`;
+  const touched = new Set<string>();
   for (const [agentName, profile] of Object.entries(input.stagedProfiles)) {
-    if (profile.model || profile.effort) saveGlobalSubagentModelProfile({ agentName, profile, agentDir: input.agentDir });
+    const scope = input.profileScopes?.[agentName.trim().toLowerCase()] ?? 'global';
+    const target = scope === 'project' && input.cwd ? projectPath! : globalPath;
+    touched.add(target);
+    if (profile.model || profile.effort) saveSubagentModelProfile({ agentName, profile, scope, cwd: input.cwd, agentDir: input.agentDir });
     else {
-      resetGlobalSubagentModelProfileField({ agentName, field: 'model', agentDir: input.agentDir });
-      resetGlobalSubagentModelProfileField({ agentName, field: 'effort', agentDir: input.agentDir });
+      resetSubagentModelProfileField({ agentName, field: 'model', scope, cwd: input.cwd, agentDir: input.agentDir });
+      resetSubagentModelProfileField({ agentName, field: 'effort', scope, cwd: input.cwd, agentDir: input.agentDir });
     }
   }
-  return `Saved subagent model profiles to ${globalSubagentsConfigPath(input.agentDir)}.`;
+  const targets = [...touched];
+  return targets.length > 1
+    ? `Saved subagent model profiles to ${targets.join(' and ')}.`
+    : `Saved subagent model profiles to ${targets[0] ?? globalPath}.`;
 }
 
 export function buildNoChangesModelProfilesMessage(agentDir?: string): string {
@@ -188,6 +203,7 @@ type ModalInput = {
   rows: ModelProfileRow[];
   availableModels?: any[];
   tui?: { requestRender?: () => void };
+  theme?: any;
   done: (result: SubagentModelProfilesModalResult) => void;
 };
 
@@ -322,6 +338,9 @@ export function createSubagentModelProfilesModal(input: ModalInput): ModalCompon
   };
 
   const rowKey = (row: ModelProfileRow): string => row.name.trim().toLowerCase();
+  const rowScope = (row: ModelProfileRow): SubagentDefinitionScope => row.scope ?? 'global';
+  const dim = (text: string): string => input.theme?.fg?.('dim', text) ?? text;
+  const scopedName = (row: ModelProfileRow): string => `${row.name} ${dim(rowScope(row) === 'project' ? '(local)' : '(global)')}`;
   const hasDirtyProfileFor = (row: ModelProfileRow): boolean => Object.prototype.hasOwnProperty.call(dirtyProfiles, rowKey(row));
   const dirtyProfileFor = (row: ModelProfileRow): SubagentModelProfile | undefined => dirtyProfiles[rowKey(row)];
 
@@ -351,16 +370,16 @@ export function createSubagentModelProfilesModal(input: ModalInput): ModalCompon
   const rowListLines = (width: number): string[] => {
     const innerWidth = Math.max(1, Math.floor(width || 1) - 2);
     const visibleRows = rows.slice(scrollOffset, scrollOffset + 10);
-    if (innerWidth >= 92) {
-      const nameWidth = 24;
-      const effortWidth = 22;
-      const modelWidth = Math.max(18, innerWidth - nameWidth - effortWidth - 6);
+    if (innerWidth >= 100) {
+      const nameWidth = 32;
+      const effortWidth = 24;
+      const modelWidth = Math.max(24, innerWidth - nameWidth - effortWidth - 6);
       const lines = [`${padToVisibleWidth('agent/phase', nameWidth)}  ${padToVisibleWidth('model', modelWidth)}  ${padToVisibleWidth('effort', effortWidth)}`];
       for (const [offset, item] of visibleRows.entries()) {
         const index = scrollOffset + offset;
         const marker = index === selectedIndex ? '›' : ' ';
         const dirty = hasDirtyProfileFor(item) ? '*' : ' ';
-        lines.push(`${marker} ${dirty} ${padToVisibleWidth(item.name, nameWidth - 4)}  ${padToVisibleWidth(rowModelText(item), modelWidth)}  ${padToVisibleWidth(rowEffortText(item), effortWidth)}`);
+        lines.push(`${marker} ${dirty} ${padToVisibleWidth(scopedName(item), nameWidth - 4)}  ${padToVisibleWidth(rowModelText(item), modelWidth)}  ${padToVisibleWidth(rowEffortText(item), effortWidth)}`);
       }
       return lines;
     }
@@ -369,7 +388,7 @@ export function createSubagentModelProfilesModal(input: ModalInput): ModalCompon
       const index = scrollOffset + offset;
       const marker = index === selectedIndex ? '›' : ' ';
       const dirty = hasDirtyProfileFor(item) ? '*' : ' ';
-      lines.push(`${marker} ${dirty} ${item.name} · ${rowModelText(item)} · ${rowEffortText(item)}`);
+      lines.push(`${marker} ${dirty} ${scopedName(item)} · ${rowModelText(item)} · ${rowEffortText(item)}`);
     }
     return lines;
   };
@@ -377,7 +396,7 @@ export function createSubagentModelProfilesModal(input: ModalInput): ModalCompon
   const renderMain = (width: number): string[] => {
     const dirtyCount = Object.keys(dirtyProfiles).length;
     const body = [
-      `target: global · ${pendingLabel(dirtyCount)}`,
+      `target: local/global by subagent scope · ${pendingLabel(dirtyCount)}`,
       '↑/↓/j/k move · enter/m model · e effort · M/E/r reset · s save · esc/q cancel',
       '',
       ...rowListLines(width),
@@ -513,7 +532,8 @@ export function buildNonTuiModelProfilesMessage(agentDir?: string): string {
 }
 
 function rowChoice(row: ModelProfileRow): string {
-  return `${row.name} — model ${row.modelLabel}; effort ${row.effortLabel}`;
+  const scope = row.scope === 'project' ? 'local' : 'global';
+  return `${row.name} (${scope}) — model ${row.modelLabel}; effort ${row.effortLabel}`;
 }
 
 async function getAvailableModels(ctx: any): Promise<any[]> {
@@ -525,9 +545,9 @@ async function getAvailableModels(ctx: any): Promise<any[]> {
   }
 }
 
-async function chooseSave(ctx: any, stagedProfiles: SubagentModelProfiles, agentDir?: string): Promise<string> {
+async function chooseSave(ctx: any, stagedProfiles: SubagentModelProfiles, input: { agentDir?: string; cwd?: string; profileScopes?: Record<string, SubagentDefinitionScope> } = {}): Promise<string> {
   const decision = await ctx.ui.select('Save subagent model profile changes?', ['Save', 'Cancel']);
-  const message = commitStagedModelProfiles({ stagedProfiles, save: decision === 'Save', agentDir });
+  const message = commitStagedModelProfiles({ stagedProfiles, save: decision === 'Save', agentDir: input.agentDir, cwd: input.cwd, profileScopes: input.profileScopes });
   ctx.ui.notify?.(message, decision === 'Save' ? 'info' : 'warning');
   return message;
 }
@@ -543,22 +563,24 @@ export async function runSubagentModelsCommand(ctx: any = {}): Promise<string> {
   const config = readSubagentsConfig(cwd);
   const availableModels = await getAvailableModels(ctx);
   const rows = buildModelProfileRows({ definitions, config, ctx, availableModels });
+  const profileScopes: Record<string, SubagentDefinitionScope> = Object.fromEntries(rows.map((row) => [row.name.trim().toLowerCase(), row.scope ?? 'global']));
 
   if (hasCustomUi) {
     const result = await ctx.ui.custom(
-      (tui: any, _theme: any, _keybindings: any, done: (result: SubagentModelProfilesModalResult) => void) => createSubagentModelProfilesModal({
+      (tui: any, theme: any, _keybindings: any, done: (result: SubagentModelProfilesModalResult) => void) => createSubagentModelProfilesModal({
         rows,
         availableModels,
         tui,
+        theme,
         done,
       }),
-      { overlay: true, overlayOptions: { anchor: 'center', width: '90%', maxHeight: '85%', minWidth: 74 } },
+      { overlay: true, overlayOptions: { anchor: 'center', width: '96%', maxHeight: '90%', minWidth: 96 } },
     ) as SubagentModelProfilesModalResult | undefined;
 
     if (result?.action === 'save') {
       const hasDirtyRows = Object.keys(result.dirtyProfiles).length > 0;
       const message = hasDirtyRows
-        ? commitStagedModelProfiles({ stagedProfiles: result.dirtyProfiles, save: true, agentDir })
+        ? commitStagedModelProfiles({ stagedProfiles: result.dirtyProfiles, save: true, agentDir, cwd, profileScopes })
         : buildNoChangesModelProfilesMessage(agentDir);
       ctx.ui.notify?.(message, 'info');
       return message;
@@ -605,5 +627,5 @@ export async function runSubagentModelsCommand(ctx: any = {}): Promise<string> {
     else staged = stageModelProfileEdit(staged, { agentName: row.name, effort });
   }
 
-  return chooseSave(ctx, staged, agentDir);
+  return chooseSave(ctx, staged, { agentDir, cwd, profileScopes });
 }

package/src/profile-resolver.ts

@@ -25,8 +25,13 @@ function field<T>(source: ProfileValueSource, value: T | undefined, format: (val
   return { value, source, label: profileSourceLabel(source, value, format) };
 }
 
+function profileForDefinition(definition: SubagentDefinition, config: SubagentsConfig) {
+  if (definition.scope === 'project') return config.project_model_profiles?.[definition.name] ?? (config.project_model_profiles ? undefined : config.model_profiles[definition.name]);
+  return config.global_model_profiles?.[definition.name] ?? (config.global_model_profiles ? undefined : config.model_profiles[definition.name]);
+}
+
 function resolveModel(definition: SubagentDefinition, config: SubagentsConfig, ctx: any): ResolvedProfileField<ModelRef> {
-  const profile = config.model_profiles[definition.name];
+  const profile = profileForDefinition(definition, config);
   if (profile?.model) return field('profile', profile.model, modelLabel);
   if (definition.model) return field('definition', definition.model, modelLabel);
   if (config.default_model) return field('default', config.default_model, modelLabel);
@@ -36,7 +41,7 @@ function resolveModel(definition: SubagentDefinition, config: SubagentsConfig, c
 }
 
 function resolveEffort(definition: SubagentDefinition, config: SubagentsConfig, ctx: any): ResolvedProfileField<ThinkingEffort> {
-  const profile = config.model_profiles[definition.name];
+  const profile = profileForDefinition(definition, config);
   if (profile?.effort) return field('profile', profile.effort, String);
   if (definition.effort) return field('definition', definition.effort, String);
   if (config.default_effort) return field('default', config.default_effort, String);

package/src/tools.ts

@@ -299,7 +299,7 @@ export function registerSubagentTools(pi: any, manager: SubagentManager): void {
     name: 'subagent_list_agents',
     label: 'Subagent List Agents',
     description: 'List available markdown-defined subagents for delegation.',
-    promptSnippet: 'List available subagents loaded from .pi/subagents/*.md.',
+    promptSnippet: 'List available subagents loaded from global/project agents and subagents markdown directories.',
     parameters: Type.Object({}),
     async execute(_id: string, _params: any, _signal: any, _onUpdate: any, ctx: any) {
       try { const agents = manager.listAgents(ctx?.cwd ?? process.cwd()); return ok(`Found ${agents.length} subagent(s).`, { agents }); } catch (e) { return fail(e); }

package/src/types.ts

@@ -12,6 +12,7 @@ export type SubagentModelProfile = {
 };
 
 export type SubagentModelProfiles = Record<string, SubagentModelProfile>;
+export type SubagentDefinitionScope = 'global' | 'project';
 
 export type ProfileValueSource = 'profile' | 'definition' | 'default' | 'orchestrator' | 'unresolved';
 
@@ -35,6 +36,7 @@ export type SubagentDefinition = {
   model?: ModelRef;
   effort?: ThinkingEffort;
   tools: string[];
+  scope?: SubagentDefinitionScope;
 };
 
 export type SubagentSessionResources = 'full' | 'lean';
@@ -44,6 +46,8 @@ export type SubagentsConfig = {
   default_model?: ModelRef;
   default_effort?: ThinkingEffort;
   model_profiles: SubagentModelProfiles;
+  global_model_profiles?: SubagentModelProfiles;
+  project_model_profiles?: SubagentModelProfiles;
   timeout_ms: number;
   stall_timeout_ms: number;
   max_concurrency: number;

package/src/ui.ts

@@ -214,15 +214,37 @@ export class SubagentsHistoryPanel {
 
   private taskStrip(width: number): string {
     const tasks = this.tasks();
-    const max = Math.max(1, Math.min(tasks.length, 8));
-    const start = Math.min(Math.max(0, this.selected - Math.floor(max / 2)), Math.max(0, tasks.length - max));
-    const chips: string[] = [];
-    for (let i = start; i < Math.min(tasks.length, start + max); i++) {
-      const task = tasks[i]!;
-      const label = `${i === this.selected ? '●' : '○'} ${task.agent}:${task.status}${task.effort ? ` effort:${task.effort}` : ''}`;
-      chips.push(i === this.selected ? (this.theme?.fg?.('accent', label) ?? label) : (this.theme?.fg?.('dim', label) ?? label));
+    const dim = (s: string) => this.theme?.fg?.('dim', s) ?? s;
+    const selected = (s: string) => this.theme?.fg?.('warning', s) ?? s;
+    const chip = (index: number): { raw: string; styled: string } => {
+      const task = tasks[index]!;
+      const raw = `${index === this.selected ? '●' : '○'} ${task.agent}:${task.status}${task.effort ? ` effort:${task.effort}` : ''}`;
+      return { raw, styled: index === this.selected ? selected(raw) : dim(raw) };
+    };
+    const selectedChip = chip(this.selected);
+    let start = this.selected;
+    let end = this.selected + 1;
+    let raw = selectedChip.raw;
+    while (start > 0 || end < tasks.length) {
+      const preferLeft = this.selected - start <= end - this.selected - 1;
+      const nextIndex = preferLeft && start > 0 ? start - 1 : end < tasks.length ? end : start > 0 ? start - 1 : -1;
+      if (nextIndex < 0) break;
+      const next = chip(nextIndex).raw;
+      const candidate = nextIndex < start ? `${next}  ${raw}` : `${raw}  ${next}`;
+      const prefix = `executions ${Math.min(start, nextIndex) + 1}-${Math.max(end, nextIndex + 1)}/${tasks.length}  `;
+      const leftIndicator = Math.min(start, nextIndex) > 0 ? '‹ ' : '';
+      const rightIndicator = Math.max(end, nextIndex + 1) < tasks.length ? ' ›' : '';
+      if (this.visibleWidth(`${prefix}${leftIndicator}${candidate}${rightIndicator}`) > width) break;
+      raw = candidate;
+      start = Math.min(start, nextIndex);
+      end = Math.max(end, nextIndex + 1);
     }
-    return this.truncateToWidth(chips.join('  '), width);
+    const styledChips: string[] = [];
+    for (let i = start; i < end; i++) styledChips.push(chip(i).styled);
+    const prefix = dim(`executions ${start + 1}-${end}/${tasks.length}`);
+    const leftIndicator = start > 0 ? `${dim('‹')} ` : '';
+    const rightIndicator = end < tasks.length ? ` ${dim('›')}` : '';
+    return `${prefix}  ${leftIndicator}${styledChips.join('  ')}${rightIndicator}`;
   }
 
   private tasks(): SubagentTask[] {