feat: skip/filter subagent observations (Dynamic Workflows) — thedotmack#2736

Claude Code Dynamic Workflows fan a single prompt out to tens-to-hundreds of
parallel subagents (agent_type `workflow-subagent`). Every tool call fires a
PostToolUse hook → claude-mem creates one provider-analyzed observation per
call, so a single run emits hundreds-to-thousands of low-signal observations.
That exhausts the provider's free-tier quota (HTTP 429) and trips the restart
guard, dropping the rest of the run — including valuable main-session work.

Add two settings, filtered BEFORE any worker HTTP call or provider request so
the round-trip and the provider tokens are saved:

- CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS (default `false`) — skip every
  observation carrying an agentId. The robust, type-independent lever.
- CLAUDE_MEM_SKIP_AGENT_TYPES (default empty) — comma-separated agent_type skip
  list, e.g. `workflow-subagent,Explore`.

Both default off to preserve current behavior (per the issue's acceptance
criteria); `workflow-subagent` is documented as the recommended value. The two
combine as a union: skip if the global toggle matches OR the agent_type is listed.

Implementation:
- New pure helper src/shared/should-skip-agent-observation.ts — single source of
  truth for both filtering points.
- Hook handler (src/cli/handlers/observation.ts) filters ahead of the runtime
  branch, so it covers both the worker and server-beta runtimes.
- Worker ingestObservation (src/services/worker/http/shared.ts) filters again as
  defense-in-depth for any non-hook caller, before the provider call.
- Settings wired into SettingsDefaultsManager (interface + defaults) and the
  viewer constants; documented in docs/public/configuration.mdx.
- Tests: helper unit tests + hook-handler integration covering worker and
  server-beta runtimes, main-session-unaffected, global toggle, and per-type list.
- Rebuilt plugin bundles.

Future work (out of scope): an optional per-session/minute throughput guard for
runaway bursts from any source.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: NRKZOZW

docs/public/configuration.mdx

@@ -22,6 +22,43 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
 | `CLAUDE_MEM_WORKER_HOST`      | `127.0.0.1`                     | Worker service host address           |
 | `CLAUDE_MEM_DATA_DIR`         | `~/.claude-mem`                 | Data root — every other path (database, chroma, logs, settings.json, worker.pid) derives from this |
 | `CLAUDE_MEM_SKIP_TOOLS`       | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |
+| `CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS` | `false`               | When `true`, skip **every** subagent observation (any tool call carrying an `agentId`). See [Subagent & Dynamic Workflow filtering](#subagent--dynamic-workflow-filtering). |
+| `CLAUDE_MEM_SKIP_AGENT_TYPES` | _(empty)_                       | Comma-separated `agent_type` values to skip, e.g. `workflow-subagent,Explore,Plan`. Main-session observations are unaffected. |
+
+### Subagent & Dynamic Workflow filtering
+
+Claude Code [Dynamic Workflows](https://code.claude.com/docs/en/workflows) fan a single
+prompt out to tens-to-hundreds of parallel subagents (`agent_type: workflow-subagent`).
+Every tool call by every subagent fires a `PostToolUse` hook, so claude-mem creates one
+provider-analyzed observation per call — a single run can emit **hundreds-to-thousands**
+of low-signal observations. That can exhaust the configured provider's free-tier quota
+(HTTP 429) and drop the rest of the run, including valuable main-session work.
+
+Two settings let you filter these out **before** any worker round-trip or provider call.
+Both default to off, so existing behavior is preserved.
+
+- **Drop all subagent noise (recommended for heavy workflow users):**
+
+  ```json
+  { "CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS": "true" }
+  ```
+
+  This is the robust lever — it keys off the presence of an `agentId`, so it catches
+  every subagent regardless of type. Main-session observations are kept.
+
+- **Surgically drop specific agent types** (keep some subagents, drop others):
+
+  ```json
+  { "CLAUDE_MEM_SKIP_AGENT_TYPES": "workflow-subagent" }
+  ```
+
+  Add a comma-separated list of `agent_type` values. The two settings combine as a
+  union: an observation is skipped if the global toggle matches **or** its `agent_type`
+  is in the list.
+
+> Subagent **summaries** are already skipped automatically; these settings add the same
+> control for **observations**. Durable cross-session knowledge generally comes from the
+> main session, so dropping ephemeral subagent steps usually improves signal-to-noise.
 
 ### Gemini Provider Settings
 

plugin/scripts/context-generator.cjs

@@ -7,6 +7,8 @@ import { executeWithWorkerFallback, isWorkerFallback } from '../../shared/worker
 import { logger } from '../../utils/logger.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
 import { shouldTrackProject } from '../../shared/should-track-project.js';
+import { shouldSkipAgentObservation } from '../../shared/should-skip-agent-observation.js';
+import { loadFromFileOnce } from '../../shared/hook-settings.js';
 import { normalizePlatformSource } from '../../shared/platform-source.js';
 import { resolveRuntimeContext, logServerBetaFallback } from '../../services/hooks/runtime-selector.js';
 import { isServerBetaClientError } from '../../services/hooks/server-beta-client.js';
@@ -60,6 +62,20 @@ export const observationHandler: EventHandler = {
       return { continue: true, suppressOutput: true };
     }
 
+    // #2736 — drop subagent observations BEFORE any worker HTTP call or provider
+    // request. Placed ahead of the runtime branch so it covers both the worker
+    // and server-beta runtimes. Saves the round-trip and the provider tokens,
+    // and prevents Dynamic Workflows fan-out from exhausting provider quota.
+    const skip = shouldSkipAgentObservation(input.agentId, input.agentType, loadFromFileOnce());
+    if (skip.skip) {
+      logger.debug('HOOK', `Skipping observation: ${skip.reason}`, {
+        toolName,
+        agentId: input.agentId,
+        agentType: input.agentType,
+      });
+      return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+    }
+
     const runtime = resolveRuntimeContext();
     if (runtime.runtime === 'server-beta') {
       try {

plugin/scripts/mcp-server.cjs

@@ -6,6 +6,7 @@ import type { SessionEventBroadcaster } from '../events/SessionEventBroadcaster.
 import type { ParsedSummary } from '../../../sdk/parser.js';
 import { stripMemoryTagsFromJson } from '../../../utils/tag-stripping.js';
 import { isProjectExcluded } from '../../../utils/project-filter.js';
+import { shouldSkipAgentObservation } from '../../../shared/should-skip-agent-observation.js';
 import { SettingsDefaultsManager } from '../../../shared/SettingsDefaultsManager.js';
 import { USER_SETTINGS_PATH } from '../../../shared/paths.js';
 import { getProjectContext } from '../../../utils/project-name.js';
@@ -114,6 +115,15 @@ export async function ingestObservation(payload: ObservationPayload): Promise<In
     return { ok: true, status: 'skipped', reason: 'tool_excluded' };
   }
 
+  // #2736 — defense in depth: the hook handler already filters subagent
+  // observations before this HTTP call, but skip again here so any non-hook
+  // caller (direct API, future ingestion paths) is filtered before the
+  // queueObservation → provider request below.
+  const agentSkip = shouldSkipAgentObservation(payload.agentId, payload.agentType, settings);
+  if (agentSkip.skip) {
+    return { ok: true, status: 'skipped', reason: agentSkip.reason! };
+  }
+
   const fileOperationTools = new Set(['Edit', 'Write', 'Read', 'NotebookEdit']);
   if (fileOperationTools.has(payload.toolName) && payload.toolInput && typeof payload.toolInput === 'object') {
     const input = payload.toolInput as { file_path?: string; notebook_path?: string };

plugin/scripts/server-beta-service.cjs

@@ -9,7 +9,9 @@ export interface SettingsDefaults {
   CLAUDE_MEM_WORKER_PORT: string;
   CLAUDE_MEM_WORKER_HOST: string;
   CLAUDE_MEM_SKIP_TOOLS: string;
-  CLAUDE_MEM_PROVIDER: string;  
+  CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS: string;  // #2736 — skip ALL subagent observations (any hook event carrying an agentId)
+  CLAUDE_MEM_SKIP_AGENT_TYPES: string;            // #2736 — comma-separated agent_type values to skip (e.g. workflow-subagent,Explore)
+  CLAUDE_MEM_PROVIDER: string;
   CLAUDE_MEM_CLAUDE_AUTH_METHOD: string;  
   CLAUDE_MEM_GEMINI_API_KEY: string;
   CLAUDE_MEM_GEMINI_MODEL: string;  
@@ -89,6 +91,8 @@ export class SettingsDefaultsManager {
     CLAUDE_MEM_WORKER_PORT: String(37700 + ((process.getuid?.() ?? 77) % 100)),
     CLAUDE_MEM_WORKER_HOST: '127.0.0.1',
     CLAUDE_MEM_SKIP_TOOLS: 'ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion',
+    CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS: 'false',  // #2736 — default off preserves current behavior; set 'true' to skip every subagent observation (recommended for heavy Dynamic Workflows users)
+    CLAUDE_MEM_SKIP_AGENT_TYPES: '',                 // #2736 — default empty preserves current behavior; recommended value 'workflow-subagent' to drop Dynamic Workflows fan-out noise
     CLAUDE_MEM_PROVIDER: 'claude',  // Default to Claude
     CLAUDE_MEM_CLAUDE_AUTH_METHOD: 'subscription',  // Default to logged-in Claude SDK auth (not API key)
     CLAUDE_MEM_GEMINI_API_KEY: '',  // Empty by default, can be set via UI or env

plugin/scripts/worker-service.cjs

@@ -0,0 +1,75 @@
+// Shared, pure decision helper for skipping subagent observations (issue #2736).
+//
+// Two filtering points call this with the SAME logic so behavior can't drift:
+//   1. The PostToolUse hook handler (src/cli/handlers/observation.ts) — runs in
+//      the short-lived hook process BEFORE any worker HTTP call or provider
+//      request, so a skipped observation costs nothing. This covers both the
+//      `worker` and `server-beta` runtimes because it sits ahead of the runtime
+//      branch.
+//   2. The worker ingest path (src/services/worker/http/shared.ts) — defense in
+//      depth for any caller that reaches the worker without going through the
+//      hook handler (direct API callers, future ingestion paths).
+//
+// Motivation: Claude Code Dynamic Workflows fan a single prompt out to
+// tens-to-hundreds of parallel subagents (agent_type `workflow-subagent`), each
+// tool call firing a PostToolUse hook → one provider-analyzed observation. A
+// single run can emit hundreds-to-thousands of low-signal observations, which
+// exhausts the configured provider's quota (HTTP 429) and trips the restart
+// guard, dropping the rest of the run — including valuable main-session work.
+
+export type AgentSkipReason = 'subagent_observation' | 'agent_type_excluded';
+
+export interface AgentSkipSettings {
+  /** When 'true', skip every observation carrying an agentId (any subagent). */
+  CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS: string;
+  /** Comma-separated agent_type values to skip (e.g. "workflow-subagent,Explore"). */
+  CLAUDE_MEM_SKIP_AGENT_TYPES: string;
+}
+
+export interface AgentSkipDecision {
+  skip: boolean;
+  reason?: AgentSkipReason;
+}
+
+const NO_SKIP: AgentSkipDecision = { skip: false };
+
+/** Parse a comma-separated agent_type skip list into a trimmed, de-duped set. */
+export function parseSkipAgentTypes(raw: string | undefined | null): Set<string> {
+  return new Set(
+    (raw ?? '')
+      .split(',')
+      .map(t => t.trim())
+      .filter(Boolean)
+  );
+}
+
+/**
+ * Decide whether an observation should be skipped based on its agent context.
+ *
+ * Union semantics (simpler and strictly safer than the issue's "priority"
+ * framing — the global toggle is a superset of any per-type list):
+ *   - If CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS === 'true' AND an agentId is
+ *     present → skip (the robust lever; independent of the exact type string).
+ *   - Else if agentType is in CLAUDE_MEM_SKIP_AGENT_TYPES → skip (surgical).
+ *
+ * Defaults preserve current behavior: with the global toggle off and an empty
+ * skip list, this never skips.
+ */
+export function shouldSkipAgentObservation(
+  agentId: string | undefined | null,
+  agentType: string | undefined | null,
+  settings: AgentSkipSettings,
+): AgentSkipDecision {
+  if (settings.CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS === 'true' && agentId) {
+    return { skip: true, reason: 'subagent_observation' };
+  }
+
+  if (agentType) {
+    const skipTypes = parseSkipAgentTypes(settings.CLAUDE_MEM_SKIP_AGENT_TYPES);
+    if (skipTypes.has(agentType)) {
+      return { skip: true, reason: 'agent_type_excluded' };
+    }
+  }
+
+  return NO_SKIP;
+}