pi-interactive-shell 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -2,7 +2,33 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
-## [Unreleased]
+## [0.9.0] - 2026-02-23
+
+### Added
+- `examples/skills/codex-5.3-prompting/` skill with GPT-5.3-Codex prompting guide -- self-contained best practices for verbosity control, scope discipline, forced upfront reading, plan mode, mid-task steering, context management, and reasoning effort recommendations.
+- **`interactive-shell:update` event** — All hands-free update callbacks now emit `pi.events.emit("interactive-shell:update", update)` with the full `HandsFreeUpdate` payload. Extensions can listen for quiet, exit, kill, and user-takeover events regardless of which code path started the session (blocking, non-blocking, or reattach).
+- **`triggerTurn` on terminal events** — Non-blocking hands-free sessions now send `pi.sendMessage` with `triggerTurn: true` when the session exits, is killed, or the user takes over. Periodic "running" updates emit only on the event bus (cheap for extensions) without waking the agent.
+
+### Fixed
+- **Quiet detection broken for TUI apps** — Ink-based CLIs (Claude Code, etc.) emit periodic ANSI-only PTY data (cursor blink, frame redraws) that reset the quiet timer on every event, preventing quiet detection from ever triggering. Now filters data through `stripVTControlCharacters` and only resets the quiet timer when there's visible content. Fixed in both the overlay (`overlay-component.ts`) and headless dispatch monitor (`headless-monitor.ts`). Also seeds the quiet timer at startup when `autoExitOnQuiet` is enabled, so sessions that never produce visible output still get killed after the grace period.
+- **Lifecycle guard decoupled from callback** — The overlay used `onHandsFreeUpdate` presence as a proxy for "blocking tool call" to decide whether to unregister sessions on completion. Wiring the callback in non-blocking paths (for event emission) would cause premature session cleanup. Introduced `streamingMode` flag to separate "has update callback" from "should unregister on completion," so non-blocking sessions stay queryable after the callback fires.
+- **`autoExitOnQuiet` broken in interval update mode** — The `onData` handler only reset the quiet timer in `on-quiet` mode, so `autoExitOnQuiet` never fired with `updateMode: "interval"`. Also, the interval timer's safety-net flush unconditionally stopped the quiet timer, preventing `autoExitOnQuiet` from firing if the interval flushed before the quiet threshold. Both fixed: data handler now resets the timer whenever `autoExitOnQuiet` is enabled regardless of update mode, and the interval flush restarts (rather than stops) the quiet timer when `autoExitOnQuiet` is active.
+- **RangeError on narrow terminals** — `render()` computed `width - 2` for border strings without a lower bound, causing `String.prototype.repeat()` to throw with negative counts when terminal width < 4. Clamped in both the main overlay and reattach overlay. Fixes #2.
+- **Hardcoded `~/.pi/agent` path** — Config loading, snapshot writing, and the install script all hardcoded `~/.pi/agent`, ignoring `PI_CODING_AGENT_DIR`. Now uses `getAgentDir()` from pi's API in all runtime paths and reads the env var in the install script. Fixes #1.
+
+### Changed
+- Default `handsFreeQuietThreshold` increased from 5000ms to 8000ms and `autoExitGracePeriod` reduced from 30000ms to 15000ms. Both remain adjustable per-call via `handsFree.quietThreshold` and `handsFree.gracePeriod`, and via config file.
+- Dispatch mode is now the recommended default for delegated Codex runs. Updated `README.md`, `SKILL.md`, `tool-schema.ts`, `examples/skills/codex-cli/SKILL.md`, and all three codex prompt templates to prefer `mode: "dispatch"` over hands-free for fire-and-forget delegations.
+- Rewrote `codex-5.3-prompting` skill from a descriptive model-behavior guide into a directive prompt-construction reference. Cut behavioral comparison, mid-task steering, and context management prose sections; reframed each prompt block with a one-line "include when X" directive so the agent knows what to inject and when.
+- Added "Backwards compatibility hedging" section to `codex-5.3-prompting` skill covering the "cutover" keyword trick -- GPT-5.3-Codex inserts compatibility shims and fallback code even when told not to; using "cutover" + "no backwards compatibility" + "do not preserve legacy code" produces cleaner breaks than vague "don't worry about backwards compatibility" phrasing.
+- Example prompts (`codex-implement-plan`, `codex-review-impl`, `codex-review-plan`) updated for GPT-5.3-Codex: load `codex-5.3-prompting` and `codex-cli` skills instead of fetching the 5.2 guide URL at runtime, added scope fencing instructions to counter 5.3's aggressive refactoring, added "don't ask clarifying questions" and "brief updates" constraints, strengthened `codex-review-plan` to force reading codebase files referenced in the plan and constrain edit scope.
+
+## [0.8.2] - 2026-02-10
+
+### Added
+- `examples/prompts/` with three Codex CLI prompt templates: `codex-review-plan`, `codex-implement-plan`, `codex-review-impl`. Demonstrates a plan → implement → review workflow using meta-prompt generation and interactive shell overlays.
+- `examples/skills/codex-cli/` skill that teaches pi Codex CLI flags, config, sandbox caveats, and interactive_shell usage patterns.
+- README section documenting the workflow pipeline, installation, usage examples, and customization.
 
 ## [0.8.1] - 2026-02-08
 

package/README.md

@@ -49,7 +49,7 @@ Three modes control how the agent engages with a session:
 
 **Hands-free** returns immediately so the agent can do other work, but the agent must poll periodically to discover output and completion. Good for processes the agent needs to monitor and react to mid-flight, like watching build output and sending follow-up commands.
 
