@preapexis/piexis 0.2.8 → 0.2.9

package/README.md

@@ -13,7 +13,7 @@ Restart Pi or run `/reload` after installation. The package loads AskQuestion, a
 ## Resources
 
 - **AskQuestion** provides keyboard-driven single/multi selection and text questions in the interactive TUI, with validation, answer review, and cancellation. It requires terminal input and output.
-- **UI** shows project information, agent activity, Git branch, model, and context usage. The startup header shows three random, category-labelled tips from `lib/ui-tips.json`, preferring different categories and staying stable across redraws. Tips cycle without repeats until the list is exhausted within the extension runtime; `/reload` starts a new cycle. Each JSON entry has `category` and `text` fields; edit them to change the recommendations.
+- **UI** shows project information, agent activity, Git branch, model, and context usage. When automatic profile routing is enabled, the footer shows `agent:<profile> (auto)` (or `(manual)` for a pinned profile) where space permits; narrow layouts retain the profile first. The startup header shows three random, category-labelled tips from `lib/ui-tips.json`, preferring different categories and staying stable across redraws. Tips cycle without repeats until the list is exhausted within the extension runtime; `/reload` starts a new cycle. Each JSON entry has `category` and `text` fields; edit them to change the recommendations.
 - **Recommended tools** offers to enable native `grep`, `find`, and `ls` for the project at startup; no slash command is needed.
 - **Agents** provides `plan`, `orchestrator`, `debug`, `ask`, and `code` profiles, all callable through the `subagent` tool. Small delegated tasks can automatically use a cheaper model.
 - **Skills** cover implementation, debugging, review, design, refactoring, validation, and document workflows. Bundled **caveman** adds concise chat style; **ponytail** guides the smallest complete coding change. Only their core instructions are included, not upstream hooks or companion skills. Source revisions and licenses live beside each skill.
@@ -46,7 +46,7 @@ The setup extension is `extensions/recommended-tools.ts`; package resource filte
 
 ## Agents and subagents
 
-Use `/profile` to select a profile, `/profile plan` to switch directly, or `pi --agent orchestrator` at startup. **Alt+A** cycles `plan → orchestrator → debug → ask → code` while idle; cycling is blocked while an agent is running. The footer shows the active profile (`agent:code`) and, on wider terminals, the shortcut hint. `/hotkeys` lists the shortcut. `code` is the default. Profile choices follow the active session branch. Profiles add instructions rather than replacing repository guidance or changing the main session's tools:
+Use `/profile` to select a profile or `auto` to resume automatic routing, `/profile plan` to switch directly, or `pi --agent orchestrator` at startup. **Alt+A** cycles `plan → orchestrator → debug → ask → code` while idle; cycling is blocked while an agent is running. The footer shows the active profile (`agent:code`) and, on wider terminals, its automatic/manual routing mode and the shortcut hint. `/hotkeys` lists the shortcut. `code` is the default. Profile choices follow the active session branch. Profiles add instructions rather than replacing repository guidance or changing the main session's tools:
 
 | Profile | Purpose |
 | --- | --- |
