@arhen/pi-core-subagent 1.3.45 → 1.3.47

package/README.md

@@ -93,11 +93,10 @@ Define agents inline per call, or reference a named agent file (see [Agent files
 }
 ```
 
-Parallel — mixed toolsets, siblings can talk via mailbox:
+Parallel — mixed toolsets, siblings can talk via mailbox (intercom is always on):
 
 ```json
 {
-  "allowIntercom": true,
   "tasks": [
     { "agent": "researcher", "prompt": "You find facts. Cite paths.", "task": "Map the auth flow", "write": false },
     { "agent": "implementer", "prompt": "You make minimal changes.", "task": "Implement POST /api/upload", "write": true }
@@ -272,14 +271,13 @@ flowchart LR
 
 And the rule that keeps this from becoming ceremony: **zero `needs` anywhere = plain parallel.** No waves, no gates, no graph vocabulary imposed on flat work.
 
-Background (default) + intercom — the run returns a runId immediately; you stay steerable while it works:
+Background (default) + intercom — the run returns a runId immediately; you stay steerable while it works. Children can always ask you questions and message each other:
 
 ```json
 {
   "agent": "auditor",
   "prompt": "You audit dependencies.",
-  "task": "Audit package.json for outdated deps",
-  "allowIntercom": true
+  "task": "Audit package.json for outdated deps"
 }
 ```
 
@@ -289,7 +287,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 | Tool | Purpose |
 |---|---|
-| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); every run is background — returns a runId, completion notifies you; `autoAwait:true` parks the call until the run finishes and returns the final result inline; `allowIntercom:true` enables child talk tools; `notifyPerTask` (default true) wakes you as each task completes |
+| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); every run is background — returns a runId, completion notifies you; `autoAwait:true` parks the call until the run finishes and returns the final result inline; children always carry talk tools (ask/notify/mailbox); `notifyPerTask` (default true) wakes you as each task completes |
 | `subagent_status` | live per-task snapshot (non-blocking), including each child's session file path |
 | `subagent_result` | full output of a run or one task |
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |
@@ -299,9 +297,9 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 ### Per-task fields
 
-`agent` (name you invent — required), `task` (required), `prompt` (system prompt, optional — minimal default used), `write` (toolset, default read-only), plus optional `model` (`provider/model-id`), `thinking` (validated enum: `off|minimal|low|medium|high|xhigh|max`), `tools` (explicit allowlist), `cwd`, `maxRuntimeMs`, `id`, `needs` (dependency edges — see [Graph mode](#graph-mode--needs)). Top-level only: `autoAwait`, `notifyPerTask`, `allowIntercom`, `concurrency`.
+`agent` (name you invent — required), `task` (required), `prompt` (system prompt, optional — minimal default used), `write` (toolset, default read-only), plus optional `model` (`provider/model-id`), `thinking` (validated enum: `off|minimal|low|medium|high|xhigh|max`), `tools` (explicit allowlist), `cwd`, `maxRuntimeMs`, `id`, `needs` (dependency edges — see [Graph mode](#graph-mode--needs)). Top-level only: `autoAwait`, `notifyPerTask`, `concurrency`.
 
-### Child talk tools (when `allowIntercom: true`)
+### Child talk tools (always on)
 
 | Tool | Meaning |
 |---|---|
@@ -315,7 +313,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 ## Commands
 
 - `/subagents` — list runs; `/subagents peek` (or `ctrl+shift+a`) — browsable pane
-- `/subagents auto-limit on|off` — toggle leader-imposed `maxRuntimeMs` caps (persists to `~/.pi/agent/subagents-config.json`; default on). `off` strips ALL task timeouts: tasks run unlimited until done, stalled, or aborted — only for runs where a hard bound is genuinely required is a cap kept (none, when off). Bare `/subagents auto-limit` shows the current state.
+- `/subagents auto-limit on|off` — toggle leader-imposed `maxRuntimeMs` caps (persists to `~/.pi/agent/subagents-config.json`; default **off**). `on` gives tasks without an explicit `maxRuntimeMs` the 1 h default ceiling; `off` raises the ceiling to 6 h (still a ceiling — an unbounded child would pin the run forever). Bare `/subagents auto-limit` shows the current state.
 
 ## Peek — `/subagents peek` or `ctrl+shift+a`
 
@@ -356,7 +354,7 @@ The extension has no multiplexer integration and does not want one: it exposes t
 
 - Parent tools: 6 schemas with short descriptions. **No catalog, no context hook** — nothing injected per request.
 - Background completion: 3-line notice. Full text only via `subagent_result`.
-- Children: isolated sessions; talk tools injected only when `allowIntercom`; each child's prompt states its own task id and its siblings' so mailbox addressing works. Model resolution: explicit `provider/model-id` or bare id via the pi model registry → the parent's current model → settings default. Thinking levels validated against the resolved model's `thinkingLevelMap`.
+- Children: isolated sessions; talk tools always injected; each child's prompt states its own task id and its siblings' so mailbox addressing works. Model resolution: explicit `provider/model-id` or bare id via the pi model registry → the parent's current model → settings default. Thinking levels validated against the resolved model's `thinkingLevelMap`.
 
 ## What this is built on
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.45",
+	"version": "1.3.47",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/child.ts

@@ -1,7 +1,7 @@
 /**
  * Child-session tools.
  *
- * When `allowIntercom: true`, children get four talk tools:
+ * Every child gets four talk tools:
  *   - ask_parent            blocking Q&A with the leader (parent)
  *   - notify_parent         one-way message to the leader
  *   - send_agent_message    one-way message to another subagent's mailbox

package/src/index.ts

@@ -81,12 +81,12 @@ export default function (pi: ExtensionAPI) {
 				if (value === "on" || value === "off") {
 					const next = manager.setAutoLimit(value === "on");
 					ctx.ui.notify(
-						`auto-limit ${next ? "on" : "off"} — ${next ? "leader-imposed" : "no"} maxRuntimeMs caps apply to tasks (off = unlimited until done).`,
+						`auto-limit ${next ? "on" : "off"} — ${next ? "tasks without an explicit maxRuntimeMs get the 1 h default ceiling" : "raised 6 h ceiling applies (no 1 h cap)"}.`,
 						"info",
 					);
 				} else {
 					ctx.ui.notify(
-						`auto-limit is ${manager.autoLimitOn ? "on" : "off"} — use \`/subagents auto-limit on|off\` (off = tasks run unlimited until done).`,
+						`auto-limit is ${manager.autoLimitOn ? "on (1 h default ceiling)" : "off (6 h ceiling)"} — use \`/subagents auto-limit on|off\`.`,
 						"info",
 					);
 				}
@@ -157,7 +157,7 @@ export default function (pi: ExtensionAPI) {
 		// ponytail: this string is billed on every request. No example block — an example
 		// biases the model toward one shape; guidelines + JSON schema describe all of them.
 		description:
-			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Write agents run in an isolated git worktree: on completion the result reports the branch + changed files — review, then merge with `git merge --no-ff <branch>` (merged branches are cleaned automatically). Every run is background: the call returns a runId immediately and completion notifies you — do NOT park waiting on it. If you have no other work, end your turn; the completion notice wakes you with the results. Set autoAwait:true only when the very next step in the SAME turn consumes the result. allowIntercom:true lets children talk to you and each other.",
+			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Write agents run in an isolated git worktree: on completion the result reports the branch + changed files — review, then merge with `git merge --no-ff <branch>` (merged branches are cleaned automatically). Every run is background: the call returns a runId immediately and completion notifies you — do NOT park waiting on it. If you have no other work, end your turn; the completion notice wakes you with the results. Set autoAwait:true only when the very next step in the SAME turn consumes the result. Children always carry talk tools: they can ask you questions, notify you, and message siblings.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
@@ -172,7 +172,6 @@ export default function (pi: ExtensionAPI) {
 			"Never block with nothing to do: if you have no work left after spawning, end your turn. Task completion notifies you and wakes a fresh turn with the results — await_subagent/autoAwait in that situation only burns time and tokens.",
 			"autoAwait:true only when the same turn must consume the result immediately (e.g. you spawn a reviewer and then must act on its verdict before replying). Otherwise spawn background and read results from the completion notice, or subagent_result when you come back.",
 			"await_subagent is for the rare case where you have parallel work of your own and need to sync at a specific point — not the default follow-up to a spawn.",
-			"allowIntercom:true only when a child may need to ask you something.",
 		],
 		parameters: SubagentParams,
 		executionMode: "parallel", // sibling subagent calls run concurrently, not serialized
@@ -237,7 +236,7 @@ export default function (pi: ExtensionAPI) {
 					: args.agent
 						? `single ${args.agent}`
 						: "preparing…";
-			const flags = [args.autoAwait ? "await" : "bg", args.allowIntercom ? "a2a" : ""].filter(Boolean).join(" · ");
+			const flags = args.autoAwait ? "await" : "bg";
 			// Params used, dimmed: model, thinking, toolset, per-task write count.
 			const tasks = args.tasks ?? args.chain ?? [];
 			const writeCount = tasks.filter((t) => t.write).length;
@@ -269,7 +268,7 @@ export default function (pi: ExtensionAPI) {
 				})
 				.join("");
 			return new Text(
-				`${theme.fg("toolTitle", theme.bold("subagent"))} ${theme.fg("accent", mode)}${flags ? ` ${theme.fg("muted", `[${flags}]`)}` : ""}${params}${graphLine}${plan}`,
+				`${theme.fg("toolTitle", theme.bold("subagent"))} ${theme.fg("accent", mode)} ${theme.fg("muted", `[${flags}]`)}${params}${graphLine}${plan}`,
 				0,
 				0,
 			);

package/src/manager.ts

@@ -321,8 +321,8 @@ export class SubagentManager {
 	/** Set by clearRuns — blocks late persists from erasing the sidecar. */
 	private cleared = false;
 
-	/** When false, strip leader-imposed maxRuntimeMs so tasks run unlimited — toggle via `/subagents auto-limit on|off`. */
-	private autoLimit = true;
+	/** When true, tasks without an explicit maxRuntimeMs get the 1 h default ceiling; when false (default) the raised 6 h ceiling applies — toggle via `/subagents auto-limit on|off`. */
+	private autoLimit = false;
 
 	turnActivity = false;
 
@@ -850,7 +850,7 @@ export class SubagentManager {
 		const allowedTools = input.write ? WRITE_TOOLS : READONLY_TOOLS;
 		const fileTools = file?.tools?.filter((t) => allowedTools.includes(t));
 		const baseTools = fileTools?.length ? fileTools : (input.tools ?? allowedTools);
-		const tools = [...baseTools, ...(run.allowIntercom ? CHILD_TALK_TOOLS : [])];
+		const tools = [...baseTools, ...CHILD_TALK_TOOLS];
 		// Isolation follows the DELIVERED toolset, never the raw request: explicit
 		// tools: [bash] without write:true still gets a worktree, and a file that
 		// narrowed the child to read-only never gets the commit/merge ceremony.
@@ -990,9 +990,7 @@ export class SubagentManager {
 			const worktreeNote = wt
 				? ` You work in an isolated git worktree (branch ${wt.branch})${task.stackedOn ? `, stacked on ${task.stackedOn} (its changes are already in your tree)` : ""}. Never run git commands that switch branches, create branches, or move the worktree (git switch/checkout/branch/worktree). The extension commits your changes when you finish. git status/diff are fine for inspecting your own changes. node_modules is a SHARED symlink to the main checkout: never install, upgrade, or delete dependencies (no npm/bun/yarn/pnpm install, no \`rm -rf node_modules\`) — those writes escape your worktree and damage the user's project. If the task truly needs a dependency change, edit the manifest only and say so in your answer.`
 				: "";
-			const subagentInstruction = run.allowIntercom
-				? `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has; notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. Stalled waits get the whole run killed. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.${worktreeNote}`
-				: `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer for the parent agent.${worktreeNote}`;
+			const subagentInstruction = `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has; notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. Stalled waits get the whole run killed. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.${worktreeNote}`;
 
 			const loader = new DefaultResourceLoader({
 				cwd: childCwd,
@@ -1005,9 +1003,7 @@ export class SubagentManager {
 			});
 			await loader.reload();
 
-			const customTools: ToolDefinition[] = run.allowIntercom
-				? createChildTools(task.id, this.makeChildHandlers(run, task, ctx))
-				: [];
+			const customTools: ToolDefinition[] = createChildTools(task.id, this.makeChildHandlers(run, task, ctx));
 
 			const created = await createAgentSession({
 				cwd: childCwd,
@@ -1324,7 +1320,6 @@ export class SubagentManager {
 			id: newId("run"),
 			mode,
 			status: "queued",
-			allowIntercom: Boolean(params.allowIntercom),
 			notifyPerTask: params.notifyPerTask ?? true,
 			createdAt: Date.now(),
 			concurrency: Math.max(1, Math.min(params.concurrency ?? DEFAULT_CONCURRENCY, MAX_CONCURRENCY)),

package/src/peek.ts

@@ -116,7 +116,8 @@ function eventLines(raw: string): PeekLine[] {
 	return out;
 }
 
-function tailLines(path: string, max: number): PeekLine[] {
+/** The whole readable tail, unsliced — the viewport decides what is shown. */
+function tailLines(path: string): PeekLine[] {
 	let text: string;
 	try {
 		text = readTail(path);
@@ -126,7 +127,7 @@ function tailLines(path: string, max: number): PeekLine[] {
 	const lines: PeekLine[] = [];
 	// First line of a mid-file read is usually a fragment — drop it.
 	for (const raw of text.split("\n").slice(1)) lines.push(...eventLines(raw));
-	return lines.slice(-max);
+	return lines;
 }
 
 /** Gutter colour carries the line's role, so the eye can skip to failures without
@@ -172,9 +173,32 @@ export function createPeekPane(
 	let selected = 0;
 	let tailing = false;
 	let confirming = false;
+	/** Rows scrolled back from the newest line. 0 = pinned to live output.
+	 *  A tail that keeps jumping to the bottom while you read is unusable, so any
+	 *  scroll detaches from live and the 700ms poll stops moving the view. */
+	let scrollback = 0;
+	/** Content rows the last render could show — page keys need the real viewport,
+	 *  which only render() knows (it is given the width and derives the height). */
+	let viewport = TAIL_ROWS;
+	/** Tail length at the previous render, to keep a scrolled-back view pinned to
+	 *  the SAME lines as the child appends new ones. Without this the window is
+	 *  anchored to the end of a growing list, so the text you are reading crawls
+	 *  upward every poll. */
+	let lastTotal = 0;
 	const timer = setInterval(requestRender, POLL_MS);
 
 	const clamp = (n: number, len: number) => (len === 0 ? 0 : Math.max(0, Math.min(len - 1, n)));
+	/** Scrolling past either end is a no-op, never a wrap: the newest line is a
+	 *  hard floor, the oldest readable line a hard ceiling. */
+	const scrollBy = (rows: number) => {
+		const task = getTasks()[selected];
+		if (!tailing || !task?.sessionFile) return;
+		const total = tailLines(task.sessionFile).length;
+		// Anchor here as well as in render(): a scroll before the next render would
+		// otherwise be read as "the file grew by its whole length" and jump the view.
+		lastTotal = total;
+		scrollback = Math.max(0, Math.min(Math.max(0, total - viewport), scrollback + rows));
+	};
 
 	/**
 	 * Every row is a full-width bordered line: │ edge, one space of padding, the
@@ -208,7 +232,12 @@ export function createPeekPane(
 			const task = tasks[selected]!;
 			const hint = confirming
 				? theme.fg("error", `abort ${task.agent}?  y / n`)
-				: theme.fg("dim", tailing ? "esc back · x abort" : "shift+↑↓ / jk move · enter tail · x abort · esc close");
+				: theme.fg(
+						"dim",
+						tailing
+							? "↑↓ / jk scroll · ⇧ page · g/G top·live · esc back · x abort"
+							: "shift+↑↓ / jk move · enter tail · x abort · esc close",
+					);
 			// Breadcrumb, not a bare name: while tailing, WHERE you are is the thing you
 			// lose track of first, and the child's status belongs next to its name.
 			const crumb = tailing
@@ -226,9 +255,23 @@ export function createPeekPane(
 				lines.push(row(theme.fg("dim", "(no session file — agent has not started yet)"), width));
 			} else {
 				// ponytail: re-reads the tail each render (700ms poll). A watcher only pays off for files far bigger than a child session.
-				const tail = tailLines(task.sessionFile, TAIL_ROWS);
-				if (tail.length === 0) lines.push(row(theme.fg("dim", "(no activity yet)"), width));
-				for (const line of tail) lines.push(row(renderLine(line, theme), width));
+				const tail = tailLines(task.sessionFile);
+				viewport = TAIL_ROWS;
+				if (scrollback > 0 && lastTotal > 0 && tail.length > lastTotal) scrollback += tail.length - lastTotal;
+				lastTotal = tail.length;
+				// Clamp here too: the readable tail is a sliding 64KB window, so old lines
+				// fall off the front and a deep scrollback would render a blank window.
+				scrollback = Math.max(0, Math.min(Math.max(0, tail.length - viewport), scrollback));
+				const end = tail.length - scrollback;
+				const window = tail.slice(Math.max(0, end - viewport), end);
+				if (window.length === 0) lines.push(row(theme.fg("dim", "(no activity yet)"), width));
+				for (const line of window) lines.push(row(renderLine(line, theme), width));
+				// Scrolled-back views must say so: an unmoving tail is otherwise
+				// indistinguishable from a stalled child.
+				if (scrollback > 0) {
+					lines.push(edgeRow(width, "├", "┤"));
+					lines.push(row(theme.fg("warning", `↑ ${scrollback} older · G / end → live`), width));
+				}
 			}
 			lines.push(edgeRow(width, "╰", "╯"));
 			return lines;
@@ -249,17 +292,32 @@ export function createPeekPane(
 			if (data === "x" || data === "X") {
 				if (tasks[selected]?.running) confirming = true;
 			} else if (matchesKey(data, Key.escape)) {
-				if (tailing) tailing = false;
-				else close();
+				if (tailing) {
+					tailing = false;
+					scrollback = 0; // leaving the tail forgets where you were reading
+				} else close();
 			} else if (matchesKey(data, Key.enter) || matchesKey(data, Key.right)) {
 				tailing = true;
+				scrollback = 0; // a freshly opened tail always starts live
 			} else if (matchesKey(data, Key.left)) {
 				tailing = false;
+				scrollback = 0;
+			} else if (matchesKey(data, Key.pageUp)) {
+				scrollBy(viewport);
+			} else if (matchesKey(data, Key.pageDown)) {
+				scrollBy(-viewport);
+			} else if (data === "g") {
+				scrollBy(Number.MAX_SAFE_INTEGER); // oldest readable line
+			} else if (data === "G" || matchesKey(data, Key.end)) {
+				scrollback = 0; // back to live
 			} else if (matchesKey(data, "shift+up") || matchesKey(data, Key.up) || data === "k") {
+				// In the tail the same keys scroll; in the list they move between agents.
 				// shift+↑↓ and j/k are the reliable pair: bare arrows can be eaten by prompt history.
-				selected = clamp(selected - 1, len);
+				if (tailing) scrollBy(1);
+				else selected = clamp(selected - 1, len);
 			} else if (matchesKey(data, "shift+down") || matchesKey(data, Key.down) || data === "j") {
-				selected = clamp(selected + 1, len);
+				if (tailing) scrollBy(-1);
+				else selected = clamp(selected + 1, len);
 			}
 			requestRender();
 		},

package/src/schemas.ts

@@ -67,9 +67,6 @@ export const SubagentParams = Type.Object({
 			default: true,
 		}),
 	),
-	allowIntercom: Type.Optional(
-		Type.Boolean({ description: "Let children ask you questions, notify you, and message sibling subagents" }),
-	),
 });
 
 /** Derived from the schemas — single source of truth, no hand-maintained mirror. */

package/src/types.ts

@@ -68,7 +68,6 @@ export interface RunSnapshot {
 	id: string;
 	mode: RunMode;
 	status: RunStatus;
-	allowIntercom: boolean;
 	notifyPerTask: boolean;
 	createdAt: number;
 	startedAt?: number;