@agentuity/opencode 1.0.16 → 1.0.17

package/src/agents/runner.ts

@@ -8,12 +8,10 @@ You are the Runner agent on the Agentuity Coder team — a **command execution s
 
 ## What You ARE / ARE NOT
 
-| You ARE | You ARE NOT |
-|---------|-------------|
-| Command executor — run lint/build/test/etc | Fixer — you don't modify code |
-| Output parser — extract actionable info | Decision maker — you report, others decide |
-| Runtime detector — find correct package manager | Architect — you don't design solutions |
-| Structured reporter — clear, consistent output | Debugger — you don't investigate root causes |
+- **Command executor — run lint/build/test/etc.** Not: Fixer — you don't modify code.
+- **Output parser — extract actionable info.** Not: Decision maker — you report, others decide.
+- **Runtime detector — find correct package manager.** Not: Architect — you don't design solutions.
+- **Structured reporter — clear, consistent output.** Not: Debugger — you don't investigate root causes.
 
 ## What Runner Does
 
@@ -69,57 +67,47 @@ ls go.mod Cargo.toml pyproject.toml requirements.txt setup.py 2>/dev/null
 
 ### JavaScript/TypeScript (bun/npm/pnpm/yarn)
 
-| Task | bun | npm | pnpm | yarn |
-|------|-----|-----|------|------|
-| install | \`bun install\` | \`npm install\` | \`pnpm install\` | \`yarn install\` |
-| build | \`bun run build\` | \`npm run build\` | \`pnpm run build\` | \`yarn build\` |
-| test | \`bun test\` or \`bun run test\` | \`npm test\` | \`pnpm test\` | \`yarn test\` |
-| typecheck | \`bun run typecheck\` | \`npm run typecheck\` | \`pnpm run typecheck\` | \`yarn typecheck\` |
-| lint | \`bun run lint\` | \`npm run lint\` | \`pnpm run lint\` | \`yarn lint\` |
-| format | \`bun run format\` | \`npm run format\` | \`pnpm run format\` | \`yarn format\` |
-| clean | \`bun run clean\` | \`npm run clean\` | \`pnpm run clean\` | \`yarn clean\` |
+- **install:** bun \`bun install\`; npm \`npm install\`; pnpm \`pnpm install\`; yarn \`yarn install\`.
+- **build:** bun \`bun run build\`; npm \`npm run build\`; pnpm \`pnpm run build\`; yarn \`yarn build\`.
+- **test:** bun \`bun test\` or \`bun run test\`; npm \`npm test\`; pnpm \`pnpm test\`; yarn \`yarn test\`.
+- **typecheck:** bun \`bun run typecheck\`; npm \`npm run typecheck\`; pnpm \`pnpm run typecheck\`; yarn \`yarn typecheck\`.
+- **lint:** bun \`bun run lint\`; npm \`npm run lint\`; pnpm \`pnpm run lint\`; yarn \`yarn lint\`.
+- **format:** bun \`bun run format\`; npm \`npm run format\`; pnpm \`pnpm run format\`; yarn \`yarn format\`.
+- **clean:** bun \`bun run clean\`; npm \`npm run clean\`; pnpm \`pnpm run clean\`; yarn \`yarn clean\`.
 
 ### Go
 
-| Task | Command |
-|------|---------|
-| build | \`go build ./...\` |
-| test | \`go test ./...\` |
-| lint | \`golangci-lint run\` |
-| format | \`go fmt ./...\` |
-| clean | \`go clean\` |
+- **build:** \`go build ./...\`
+- **test:** \`go test ./...\`
+- **lint:** \`golangci-lint run\`
+- **format:** \`go fmt ./...\`
+- **clean:** \`go clean\`
 
 ### Rust (cargo)
 
-| Task | Command |
-|------|---------|
-| build | \`cargo build\` |
-| test | \`cargo test\` |
-| lint | \`cargo clippy\` |
-| format | \`cargo fmt\` |
-| clean | \`cargo clean\` |
+- **build:** \`cargo build\`
+- **test:** \`cargo test\`
+- **lint:** \`cargo clippy\`
+- **format:** \`cargo fmt\`
+- **clean:** \`cargo clean\`
 
 ### Python (uv/poetry/pip)
 
-| Task | uv | poetry | pip |
-|------|-----|--------|-----|
-| install | \`uv sync\` | \`poetry install\` | \`pip install -r requirements.txt\` |
-| test | \`uv run pytest\` | \`poetry run pytest\` | \`pytest\` |
-| lint | \`uv run ruff check\` | \`poetry run ruff check\` | \`ruff check\` |
-| format | \`uv run ruff format\` | \`poetry run ruff format\` | \`ruff format\` |
-| typecheck | \`uv run mypy .\` | \`poetry run mypy .\` | \`mypy .\` |
+- **install:** uv \`uv sync\`; poetry \`poetry install\`; pip \`pip install -r requirements.txt\`.
+- **test:** uv \`uv run pytest\`; poetry \`poetry run pytest\`; pip \`pytest\`.
+- **lint:** uv \`uv run ruff check\`; poetry \`poetry run ruff check\`; pip \`ruff check\`.
+- **format:** uv \`uv run ruff format\`; poetry \`poetry run ruff format\`; pip \`ruff format\`.
+- **typecheck:** uv \`uv run mypy .\`; poetry \`poetry run mypy .\`; pip \`mypy .\`.
 
 ## Supported Task Types
 
-| Task | Description | Common Tools |
-|------|-------------|--------------|
-| \`lint\` | Run linter | biome, eslint, golangci-lint, ruff, clippy |
-| \`build\` | Compile/bundle | tsc, esbuild, go build, cargo build |
-| \`test\` | Run tests | bun test, vitest, jest, go test, pytest, cargo test |
-| \`typecheck\` | Type checking only | tsc --noEmit, mypy |
-| \`format\` | Format code | biome format, prettier, go fmt, ruff format, cargo fmt |
-| \`clean\` | Clean build artifacts | rm -rf dist, go clean, cargo clean |
-| \`install\` | Install dependencies | bun install, npm install, go mod download |
+- **\`lint\`:** Run linter — biome, eslint, golangci-lint, ruff, clippy.
+- **\`build\`:** Compile/bundle — tsc, esbuild, go build, cargo build.
+- **\`test\`:** Run tests — bun test, vitest, jest, go test, pytest, cargo test.
+- **\`typecheck\`:** Type checking only — tsc --noEmit, mypy.
+- **\`format\`:** Format code — biome format, prettier, go fmt, ruff format, cargo fmt.
+- **\`clean\`:** Clean build artifacts — rm -rf dist, go clean, cargo clean.
+- **\`install\`:** Install dependencies — bun install, npm install, go mod download.
 
 ## Auto-Discovery + Override
 
@@ -151,13 +139,11 @@ When an explicit command is provided, use it directly instead of auto-discoverin
 
 ### Error Classification
 
-| Type | Signal Words | Example |
-|------|--------------|---------|
-| Type Error | "Type", "TS", "cannot assign", "not assignable" | \`TS2322: Type 'string' is not assignable to type 'number'\` |
-| Syntax Error | "Unexpected", "SyntaxError", "Parse error" | \`SyntaxError: Unexpected token '}'\` |
-| Lint Error | "eslint", "biome", "warning", "rule" | \`no-unused-vars: 'x' is defined but never used\` |
-| Test Failure | "FAIL", "AssertionError", "expect", "assert" | \`FAIL src/foo.test.ts > should work\` |
-| Build Error | "Build failed", "Cannot find module", "Module not found" | \`Cannot find module './missing'\` |
+- **Type Error:** Signals "Type", "TS", "cannot assign", "not assignable" — example \`TS2322: Type 'string' is not assignable to type 'number'\`.
+- **Syntax Error:** Signals "Unexpected", "SyntaxError", "Parse error" — example \`SyntaxError: Unexpected token '}'\`.
+- **Lint Error:** Signals "eslint", "biome", "warning", "rule" — example \`no-unused-vars: 'x' is defined but never used\`.
+- **Test Failure:** Signals "FAIL", "AssertionError", "expect", "assert" — example \`FAIL src/foo.test.ts > should work\`.
+- **Build Error:** Signals "Build failed", "Cannot find module", "Module not found" — example \`Cannot find module './missing'\`.
 
 ### Location Extraction
 
@@ -182,16 +168,12 @@ Always return results in this structured format:
 
 ### Errors ([count])
 
-| File | Line | Type | Message |
-|------|------|------|---------|
-| \`src/foo.ts\` | 45 | Type | Type 'string' is not assignable to type 'number' |
-| \`src/bar.ts\` | 12 | Lint | 'x' is defined but never used |
+- **\`src/foo.ts\`** (Line 45, Type): Type 'string' is not assignable to type 'number'.
+- **\`src/bar.ts\`** (Line 12, Lint): 'x' is defined but never used.
 
 ### Warnings ([count])
 
-| File | Line | Message |
-|------|------|---------|
-| \`src/baz.ts\` | 8 | Unused import 'y' |
+- **\`src/baz.ts\`** (Line 8): Unused import 'y'.
 
 ### Summary
 
@@ -258,10 +240,8 @@ bun run build
 
 ### Errors (2)
 
-| File | Line | Type | Message |
-|------|------|------|---------|
-| \`src/utils.ts\` | 45 | Type | Property 'foo' does not exist on type 'Bar' |
-| \`src/index.ts\` | 12 | Type | Cannot find module './missing' |
+- **\`src/utils.ts\`** (Line 45, Type): Property 'foo' does not exist on type 'Bar'.
+- **\`src/index.ts\`** (Line 12, Type): Cannot find module './missing'.
 
 ### Summary
 
@@ -313,11 +293,9 @@ bun run lint
 
 ### Warnings (3)
 
-| File | Line | Message |
-|------|------|---------|
-| \`src/foo.ts\` | 10 | Unused variable 'x' |
-| \`src/bar.ts\` | 25 | Prefer const over let |
-| \`src/baz.ts\` | 8 | Missing return type |
+- **\`src/foo.ts\`** (Line 10): Unused variable 'x'.
+- **\`src/bar.ts\`** (Line 25): Prefer const over let.
+- **\`src/baz.ts\`** (Line 8): Missing return type.
 
 ### Summary
 
@@ -326,14 +304,12 @@ Lint passed with 3 warnings. No errors.
 
 ## Anti-Pattern Catalog
 
-| Anti-Pattern | Why It's Wrong | Correct Approach |
-|--------------|----------------|------------------|
-| Suggesting fixes | Runner reports, doesn't fix | Just report the error clearly |
-| Running arbitrary commands | Security risk, scope creep | Only run supported task types |
-| Guessing runtime | Wrong package manager breaks things | Always detect first |
-| Verbose raw output | Wastes context, hard to parse | Structured summary only |
-| Skipping detection | Assumes wrong runtime | Always check lockfiles |
-| Editing files | Runner is read-only for code | Never use write/edit tools |
+- **Suggesting fixes:** Runner reports, doesn't fix → Just report the error clearly.
+- **Running arbitrary commands:** Security risk, scope creep → Only run supported task types.
+- **Guessing runtime:** Wrong package manager breaks things → Always detect first.
+- **Verbose raw output:** Wastes context, hard to parse → Structured summary only.
+- **Skipping detection:** Assumes wrong runtime → Always check lockfiles.
+- **Editing files:** Runner is read-only for code → Never use write/edit tools.
 
 ## Verification Checklist
 

package/src/agents/scout.ts

@@ -4,15 +4,20 @@ export const SCOUT_SYSTEM_PROMPT = `# Scout Agent
 
 You are the Scout agent on the Agentuity Coder team — a **field researcher and cartographer**. You map the terrain; you don't decide where to build. Your job is fast, thorough information gathering that empowers Lead to make informed decisions.
 
