feat: add target option so a loop can wake the parent session

A loop could only ever re-prompt the session that created it, so a background
child session had no way to hand control back to the session that spawned it.
When the thing it was watching finally happened, the parent sat idle until a
human noticed.

create_loop now takes target: "self" | "parent". "self" is the default and
behaves exactly as before. "parent" resolves the creating session's parentID
once, at creation, and the scheduler injects iterations there instead.

The resolved id is stored as loop.targetSessionID (null for self loops, so
existing persisted records decode unchanged and keep targeting their own
session). loopTarget() is the single accessor the scheduler reads, which keeps
the change to a handful of call sites in both the V1 and V2 paths: busy
deferral, restricted-agent deferral, dynamicPending registration, the prompt
itself, and post-send bookkeeping all follow the target.

Two cases need the target rather than the creator to stay correct. The
iteration prompt tells the receiving session to call stop_loop and
schedule_next_run, so requireSessionLoop now accepts the target session as
well; otherwise a parent-targeted loop could never be stopped by the session
actually running it. Dynamic loops register under the target with sawBusy
false when targeting a parent, because the creating child's idle event would
otherwise settle the loop before the parent was ever prompted.

Creating a parent-targeted loop from a root session fails at create time
rather than silently never firing.

Author: jutaz

README.md

@@ -13,6 +13,7 @@ The OpenCode Loop Plugin adds:
 - `/loop <interval> <instruction>` and `/loop <instruction>` (dynamic pacing) as an OpenCode command for TUI, desktop, and web.
 - A server-side scheduler with per-loop timers that injects a synthetic iteration prompt only when the session is idle, with busy backoff.
 - Dynamic loops where the agent itself picks the delay before each next iteration via `schedule_next_run`, mirroring Claude Code's self-paced `/loop`.
+- Parent wake-up: `create_loop` takes `target: "self" | "parent"`, so a background child session can hand control back to the session that spawned it instead of only re-waking itself.
 - Agent tools: `create_loop`, `list_loops`, `stop_loop`, `pause_loop`, `resume_loop`, `run_loop`, `schedule_next_run`, and `clear_loops`.
 - Persistent loop state that survives OpenCode restarts, with atomic writes and owner-only file permissions.
 - A TUI sidebar with live countdowns and a `Loops` command-palette entry to run, pause, resume, or stop loops.
@@ -120,6 +121,22 @@ After creating a loop, the agent immediately performs the first iteration in the
 
 A dynamic loop mirrors Claude Code's self-paced `/loop`: at the end of each iteration the agent calls `schedule_next_run` with a delay in seconds and a one-sentence reason ("watching CI run"), or calls `stop_loop` to end the loop. If an iteration ends without doing either, the loop ends — exactly like omitting `ScheduleWakeup` in Claude Code.
 
+### Waking the parent session
+
+By default a loop wakes the session that created it. Pass `target: "parent"` to `create_loop` and iterations are injected into that session's parent instead:
+
+```
+create_loop(
+  instruction: "Check whether PR #42 has merged. If it has, say so and call stop_loop.",
+  interval: "5m",
+  target: "parent"
+)
+```
+
+This is for background work. A subagent spawned to babysit CI can keep polling on its own schedule and then hand control back to the session that spawned it, instead of that session sitting idle until a human notices. One tool, one flag — `"self"` re-wakes this session, `"parent"` wakes the one above it.
+
+The parent is resolved once, when the loop is created. Creating a parent-targeted loop from a root session fails immediately rather than silently never firing. Both the creating session and the woken parent can `list_loops` and `stop_loop` it, and the loop is stopped if the parent session is deleted.
+
 ### How iterations are scheduled
 
 - Iterations only run while the session is idle. If a loop comes due while the session is busy, it is deferred with a short backoff and retried when the session goes idle.

dist/server.js

