@dreb/coding-agent 2.32.1 → 2.33.0

package/README.md

@@ -384,6 +384,8 @@ The `subagent` tool delegates tasks to independent child agent processes. Each s
 
 **Session metadata:** Each child process records its agent type in the session JSONL header (`agentType` field), providing an audit trail of which agent definition executed the work.
 
+**Background-agent guardrail:** Background subagents run asynchronously and return control to you while they work. To stop the parent agent from spinning ahead of results, a guardrail pauses it after `backgroundAgents.parentTurnLimit` turns (default 3) while subagents are still running. When this happens, dreb surfaces a friendly, non-error notification in the TUI and Telegram — explaining that background agents are still working and the parent paused intentionally, and that it resumes when they report back or when you send a message to steer it. This is a frontend/session event, not a model-context steer, so it can't go stale. Set `backgroundAgents.parentTurnGuardrail` to `false` to let the parent run unbounded while subagents work, or raise `parentTurnLimit` to relax the guardrail. See [settings](docs/settings.md#background-agents).
+
 ---
 
 ## Semantic Search

package/dist/core/agent-session.d.ts

@@ -23,7 +23,7 @@ import { PerformanceTracker } from "./performance-tracker.js";
 import { type PromptTemplate } from "./prompt-templates.js";
 import type { ResourceLoader } from "./resource-loader.js";
 import type { BranchSummaryEntry, SessionManager } from "./session-manager.js";
-import type { SettingsManager } from "./settings-manager.js";
+import { type SettingsManager } from "./settings-manager.js";
 import type { BashOperations } from "./tools/bash.js";
 import { type SessionTask, type SubagentResult } from "./tools/index.js";
 /** Parsed skill block from a user message */
@@ -69,6 +69,11 @@ export type AgentSessionEvent = AgentEvent | {
     agentId: string;
     agentType: string;
     success: boolean;
+} | {
+    type: "parent_paused_for_background_agents";
+    runningAgentCount: number;
+    turnsUsed: number;
+    turnLimit: number;
 } | {
     type: "tasks_update";
     tasks: readonly SessionTask[];
@@ -204,6 +209,8 @@ export declare class AgentSession {
     private _modelRegistry;
     private _tasks;
     private _bgTurnCounter;
+    private _bgRunningAtTurnStart;
+    private _bgPauseNotified;
     private static readonly BG_TURN_LIMIT;
     private _sentinelSteered;
     private _unsubscribeGuardrailSentinel?;
@@ -245,6 +252,12 @@ export declare class AgentSession {
      * - Layer D: Turn limiter — restrict parent to N turns while bg agents are running
      */
     private _installBackgroundAgentGuardrails;
+    /**
+     * Reset the background-agent guardrail counter and the pause-notified flag together.
+     * These two fields are one logical unit — they must always reset in lockstep so a new
+     * pause episode both restarts the turn budget and re-arms the pause notification.
+     */
+    private _resetBgGuardrailState;
     /**
      * Handle background agent completion — builds the delivery message and routes
      * it to the parent agent via the appropriate channel (steer, prompt, or appendMessage).