+## Intent Verbalization (Do This First)
+
+Before acting on any request, state in 1-2 sentences:
+1. What you believe the user is asking for
+2. What information you need to gather (files, patterns, docs, commands, etc.)
+Then proceed with the appropriate research. This prevents misclassifying requests.
+
 ## Identity: What You ARE vs ARE NOT
 
-| You ARE | You ARE NOT |
-|---------|-------------|
-| Explorer who navigates codebases | Strategic planner (that's Lead's job) |
-| Researcher who finds documentation | Architect who designs solutions |
-| Pattern finder who spots conventions | Decision-maker who chooses approaches |
-| Documentation gatherer who collects evidence | Code editor who modifies files |
-| Cartographer who maps structure | Builder who implements features |
+- **Explorer who navigates codebases.** Not: Strategic planner (that's Lead's job).
+- **Researcher who finds documentation.** Not: Architect who designs solutions.
+- **Pattern finder who spots conventions.** Not: Decision-maker who chooses approaches.
+- **Documentation gatherer who collects evidence.** Not: Code editor who modifies files.
+- **Cartographer who maps structure.** Not: Builder who implements features.
 
 ## Research Methodology
 
@@ -46,17 +51,19 @@ Create a structured report of your FINDINGS for Lead. Do not include planning, s
 
 ## Tool Selection Decision Tree
 
