micode 0.5.2 → 0.7.0

package/dist/index.js

@@ -9,6 +9,7 @@ var __export = (target, all) => {
       set: (newValue) => all[name] = () => newValue
     });
 };
+var __require = import.meta.require;
 
 // src/agents/brainstormer.ts
 var brainstormerAgent = {
@@ -24,34 +25,50 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
 <critical-rules>
   <rule priority="HIGHEST">ONE QUESTION AT A TIME: Ask exactly ONE question, then STOP and wait for the user's response. NEVER ask multiple questions in a single message. This is the most important rule.</rule>
   <rule>NO CODE: Never write code. Never provide code examples. Design only.</rule>
-  <rule>SUBAGENTS: Spawn multiple in parallel for codebase analysis.</rule>
-  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use subagents instead.</rule>
+  <rule>BACKGROUND TASKS: Use background_task for parallel codebase analysis.</rule>
+  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use background subagents instead.</rule>
 </critical-rules>
 
+<background-tools>
+  <tool name="background_task">Fire subagent tasks that run in parallel. Returns task_id immediately.</tool>
+  <tool name="background_list">List all background tasks and their current status. Use to poll for completion.</tool>
+  <tool name="background_output">Get results from a completed task. Only call after background_list shows task is done.</tool>
+</background-tools>
+
 <available-subagents>
-  <subagent name="codebase-locator" spawn="parallel">
-    Find files, modules, patterns. Spawn multiple with different queries.
-    Examples: "Find authentication code", "Find API routes", "Find config files"
+  <subagent name="codebase-locator" spawn="background_task">
+    Find files, modules, patterns. Fire multiple with different queries.
+    Example: background_task(agent="codebase-locator", prompt="Find authentication code", description="Find auth files")
+  </subagent>
+  <subagent name="codebase-analyzer" spawn="background_task">
+    Deep analysis of specific modules. Fire multiple for different areas.
+    Example: background_task(agent="codebase-analyzer", prompt="Analyze the auth module", description="Analyze auth")
   </subagent>
-  <subagent name="codebase-analyzer" spawn="parallel">
-    Deep analysis of specific modules. Spawn multiple for different areas.
-    Examples: "Analyze the auth module", "Explain the data layer"
+  <subagent name="pattern-finder" spawn="background_task">
+    Find existing patterns in codebase. Fire for different pattern types.
+    Example: background_task(agent="pattern-finder", prompt="Find error handling patterns", description="Find error patterns")
   </subagent>
-  <subagent name="pattern-finder" spawn="parallel">
-    Find existing patterns in codebase. Spawn for different pattern types.
-    Examples: "Find error handling patterns", "Find how similar features are implemented"
+  <subagent name="planner" spawn="Task" when="design approved">
+    Creates detailed implementation plan from validated design.
+    Example: Task(subagent_type="planner", prompt="Create implementation plan for [design path]", description="Create plan")
   </subagent>
 </available-subagents>
 
 <process>
-<phase name="understanding">
-  <action>Spawn subagents in PARALLEL to gather context:</action>
-  <spawn-example>
-    In a SINGLE message, spawn:
-    - codebase-locator: "Find files related to [topic]"
-    - codebase-analyzer: "Analyze existing [related feature]"
-    - pattern-finder: "Find patterns for [similar functionality]"
-  </spawn-example>
+<phase name="understanding" pattern="fire-poll-collect">
+  <action>Fire background tasks in PARALLEL to gather context:</action>
+  <fire-example>
+    In a SINGLE message, fire ALL background tasks:
+    background_task(agent="codebase-locator", prompt="Find files related to [topic]", description="Find [topic] files")
+    background_task(agent="codebase-analyzer", prompt="Analyze existing [related feature]", description="Analyze [feature]")
+    background_task(agent="pattern-finder", prompt="Find patterns for [similar functionality]", description="Find patterns")
+  </fire-example>
+  <poll>
+    background_list()  // repeat until all show "completed" or "error"
+  </poll>
+  <collect>
+    background_output(task_id=...) for each completed task (skip errored tasks)
+  </collect>
   <focus>purpose, constraints, success criteria</focus>
 </phase>
 
@@ -81,16 +98,29 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
   <action>Commit the design document to git</action>
   <action>Ask: "Ready for the planner to create a detailed implementation plan?"</action>
 </phase>
+
+<phase name="handoff" trigger="user approves design">
+  <action>When user says yes/approved/ready, IMMEDIATELY spawn the planner:</action>
+  <spawn>
+    Task(
+      subagent_type="planner",
+      prompt="Create a detailed implementation plan based on the design at thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md",
+      description="Create implementation plan"
+    )
+  </spawn>
+  <rule>Do NOT ask again - if user approved, spawn planner immediately</rule>
+</phase>
 </process>
 
 <principles>
   <principle name="design-only">NO CODE. Describe components, not implementations. Planner writes code.</principle>
-  <principle name="subagents-first">ALWAYS use subagents for code analysis, NEVER tools directly</principle>
-  <principle name="parallel-spawn">Spawn multiple subagents in a SINGLE message</principle>
+  <principle name="background-tasks">Use background_task for parallel research, poll with background_list, collect with background_output</principle>
+  <principle name="parallel-fire">Fire ALL background tasks in a SINGLE message for true parallelism</principle>
   <principle name="one-question">Ask exactly ONE question per message. STOP after asking. Wait for user's answer before continuing. NEVER bundle multiple questions together.</principle>
   <principle name="yagni">Remove unnecessary features from ALL designs</principle>
   <principle name="explore-alternatives">ALWAYS propose 2-3 approaches before settling</principle>
   <principle name="incremental-validation">Present in sections, validate each before proceeding</principle>
+  <principle name="auto-handoff">When user approves design, IMMEDIATELY spawn planner - don't ask again</principle>
 </principles>
 
 <never-do>
@@ -351,13 +381,24 @@ Every task is bite-sized (2-5 minutes), with exact paths and complete code.
 
 <critical-rules>
   <rule>FOLLOW THE DESIGN: The brainstormer's design is the spec. Do not explore alternatives.</rule>
-  <rule>SUBAGENTS: Spawn for implementation details (paths, signatures, line numbers).</rule>
-  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use subagents instead.</rule>
+  <rule>BACKGROUND TASKS: Use background_task for parallel research (fire-and-collect pattern).</rule>
+  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use background subagents instead.</rule>
   <rule>Every code example MUST be complete - never write "add validation here"</rule>
   <rule>Every file path MUST be exact - never write "somewhere in src/"</rule>
   <rule>Follow TDD: failing test \u2192 verify fail \u2192 implement \u2192 verify pass \u2192 commit</rule>
 </critical-rules>
 
+<background-tools>
+  <tool name="background_task">Fire subagent tasks that run in parallel. Returns task_id immediately.</tool>
+  <tool name="background_list">List all background tasks and their current status. Use to poll for completion.</tool>
+  <tool name="background_output">Get results from a completed task. Only call after background_list shows task is done.</tool>
+</background-tools>
+
+<fallback-rule>
+If background_task fails or is unavailable, fall back to Task() for sequential execution.
+Always prefer background_task for parallel research, but Task() works as a reliable fallback.
+</fallback-rule>
+
 <research-scope>
 Brainstormer did conceptual research (architecture, patterns, approaches).
 Your research is IMPLEMENTATION-LEVEL only:
@@ -375,18 +416,19 @@ All research must serve the design - never second-guess design decisions.
 </library-research>
 
 <available-subagents>
-  <subagent name="codebase-locator" spawn="parallel">
+  <subagent name="codebase-locator" spawn="background">
     Find exact file paths needed for implementation.
     Examples: "Find exact path to UserService", "Find test directory structure"
   </subagent>
-  <subagent name="codebase-analyzer" spawn="parallel">
+  <subagent name="codebase-analyzer" spawn="background">
     Get exact signatures and types for code examples.
     Examples: "Get function signature for createUser", "Get type definition for UserConfig"
   </subagent>
-  <subagent name="pattern-finder" spawn="parallel">
+  <subagent name="pattern-finder" spawn="background">
     Find exact patterns to copy in code examples.
     Examples: "Find exact test setup pattern", "Find exact error handling in similar endpoint"
   </subagent>
+  <fallback>If background_task unavailable, use Task() with same subagent types.</fallback>
 </available-subagents>
 
 <inputs>
@@ -402,15 +444,21 @@ All research must serve the design - never second-guess design decisions.
   <action>Note any constraints or decisions made by brainstormer</action>
 </phase>
 
-<phase name="implementation-research">
-  <action>Spawn subagents in PARALLEL to gather exact details:</action>
-  <spawn-example>
-    In a SINGLE message, spawn:
-    - codebase-locator: "Find exact path to [component from design]"
-    - codebase-locator: "Find test file naming convention"
-    - codebase-analyzer: "Get exact signature for [function mentioned in design]"
-    - pattern-finder: "Find exact test setup pattern for [type of test]"
-  </spawn-example>
+<phase name="implementation-research" pattern="fire-and-collect">
+  <action>Fire background tasks AND library research in parallel:</action>
+  <fire-phase description="Launch all research simultaneously">
+    In a SINGLE message, fire:
+    - background_task(agent="codebase-locator", prompt="Find exact path to [component]")
+    - background_task(agent="codebase-analyzer", prompt="Get signature for [function]")
+    - background_task(agent="pattern-finder", prompt="Find test setup pattern")
+    - context7_resolve-library-id + context7_query-docs for API docs
+    - btca_ask for library internals when needed
+  </fire-phase>
+  <collect-phase description="Poll until all complete, then collect">
+    - Poll with background_list until all tasks show completed or error
+    - Call background_output(task_id=...) for each completed task (skip errored)
+    - Combine all results for planning phase
+  </collect-phase>
   <rule>Only research what's needed to implement the design</rule>
   <rule>Never research alternatives to design decisions</rule>
 </phase>
@@ -502,6 +550,29 @@ git commit -m "feat(scope): add specific feature"
 </template>
 </output-format>
 
+<execution-example pattern="fire-and-collect">
+<step name="fire">
+// In a SINGLE message, fire all research tasks:
+background_task(agent="codebase-locator", prompt="Find UserService path")  // returns task_id_1
+background_task(agent="codebase-analyzer", prompt="Get createUser signature")  // returns task_id_2
+background_task(agent="pattern-finder", prompt="Find test setup pattern")  // returns task_id_3
+context7_resolve-library-id(libraryName="express")  // runs in parallel
+btca_ask(tech="express", question="middleware chain order")  // runs in parallel
+</step>
+<step name="collect">
+// Poll until all background tasks complete:
+background_list()  // check status of all tasks
+// When all show "completed":
+background_output(task_id=task_id_1)  // get result
+background_output(task_id=task_id_2)  // get result
+background_output(task_id=task_id_3)  // get result
+// context7 and btca_ask results already available from fire step
+</step>
+<step name="plan">
+// Use all collected results to write the implementation plan
+</step>
+</execution-example>
+
 <principles>
   <principle name="zero-context">Engineer knows nothing about our codebase</principle>
   <principle name="complete-code">Every code block is copy-paste ready</principle>
@@ -553,9 +624,17 @@ Execute the plan. Write code. Verify.
 <step>Verify preconditions match plan</step>
 <step>Make the changes</step>
 <step>Run verification (tests, lint, build)</step>
+<step>If verification passes: commit with message from plan</step>
 <step>Report results</step>
 </process>
 
+<terminal-tools>
+<bash>Use for synchronous commands that complete (npm install, git, builds)</bash>
+<pty>Use for background processes (dev servers, watch modes, REPLs)</pty>
+<rule>If plan says "start dev server" or "run in background", use pty_spawn</rule>
+<rule>If plan says "run command" or "install", use bash</rule>
+</terminal-tools>
+
 <before-each-change>
 <check>Verify file exists where expected</check>
 <check>Verify code structure matches plan assumptions</check>
@@ -566,8 +645,17 @@ Execute the plan. Write code. Verify.
 <check>Run tests if available</check>
 <check>Check for type errors</check>
 <check>Verify no regressions</check>
+<check>If all pass: git add and commit with plan's commit message</check>
 </after-each-change>
 
+<commit-rules>
+<rule>Commit ONLY after verification passes</rule>
+<rule>Use the commit message from the plan (e.g., "feat(scope): description")</rule>
+<rule>Stage only the files mentioned in the task</rule>
+<rule>If plan doesn't specify commit message, use: "feat(task): [task description]"</rule>
+<rule>Do NOT push - just commit locally</rule>
+</commit-rules>
+
 <output-format>
 <template>
 ## Task: [Description]
@@ -580,6 +668,8 @@ Execute the plan. Write code. Verify.
 - [x] Types check
 - [ ] Manual check needed: [what]
 
+**Commit**: \`[commit hash]\` - [commit message]
+
 **Issues**: None / [description]
 </template>
 </output-format>
@@ -671,6 +761,12 @@ Check correctness and style. Be specific. Run code, don't just read.
 <step>Report with precise references</step>
 </process>
 
+<terminal-verification>
+<rule>If implementation includes PTY usage, verify sessions are properly cleaned up</rule>
+<rule>If tests require a running server, check that pty_spawn was used appropriately</rule>
+<rule>Check that long-running processes use PTY, not blocking bash</rule>
+</terminal-verification>
+
 <output-format>
 <template>
 ## Review: [Component]
@@ -708,16 +804,42 @@ var executorAgent = {
   model: "anthropic/claude-opus-4-5",
   temperature: 0.2,
   prompt: `<purpose>
-Execute plan tasks with maximum parallelism.
+Execute plan tasks with maximum parallelism using fire-and-check pattern.
 Each task gets its own implementer \u2192 reviewer cycle.
 Detect and parallelize independent tasks.
 </purpose>
 
-<workflow>
+<background-tools>
+You have access to background task management tools:
+- background_task: Fire a subagent to run in background, returns task_id immediately
+- background_output: Check status or get results from a background task
+- background_list: List all background tasks and their status
+</background-tools>
+
+<pty-tools description="For background bash processes">
+PTY tools manage background terminal sessions (different from background_task which runs subagents):
+- pty_spawn: Start a background process (dev server, watch mode, REPL)
+- pty_write: Send input to a PTY (commands, Ctrl+C, etc.)
+- pty_read: Read output from a PTY buffer
+- pty_list: List all PTY sessions
+- pty_kill: Terminate a PTY session
+
+Use PTY when:
+- Plan requires starting a dev server before running tests
+- Plan requires a watch mode process running during implementation
+- Plan requires interactive terminal input
+
+Do NOT use PTY for:
+- Quick commands (use bash)
+- Subagent tasks (use background_task)
+</pty-tools>
+
+<workflow pattern="fire-and-check">
 <step>Parse plan to extract individual tasks</step>
 <step>Analyze task dependencies to build execution graph</step>
 <step>Group tasks into parallel batches (independent tasks run together)</step>
-<step>For each batch: spawn implementer \u2192 reviewer per task IN PARALLEL</step>
+<step>Fire ALL implementers in batch as background_task</step>
+<step>Poll with background_list, start reviewer immediately when each implementer finishes</step>
 <step>Wait for batch to complete before starting dependent batch</step>
 <step>Aggregate results and report</step>
 </workflow>
@@ -737,83 +859,115 @@ Tasks are DEPENDENT (must be sequential) when:
 When uncertain, assume DEPENDENT (safer).
 </dependency-analysis>
 
-<execution-pattern>
-Example: 9 tasks where tasks 1-3 are independent, 4-6 depend on 1-3, 7-9 depend on 4-6
-
-Batch 1 (parallel):
-  - Spawn implementer for task 1 \u2192 reviewer
-  - Spawn implementer for task 2 \u2192 reviewer
-  - Spawn implementer for task 3 \u2192 reviewer
-  [Wait for all to complete]
-
-Batch 2 (parallel):
-  - Spawn implementer for task 4 \u2192 reviewer
-  - Spawn implementer for task 5 \u2192 reviewer
-  - Spawn implementer for task 6 \u2192 reviewer
-  [Wait for all to complete]
-
-Batch 3 (parallel):
-  - Spawn implementer for task 7 \u2192 reviewer
-  - Spawn implementer for task 8 \u2192 reviewer
-  - Spawn implementer for task 9 \u2192 reviewer
-  [Wait for all to complete]
+<execution-pattern name="fire-and-check">
+The fire-and-check pattern maximizes parallelism by:
+1. Firing all implementers as background tasks simultaneously
+2. Polling to detect completion as early as possible
+3. Starting each reviewer immediately when its implementer finishes
+4. Not waiting for all implementers before starting any reviewers
+
+Example: 3 independent tasks
+- Fire implementer 1, 2, 3 as background_task (all start immediately)
+- Poll with background_list
+- Task 2 finishes first \u2192 immediately start reviewer 2
+- Task 1 finishes \u2192 immediately start reviewer 1
+- Task 3 finishes \u2192 immediately start reviewer 3
+- Reviewers run in parallel as they're spawned
 </execution-pattern>
 
 <available-subagents>
-  <subagent name="implementer" spawn="parallel-per-task">
+  <subagent name="implementer">
     Executes ONE task from the plan.
     Input: Single task with context (which files, what to do).
     Output: Changes made and verification results for that task.
-    Invoke with: Task tool, subagent_type="implementer"
+    <invocation type="background">
+      background_task(description="Implement task 1", prompt="...", agent="implementer")
+    </invocation>
+    <invocation type="fallback">
+      Task(description="Implement task 1", prompt="...", subagent_type="implementer")
+    </invocation>
   </subagent>
-  <subagent name="reviewer" spawn="parallel-per-task">
+  <subagent name="reviewer">
     Reviews ONE task's implementation.
     Input: Single task's changes against its requirements.
     Output: APPROVED or CHANGES REQUESTED for that task.
-    Invoke with: Task tool, subagent_type="reviewer"
+    <invocation type="background">
+      background_task(description="Review task 1", prompt="...", agent="reviewer")
+    </invocation>
+    <invocation type="fallback">
+      Task(description="Review task 1", prompt="...", subagent_type="reviewer")
+    </invocation>
   </subagent>
 </available-subagents>
 
-<critical-instruction>
-You MUST use the Task tool to spawn implementer and reviewer subagents.
-Example: Task(description="Implement task 1", prompt="...", subagent_type="implementer")
-Do NOT try to implement or review yourself - delegate to subagents.
-</critical-instruction>
-
 <per-task-cycle>
 For each task:
-1. Spawn implementer with task details
-2. Wait for implementer to complete
-3. Spawn reviewer to check that task
-4. If reviewer requests changes: re-spawn implementer for fixes
+1. Fire implementer as background_task
+2. Poll until implementer completes
+3. Start reviewer immediately when implementer finishes
+4. If reviewer requests changes: fire new implementer for fixes
 5. Max 3 cycles per task before marking as blocked
 6. Report task status: DONE / BLOCKED
 </per-task-cycle>
 
-<parallel-spawning>
-Within a batch, spawn ALL implementers in a SINGLE message using the Task tool:
+<fire-and-check-loop>
+Within a batch:
+1. Fire ALL implementers as background_task in ONE message
+2. Enter polling loop:
+   a. Call background_list to check status of ALL tasks
+   b. For each newly completed task (status != "running"):
+      - Get result with background_output (task is already done)
+      - If implementer completed: start its reviewer as background_task
+      - If reviewer completed: check APPROVED or CHANGES REQUESTED
+   c. If changes needed and cycles < 3: fire new implementer
+   d. Sleep briefly, then repeat until all tasks done or blocked
+3. Move to next batch
 
-Example for batch with tasks 1, 2, 3 - call Task tool 3 times in ONE message:
-- Task(description="Task 1", prompt="Execute task 1: [details]", subagent_type="implementer")
-- Task(description="Task 2", prompt="Execute task 2: [details]", subagent_type="implementer")
-- Task(description="Task 3", prompt="Execute task 3: [details]", subagent_type="implementer")
+IMPORTANT: Always poll with background_list first to check status,
+then fetch results with background_output only for completed tasks.
+</fire-and-check-loop>
 
-Then after all complete, in ONE message call Task tool for reviewers:
-- Task(description="Review 1", prompt="Review task 1 implementation", subagent_type="reviewer")
-- Task(description="Review 2", prompt="Review task 2 implementation", subagent_type="reviewer")
-- Task(description="Review 3", prompt="Review task 3 implementation", subagent_type="reviewer")
-</parallel-spawning>
+<fallback-rule>
+If background_task fails or is unavailable, fall back to Task() tool:
+- Task(description="...", prompt="...", subagent_type="implementer")
+- Task(description="...", prompt="...", subagent_type="reviewer")
+The Task tool blocks until completion but still works correctly.
+</fallback-rule>
 
 <rules>
 <rule>Parse ALL tasks from plan before starting execution</rule>
 <rule>ALWAYS analyze dependencies before parallelizing</rule>
-<rule>Spawn parallel tasks in SINGLE message for true parallelism</rule>
+<rule>Fire parallel tasks as background_task for true parallelism</rule>
+<rule>Start reviewer immediately when its implementer finishes - don't wait for others</rule>
 <rule>Wait for entire batch before starting next batch</rule>
 <rule>Each task gets its own implement \u2192 review cycle</rule>
 <rule>Max 3 review cycles per task</rule>
 <rule>Continue with other tasks if one is blocked</rule>
 </rules>
 
+<execution-example pattern="fire-and-check">
+# Batch with tasks 1, 2, 3 (independent)
+
+## Step 1: Fire all implementers
+background_task(description="Task 1", prompt="Execute task 1: [details]", agent="implementer") \u2192 task_id_1
+background_task(description="Task 2", prompt="Execute task 2: [details]", agent="implementer") \u2192 task_id_2
+background_task(description="Task 3", prompt="Execute task 3: [details]", agent="implementer") \u2192 task_id_3
+
+## Step 2: Poll and react
+background_list() \u2192 shows task_id_2 completed
+background_output(task_id="task_id_2") \u2192 get result
+background_task(description="Review 2", prompt="Review task 2 implementation", agent="reviewer") \u2192 review_id_2
+
+background_list() \u2192 shows task_id_1, task_id_3 completed
+background_output(task_id="task_id_1") \u2192 get result
+background_output(task_id="task_id_3") \u2192 get result
+background_task(description="Review 1", prompt="Review task 1 implementation", agent="reviewer") \u2192 review_id_1
+background_task(description="Review 3", prompt="Review task 3 implementation", agent="reviewer") \u2192 review_id_3
+
+## Step 3: Continue polling until all reviews complete
+...
+</execution-example>
+
 <output-format>
 <template>
 ## Execution Complete
@@ -848,11 +1002,13 @@ Then after all complete, in ONE message call Task tool for reviewers:
 </output-format>
 
 <never-do>
+<forbidden>NEVER call background_output on running tasks - always poll with background_list first</forbidden>
 <forbidden>Never skip dependency analysis</forbidden>
 <forbidden>Never spawn dependent tasks in parallel</forbidden>
 <forbidden>Never skip reviewer for any task</forbidden>
 <forbidden>Never continue past 3 cycles for a single task</forbidden>
 <forbidden>Never report success if any task is blocked</forbidden>
+<forbidden>Never wait for all implementers before starting any reviewer</forbidden>
 </never-do>`
 };
 
@@ -928,7 +1084,7 @@ Just do it - including obvious follow-up actions.
 </phase>
 
 <phase name="ledger" trigger="context getting full or session ending">
-<action>System auto-updates ledger at 80% context usage</action>
+<action>System auto-updates ledger at 60% context usage</action>
 <output>thoughts/ledgers/CONTINUITY_{session-name}.md</output>
 </phase>
 </workflow>
@@ -956,6 +1112,23 @@ Just do it - including obvious follow-up actions.
 </when-to-use>
 </library-research>
 
+<terminal-tools description="Choose the right terminal tool">
+<tool name="bash">Synchronous commands. Use for: npm install, git, builds, quick commands that complete.</tool>
+<tool name="pty_spawn">Background PTY sessions. Use for: dev servers, watch modes, REPLs, long-running processes.</tool>
+<when-to-use>
+<use tool="bash">Command completes quickly (npm install, git status, mkdir)</use>
+<use tool="pty_spawn">Process runs indefinitely (npm run dev, pytest --watch, python REPL)</use>
+<use tool="pty_spawn">Need to send interactive input (Ctrl+C, responding to prompts)</use>
+<use tool="pty_spawn">Want to check output later without blocking</use>
+</when-to-use>
+<pty-workflow>
+<step>pty_spawn to start the process</step>
+<step>pty_read to check output (use pattern to filter)</step>
+<step>pty_write to send input (\\n for Enter, \\x03 for Ctrl+C)</step>
+<step>pty_kill when done (cleanup=true to remove)</step>
+</pty-workflow>
+</terminal-tools>
+
 <tracking>
 <rule>Use TodoWrite to track what you're doing</rule>
 <rule>Never discard tasks without explicit approval</rule>
@@ -986,7 +1159,7 @@ var PROMPT2 = `
 
   <critical-rule>
     MAXIMIZE PARALLELISM. Speed is critical.
-    - Spawn multiple agents simultaneously
+    - Fire ALL background tasks simultaneously
     - Run multiple tool calls in single message
     - Never wait for one thing when you can do many
   </critical-rule>
@@ -999,16 +1172,33 @@ var PROMPT2 = `
     </outputs>
   </task>
 
-  <parallel-execution-strategy>
-    <phase name="1-discovery" parallel="true">
-      <description>Spawn ALL discovery tasks simultaneously</description>
-      <spawn-agents>
+  <background-tools>
+    <tool name="background_task">
+      Fire a subagent to run in background. Returns task_id immediately.
+      Parameters: description, prompt, agent (subagent type)
+      Example: background_task(description="Find entry points", prompt="Find all entry points", agent="codebase-locator")
+    </tool>
+    <tool name="background_list">
+      List all background tasks and their status. Use to poll for completion.
+      No parameters required.
+    </tool>
+    <tool name="background_output">
+      Get results from a completed task. Only call after background_list shows task is done.
+      Parameters: task_id
+      Example: background_output(task_id="abc123")
+    </tool>
+  </background-tools>
+
+  <parallel-execution-strategy pattern="fire-and-collect">
+    <phase name="1-fire" description="Fire ALL tasks simultaneously">
+      <description>Launch ALL discovery agents + run tools in a SINGLE message</description>
+      <fire-agents>
         <agent name="codebase-locator">Find entry points, configs, main modules</agent>
         <agent name="codebase-locator">Find test files and test patterns</agent>
         <agent name="codebase-locator">Find linter, formatter, CI configs</agent>
         <agent name="codebase-analyzer">Analyze directory structure</agent>
         <agent name="pattern-finder">Find naming conventions across files</agent>
-      </spawn-agents>
+      </fire-agents>
       <parallel-tools>
         <tool>Glob for package.json, pyproject.toml, go.mod, Cargo.toml, etc.</tool>
         <tool>Glob for *.config.*, .eslintrc*, .prettierrc*, ruff.toml, etc.</tool>
@@ -1017,13 +1207,20 @@ var PROMPT2 = `
       </parallel-tools>
     </phase>
 
-    <phase name="2-deep-analysis" parallel="true">
-      <description>Analyze core modules in parallel</description>
-      <spawn-agents>
+    <phase name="2-collect" description="Poll and collect all results">
+      <description>Poll background_list until all tasks complete, then collect with background_output</description>
+      <action>Poll background_list until all tasks show "completed" or "error"</action>
+      <action>Call background_output for each completed task (skip errored)</action>
+      <action>Process tool results from phase 1</action>
+    </phase>
+
+    <phase name="3-deep-analysis" description="Fire deep analysis tasks">
+      <description>Based on discovery, fire more background tasks</description>
+      <fire-agents>
         <agent name="codebase-analyzer">Analyze core/domain logic</agent>
         <agent name="codebase-analyzer">Analyze API/entry points</agent>
         <agent name="codebase-analyzer">Analyze data layer</agent>
-      </spawn-agents>
+      </fire-agents>
       <parallel-tools>
         <tool>Read 5 core source files simultaneously</tool>
         <tool>Read 3 test files simultaneously</tool>
@@ -1031,8 +1228,9 @@ var PROMPT2 = `
       </parallel-tools>
     </phase>
 
-    <phase name="3-write" parallel="true">
-      <description>Write both files in parallel</description>
+    <phase name="4-collect-and-write" description="Collect and write output">
+      <description>Collect deep analysis results, then write both files</description>
+      <action>Collect all deep analysis results</action>
       <action>Write ARCHITECTURE.md</action>
       <action>Write CODE_STYLE.md</action>
     </phase>
@@ -1042,23 +1240,37 @@ var PROMPT2 = `
     <subagent name="codebase-locator" spawn="multiple">
       Fast file/pattern finder. Spawn multiple with different queries.
       Examples: "Find all entry points", "Find all config files", "Find test directories"
-      Invoke with: Task tool, subagent_type="codebase-locator"
+      
+      Background: background_task(description="Find entry points", prompt="Find all entry points and main files", agent="codebase-locator")
+      Fallback: Task(description="Find entry points", prompt="Find all entry points and main files", subagent_type="codebase-locator")
     </subagent>
     <subagent name="codebase-analyzer" spawn="multiple">
       Deep module analyzer. Spawn multiple for different areas.
       Examples: "Analyze src/core", "Analyze api layer", "Analyze database module"
-      Invoke with: Task tool, subagent_type="codebase-analyzer"
+      
+      Background: background_task(description="Analyze core", prompt="Analyze the core module", agent="codebase-analyzer")
+      Fallback: Task(description="Analyze core", prompt="Analyze the core module", subagent_type="codebase-analyzer")
     </subagent>
     <subagent name="pattern-finder" spawn="multiple">
       Pattern extractor. Spawn for different pattern types.
       Examples: "Find naming patterns", "Find error handling patterns", "Find async patterns"
-      Invoke with: Task tool, subagent_type="pattern-finder"
+      
+      Background: background_task(description="Find patterns", prompt="Find naming conventions", agent="pattern-finder")
+      Fallback: Task(description="Find patterns", prompt="Find naming conventions", subagent_type="pattern-finder")
     </subagent>
   </available-subagents>
 
+  <fallback-rule>
+    If background_task fails or is unavailable, fall back to Task() tool.
+    The Task tool provides synchronous subagent execution.
+    Example fallback: Task(description="Find entry points", prompt="Find all entry points", subagent_type="codebase-locator")
+  </fallback-rule>
+
   <critical-instruction>
-  You MUST use the Task tool to spawn subagents. Call multiple Task tools in a SINGLE message for parallelism.
-  Example: Task(description="Find entry points", prompt="Find all entry points and main files", subagent_type="codebase-locator")
+    Use background_task to fire subagents for TRUE parallelism.
+    Fire ALL background_task calls in a SINGLE message.
+    Then poll with background_list until all complete, and collect with background_output.
+    This is the fire-and-collect pattern - fire everything, poll, then collect everything.
   </critical-instruction>
 
   <language-detection>
@@ -1124,10 +1336,10 @@ var PROMPT2 = `
 
   <rules>
     <category name="Speed">
-      <rule>ALWAYS spawn multiple agents in a SINGLE message</rule>
+      <rule>ALWAYS fire multiple background_task calls in a SINGLE message</rule>
       <rule>ALWAYS run multiple tool calls in a SINGLE message</rule>
       <rule>NEVER wait for one task when you can start others</rule>
-      <rule>Batch related queries into parallel agent spawns</rule>
+      <rule>Use fire-and-collect: fire all, then collect all</rule>
     </category>
 
     <category name="Analysis">
@@ -1152,27 +1364,40 @@ var PROMPT2 = `
     </category>
   </rules>
 
-  <execution-example>
-    <step description="Start with maximum parallelism">
-      In a SINGLE message, call Task tool multiple times AND run other tools:
-      - Task(description="Find entry points", prompt="Find all entry points and main files", subagent_type="codebase-locator")
-      - Task(description="Find configs", prompt="Find all config files (linters, formatters, build)", subagent_type="codebase-locator")
-      - Task(description="Find tests", prompt="Find test directories and test files", subagent_type="codebase-locator")
-      - Task(description="Analyze structure", prompt="Analyze the directory structure and organization", subagent_type="codebase-analyzer")
-      - Task(description="Find patterns", prompt="Find naming conventions used across the codebase", subagent_type="pattern-finder")
+  <execution-example pattern="fire-and-collect">
+    <step description="FIRE: Launch all discovery tasks simultaneously">
+      In a SINGLE message, fire ALL background_task calls AND run other tools:
+      - background_task(description="Find entry points", prompt="Find all entry points and main files", agent="codebase-locator") -> task_id_1
+      - background_task(description="Find configs", prompt="Find all config files (linters, formatters, build)", agent="codebase-locator") -> task_id_2
+      - background_task(description="Find tests", prompt="Find test directories and test files", agent="codebase-locator") -> task_id_3
+      - background_task(description="Analyze structure", prompt="Analyze the directory structure and organization", agent="codebase-analyzer") -> task_id_4
+      - background_task(description="Find patterns", prompt="Find naming conventions used across the codebase", agent="pattern-finder") -> task_id_5
       - Glob: package.json, pyproject.toml, go.mod, Cargo.toml, etc.
       - Glob: README*, ARCHITECTURE*, docs/*
     </step>
 
-    <step description="Parallel deep analysis">
-      Based on discovery, in a SINGLE message:
-      - Task for each major module: subagent_type="codebase-analyzer"
+    <step description="COLLECT: Poll and gather all results">
+      First poll until all tasks complete:
+      - background_list()  // repeat until all show "completed" or "error"
+      Then collect results (skip errored tasks):
+      - background_output(task_id=task_id_1)
+      - background_output(task_id=task_id_2)
+      - background_output(task_id=task_id_3)
+      - background_output(task_id=task_id_4)
+      - background_output(task_id=task_id_5)
+    </step>
+
+    <step description="FIRE: Deep analysis based on discovery">
+      Based on discovery, in a SINGLE message fire more tasks:
+      - background_task for each major module: agent="codebase-analyzer"
       - Read multiple source files simultaneously
       - Read multiple test files simultaneously
     </step>
 
-    <step description="Parallel write">
-      Write ARCHITECTURE.md and CODE_STYLE.md
+    <step description="COLLECT and WRITE">
+      Collect deep analysis results, then write:
+      - Write ARCHITECTURE.md
+      - Write CODE_STYLE.md
     </step>
   </execution-example>
 </agent>
@@ -15235,7 +15460,7 @@ function createFileOpsTrackerHook(_ctx) {
 }
 
 // src/hooks/auto-clear-ledger.ts
-var DEFAULT_THRESHOLD = 0.8;
+var DEFAULT_THRESHOLD = 0.6;
 var MIN_TOKENS_FOR_CLEAR = 50000;
 var CLEAR_COOLDOWN_MS = 60000;
 function createAutoClearLedgerHook(ctx) {
@@ -15495,6 +15720,7 @@ function createArtifactAutoIndexHook(_ctx) {
 
 // src/tools/background-task/manager.ts
 var POLL_INTERVAL_MS = 2000;
+var TASK_TTL_MS = 60 * 60 * 1000;
 function generateTaskId() {
   const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
   let result = "bg_";
@@ -15556,6 +15782,7 @@ class BackgroundTaskManager {
       },
       query: { directory: this.ctx.directory }
     }).catch((error45) => {
+      console.error(`[background-task] Failed to prompt session ${sessionID}:`, error45);
       task.status = "error";
       task.error = error45 instanceof Error ? error45.message : String(error45);
       task.completedAt = new Date;
@@ -15573,7 +15800,9 @@ class BackgroundTaskManager {
       this.ctx.client.session.abort({
         path: { id: task.sessionID },
         query: { directory: this.ctx.directory }
-      }).catch(() => {});
+      }).catch((error45) => {
+        console.error(`[background-task] Failed to abort session ${task.sessionID}:`, error45);
+      });
       task.status = "cancelled";
       task.completedAt = new Date;
       this.markForNotification(task);
@@ -15615,20 +15844,18 @@ class BackgroundTaskManager {
         path: { id: task.sessionID },
         query: { directory: this.ctx.directory }
       });
-      const messages = resp.data || [];
-      const lastAssistant = [...messages].reverse().find((m) => {
-        const msg = m;
-        const info = msg.info;
-        return info?.role === "assistant";
-      });
+      const messagesResp = resp;
+      const messages = messagesResp.data || [];
+      const lastAssistant = [...messages].reverse().find((m) => m.info?.role === "assistant");
       if (lastAssistant) {
-        const parts = lastAssistant.parts;
-        const textParts = parts?.filter((p) => p.type === "text") || [];
+        const textParts = lastAssistant.parts?.filter((p) => p.type === "text") || [];
         task.result = textParts.map((p) => p.text || "").join(`
 `);
         return task.result;
       }
-    } catch {}
+    } catch (error45) {
+      console.error(`[background-task] Failed to fetch result for task ${taskId}:`, error45);
+    }
     return;
   }
   formatTaskStatus(task) {
@@ -15660,13 +15887,6 @@ class BackgroundTaskManager {
       output += `
 ### Error
 ${task.error}
-`;
-    }
-    if (task.progress?.lastMessage) {
-      const preview = task.progress.lastMessage.length > 200 ? `${task.progress.lastMessage.slice(0, 200)}...` : task.progress.lastMessage;
-      output += `
-### Last Message Preview
-${preview}
 `;
     }
     return output;
@@ -15684,7 +15904,19 @@ ${preview}
       this.pollingInterval = undefined;
     }
   }
+  cleanupOldTasks() {
+    const now = Date.now();
+    for (const [taskId, task] of this.tasks) {
+      if (task.status === "running")
+        continue;
+      const completedAt = task.completedAt?.getTime() || 0;
+      if (now - completedAt > TASK_TTL_MS) {
+        this.tasks.delete(taskId);
+      }
+    }
+  }
   async pollRunningTasks() {
+    this.cleanupOldTasks();
     const runningTasks = this.getRunningTasks();
     if (runningTasks.length === 0) {
       this.stopPolling();
@@ -15710,9 +15942,12 @@ ${preview}
               variant: "success",
               duration: 5000
             }
-          }).catch(() => {});
+          }).catch((error45) => {
+            console.error(`[background-task] Failed to show toast for task ${task.id}:`, error45);
+          });
         }
-      } catch {
+      } catch (error45) {
+        console.error(`[background-task] Failed to poll task ${task.id}:`, error45);
         if (task.status === "running") {
           task.status = "error";
           task.error = "Session lost";
@@ -15801,27 +16036,17 @@ Use \`background_output\` with task_id="${task.id}" to check progress or get res
     }
   });
   const background_output = tool({
-    description: `Check status or get results from a background task.
-By default returns immediately with current status.
-Set block=true to wait for completion (with timeout).`,
+    description: `Get status or results from a background task.
+Returns immediately with current status. Use background_list to poll for completion.`,
     args: {
-      task_id: tool.schema.string().describe("ID of the task to check (e.g., 'bg_abc12345')"),
-      block: tool.schema.boolean().optional().describe("Wait for task completion (default: false)"),
-      timeout: tool.schema.number().optional().describe("Max seconds to wait if blocking (default: 60, max: 600)")
+      task_id: tool.schema.string().describe("ID of the task to check (e.g., 'bg_abc12345')")
     },
     execute: async (args) => {
-      const { task_id, block = false, timeout = 60 } = args;
+      const { task_id } = args;
       const task = manager.getTask(task_id);
       if (!task) {
         return `Task not found: ${task_id}`;
       }
-      if (block && task.status === "running") {
-        const maxWait = Math.min(timeout || 60, 600) * 1000;
-        const startTime = Date.now();
-        while (task.status === "running" && Date.now() - startTime < maxWait) {
-          await new Promise((resolve2) => setTimeout(resolve2, 1000));
-        }
-      }
       let output = manager.formatTaskStatus(task);
       if (task.status === "completed") {
         const result = await manager.getTaskResult(task_id);
@@ -15887,20 +16112,789 @@ ${result}
     background_list
   };
 }
+// node_modules/bun-pty/src/terminal.ts
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { Buffer } from "buffer";
+
+// node_modules/bun-pty/src/interfaces.ts
+class EventEmitter {
+  listeners = [];
+  event = (listener) => {
+    this.listeners.push(listener);
+    return {
+      dispose: () => {
+        const i = this.listeners.indexOf(listener);
+        if (i !== -1) {
+          this.listeners.splice(i, 1);
+        }
+      }
+    };
+  };
+  fire(data) {
+    for (const listener of this.listeners) {
+      listener(data);
+    }
+  }
+}
+
+// node_modules/bun-pty/src/terminal.ts
+import { join as join4, dirname as dirname3, basename as basename2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+var DEFAULT_COLS = 80;
+var DEFAULT_ROWS = 24;
+var DEFAULT_FILE = "sh";
+var DEFAULT_NAME = "xterm";
+function shQuote(s) {
+  if (s.length === 0)
+    return "''";
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function resolveLibPath() {
+  const env = process.env.BUN_PTY_LIB;
+  if (env && existsSync2(env))
+    return env;
+  try {
+    const embeddedPath = __require(`../rust-pty/target/release/${process.platform === "win32" ? "rust_pty.dll" : process.platform === "darwin" ? process.arch === "arm64" ? "librust_pty_arm64.dylib" : "librust_pty.dylib" : process.arch === "arm64" ? "librust_pty_arm64.so" : "librust_pty.so"}`);
+    if (embeddedPath)
+      return embeddedPath;
+  } catch {}
+  const platform = process.platform;
+  const arch = process.arch;
+  const filenames = platform === "darwin" ? arch === "arm64" ? ["librust_pty_arm64.dylib", "librust_pty.dylib"] : ["librust_pty.dylib"] : platform === "win32" ? ["rust_pty.dll"] : arch === "arm64" ? ["librust_pty_arm64.so", "librust_pty.so"] : ["librust_pty.so"];
+  const base = Bun.fileURLToPath(import.meta.url);
+  const fileDir = dirname3(base);
+  const dirName = basename2(fileDir);
+  const here = dirName === "src" || dirName === "dist" ? dirname3(fileDir) : fileDir;
+  const basePaths = [
+    join4(here, "rust-pty", "target", "release"),
+    join4(here, "..", "bun-pty", "rust-pty", "target", "release"),
+    join4(process.cwd(), "node_modules", "bun-pty", "rust-pty", "target", "release")
+  ];
+  const fallbackPaths = [];
+  for (const basePath of basePaths) {
+    for (const filename of filenames) {
+      fallbackPaths.push(join4(basePath, filename));
+    }
+  }
+  for (const path of fallbackPaths) {
+    if (existsSync2(path))
+      return path;
+  }
+  throw new Error(`librust_pty shared library not found.
+Checked:
+  - BUN_PTY_LIB=${env ?? "<unset>"}
+  - ${fallbackPaths.join(`
+  - `)}
+
+Set BUN_PTY_LIB or ensure one of these paths contains the file.`);
+}
+var libPath = resolveLibPath();
+var lib;
+try {
+  lib = dlopen(libPath, {
+    bun_pty_spawn: {
+      args: [FFIType.cstring, FFIType.cstring, FFIType.cstring, FFIType.i32, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_write: {
+      args: [FFIType.i32, FFIType.pointer, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_read: {
+      args: [FFIType.i32, FFIType.pointer, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_resize: {
+      args: [FFIType.i32, FFIType.i32, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_kill: { args: [FFIType.i32], returns: FFIType.i32 },
+    bun_pty_get_pid: { args: [FFIType.i32], returns: FFIType.i32 },
+    bun_pty_get_exit_code: { args: [FFIType.i32], returns: FFIType.i32 },
+    bun_pty_close: { args: [FFIType.i32], returns: FFIType.void }
+  });
+} catch (error45) {
+  console.error("Failed to load lib", error45);
+}
+
+class Terminal {
+  handle = -1;
+  _pid = -1;
+  _cols = DEFAULT_COLS;
+  _rows = DEFAULT_ROWS;
+  _name = DEFAULT_NAME;
+  _readLoop = false;
+  _closing = false;
+  _onData = new EventEmitter;
+  _onExit = new EventEmitter;
+  constructor(file2 = DEFAULT_FILE, args = [], opts = { name: DEFAULT_NAME }) {
+    this._cols = opts.cols ?? DEFAULT_COLS;
+    this._rows = opts.rows ?? DEFAULT_ROWS;
+    const cwd = opts.cwd ?? process.cwd();
+    const cmdline = [shQuote(file2), ...args.map(shQuote)].join(" ");
+    let envStr = "";
+    if (opts.env) {
+      const envPairs = Object.entries(opts.env).map(([k, v]) => `${k}=${v}`);
+      envStr = envPairs.join("\x00") + "\x00";
+    }
+    this.handle = lib.symbols.bun_pty_spawn(Buffer.from(`${cmdline}\x00`, "utf8"), Buffer.from(`${cwd}\x00`, "utf8"), Buffer.from(`${envStr}\x00`, "utf8"), this._cols, this._rows);
+    if (this.handle < 0)
+      throw new Error("PTY spawn failed");
+    this._pid = lib.symbols.bun_pty_get_pid(this.handle);
+    this._startReadLoop();
+  }
+  get pid() {
+    return this._pid;
+  }
+  get cols() {
+    return this._cols;
+  }
+  get rows() {
+    return this._rows;
+  }
+  get process() {
+    return "shell";
+  }
+  get onData() {
+    return this._onData.event;
+  }
+  get onExit() {
+    return this._onExit.event;
+  }
+  write(data) {
+    if (this._closing)
+      return;
+    const buf = Buffer.from(data, "utf8");
+    lib.symbols.bun_pty_write(this.handle, ptr(buf), buf.length);
+  }
+  resize(cols, rows) {
+    if (this._closing)
+      return;
+    this._cols = cols;
+    this._rows = rows;
+    lib.symbols.bun_pty_resize(this.handle, cols, rows);
+  }
+  kill(signal = "SIGTERM") {
+    if (this._closing)
+      return;
+    this._closing = true;
+    lib.symbols.bun_pty_kill(this.handle);
+    lib.symbols.bun_pty_close(this.handle);
+    this._onExit.fire({ exitCode: 0, signal });
+  }
+  async _startReadLoop() {
+    if (this._readLoop)
+      return;
+    this._readLoop = true;
+    const buf = Buffer.allocUnsafe(4096);
+    while (this._readLoop && !this._closing) {
+      const n = lib.symbols.bun_pty_read(this.handle, ptr(buf), buf.length);
+      if (n > 0) {
+        this._onData.fire(buf.subarray(0, n).toString("utf8"));
+      } else if (n === -2) {
+        const exitCode = lib.symbols.bun_pty_get_exit_code(this.handle);
+        this._onExit.fire({ exitCode });
+        break;
+      } else if (n < 0) {
+        break;
+      } else {
+        await new Promise((r) => setTimeout(r, 8));
+      }
+    }
+  }
+}
+
+// node_modules/bun-pty/src/index.ts
+function spawn3(file2, args, options) {
+  return new Terminal(file2, args, options);
+}
+
+// src/tools/pty/buffer.ts
+var parsed = parseInt(process.env.PTY_MAX_BUFFER_LINES || "50000", 10);
+var DEFAULT_MAX_LINES = isNaN(parsed) ? 50000 : parsed;
+
+class RingBuffer {
+  lines = [];
+  maxLines;
+  constructor(maxLines = DEFAULT_MAX_LINES) {
+    this.maxLines = maxLines;
+  }
+  append(data) {
+    const newLines = data.split(`
+`);
+    for (const line of newLines) {
+      this.lines.push(line);
+      if (this.lines.length > this.maxLines) {
+        this.lines.shift();
+      }
+    }
+  }
+  read(offset = 0, limit) {
+    const start = Math.max(0, offset);
+    const end = limit !== undefined ? start + limit : this.lines.length;
+    return this.lines.slice(start, end);
+  }
+  search(pattern) {
+    const matches = [];
+    for (let i = 0;i < this.lines.length; i++) {
+      const line = this.lines[i];
+      if (line !== undefined && pattern.test(line)) {
+        matches.push({ lineNumber: i + 1, text: line });
+      }
+    }
+    return matches;
+  }
+  get length() {
+    return this.lines.length;
+  }
+  clear() {
+    this.lines = [];
+  }
+}
+
+// src/tools/pty/manager.ts
+function generateId() {
+  const hex3 = Array.from(crypto.getRandomValues(new Uint8Array(4))).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `pty_${hex3}`;
+}
+
+class PTYManager {
+  sessions = new Map;
+  spawn(opts) {
+    const id = generateId();
+    const args = opts.args ?? [];
+    const workdir = opts.workdir ?? process.cwd();
+    const env = { ...process.env, ...opts.env };
+    const title = opts.title ?? (`${opts.command} ${args.join(" ")}`.trim() || `Terminal ${id.slice(-4)}`);
+    const ptyProcess = spawn3(opts.command, args, {
+      name: "xterm-256color",
+      cols: 120,
+      rows: 40,
+      cwd: workdir,
+      env
+    });
+    const buffer = new RingBuffer;
+    const session = {
+      id,
+      title,
+      command: opts.command,
+      args,
+      workdir,
+      env: opts.env,
+      status: "running",
+      pid: ptyProcess.pid,
+      createdAt: new Date,
+      parentSessionId: opts.parentSessionId,
+      buffer,
+      process: ptyProcess
+    };
+    this.sessions.set(id, session);
+    ptyProcess.onData((data) => {
+      buffer.append(data);
+    });
+    ptyProcess.onExit(({ exitCode }) => {
+      if (session.status === "running") {
+        session.status = "exited";
+        session.exitCode = exitCode;
+      }
+    });
+    return this.toInfo(session);
+  }
+  write(id, data) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+    if (session.status !== "running") {
+      return false;
+    }
+    session.process.write(data);
+    return true;
+  }
+  read(id, offset = 0, limit) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const lines = session.buffer.read(offset, limit);
+    const totalLines = session.buffer.length;
+    const hasMore = offset + lines.length < totalLines;
+    return { lines, totalLines, offset, hasMore };
+  }
+  search(id, pattern, offset = 0, limit) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const allMatches = session.buffer.search(pattern);
+    const totalMatches = allMatches.length;
+    const totalLines = session.buffer.length;
+    const paginatedMatches = limit !== undefined ? allMatches.slice(offset, offset + limit) : allMatches.slice(offset);
+    const hasMore = offset + paginatedMatches.length < totalMatches;
+    return { matches: paginatedMatches, totalMatches, totalLines, offset, hasMore };
+  }
+  list() {
+    return Array.from(this.sessions.values()).map((s) => this.toInfo(s));
+  }
+  get(id) {
+    const session = this.sessions.get(id);
+    return session ? this.toInfo(session) : null;
+  }
+  kill(id, cleanup = false) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+    if (session.status === "running") {
+      try {
+        session.process.kill();
+      } catch {}
+      session.status = "killed";
+    }
+    if (cleanup) {
+      session.buffer.clear();
+      this.sessions.delete(id);
+    }
+    return true;
+  }
+  cleanupBySession(parentSessionId) {
+    for (const [id, session] of this.sessions) {
+      if (session.parentSessionId === parentSessionId) {
+        this.kill(id, true);
+      }
+    }
+  }
+  cleanupAll() {
+    for (const id of this.sessions.keys()) {
+      this.kill(id, true);
+    }
+  }
+  toInfo(session) {
+    return {
+      id: session.id,
+      title: session.title,
+      command: session.command,
+      args: session.args,
+      workdir: session.workdir,
+      status: session.status,
+      exitCode: session.exitCode,
+      pid: session.pid,
+      createdAt: session.createdAt,
+      lineCount: session.buffer.length
+    };
+  }
+}
+// src/tools/pty/tools/spawn.ts
+var DESCRIPTION = `Spawns a new interactive PTY (pseudo-terminal) session that runs in the background.
+
+Unlike the built-in bash tool which runs commands synchronously and waits for completion, PTY sessions persist and allow you to:
+- Run long-running processes (dev servers, watch modes, etc.)
+- Send interactive input (including Ctrl+C, arrow keys, etc.)
+- Read output at any time
+- Manage multiple concurrent terminal sessions
+
+Usage:
+- The \`command\` parameter is required (e.g., "npm", "python", "bash")
+- Use \`args\` to pass arguments to the command (e.g., ["run", "dev"])
+- Use \`workdir\` to set the working directory (defaults to project root)
+- Use \`env\` to set additional environment variables
+- Use \`title\` to give the session a human-readable name
+- Use \`description\` for a clear, concise 5-10 word description (optional)
+
+Returns the session info including:
+- \`id\`: Unique identifier (pty_XXXXXXXX) for use with other pty_* tools
+- \`pid\`: Process ID
+- \`status\`: Current status ("running")
+
+After spawning, use:
+- \`pty_write\` to send input to the PTY
+- \`pty_read\` to read output from the PTY
+- \`pty_list\` to see all active PTY sessions
+- \`pty_kill\` to terminate the PTY
+
+Examples:
+- Start a dev server: command="npm", args=["run", "dev"], title="Dev Server"
+- Start a Python REPL: command="python3", title="Python REPL"
+- Run tests in watch mode: command="npm", args=["test", "--", "--watch"]`;
+function createPtySpawnTool(manager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {
+      command: tool.schema.string().describe("The command/executable to run"),
+      args: tool.schema.array(tool.schema.string()).optional().describe("Arguments to pass to the command"),
+      workdir: tool.schema.string().optional().describe("Working directory for the PTY session"),
+      env: tool.schema.record(tool.schema.string(), tool.schema.string()).optional().describe("Additional environment variables"),
+      title: tool.schema.string().optional().describe("Human-readable title for the session"),
+      description: tool.schema.string().optional().describe("Clear, concise description of what this PTY session is for in 5-10 words")
+    },
+    execute: async (args, ctx) => {
+      const info = manager.spawn({
+        command: args.command,
+        args: args.args,
+        workdir: args.workdir,
+        env: args.env,
+        title: args.title,
+        parentSessionId: ctx.sessionID
+      });
+      const output = [
+        `<pty_spawned>`,
+        `ID: ${info.id}`,
+        `Title: ${info.title}`,
+        `Command: ${info.command} ${info.args.join(" ")}`,
+        `Workdir: ${info.workdir}`,
+        `PID: ${info.pid}`,
+        `Status: ${info.status}`,
+        `</pty_spawned>`
+      ].join(`
+`);
+      return output;
+    }
+  });
+}
+// src/tools/pty/tools/write.ts
+var DESCRIPTION2 = `Sends input data to an active PTY session.
+
+Use this tool to:
+- Type commands or text into an interactive terminal
+- Send special key sequences (Ctrl+C, Enter, arrow keys, etc.)
+- Respond to prompts in interactive programs
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`data\`: The input to send (text, commands, or escape sequences)
+
+Common escape sequences:
+- Enter/newline: "\\n" or "\\r"
+- Ctrl+C (interrupt): "\\x03"
+- Ctrl+D (EOF): "\\x04"
+- Ctrl+Z (suspend): "\\x1a"
+- Tab: "\\t"
+- Arrow Up: "\\x1b[A"
+- Arrow Down: "\\x1b[B"
+- Arrow Right: "\\x1b[C"
+- Arrow Left: "\\x1b[D"
+
+Returns success or error message.
+
+Examples:
+- Send a command: data="ls -la\\n"
+- Interrupt a process: data="\\x03"
+- Answer a prompt: data="yes\\n"`;
+function parseEscapeSequences(input) {
+  return input.replace(/\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|[nrt0\\])/g, (match, seq) => {
+    if (seq.startsWith("x")) {
+      return String.fromCharCode(parseInt(seq.slice(1), 16));
+    }
+    if (seq.startsWith("u")) {
+      return String.fromCharCode(parseInt(seq.slice(1), 16));
+    }
+    switch (seq) {
+      case "n":
+        return `
+`;
+      case "r":
+        return "\r";
+      case "t":
+        return "\t";
+      case "0":
+        return "\x00";
+      case "\\":
+        return "\\";
+      default:
+        return match;
+    }
+  });
+}
+function createPtyWriteTool(manager) {
+  return tool({
+    description: DESCRIPTION2,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      data: tool.schema.string().describe("The input data to send to the PTY")
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+      if (session.status !== "running") {
+        throw new Error(`Cannot write to PTY '${args.id}' - session status is '${session.status}'.`);
+      }
+      const parsedData = parseEscapeSequences(args.data);
+      const success2 = manager.write(args.id, parsedData);
+      if (!success2) {
+        throw new Error(`Failed to write to PTY '${args.id}'.`);
+      }
+      const preview = args.data.length > 50 ? `${args.data.slice(0, 50)}...` : args.data;
+      const displayPreview = preview.replace(/\x03/g, "^C").replace(/\x04/g, "^D").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+      return `Sent ${parsedData.length} bytes to ${args.id}: "${displayPreview}"`;
+    }
+  });
+}
+// src/tools/pty/tools/read.ts
+var DESCRIPTION3 = `Reads output from a PTY session's buffer.
+
+The PTY maintains a rolling buffer of output lines. Use offset and limit to paginate through the output, similar to reading a file.
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`offset\`: Line number to start reading from (0-based, defaults to 0)
+- \`limit\`: Number of lines to read (defaults to 500)
+- \`pattern\`: Regex pattern to filter lines (optional)
+- \`ignoreCase\`: Case-insensitive pattern matching (default: false)
+
+Returns:
+- Numbered lines of output (similar to cat -n format)
+- Total line count in the buffer
+- Indicator if more lines are available
+
+The buffer stores up to PTY_MAX_BUFFER_LINES (default: 50000) lines. Older lines are discarded when the limit is reached.
+
+Pattern Filtering:
+- When \`pattern\` is set, lines are FILTERED FIRST using the regex, then offset/limit apply to the MATCHES
+- Original line numbers are preserved so you can see where matches occurred in the buffer
+- Supports full regex syntax (e.g., "error", "ERROR|WARN", "failed.*connection", etc.)
+- If the pattern is invalid, an error message is returned explaining the issue
+- If no lines match the pattern, a clear message indicates zero matches
+
+Tips:
+- To see the latest output, use a high offset or omit offset to read from the start
+- To tail recent output, calculate offset as (totalLines - N) where N is how many recent lines you want
+- Lines longer than 2000 characters are truncated
+- Empty output may mean the process hasn't produced output yet
+
+Examples:
+- Read first 100 lines: offset=0, limit=100
+- Read lines 500-600: offset=500, limit=100
+- Read all available: omit both parameters
+- Find errors: pattern="error", ignoreCase=true
+- Find specific log levels: pattern="ERROR|WARN|FATAL"
+- First 10 matches only: pattern="error", limit=10`;
+var DEFAULT_LIMIT = 500;
+var MAX_LINE_LENGTH = 2000;
+function createPtyReadTool(manager) {
+  return tool({
+    description: DESCRIPTION3,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      offset: tool.schema.number().optional().describe("Line number to start reading from (0-based, defaults to 0)"),
+      limit: tool.schema.number().optional().describe("Number of lines to read (defaults to 500)"),
+      pattern: tool.schema.string().optional().describe("Regex pattern to filter lines"),
+      ignoreCase: tool.schema.boolean().optional().describe("Case-insensitive pattern matching (default: false)")
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+      const offset = Math.max(0, args.offset ?? 0);
+      const limit = args.limit ?? DEFAULT_LIMIT;
+      if (args.pattern) {
+        let regex;
+        try {
+          regex = new RegExp(args.pattern, args.ignoreCase ? "i" : "");
+        } catch (e) {
+          const error45 = e instanceof Error ? e.message : String(e);
+          throw new Error(`Invalid regex pattern '${args.pattern}': ${error45}`);
+        }
+        const result2 = manager.search(args.id, regex, offset, limit);
+        if (!result2) {
+          throw new Error(`PTY session '${args.id}' not found.`);
+        }
+        if (result2.matches.length === 0) {
+          return [
+            `<pty_output id="${args.id}" status="${session.status}" pattern="${args.pattern}">`,
+            `No lines matched the pattern '${args.pattern}'.`,
+            `Total lines in buffer: ${result2.totalLines}`,
+            `</pty_output>`
+          ].join(`
+`);
+        }
+        const formattedLines2 = result2.matches.map((match) => {
+          const lineNum = match.lineNumber.toString().padStart(5, "0");
+          const truncatedLine = match.text.length > MAX_LINE_LENGTH ? `${match.text.slice(0, MAX_LINE_LENGTH)}...` : match.text;
+          return `${lineNum}| ${truncatedLine}`;
+        });
+        const output2 = [
+          `<pty_output id="${args.id}" status="${session.status}" pattern="${args.pattern}">`,
+          ...formattedLines2,
+          ""
+        ];
+        if (result2.hasMore) {
+          output2.push(`(${result2.matches.length} of ${result2.totalMatches} matches shown. Use offset=${offset + result2.matches.length} to see more.)`);
+        } else {
+          output2.push(`(${result2.totalMatches} match${result2.totalMatches === 1 ? "" : "es"} from ${result2.totalLines} total lines)`);
+        }
+        output2.push(`</pty_output>`);
+        return output2.join(`
+`);
+      }
+      const result = manager.read(args.id, offset, limit);
+      if (!result) {
+        throw new Error(`PTY session '${args.id}' not found.`);
+      }
+      if (result.lines.length === 0) {
+        return [
+          `<pty_output id="${args.id}" status="${session.status}">`,
+          `(No output available - buffer is empty)`,
+          `Total lines: ${result.totalLines}`,
+          `</pty_output>`
+        ].join(`
+`);
+      }
+      const formattedLines = result.lines.map((line, index) => {
+        const lineNum = (result.offset + index + 1).toString().padStart(5, "0");
+        const truncatedLine = line.length > MAX_LINE_LENGTH ? `${line.slice(0, MAX_LINE_LENGTH)}...` : line;
+        return `${lineNum}| ${truncatedLine}`;
+      });
+      const output = [`<pty_output id="${args.id}" status="${session.status}">`, ...formattedLines];
+      if (result.hasMore) {
+        output.push("");
+        output.push(`(Buffer has more lines. Use offset=${result.offset + result.lines.length} to read beyond line ${result.offset + result.lines.length})`);
+      } else {
+        output.push("");
+        output.push(`(End of buffer - total ${result.totalLines} lines)`);
+      }
+      output.push(`</pty_output>`);
+      return output.join(`
+`);
+    }
+  });
+}
+// src/tools/pty/tools/list.ts
+var DESCRIPTION4 = `Lists all PTY sessions (active and exited).
+
+Use this tool to:
+- See all running and exited PTY sessions
+- Get session IDs for use with other pty_* tools
+- Check the status and output line count of each session
+- Monitor which processes are still running
+
+Returns for each session:
+- \`id\`: Unique identifier for use with other tools
+- \`title\`: Human-readable name
+- \`command\`: The command that was executed
+- \`status\`: Current status (running, exited, killed)
+- \`exitCode\`: Exit code (if exited/killed)
+- \`pid\`: Process ID
+- \`lineCount\`: Number of lines in the output buffer
+- \`createdAt\`: When the session was created
+
+Tips:
+- Use the session ID with pty_read, pty_write, or pty_kill
+- Sessions remain in the list after exit until explicitly cleaned up with pty_kill
+- This allows you to compare output from multiple sessions`;
+function createPtyListTool(manager) {
+  return tool({
+    description: DESCRIPTION4,
+    args: {},
+    execute: async () => {
+      const sessions = manager.list();
+      if (sessions.length === 0) {
+        return `<pty_list>
+No active PTY sessions.
+</pty_list>`;
+      }
+      const lines = ["<pty_list>"];
+      for (const session of sessions) {
+        const exitInfo = session.exitCode !== undefined ? ` (exit: ${session.exitCode})` : "";
+        lines.push(`[${session.id}] ${session.title}`);
+        lines.push(`  Command: ${session.command} ${session.args.join(" ")}`);
+        lines.push(`  Status: ${session.status}${exitInfo}`);
+        lines.push(`  PID: ${session.pid} | Lines: ${session.lineCount} | Workdir: ${session.workdir}`);
+        lines.push(`  Created: ${session.createdAt.toISOString()}`);
+        lines.push("");
+      }
+      lines.push(`Total: ${sessions.length} session(s)`);
+      lines.push("</pty_list>");
+      return lines.join(`
+`);
+    }
+  });
+}
+// src/tools/pty/tools/kill.ts
+var DESCRIPTION5 = `Terminates a PTY session and optionally cleans up its buffer.
+
+Use this tool to:
+- Stop a running process (sends SIGTERM)
+- Clean up an exited session to free memory
+- Remove a session from the list
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`cleanup\`: If true, removes the session and frees the buffer (default: false)
+
+Behavior:
+- If the session is running, it will be killed (status becomes "killed")
+- If cleanup=false (default), the session remains in the list with its output buffer intact
+- If cleanup=true, the session is removed entirely and the buffer is freed
+- Keeping sessions without cleanup allows you to compare logs between runs
+
+Tips:
+- Use cleanup=false if you might want to read the output later
+- Use cleanup=true when you're done with the session entirely
+- To send Ctrl+C instead of killing, use pty_write with data="\\x03"
+
+Examples:
+- Kill but keep logs: cleanup=false (or omit)
+- Kill and remove: cleanup=true`;
+function createPtyKillTool(manager) {
+  return tool({
+    description: DESCRIPTION5,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      cleanup: tool.schema.boolean().optional().describe("If true, removes the session and frees the buffer (default: false)")
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+      const wasRunning = session.status === "running";
+      const cleanup = args.cleanup ?? false;
+      const success2 = manager.kill(args.id, cleanup);
+      if (!success2) {
+        throw new Error(`Failed to kill PTY session '${args.id}'.`);
+      }
+      const action = wasRunning ? "Killed" : "Cleaned up";
+      const cleanupNote = cleanup ? " (session removed)" : " (session retained for log access)";
+      return [
+        `<pty_killed>`,
+        `${action}: ${args.id}${cleanupNote}`,
+        `Title: ${session.title}`,
+        `Command: ${session.command} ${session.args.join(" ")}`,
+        `Final line count: ${session.lineCount}`,
+        `</pty_killed>`
+      ].join(`
+`);
+    }
+  });
+}
+// src/tools/pty/index.ts
+function createPtyTools(manager) {
+  return {
+    pty_spawn: createPtySpawnTool(manager),
+    pty_write: createPtyWriteTool(manager),
+    pty_read: createPtyReadTool(manager),
+    pty_list: createPtyListTool(manager),
+    pty_kill: createPtyKillTool(manager)
+  };
+}
+
 // src/config-loader.ts
 import { readFile as readFile3 } from "fs/promises";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { homedir as homedir2 } from "os";
 var SAFE_AGENT_PROPERTIES = ["model", "temperature", "maxTokens"];
 async function loadMicodeConfig(configDir) {
-  const baseDir = configDir ?? join4(homedir2(), ".config", "opencode");
-  const configPath = join4(baseDir, "micode.json");
+  const baseDir = configDir ?? join5(homedir2(), ".config", "opencode");
+  const configPath = join5(baseDir, "micode.json");
   try {
     const content = await readFile3(configPath, "utf-8");
-    const parsed = JSON.parse(content);
-    if (parsed.agents && typeof parsed.agents === "object") {
+    const parsed2 = JSON.parse(content);
+    if (parsed2.agents && typeof parsed2.agents === "object") {
       const sanitizedAgents = {};
-      for (const [agentName, agentConfig] of Object.entries(parsed.agents)) {
+      for (const [agentName, agentConfig] of Object.entries(parsed2.agents)) {
         if (agentConfig && typeof agentConfig === "object") {
           const sanitized = {};
           const config2 = agentConfig;
@@ -15914,7 +16908,7 @@ async function loadMicodeConfig(configDir) {
       }
       return { agents: sanitizedAgents };
     }
-    return parsed;
+    return parsed2;
   } catch {
     return null;
   }
@@ -15992,6 +16986,8 @@ var OpenCodeConfigPlugin = async (ctx) => {
   const fileOpsTrackerHook = createFileOpsTrackerHook(ctx);
   const backgroundTaskManager = new BackgroundTaskManager(ctx);
   const backgroundTaskTools = createBackgroundTaskTools(backgroundTaskManager);
+  const ptyManager = new PTYManager;
+  const ptyTools = createPtyTools(ptyManager);
   return {
     tool: {
       ast_grep_search,
@@ -15999,7 +16995,8 @@ var OpenCodeConfigPlugin = async (ctx) => {
       btca_ask,
       look_at,
       artifact_search,
-      ...backgroundTaskTools
+      ...backgroundTaskTools,
+      ...ptyTools
     },
     config: async (config2) => {
       config2.permission = {
@@ -16073,6 +17070,7 @@ var OpenCodeConfigPlugin = async (ctx) => {
         const props = event.properties;
         if (props?.info?.id) {
           thinkModeState.delete(props.info.id);
+          ptyManager.cleanupBySession(props.info.id);
         }
       }
       await autoCompactHook.event({ event });