pi-agent-flow 1.6.0 → 1.7.1

package/README.md

@@ -31,7 +31,7 @@ Then start Pi and delegate tasks using flow states.
 
 ```shell
 # Install from a local clone
-git clone https://github.com/your-org/pi-agent-flow.git
+git clone https://github.com/tuanhung303/pi-agent-flow.git
 cd pi-agent-flow
 pi install .
 ```
@@ -45,18 +45,25 @@ pi install .
 - **Flow-state delegation** — six bundled specialist flows (`scout`, `debug`, `build`, `craft`, `audit`, `ideas`) plus custom flows via Markdown front-matter
 - **Isolated forked context** — each flow runs as an isolated `pi` child process with a session snapshot (or clean slate when configured)
 - **Parallel execution** — batch independent flows into one call with bounded concurrency
-- **Structured reports** — every flow returns `[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`
+- **Structured reports** — every flow returns `[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`; optional JSON schema with files, actions, commands, and reasoning
+- **Mechanically enriched commands** — bash commands in structured output are replaced with exact verbatim tool-call strings and annotated with `executionTime`
 - **Depth guards** — configurable max delegation depth (default: `3`)
-- **Session timeout modes** — child flows use controlled budgets: `fast` (300s), `default` (600s), or `long` (900s)
+- **Session timeout modes** — child flows use controlled budgets: `fast` (300s), `default` (600s), `long` (900s), or `extreme_long` (1200s)
+- **Two-stage timeout awareness** — flows receive deadline hints in their prompt; the parent UI shows live countdowns and injects warning reminders before hard kill
+- **Graceful shutdown** — parent `SIGINT`/`SIGTERM` propagates to all child process groups; orphaned sub-agents are force-killed after a grace period
 - **Cycle prevention** — blocks re-entering flows already in the ancestor stack
 - **Model tiering & failover** — flows map to `lite` / `flash` / `full` tiers with primary + failover model chains
+- **Persistent flow mode** — switch global model strategies with `--flow-mode`; written to `settings.json` and remembered across sessions
+- **Flow-mode notification** — concise (`mode: name | lite: model · flash: model · full: model`) or verbose (with per-tier flow-name labels) startup message
+- **Auto-transition** — opt-in automatic queuing of follow-up flows based on the declarative transition matrix
 - **Unified batch tools** — `batch` (read/write/edit/delete) and `batch_read` replace separate file tools for cross-cutting work
 - **Web tool** — built-in `web` search (Brave + DuckDuckGo) and page fetch with HTML→Markdown conversion
 - **Sliding system prompt** — lightweight routing reminder injected before each user message, stripped from child snapshots to avoid duplication
-- **Session snapshot sanitization** — removes sliding prompts, reasoning/thinking artifacts, and non-inheritable content before forking
+- **Session snapshot sanitization** — removes sliding prompts, reasoning/thinking artifacts, and non-inheritable content before forking; compresses prior flow results into compact context maps
+- **Shared context inheritance** — child flows receive the parent's sanitized session automatically; write forward-looking intents and let the child pick up context from its inherited snapshot
 - **Project flow confirmation** — prompts before running project-local flows from `.pi/agents/` for security
 - **Post-flow hooks** — automatic advisory messages suggesting follow-up flows (e.g., `build → audit`)
-- **Rich TUI rendering** — collapsed activity-panel view with per-flow stats, plus expanded view with full reports and tool traces
+- **Rich TUI rendering** — collapsed activity-panel view with per-flow stats, live countdowns, and expanded view with full reports and tool traces
 - **Smooth streaming metrics** — token counters and smoothed TPS increment tick-by-tick during active streaming
 
 ---
@@ -76,15 +83,46 @@ The result is faster, cheaper, and cleaner delegation: the main agent remains un
 
 ---
 