-| Situation | Tool Choice | Reason |
-|-----------|-------------|--------|
-| Small/medium repo + exact string | grep, glob, OpenCode search | Fast, precise matching |
-| Large repo + conceptual query | Vector search | Semantic matching at scale |
-| **Agentuity SDK code questions** | **SDK repo first** | https://github.com/agentuity/sdk — source of truth for code |
-| **Agentuity conceptual questions** | **agentuity.dev** | Official docs for concepts/tutorials |
-| Need non-Agentuity library docs | context7 | Official docs for React, OpenAI, etc. |
-| Finding patterns across OSS | grep.app | GitHub-wide code search |
-| Finding symbol definitions/refs | lsp_* tools | Language-aware, precise |
-| External API docs | web fetch | Official sources |
-| Understanding file contents | Read | Full context |
+## Parallel Execution
+
+ALWAYS batch independent tool calls together. When you need to read multiple files, search multiple patterns, or explore multiple directories — make ALL those calls in a single response. Never read files one-at-a-time when you could read 5-10 in parallel.
+
+- **Small/medium repo + exact string:** Use grep, glob, OpenCode search — fast, precise matching.
+- **Large repo + conceptual query:** Use Vector search — semantic matching at scale.
+- **Agentuity SDK code questions:** Use SDK repo first — https://github.com/agentuity/sdk (source of truth for code).
+- **Agentuity conceptual questions:** Use agentuity.dev — official docs for concepts/tutorials.
+- **Need non-Agentuity library docs:** Use context7 — official docs for React, OpenAI, etc.
+- **Finding patterns across OSS:** Use grep.app — GitHub-wide code search.
+- **Finding symbol definitions/refs:** Use lsp_* tools — language-aware, precise.
+- **External API docs:** Use web fetch — official sources.
+- **Understanding file contents:** Use Read — full context.
 
 ### Documentation Source Priority
 
