@agentuity/opencode 1.0.16 → 1.0.18

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()) {
@@ -324,6 +349,17 @@ export class BackgroundManager {
 					if (matchedTaskId) {
 						const task = this.tasks.get(matchedTaskId);
 						if (task) {
+							// Terminal tasks are final — never overwrite their status.
+							// The API can return undefined/unknown status for cleaned-up sessions
+							// which maps to 'pending' by default; without this guard that would
+							// illegally resurrect a completed/errored/cancelled task.
+							if (
+								task.status === 'completed' ||
+								task.status === 'error' ||
+								task.status === 'cancelled'
+							) {
+								continue;
+							}
 							const newStatus = this.mapSessionStatusToTaskStatus(childSession);
 							if (newStatus !== task.status) {
 								// Use proper handlers to trigger side effects (concurrency, notifications, etc.)
@@ -400,6 +436,7 @@ export class BackgroundManager {
 								progress: {
 									toolCalls: 0,
 									lastUpdate: new Date(),
+									activeToolCallsInFlight: 0,
 								},
 							};
 
@@ -485,6 +522,7 @@ export class BackgroundManager {
 						progress: {
 							toolCalls: 0,
 							lastUpdate: new Date(),
+							activeToolCallsInFlight: 0,
 						},
 					};
 
@@ -522,7 +560,7 @@ export class BackgroundManager {
 
 	private mapSessionStatusToTaskStatus(session: unknown): BackgroundTaskStatus {
 		// Map OpenCode session status to our task status
-		// Session status types: 'idle' | 'pending' | 'running' | 'error'
+		// Session status types: 'idle' | 'pending' | 'running' | 'compacting' | 'error'
 		const status = (session as { status?: { type?: string } })?.status?.type;
 		switch (status) {
 			case 'idle':
@@ -530,11 +568,14 @@ export class BackgroundManager {
 			case 'pending':
 				return 'pending';
 			case 'running':
+			case 'compacting': // Session is compacting context — still actively running
 				return 'running';
 			case 'error':
 				return 'error';
 			default:
-				// Unknown session status - default to pending for best-effort recovery
+				// Unknown session status - default to pending for best-effort recovery.
+				// Note: refreshStatuses() guards terminal tasks before calling this,
+				// so a 'pending' default can never downgrade a completed/errored task.
 				return 'pending';
 		}
 	}
@@ -587,12 +628,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,10 +690,77 @@ 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(),
+				// Monitor uses a dedicated concurrency lane so it can never be blocked
+				// by the tasks it's watching. If Monitor queued behind regular tasks it
+				// would never start, and Lead would receive no consolidated report.
+				concurrencyGroup: 'monitor',
+				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;
 
-		const concurrencyKey = this.getConcurrencyKey(task.agent);
+		// Use task.concurrencyGroup if explicitly set (e.g. 'monitor' for the auto-launched
+		// Monitor agent), otherwise derive from the agent name. This lets Monitor run in its
+		// own concurrency lane so it can never be blocked by the tasks it's watching.
+		const concurrencyKey = task.concurrencyGroup ?? this.getConcurrencyKey(task.agent);
 		task.concurrencyKey = concurrencyKey;
 
 		try {
@@ -725,16 +849,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 +895,7 @@ export class BackgroundManager {
 		return {
 			toolCalls: 0,
 			lastUpdate: new Date(),
+			activeToolCallsInFlight: 0,
 		};
 	}
 
@@ -794,21 +940,44 @@ 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;
+		}
 
-		if (notifiedStatuses.has(task.status)) {
+		// Snapshot status at call-time to prevent race conditions where concurrent
+		// refreshStatuses() calls mutate task.status during our async awaits below.
+		// Without this, the wrong status could be recorded as notified after delivery.
+		const statusAtCallTime = task.status;
+
+		const notifiedStatuses = task.notifiedStatuses;
+		if (notifiedStatuses.has(statusAtCallTime)) {
 			return; // Already notified for this status, skip duplicate
 		}
 
-		const statusLine = task.status === 'completed' ? 'completed' : task.status;
-		const message = `[BACKGROUND TASK ${statusLine.toUpperCase()}]
+		// Belt-and-suspenders: rate limit notifications per task+status to 1 per 10s
+		const now = Date.now();
+		const lastNotifyKey = `${task.id}:${statusAtCallTime}`;
+		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 message = `[BACKGROUND TASK ${statusAtCallTime.toUpperCase()}]
 
 Task: ${task.description}
 Agent: ${task.agent}
-Status: ${task.status}
+Status: ${statusAtCallTime}
 Task ID: ${task.id}
 
 Use the agentuity_background_output tool with task_id "${task.id}" to view the result.`;
@@ -825,8 +994,10 @@ Use the agentuity_background_output tool with task_id "${task.id}" to view the r
 					responseStyle: 'data',
 					...this.getClientOverrides(),
 				});
-				// Mark as notified only AFTER confirmed delivery
-				notifiedStatuses.add(task.status);
+				// Mark the snapshotted status as notified only AFTER confirmed delivery.
+				// Using the snapshot prevents recording the wrong status if task.status
+				// was mutated concurrently during the await above.
+				notifiedStatuses.add(statusAtCallTime);
 				task.notifiedStatuses = notifiedStatuses;
 				return; // Success
 			} catch (error) {
@@ -840,7 +1011,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(statusAtCallTime);
 				}
 			}
 		}
@@ -931,10 +1104,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 {

package/src/config/loader.ts

@@ -146,7 +146,7 @@ const DEFAULT_BLOCKED_COMMANDS = [
 
 const DEFAULT_BACKGROUND_CONFIG: BackgroundTaskConfig = {
 	enabled: true,
-	defaultConcurrency: 1,
+	defaultConcurrency: 5,
 	staleTimeoutMs: 30 * 60 * 1000,
 	providerConcurrency: {},
 	modelConcurrency: {},
@@ -199,7 +199,7 @@ function mergeBackgroundConfig(
 	if (!base && !override) return undefined;
 	return {
 		enabled: override?.enabled ?? base?.enabled ?? true,
-		defaultConcurrency: override?.defaultConcurrency ?? base?.defaultConcurrency ?? 1,
+		defaultConcurrency: override?.defaultConcurrency ?? base?.defaultConcurrency ?? 5,
 		staleTimeoutMs: override?.staleTimeoutMs ?? base?.staleTimeoutMs ?? 30 * 60 * 1000,
 		providerConcurrency: {
 			...(base?.providerConcurrency ?? {}),

package/src/plugin/hooks/cadence.ts

@@ -197,7 +197,10 @@ export function createCadenceHooks(
 
 			log(`Event received: ${event.type}`);
 
-			// Handle session.compacted - save compaction AND continue loop
+			// Handle session.compacted - save compaction AND continue loop.
+			// Note: Compaction continues in the SAME session (via session.prompt with
+			// the existing sessionId), so permissions configured in the config hook
+			// (plugin.ts) are automatically inherited — no re-application needed.
 			if (event.type === 'session.compacted') {
 				const sessionId = event.sessionId;
 				if (!sessionId) return;
@@ -379,14 +382,7 @@ ${taskList}
 Use \`agentuity_background_output({ task_id: "..." })\` to check their status.
 Use \`agentuity_session_dashboard({ session_id: "..." })\` to get a full session tree with status, costs, and health summary for Lead-of-Leads monitoring.
 
-**Tip:** If you spawned child Leads for parallel work, delegate monitoring to BackgroundMonitor:
-\`\`\`typescript
-agentuity_background_task({
-  agent: "monitor",
-  task: "Monitor these background tasks and report when all complete:\\n${tasks.map((t) => `- ${t.id}`).join('\\n')}",
-  description: "Monitor child tasks"
-})
-\`\`\``;
+**Tip:** A Monitor agent is auto-launched to watch these tasks. You will receive \`[BACKGROUND TASK COMPLETED]\` notifications as each task finishes, and \`[ALL BACKGROUND TASKS COMPLETE]\` when all are done. Use \`agentuity_session_dashboard\` for a unified progress view.`;
 			}
 
 			// 5. Build SQLite dashboard section

package/src/plugin/hooks/completion.ts

@@ -0,0 +1,81 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { CoderConfig } from '../../types';
+
+export interface CompletionHooks {
+	onParams: (input: unknown) => void;
+	onMessage: (input: unknown) => void;
+}
+
+/**
+ * Creates hooks for logging agent completion metrics.
+ *
+ * Tracks the start of each LLM call (via chat.params) and logs
+ * agent name, model, and duration when the response arrives (via chat.message).
+ */
+export function createCompletionHooks(ctx: PluginInput, _config: CoderConfig): CompletionHooks {
+	const startTimes = new Map<string, { startedAt: number; agent?: string; model?: string }>();
+
+	return {
+		onParams(input: unknown): void {
+			// OpenCode passes agent and model as structured objects (not plain strings)
+			// in the chat.params hook. Normalize to string here so template literals
+			// don't produce '[object Object]' in the completion log.
+			const inp = input as {
+				sessionID?: string;
+				agent?: unknown;
+				model?: unknown;
+			};
+			if (!inp.sessionID) return;
+
+			const agentStr =
+				typeof inp.agent === 'string'
+					? inp.agent
+					: ((inp.agent as { id?: string; name?: string; displayName?: string } | null)
+							?.displayName ??
+						(inp.agent as { id?: string; name?: string } | null)?.name ??
+						(inp.agent as { id?: string } | null)?.id ??
+						String(inp.agent ?? 'unknown'));
+
+			const modelStr =
+				typeof inp.model === 'string'
+					? inp.model
+					: ((inp.model as { id?: string; name?: string } | null)?.id ??
+						(inp.model as { name?: string } | null)?.name ??
+						String(inp.model ?? 'unknown'));
+
+			startTimes.set(inp.sessionID, {
+				startedAt: Date.now(),
+				agent: agentStr,
+				model: modelStr,
+			});
+		},
+
+		onMessage(input: unknown): void {
+			const inp = input as { sessionID?: string };
+			if (!inp.sessionID) return;
+
+			const start = startTimes.get(inp.sessionID);
+			if (!start) return;
+
+			const durationMs = Date.now() - start.startedAt;
+			const durationSec = (durationMs / 1000).toFixed(1);
+
+			const logLine = `Completion: agent=${start.agent} model=${start.model} duration=${durationSec}s`;
+
+			// Verbose local logging for immediate visibility
+			console.debug(`[agentuity-coder] ${logLine}`);
+
+			// Also send to the OpenCode log service
+			ctx.client.app.log({
+				body: {
+					service: 'agentuity-coder',
+					level: 'debug',
+					message: logLine,
+				},
+			});
+
+			// Clean up after logging
+			startTimes.delete(inp.sessionID);
+		},
+	};
+}

package/src/plugin/hooks/params.ts

@@ -1,5 +1,5 @@
 import type { PluginInput } from '@opencode-ai/plugin';
-import type { CoderConfig } from '../../types';
+import type { AgentConfig, CoderConfig } from '../../types';
 
 export interface ParamsHooks {
 	onParams: (input: unknown, output: unknown) => Promise<void>;
@@ -199,3 +199,99 @@ export function createParamsHooks(
  *
  * Note: Triggers use multi-word phrases to avoid false positives from common words.
  */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Model Fallback Chain
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Retryable HTTP status codes that should trigger model fallback */
+export const RETRYABLE_STATUS_CODES = [429, 500, 502, 503] as const;
+
+/**
+ * Tracks API errors per agent to enable model fallback on subsequent calls.
+ *
+ * When an agent's primary model fails with a retryable error (429, 500, 502, 503),
+ * the next `chat.params` call can select a fallback model from the agent's
+ * `fallbackModels` list.
+ *
+ * Current limitation: The `chat.params` hook can modify temperature/topP/topK/options
+ * but CANNOT change the model itself (model is in the input, not output). Full model
+ * fallback requires one of:
+ *   1. A `chat.error` hook that allows retrying with a different model
+ *   2. A `chat.model` hook that allows overriding the model selection
+ *   3. Adding `model` to the `chat.params` output type
+ *
+ * TODO: When OpenCode adds a suitable hook, implement the retry logic here:
+ *   - On API error (429/5xx), record the failure in `agentErrorState`
+ *   - On next `chat.params` call for the same agent, select next fallback model
+ *   - Log: `[ModelFallback] Switching from ${currentModel} to ${fallbackModel} due to ${error}`
+ *   - Reset fallback state after successful completion or after TTL expires
+ */
+export class ModelFallbackTracker {
+	/**
+	 * Map of agent name → { failedModel, failedAt, errorCode, fallbackIndex }
+	 * Used to track which agents have experienced API errors.
+	 */
+	private agentErrorState = new Map<
+		string,
+		{
+			failedModel: string;
+			failedAt: number;
+			errorCode: number;
+			fallbackIndex: number;
+		}
+	>();
+
+	/** TTL for error state — reset after 5 minutes */
+	private readonly ERROR_STATE_TTL_MS = 5 * 60 * 1000;
+
+	/**
+	 * Record an API error for an agent. Call this from an event handler
+	 * when a retryable API error is detected.
+	 */
+	recordError(agentName: string, model: string, errorCode: number): void {
+		const existing = this.agentErrorState.get(agentName);
+		const fallbackIndex = existing ? existing.fallbackIndex + 1 : 0;
+		this.agentErrorState.set(agentName, {
+			failedModel: model,
+			failedAt: Date.now(),
+			errorCode,
+			fallbackIndex,
+		});
+		console.debug(
+			`[ModelFallback] Recorded error for ${agentName}: model=${model} code=${errorCode} fallbackIndex=${fallbackIndex}`
+		);
+	}
+
+	/**
+	 * Get the next fallback model for an agent, if one is available.
+	 * Returns undefined if no fallback is needed or available.
+	 */
+	getNextFallback(agentName: string, agentConfig: AgentConfig): string | undefined {
+		const state = this.agentErrorState.get(agentName);
+		if (!state) return undefined;
+
+		// Check TTL
+		if (Date.now() - state.failedAt > this.ERROR_STATE_TTL_MS) {
+			this.agentErrorState.delete(agentName);
+			return undefined;
+		}
+
+		const fallbacks = agentConfig.fallbackModels;
+		if (!fallbacks?.length) return undefined;
+
+		if (state.fallbackIndex >= fallbacks.length) {
+			// Exhausted all fallbacks
+			return undefined;
+		}
+
+		return fallbacks[state.fallbackIndex];
+	}
+
+	/**
+	 * Clear error state for an agent (e.g., after successful completion).
+	 */
+	clearError(agentName: string): void {
+		this.agentErrorState.delete(agentName);
+	}
+}

package/src/plugin/hooks/session-memory.ts

@@ -51,6 +51,10 @@ export function createSessionMemoryHooks(
 		/**
 		 * Listen for session.compacted event.
 		 * The compaction summary is already in context - just tell Lead to save it.
+		 *
+		 * Note: Compaction continues in the SAME session (via session.prompt with
+		 * the existing sessionId), so permissions configured in the config hook
+		 * (plugin.ts) are automatically inherited — no re-application needed.
 		 */
 		async onEvent(input: {
 			event: { type: string; properties?: Record<string, unknown> };

package/src/plugin/hooks/tools.ts

@@ -165,7 +165,38 @@ export function createToolHooks(ctx: PluginInput, config: CoderConfig): ToolHook
 			}
 		},
 
-		async after(_input: unknown, _output: unknown): Promise<void> {},
+		async after(input: unknown, output: unknown): Promise<void> {
+			// Graceful handling for unavailable tools: if a tool execution produced an
+			// error indicating the tool doesn't exist or is unavailable, normalize the
+			// output to a helpful message so the session continues instead of crashing.
+			const toolName = extractToolName(input);
+			if (!toolName) return;
+
+			const out = output as {
+				output?: string;
+				title?: string;
+				metadata?: Record<string, unknown>;
+			};
+			if (typeof out.output !== 'string') return;
+
+			const lower = out.output.toLowerCase();
+			const isToolMissing =
+				(lower.includes('not found') ||
+					lower.includes('not available') ||
+					lower.includes('does not exist') ||
+					lower.includes('unknown tool') ||
+					lower.includes('no such tool')) &&
+				(lower.includes('tool') || lower.includes(toolName.toLowerCase()));
+
+			if (isToolMissing) {
+				out.output = JSON.stringify({
+					error: `Tool '${toolName}' is not available in this session. It may have been removed or is not installed. Please use an alternative approach or ask the user for guidance.`,
+					tool: toolName,
+					recoverable: true,
+				});
+				out.title = `Tool unavailable: ${toolName}`;
+			}
+		},
 	};
 }