+## Shared Context
+
+When you delegate to a flow, the child agent receives an automatic **sanitized fork** of your current session. This lets you write concise intents that focus on **what new work to do** rather than restating the full problem.
+
+### How it works
+
+1. **Snapshot serialized** — your conversation (files read, commands run, prior flow results) is serialized into a JSONL snapshot.
+2. **Sanitized** — sliding prompts, reasoning/thinking artifacts, and other non-inheritable content are stripped.
+3. **Compressed** — prior flow tool results are compacted into short summaries: files touched, commands used, outcome status.
+4. **Forked** — the child agent loads this snapshot via `--session` at startup.
+
+### Writing good intents
+
+The child already sees what you've done. Write intents that say **what to do next**, not what context it needs:
+
+| ❌ Bad intent | ✅ Good intent |
+|---|---|
+| `"The auth module uses JWT tokens… inspect src/auth/ for security issues"` | `"Audit the auth module for security issues"` |
+| `"We already found the bug… run the failing test and fix it"` | `"Fix the failing test in tests/auth.test.ts"` |
+| `"The file structure is… implement the feature described in the PRD"` | `"Implement the feature described in the PRD"` |
+
+### Clean slate
+
+Set `inheritContext: false` in a custom flow's front-matter to start with a clean slate. The child receives only your `intent` — no inherited session. This is ideal for unbiased creative work in `ideas` flows.
+
+### What the child sees
+
+The child's `<context-seal>` prompt tells it: *"The conversation above is sealed — it is your session history for situational awareness only."* The child can reference files and findings already in context but shouldn't act as if it's still in the parent's conversation.
+
+---
+
 ## Bundled Flows
 
 | Flow | Purpose | Tools | Tier |
 |------|---------|-------|------|
 | `[scout]` | Discover files, trace code paths, map architecture | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
-| `[debug]` | Investigate logs, errors, stack traces, root causes, and update relevant troubleshooting docs | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
-| `[build]` | Implement features, fix bugs, write tests, update relevant docs, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
+| `[debug]` | Investigate logs, errors, stack traces, root causes | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
+| `[build]` | Implement features, fix bugs, write tests, update docs, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
 | `[craft]` | Plan structure, break down requirements, design solutions | `batch`, `bash`, `find`, `grep`, `ls` | `full` |
-| `[audit]` | Audit security, quality, correctness; fix issues autonomously | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
+| `[audit]` | Audit security, quality, correctness; fix safe issues autonomously | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
 | `[ideas]` | Generate ideas and explore possibilities with inherited context | `batch`, `bash` | `full` |
 
 > **Note:** All bundled flows have `maxDepth: 0`, meaning they do not delegate further by default. Custom flows can override this via front-matter.
@@ -102,6 +140,7 @@ Each flow call may set `sessionMode` to choose the child-agent time budget:
 | `fast` | 300s | quick scouting, narrow checks, small design passes |
 | `default` | 600s | normal flow work; this is the default |
 | `long` | 900s | large builds, full test runs, broad refactors, complex debugging |
+| `extreme_long` | 1200s | very large refactors, extensive audits, or multi-step debugging sessions |
 
 Example:
 
@@ -120,6 +159,16 @@ Example:
 
 The public interface is mode-based; arbitrary per-flow numeric timeouts are not exposed.
 
+### Timeout behavior
+
+Flows are aware of their deadline from the moment they start:
+
+- **Prompt injection** — the activation block includes the exact time budget and warns the agent to wrap up before the deadline.
+- **Parent UI countdown** — a live `MM:SS` countdown is shown next to the flow's aim while it runs.
+- **Two-stage warnings** — at 2 minutes before hard timeout a warning is injected into the child's reminder stream; at 2 minutes 15 seconds a final urge demands the agent stop all tool use and output structured findings.
+- **Grace period** — after the hard timeout fires, the agent gets a 90-second reporting grace to finish its summary before the process is force-killed.
+- **Graceful shutdown** — when the parent receives `SIGINT` or `SIGTERM`, the signal propagates to every child process group so sub-agents terminate cleanly instead of becoming orphans.
+
 ---
 
 ## Flow Definitions
@@ -165,24 +214,72 @@ flow [myflow] accomplished
 | `thinking` | `string` | Thinking budget (e.g., `"low"`, `"medium"`, `"high"`) |
 | `maxDepth` | `number` | How many more delegation levels this flow may spawn |
 | `inheritContext` | `boolean` | Whether to fork parent session snapshot (`true`) or start clean (`false`) |
+| `tier` | `string` | Explicit tier override: `lite`, `flash`, or `full` |
 
 ---
 
-## Post-Flow Hooks
+## Structured Output
+
+When `structuredOutput` is enabled (default), flows are instructed to append a JSON code block to their final response. The block is mechanically validated and enriched:
+
+- **Bash commands** are replaced with the exact verbatim strings from the actual tool calls, fixing the common LLM behaviour of paraphrasing `curl -s -X POST …` as `"curl GAWA baseline"`.
+- **Execution time** is captured from the timed-bash wrapper and attached to each bash command entry.
 
-When certain flows complete successfully, the system injects advisory messages suggesting follow-up flows. This keeps the agent on the optimal path without requiring the user to manually chain flows.
+Schema:
 
