fix(agents): Record whose work a child agent does in its session log

packages/junior-evals/evals/guardian/child-agent-approval.eval.ts

@@ -3,9 +3,11 @@
  *
  * A child agent's task comes from its parent agent, so the task text is not
  * user intent. Core gives Guardian a fixed child `userIntent` and reads the
- * root Conversation at review time. Only `user:` lines from the child's own
- * Actor, or the `automation:` instruction of an Automation run, can approve.
- * They approve what they name and the conventional steps of that work.
+ * root Conversation at review time. Only `user:` lines from the person whose
+ * work the child does, or the `automation:` instruction of an Automation run,
+ * can approve. A watch Turn of the child runs as the event Actor, but still
+ * reads the root for that person. They approve what they name and the
+ * conventional steps of that work.
  */
 import { describeEval } from "vitest-evals";
 import {
@@ -533,48 +535,65 @@ describeEval("Guardian Child Agent Approval Snapshots", guardianEvals, (it) => {
     });
   }
 
-  it("when a Watch on the child's own PR delivers review feedback, allow marking it addressed", async ({
-    run,
-  }) => {
-    await run({
-      expectedDecision: "allow",
-      proposal: childProposal({
-        context: childWatchContext({
-          eventType: "pull_request.review_comment.created",
-          identifier: `${repo}#${prNumber}`,
-          namespace: "github",
+  // A Watch Turn of the child runs as the event Actor. Core reads the root
+  // for the person whose work the child does, so the user's request is still
+  // a `user:` line.
+  for (const { name, input, tool } of [
+    {
+      name: "when a Watch on the child's own PR delivers review feedback, allow marking it addressed",
+      input: feedbackInput,
+      tool: {
+        ...updateFeedbackTool,
+        proposalDescription: `Mark review comment ${reviewCommentId} on ${repo} as addressed (+1).`,
+      },
+    },
+    {
+      name: "when a Watch on the child's own PR delivers review feedback, allow resolving the handled thread",
+      input: { repo, threadId: reviewThreadId },
+      tool: {
+        ...resolveThreadTool,
+        proposalDescription: `Resolve review thread ${reviewThreadId} on ${repo}.`,
+      },
+    },
+  ]) {
+    it(name, async ({ run }) => {
+      await run({
+        expectedDecision: "allow",
+        proposal: childProposal({
+          context: childWatchContext({
+            eventType: "pull_request.review_comment.created",
+            identifier: `${repo}#${prNumber}`,
+            namespace: "github",
+          }),
+          entries: [
+            { role: "parent agent", text: parentTask(fixRequest) },
+            pullRequestCreated,
+            {
+              role: "parent agent",
+              text: renderTaskInput({
+                about: `${repo}#${prNumber}`,
+                guidance:
+                  'After acting on actionable feedback, call github_updatePullRequestFeedback with the exact repo, commentId, and commentKind from Verified details, and status "addressed" or "declined". Then resolve the thread with github_resolvePullRequestReviewThread.',
+                instructions:
+                  "Address review feedback on the pull request that I opened.",
+                trustedSummary: `New review comment on ${repo}#${prNumber}.`,
+                verifiedDetails: {
+                  commentId: reviewCommentId,
+                  commentKind: "review",
+                  repo,
+                },
+                externalText: reviewComment,
+              }),
+            },
+            ...fixPushed,
+          ],
+          input,
+          root: fixRoot,
+          tool,
         }),
-        entries: [
-          { role: "parent agent", text: parentTask(fixRequest) },
-          pullRequestCreated,
-          {
-            role: "parent agent",
-            text: renderTaskInput({
-              about: `${repo}#${prNumber}`,
-              guidance:
-                'After acting on actionable feedback, call github_updatePullRequestFeedback with the exact repo, commentId, and commentKind from Verified details, and status "addressed" or "declined". Then resolve the thread with github_resolvePullRequestReviewThread.',
-              instructions:
-                "Address review feedback on the pull request that I opened.",
-              trustedSummary: `New review comment on ${repo}#${prNumber}.`,
-              verifiedDetails: {
-                commentId: reviewCommentId,
-                commentKind: "review",
-                repo,
-              },
-              externalText: reviewComment,
-            }),
-          },
-          ...fixPushed,
-        ],
-        input: feedbackInput,
-        root: fixRoot,
-        tool: {
-          ...updateFeedbackTool,
-          proposalDescription: `Mark review comment ${reviewCommentId} on ${repo} as addressed (+1).`,
-        },
-      }),
+      });
     });
-  });
+  }
 
   it("when the assistant said each agent would open a PR for the requested fix, allow the child's PR", async ({
     run,

packages/junior/src/chat/agent-invocations/README.md

@@ -151,8 +151,10 @@ valid targets.
   agent invocation ends as `completed` with `parentMailboxStatus: "steered"`.
   The running agent invocation reports for both. A message joins only with the
   Actor and credentials of the running Turn. Otherwise it and every later
-  parent message wait. If the child finishes without another model call, the
-  message runs after that work, and the earlier work ends as `replaced`.
+  parent message wait. It also joins only for the same `onBehalfOf` (see
+  User Approval). A message without one keeps the running one. If the child
+  finishes without another model call, the message runs after that work, and
+  the earlier work ends as `replaced`.
 - **Child to parent.** The message wakes the parent as an Event with
   namespace `junior` and type `agent.message`. It uses the same mailbox path
   and Actor rules as a child result: the Actor comes from the sender's agent
@@ -171,9 +173,11 @@ A child Conversation has no Location, so it cannot run an Event Turn. When
 results starts a new agent invocation on that child instead. Its id comes from
 the result's agent invocation id, so retries do not start a second one. An
 agent message from one of those children starts an agent invocation the same
-way; its id comes from the message's Inbound message id. It uses the parent,
-Actor, and credentials of the child's latest agent invocation, and it skips the
-queue and active-count checks.
+way; its id comes from the message's Inbound message id. It uses the parent of
+the child's latest agent invocation, and the Actor and credentials of the
+child's latest task from `spawnAgent` or `messageAgent`. A watch event is not a
+task, so the grants of a timer never pass to later work. It skips the queue and
+active-count checks.
 
 The parent gets one report for the child's work. A finished agent invocation
 is `replaced` instead of sent when the child still has open work: another open
@@ -237,9 +241,9 @@ When Guardian reviews an action of a child, `root-conversation.ts` walks
 rewrite these events. Nothing is copied into the child, and nothing new is
 stored.
 
-- Only a root message whose author has the same Actor identity as the child
-  is labeled `user`. It is compared by platform, team, and user id. When
-  either Actor is not known, the message does not count.
+- Only a root message whose author has the same Actor identity as the
+  child's `onBehalfOf` is labeled `user`. It is compared by platform, team,
+  and user id. When either Actor is not known, the message does not count.
 - When the root is an Automation run, the dispatch input message is that
   run's own instruction. It is labeled `automation` for the run's system
   Actor. This is the authority that the run already has. Guardian reviews the
@@ -266,6 +270,34 @@ stored.
   its text. An edit of a message older than the read is left out, so an edit
   never moves a message after a newer one, such as a revocation.
 
+### Whose Work a Child Does
+
+`onBehalfOf` is the Actor whose work a child does. It is not the Run Actor. A
+watch, timer, or result Turn of a child runs as the event system Actor, but it
+still does the work of the person who gave the task. `on-behalf-of.ts` owns
+this rule. The value is in the child's session log, so no SQL column holds it:
+
+- `spawnAgent` and `messageAgent` put it in the `meta` of the task message
+  that they write into the child. A root Turn gives its Actor. A child Turn
+  gives its own `onBehalfOf`. An Event Turn on a root is not from a person,
+  so its task has none.
+- Each child Turn uses the value of its own task message. Without one, it
+  keeps the value of the child's latest instruction. So a watch Turn, or a
+  message from a root Event Turn, keeps the person of the earlier task. A
+  child that a root Event Turn starts has none.
+- The Turn saves the value in the `onBehalfOf` field of its instruction
+  provenance. The instruction still has no `actor`, so agent text never
+  becomes user intent. The latest instruction is read across history
+  versions, so compaction and handoff do not lose it.
+- The model and tool input cannot set it. It never changes the Run Actor,
+  credentials, or a timer's own grants.
+- A child that started before this field existed has no value. It gets no
+  `user` lines until a new task gives it one. There is no fallback, such as
+  the Run Actor or the thread owner.
+- A heartbeat repair of a task message cannot know the value. The child then
+  keeps the value of its latest instruction, the same as for a message from a
+  root Event Turn.
+
 Guardian renders the projection outside the untrusted proposal JSON, in a
 `<root_user_instructions key="...">` section with a new random key for each
 request. Each line has its real author as a prefix. The rules for a child

packages/junior/src/chat/agent-invocations/child-input.ts

@@ -0,0 +1,104 @@
+/**
+ * Creates the agent invocation that gives one input to a child Conversation:
+ * a result or message from its own child agent, or its own watch events.
+ *
+ * The parent did not start this work, so it is not a task. It runs with the
+ * Actor and credentials of the child's latest task. A watch event or a result
+ * is never a task, so the credentials of one timer Turn never pass to later
+ * work.
+ */
+import { and, asc, desc, eq, isNotNull } from "drizzle-orm";
+import { getSqlExecutor } from "@/chat/db";
+import { juniorAgentInvocations } from "@/db/schema";
+import { getAgentInvocation, invocationFromRow } from "./store";
+import type { AgentInvocation } from "./types";
+
+/**
+ * Read the latest task of one child Conversation: the newest agent invocation
+ * that its parent started with `spawnAgent` or `messageAgent`. The first agent
+ * invocation of a child always comes from `spawnAgent`, also when it has no
+ * tool call id.
+ */
+async function getLatestAgentTask(
+  childConversationId: string,
+): Promise<AgentInvocation | undefined> {
+  const db = getSqlExecutor().db();
+  const [latest] = await db
+    .select()
+    .from(juniorAgentInvocations)
+    .where(
+      and(
+        eq(juniorAgentInvocations.childConversationId, childConversationId),
+        isNotNull(juniorAgentInvocations.parentToolCallId),
+      ),
+    )
+    .orderBy(desc(juniorAgentInvocations.createdAt))
+    .limit(1);
+  if (latest) {
+    return invocationFromRow(latest);
+  }
+  const [first] = await db
+    .select()
+    .from(juniorAgentInvocations)
+    .where(eq(juniorAgentInvocations.childConversationId, childConversationId))
+    .orderBy(asc(juniorAgentInvocations.createdAt))
+    .limit(1);
+  return first ? invocationFromRow(first) : undefined;
+}
+
+/**
+ * Create or replay the agent invocation that gives one input to the child
+ * Conversation of `latest`. It continues that Conversation for the same
+ * parent. It runs as the Actor and with the credentials of the child's latest
+ * task, unless `runAs` sets them. It skips the queue and active-count checks
+ * because it continues work that already passed them.
+ */
+export async function createAgentInvocationForChildInput(
+  args: {
+    input: string;
+    invocationId: string;
+    latest: AgentInvocation;
+    /** Actor, credentials, and Source for watch events. */
+    runAs?: Pick<AgentInvocation, "actor" | "credentialContext" | "source">;
+  },
+  nowMs = Date.now(),
+): Promise<AgentInvocation> {
+  const { invocationId, latest } = args;
+  const task = await getLatestAgentTask(latest.childConversationId);
+  if (!task) {
+    throw new Error(
+      `Child conversation ${latest.childConversationId} has no agent task`,
+    );
+  }
+  const runAs = args.runAs ?? task;
+  await getSqlExecutor()
+    .db()
+    .insert(juniorAgentInvocations)
+    .values({
+      invocationId,
+      parentConversationId: latest.parentConversationId,
+      childConversationId: latest.childConversationId,
+      agentName: latest.agentName ?? null,
+      input: args.input,
+      actor: runAs.actor,
+      credentialContext: runAs.credentialContext ?? null,
+      source: args.runAs?.source ?? { kind: "agent_invocation" },
+      destination: latest.destination,
+      modelProfile: latest.modelProfile ?? null,
+      reasoningLevel: latest.reasoningLevel ?? null,
+      status: "pending",
+      mailboxStatus: "pending",
+      createdAt: new Date(nowMs),
+      updatedAt: new Date(nowMs),
+      terminalAt: null,
+    })
+    .onConflictDoNothing();
+  const invocation = await getAgentInvocation(invocationId);
+  if (
+    !invocation ||
+    invocation.childConversationId !== latest.childConversationId
+  ) {
+    throw new Error(`Agent invocation creation raced for ${invocationId}`);
+  }
+  return invocation;
+}

packages/junior/src/chat/agent-invocations/markers.ts

@@ -4,6 +4,7 @@
  * The child Conversation gets `message` events for its input and its result,
  * because a child has no Location that records visible messages.
  */
+import type { Actor } from "@/chat/actor";
 import { getConversationEventStore } from "@/chat/db";
 import { getAgentInvocationMessageId } from "./store";
 import type { AgentInvocation, TerminalAgentInvocation } from "./types";
@@ -16,10 +17,12 @@ const SUBAGENT_KIND = "agent";
  * record its input as a user message in the child Conversation. The dashboard
  * pairs the parent event with `subagent_ended` to show the child and its
  * status. It must be written before the child mailbox append, so the child
- * cannot end first.
+ * cannot end first. `onBehalfOf` of a parent task goes on the child message
+ * (see `on-behalf-of.ts`).
  */
 export async function recordSubagentStarted(
   invocation: AgentInvocation,
+  onBehalfOf?: Actor,
 ): Promise<void> {
   const eventStore = getConversationEventStore();
   // The mailbox input has the same id, so the child Turn links to it.
@@ -32,6 +35,7 @@ export async function recordSubagentStarted(
         messageId,
         role: "user",
         text: invocation.input,
+        ...(onBehalfOf ? { meta: { onBehalfOf } } : undefined),
       },
       createdAtMs: invocation.createdAtMs,
     },

packages/junior/src/chat/agent-invocations/message.ts

@@ -14,6 +14,7 @@ import {
   findChildAgentConversationId,
   getActiveAgentInvocationForConversation,
 } from "./store";
+import { taskOnBehalfOf } from "./on-behalf-of";
 import { PARENT_AGENT_TARGET } from "./types";
 import { enqueueAgentInvocation } from "./work";
 
@@ -85,7 +86,11 @@ export function bindMessageAgent(
       parentConversationId: run.conversationId,
       parentToolCallId: call.toolCallId,
     });
-    await enqueueAgentInvocation(invocation, { ...options, queue });
+    await enqueueAgentInvocation(invocation, {
+      ...options,
+      onBehalfOf: taskOnBehalfOf(run, actor),
+      queue,
+    });
     return {
       conversationId: childConversationId,
       delivery: queued ? "queued" : "started",