@@ -56,9 +56,23 @@ Use `/profile` to select a profile, `/profile plan` to switch directly, or `pi -
 | `ask` | Answer questions from code/documentation; no changes |
 | `code` | Implement scoped changes and run checks |
 
-All five are callable with `subagent({ "agent": "ask", "task": "Locate the configuration loader" })`. The orchestrator chooses when to delegate; delegation is not an automatic pipeline. Each child receives its task, normal Pi resources, and profile instructions, **not** the parent's conversation. Supply necessary context explicitly. Children share the workspace, so calls are sequential; delegation stops at two child levels. A delegated orchestrator can call other subagents at the second level.
+With `auto_profile: true`, Piexis checks each eligible new request using conservative English leading-action rules:
 
-Optional configuration lives in `~/.pi/agent/agent.json` (or `$PI_CODING_AGENT_DIR/agent.json`) and trusted-project `.pi/agent.json`. Legacy `agents.json` is still read when `agent.json` is absent in that scope; no files are renamed or deleted. Project fields override user fields; per-variant overrides merge by field. Accepting **Enable** during project setup creates the project scaffold only when no project agent configuration exists; user-level files are never written. Defaults use the current model unless user-level configuration specifies another model. New scaffolds set `delegate_exploration` to `false`; edit it to opt in. `/setup-agents` creates a missing project config or fills only its missing settings with defaults, preserving every configured value. It uses the active model when it must choose a model. Generated files include `$schema` for editor validation; configuration reloads on each profile switch and delegation. Use exact `provider/model-id` strings from `/model`, not fuzzy aliases:
+| Clear request wording | Profile |
+| --- | --- |
+| Plan / make a plan | `plan` |
+| Debug / investigate / fix this bug | `debug` |
+| Explain / answer / what or how question | `ask` |
+| Orchestrate / coordinate / delegate tasks | `orchestrator` |
+| Implement / build / write / **Execute** | `code` |
+
+All five are callable with `subagent({ "agent": "ask", "task": "Locate the configuration loader" })`. The orchestrator chooses when to delegate; delegation is not an automatic pipeline. Each child receives its task, normal Pi resources, and profile instructions, **not** the parent's conversation. Supply necessary context explicitly. Children share the workspace. Only an `orchestrator` parent can run up to **two** independent jobs concurrently; other profiles remain sequential. Delegation stops at two child levels, and nested writes must remain within the inherited parent scope. A delegated orchestrator can call other subagents at the second level.
+
+Declare ownership with `subagent({ "agent": "code", "mode": "write", "paths": ["lib/example.ts", "tests/example.test.mjs"], "task": "..." })`. File/directory overlaps serialize writes. Missing or empty write paths, repository-root ownership, and shared configuration (`package.json`, lockfiles, `tsconfig*.json`, `.pi/`, `.git/`, `.github/`, and common root tool configs) reserve broad write ownership and serialize with all writes. Paths are normalized repository-relative paths; absolute, escaping, and symlinked write paths are rejected. `mode: "read"` selects only read tools and reserves no paths. `plan`, `ask`, and `purpose: "explore"` are always read-only. Read jobs can run beside writes, subject to capacity and parent-profile policy; their observations are not snapshot-isolated. Results/progress include mode, normalized paths, queue reason, and status.
+
+Scopes are cooperative ownership declarations, **not sandboxing**. Do not write outside them or edit the parent workspace while write children are running. No output is automatically merged or reverted. Pi's global sequential setting, or a sequential tool in the same batch, can still serialize calls. Concurrency is fixed at two per parent scheduler; no new `agent.json` setting is required.
+
+Optional configuration lives in `~/.pi/agent/agent.json` (or `$PI_CODING_AGENT_DIR/agent.json`) and trusted-project `.pi/agent.json`. Legacy `agents.json` is still read when `agent.json` is absent in that scope; no files are renamed or deleted. Project fields override user fields; per-variant overrides merge by field. Accepting **Enable** during project setup creates the project scaffold only when no project agent configuration exists; user-level files are never written. Defaults use the current model unless user-level configuration specifies another model. New scaffolds set `delegate_exploration` and `auto_profile` to `false`; inherited user values are preserved unless a trusted project explicitly supplies its own value. `/setup-agents` creates a missing project config or fills only its missing settings with defaults, preserving every configured value. It uses the active model when it must choose a model. Generated files include `$schema` for editor validation; configuration reloads on each profile switch and delegation. Use exact `provider/model-id` strings from `/model`, not fuzzy aliases:
 
 ```json
 {
@@ -67,6 +81,7 @@ Optional configuration lives in `~/.pi/agent/agent.json` (or `$PI_CODING_AGENT_D
   "small_model": "provider/default-model",
   "subagent_model": "provider/default-model",
   "delegate_exploration": true,
+  "auto_profile": false,
   "subagent_variant_overrides": {
     "plan": { "model": "provider/default-model", "effort": "high" },
     "orchestrator": { "model": "provider/default-model", "effort": "high" },
@@ -77,6 +92,10 @@ Optional configuration lives in `~/.pi/agent/agent.json` (or `$PI_CODING_AGENT_D
 }
 ```
 
+`auto_profile` defaults to `false`; set it to `true` in user configuration or a trusted project configuration to switch profiles for each clear English request without confirmation. Unmatched or ambiguous wording keeps the current profile; `Execute` alone selects `code` and uses the existing conversation as context. The outer request wins: “Explain how to implement login” selects `ask`, not `code`; quoted/code mentions and negations do not trigger the mentioned action. `/profile`, **Alt+A**, and `--agent` pin manual selection on the current branch; `/profile auto` releases the pin without changing the current profile or model, so the next clear request can route again.
+
+Only idle main-session user input is eligible. Queued steering/follow-up messages, slash commands, extension-originated input, and delegated agents do not auto-route. A failed automatic activation does not submit the request; correct the configuration or model and retry. These conservative rules use no classifier/model call, new keyboard shortcut, automatic pipeline/plan handoff, or tool-access/sandboxing changes. Non-TUI clients receive supported status/notifications; Piexis does not add a browser-specific badge.
+
 **Alt+A** and `/profile` apply the selected profile's `model` and `effort` from `subagent_variant_overrides` to the main session too. Without a profile model override, switching uses the top-level `model` if configured; otherwise it keeps the current model. Missing effort overrides leave the current thinking level alone (subject to Pi's model-capability clamping). `subagent_model` and `small_model` remain delegation-only settings. Invalid configuration or an unavailable model leaves the current profile unchanged and shows a warning.
 
 Replace the example model IDs with available, authenticated models. `model` initializes a new main session; explicit CLI model selections and resumed sessions win at startup. An explicit profile switch subsequently applies the configured settings. `subagent_model` defaults to the current main-session model. A per-variant `model` wins over all automatic routing. New scaffolds explicitly pin each variant to the default subagent model; remove the `model` field from a variant's override to let it follow automatic routing or later `subagent_model` changes. Otherwise, short lookups/summaries in `ask` and clearly mechanical typo/comment/label/symbol edits in `code` use `small_model` when configured. Ambiguous, longer, or complex tasks, including planning, debugging, and orchestration, keep the normal subagent model. This is a conservative text heuristic, not a classifier or a guarantee of task difficulty. Omit `small_model` to disable automatic small-task routing.
@@ -87,7 +106,7 @@ Effort accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Var
 
 Child agents run in separate Pi processes with ephemeral sessions and the same OS permissions. Their tool selection is a subset of the parent's active tools; `plan`/`ask` children select only `read`, `grep`, `find`, and `ls`, and disable native MCP access. With `delegate_exploration`, a non-exploration `plan` or `ask` child may also receive `subagent` to perform one nested exploration; exploration children never receive it. `plan`/`ask` parents may delegate only to those two profiles. Other children omit `AskQuestion` and return questions to the parent. Main profile instructions and child tool selection are **not sandboxing**. Normal configured extensions and explicitly supplied CLI extensions load in children, with the parent's project-trust decision. Runtime-only provider/tool registrations, CLI `--api-key` overrides, credentials supplied only to an embedded SDK session, and in-memory state in other extensions are not copied to child processes. Use Pi's stored or environment-based authentication for delegation. Other extensions remain responsible for their own restrictions; verify their subprocess behavior before using delegation in a restricted host.
 
-Abort and shutdown terminate active children (including their process group on Unix). Windows termination is best-effort for descendants. Model-facing output is capped at 50,000 characters; tool details retain up to 1 MB. JSON/print mode supports subagents but has no profile picker or child terminal interaction. Avoid loading another extension that registers `subagent`, `/profile`, `/setup-agents`, or `--agent` alongside this one.
+Abort removes queued work without spawning a child and terminates active children (including their process group on Unix). Profile switching is blocked during preparation, queued work, and active work. Shutdown cancels all queued/active jobs and waits for active children to settle. Windows termination is best-effort for descendants. Model-facing output is capped at 50,000 characters; tool details retain up to 1 MB. JSON/print mode supports subagents but has no profile picker or child terminal interaction. Avoid loading another extension that registers `subagent`, `/profile`, `/setup-agents`, or `--agent` alongside this one.
 
 ## AskQuestion
 

package/extensions/agents.ts

@@ -5,81 +5,153 @@ import { Key } from "@earendil-works/pi-tui";
 import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as piSdk from "@earendil-works/pi-coding-agent";
 import {
-  agentNames, childResourceArgs, completeProjectAgentConfig, isAgentName, loadAgentConfig, profiles, routeSubagent, subagentTools,
-  type AgentName, type Effort,
+  agentNames, childResourceArgs, completeProjectAgentConfig, detectProfileIntent, isAgentName, loadAgentConfig, profiles, routeSubagent, subagentTools,
+  type AgentConfig, type AgentName, type Effort,
 } from "../lib/agents.ts";
 import { limitOutput, piInvocation, runSubagent } from "../lib/subagent-runner.ts";
+import { normalizeSubagentScope, SubagentScheduler, type SchedulerStatus } from "../lib/subagent-scheduler.ts";
 
 const AgentSchema = Type.Union(agentNames.map((name) => Type.Literal(name)));
 const parameters = Type.Object({
   agent: AgentSchema,
   purpose: Type.Optional(Type.Literal("explore", { description: "Use the configured small_model for read-only codebase exploration; available only for ask when delegate_exploration is enabled." })),
+  mode: Type.Optional(Type.Union([Type.Literal("read"), Type.Literal("write")], { description: "Declared work mode. Defaults to write, except read-only plan/ask and exploration. Read mode selects only read tools." })),
+  paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Repository-relative files or directories the task may modify. Missing paths mean broad write ownership. Overlaps and shared configuration serialize writes." })),
   task: Type.String({ minLength: 1, maxLength: 50_000, description: "Self-contained task including needed context; conversation history is not inherited." }),
 });
 const stateType = "piexis-agent";
+const profileChoices = [...agentNames, "auto"];
 
 export default function agentsExtension(pi: ExtensionAPI) {
   let active: AgentName = "code";
+  let pinned = false;
+  let activationOrigin: "manual" | "automatic" | undefined;
+  let autoProfileEnabled = false;
   let explorationEnabled = false;
   let switching = false;
+  let startupHandled = false;
   const depthText = process.env.PIEXIS_SUBAGENT_DEPTH ?? "0";
   const depth = /^[0-2]$/.test(depthText) ? Number(depthText) : 2;
   const jobs = new Map<AbortController, Promise<unknown>>();
+  let scheduler = new SubagentScheduler();
+  const childStatuses = new Map<AbortController, { agent: AgentName; status: "queued" | "running" }>();
+
+  function childStatus(ctx: ExtensionContext) {
+    if (!ctx.hasUI) return;
+    const groups = (["running", "queued"] as const).map((state) => {
+      const names = [...childStatuses.values()].filter((job) => job.status === state).map((job) => job.agent);
+      return names.length ? `${names.length} ${state}: ${names.join(", ")}` : "";
+    }).filter(Boolean);
+    ctx.ui.setStatus("piexis-subagents", groups.length ? `subagents · ${groups.join(" · ")}` : undefined);
+  }
+  const inheritedScope = process.env.PIEXIS_SUBAGENT_SCOPE ? JSON.parse(process.env.PIEXIS_SUBAGENT_SCOPE) : undefined;
   const extensionPath = fileURLToPath(import.meta.url);
 
   pi.registerFlag("agent", { description: `Agent profile: ${agentNames.join(", ")}`, type: "string" });
 
   function status(ctx: ExtensionContext) {
-    if (ctx.hasUI) ctx.ui.setStatus("piexis-agent", `agent:${active}`);
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus("piexis-agent", `agent:${active}`);
+    ctx.ui.setStatus("piexis-agent-mode", autoProfileEnabled ? (pinned ? "manual" : "auto") : "");
+  }
+
+  function persist() {
+    pi.appendEntry(stateType, { agent: active, origin: activationOrigin, pinned });
   }
 
-  async function activate(name: AgentName, ctx: ExtensionContext) {
-    if (switching || !ctx.isIdle() || jobs.size > 0) {
+  function canSwitch(ctx: ExtensionContext) {
+    return !switching && ctx.isIdle() && jobs.size === 0;
+  }
+
+  async function activate(name: AgentName, ctx: ExtensionContext, origin: "manual" | "automatic", config?: AgentConfig): Promise<boolean> {
+    if (!canSwitch(ctx)) {
       ctx.ui.notify("Wait for the current agent to finish before switching profiles.", "warning");
-      return;
+      return false;
     }
     switching = true;
+    const previousModel = ctx.model;
+    const previousEffort = (ctx.thinkingLevel ?? pi.getThinkingLevel()) as Effort;
+    const previousState = { active, activationOrigin, pinned };
+    let modelChanged = false;
+    let effortChanged = false;
     try {
-      const config = await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted());
+      config ??= await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted());
       const override = config.subagent_variant_overrides?.[name];
       const modelId = override?.model ?? config.model;
       if (modelId) {
         const slash = modelId.indexOf("/");
         const model = ctx.modelRegistry.find(modelId.slice(0, slash), modelId.slice(slash + 1));
         if (!model || !(await pi.setModel(model))) throw new Error(`Configured model unavailable: ${modelId}. Check /model and /login.`);
+        modelChanged = true;
       }
-      if (override?.effort !== undefined) pi.setThinkingLevel(override.effort);
+      if (override?.effort !== undefined) { effortChanged = true; pi.setThinkingLevel(override.effort); }
       active = name;
-      pi.appendEntry(stateType, { agent: active });
+      activationOrigin = origin;
+      pinned = origin === "manual";
+      persist();
+      autoProfileEnabled = config.auto_profile === true;
       status(ctx);
-      ctx.ui.notify(`Agent: ${active}`, "info");
+      if (origin === "manual" || name !== previousState.active) {
+        ctx.ui.notify(`Agent: ${active}${origin === "automatic" ? " (automatic)" : ""}`, "info");
+      }
+      return true;
     } catch (error) {
+      // setModel can succeed before a later setting throws; keep a failed route atomic.
+      active = previousState.active;
+      activationOrigin = previousState.activationOrigin;
+      pinned = previousState.pinned;
+      try {
+        if (modelChanged && previousModel && !(await pi.setModel(previousModel))) throw new Error("Previous model unavailable");
+        if (modelChanged || effortChanged) pi.setThinkingLevel(previousEffort);
+      } catch (rollbackError) {
+        ctx.ui.notify(`Agents: could not restore previous settings: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`, "warning");
+      }
       ctx.ui.notify(`Agents: ${error instanceof Error ? error.message : String(error)}`, "warning");
+      return false;
     } finally {
       switching = false;
     }
   }
 
-  function restore(ctx: ExtensionContext, applyFlag = false) {
+  function restore(ctx: ExtensionContext) {
     active = "code";
+    pinned = false;
+    activationOrigin = undefined;
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type !== "custom" || entry.customType !== stateType) continue;
-      const agent = (entry.data as { agent?: unknown } | undefined)?.agent;
-      if (isAgentName(agent)) active = agent;
+      const data = entry.data as { agent?: unknown; origin?: unknown; pinned?: unknown } | undefined;
+      if (!isAgentName(data?.agent)) continue;
+      active = data.agent;
+      activationOrigin = data.origin === "automatic" ? "automatic" : "manual";
+      pinned = typeof data.pinned === "boolean" ? data.pinned : true;
     }
-    const flag = applyFlag ? pi.getFlag("agent") : undefined;
-    if (isAgentName(flag)) active = flag;
-    else if (flag !== undefined && flag !== "") ctx.ui.notify(`Unknown agent: ${flag}. Choose ${agentNames.join(", ")}.`, "warning");
     status(ctx);
   }
 
-  pi.on("session_start", async (_event, ctx) => {
-    restore(ctx, true);
-    try { explorationEnabled = Boolean((await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted())).delegate_exploration); }
-    catch { explorationEnabled = false; }
+  pi.on("session_start", async (event, ctx) => {
+    if (jobs.size === 0) scheduler = new SubagentScheduler();
+    try {
+      const config = await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted());
+      explorationEnabled = Boolean(config.delegate_exploration);
+      autoProfileEnabled = config.auto_profile === true;
+    } catch { explorationEnabled = false; autoProfileEnabled = false; }
+    restore(ctx);
+    childStatus(ctx);
+    if (!startupHandled && (!event.reason || event.reason === "startup")) {
+      const flag = pi.getFlag("agent");
+      if (isAgentName(flag)) {
+        active = flag;
+        activationOrigin = "manual";
+        // Child processes receive --agent as their fixed role; only main branches persist a pin.
+        if (depth === 0) { pinned = true; persist(); }
+      } else if (flag !== undefined && flag !== "") ctx.ui.notify(`Unknown agent: ${flag}. Choose ${agentNames.join(", ")}.`, "warning");
+    }
+    startupHandled = true;
+    status(ctx);
     if (depth >= 2) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "subagent"));
     // Only initialize a new main session; explicit CLI choices and resumed models remain authoritative.
-    if (depth !== 0 || ctx.sessionManager.getBranch().some((entry) => entry.type === "message")) return;
+    if (depth !== 0 || (event.reason && event.reason !== "startup" && event.reason !== "new") ||
+      ctx.sessionManager.getBranch().some((entry) => entry.type === "message")) return;
     const args = process.argv.slice(2).slice(0, process.argv.indexOf("--") < 0 ? undefined : process.argv.indexOf("--") - 2);
     if (args.some((arg) => arg === "--model" || arg === "--models" || arg.startsWith("--model=") || arg.startsWith("--models="))) return;
     try {
@@ -93,6 +165,29 @@ export default function agentsExtension(pi: ExtensionAPI) {
   });
   pi.on("session_tree", (_event, ctx) => restore(ctx));
 
+  pi.on("input", async (event, ctx) => {
+    if (depth !== 0 || switching || jobs.size > 0 || !ctx.isIdle() ||
+      (event.source !== "interactive" && event.source !== "rpc") || event.streamingBehavior === "steer" || event.streamingBehavior === "followUp" ||
+      event.text.trimStart().startsWith("/")) return { action: "continue" as const };
+    let config;
+    try { config = await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted()); }
+    catch (error) {
+      ctx.ui.notify(`Agents: ${error instanceof Error ? error.message : String(error)}. Request was not submitted.`, "warning");
+      return { action: "handled" as const };
+    }
+    autoProfileEnabled = config.auto_profile === true;
+    status(ctx);
+    if (!autoProfileEnabled || pinned) return { action: "continue" as const };
+    const name = detectProfileIntent(event.text);
+    // The initial code profile has not applied a variant yet; an explicit first Execute must do so.
+    if (!name || (name === active && activationOrigin !== undefined)) return { action: "continue" as const };
+    if (!(await activate(name, ctx, "automatic", config))) {
+      ctx.ui.notify("Automatic profile activation failed; request was not submitted. Fix the configuration or model and retry.", "warning");
+      return { action: "handled" as const };
+    }
+    return { action: "continue" as const };
+  });
+
   pi.registerCommand("setup-agents", {
     description: "Fill missing project agent.json settings with defaults without replacing configured values",
     handler: async (_args, ctx) => {
@@ -112,17 +207,33 @@ export default function agentsExtension(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("profile", {
-    description: "Switch agent profile (plan, orchestrator, debug, ask, code)",
+    description: "Switch agent profile (plan, orchestrator, debug, ask, code) or resume automatic routing (auto)",
+    getArgumentCompletions: (prefix) => {
+      const matches = profileChoices.filter((choice) => choice.startsWith(prefix));
+      return matches.length > 0 ? matches.map((choice) => ({ value: choice, label: choice })) : null;
+    },
     handler: async (args, ctx) => {
       await ctx.waitForIdle();
       let name: string | undefined = args.trim() || undefined;
       if (!name) {
-        if (!ctx.hasUI) { ctx.ui.notify(`Current agent: ${active}. Use /profile <${agentNames.join("|")}>.`, "info"); return; }
-        name = await ctx.ui.select(`Agent profile (current: ${active})`, [...agentNames]);
+        if (!ctx.hasUI) { ctx.ui.notify(`Current agent: ${active}. Use /profile <${profileChoices.join("|")}>.`, "info"); return; }
+        name = await ctx.ui.select(`Agent profile (current: ${active})`, profileChoices);
         if (!name) return;
       }
-      if (!isAgentName(name)) { ctx.ui.notify(`Unknown agent: ${name}. Choose ${agentNames.join(", ")}.`, "error"); return; }
-      await activate(name, ctx);
+      if (name === "auto") {
+        let config;
+        try { config = await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted()); }
+        catch (error) { ctx.ui.notify(`Agents: ${error instanceof Error ? error.message : String(error)}`, "warning"); return; }
+        if (!config.auto_profile) { ctx.ui.notify("Enable auto_profile in agent.json before using /profile auto.", "warning"); return; }
+        if (!canSwitch(ctx)) { ctx.ui.notify("Wait for the current agent to finish before switching profiles.", "warning"); return; }
+        autoProfileEnabled = true;
+        if (pinned) { pinned = false; persist(); }
+        status(ctx);
+        ctx.ui.notify("Agent profile routing is automatic.", "info");
+        return;
+      }
+      if (!isAgentName(name)) { ctx.ui.notify(`Unknown agent: ${name}. Choose ${profileChoices.join(", ")}.`, "error"); return; }
+      await activate(name, ctx, "manual");
     },
   });
 
@@ -130,13 +241,13 @@ export default function agentsExtension(pi: ExtensionAPI) {
     description: "Cycle agent profile (plan → orchestrator → debug → ask → code)",
     handler: async (ctx) => {
       if (ctx.mode !== "tui") return;
-      await activate(agentNames[(agentNames.indexOf(active) + 1) % agentNames.length], ctx);
+      await activate(agentNames[(agentNames.indexOf(active) + 1) % agentNames.length], ctx, "manual");
     },
   });
 
   pi.on("before_agent_start", (event) => ({
     systemPrompt: `${event.systemPrompt}\n\nPiexis agent profile: ${active}\n${profiles[active]}\n${depth > 0
-      ? "You are a delegated subagent. Work only on the supplied task. If user input is needed, return the question to the parent; no terminal interaction is available. Report changed files, results, and unexecuted checks. If the subagent tool is available, use purpose: explore only for bounded read-only codebase exploration and return concise file paths, line numbers, and uncertainties."
+      ? `You are a delegated subagent. Work only on the supplied task.${inheritedScope ? ` Declared ownership: ${inheritedScope.mode}; paths: ${JSON.stringify(inheritedScope.paths)}. Modify only these paths (an empty write list means broad ownership); keep nested delegation within this ownership.` : ""} If user input is needed, return the question to the parent; no terminal interaction is available. Report changed files, results, and unexecuted checks. If the subagent tool is available, use purpose: explore only for bounded read-only codebase exploration and return concise file paths, line numbers, and uncertainties.`
       : explorationEnabled
         ? "All five profiles are callable through subagent. Delegate only when a separate context helps; supply a focused task and all relevant context. For bounded codebase exploration involving discovery, several files, or a summary, delegate to subagent with agent: ask and purpose: explore. It uses the configured small model and must return concise findings with file paths, line numbers, and uncertainties. Keep planning, judgment, edits, and final verification here; do not delegate a trivial single read."
         : "All five profiles are callable through subagent. Delegate only when a separate context helps; supply a focused task and all relevant context."}`,
@@ -145,61 +256,104 @@ export default function agentsExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
-    description: "Delegate a self-contained task to plan, orchestrator, debug, ask, or code in an isolated Pi process in this workspace. With delegate_exploration enabled, ask plus purpose: explore always uses the configured small_model with read-only tools. Other small tasks can automatically use small_model; variant overrides win. Model, effort, and routing reason are returned. Calls are sequential to avoid concurrent workspace edits. No sandboxing; child questions return to the parent.",
-    executionMode: "sequential",
+    description: "Delegate a self-contained task to plan, orchestrator, debug, ask, or code in an isolated Pi process in this workspace. With delegate_exploration enabled, ask plus purpose: explore always uses the configured small_model with read-only tools. Other small tasks can automatically use small_model; variant overrides win. Model, effort, and routing reason are returned. Orchestrator calls can run concurrently, up to two, only for non-conflicting declared scopes. Other profiles remain sequential. Declare mode and precise paths; broad writes and shared configuration serialize writes. Scopes are cooperative, not sandboxing; child questions return to the parent.",
+    executionMode: "parallel",
     parameters,
     async execute(_id, params, signal, onUpdate, ctx) {
-      if (depth >= 2) throw new Error("Subagent delegation depth limit (2) reached");
-      if (!isAgentName(params.agent) || !params.task.trim() || params.task.length > 50_000) throw new Error("A valid agent and non-empty task of at most 50000 characters are required");
-      if ((active === "plan" || active === "ask") && params.agent !== "plan" && params.agent !== "ask") {
-        throw new Error(`${active} may delegate only to plan or ask; switch to code, debug, or orchestrator for changes`);
-      }
-      const exploration = params.purpose === "explore";
-      if (exploration && params.agent !== "ask") throw new Error("Exploration delegation requires agent: ask");
-      if (!ctx.model) throw new Error("Select a main model before delegating");
-      const config = await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted());
-      if (exploration && !config.delegate_exploration) throw new Error("Enable delegate_exploration in agent.json before delegating exploration");
-      const route = routeSubagent(config, params.agent, params.task, `${ctx.model.provider}/${ctx.model.id}`, (ctx.thinkingLevel ?? pi.getThinkingLevel()) as Effort, exploration);
-      const slash = route.model.indexOf("/");
-      const selected = ctx.modelRegistry.find(route.model.slice(0, slash), route.model.slice(slash + 1));
-      if (!selected || !ctx.modelRegistry.hasConfiguredAuth(selected)) throw new Error(`Subagent model unavailable: ${route.model}. Check /model and /login.`);
-      const tools = subagentTools(params.agent, pi.getActiveTools(), depth + 1, config.delegate_exploration && !exploration);
+      const parentProfile = active;
       const controller = new AbortController();
       const abort = () => controller.abort(signal?.reason);
       signal?.addEventListener("abort", abort, { once: true });
       if (signal?.aborted) abort();
-      const details = { agent: params.agent, ...route };
-      const args = ["--mode", "json", "--print", "--no-session", "--model", route.model,
-        "--thinking", route.effort, "--agent", params.agent,
-        ctx.isProjectTrusted() ? "--approve" : "--no-approve", ...childResourceArgs(process.argv.slice(2)),
-        "--extension", resolve(extensionPath), "--tools", tools.join(",")];
-      if (tools.length === 0) args.push("--no-tools");
-      // Callable MCP tools must not escape a read-only child's explicit built-in loadout.
-      if (params.agent === "plan" || params.agent === "ask") {
-        if ("createMcpExtension" in piSdk) args.push("--no-mcp");
-        args.push("--exclude-tools", "mcp__*");
-      }
-      const job = runSubagent({ invocation: piInvocation(), args, cwd: ctx.cwd, depth: depth + 1,
-        task: params.task, signal: controller.signal,
-        onProgress: (text) => onUpdate?.({ content: [{ type: "text", text: `${params.agent} · ${route.model} · ${route.effort} (${route.reason})\n${text}` }], details }),
-      });
+      // Track preparation as well as queued/running work so shutdown and switching cannot race it.
+      const job = executeJob();
       jobs.set(controller, job);
-      try {
-        const result = await job;
+      try { return await job; }
+      finally {
+        jobs.delete(controller);
+        childStatuses.delete(controller);
+        childStatus(ctx);
+        signal?.removeEventListener("abort", abort);
+      }
+
+      async function executeJob() {
+        controller.signal.throwIfAborted();
+        if (depth >= 2) throw new Error("Subagent delegation depth limit (2) reached");
+        if (!isAgentName(params.agent) || !params.task.trim() || params.task.length > 50_000) throw new Error("A valid agent and non-empty task of at most 50000 characters are required");
+        if ((parentProfile === "plan" || parentProfile === "ask") && params.agent !== "plan" && params.agent !== "ask") {
+          throw new Error(`${parentProfile} may delegate only to plan or ask; switch to code, debug, or orchestrator for changes`);
+        }
+        const exploration = params.purpose === "explore";
+        if (exploration && params.agent !== "ask") throw new Error("Exploration delegation requires agent: ask");
+        const readOnly = exploration || params.agent === "plan" || params.agent === "ask";
+        const parentScope = inheritedScope ? await normalizeSubagentScope(ctx.cwd, inheritedScope) : undefined;
+        const scope = await normalizeSubagentScope(ctx.cwd, {
+          mode: params.mode,
+          paths: params.paths ?? (parentScope?.mode === "write" && !readOnly && params.mode !== "read" ? parentScope.paths : undefined),
+        }, readOnly);
+        if (scope.mode === "write" && parentScope) {
+          if (parentScope.mode === "read" || (parentScope.paths.length > 0 && !parentScope.paths.includes(".") &&
+            (scope.paths.length === 0 || scope.paths.some((path) => !parentScope.paths.some((owner) => path === owner || path.startsWith(`${owner}/`)))))) {
+            throw new Error("Nested write scope must stay within the parent's declared ownership");
+          }
+        }
+        if (!ctx.model) throw new Error("Select a main model before delegating");
+        const config = await loadAgentConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted());
+        if (exploration && !config.delegate_exploration) throw new Error("Enable delegate_exploration in agent.json before delegating exploration");
+        const route = routeSubagent(config, params.agent, params.task, `${ctx.model.provider}/${ctx.model.id}`, (ctx.thinkingLevel ?? pi.getThinkingLevel()) as Effort, exploration);
+        const slash = route.model.indexOf("/");
+        const selected = ctx.modelRegistry.find(route.model.slice(0, slash), route.model.slice(slash + 1));
+        if (!selected || !ctx.modelRegistry.hasConfiguredAuth(selected)) throw new Error(`Subagent model unavailable: ${route.model}. Check /model and /login.`);
+        const tools = subagentTools(scope.mode === "read" ? "ask" : params.agent, pi.getActiveTools(), depth + 1, config.delegate_exploration && !exploration);
+        let scheduling: SchedulerStatus = { status: "queued" };
+        const details = () => ({ agent: params.agent, ...route, mode: scope.mode, paths: scope.paths, broad: scope.broad, ...scheduling });
+        const update = (text: string) => onUpdate?.({ content: [{ type: "text" as const, text: `${params.agent} · ${route.model} · ${route.effort} (${route.reason})\n${text}` }], details: details() });
+        const args = ["--mode", "json", "--print", "--no-session", "--model", route.model,
+          "--thinking", route.effort, "--agent", params.agent,
+          ctx.isProjectTrusted() ? "--approve" : "--no-approve", ...childResourceArgs(process.argv.slice(2)),
+          "--extension", resolve(extensionPath), "--tools", tools.join(",")];
+        if (tools.length === 0) args.push("--no-tools");
+        // Callable MCP tools must not escape a read-only child's explicit built-in loadout.
+        if (scope.mode === "read") {
+          if ("createMcpExtension" in piSdk) args.push("--no-mcp");
+          args.push("--exclude-tools", "mcp__*");
+        }
+        const reportStatus = (state: SchedulerStatus) => {
+          scheduling = state;
+          if (state.status === "queued" || state.status === "running") {
+            childStatuses.set(controller, { agent: params.agent, status: state.status });
+          } else childStatuses.delete(controller);
+          childStatus(ctx);
+          update(`${state.status}${state.reason ? ` (${state.reason})` : ""} · ${scope.mode}${scope.paths.length ? ` · ${scope.paths.join(", ")}` : ""}`);
+        };
+        controller.signal.throwIfAborted();
+        const result = await scheduler.schedule({
+          scope, controller, serial: parentProfile !== "orchestrator",
+          run: async () => {
+            // A previous writer may have created a symlink while this request was queued.
+            await normalizeSubagentScope(ctx.cwd, scope);
+            return runSubagent({ invocation: piInvocation(), args, cwd: ctx.cwd, depth: depth + 1,
+              task: params.task, scope, signal: controller.signal, onProgress: update });
+          },
+          onStatus: (state) => {
+            // Runner results can resolve with provider errors; classify before reporting completion.
+            if (state.status !== "completed") reportStatus(state);
+          },
+        });
         const failed = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted" || Boolean(result.error);
+        reportStatus({ status: result.stopReason === "aborted" ? "aborted" : failed ? "failed" : "completed" });
         return {
           content: [{ type: "text" as const, text: `${params.agent} · ${route.model} · ${route.effort} (${route.reason})\n${limitOutput(failed ? result.error || result.stderr || result.output || "Subagent failed" : result.output)}` }],
-          details: { ...details, ...result }, usage: result.usage, isError: failed,
+          details: { ...details(), ...result }, usage: result.usage, isError: failed,
         };
-      } finally {
-        jobs.delete(controller);
-        signal?.removeEventListener("abort", abort);
       }
     },
   });
 
   pi.on("session_shutdown", async () => {
+    const closing = scheduler.shutdown("Session shutdown");
     for (const controller of jobs.keys()) controller.abort("Session shutdown");
+    await closing;
     await Promise.allSettled(jobs.values());
   });
 }

package/extensions/ui.ts

@@ -169,7 +169,7 @@ export default function (pi: ExtensionAPI) {
 
           let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, cost = 0;
           for (const entry of ctx.sessionManager.getBranch()) {
-            if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+            if (entry.type !== "message" || (entry.message.role !== "assistant" && entry.message.role !== "toolResult")) continue;
             const u = entry.message.usage;
             if (!u) continue;
             input += u.input;
@@ -183,14 +183,22 @@ export default function (pi: ExtensionAPI) {
           const activity = state === "tool" ? `${frame} ${activeTool}`
             : state === "thinking" ? `${frame} thinking` : "● ready";
           const agent = footerData.getExtensionStatuses?.().get("piexis-agent");
+          const agentMode = footerData.getExtensionStatuses?.().get("piexis-agent-mode");
           const branch = footerData.getGitBranch();
           // Reserve a small model slot; long tool names must not displace the profile.
           const modelReserve = width >= 32 ? 9 : 0;
-          const profile = agent && visibleWidth(agent) + 6 + modelReserve <= width
-            ? theme.fg("accent", agent) + sep : "";
-          const activityWidth = Math.max(1, Math.min(24, width - visibleWidth(profile) - modelReserve));
-          const left1 = profile + theme.fg(state === "ready" ? "success" : "accent",
-            truncateToWidth(activity, activityWidth, "…"));
+          const fullProfile = agent && agentMode ? `${agent} (${agentMode})` : agent ?? "";
+          // Mode is optional; the profile itself remains ahead of activity and right-side fields.
+          const profileText = agent && width >= 48 && visibleWidth(fullProfile) + 6 + modelReserve <= width
+            ? fullProfile
+            : agent ?? "";
+          const profileLimit = Math.max(0, width - 1);
+          const profile = profileText
+            ? theme.fg("accent", truncateToWidth(profileText, profileLimit, "…")) + (profileLimit > 0 ? sep : "")
+            : "";
+          const activityWidth = Math.max(0, Math.min(24, width - visibleWidth(profile) - modelReserve));
+          const left1 = profile + (activityWidth ? theme.fg(state === "ready" ? "success" : "accent",
+            truncateToWidth(activity, activityWidth, "…")) : "");
           const row1 = justify(left1, [
             { text: ctx.model?.id ?? "—", priority: 5 },
             { text: muted(`think ${pi.getThinkingLevel()}`), priority: 4 },
@@ -224,7 +232,10 @@ export default function (pi: ExtensionAPI) {
             { text: muted(costText), priority: 3 }
           ], sep, width);
 
-          return [row1, row2];
+          const children = footerData.getExtensionStatuses?.().get("piexis-subagents");
+          return children
+            ? [row1, row2, theme.fg("accent", truncateToWidth(children, width, "…"))]
+            : [row1, row2];
         },
 
         dispose() {

package/lib/agent-config.ts

@@ -11,6 +11,7 @@ export interface AgentConfig {
   small_model?: string;
   subagent_model?: string;
   delegate_exploration?: boolean;
+  auto_profile?: boolean;
   subagent_variant_overrides?: Partial<Record<AgentName, { model?: string; effort?: Effort }>>;
 }
 
@@ -21,7 +22,8 @@ export interface AgentConfig {
 export const initialAgentConfigDefaults = {
   "$schema": agentConfigSchemaUrl,
   delegate_exploration: false,
-} satisfies Pick<AgentConfig, "$schema" | "delegate_exploration">;
+  auto_profile: false,
+} satisfies Pick<AgentConfig, "$schema" | "delegate_exploration" | "auto_profile">;
 
 /** Header copy for incomplete project agent configuration. */
 export type AgentConfigSetting = Exclude<keyof AgentConfig, "$schema">;
@@ -31,6 +33,7 @@ export const agentConfigCapabilities = {
   small_model: "use a cheaper model for eligible small tasks",
   subagent_model: "choose the normal model for delegated work",
   delegate_exploration: "opt in to cheap, read-only codebase exploration",
+  auto_profile: "automatically select a profile for clear requests",
   subagent_variant_overrides: "customize model and effort for each agent profile",
 } satisfies Record<AgentConfigSetting, string>;
 
@@ -50,6 +53,7 @@ export function createInitialAgentConfig(selected: string, inherited: AgentConfi
     small_model: inherited.small_model ?? selected,
     subagent_model: inherited.subagent_model ?? selected,
     delegate_exploration: inherited.delegate_exploration ?? initialAgentConfigDefaults.delegate_exploration,
+    auto_profile: inherited.auto_profile ?? initialAgentConfigDefaults.auto_profile,
     subagent_variant_overrides: overrides,
   };
 }

package/lib/agents.ts

@@ -8,7 +8,7 @@ export { agentNames, type AgentConfig, type AgentName, effortLevels, type Effort
 
 export const profiles: Record<AgentName, string> = {
   plan: "Explore the request and relevant code, clarify important unknowns, and return an actionable plan with acceptance checks. Do not implement or delegate implementation. Stop after the plan.",
-  orchestrator: "Break work into focused tasks and delegate to plan, debug, ask, or code using subagent. Include all necessary context in each task; children do not inherit the conversation. Keep overlapping file changes sequential. Inspect results, resolve disagreements, and report verification evidence. Do not delegate the same orchestration task recursively.",
+  orchestrator: "Break work into focused tasks and delegate to plan, debug, ask, or code using subagent. Include all necessary context in each task; children do not inherit the conversation. Declare mode: read for read-only work and mode: write with precise repository-relative paths for edits. Divide parallel work by non-overlapping ownership; at most two jobs can run concurrently. Leave uncertain, overlapping, or shared-configuration writes sequential. Do not edit the workspace yourself while write children are running. Inspect results, reconcile integration issues, and run final verification after all children settle. Do not delegate the same orchestration task recursively.",
   debug: "Reproduce or establish evidence for the failure, trace its cause before editing, and make the smallest justified fix. Verify with a regression check. Separate confirmed facts from hypotheses and report any unexecuted checks.",
   ask: "Answer the user's question using relevant code or documentation as evidence. Do not change files or delegate changes. When context is missing, ask rather than invent facts. Stop when the question is answered.",
   code: "Implement the requested scope using existing repository patterns. Preserve unrelated changes, add focused coverage for behavior changes, run relevant checks, and report results. Stop when acceptance conditions are met.",
@@ -34,7 +34,7 @@ export function parseAgentConfig(value: unknown): AgentConfig {
   const source = object(value, "Agent configuration");
   const result: AgentConfig = {};
   for (const key of Object.keys(source)) {
-    if (!["$schema", "model", "small_model", "subagent_model", "delegate_exploration", "subagent_variant_overrides"].includes(key)) {
+    if (!["$schema", "model", "small_model", "subagent_model", "delegate_exploration", "auto_profile", "subagent_variant_overrides"].includes(key)) {
       throw new Error(`Unknown agent configuration key: ${key}`);
     }
   }
@@ -49,6 +49,10 @@ export function parseAgentConfig(value: unknown): AgentConfig {
     if (typeof source.delegate_exploration !== "boolean") throw new Error("delegate_exploration must be a boolean");
     result.delegate_exploration = source.delegate_exploration;
   }
+  if (source.auto_profile !== undefined) {
+    if (typeof source.auto_profile !== "boolean") throw new Error("auto_profile must be a boolean");
+    result.auto_profile = source.auto_profile;
+  }
   if (source.subagent_variant_overrides !== undefined) {
     result.subagent_variant_overrides = {};
     for (const [name, value] of Object.entries(object(source.subagent_variant_overrides, "subagent_variant_overrides"))) {
@@ -166,6 +170,35 @@ export async function completeProjectAgentConfig(cwd: string, agentDir: string,
   });
 }
 
+const profileIntentRules: [AgentName, RegExp][] = [
+  ["plan", /^(?:let'?s\s+plan|(?:make|create)\s+(?:me\s+)?(?:a\s+)?plan|help\s+me\s+plan|plan)\b/i],
+  ["debug", /^(?:help\s+me\s+)?(?:debug|investigate|fix\s+(?:a\s+|the\s+|this\s+)?(?:bug|error|crash|failure))\b/i],
+  ["orchestrator", /^(?:orchestrate|coordinate|delegate)\b/i],
+  ["code", /^(?:implement|build|write|execute)\b/i],
+  ["ask", /^(?:explain|answer(?:\s+(?:this\s+)?question)?|what|how|why|where|when|who)\b/i],
+];
+const politePrefix = /^(?:(?:please|kindly|hey)[,\s]+|(?:could|would|can)\s+you\s+)+/i;
+
+export function detectProfileIntent(text: string): AgentName | undefined {
+  const input = text.trim().replace(/\u2019/g, "'").replace(politePrefix, "");
+  if (!input || /^[/`>~"'\u201c\u2018]/.test(input)) return undefined;
+  const match = profileIntentRules.find(([, expression]) => expression.test(input));
+  if (!match) return undefined;
+  const [profile, expression] = match;
+  const rest = input.slice(input.match(expression)![0].length);
+  if (profile !== "ask" && /^\s+(?:is|means|refers\s+to)\b/i.test(rest)) return undefined;
+  // shortcut: bounded English outer-action rules; expand only with evaluated intent examples.
+  const nested = /^(?:\s+(?:how|why|what|when|where)\b)|\bto\s+(?:debug|investigate|implement|build|write|execute)\b/i.test(rest);
+  if (!nested) {
+    const ownText = rest.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`]*`|"[^"]*"|“[^”]*”|'[^']*'|‘[^’]*’/g, "");
+    for (const clause of ownText.split(/\b(?:and(?:\s+then)?|then|but|also)\s+|[.!?]\s+|\n+/i).slice(1)) {
+      const other = profileIntentRules.find(([, rule]) => rule.test(clause.trim().replace(politePrefix, "")));
+      if (other && other[0] !== profile) return undefined;
+    }
+  }
+  return profile;
+}
+
 export function isSmallTask(agent: AgentName, task: string): boolean {
   // shortcut: conservative text heuristic, replace with evaluated routing if real tasks outgrow it.
   if (task.length > 400 || task.split(/\s+/).length > 65) return false;

package/lib/subagent-runner.ts

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { basename, dirname, join } from "node:path";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { SubagentScope } from "./subagent-scheduler.ts";
 
 type Usage = NonNullable<Awaited<ReturnType<ToolDefinition["execute"]>>["usage"]>;
 
@@ -50,6 +51,7 @@ export async function runSubagent(options: {
   cwd: string;
   depth: number;
   task: string;
+  scope?: SubagentScope;
   signal: AbortSignal;
   onProgress?: (text: string) => void;
 }): Promise<ChildResult> {
@@ -60,7 +62,8 @@ export async function runSubagent(options: {
     const child = spawn(options.invocation.command, [...options.invocation.args, ...options.args], {
       cwd: options.cwd, shell: false, detached: grouped,
       stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env, PIEXIS_SUBAGENT_DEPTH: String(options.depth) },
+      env: { ...process.env, PIEXIS_SUBAGENT_DEPTH: String(options.depth),
+        ...(options.scope ? { PIEXIS_SUBAGENT_SCOPE: JSON.stringify(options.scope) } : {}) },
     });
     let buffer = "", bytes = 0, timer: NodeJS.Timeout | undefined, failure: Error | undefined;
     let closed = false;

package/lib/subagent-scheduler.ts

@@ -0,0 +1,221 @@
+import { lstat } from "node:fs/promises";
+import { basename, relative, resolve, sep } from "node:path";
+
+export type SubagentScope = { mode: "read" | "write"; paths: string[]; broad: boolean };
+
+const sharedRootFiles = new Set([
+  "package.json", "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml",
+  "bun.lock", "bun.lockb", ".npmrc", "biome.json", "turbo.json", "nx.json",
+]);
+const sharedRootPatterns = [
+  /^tsconfig(?:\.[^/]+)?\.json$/,
+  /^(?:vite|webpack|rollup|esbuild|eslint|prettier)\.config\.[^/]+$/,
+  /^\.eslintrc(?:\.[^/]+)?$/,
+  /^\.prettierrc(?:\.[^/]+)?$/,
+];
+
+function isSharedPath(path: string): boolean {
+  path = path.toLowerCase();
+  const first = path.split("/")[0];
+  if ([".pi", ".git", ".github"].includes(first)) return true;
+  const name = basename(path);
+  if (sharedRootFiles.has(name) || /^tsconfig(?:\.[^/]+)?\.json$/.test(name)) return true;
+  return !path.includes("/") && sharedRootPatterns.some((pattern) => pattern.test(path));
+}
+
+async function rejectSymlinkComponents(cwd: string, path: string): Promise<void> {
+  let current = cwd;
+  for (const segment of path.split("/")) {
+    current = resolve(current, segment);
+    try {
+      if ((await lstat(current)).isSymbolicLink()) throw new Error(`Write path contains a symbolic-link component: ${path}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw error;
+    }
+  }
+}
+
+/** Validates a declared scope without resolving symlinks outside the workspace. */
+export async function normalizeSubagentScope(
+  cwd: string,
+  input: { mode?: "read" | "write"; paths?: string[] },
+  readOnly = false,
+): Promise<SubagentScope> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError("Subagent scope must be an object");
+  const mode = input.mode === undefined ? (readOnly ? "read" : "write") : input.mode;
+  if (mode !== "read" && mode !== "write") throw new TypeError("Subagent scope mode must be read or write");
+  if (readOnly && input.mode === "write") throw new Error("A read-only subagent cannot declare write scope");
+  if (input.paths !== undefined && !Array.isArray(input.paths)) throw new TypeError("Subagent scope paths must be an array");
+
+  const root = resolve(cwd);
+  const paths: string[] = [];
+  for (const value of input.paths ?? []) {
+    if (typeof value !== "string") throw new TypeError("Subagent scope paths must contain strings");
+    if (!value || value.includes("\0") || value.includes("\\") || /^(?:[A-Za-z]:|\/)/.test(value)) {
+      throw new Error(`Invalid repository-relative path: ${JSON.stringify(value)}`);
+    }
+    const absolute = resolve(root, value);
+    const fromRoot = relative(root, absolute);
+    if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) throw new Error(`Path escapes workspace: ${value}`);
+    paths.push(fromRoot ? fromRoot.split(sep).join("/") : ".");
+  }
+  const normalized = [...new Set(paths)];
+  if (mode === "write") await Promise.all(normalized.filter((path) => path !== ".").map((path) => rejectSymlinkComponents(root, path)));
+  const broad = mode === "write" && (normalized.length === 0 || normalized.includes(".") || normalized.some(isSharedPath));
+  return { mode, paths: normalized, broad };
+}
+
+function overlaps(a: string, b: string): boolean {
+  // Case-fold conservatively on platforms whose default filesystems are case-insensitive.
+  if (process.platform === "win32" || process.platform === "darwin") { a = a.toLowerCase(); b = b.toLowerCase(); }
+  return a === "." || b === "." || a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+export function scopesConflict(a: SubagentScope, b: SubagentScope): boolean {
+  if (a.mode === "read" || b.mode === "read") return false;
+  if (a.broad || b.broad) return true;
+  return a.paths.some((left) => b.paths.some((right) => overlaps(left, right)));
+}
+
+export type SchedulerStatus = { status: "queued" | "running" | "completed" | "failed" | "aborted"; reason?: string };
+
+type Job<T> = {
+  scope: SubagentScope;
+  controller: AbortController;
+  serial: boolean;
+  run: () => Promise<T>;
+  onStatus?: (status: SchedulerStatus) => void;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+  abort: () => void;
+  state: "queued" | "active" | "settled";
+  lastStatus?: string;
+  done: Promise<void>;
+  finish: () => void;
+};
+
+export class SubagentScheduler {
+  #queued: Job<unknown>[] = [];
+  #active = new Set<Job<unknown>>();
+  #draining = false;
+  #stopping = false;
+  #shutdown?: Promise<void>;
+  readonly #limit: number;
+
+  constructor(limit = 2) {
+    if (!Number.isInteger(limit) || limit < 1) throw new RangeError("Subagent scheduler limit must be at least one");
+    this.#limit = limit;
+  }
+
+  get size(): number { return this.#queued.length + this.#active.size; }
+
+  schedule<T>(options: { scope: SubagentScope; controller: AbortController; serial?: boolean; run: () => Promise<T>; onStatus?: (status: SchedulerStatus) => void }): Promise<T> {
+    if (this.#stopping) return Promise.reject(this.#abortError("Subagent scheduler is shut down"));
+    options.controller.signal.throwIfAborted();
+    return new Promise<T>((resolve, reject) => {
+      let finish!: () => void;
+      const done = new Promise<void>((doneResolve) => { finish = doneResolve; });
+      const job: Job<T> = {
+        ...options, serial: options.serial === true, resolve, reject, state: "queued", done, finish,
+        abort: () => this.#cancelQueued(job as unknown as Job<unknown>),
+      };
+      options.controller.signal.addEventListener("abort", job.abort, { once: true });
+      this.#queued.push(job as Job<unknown>);
+      this.#drain();
+    });
+  }
+
+  async shutdown(reason?: unknown): Promise<void> {
+    if (this.#shutdown) return this.#shutdown;
+    this.#stopping = true;
+    this.#shutdown = (async () => {
+      for (const job of [...this.#queued]) {
+        job.controller.abort(reason);
+        this.#cancelQueued(job);
+      }
+      for (const job of this.#active) job.controller.abort(reason);
+      await Promise.all([...this.#active].map((job) => job.done));
+    })();
+    return this.#shutdown;
+  }
+
+  #drain(): void {
+    if (this.#draining || this.#stopping) return;
+    this.#draining = true;
+    try {
+      let started: boolean;
+      do {
+        started = false;
+        for (const job of [...this.#queued]) {
+          if (this.#stopping) break;
+          if (job.state !== "queued") continue;
+          const reason = this.#blockingReason(job);
+          if (reason) { this.#status(job, { status: "queued", reason }); continue; }
+          this.#queued.splice(this.#queued.indexOf(job), 1);
+          job.controller.signal.removeEventListener("abort", job.abort);
+          this.#start(job);
+          started = true;
+        }
+      } while (started && !this.#shutdown);
+    } finally { this.#draining = false; }
+  }
+
+  #blockingReason(job: Job<unknown>): string | undefined {
+    if (this.#active.size >= this.#limit || job.serial && this.#active.size > 0 || [...this.#active].some((active) => active.serial)) return "capacity";
+    const conflict = [...this.#active].find((active) => scopesConflict(job.scope, active.scope));
+    if (!conflict) return undefined;
+    if (job.scope.broad || conflict.scope.broad) return "conflicting broad write";
+    const left = job.scope.paths.find((path) => conflict.scope.paths.some((other) => overlaps(path, other)))!;
+    return `conflicting path: ${left}`;
+  }
+
+  #start(job: Job<unknown>): void {
+    job.state = "active";
+    this.#active.add(job);
+    this.#status(job, { status: "running" });
+    let promise: Promise<unknown>;
+    try { job.controller.signal.throwIfAborted(); promise = Promise.resolve(job.run()); }
+    catch (error) { promise = Promise.reject(error); }
+    promise.then(
+      (value) => this.#settle(job, "completed", value),
+      (error) => this.#settle(job, job.controller.signal.aborted ? "aborted" : "failed", error),
+    );
+  }
+
+  #settle(job: Job<unknown>, status: SchedulerStatus["status"], value: unknown): void {
+    if (job.state === "settled") return;
+    if (status === "completed" && job.controller.signal.aborted) { status = "aborted"; value = job.controller.signal.reason; }
+    job.state = "settled";
+    this.#active.delete(job);
+    job.finish();
+    this.#status(job, { status });
+    if (status === "completed") job.resolve(value); else job.reject(value);
+    this.#drain();
+  }
+
+  #cancelQueued(job: Job<unknown>): void {
+    if (job.state !== "queued") return;
+    job.state = "settled";
+    const index = this.#queued.indexOf(job);
+    if (index >= 0) this.#queued.splice(index, 1);
+    job.finish();
+    job.controller.signal.removeEventListener("abort", job.abort);
+    this.#status(job, { status: "aborted" });
+    try { job.controller.signal.throwIfAborted(); } catch (error) { job.reject(error); }
+    this.#drain();
+  }
+
+  #status(job: Job<unknown>, status: SchedulerStatus): void {
+    const key = `${status.status}\0${status.reason ?? ""}`;
+    if (job.lastStatus === key) return;
+    job.lastStatus = key;
+    try { job.onStatus?.(status); } catch { /* Status observers cannot retain scheduler reservations. */ }
+  }
+
+  #abortError(message: string): Error {
+    const error = new Error(message);
+    error.name = "AbortError";
+    return error;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preapexis/piexis",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "type": "module",
   "description": "Extensions, skills, prompts, and themes for pi",
   "repository": {

package/schemas/agent.schema.json

@@ -16,6 +16,10 @@
       "type": "boolean",
       "description": "Allow read-only exploration to use small_model."
     },
+    "auto_profile": {
+      "type": "boolean",
+      "description": "Automatically select a profile for clear requests."
+    },
     "subagent_variant_overrides": {
       "type": "object",
       "additionalProperties": false,