-### Built-in Hooks
+```json
+{
+  "version": "1.0",
+  "status": "complete",
+  "summary": "2-3 sentence summary",
+  "files": [
+    { "path": "relative/path", "role": "read", "description": "why it matters", "snippet": "short excerpt", "ranges": [{ "start": 10, "end": 25, "label": "bug" }] }
+  ],
+  "actions": [
+    { "type": "read", "description": "what was done", "target": "file.ts", "result": "success", "evidence": "output or proof" }
+  ],
+  "commands": [
+    { "command": "curl -s -X POST https://api.example.com/v1/data", "tool": "bash", "executionTime": "1.2s (normal)" }
+  ],
+  "notDone": [
+    { "item": "unfinished work", "reason": "why it was not completed", "blocker": "blocking issue", "nextStep": "specific follow-up" }
+  ],
+  "nextSteps": ["recommended follow-up action"],
+  "reasoning": ["key hypothesis or inference"],
+  "notes": ["observation or warning"]
+}
+```
+
+Only include fields that have data. Omit empty arrays; missing array fields are acceptable.
 
-| Hook | Trigger | Advice |
-|------|---------|--------|
-| `build → audit` | A `[build]` flow succeeds | *"Consider running an [audit] flow to audit the changes…"* |
-| `debug → build` | A `[debug]` flow succeeds | *"The root cause has been identified. Consider running a [build] flow to implement the fix."* |
-| `audit → scout` | An `[audit]` flow succeeds | *"Audit complete. Consider running a [scout] flow to trace the audit findings across the codebase."* |
+---
+
+## Post-Flow Hooks & Auto-Transitions
+
+When certain flows complete, the system injects advisory messages suggesting follow-up flows. This keeps the agent on the optimal path without requiring the user to manually chain flows.
+
+### Built-in transition matrix
+
+| Source | Target | Condition | Advice |
+|--------|--------|-----------|--------|
+| `scout` | `build` | success | Context mapped. Consider running a [build] flow to implement changes, or [debug] if investigating an issue. |
+| `scout` | `debug` | success | Context mapped. Consider running a [debug] flow if investigating an issue. |
+| `debug` | `build` | success | The root cause has been identified. Consider running a [build] flow to implement the fix. |
+| `debug` | `audit` | success | Root cause identified. Consider running an [audit] flow to verify the fix area for related issues. |
+| `build` | `audit` | success | Consider running an [audit] flow to audit the changes for security, correctness, and code quality. |
+| `build` | `debug` | failure | Build failed. Consider running a [debug] flow to investigate the root cause. |
+| `audit` | `scout` | success | Audit complete. Consider running a [scout] flow to trace the audit findings across the codebase. |
+| `audit` | `build` | failure | Audit found issues. Consider running a [build] flow to fix them. |
+| `craft` | `build` | success | Plan ready. Consider running a [build] flow to implement the design. |
+| `ideas` | `craft` | success | Ideas explored. Consider running a [craft] flow to design the approach, or [build] to implement directly. |
 
 Hooks are smart: if the agent already included the suggested flow in the same batch, the advisory is suppressed to avoid redundancy.
 
-### Extending
+### Auto-transition
+
+Enable `autoTransition: true` in `flowSettings` (or `--auto-transition`) to automatically queue follow-up flows without manual intervention. The system checks that the target flow exists, was not already requested, and would not create a cycle before queuing it.
+
+### Extending hooks
 
 Hooks are registered via `registerHook()` in `hooks.ts`. Each hook defines a trigger (flow type + success requirement) and an action that returns advisory text.
 