-**Dispatch** also returns immediately, but the agent doesn't poll at all. When the session completes — whether by natural exit, quiet detection, timeout, or user intervention — the agent gets woken up with a notification containing the tail output. This is the right mode for delegating a task to a subagent and moving on. Add `background: true` to skip the overlay entirely and run headless.
+**Dispatch** also returns immediately, but the agent doesn't poll at all. When the session completes — whether by natural exit, quiet detection, timeout, or user intervention — the agent gets woken up with a notification containing the tail output. This is the right mode for delegating a task to a subagent and moving on. For fire-and-forget delegated runs and QA checks, prefer dispatch by default. Add `background: true` to skip the overlay entirely and run headless.
 
 ## Quick Start
 
@@ -329,6 +329,82 @@ interactive_shell → node-pty → subprocess
 
 Full PTY. The subprocess thinks it's in a real terminal.
 
+## Example Workflow: Plan, Implement, Review
+
+The `examples/prompts/` directory includes three prompt templates that chain together into a complete development workflow using Codex CLI. Each template instructs pi to gather context, generate a tailored meta prompt based on the [Codex prompting guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md), and launch Codex in an interactive overlay.
+
+### The Pipeline
+
+```
+Write a plan
+    ↓
+/codex-review-plan path/to/plan.md        ← Codex verifies every assumption against the codebase
+    ↓
+/codex-implement-plan path/to/plan.md     ← Codex implements the reviewed plan faithfully
+    ↓
+/codex-review-impl path/to/plan.md        ← Codex reviews the diff against the plan, fixes issues
+```
+
+### Installing the Templates
+
+Copy the prompt templates and Codex CLI skill to your pi config:
+
+```bash
+# Prompt templates (slash commands)
+cp ~/.pi/agent/extensions/interactive-shell/examples/prompts/*.md ~/.pi/agent/prompts/
+
+# Codex CLI skill (teaches pi how to use codex flags, sandbox caveats, etc.)
+cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/codex-cli ~/.pi/agent/skills/
+```
+
+### Usage
+
+Say you have a plan at `docs/auth-redesign-plan.md`:
+
+**Step 1: Review the plan** — Codex reads your plan, then verifies every file path, API shape, data flow, and integration point against the actual codebase. Fixes issues directly in the plan file.
+
+```
+/codex-review-plan docs/auth-redesign-plan.md
+/codex-review-plan docs/auth-redesign-plan.md pay attention to the migration steps
+```
+
+**Step 2: Implement the plan** — Codex reads all relevant code first, then implements bottom-up: shared utilities first, then dependent modules, then integration code. No stubs, no TODOs.
+
+```
+/codex-implement-plan docs/auth-redesign-plan.md
+/codex-implement-plan docs/auth-redesign-plan.md skip test files for now
+```
+
+**Step 3: Review the implementation** — Codex diffs the changes, reads every changed file in full (plus imports and dependents), traces code paths across file boundaries, and fixes every issue it finds. Pass the plan to verify completeness, or omit it to just review the diff.
+
+```
+/codex-review-impl docs/auth-redesign-plan.md              # review diff against plan
+/codex-review-impl docs/auth-redesign-plan.md check cleanup ordering
+/codex-review-impl                                          # just review the diff, no plan
+/codex-review-impl focus on error handling and race conditions
+```
+
+### How They Work
+
+These templates demonstrate a "meta-prompt generation" pattern:
+
+1. **Pi gathers context** — reads the plan, runs git diff, fetches the Codex prompting guide
+2. **Pi generates a calibrated prompt** — tailored to the specific plan/diff, following the guide's best practices
+3. **Pi launches Codex in the overlay** — with explicit flags (`-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`) and hands off control
+
+The user watches Codex work in the overlay and can take over anytime (type to intervene, Ctrl+T to transfer output back to pi, Ctrl+Q for options).
+
+### Customizing
+
+These are starting points. Fork them and adjust:
+
+- **Model/flags** — swap `gpt-5.3-codex` for another model, change reasoning effort
+- **Review criteria** — add project-specific checks (security policies, style rules)
+- **Implementation rules** — change the 500-line file limit, add framework-specific patterns
+- **Other agents** — adapt the pattern for Claude (`claude "prompt"`), Gemini (`gemini -i "prompt"`), or any CLI
+
+See the [pi prompt templates docs](https://github.com/badlogic/pi-mono/) for the full `$1`, `$@` placeholder syntax.
+
 ## Advanced: Multi-Agent Workflows
 
 For orchestrating multi-agent chains (scout → planner → worker → reviewer) with file-based handoff and auto-continue support, see:

package/SKILL.md

@@ -84,6 +84,8 @@ interactive_shell({
 
 Dispatch defaults `autoExitOnQuiet: true`. The agent can still query the sessionId if needed, but doesn't have to.
 
+For fire-and-forget delegated runs (including QA-style delegated checks), prefer dispatch as the default mode.
+
 #### Background Dispatch (Headless)
 No overlay opens. Multiple headless dispatches can run concurrently:
 

package/config.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 export interface InteractiveShellConfig {
 	exitAutoCloseDelay: number;
@@ -52,8 +52,8 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 	// Hands-free mode defaults
 	handsFreeUpdateMode: "on-quiet" as const,
 	handsFreeUpdateInterval: 60000,
-	handsFreeQuietThreshold: 5000,
-	autoExitGracePeriod: 30000,
+	handsFreeQuietThreshold: 8000,
+	autoExitGracePeriod: 15000,
 	handsFreeUpdateMaxChars: 1500,
 	handsFreeMaxTotalChars: 100000,
 	// Query rate limiting (default 60 seconds between queries)
@@ -62,7 +62,7 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 
 export function loadConfig(cwd: string): InteractiveShellConfig {
 	const projectPath = join(cwd, ".pi", "interactive-shell.json");
-	const globalPath = join(homedir(), ".pi", "agent", "interactive-shell.json");
+	const globalPath = join(getAgentDir(), "interactive-shell.json");
 
 	let globalConfig: Partial<InteractiveShellConfig> = {};
 	let projectConfig: Partial<InteractiveShellConfig> = {};

package/examples/prompts/codex-implement-plan.md

@@ -0,0 +1,26 @@
+---
+description: Launch Codex CLI in overlay to fully implement an existing plan/spec document
+---
+Load the `codex-5.3-prompting` and `codex-cli` skills. Then read the plan at `$1`.
+
+Analyze the plan to understand: how many files are created vs modified, whether there's a prescribed implementation order or prerequisites, what existing code is referenced, and roughly how large the implementation is.
+
+Based on the prompting skill's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+
+1. Read and internalize the full plan document. Identify every file to be created, every file to be modified, and any prerequisites or ordering constraints.
+2. Before writing any code, read all existing files that will be modified — in full, not just the sections mentioned in the plan. Also read key files they import from or that import them, to absorb the surrounding patterns, naming conventions, and architecture.
+3. If the plan specifies an implementation order or prerequisites (e.g., "extract module X before building Y"), follow that order exactly. Otherwise, implement bottom-up: shared utilities and types first, then the modules that depend on them, then integration/registration code last.
+4. Implement each piece completely. No stubs, no TODOs, no placeholder comments, no "implement this later" shortcuts. Every function body, every edge case handler, every error path described in the plan must be real code.
+5. Match existing code patterns exactly — same formatting, same import style, same error handling conventions, same naming. Read the surrounding codebase to absorb these patterns before writing. If the plan references patterns from specific files (e.g., "same pattern as X"), read those files and replicate the pattern faithfully.
+6. Stay within scope. Do not refactor, rename, or restructure adjacent code that the plan does not mention. No "while I'm here" improvements. If something adjacent looks wrong, note it in the summary but do not touch it.
+7. Keep files reasonably sized. If a file grows beyond ~500 lines, split it as the plan describes or refactor into logical sub-modules.
+8. After implementing all files, do a self-review pass: re-read the plan from top to bottom and verify every requirement, every edge case, every design decision is addressed in the code. Check for: missing imports, type mismatches, unreachable code paths, inconsistent field names between modules, and any plan requirement that was overlooked.
+9. Do NOT commit or push. Write a summary listing every file created or modified, what was implemented in each, and any plan ambiguities that required judgment calls.
+
+The meta prompt should follow the prompting skill's patterns: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Instruct Codex not to ask clarifying questions about things answerable by reading the plan or codebase — read first, then act. Keep progress updates brief and concrete (no narrating routine file reads or tool calls). Emphasize that the plan has already been thoroughly reviewed — the job is faithful execution, not second-guessing the design. Emphasize scope discipline — GPT-5.3-Codex is aggressive about refactoring adjacent code if not explicitly fenced in.
+
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`.
+
+Use `interactive_shell` with `mode: "dispatch"` for this delegated run (fire-and-forget with completion notification). Do NOT pass sandbox flags in interactive_shell. Dispatch mode only. End turn immediately. Do not poll. Wait for completion notification.
+
+$@

package/examples/prompts/codex-review-impl.md

@@ -0,0 +1,27 @@
+---
+description: Launch Codex CLI in overlay to review implemented code changes (optionally against a plan)
+---
+Load the `codex-5.3-prompting` and `codex-cli` skills. Then determine the review scope:
+
+- If `$1` looks like a file path (contains `/` or ends in `.md`): read it as the plan/spec these changes were based on. The diff scope is uncommitted changes vs HEAD, or if clean, the current branch vs main.
+- Otherwise: no plan file. Diff scope is the same. Treat all of `$@` as additional review context or focus areas.
+
+Run the appropriate git diff to identify which files changed and how many lines are involved. This context helps you generate a better-calibrated meta prompt.
+
+Based on the prompting skill's best practices, the diff scope, and the optional plan, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+
+1. Identify all changed files via git diff, then read every changed file in full — not just the diff hunks. For each changed file, also read the files it imports from and key files that depend on it, to understand integration points and downstream effects.
+2. If a plan/spec was provided, read it and verify the implementation is complete — every requirement addressed, no steps skipped, nothing invented beyond scope, no partial stubs left behind.
+3. Review each changed file for: bugs, logic errors, race conditions, resource leaks (timers, event listeners, file handles, unclosed connections), null/undefined hazards, off-by-one errors, error handling gaps, type mismatches, dead code, unused imports/variables/parameters, unnecessary complexity, and inconsistency with surrounding code patterns and naming conventions.
+4. Trace key code paths end-to-end across function and file boundaries — verify data flows, state transitions, error propagation, and cleanup ordering. Don't evaluate functions in isolation.
+5. Check for missing or inadequate tests, stale documentation, and missing changelog entries.
+6. Fix every issue found with direct code edits. Keep fixes scoped to the actual issues identified — do not expand into refactoring or restructuring code that wasn't flagged in the review. If adjacent code looks problematic, note it in the summary but don't touch it.
+7. After all fixes, write a clear summary listing what was found, what was fixed, and any remaining concerns that require human judgment.
+
+The meta prompt should follow the prompting skill's patterns: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Instruct Codex not to ask clarifying questions — if intent is unclear, read the surrounding code for context instead of asking. Keep progress updates brief and concrete (no narrating routine file reads or tool calls). Emphasize thoroughness — read the actual code deeply before making judgments, question every assumption, and never rubber-stamp. GPT-5.3-Codex moves fast and can skim; the meta prompt must force it to slow down and read carefully before judging.
+
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`.
+
+Use `interactive_shell` with `mode: "dispatch"` for this delegated run (fire-and-forget with completion notification). Do NOT pass sandbox flags in interactive_shell. Dispatch mode only. End turn immediately. Do not poll. Wait for completion notification.
+
+$@

package/examples/prompts/codex-review-plan.md

@@ -0,0 +1,21 @@
+---
+description: Launch Codex CLI in overlay to review an implementation plan against the codebase
+---
+Load the `codex-5.3-prompting` and `codex-cli` skills. Then read the plan at `$1`.
+
+Based on the prompting skill's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+
+1. Read and internalize the full plan. Then read every codebase file the plan references — in full, not just the sections mentioned. Also read key files adjacent to those (imports, dependents) to understand the real state of the code the plan targets.
+2. Systematically review the plan against what the code actually looks like, not what the plan assumes it looks like.
+3. Verify every assumption, file path, API shape, data flow, and integration point mentioned in the plan against the actual codebase.
+4. Check that the plan's approach is logically sound, complete, and accounts for edge cases.
+5. Identify any gaps, contradictions, incorrect assumptions, or missing steps.
+6. Make targeted edits to the plan file to fix issues found, adding inline notes where changes were made. Fix what's wrong — do not restructure or rewrite sections that are correct.
+
+The meta prompt should follow the prompting skill's patterns (clear system context, explicit constraints, step-by-step instructions, expected output format). Instruct Codex not to ask clarifying questions — read the codebase to resolve ambiguities instead of asking. Keep progress updates brief and concrete. GPT-5.3-Codex is eager and may restructure the plan beyond what's needed; constrain edits to actual issues found.
+
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="xhigh" -a never`.
+
+Use `interactive_shell` with `mode: "dispatch"` for this delegated run (fire-and-forget with completion notification). Do NOT pass sandbox flags in interactive_shell. Dispatch mode only. End turn immediately. Do not poll. Wait for completion notification.
+
+$@

package/examples/skills/codex-5.3-prompting/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: codex-5.3-prompting
+description: How to write system prompts and instructions for GPT-5.3-Codex. Use when constructing or tuning prompts targeting Codex 5.3.
+---
+
+# GPT-5.3-Codex Prompting Guide
+
+GPT-5.3-Codex is fast, capable, and eager. It moves quickly and will skip reading, over-refactor, and drift scope if prompts aren't tight. Explicit constraints matter more than with GPT-5.2-Codex. Include the following blocks as needed when constructing system prompts.
+
+## Output shape
+
+Always include. Controls verbosity and response structure.
+
+```
+<output_verbosity_spec>
+- Default: 3-6 sentences or <=5 bullets for typical answers.
+- Simple yes/no questions: <=2 sentences.
+- Complex multi-step or multi-file tasks:
+  - 1 short overview paragraph
+  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
+- Avoid long narrative paragraphs; prefer compact bullets and short sections.
+- Do not rephrase the user's request unless it changes semantics.
+</output_verbosity_spec>
+```
+
+## Scope constraints
+
+Always include. GPT-5.3-Codex will add features, refactor adjacent code, and invent UI elements if you don't fence it in.
+
+```
+<design_and_scope_constraints>
+- Explore any existing design systems and understand them deeply.
+- Implement EXACTLY and ONLY what the user requests.
+- No extra features, no added components, no UX embellishments.
+- Style aligned to the design system at hand.
+- Do NOT invent colors, shadows, tokens, animations, or new UI elements unless requested or necessary.
+- If any instruction is ambiguous, choose the simplest valid interpretation.
+</design_and_scope_constraints>
+```
+
+## Context loading
+
+Always include. GPT-5.3-Codex skips reading and starts writing if you don't force it.
+
+```
+<context_loading>
+- Read ALL files that will be modified -- in full, not just the sections mentioned in the task.
+- Also read key files they import from or that depend on them.
+- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
+- Do not ask clarifying questions about things that are answerable by reading the codebase.
+</context_loading>
+```
+
+## Plan-first mode
+
+Include for multi-file work, large refactors, or any task with ordering dependencies.
+
+```
+<plan_first>
+- Before writing any code, produce a brief implementation plan:
+  - Files to create vs. modify
+  - Implementation order and prerequisites
+  - Key design decisions and edge cases
+  - Acceptance criteria for "done"
+- Get the plan right first. Then implement step by step following the plan.
+- If the plan is provided externally, follow it faithfully -- the job is execution, not second-guessing the design.
+</plan_first>
+```
+
+## Long-context handling
+
+Include when inputs exceed ~10k tokens (multi-chapter docs, long threads, multiple PDFs).
+
+```
+<long_context_handling>
+- For inputs longer than ~10k tokens:
+  - First, produce a short internal outline of the key sections relevant to the task.
+  - Re-state the constraints explicitly before answering.
+  - Anchor claims to sections ("In the 'Data Retention' section...") rather than speaking generically.
+- If the answer depends on fine details (dates, thresholds, clauses), quote or paraphrase them.
+</long_context_handling>
+```
+
+## Uncertainty and ambiguity
+
+Include when the task involves underspecified requirements or hallucination-prone domains.
+
+```
+<uncertainty_and_ambiguity>
+- If the question is ambiguous or underspecified:
+  - Ask up to 1-3 precise clarifying questions, OR
+  - Present 2-3 plausible interpretations with clearly labeled assumptions.
+- Never fabricate exact figures, line numbers, or external references when uncertain.
+- When unsure, prefer "Based on the provided context..." over absolute claims.
+</uncertainty_and_ambiguity>
+```
+
+## User updates
+
+Include for agentic / long-running tasks.
+
+```
+<user_updates_spec>
+- Send brief updates (1-2 sentences) only when:
+  - You start a new major phase of work, or
+  - You discover something that changes the plan.
+- Avoid narrating routine tool calls ("reading file...", "running tests...").
+- Each update must include at least one concrete outcome ("Found X", "Confirmed Y", "Updated Z").
+- Do not expand the task beyond what was asked; if you notice new work, call it out as optional.
+</user_updates_spec>
+```
+
+## Tool usage
+
+Include when the prompt involves tool-calling agents.
+
+```
+<tool_usage_rules>
+- Prefer tools over internal knowledge whenever:
+  - You need fresh or user-specific data (tickets, orders, configs, logs).
+  - You reference specific IDs, URLs, or document titles.
+- Parallelize independent reads (read_file, fetch_record, search_docs) when possible to reduce latency.
+- After any write/update tool call, briefly restate:
+  - What changed
+  - Where (ID or path)
+  - Any follow-up validation performed
+</tool_usage_rules>
+```
+
+## Reasoning effort
+
+Set `model_reasoning_effort` via Codex CLI: `-c model_reasoning_effort="high"`
+
+| Task type | Effort |
+|---|---|
+| Simple code generation, formatting | `low` or `medium` |
+| Standard implementation from clear specs | `high` |
+| Complex refactors, plan review, architecture | `xhigh` |
+| Code review (thorough) | `high` or `xhigh` |
+
+## Backwards compatibility hedging
+
+GPT-5.3-Codex has a strong tendency to preserve old patterns, add compatibility shims, and provide fallback code "just in case" -- even when explicitly told not to worry about backwards compatibility. Vague instructions like "don't worry about backwards compatibility" get interpreted weakly; the model may still hedge.
+
+Use **"cutover"** to signal a clean, irreversible break. It's a precise industry term that conveys finality and intentional deprecation -- no dual-support phase, no gradual migration, no preserving old behavior.
+
+Instead of:
+> "Rewrite this and don't worry about backwards compatibility"
+
+Say:
+> "This is a cutover. No backwards compatibility. Rewrite using only Python 3.12+ features and current best practices. Do not preserve legacy code, polyfills, or deprecated patterns."
+
+## Quick reference
+
+- **Force reading first.** "Read all necessary files before you ask any dumb question."
+- **Use plan mode.** Draft the full task with acceptance criteria before implementing.
+- **Steer aggressively mid-task.** GPT-5.3-Codex handles redirects without losing context. Be direct: "Stop. Fix the actual cause." / "Simplest valid implementation only."
+- **Constrain scope hard.** GPT-5.3-Codex will refactor aggressively if you don't fence it in.
+- **Watch context burn.** Faster model = faster context consumption. Start fresh at ~40%.
+- **Use domain jargon.** "Cutover," "golden-path," "no fallbacks," "domain split" get cleaner, faster responses.
+- **Download libraries locally.** Tell it to read them for better context than relying on training data.

package/examples/skills/codex-cli/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: codex-cli
+description: OpenAI Codex CLI reference. Use when running codex in interactive_shell overlay or when user asks about codex CLI options.
+---
+
+# Codex CLI (OpenAI)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `codex` | Start interactive TUI |
+| `codex "prompt"` | TUI with initial prompt |
+| `codex exec "prompt"` | Non-interactive (headless), streams to stdout. Supports `--output-schema <file>` for structured JSON output |
+| `codex e "prompt"` | Shorthand for exec |
+| `codex login` | Authenticate (OAuth, device auth, or API key) |
+| `codex login status` | Show auth mode |
+| `codex logout` | Remove credentials |
+| `codex mcp` | Manage MCP servers |
+| `codex completion` | Generate shell completions |
+
+## Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `-m, --model <model>` | Switch model (default: `gpt-5.3-codex`) |
+| `-c <key=value>` | Override config.toml values (dotted paths, parsed as TOML) |
+| `-p, --profile <name>` | Use config profile from config.toml |
+| `-s, --sandbox <mode>` | Sandbox policy: `read-only`, `workspace-write`, `danger-full-access` |
+| `-a, --ask-for-approval <policy>` | `untrusted`, `on-failure`, `on-request`, `never` |
+| `--full-auto` | Alias for `-a on-request --sandbox workspace-write` |
+| `--search` | Enable live web search tool |
+| `-i, --image <file>` | Attach image(s) to initial prompt |
+| `--add-dir <dir>` | Additional writable directories |
+| `-C, --cd <dir>` | Set working root directory |
+| `--no-alt-screen` | Inline mode (preserve terminal scrollback) |
+
+## Sandbox Modes
+
+- `read-only` - Can only read files
+- `workspace-write` - Can write to workspace
+- `danger-full-access` - Full system access (use with caution)
+
+## Features
+
+- **Image inputs** - Accepts screenshots and design specs
+- **Code review** - Reviews changes before commit
+- **Web search** - Can search for information
+- **MCP integration** - Third-party tool support
+
+## Config
+
+Config file: `~/.codex/config.toml`
+
+Key config values (set in file or override with `-c`):
+- `model` -- model name (e.g., `gpt-5.3-codex`)
+- `model_reasoning_effort` -- `low`, `medium`, `high`, `xhigh`
+- `model_reasoning_summary` -- `detailed`, `concise`, `none`
+- `model_verbosity` -- `low`, `medium`, `high`
+- `profile` -- default profile name
+- `tool_output_token_limit` -- max tokens per tool output
+
+Define profiles for different projects/modes with `[profiles.<name>]` sections. Override at runtime with `-p <name>` or `-c model_reasoning_effort="high"`.
+
+## In interactive_shell
+
+Do NOT pass `-s` / `--sandbox` flags. Codex's `read-only` and `workspace-write` sandbox modes apply OS-level filesystem restrictions that break basic shell operations inside the PTY -- zsh can't even create temp files for here-documents, so every write attempt fails with "operation not permitted." The interactive shell overlay already provides supervision (user watches in real-time, Ctrl+Q to kill, Ctrl+T to transfer output), making Codex's sandbox redundant.
+
+Use explicit flags to control model and behavior per-run.
+
+For delegated fire-and-forget runs, prefer `mode: "dispatch"` so the agent is notified automatically when Codex completes.
+
+```typescript
+// Delegated run with completion notification (recommended default)
+interactive_shell({
+  command: 'codex -m gpt-5.3-codex -a never "Review this codebase for security issues"',
+  mode: "dispatch"
+})
+
+// Override reasoning effort for a single delegated run
+interactive_shell({
+  command: 'codex -m gpt-5.3-codex -c model_reasoning_effort="xhigh" -a never "Complex refactor task"',
+  mode: "dispatch"
+})
+
+// Headless - use bash instead
+bash({ command: 'codex exec "summarize the repo"' })
+```

package/headless-monitor.ts

@@ -1,3 +1,4 @@
+import { stripVTControlCharacters } from "node:util";
 import type { PtyTerminalSession } from "./pty-session.js";
 import type { InteractiveShellConfig } from "./config.js";
 
@@ -40,6 +41,10 @@ export class HeadlessDispatchMonitor {
 	) {
 		this.subscribe();
 
+		if (options.autoExitOnQuiet) {
+			this.resetQuietTimer();
+		}
+
 		if (options.timeout && options.timeout > 0) {
 			this.timeoutTimer = setTimeout(() => {
 				this.handleCompletion(null, undefined, true);
@@ -57,9 +62,12 @@ export class HeadlessDispatchMonitor {
 
 	private subscribe(): void {
 		this.unsubscribe();
-		this.unsubData = this.session.addDataListener(() => {
+		this.unsubData = this.session.addDataListener((data) => {
 			if (this.options.autoExitOnQuiet) {
-				this.resetQuietTimer();
+				const visible = stripVTControlCharacters(data);
+				if (visible.trim().length > 0) {
+					this.resetQuietTimer();
+				}
 			}
 		});
 		this.unsubExit = this.session.addExitListener((exitCode, signal) => {

package/index.ts

@@ -3,7 +3,7 @@ import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { InteractiveShellOverlay } from "./overlay-component.js";
 import { ReattachOverlay } from "./reattach-overlay.js";
 import { PtyTerminalSession } from "./pty-session.js";
-import type { InteractiveShellResult } from "./types.js";
+import type { InteractiveShellResult, HandsFreeUpdate } from "./types.js";
 import { sessionManager, generateSessionId, releaseSessionId } from "./session-manager.js";
 import type { OutputOptions, OutputResult } from "./session-manager.js";
 import { loadConfig } from "./config.js";
@@ -134,6 +134,36 @@ function registerHeadlessActive(
 	});
 }
 
+function makeNonBlockingUpdateHandler(pi: ExtensionAPI): (update: HandsFreeUpdate) => void {
+	return (update) => {
+		pi.events.emit("interactive-shell:update", update);
+
+		if (update.status !== "running") {
+			const tail = update.tail.length > 0 ? `\n\n${update.tail.join("\n")}` : "";
+			let statusLine: string;
+			switch (update.status) {
+				case "exited":
+					statusLine = `Session ${update.sessionId} exited (${formatDurationMs(update.runtime)})`;
+					break;
+				case "killed":
+					statusLine = `Session ${update.sessionId} killed (${formatDurationMs(update.runtime)})`;
+					break;
+				case "user-takeover":
+					statusLine = `Session ${update.sessionId}: user took over (${formatDurationMs(update.runtime)})`;
+					break;
+				default:
+					statusLine = `Session ${update.sessionId} update (${formatDurationMs(update.runtime)})`;
+			}
+			pi.sendMessage({
+				customType: "interactive-shell-update",
+				content: statusLine + tail,
+				display: true,
+				details: update,
+			}, { triggerTurn: true });
+		}
+	};
+}
+
 let bgWidgetCleanup: (() => void) | null = null;
 
 function setupBackgroundWidget(ctx: { ui: { setWidget: Function }; hasUI?: boolean }) {
@@ -495,6 +525,9 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 								? handsFree?.autoExitOnQuiet !== false
 								: handsFree?.autoExitOnQuiet === true,
 							autoExitGracePeriod: handsFree?.gracePeriod ?? config.autoExitGracePeriod,
+							onHandsFreeUpdate: mode === "hands-free"
+								? makeNonBlockingUpdateHandler(pi)
+								: undefined,
 							handoffPreviewEnabled: handoffPreview?.enabled,
 							handoffPreviewLines: handoffPreview?.lines,
 							handoffPreviewMaxChars: handoffPreview?.maxChars,
@@ -698,6 +731,9 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 								? handsFree?.autoExitOnQuiet !== false
 								: handsFree?.autoExitOnQuiet === true,
 							autoExitGracePeriod: handsFree?.gracePeriod ?? config.autoExitGracePeriod,
+							onHandsFreeUpdate: mode === "hands-free"
+								? makeNonBlockingUpdateHandler(pi)
+								: undefined,
 							handoffPreviewEnabled: handoffPreview?.enabled,
 							handoffPreviewLines: handoffPreview?.lines,
 							handoffPreviewMaxChars: handoffPreview?.maxChars,
@@ -764,6 +800,7 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 							handsFreeMaxTotalChars: handsFree?.maxTotalChars,
 							autoExitOnQuiet: handsFree?.autoExitOnQuiet,
 							autoExitGracePeriod: handsFree?.gracePeriod ?? config.autoExitGracePeriod,
+							streamingMode: mode === "hands-free",
 							onHandsFreeUpdate: mode === "hands-free"
 								? (update) => {
 									let statusText: string;
@@ -774,6 +811,9 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 										case "exited":
 											statusText = `Session ${update.sessionId} exited`;
 											break;
+										case "killed":
+											statusText = `Session ${update.sessionId} killed`;
+											break;
 										default: {
 											const budgetInfo = update.budgetExhausted ? " [budget exhausted]" : "";
 											statusText = `Session ${update.sessionId} running (${formatDurationMs(update.runtime)})${budgetInfo}`;
@@ -794,6 +834,7 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 											userTookOver: update.userTookOver,
 										},
 									});
+									pi.events.emit("interactive-shell:update", update);
 								}
 								: undefined,
 							handoffPreviewEnabled: handoffPreview?.enabled,

package/overlay-component.ts

@@ -1,9 +1,10 @@
 import { mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 import type { Component, Focusable, TUI } from "@mariozechner/pi-tui";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import type { Theme } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { PtyTerminalSession } from "./pty-session.js";
 import { sessionManager, generateSessionId } from "./session-manager.js";
 import type { InteractiveShellConfig } from "./config.js";
@@ -84,11 +85,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const rows = Math.max(3, overlayHeight - (HEADER_LINES + FOOTER_LINES_COMPACT + 2));
 
 		const ptyEvents = {
-			onData: () => {
+			onData: (data: string) => {
 				this.debouncedRender();
-				if (this.state === "hands-free" && this.updateMode === "on-quiet") {
-					this.hasUnsentData = true;
-					this.resetQuietTimer();
+				if (this.state === "hands-free" && (this.updateMode === "on-quiet" || this.options.autoExitOnQuiet)) {
+					const visible = stripVTControlCharacters(data);
+					if (visible.trim().length > 0) {
+						if (this.updateMode === "on-quiet") {
+							this.hasUnsentData = true;
+						}
+						this.resetQuietTimer();
+					}
 				}
 			},
 			onExit: () => {
@@ -427,13 +433,21 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			}
 		}, 2000);
 
+		if (this.options.autoExitOnQuiet) {
+			this.resetQuietTimer();
+		}
+
 		this.handsFreeInterval = setInterval(() => {
 			if (this.state === "hands-free") {
 				if (this.updateMode === "on-quiet") {
 					if (this.hasUnsentData && this.options.onHandsFreeUpdate) {
 						this.emitHandsFreeUpdate();
 						this.hasUnsentData = false;
-						this.stopQuietTimer();
+						if (this.options.autoExitOnQuiet) {
+							this.resetQuietTimer();
+						} else {
+							this.stopQuietTimer();
+						}
 					}
 				} else {
 					this.emitHandsFreeUpdate();
@@ -442,7 +456,6 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		}, this.currentUpdateInterval);
 	}
 
-	/** Reset the quiet timer - called on each data event in on-quiet mode */
 	private resetQuietTimer(): void {
 		this.stopQuietTimer();
 		this.quietTimer = setTimeout(() => {
@@ -510,7 +523,11 @@ export class InteractiveShellOverlay implements Component, Focusable {
 						if (this.hasUnsentData && this.options.onHandsFreeUpdate) {
 							this.emitHandsFreeUpdate();
 							this.hasUnsentData = false;
-							this.stopQuietTimer();
+							if (this.options.autoExitOnQuiet) {
+								this.resetQuietTimer();
+							} else {
+								this.stopQuietTimer();
+							}
 						}
 					} else {
 						this.emitHandsFreeUpdate();
@@ -526,9 +543,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		if (clamped === this.currentQuietThreshold) return;
 		this.currentQuietThreshold = clamped;
 
-		// If a quiet timer is active, restart it with the new threshold
-		// Use resetQuietTimer to ensure autoExitOnQuiet logic is included
-		if (this.quietTimer && this.updateMode === "on-quiet") {
+		if (this.quietTimer) {
 			this.resetQuietTimer();
 		}
 	}
@@ -624,8 +639,6 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.state = "running";
 		this.userTookOver = true;
 
-		// Notify agent that user took over (streaming mode)
-		// In non-blocking mode, keep session registered so agent can query status
 		if (this.options.onHandsFreeUpdate) {
 			this.options.onHandsFreeUpdate({
 				status: "user-takeover",
@@ -637,11 +650,12 @@ export class InteractiveShellOverlay implements Component, Focusable {
 				totalCharsSent: this.totalCharsSent,
 				budgetExhausted: this.budgetExhausted,
 			});
-			// Unregister and release ID in streaming mode - agent got notified, won't query
+		}
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query and see "user-takeover" status
 
 		this.tui.requestRender();
 	}
@@ -705,7 +719,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const maxChars = this.options.handoffSnapshotMaxChars ?? this.config.handoffSnapshotMaxChars;
 		if (lines <= 0 || maxChars <= 0) return undefined;
 
-		const baseDir = join(homedir(), ".pi", "agent", "cache", "interactive-shell");
+		const baseDir = join(getAgentDir(), "cache", "interactive-shell");
 		mkdirSync(baseDir, { recursive: true });
 
 		const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -761,10 +775,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		// In streaming mode, unregister now since agent got final update.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -801,10 +814,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		// Use releaseId=false because the background session now owns the ID.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. releaseId=false because background owns the ID.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(false);
 		}
 
@@ -836,9 +848,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -875,9 +887,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -929,9 +941,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -1040,6 +1052,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	}
 
 	render(width: number): string[] {
+		width = Math.max(4, width);
 		const th = this.theme;
 		const border = (s: string) => th.fg("border", s);
 		const accent = (s: string) => th.fg("accent", s);
@@ -1176,10 +1189,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		if (!this.completionResult) {
 			this.session.kill();
 			this.session.dispose();
-			// Release ID since session is dead and agent can't query anymore
 			this.unregisterActiveSession(true);
-		} else if (this.options.onHandsFreeUpdate) {
-			// Streaming mode already delivered result, safe to unregister and release
+		} else if (this.options.streamingMode) {
+			// Streaming mode already delivered result via tool return, safe to clean up
 			this.unregisterActiveSession(true);
 		}
 		// Non-blocking mode with completion: keep registered so agent can query

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "headless-monitor.ts",
     "types.ts",
     "scripts/",
+    "examples/",
     "banner.png",
     "README.md",
     "SKILL.md",

package/reattach-overlay.ts

@@ -1,9 +1,9 @@
 import { mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import type { Component, Focusable, TUI } from "@mariozechner/pi-tui";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import type { Theme } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { PtyTerminalSession } from "./pty-session.js";
 import { sessionManager } from "./session-manager.js";
 import type { InteractiveShellConfig } from "./config.js";
@@ -156,7 +156,7 @@ export class ReattachOverlay implements Component, Focusable {
 		const maxChars = this.config.handoffSnapshotMaxChars;
 		if (lines <= 0 || maxChars <= 0) return undefined;
 
-		const baseDir = join(homedir(), ".pi", "agent", "cache", "interactive-shell");
+		const baseDir = join(getAgentDir(), "cache", "interactive-shell");
 		mkdirSync(baseDir, { recursive: true });
 
 		const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -358,6 +358,7 @@ export class ReattachOverlay implements Component, Focusable {
 	}
 
 	render(width: number): string[] {
+		width = Math.max(4, width);
 		const th = this.theme;
 		const border = (s: string) => th.fg("border", s);
 		const accent = (s: string) => th.fg("accent", s);

package/scripts/install.js

@@ -9,8 +9,19 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 
-const EXTENSION_DIR = join(homedir(), ".pi", "agent", "extensions", "interactive-shell");
-const SKILL_DIR = join(homedir(), ".pi", "agent", "skills", "interactive-shell");
+function getAgentDir() {
+	const envDir = process.env.PI_CODING_AGENT_DIR;
+	if (envDir) {
+		if (envDir === "~") return homedir();
+		if (envDir.startsWith("~/")) return homedir() + envDir.slice(1);
+		return envDir;
+	}
+	return join(homedir(), ".pi", "agent");
+}
+
+const agentDir = getAgentDir();
+const EXTENSION_DIR = join(agentDir, "extensions", "interactive-shell");
+const SKILL_DIR = join(agentDir, "skills", "interactive-shell");
 
 function log(msg) {
 	console.log(`[pi-interactive-shell] ${msg}`);

package/tool-schema.ts

@@ -14,6 +14,10 @@ MODES:
 - hands-free: Agent monitors with periodic updates, user can take over anytime by typing
 - dispatch: Agent is notified on completion via triggerTurn (no polling needed)
 
+RECOMMENDED DEFAULT FOR DELEGATED TASKS:
+- For fire-and-forget delegations and QA-style checks, prefer mode="dispatch".
+- Dispatch is the safest choice when the agent should continue immediately and be notified automatically on completion.
+
 The user will see the process in an overlay. They can:
 - Watch output in real-time
 - Scroll through output (Shift+Up/Down)
@@ -234,10 +238,10 @@ export const toolParameters = Type.Object({
 				Type.Number({ description: "Max interval between updates in ms (default: 60000)" }),
 			),
 			quietThreshold: Type.Optional(
-				Type.Number({ description: "Silence duration before emitting update in on-quiet mode (default: 5000ms)" }),
+				Type.Number({ description: "Silence duration before emitting update in on-quiet mode (default: 8000ms)" }),
 			),
 			gracePeriod: Type.Optional(
-				Type.Number({ description: "Startup grace period before autoExitOnQuiet can kill the session (default: 30000ms)" }),
+				Type.Number({ description: "Startup grace period before autoExitOnQuiet can kill the session (default: 15000ms)" }),
 			),
 			updateMaxChars: Type.Optional(
 				Type.Number({ description: "Max chars per update (default: 1500)" }),

package/types.ts

@@ -73,6 +73,9 @@ export interface InteractiveShellOptions {
 	autoExitGracePeriod?: number;
 	// Auto-kill timeout
 	timeout?: number;
+	// When true, unregister active session on completion (blocking tool call path).
+	// When false/undefined, keep registered so agent can query result later.
+	streamingMode?: boolean;
 	// Existing PTY session (for attach flow -- skip creating a new PTY)
 	existingSession?: import("./pty-session.js").PtyTerminalSession;
 }