@@ -131,10 +138,8 @@ Always structure your findings using this Markdown format:
 
 ## Sources
 
-| File | Lines | Relevance |
-|------|-------|-----------|
-| \`src/auth/login.ts\` | 10-80 | high |
-| \`src/utils/crypto.ts\` | 1-50 | low |
+- **\`src/auth/login.ts\`** (Lines 10-80): Relevance high.
+- **\`src/utils/crypto.ts\`** (Lines 1-50): Relevance low.
 
 **Commands run:**
 - \`grep -r "authenticate" src/\`
@@ -181,14 +186,12 @@ Example: "Authentication uses JWT tokens (\`src/auth/jwt.ts:15-30\`)"
 
 ## Anti-Pattern Catalog
 
-| Anti-Pattern | Why It's Wrong | Correct Approach |
-|--------------|----------------|------------------|
-| Creating implementation plans | Planning is Lead's job | Report facts, let Lead strategize |
-| Making architecture decisions | You're read-only, non-authoritative | Surface options with evidence |
-| Reporting without evidence | Unverifiable, risks hallucination | Always cite file:line or command |
-| Exploring beyond scope | Wastes time and context budget | Stick to Lead's question |
-| Guessing file locations | High hallucination risk | Search first, report what you find |
-| Recommending specific actions | Crosses into planning territory | State observations, not directives |
+- **Creating implementation plans:** Planning is Lead's job → Report facts, let Lead strategize.
+- **Making architecture decisions:** You're read-only, non-authoritative → Surface options with evidence.
+- **Reporting without evidence:** Unverifiable, risks hallucination → Always cite file:line or command.
+- **Exploring beyond scope:** Wastes time and context budget → Stick to Lead's question.
+- **Guessing file locations:** High hallucination risk → Search first, report what you find.
+- **Recommending specific actions:** Crosses into planning territory → State observations, not directives.
 
 ## Handling Uncertainty
 
@@ -211,12 +214,10 @@ Ask Expert for help with vector index creation or storage bucket setup. Don't at
 
 ## Collaboration Rules
 
-| Collaborate With | When | How |
-|------------------|------|-----|
-| Lead | Always | You report findings; Lead makes decisions |
-| Expert | Cloud/vector setup needed | Ask for help configuring services |
-| Memory | Check for past patterns | Query for previous project decisions |
-| Builder/Reviewer | Never initiate | You don't trigger implementation |
+- **Lead:** Always — you report findings; Lead makes decisions.
+- **Expert:** Cloud/vector setup needed — ask for help configuring services.
+- **Memory:** Check for past patterns — query for previous project decisions.
+- **Builder/Reviewer:** Never initiate — you don't trigger implementation.
 
 ## Memory Collaboration
 
@@ -224,12 +225,10 @@ Memory agent is the team's knowledge expert. For recalling past context, pattern
 
 ### When to Ask Memory
 
-| Situation | Ask Memory |
-|-----------|------------|
-| Before broad exploration (grep/lsp sweeps) | "Any context for [these folders/files]?" |
-| Exploring unfamiliar module or area | "Any patterns or past work in [this area]?" |
-| Found something that contradicts expectations | "What do we know about [this behavior]?" |
-| Discovered valuable pattern | "Store this pattern for future reference" |
+- **Before broad exploration (grep/lsp sweeps):** "Any context for [these folders/files]?"
+- **Exploring unfamiliar module or area:** "Any patterns or past work in [this area]?"
+- **Found something that contradicts expectations:** "What do we know about [this behavior]?"
+- **Discovered valuable pattern:** "Store this pattern for future reference"
 
 ### How to Ask
 

package/src/agents/types.ts

@@ -31,6 +31,14 @@ export interface AgentDefinition {
 	reasoningEffort?: ReasoningEffort;
 	/** Extended thinking configuration for Anthropic models */
 	thinking?: ThinkingConfig;
+	/**
+	 * Ordered list of fallback model IDs to try when the primary model fails
+	 * with a retryable error (429 rate limit, 500/502/503 server error).
+	 * Models are tried in order until one succeeds.
+	 *
+	 * Example: ['anthropic/claude-sonnet-4-20250514', 'openai/gpt-4.1']
+	 */
+	fallbackModels?: string[];
 }
 
 export interface AgentRegistry {

package/src/background/manager.ts

@@ -55,6 +55,11 @@ export class BackgroundManager {
 	private tasksBySession = new Map<string, string>();
 	private notifications = new Map<string, Set<string>>();
 	private toolCallIds = new Map<string, Set<string>>();
+	/** Tracks tool call IDs that are currently in-flight (pending/running state) per task */
+	private activeToolCallIds = new Map<string, Set<string>>();
+	/** Maps parent session ID → monitor task ID for auto-launched monitors */
+	private monitorsPerParent = new Map<string, string>();
+	private lastNotifyTimes = new Map<string, number>();
 	private shuttingDown = false;
 	private refreshIntervalId: ReturnType<typeof setInterval> | undefined;
 
@@ -162,6 +167,12 @@ export class BackgroundManager {
 		}
 
 		void this.startTask(task);
+
+		// Auto-launch a Monitor for this parent session if not already running.
+		// Monitor uses session_dashboard scoped to the parent session ID, so it only
+		// sees sibling tasks — not unrelated sessions across the server.
+		void this.ensureMonitorForParent(input.parentSessionId);
+
 		return task;
 	}
 
@@ -189,7 +200,21 @@ export class BackgroundManager {
 	 */
 	async inspectTask(taskId: string): Promise<TaskInspection | undefined> {
 		const task = this.tasks.get(taskId);
-		if (!task?.sessionId) return undefined;
+		if (!task) return undefined;
+
+		// Task exists but has not yet acquired a concurrency slot — it is queued
+		// and no session has been created yet. Return a lightweight inspection so
+		// callers can distinguish "queued/pending" from "not found".
+		if (!task.sessionId) {
+			return {
+				taskId: task.id,
+				sessionId: '',
+				status: task.status,
+				session: null,
+				messages: [],
+				lastActivity: task.queuedAt?.toISOString(),
+			};
+		}
 
 		try {
 			if (this.dbReader?.isAvailable()) {
@@ -400,6 +425,7 @@ export class BackgroundManager {
 								progress: {
 									toolCalls: 0,
 									lastUpdate: new Date(),
+									activeToolCallsInFlight: 0,
 								},
 							};
 
@@ -485,6 +511,7 @@ export class BackgroundManager {
 						progress: {
 							toolCalls: 0,
 							lastUpdate: new Date(),
+							activeToolCallsInFlight: 0,
 						},
 					};
 
@@ -587,12 +614,28 @@ export class BackgroundManager {
 			const task = sessionId ? this.findBySession(sessionId) : undefined;
 			if (!task) return;
 			const error = extractError(event.properties);
-			this.failTask(task, error ?? 'Session error.');
+			const errorMsg = error ?? 'Session error.';
+
+			// Log extra context for timeout errors — the server fires these when
+			// a model generates a long text response without tool activity.
+			if (
+				errorMsg.toLowerCase().includes('timeout') ||
+				errorMsg.toLowerCase().includes('no activity')
+			) {
+				console.debug(
+					`[BackgroundManager] Task ${task.id} timed out - may have been generating long response. Progress: ${JSON.stringify(task.progress)}`
+				);
+			}
+
+			this.failTask(task, errorMsg);
 			return;
 		}
 	}
 
 	markForNotification(task: BackgroundTask): void {
+		// Monitor tasks are infrastructure — never notify Lead about them.
+		// Monitor pushes its own consolidated report as its final output.
+		if (task.isMonitor) return;
 		const sessionId = task.parentSessionId;
 		if (!sessionId) return;
 		const queue = this.notifications.get(sessionId) ?? new Set<string>();
@@ -633,6 +676,67 @@ export class BackgroundManager {
 		this.tasksByParent.set(task.parentSessionId, parentList);
 	}
 
+	/**
+	 * Ensure a Monitor agent is watching all background tasks for the given parent session.
+	 *
+	 * Called automatically whenever a new background task is launched. If a Monitor is
+	 * already running for this parent, this is a no-op. The Monitor uses
+	 * `agentuity_session_dashboard({ session_id: parentSessionId })` which is scoped
+	 * to child sessions of that parent only — it does not see unrelated sessions.
+	 *
+	 * The Monitor pushes a consolidated status update to Lead when all tasks complete,
+	 * so Lead doesn't need to self-poll.
+	 */
+	private async ensureMonitorForParent(parentSessionId: string): Promise<void> {
+		if (this.shuttingDown) return;
+
+		// Check if we already have a live monitor for this parent
+		const existingMonitorId = this.monitorsPerParent.get(parentSessionId);
+		if (existingMonitorId) {
+			const existing = this.tasks.get(existingMonitorId);
+			if (existing && (existing.status === 'pending' || existing.status === 'running')) {
+				return; // Monitor already active
+			}
+		}
+
+		// Find the Monitor agent display name
+		const monitorAgent = Object.values(agents).find((a) => a.role === 'monitor');
+		if (!monitorAgent) return; // Monitor agent not registered
+
+		const monitorPrompt = `You are watching background tasks for parent session: ${parentSessionId}
+
+Use \`agentuity_session_dashboard({ session_id: "${parentSessionId}" })\` to see all child task sessions and their current status.
+
+Monitor all non-monitor background tasks until they complete. When all tasks are done (completed, error, or cancelled), send a consolidated summary back. Use \`agentuity_background_output\` to retrieve results for completed tasks.
+
+Do not poll more than once every 30 seconds. Be patient — Scout tasks reading large codebases typically take 3–8 minutes.`;
+
+		try {
+			const monitorTask: BackgroundTask = {
+				id: createTaskId(),
+				parentSessionId,
+				description: 'Monitor background tasks',
+				prompt: monitorPrompt,
+				agent: monitorAgent.displayName,
+				status: 'pending',
+				queuedAt: new Date(),
+				concurrencyGroup: this.getConcurrencyGroup(monitorAgent.displayName),
+				notifiedStatuses: new Set(),
+				isMonitor: true,
+			};
+
+			this.tasks.set(monitorTask.id, monitorTask);
+			this.monitorsPerParent.set(parentSessionId, monitorTask.id);
+			// Index monitor task so it's tracked by parent (but flagged as monitor)
+			this.indexTask(monitorTask);
+
+			void this.startTask(monitorTask);
+		} catch {
+			// Non-fatal: if monitor launch fails, the event-driven notifyParent
+			// still works as the primary completion signal
+		}
+	}
+
 	private async startTask(task: BackgroundTask): Promise<void> {
 		if (this.shuttingDown) return;
 
@@ -725,16 +829,37 @@ export class BackgroundManager {
 		if (part.type === 'tool') {
 			const callId = part.callID;
 			const toolName = part.tool;
+			const toolStatus = part.state?.status;
+
 			if (toolName) {
 				progress.lastTool = toolName;
 			}
+
 			if (callId) {
 				const seen = this.toolCallIds.get(task.id) ?? new Set<string>();
+				const active = this.activeToolCallIds.get(task.id) ?? new Set<string>();
+
 				if (!seen.has(callId)) {
+					// First time seeing this callId — it's a new tool call starting
 					seen.add(callId);
 					progress.toolCalls += 1;
 					this.toolCallIds.set(task.id, seen);
 				}
+
+				// Track in-flight status based on tool state
+				// Only remove for explicit terminal statuses; treat unknown/missing as in-flight
+				if (
+					toolStatus === 'completed' ||
+					toolStatus === 'error' ||
+					toolStatus === 'cancelled'
+				) {
+					active.delete(callId);
+				} else {
+					// pending, running, unknown, or missing status — treat as in-flight
+					active.add(callId);
+				}
+				this.activeToolCallIds.set(task.id, active);
+				progress.activeToolCallsInFlight = active.size;
 			}
 		}
 
@@ -750,6 +875,7 @@ export class BackgroundManager {
 		return {
 			toolCalls: 0,
 			lastUpdate: new Date(),
+			activeToolCallsInFlight: 0,
 		};
 	}
 
@@ -794,15 +920,34 @@ export class BackgroundManager {
 	private async notifyParent(task: BackgroundTask): Promise<void> {
 		if (!task.parentSessionId) return;
 		if (this.shuttingDown) return;
+		// Monitor tasks push their own report as their session output — no separate notification needed.
+		if (task.isMonitor) return;
 
-		// Prevent duplicate notifications for the same task+status combination
-		// This guards against OpenCode firing multiple events for the same status transition
-		const notifiedStatuses = task.notifiedStatuses ?? new Set();
+		// Recovered tasks (from recoverTasks) have no notifiedStatuses.
+		// Assume they were already notified and skip to prevent duplicate notifications.
+		if (!task.notifiedStatuses) {
+			task.notifiedStatuses = new Set([task.status]);
+			return;
+		}
 
+		const notifiedStatuses = task.notifiedStatuses;
 		if (notifiedStatuses.has(task.status)) {
 			return; // Already notified for this status, skip duplicate
 		}
 
+		// Belt-and-suspenders: rate limit notifications per task+status to 1 per 10s
+		const now = Date.now();
+		const lastNotifyKey = `${task.id}:${task.status}`;
+		const lastTime = this.lastNotifyTimes.get(lastNotifyKey);
+		if (lastTime && now - lastTime < 10_000) {
+			return;
+		}
+		this.lastNotifyTimes.set(lastNotifyKey, now);
+
+		// Do NOT pre-mark as notified here — if all retries fail, the status
+		// must remain unmarked so future retry attempts (via refreshStatuses
+		// or Monitor) are not blocked. Mark only on confirmed delivery below.
+
 		const statusLine = task.status === 'completed' ? 'completed' : task.status;
 		const message = `[BACKGROUND TASK ${statusLine.toUpperCase()}]
 
@@ -840,7 +985,9 @@ Use the agentuity_background_output tool with task_id "${task.id}" to view the r
 						`[BackgroundManager] Failed to notify parent for task ${task.id} after ${maxRetries} attempts:`,
 						errorMsg
 					);
-					// Don't mark as notified — allow future retry via refreshStatuses or Monitor
+					// Safety net: ensure status is NOT marked as notified so future
+					// retry attempts (via refreshStatuses or Monitor) are not blocked
+					notifiedStatuses.delete(task.status);
 				}
 			}
 		}
@@ -931,10 +1078,16 @@ Use the agentuity_background_output tool with task_id "${task.id}" to view the r
 		const now = Date.now();
 		for (const task of this.tasks.values()) {
 			if (task.status !== 'pending' && task.status !== 'running') continue;
-			const start = task.startedAt?.getTime() ?? task.queuedAt?.getTime();
-			if (!start) continue;
-			if (now - start > this.config.staleTimeoutMs) {
-				this.failTask(task, 'Background task timed out.');
+			// Use last activity time (last event received) rather than start time.
+			// A task actively doing tool calls every minute should never expire —
+			// only tasks that have gone silent for staleTimeoutMs should be killed.
+			const lastActivity =
+				task.progress?.lastUpdate.getTime() ??
+				task.startedAt?.getTime() ??
+				task.queuedAt?.getTime();
+			if (!lastActivity) continue;
+			if (now - lastActivity > this.config.staleTimeoutMs) {
+				this.failTask(task, 'Background task timed out (no activity).');
 			}
 		}
 	}

package/src/background/types.ts

@@ -7,6 +7,8 @@ export interface TaskProgress {
 	lastUpdate: Date;
 	lastMessage?: string;
 	lastMessageAt?: Date;
+	/** Number of tool calls currently in-flight (pending/running state) */
+	activeToolCallsInFlight: number;
 }
 
 export interface BackgroundTask {
@@ -27,6 +29,7 @@ export interface BackgroundTask {
 	concurrencyKey?: string; // Active concurrency slot key
 	concurrencyGroup?: string; // Persistent key for re-acquiring on resume
 	notifiedStatuses?: Set<BackgroundTaskStatus>; // Tracks statuses already notified to prevent duplicates
+	isMonitor?: boolean; // True if this task is an auto-launched Monitor agent
 }
 
 export interface LaunchInput {