@@ -220,7 +317,7 @@ registerHook({
 }
 ```
 
-### Override working directory for a flow
+### Override working directory or confirm project flows
 
 ```json
 {
@@ -230,13 +327,26 @@ registerHook({
 }
 ```
 
+Suppress the confirmation prompt before running project-local flows:
+
+```json
+{
+  "flow": [
+    { "type": "scout", "intent": "Map packages/ui", "aim": "Map UI package" }
+  ],
+  "confirmProjectFlows": false
+}
+```
+
+
+
 ---
 
 ## Tools
 
 ### `flow` — delegate to flow states
 
-The core delegation tool. Accepts an array of flow tasks and runs them in parallel.
+The core delegation tool. Accepts an array of flow tasks and runs them in parallel with bounded concurrency (default: 4, capped to CPU count).
 
 ### `batch` / `batch_read` — unified file operations
 
@@ -289,16 +399,27 @@ Use `flowModelConfigs` in your Pi settings to define tiered model strategies. Ea
 
 Settings are merged: project `.pi/settings.json` overrides global `~/.pi/agent/settings.json`.
 
+### Persistent flow mode switch
+
 Switch the global active strategy quickly with `--flow-mode`:
 
 ```bash
 pi --flow-mode balance
 pi --flow-mode quality
-pi --flow-mode mimo
 ```
 
 `--flow-mode` updates `flowModelConfig` in global `~/.pi/agent/settings.json` (or `$PI_CODING_AGENT_DIR/settings.json`) and applies the mode immediately for the current invocation. The mode must already exist in the merged `flowModelConfigs`; project `.pi/settings.json` can still override global settings on later no-flag runs.
 
+On startup, the selected mode is printed in a compact notification:
+
+```
+mode: balance | lite: gpt-5.4-mini · flash: gpt-5.5 · full: gpt-5.5
+```
+
+Failover-only tiers are shown as `failover: model-a, model-b`. Verbose mode includes the flow names associated with each tier.
+
+### Flow settings
+
 You can also set flow runtime defaults under `flowSettings`:
 
 ```json
@@ -313,7 +434,15 @@ You can also set flow runtime defaults under `flowSettings`:
 }
 ```
 
-`flowSettings.sessionMode` accepts `fast`, `default`, or `long`. Session mode precedence is:
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `sessionMode` | `default` | Default child-flow session mode: `fast`, `default`, `long`, or `extreme_long` |
+| `maxConcurrency` | `4` | Maximum parallel flows (capped to CPU count) |
+| `toolOptimize` | `true` | Use unified `batch`/`batch_read` instead of separate read/write/edit |
+| `structuredOutput` | `true` | Inject JSON structured-output instructions into flow prompts |
+| `autoTransition` | `false` | Automatically queue follow-up flows based on the transition matrix |
+
+Session mode precedence is:
 
 ```txt
 per-flow sessionMode > --flow-session-mode > PI_FLOW_SESSION_MODE > flowSettings.sessionMode > default
@@ -331,9 +460,13 @@ per-flow sessionMode > --flow-session-mode > PI_FLOW_SESSION_MODE > flowSettings
 | `--flow-lite-model [model]` | Override the lite-tier model | — |
 | `--flow-flash-model [model]` | Override the flash-tier model | — |
 | `--flow-full-model [model]` | Override the full-tier model | — |
-| `--flow-session-mode [mode]` | Default child-flow session mode: `fast`, `default`, or `long` | `default` |
-| `--tool-optimize` | Use unified `batch`/`batch_read` instead of separate read/write/edit | `true` |
-| `--no-tool-optimize` | Disable tool optimization; use legacy read/write/edit tools | — |
+| `--flow-session-mode [mode]` | Default child-flow session mode | `default` |
+| `--flow-max-concurrency [n]` | Maximum parallel flows | `4` |
+| `--tool-optimize` | Use unified `batch`/`batch_read` | `true` |
+| `--no-tool-optimize` | Disable tool optimization; use legacy read/write/edit | — |
+| `--auto-transition` | Automatically queue follow-up flows | `false` |
+| `--structured-output` | Inject structured JSON output instructions | `true` |
+| `--no-structured-output` | Disable structured output injection | — |
 
 ### Environment variables
 
@@ -344,7 +477,9 @@ per-flow sessionMode > --flow-session-mode > PI_FLOW_SESSION_MODE > flowSettings
 | `PI_FLOW_STACK` | JSON array of ancestor flow names |
 | `PI_FLOW_PREVENT_CYCLES` | `"1"` or `"0"` |
 | `PI_FLOW_TOOL_OPTIMIZE` | `"1"` or `"0"` (overrides default tool optimization) |
-| `PI_FLOW_SESSION_MODE` | Default child-flow session mode: `fast`, `default`, or `long` |
+| `PI_FLOW_SESSION_MODE` | Default child-flow session mode: `fast`, `default`, `long`, or `extreme_long` |
+| `PI_FLOW_MAX_CONCURRENCY` | Maximum parallel flows |
+| `PI_FLOW_SPAWN_COMMAND` | Override the spawn command for exotic runtime environments (e.g. bundled with pkg/nexe) |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/flow.ts

@@ -25,10 +25,11 @@ import { DEFAULT_AGENT_SESSION_MODE, getAgentSessionTimeoutMs, type AgentSession
 
 const isWindows = process.platform === "win32";
 const SIGKILL_TIMEOUT_MS = 5000;
+const FINISH_KILL_GRACE_MS = 5_000; // wait 5s after finish() before force-killing the child process
 const AGENT_END_GRACE_MS = 2000;
 const FLOW_TIME_BUDGET_WARNING_MS = 2 * 60 * 1000; // warn 2 min before kill
-const FLOW_FINAL_URGE_MS = 30 * 1000; // final urge 30 s before kill
-const REPORTING_GRACE_MS = 10_000; // grace period after timeout for agent to report findings
+const FLOW_FINAL_URGE_MS = 135 * 1000; // final urge 135 s (2m15s) before kill (increased from 30s for wider summary window)
+const REPORTING_GRACE_MS = 90_000; // grace period after timeout for agent to report findings (increased from 10s to 90s)
 const FLOW_TOOL_SUMMARY_GRACE_MS = FLOW_FINAL_URGE_MS; // bash/tool abort lead time so the agent can summarize
 const FLOW_DEPTH_ENV = "PI_FLOW_DEPTH";
 const FLOW_MAX_DEPTH_ENV = "PI_FLOW_MAX_DEPTH";
@@ -38,6 +39,54 @@ const FLOW_DEADLINE_ENV = "PI_FLOW_DEADLINE_MS";
 const FLOW_TOOL_SUMMARY_GRACE_ENV = "PI_FLOW_TOOL_SUMMARY_GRACE_MS";
 export const FLOW_TOOL_OPTIMIZE_ENV = "PI_FLOW_TOOL_OPTIMIZE";
 const PI_OFFLINE_ENV = "PI_OFFLINE";
+const FLOW_REMINDER_FILE_ENV = "PI_FLOW_REMINDER_FILE";
+
+// ---------------------------------------------------------------------------
+// Global child process group tracking for signal propagation
+// ---------------------------------------------------------------------------
+
+/** Track child process groups so we can kill them on parent exit / signal. */
+const runningChildGroups = new Map<number, { groupPid: number; name: string }>();
+
+/** Register a child process group for cleanup on shutdown. */
+export function registerChildGroup(pid: number, name: string): void {
+	if (pid > 0 && !isWindows) {
+		runningChildGroups.set(pid, { groupPid: pid, name });
+	}
+}
+
+/** Unregister a completed/stopped child process group. */
+export function unregisterChildGroup(pid: number): void {
+	runningChildGroups.delete(pid);
+}
+
+/**
+ * Terminate all registered child process groups via SIGTERM (then SIGKILL after timeout).
+ * Called on parent exit, SIGINT, SIGTERM, or pi-agent-flow:shutdown.
+ */
+export function terminateAllChildGroups(): void {
+	if (runningChildGroups.size === 0) return;
+	const pids = Array.from(runningChildGroups.keys());
+	for (const pid of pids) {
+		try {
+			process.kill(-pid, "SIGTERM");
+		} catch {
+			try { process.kill(pid, "SIGTERM"); } catch { /* gone */ }
+		}
+	}
+	// Hard kill after timeout
+	const sigkillTimer = setTimeout(() => {
+		for (const pid of pids) {
+			try {
+				process.kill(-pid, "SIGKILL");
+			} catch {
+				try { process.kill(pid, "SIGKILL"); } catch { /* gone */ }
+			}
+		}
+		runningChildGroups.clear();
+	}, 5000);
+	sigkillTimer.unref();
+}
 
 type FlowUpdateCallback = (partial: AgentToolResult<FlowDetails>) => void;
 
@@ -109,6 +158,24 @@ function cleanupFlowTempDir(dir: string | null): void {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// Reminder file helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a reminder message to the reminder file so the child agent can see it
+ * via the timed-bash wrapper before its next tool call.
+ * Creates the file if it doesn't exist; appends the message.
+ */
+function writeReminderFile(reminderFilePath: string | null, message: string): void {
+	if (!reminderFilePath) return;
+	try {
+		fs.writeFileSync(reminderFilePath, message + "\n", { encoding: "utf-8", flag: "a" });
+	} catch {
+		/* best-effort */
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Build pi CLI arguments (fork-only)
 // ---------------------------------------------------------------------------
@@ -428,6 +495,15 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		forkSessionTmpPath = forkTmp.filePath;
 	}
 
+	// Create a temp dir for the reminder file so the child agent can read timeout warnings
+	// via the timed-bash wrapper before its next tool call.
+	let reminderTmpDir: string | null = null;
+	let reminderFilePath: string | null = null;
+	if (effectiveTimeout > 0) {
+		reminderTmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-flow-reminder-"));
+		reminderFilePath = path.join(reminderTmpDir, "reminder.txt");
+	}
+
 	try {
 		const piArgs = buildFlowArgs(
 			flow,
@@ -472,13 +548,20 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 					...(effectiveTimeout > 0 ? {
 						[FLOW_DEADLINE_ENV]: String(deadlineAtMs),
 						[FLOW_TOOL_SUMMARY_GRACE_ENV]: String(toolSummaryGraceMs),
+						[FLOW_REMINDER_FILE_ENV]: reminderFilePath ?? "",
 					} : {
 						[FLOW_DEADLINE_ENV]: "",
 						[FLOW_TOOL_SUMMARY_GRACE_ENV]: "0",
+						[FLOW_REMINDER_FILE_ENV]: "",
 					}),
 				},
 			});
 
+			// Register the child process group for global cleanup on signal/exit
+			if (proc.pid !== undefined && !isWindows) {
+				registerChildGroup(proc.pid, normalizedFlowName);
+			}
+
 			let stdinEnded = false;
 			const endStdin = () => {
 				if (stdinEnded) return;
@@ -497,6 +580,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			let timeoutFired = false;
 			let semanticCompletionTimer: NodeJS.Timeout | undefined;
 			let countdownTimer: NodeJS.Timeout | undefined;
+			let finishKillTimer: NodeJS.Timeout | undefined;
 
 			const clearSemanticCompletionTimer = () => {
 				if (semanticCompletionTimer) {
@@ -534,6 +618,13 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				sigkillTimer.unref();
 			};
 
+			const clearFinishKillTimer = () => {
+				if (finishKillTimer) {
+					clearTimeout(finishKillTimer);
+					finishKillTimer = undefined;
+				}
+			};
+
 			const finish = (code: number) => {
 				if (settled) return;
 				settled = true;
@@ -543,6 +634,15 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				if (signal && abortHandler) {
 					signal.removeEventListener("abort", abortHandler);
 				}
+				// Soft-kill: give the child a short grace to exit naturally after stdin close.
+				// If it hasn't closed by then, force-kill to prevent orphaned processes.
+				clearFinishKillTimer();
+				finishKillTimer = setTimeout(() => {
+					if (!didClose) {
+						terminateChild();
+					}
+				}, FINISH_KILL_GRACE_MS);
+				finishKillTimer.unref();
 				resolve(code);
 			};
 
@@ -596,6 +696,10 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 
 			proc.on("close", (code) => {
 				didClose = true;
+				clearFinishKillTimer();
+				if (proc.pid !== undefined) {
+					unregisterChildGroup(proc.pid);
+				}
 				if (buffer.trim()) flushBufferedLines(buffer);
 				finish(code ?? 0);
 			});
@@ -630,13 +734,15 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 						const remainingSec = Math.round(FLOW_TIME_BUDGET_WARNING_MS / 1000);
 						const warnMsg = `\n[Flow warning] ${remainingSec}s remaining before hard timeout. The agent should wrap up now.`;
 						result.stderr += warnMsg;
+						// Write to reminder file so the child agent sees it on its next bash call.
+						writeReminderFile(reminderFilePath, `[Flow warning] ${remainingSec}s remaining before hard timeout. Wrap up your work and output structured findings.`);
 						// Force an update so the parent UI shows the warning immediately.
 						emitUpdate();
 					}, warningMs);
 					warnTimer.unref();
 				}
 
-				// Final urge timer: stronger warning 30 s before hard timeout
+				// Final urge timer: stronger warning 45 s before hard timeout
 				const urgeMs = effectiveTimeout - FLOW_FINAL_URGE_MS;
 				if (urgeMs > 0) {
 					const urgeTimer = setTimeout(() => {
@@ -644,6 +750,8 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 						const remainingSec = Math.round(FLOW_FINAL_URGE_MS / 1000);
 						const urgeMsg = `\n[Flow warning] ${remainingSec}s remaining before hard timeout. Stop all work and output your structured findings.`;
 						result.stderr += urgeMsg;
+						// Write to reminder file so the child agent sees it on its next bash call.
+						writeReminderFile(reminderFilePath, `[Flow urge] ${remainingSec}s remaining before hard timeout. STOP all tool use and output your structured findings NOW.`);
 						emitUpdate();
 					}, urgeMs);
 					urgeTimer.unref();
@@ -692,6 +800,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		return normalized;
 	} finally {
 		cleanupFlowTempDir(forkSessionTmpDir);
+		cleanupFlowTempDir(reminderTmpDir);
 	}
 }
 

package/src/index.ts

@@ -24,7 +24,7 @@ import { getInheritedCliArgs } from "./cli-args.js";
 import { renderFlowCall, renderFlowResult } from "./render.js";
 import { getFlowSummaryText } from "./runner-events.js";
 import { runHooks, runHooksDetailed, getRegisteredHooks, registerHook, unregisterHook } from "./hooks.js";
-import { mapFlowConcurrent, runFlow } from "./flow.js";
+import { mapFlowConcurrent, runFlow, terminateAllChildGroups } from "./flow.js";
 import { executeFlows } from "./executor.js";
 import {
 	type SingleResult,
@@ -100,8 +100,9 @@ const FlowItem = Type.Object({
 			Type.Literal("fast"),
 			Type.Literal("default"),
 			Type.Literal("long"),
+			Type.Literal("extreme_long"),
 		], {
-			description: "Agent session budget for this flow: fast=300s, default=600s, long=900s. Use long only for large builds, broad refactors, full test runs, or complex debugging.",
+			description: "Agent session budget for this flow: fast=300s, default=600s, long=900s, extreme_long=1200s. Use long or extreme_long only when the work genuinely needs the larger budget.",
 		}),
 	),
 });
