feat(server): richer subagent labels from sibling meta.json

The CLI writes agent-<id>.meta.json next to every subagent transcript.
Classic Task subagents carry description + agentType; workflow agents
carry agentType only (often the generic 'workflow-subagent').

resolveSubagentLabel now resolves in tiers: meta description, parent
Agent tool_use match, meta agentType + prompt first sentence, prompt
first sentence. On real data this turns eight identical truncated
'Repo root: /Users/...' workflow heroes into 'Explore: <task>' labels
and gives classic subagents their exact Agent-tool description without
scanning the parent transcript.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: FulAppiOS

server/src/parsers/subagent-label.test.ts

@@ -153,6 +153,60 @@ describe('resolveSubagentLabel', () => {
     expect(label).toBe('Audit Y');
   });
 
+  test('prefers description from the sibling meta.json over everything', async () => {
+    await writeFile(subagentPath, jsonline({
+      type: 'user',
+      message: { role: 'user', content: 'Run a thorough audit of X' },
+    }));
+    await writeFile(subagentPath.replace('.jsonl', '.meta.json'), JSON.stringify({
+      agentType: 'Explore',
+      description: 'Verify Claude Code lifecycle hooks',
+      toolUseId: 'toolu_123',
+    }));
+    await writeFile(parentPath, jsonline({
+      type: 'assistant',
+      message: {
+        role: 'assistant',
+        content: [{
+          type: 'tool_use',
+          name: 'Agent',
+          input: { description: 'Audit X for regressions', prompt: 'Run a thorough audit of X' },
+        }],
+      },
+    }));
+
+    const label = await resolveSubagentLabel(subagentPath);
+    expect(label).toBe('Verify Claude Code lifecycle hooks');
+  });
+
+  test('combines meta agentType with the prompt first sentence for workflow agents', async () => {
+    const workflowDir = join(projectDir, parentSessionId, 'subagents', 'workflows', 'wf_0f3513d0-3cc');
+    await mkdir(workflowDir, { recursive: true });
+    const workflowAgentPath = join(workflowDir, 'agent-a2282a1d2c6a1932f.jsonl');
+    await writeFile(workflowAgentPath, jsonline({
+      type: 'user',
+      message: { role: 'user', content: 'Esplora il backend Laravel. Rispondi con snippet.' },
+    }));
+    await writeFile(workflowAgentPath.replace('.jsonl', '.meta.json'), JSON.stringify({ agentType: 'Explore' }));
+
+    const label = await resolveSubagentLabel(workflowAgentPath);
+    expect(label).toBe('Explore: Esplora il backend Laravel');
+  });
+
+  test('drops the generic workflow-subagent agentType from meta.json', async () => {
+    const workflowDir = join(projectDir, parentSessionId, 'subagents', 'workflows', 'wf_2ca7ddd8-324');
+    await mkdir(workflowDir, { recursive: true });
+    const workflowAgentPath = join(workflowDir, 'agent-afa8678eb14a03831.jsonl');
+    await writeFile(workflowAgentPath, jsonline({
+      type: 'user',
+      message: { role: 'user', content: 'Write the plan. Then stop.' },
+    }));
+    await writeFile(workflowAgentPath.replace('.jsonl', '.meta.json'), JSON.stringify({ agentType: 'workflow-subagent' }));
+
+    const label = await resolveSubagentLabel(workflowAgentPath);
+    expect(label).toBe('Write the plan');
+  });
+
   test('ignores parent Agent invocations with non-matching prompt', async () => {
     await writeFile(subagentPath, jsonline({
       type: 'user',

server/src/parsers/subagent-label.ts

@@ -34,6 +34,34 @@ function firstSentenceFallback(prompt: string): string | undefined {
   return cleaned.length > 0 ? truncate(cleaned) : undefined;
 }
 
+interface SubagentMeta {
+  description?: string;
+  agentType?: string;
+}
+
+/**
+ * Read the sibling `agent-*.meta.json` the CLI writes next to each subagent
+ * transcript. Classic Task subagents carry `description` + `agentType`;
+ * workflow agents usually only `agentType` (the generic `workflow-subagent`
+ * value carries no information and is dropped).
+ */
+async function readSubagentMeta(filePath: string): Promise<SubagentMeta> {
+  const metaFile = Bun.file(filePath.replace(/\.jsonl$/, '.meta.json'));
+  try {
+    if (!(await metaFile.exists())) return {};
+    const meta = (await metaFile.json()) as { description?: unknown; agentType?: unknown };
+    const description = typeof meta.description === 'string' && meta.description.length > 0
+      ? meta.description
+      : undefined;
+    const agentType = typeof meta.agentType === 'string' && meta.agentType.length > 0 && meta.agentType !== 'workflow-subagent'
+      ? meta.agentType
+      : undefined;
+    return { description, agentType };
+  } catch {
+    return {};
+  }
+}
+
 function readFirstLineContent(text: string): string | undefined {
   const [firstLine] = text.split('\n', 1);
   if (firstLine === undefined || firstLine.trim() === '') return undefined;
@@ -74,11 +102,14 @@ function matchAgentLabel(parentText: string, targetPrompt: string): string | und
 /**
  * Given a subagent JSONL path (`.../<parentSessionId>/subagents/agent-*.jsonl`,
  * or the ultra-mode variant `.../<parentSessionId>/subagents/workflows/wf_<runId>/agent-*.jsonl`),
- * return a human-readable label by correlating the child's first user prompt
- * against the parent's `Agent` tool_use invocations. Falls back to the first
- * sentence of the subagent prompt when the parent can't be found or doesn't
- * carry an exact prompt match — always the case for workflow agents, whose
- * prompts live in the Workflow script rather than in the parent transcript.
+ * return a human-readable label. Tiers, best first:
+ *
+ * 1. `description` from the sibling `agent-*.meta.json`
+ * 2. the parent's matching `Agent` tool_use (description / subagent_type)
+ * 3. `agentType` from meta.json combined with the prompt's first sentence —
+ *    the only informative pair for workflow agents, whose prompts live in
+ *    the Workflow script rather than in the parent transcript
+ * 4. the first sentence of the subagent prompt
  *
  * Returns `undefined` for non-subagent paths or when nothing usable is available.
  */
@@ -90,6 +121,9 @@ export async function resolveSubagentLabel(filePath: string): Promise<string | u
   }
   if (basename(subagentsDir) !== 'subagents') return undefined;
 
+  const meta = await readSubagentMeta(filePath);
+  if (meta.description !== undefined) return truncate(meta.description);
+
   const parentSessionDir = dirname(subagentsDir);
   const projectDir = dirname(parentSessionDir);
   const parentSessionId = basename(parentSessionDir);
@@ -99,14 +133,19 @@ export async function resolveSubagentLabel(filePath: string): Promise<string | u
   if (!(await childFile.exists())) return undefined;
   const childText = await childFile.text();
   const prompt = readFirstLineContent(childText);
-  if (prompt === undefined) return undefined;
 
-  const parentFile = Bun.file(parentPath);
-  if (await parentFile.exists()) {
-    const parentText = await parentFile.text();
-    const matched = matchAgentLabel(parentText, prompt);
-    if (matched !== undefined) return matched;
+  if (prompt !== undefined) {
+    const parentFile = Bun.file(parentPath);
+    if (await parentFile.exists()) {
+      const parentText = await parentFile.text();
+      const matched = matchAgentLabel(parentText, prompt);
+      if (matched !== undefined) return matched;
+    }
   }
 
-  return firstSentenceFallback(prompt);
+  const sentence = prompt !== undefined ? firstSentenceFallback(prompt) : undefined;
+  if (meta.agentType !== undefined) {
+    return truncate(sentence !== undefined ? `${meta.agentType}: ${sentence}` : meta.agentType);
+  }
+  return sentence;
 }