feat(acp): nest subagent work under parent cards

Subagent narration and tool calls are not peer transcript
events: they belong to the Agent/Task call that spawned
them. Emitting their chunks into the main stream split the
primary bubble, and folding them as top-level tools hid the
parent relationship.

- Detect parent via _meta keys (parentToolCallId variants)
- Drop subagent message/thought chunks from the main stream
- Persist parent id and ordered children; skip parents in folds

Author: nullmastermind

src/AcpConnection.cpp

@@ -961,10 +961,17 @@ void AcpConnection::handleInboundNotification(const QString &method, const QJson
             return;
         m_promptProducedOutput = true;
         noteStreamingActivity();
+        // A subagent's narration is not the agent's answer: its result comes
+        // back through the Agent tool call, and its chunks would interleave
+        // with (and split) the main agent's bubble.
+        if (!AcpProtocol::subagentParentToolCallId(update).isEmpty())
+            return;
         emit messageChunk(text, update.value(QStringLiteral("messageId")).toString());
     } else if (kind == QLatin1String("agent_thought_chunk")) {
         m_promptProducedOutput = true;
         noteStreamingActivity();
+        if (!AcpProtocol::subagentParentToolCallId(update).isEmpty())
+            return; // same as a subagent's message chunk
         const QString text = AcpProtocol::contentBlockToChunkText(
             update.value(QStringLiteral("content")).toObject());
         emit thoughtChunk(text);
@@ -981,6 +988,7 @@ void AcpConnection::handleInboundNotification(const QString &method, const QJson
         tc.rawInput = update.value(QStringLiteral("rawInput")).toObject();
         tc.rawOutput = AcpProtocol::rawOutputToObject(update.value(QStringLiteral("rawOutput")));
         tc.groupId = update.value(QStringLiteral("groupId")).toInt(0);
+        tc.parentToolCallId = AcpProtocol::subagentParentToolCallId(update);
         if (AcpProtocol::isAdvisorToolName(tc.name)) {
             m_advisorToolCallIds.insert(tc.id);
         }
@@ -1021,6 +1029,9 @@ void AcpConnection::handleInboundNotification(const QString &method, const QJson
         if (AcpProtocol::toolCallUpdateIsBackgrounded(update)) {
             u.backgrounded = true;
         }
+        if (QString parent = AcpProtocol::subagentParentToolCallId(update); !parent.isEmpty()) {
+            u.parentToolCallId = std::move(parent);
+        }
         noteScheduledJobUpdate(update);
         const QJsonValue c = update.value(QStringLiteral("content"));
         if (advisorFailed) {

src/AcpProtocol.cpp

@@ -562,6 +562,24 @@ bool toolCallUpdateIsBackgrounded(const QJsonObject &update)
         .value(QStringLiteral("backgrounded")).toBool(false);
 }
 
+QString subagentParentToolCallId(const QJsonObject &update)
+{
+    const QJsonValue metaValue = update.value(QStringLiteral("_meta"));
+    if (!metaValue.isObject())
+        return {}; // the main agent's updates: no lookups past this
+    const QJsonObject meta = metaValue.toObject();
+    QString parent = meta.value(QStringLiteral("parentToolCallId")).toString();
+    if (parent.isEmpty()) {
+        parent = meta.value(QStringLiteral("claudeCode")).toObject()
+                     .value(QStringLiteral("parentToolUseId")).toString();
+    }
+    if (parent.isEmpty())
+        parent = meta.value(QStringLiteral("parentToolUseId")).toString();
+    if (!parent.isEmpty() && parent == update.value(QStringLiteral("toolCallId")).toString())
+        return {};
+    return parent;
+}
+
 QString formatWaitDuration(qint64 ms)
 {
     if (ms < 0) {

src/AcpProtocol.h

@@ -110,6 +110,9 @@ struct AcpToolCall
     // persisted. -1 = unknown (restored/never observed running).
     qint64 startedAtMs{0};
     qint64 durationMs{-1};
+    // Made by a subagent: the Agent/Task tool call that spawned it. Such calls
+    // render nested under that card, never as transcript peers. Persisted.
+    QString parentToolCallId;
 };
 
 // Needle match for ACP tool name or title. Prefer extra over dropping a write.
@@ -156,6 +159,9 @@ struct AcpToolCallUpdate
     std::optional<bool> backgroundRunning;
     // Host-side (not wire): mirrors AcpToolCall::durationMs once known.
     std::optional<qint64> durationMs;
+    // Late subagent attribution (subagentParentToolCallId of the update): an
+    // eager tool_call can miss it, the refining update carries it.
+    std::optional<QString> parentToolCallId;
 };
 
 struct AcpPlanEntry
@@ -346,6 +352,12 @@ bool asyncTaskStateIsLive(const QString &state);
 // `_meta.jetbrains.air.asyncTasks.backgrounded == true` on a tool_call_update.
 bool toolCallUpdateIsBackgrounded(const QJsonObject &update);
 
+// The Agent/Task tool call whose subagent sent this session/update, from its
+// `_meta`: `parentToolCallId`, then `claudeCode.parentToolUseId`
+// (claude-agent-acp), then `parentToolUseId`. Empty for the main agent, and
+// when the id names the update's own tool call.
+QString subagentParentToolCallId(const QJsonObject &update);
+
 // Compact wait clock: "4.2s" under a minute, "2m 05s" under an hour, then "1h 02m".
 QString formatWaitDuration(qint64 ms);
 // Compact tool run time: "<1s", "40s", "1m5s", "1h1m5s".

src/AcpSessionModel.cpp

@@ -242,13 +242,30 @@ void AcpSessionModel::loadFromDisk()
         tc.groupId = to.value(QStringLiteral("groupId")).toInt();
         tc.backgrounded = to.value(QStringLiteral("backgrounded")).toBool(false);
         tc.durationMs = static_cast<qint64>(to.value(QStringLiteral("durationMs")).toDouble(-1));
+        tc.parentToolCallId = to.value(QStringLiteral("parentToolCallId")).toString();
         if (!tc.id.isEmpty()) {
             m_toolCalls.insert(tc.id, tc);
             if (tc.groupId > m_currentGroupId) {
                 m_currentGroupId = tc.groupId;
             }
+            // Arrival order lives on the parent (m_toolCalls is unordered).
+            const QJsonArray children = to.value(QStringLiteral("subagentChildren")).toArray();
+            if (!children.isEmpty()) {
+                QStringList &ids = m_subagentChildren[tc.id];
+                ids.reserve(children.size());
+                for (const auto cv : children) {
+                    if (QString id = cv.toString(); !id.isEmpty())
+                        ids.append(std::move(id));
+                }
+            }
         }
     }
+    // Children whose id the parent's list lacks (hand-edited or older file).
+    for (auto it = m_toolCalls.cbegin(); it != m_toolCalls.cend(); ++it) {
+        const QString &parent = it.value().parentToolCallId;
+        if (!parent.isEmpty() && !m_subagentChildren.value(parent).contains(it.key()))
+            m_subagentChildren[parent].append(it.key());
+    }
 
     // timeline
     const QJsonArray tl = obj.value(QStringLiteral("timeline")).toArray();
@@ -335,6 +352,13 @@ QJsonObject AcpSessionModel::toHistoryJson() const
         if (tc.durationMs >= 0) {
             to.insert(QStringLiteral("durationMs"), static_cast<double>(tc.durationMs));
         }
+        if (!tc.parentToolCallId.isEmpty()) {
+            to.insert(QStringLiteral("parentToolCallId"), tc.parentToolCallId);
+        }
+        if (const auto children = m_subagentChildren.constFind(tc.id);
+            children != m_subagentChildren.constEnd() && !children->isEmpty()) {
+            to.insert(QStringLiteral("subagentChildren"), QJsonArray::fromStringList(*children));
+        }
         if (AskUserForm::isAskUserToolCall(tc.name, tc.title, tc.rawInput)) {
             // Small (validated: <= 30 questions) and needed to restore the form.
             to.insert(QStringLiteral("rawInput"), tc.rawInput);
@@ -642,29 +666,53 @@ void AcpSessionModel::onThoughtChunk(const QString &text)
     schedulePersistIfNeeded();
 }
 
+void AcpSessionModel::attachSubagentChild(const QString &parentToolCallId, const QString &childId)
+{
+    QStringList &ids = m_subagentChildren[parentToolCallId];
+    if (!ids.contains(childId))
+        ids.append(childId);
+}
+
 void AcpSessionModel::onToolCallReceived(const AcpToolCall &tc)
 {
+    // A re-sent tool_call without the meta keeps the attribution it had.
+    QString parentToolCallId = tc.parentToolCallId;
+    if (parentToolCallId.isEmpty()) {
+        const auto prior = m_toolCalls.constFind(tc.id);
+        if (prior != m_toolCalls.constEnd())
+            parentToolCallId = prior->parentToolCallId;
+    }
+    const bool subagentChild = !parentToolCallId.isEmpty();
     // A tool-call card is a new timeline peer — close any active streaming
     // assistant text or thought so a subsequent text/thought chunk opens a
     // fresh bubble below the card instead of merging into the previous one.
-    m_streamingAssistantMessageIndex = -1;
-    m_streamingThoughtMessageIndex = -1;
+    // A subagent's call nests under its Agent card instead: not a peer.
+    if (!subagentChild) {
+        m_streamingAssistantMessageIndex = -1;
+        m_streamingThoughtMessageIndex = -1;
+    }
 
     AcpToolCall copy = tc;
+    copy.parentToolCallId = parentToolCallId;
     copy.groupId = m_currentGroupId;
     if (!AcpProtocol::toolCallStatusIsTerminal(copy.status)) {
         copy.startedAtMs = QDateTime::currentMSecsSinceEpoch();
     }
     AcpProtocol::injectToolCallPath(copy.rawInput, QJsonArray{});
     AcpProtocol::stripTerminalContentBlocks(copy.content);
     copy.content = AcpProtocol::ensureDiffContent(copy.content, copy.rawInput, copy.rawOutput);
+    const bool known = m_toolCalls.contains(copy.id);
     m_toolCalls.insert(copy.id, copy);
 
-    AcpTimelineEntry entry;
-    entry.kind = AcpTimelineEntry::Kind::ToolCall;
-    entry.toolCallId = copy.id;
-    entry.groupId = m_currentGroupId;
-    m_timeline.append(entry);
+    if (subagentChild) {
+        attachSubagentChild(copy.parentToolCallId, copy.id);
+    } else if (!known) {
+        AcpTimelineEntry entry;
+        entry.kind = AcpTimelineEntry::Kind::ToolCall;
+        entry.toolCallId = copy.id;
+        entry.groupId = m_currentGroupId;
+        m_timeline.append(entry);
+    }
 
     emit toolCallAddedOrUpdated(copy.id);
     schedulePersistIfNeeded();
@@ -678,11 +726,17 @@ void AcpSessionModel::onToolCallUpdated(const AcpToolCallUpdate &update)
         // initial tool_call. We still want it in the timeline.
         // Also close any active streaming text/thought, since this branch
         // adds a fresh timeline peer (same rule as onToolCallReceived).
-        m_streamingAssistantMessageIndex = -1;
-        m_streamingThoughtMessageIndex = -1;
+        const bool subagentChild = update.parentToolCallId.has_value();
+        if (!subagentChild) {
+            m_streamingAssistantMessageIndex = -1;
+            m_streamingThoughtMessageIndex = -1;
+        }
 
         AcpToolCall tc;
         tc.id = update.id;
+        if (subagentChild) {
+            tc.parentToolCallId = *update.parentToolCallId;
+        }
         if (update.title.has_value()) {
             tc.title = *update.title;
         }
@@ -716,12 +770,23 @@ void AcpSessionModel::onToolCallUpdated(const AcpToolCallUpdate &update)
         }
         m_toolCalls.insert(update.id, tc);
 
-        AcpTimelineEntry entry;
-        entry.kind = AcpTimelineEntry::Kind::ToolCall;
-        entry.toolCallId = update.id;
-        entry.groupId = m_currentGroupId;
-        m_timeline.append(entry);
+        if (subagentChild) {
+            attachSubagentChild(tc.parentToolCallId, tc.id);
+        } else {
+            AcpTimelineEntry entry;
+            entry.kind = AcpTimelineEntry::Kind::ToolCall;
+            entry.toolCallId = update.id;
+            entry.groupId = m_currentGroupId;
+            m_timeline.append(entry);
+        }
     } else {
+        // Late attribution: an eager (permission) tool_call can arrive before
+        // the adapter knows its subagent. The call keeps its timeline entry;
+        // every reader skips entries whose call has a parent.
+        if (update.parentToolCallId.has_value() && it.value().parentToolCallId.isEmpty()) {
+            it.value().parentToolCallId = *update.parentToolCallId;
+            attachSubagentChild(*update.parentToolCallId, update.id);
+        }
         const QJsonArray previousContent = it.value().content;
         if (update.title.has_value()) {
             it.value().title = *update.title;
@@ -1100,6 +1165,8 @@ void AcpSessionModel::upsertGoalJudgeToolCall(const AcpToolCall &tc)
 {
     AcpToolCall copy = tc;
     copy.id = namespacedGoalJudgeToolId(tc.id);
+    if (!copy.parentToolCallId.isEmpty())
+        copy.parentToolCallId = namespacedGoalJudgeToolId(copy.parentToolCallId);
     closeGoalJudgeStreaming();
     const int assistantIdx = m_streamingAssistantMessageIndex;
     const int thoughtIdx = m_streamingThoughtMessageIndex;
@@ -1114,6 +1181,8 @@ void AcpSessionModel::applyGoalJudgeToolCallUpdate(const AcpToolCallUpdate &upda
 {
     AcpToolCallUpdate u = update;
     u.id = namespacedGoalJudgeToolId(update.id);
+    if (u.parentToolCallId.has_value())
+        u.parentToolCallId = namespacedGoalJudgeToolId(*u.parentToolCallId);
     const bool existed = m_toolCalls.contains(u.id);
     if (!existed)
         closeGoalJudgeStreaming();
@@ -1173,6 +1242,12 @@ void AcpSessionModel::removeGoalJudgeTurn()
             if (e.kind == AcpTimelineEntry::Kind::ToolCall) {
                 removedTools.append(e.toolCallId);
                 m_toolCalls.remove(e.toolCallId);
+                // Its subagent's calls have no timeline entries of their own.
+                const QStringList children = m_subagentChildren.take(e.toolCallId);
+                for (const QString &child : children) {
+                    if (m_toolCalls.remove(child))
+                        removedTools.append(child);
+                }
             } else if (e.messageIndex >= 0) {
                 removedMsg.append(e.messageIndex);
             }

src/AcpSessionModel.h

@@ -122,6 +122,14 @@ class AcpSessionModel : public QObject
     const QVector<AcpMessage> &messages() const { return m_messages; }
     const QHash<QString, AcpProtocol::AcpToolCall> &toolCalls() const { return m_toolCalls; }
     const QVector<AcpTimelineEntry> &timeline() const { return m_timeline; }
+    // Tool calls a subagent made, in arrival order, keyed by the Agent/Task
+    // tool call that spawned it. They live in toolCalls() but get no timeline
+    // entry (a call attributed late keeps the one it already had; readers skip
+    // tool calls with a parentToolCallId).
+    QStringList subagentChildren(const QString &parentToolCallId) const
+    {
+        return m_subagentChildren.value(parentToolCallId);
+    }
     const std::optional<AcpProtocol::AcpUsage> &usage() const { return m_usage; }
     const QList<AcpProtocol::AcpCommandInfo> &availableCommands() const { return m_availableCommands; }
     // True only when the agent advertised `goal`/`/goal`. Host inject does not set this.
@@ -216,6 +224,7 @@ public slots:
 private:
     void schedulePersistIfNeeded();
     void flushPendingPersist();
+    void attachSubagentChild(const QString &parentToolCallId, const QString &childId);
     QString resolveHistoryDir() const;
     QString resolveHistoryFilePath() const;
 
@@ -231,6 +240,7 @@ public slots:
     QVector<AcpMessage> m_messages;
     QHash<QString, AcpProtocol::AcpToolCall> m_toolCalls;
     QVector<AcpTimelineEntry> m_timeline;
+    QHash<QString, QStringList> m_subagentChildren; // parent tool call -> children, arrival order
 
     int m_currentGroupId = 0;
     std::optional<AcpProtocol::AcpUsage> m_usage;

src/AcpTurnFolding.cpp

@@ -98,7 +98,10 @@ QVector<Turn> compute(const QVector<AcpTimelineEntry> &timeline,
                 continue;
             const AcpTimelineEntry &e = timeline.at(i);
             if (e.kind == AcpTimelineEntry::Kind::ToolCall) {
-                if (toolCalls.contains(e.toolCallId)) {
+                // A subagent's call attributed after it got its entry renders
+                // inside its Agent card, not here.
+                const auto tc = toolCalls.constFind(e.toolCallId);
+                if (tc != toolCalls.constEnd() && tc->parentToolCallId.isEmpty()) {
                     turn.folded.append(i);
                     ++turn.toolCalls;
                 }