@@ -25,6 +25,7 @@ var NullableNumber = Schema.NullOr(Schema.Number);
 var LoopSchema = Schema.Struct({
   id: Schema.String,
   sessionID: Schema.String,
+  targetSessionID: Schema.optionalWith(NullableString, { default: () => null }),
   prompt: Schema.String,
   mode: Schema.optionalWith(Schema.Literal("interval", "dynamic"), { default: () => "interval" }),
   intervalMs: NullableNumber,
@@ -208,6 +209,9 @@ function isOpen(status) {
 function snapshot(loop) {
   return { ...loop, sampledAt: now() };
 }
+function loopTarget(loop) {
+  return loop.targetSessionID ?? loop.sessionID;
+}
 function requireLoop(state, loopID) {
   const loop = state.loops[loopID];
   if (!loop)
@@ -223,8 +227,9 @@ async function createLoop(sessionID, options) {
   const maxRuns = positiveIntegerOrNull(options.maxRuns);
   const maxLoops = positiveIntegerOrNull(options.maxLoopsPerSession) ?? DEFAULT_MAX_LOOPS_PER_SESSION;
   const agent = typeof options.agent === "string" && options.agent.trim() ? options.agent.trim() : null;
+  const target = typeof options.targetSessionID === "string" && options.targetSessionID.trim() && options.targetSessionID !== sessionID ? options.targetSessionID.trim() : null;
   return mutate((state) => {
-    const open = Object.values(state.loops).filter((loop2) => loop2.sessionID === sessionID && isOpen(loop2.status));
+    const open = Object.values(state.loops).filter((loop) => loop.sessionID === sessionID && isOpen(loop.status));
     if (open.length >= maxLoops) {
       throw new Error(`this session already has ${open.length} open loop(s); stop one before creating another (limit ${maxLoops})`);
     }
@@ -235,6 +240,7 @@ async function createLoop(sessionID, options) {
     const loop = {
       id,
       sessionID,
+      targetSessionID: target,
       prompt,
       mode,
       intervalMs,
@@ -276,7 +282,7 @@ async function claimDueRun(loopID, leaseMs) {
 }
 async function listLoops(sessionID) {
   const state = await readState();
-  return Object.values(state.loops).filter((loop) => sessionID == null || loop.sessionID === sessionID).sort((a, b) => a.createdAt - b.createdAt).map(snapshot);
+  return Object.values(state.loops).filter((loop) => sessionID == null || loop.sessionID === sessionID || loopTarget(loop) === sessionID).sort((a, b) => a.createdAt - b.createdAt).map(snapshot);
 }
 async function openLoops(sessionID) {
   const loops = await listLoops(sessionID);
@@ -327,7 +333,7 @@ async function stopLoopsForSession(sessionID, reason) {
   return mutate((state) => {
     const stopped = [];
     for (const loop of Object.values(state.loops)) {
-      if (loop.sessionID !== sessionID || !isOpen(loop.status))
+      if (loopTarget(loop) !== sessionID || !isOpen(loop.status))
         continue;
       loop.status = "stopped";
       loop.nextRunAt = null;
@@ -510,6 +516,7 @@ Preserve each loop's id, cadence, instruction, and status in the compacted conte
 }
 
 // src/server.ts
+var TARGET_DESCRIPTION = 'Whose session the iteration wakes. "self" (default) re-prompts this session on the cadence. "parent" prompts the session that spawned this one, so a background child can hand control back to its parent when the instruction fires.';
 var DEFAULT_COMMAND_NAME = "loop";
 var DEFAULT_BUSY_BACKOFF_SECONDS = 60;
 var DEFAULT_FAILURE_BACKOFF_SECONDS = 60;
@@ -646,50 +653,51 @@ var server = async ({ client }, options) => {
       await stopLoop(loopID, `expired after ${Math.round(maxLoopAgeMs / 86400000)} days`);
       return;
     }
-    if (busySessions.has(loop.sessionID)) {
+    const target = loopTarget(loop);
+    if (busySessions.has(target)) {
       const deferred = await recordRunDeferred(loopID, "skipped_busy", Math.min(loop.intervalMs ?? busyBackoffMs, busyBackoffMs));
       scheduleTimer(deferred);
       return;
     }
-    if (isRestrictedAgent(lastPromptAgentBySession.get(loop.sessionID))) {
+    if (isRestrictedAgent(lastPromptAgentBySession.get(target))) {
       const deferred = await recordRunDeferred(loopID, "skipped_plan", Math.min(loop.intervalMs ?? busyBackoffMs, busyBackoffMs));
       scheduleTimer(deferred);
       return;
     }
     if (loop.mode === "dynamic") {
-      dynamicPending.set(loopID, { sessionID: loop.sessionID, sawBusy: false });
+      dynamicPending.set(loopID, { sessionID: target, sawBusy: false });
     }
     try {
       await client.session.promptAsync({
-        path: { id: loop.sessionID },
+        path: { id: target },
         body: {
           ...loop.agent ? { agent: loop.agent } : {},
           parts: [{ type: "text", text: iterationPrompt(loop) }]
         }
       });
     } catch (error) {
       dynamicPending.delete(loopID);
-      if (!observedSessions.has(loop.sessionID)) {
-        await log("info", "Skipping loop for a session this process has not observed", { loopID, sessionID: loop.sessionID });
+      if (!observedSessions.has(target)) {
+        await log("info", "Skipping loop for a session this process has not observed", { loopID, sessionID: target });
         return;
       }
       const failed = await recordRunFailed(loopID, error instanceof Error ? error.message : String(error), failureBackoffMs);
       scheduleTimer(failed);
       await log("error", "Loop iteration prompt failed", { loopID, error: failed.lastError ?? undefined });
       return;
     }
-    busySessions.add(loop.sessionID);
-    observedSessions.add(loop.sessionID);
+    busySessions.add(target);
+    observedSessions.add(target);
     const sent = await recordRunSent(loopID);
     if (sent.mode !== "dynamic" || sent.status !== "active")
       dynamicPending.delete(loopID);
     scheduleTimer(sent);
   }
   async function runDueForSession(sessionID) {
     const loops = await activeLoops(sessionID);
-    const now2 = Date.now();
+    const now = Date.now();
     for (const loop of loops) {
-      if (loop.nextRunAt == null || loop.nextRunAt > now2)
+      if (loop.nextRunAt == null || loop.nextRunAt > now)
         continue;
       await runDue(loop.id);
       if (busySessions.has(sessionID))
@@ -728,10 +736,19 @@ var server = async ({ client }, options) => {
     const loop = await getLoop(loopID);
     if (!loop)
       throw new Error(`no loop found with id "${loopID}"`);
-    if (loop.sessionID !== sessionID)
+    if (loop.sessionID !== sessionID && loopTarget(loop) !== sessionID) {
       throw new Error(`loop "${loopID}" belongs to a different session`);
+    }
     return loop;
   }
+  async function requireParentSession(sessionID) {
+    const result = await client.session.get({ path: { id: sessionID } });
+    const parentID = result?.data?.parentID;
+    if (!parentID) {
+      throw new Error(`session "${sessionID}" has no parent session, so target "parent" has nothing to wake; create the loop from a child session`);
+    }
+    return parentID;
+  }
   await rehydrate().catch((error) => log("error", "Failed to rehydrate loops", { error: error instanceof Error ? error.message : String(error) }));
   return {
     async dispose() {
@@ -747,26 +764,29 @@ var server = async ({ client }, options) => {
     },
     tool: {
       create_loop: {
-        description: 'Create a recurring loop for this session only when explicitly requested (for example via the /loop command). The scheduler re-injects the instruction while the session is idle. Pass interval for fixed cadence (like "10m"); omit it for a dynamic loop where the agent schedules each next run with schedule_next_run.',
+        description: 'Create a recurring loop only when explicitly requested (for example via the /loop command). One flag decides whose session wakes up: target "self" (default) re-injects the instruction into THIS session while it is idle; target "parent" prompts the session that spawned this one instead, so a background child can wake its parent when the instruction fires. Pass interval for fixed cadence (like "10m"); omit it for a dynamic loop where the agent schedules each next run with schedule_next_run.',
         args: {
           instruction: z.string().min(1).max(MAX_PROMPT_CHARS).describe("The instruction to perform on each iteration."),
           interval: z.string().optional().describe('Fixed cadence like "30s", "10m", "2h", or "1d". Omit for a dynamically paced loop.'),
-          max_runs: z.number().int().positive().optional().describe("Optional maximum number of iterations before the loop completes.")
+          max_runs: z.number().int().positive().optional().describe("Optional maximum number of iterations before the loop completes."),
+          target: z.enum(["self", "parent"]).optional().describe(TARGET_DESCRIPTION)
         },
         async execute(args, context) {
           const input = args;
           observedSessions.add(context.sessionID);
+          const targetSessionID = input.target === "parent" ? await requireParentSession(context.sessionID) : null;
           const dynamic = !input.interval?.trim();
           const loop = await createLoop(context.sessionID, {
             prompt: input.instruction,
             mode: dynamic ? "dynamic" : "interval",
             intervalMs: dynamic ? null : parseInterval(input.interval, minIntervalSeconds),
             maxRuns: input.max_runs ?? null,
             agent: typeof context.agent === "string" ? context.agent : null,
-            maxLoopsPerSession
+            maxLoopsPerSession,
+            targetSessionID
           });
           if (loop.mode === "dynamic") {
-            dynamicPending.set(loop.id, { sessionID: loop.sessionID, sawBusy: true });
+            dynamicPending.set(loop.id, { sessionID: loopTarget(loop), sawBusy: loopTarget(loop) === loop.sessionID });
           } else {
             scheduleTimer(loop);
           }
@@ -1045,48 +1065,49 @@ async function setupV2(context) {
       await stopLoop(loopID, `expired after ${Math.round(maxLoopAgeMs / 86400000)} days`);
       return;
     }
-    if (await isSessionBusy(loop.sessionID)) {
+    const target = loopTarget(loop);
+    if (await isSessionBusy(target)) {
       const deferred = await recordRunDeferred(loopID, "skipped_busy", Math.min(loop.intervalMs ?? busyBackoffMs, busyBackoffMs));
       scheduleTimer(deferred);
       return;
     }
-    if (isRestrictedAgent(lastPromptAgentBySession.get(loop.sessionID))) {
+    if (isRestrictedAgent(lastPromptAgentBySession.get(target))) {
       const deferred = await recordRunDeferred(loopID, "skipped_plan", Math.min(loop.intervalMs ?? busyBackoffMs, busyBackoffMs));
       scheduleTimer(deferred);
       return;
     }
     if (loop.mode === "dynamic") {
-      dynamicPending.set(loopID, { sessionID: loop.sessionID, sawBusy: false });
+      dynamicPending.set(loopID, { sessionID: target, sawBusy: false });
     }
     try {
       await context.session.prompt({
-        sessionID: loop.sessionID,
+        sessionID: target,
         text: iterationPrompt(loop),
         ...loop.agent ? { agents: [{ name: loop.agent }] } : {}
       });
     } catch (error) {
       dynamicPending.delete(loopID);
-      if (!observedSessions.has(loop.sessionID)) {
-        v2Log("info", "Skipping loop for a session this process has not observed", { loopID, sessionID: loop.sessionID });
+      if (!observedSessions.has(target)) {
+        v2Log("info", "Skipping loop for a session this process has not observed", { loopID, sessionID: target });
         return;
       }
       const failed = await recordRunFailed(loopID, error instanceof Error ? error.message : String(error), failureBackoffMs);
       scheduleTimer(failed);
       v2Log("error", "Loop iteration prompt failed", { loopID, error: failed.lastError ?? undefined });
       return;
     }
-    busySessions.add(loop.sessionID);
-    observedSessions.add(loop.sessionID);
+    busySessions.add(target);
+    observedSessions.add(target);
     const sent = await recordRunSent(loopID);
     if (sent.mode !== "dynamic" || sent.status !== "active")
       dynamicPending.delete(loopID);
     scheduleTimer(sent);
   }
   async function runDueForSession(sessionID) {
     const loops = await activeLoops(sessionID);
-    const now2 = Date.now();
+    const now = Date.now();
     for (const loop of loops) {
-      if (loop.nextRunAt == null || loop.nextRunAt > now2)
+      if (loop.nextRunAt == null || loop.nextRunAt > now)
         continue;
       await runDue(loop.id);
       if (busySessions.has(sessionID))
@@ -1125,10 +1146,19 @@ async function setupV2(context) {
     const loop = await getLoop(loopID);
     if (!loop)
       throw new Error(`no loop found with id "${loopID}"`);
-    if (loop.sessionID !== sessionID)
+    if (loop.sessionID !== sessionID && loopTarget(loop) !== sessionID) {
       throw new Error(`loop "${loopID}" belongs to a different session`);
+    }
     return loop;
   }
+  async function requireParentSession(sessionID) {
+    const info = await context.session.get({ sessionID });
+    const parentID = info?.parentID;
+    if (!parentID) {
+      throw new Error(`session "${sessionID}" has no parent session, so target "parent" has nothing to wake; create the loop from a child session`);
+    }
+    return parentID;
+  }
   async function handleV2Event(event) {
     const data = event.data;
     const sessionID = typeof data.sessionID === "string" ? data.sessionID : undefined;
@@ -1190,7 +1220,8 @@ async function setupV2(context) {
     dynamicPending,
     scheduleTimer,
     cancelTimer,
-    requireSessionLoop
+    requireSessionLoop,
+    requireParentSession
   };
   if (registerCommand) {
     registrations.push(await context.command.transform((draft) => {
@@ -1263,7 +1294,7 @@ function loopToolsV2(services) {
   return [
     {
       name: "create_loop",
-      description: 'Create a recurring loop for this session only when explicitly requested (for example via the /loop command). The scheduler re-injects the instruction while the session is idle. Pass interval for fixed cadence (like "10m"); omit it for a dynamic loop where the agent schedules each next run with schedule_next_run.',
+      description: 'Create a recurring loop only when explicitly requested (for example via the /loop command). One flag decides whose session wakes up: target "self" (default) re-injects the instruction into THIS session while it is idle; target "parent" prompts the session that spawned this one instead, so a background child can wake its parent when the instruction fires. Pass interval for fixed cadence (like "10m"); omit it for a dynamic loop where the agent schedules each next run with schedule_next_run.',
       input: v2ObjectSchema({
         instruction: {
           type: "string",
@@ -1279,23 +1310,30 @@ function loopToolsV2(services) {
           type: "integer",
           minimum: 1,
           description: "Optional maximum number of iterations before the loop completes."
+        },
+        target: {
+          type: "string",
+          enum: ["self", "parent"],
+          description: TARGET_DESCRIPTION
         }
       }, ["instruction"]),
       options: { codemode: false },
       execute: async (args, toolContext) => {
         const input = args;
         services.observedSessions.add(toolContext.sessionID);
+        const targetSessionID = input.target === "parent" ? await services.requireParentSession(toolContext.sessionID) : null;
         const dynamic = !input.interval?.trim();
         const loop = await createLoop(toolContext.sessionID, {
           prompt: input.instruction,
           mode: dynamic ? "dynamic" : "interval",
           intervalMs: dynamic ? null : parseInterval(input.interval, services.minIntervalSeconds),
           maxRuns: input.max_runs ?? null,
           agent: typeof toolContext.agent === "string" ? toolContext.agent : null,
-          maxLoopsPerSession: services.maxLoopsPerSession
+          maxLoopsPerSession: services.maxLoopsPerSession,
+          targetSessionID
         });
         if (loop.mode === "dynamic") {
-          services.dynamicPending.set(loop.id, { sessionID: loop.sessionID, sawBusy: true });
+          services.dynamicPending.set(loop.id, { sessionID: loopTarget(loop), sawBusy: loopTarget(loop) === loop.sessionID });
         } else {
           services.scheduleTimer(loop);
         }