@@ -110,7 +111,7 @@ const FlowParams = Type.Object({
 	flow: Type.Array(FlowItem, {
 		description:
 			"Array of flow tasks to execute. Each runs in its own forked process. " +
-			"Optional sessionMode selects the child-agent budget: fast=300s, default=600s, long=900s. " +
+			"Optional sessionMode selects the child-agent budget: fast=300s, default=600s, long=900s, extreme_long=1200s. " +
 			'Example: { flow: [{ type: "scout", "intent": "Find all authentication-related code and trace JWT validation", "aim": "Find auth code and trace JWT", "sessionMode": "fast" }, { type: "build", "intent": "Fix the bug in user registration", "aim": "Fix registration bug", "sessionMode": "long" }] }',
 		minItems: 1,
 	}),
@@ -933,6 +934,14 @@ flow [type] accomplished
 
 ### Guards
 - Depth: ${currentDepth}/${maxDepth} | Cycles: ${preventCycles ? "blocked" : "off"} | Stack: ${ancestorFlowStack.length > 0 ? ancestorFlowStack.join(" -> ") : "(root)"}
+
+### Shared Context
+Child flows fork your session automatically:
+
+- They receive a sanitized snapshot of your conversation — files read, commands run, prior flow results.
+- Prior flow tool results are **compressed** into compact summaries (files touched, commands used, status).
+- Write 'intent' as a **forward-looking mission** — reference what the child already sees, don't re-describe it.
+- Set inheritContext: false in a custom flow's front-matter to start with a **clean slate** (no inherited context).
 `,
 		};
 	});
@@ -997,7 +1006,7 @@ flow [type] accomplished
 				"",
 				"Flow states are isolated \u03c0 processes with forked session snapshots. They run in parallel.",
 				'Invoke: { "flow": [{ "type": "scout", "intent": "...", "aim": "...", "sessionMode": "default" }, ...] }',
-				"Session modes: fast=300s, default=600s, long=900s. Use long only when the work genuinely needs the larger budget.",
+				"Session modes: fast=300s, default=600s, long=900s, extreme_long=1200s. Use long or extreme_long only when the work genuinely needs the larger budget.",
 				"States: scout, debug, build, craft, audit, ideas.",
 				"Custom states configs in (create if not exists): .md files in .pi/agents/ or ~/.pi/agent/agents/.",
 			].join("\n"),
@@ -1095,14 +1104,20 @@ flow [type] accomplished
 	}
 
 	// Register cleanup on process exit (once).
-	// We intentionally do NOT hook SIGINT/SIGTERM here. A plugin must not
-	// override the host process signal handling; doing so can cut off the
-	// host's terminal-cleanup logic and leave escape sequences or status
-	// lines visible on Ctrl+C. The 'exit' event fires for normal exits,
-	// including when the host handles the signal and calls process.exit().
+	// We use prependListener on SIGINT/SIGTERM to propagate to child processes
+	// before the host's own signal handler runs. This avoids orphaned sub-agents.
+	// The host handler still runs afterward and handles terminal cleanup.
 	if (!(globalThis as any).__pi_agent_flow_shutdown_registered) {
 		(globalThis as any).__pi_agent_flow_shutdown_registered = true;
+
+		// Propagate signals to child process groups so sub-agents don't become orphans.
+		// We use prependListener so our handler runs first, before the host's cleanup.
+		process.prependListener("SIGINT", terminateAllChildGroups);
+		process.prependListener("SIGTERM", terminateAllChildGroups);
+
+		// Also handle the 'exit' event, which fires when the host calls process.exit().
 		const emitShutdown = () => {
+			terminateAllChildGroups();
 			if (typeof pi.emit === "function") {
 				pi.emit("pi-agent-flow:shutdown", { reason: "process-exit" });
 			}

package/src/session-mode.ts

@@ -1,15 +1,16 @@
-export const AGENT_SESSION_MODES = ["fast", "default", "long"] as const;
+export const AGENT_SESSION_MODES = ["fast", "default", "long", "extreme_long"] as const;
 
 export type AgentSessionMode = typeof AGENT_SESSION_MODES[number];
 
 export const DEFAULT_AGENT_SESSION_MODE: AgentSessionMode = "default";
-export const MAX_AGENT_SESSION_TIMEOUT_MS = 900_000;
+export const MAX_AGENT_SESSION_TIMEOUT_MS = 1_200_000;
 export const PI_FLOW_SESSION_MODE_ENV = "PI_FLOW_SESSION_MODE";
 
 export const AGENT_SESSION_TIMEOUTS_MS: Record<AgentSessionMode, number> = {
 	fast: 300_000,
 	default: 600_000,
-	long: MAX_AGENT_SESSION_TIMEOUT_MS,
+	long: 900_000,
+	extreme_long: MAX_AGENT_SESSION_TIMEOUT_MS,
 };
 
 export function parseAgentSessionMode(value: unknown): AgentSessionMode | undefined {

package/src/sliding-prompt.ts

@@ -22,6 +22,7 @@ export const SLIDING_PROMPT =
 	`You are operating with pi-agent-flow routing.\n` +
 	`If the answer is already in context, answer directly; otherwise delegate to the appropriate flow.\n` +
 	`For git, bash, CLI, or terminal tasks, delegate to [build].\n` +
+	`Child flows inherit your session context — write intents that focus on new work rather than restating what the child already sees.\n` +
 	`${SLIDING_PROMPT_CLOSE_TAG}`;
 
 const SLIDING_PROMPT_RE = new RegExp(

package/src/timed-bash.ts

@@ -13,6 +13,7 @@
  * still active.
  */
 
+import * as fs from "node:fs";
 import { createBashToolDefinition } from "@mariozechner/pi-coding-agent";
 
 export type TimingTier =
@@ -30,6 +31,7 @@ export interface TimingReport {
 
 const FLOW_DEADLINE_ENV = "PI_FLOW_DEADLINE_MS";
 const FLOW_TOOL_SUMMARY_GRACE_ENV = "PI_FLOW_TOOL_SUMMARY_GRACE_MS";
+const FLOW_REMINDER_FILE_ENV = "PI_FLOW_REMINDER_FILE";
 const DEFAULT_FLOW_TOOL_SUMMARY_GRACE_MS = 30_000;
 
 /** Classify duration into user-defined tiers with actionable feedback. */
@@ -87,6 +89,30 @@ function getFlowToolSummaryGraceMs(): number {
 	return parseNonNegativeSafeInteger(process.env[FLOW_TOOL_SUMMARY_GRACE_ENV]) ?? DEFAULT_FLOW_TOOL_SUMMARY_GRACE_MS;
 }
 
+function getFlowReminderFilePath(): string | null {
+	const raw = process.env[FLOW_REMINDER_FILE_ENV];
+	return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+
+/**
+ * Read any pending reminder from the reminder file set by the parent runner.
+ * Returns the reminder text (without trailing newline), or null if no reminder exists.
+ * Clears the file after reading so the agent only sees each reminder once.
+ */
+export function readAndClearReminderFile(): string | null {
+	const filePath = getFlowReminderFilePath();
+	if (!filePath) return null;
+	try {
+		if (!fs.existsSync(filePath)) return null;
+		const content = fs.readFileSync(filePath, { encoding: "utf-8" }).trim();
+		// Clear the file after reading so each reminder is only injected once.
+		try { fs.writeFileSync(filePath, "", { encoding: "utf-8" }); } catch { /* best-effort */ }
+		return content || null;
+	} catch {
+		return null;
+	}
+}
+
 function formatDeadlineAppendix(): string {
 	return "\n\n[Flow timeout] Bash command was interrupted to preserve time for the final flow summary. Stop running tools and return structured findings now.";
 }
@@ -189,6 +215,12 @@ export function createTimedBashToolDefinition(
 		) {
 			const start = Date.now();
 			const deadlineSignal = createDeadlineSignal(signal);
+
+			// Check for pending reminder from parent runner before executing bash.
+			// This allows the parent to inject timeout warnings into the agent's context
+			// via the tool result, since stdin is closed after spawn.
+			const reminderPreamble = readAndClearReminderFile();
+
 			try {
 				const result = await original.execute(
 					toolCallId,
@@ -201,6 +233,10 @@ export function createTimedBashToolDefinition(
 				const report = classifyDuration(duration);
 				const appendix = formatTimingAppendix(report);
 
+				// Inject reminder preamble before timing info so it's the first thing the agent sees.
+				if (reminderPreamble) {
+					appendTextToToolResult(result, `\n\n[REMINDER FROM PARENT] ${reminderPreamble}`);
+				}
 				appendTextToToolResult(result, appendix);
 				if (deadlineSignal.wasDeadlineAbort()) {
 					appendTextToToolResult(result, formatDeadlineAppendix());