@sema-agent/core 5.16.0 → 5.17.0

package/dist/agents/send-message-tool.js

@@ -5,6 +5,7 @@ import { canAccessAgentRecord, clearRevivedRowTerminalPayload } from "../core/ba
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
+import { appendHopToken, judgePeerAdmission, peerAxisToken, resolvePeerAdmissionConfig, PEER_MESSAGE_NOTICE, } from "./peer-admission.js";
 export const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 let uplinkSeqGlobal = Date.now();
 const UPLINK_RESULT_MAX = 8000;
@@ -104,23 +105,55 @@ export function createSendMessageTool(opts) {
             if (isObserverTaskId(to)) {
                 return { content: OBSERVER_SENDMESSAGE_TARGET_REFUSAL, details: { error: "observer_target", to }, isError: true };
             }
+            const admissionConfig = resolvePeerAdmissionConfig(opts.admission);
+            const guardScope = ctx.principal ?? opts.scope;
+            const selfRef = ctx.peerSelfRef ?? opts.peerSelf;
+            const directMountSessionId = ctx.sessionId ?? opts.sessionId;
+            const directMountTaskId = ctx.taskId ?? opts.owner;
+            const senderKey = selfRef?.current.key ??
+                (directMountSessionId !== undefined
+                    ? peerAxisToken(guardScope, "s", directMountSessionId)
+                    : directMountTaskId !== undefined
+                        ? peerAxisToken(guardScope, "t", directMountTaskId)
+                        : undefined);
+            const inboundChain = (ctx.peerInboundChainRef ?? opts.peerInbound)?.current ?? [];
+            const prospectiveChain = appendHopToken(inboundChain, senderKey);
+            const admitFor = (recipientKey, ownTokens) => judgePeerAdmission(guardScope, recipientKey, { senderKey, body: message, prospectiveChain, ownTokens }, admissionConfig);
+            const DEDUP_RETRY_NOTE = "Note: resending the identical text within the dedup window reads as duplicate — rephrase or wait it out.";
+            const admissionRefusal = (reason, whoLabel) => {
+                const text = reason === "rate_limited"
+                    ? `you are sending messages to ${whoLabel} faster than its rate limit — the budget refills on its own; slow down and resend in a moment.`
+                    : reason === "duplicate"
+                        ? `an identical message was already sent to ${whoLabel} moments ago — if this is genuinely new, rephrase it or wait out the dedup window.`
+                        : reason === "hop_loop"
+                            ? `this message has already passed through ${whoLabel} too many times (a forwarding loop) — stop relaying it; act on it or drop it.`
+                            : `this message's forwarding chain is too long (runaway relay) — stop relaying it; act on it or drop it.`;
+                return { content: `Message not sent: ${text}`, details: { error: reason, to }, isError: true };
+            };
             if (normalizeAgentName(to) === "main") {
                 if (opts.uplink && senderId !== undefined) {
+                    const uplinkIdentity = opts.uplinkRecipient?.current;
+                    if (uplinkIdentity?.key !== undefined) {
+                        const verdict = admitFor(uplinkIdentity.key, uplinkIdentity.ownTokens);
+                        if (!verdict.ok)
+                            return admissionRefusal(verdict.reason, "main");
+                    }
                     try {
                         opts.uplink({
                             task_id: senderId,
                             task_type: "background_agent",
                             status: "event",
                             summary: `message from ${senderLabel}: ${summary}`,
-                            result: message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message,
+                            result: `${message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message}\n\n${PEER_MESSAGE_NOTICE}`,
                             seq: ++uplinkSeqGlobal,
+                            peer: { hopChain: prospectiveChain },
                         }, { priority: "next" });
                     }
                     catch (e) {
-                        return { content: `Message not sent: the parent's notification lane rejected it (${e instanceof Error ? e.message : String(e)}).`, details: { error: "uplink_failed", to }, isError: true };
+                        return { content: `Message not sent: the parent's notification lane rejected it (${e instanceof Error ? e.message : String(e)}). ${DEDUP_RETRY_NOTE}`, details: { error: "uplink_failed", to }, isError: true };
                     }
                     return {
-                        content: `Message sent to main — it will reach the spawning conversation at its next turn boundary. Continue with your task; do not wait for a reply.`,
+                        content: `Message sent to main — queued for the spawning conversation at its next turn boundary. If that conversation finishes before reading it, the message may not survive. Continue with your task; do not wait for a reply.`,
                         details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
                     };
                 }
@@ -207,9 +240,102 @@ export function createSendMessageTool(opts) {
                 }
                 if (row.sessionId === undefined)
                     return undefined;
+                const t3RecipientKey = peerAxisToken(scope, "h", handle);
+                const t3Verdict = admitFor(t3RecipientKey, [t3RecipientKey, peerAxisToken(scope, "s", row.sessionId)]);
+                if (!t3Verdict.ok)
+                    return admissionRefusal(t3Verdict.reason, whoT3);
+                let boxFull = false;
+                try {
+                    boxFull = (await opts.mailbox.peekCount(scope, handle)) >= admissionConfig.maxQueuedPeerMessages;
+                }
+                catch {
+                }
+                if (boxFull) {
+                    const queueFullReceipt = (guidance) => ({
+                        content: `Message not sent: ${whoT3}'s mailbox is at its queued-message limit (${admissionConfig.maxQueuedPeerMessages}) — the message was NOT queued. ${guidance} ${DEDUP_RETRY_NOTE}`,
+                        details: { error: "queue_full", to },
+                        isError: true,
+                    });
+                    if (!opts.registry.beginDurableClaim(handle)) {
+                        return queueFullReceipt(`Another lifecycle operation currently owns this agent's claim — resend in a moment.`);
+                    }
+                    try {
+                        const now = Date.now();
+                        const nextSeq = (row.seq ?? 1) + 1;
+                        const claimed = { ...row, status: "running", writerId: opts.registry.writerId, writerEpoch: (row.writerEpoch ?? 0) + 1, updatedAt: now, seq: nextSeq };
+                        clearRevivedRowTerminalPayload(claimed);
+                        let won = false;
+                        try {
+                            won = await opts.agentStore.update(handle, scope, claimed, { rev: row.rev });
+                        }
+                        catch {
+                            won = false;
+                        }
+                        if (!won) {
+                            return queueFullReceipt(`Another delivery claimed the agent's record first — this send did not start a backlog drain; a later resend will try again.`);
+                        }
+                        const claimedRev = row.rev + 1;
+                        const rollbackDrain = async () => {
+                            try {
+                                await opts.agentStore.update(handle, scope, { ...row, updatedAt: Date.now() }, { rev: claimedRev });
+                            }
+                            catch {
+                            }
+                        };
+                        try {
+                            await opts.runner.sessions.acquire(row.sessionId, { requireExisting: true });
+                        }
+                        catch (e) {
+                            await rollbackDrain();
+                            if (e?.code === "not_found") {
+                                return queueFullReceipt(`Its transcript session no longer exists (evicted or reaped), so a revival cannot drain the backlog.`);
+                            }
+                            return queueFullReceipt(`Its transcript store did not answer (${e instanceof Error ? e.message : String(e)}) — this send did not start a backlog drain; a later resend will try again.`);
+                        }
+                        const drainLeaseOwner = `${opts.registry.writerId}:${ctx.toolCallId}`;
+                        let drainLease = null;
+                        try {
+                            drainLease = await opts.mailbox.claimLease(scope, handle, drainLeaseOwner, REVIVE_LEASE_TTL_MS);
+                        }
+                        catch {
+                            drainLease = null;
+                        }
+                        if (drainLease === null) {
+                            await rollbackDrain();
+                            return queueFullReceipt(`No backlog batch was claimable this time — this send did not start a backlog drain; a later resend will try again.`);
+                        }
+                        const drainPrompt = `${drainLease.messages.map((m) => frameTeammateMessage({ from: m.from ?? "main", text: m.content })).join("\n")}\n\n${PEER_MESSAGE_NOTICE}`;
+                        const drainSeed = drainLease.messages[drainLease.messages.length - 1]?.hopChain ?? [];
+                        let drainSpawned;
+                        try {
+                            drainSpawned = await opts.reviveSpawn({ row: claimed, rev: claimedRev, prompt: drainPrompt, peerSeed: { hopChain: [...drainSeed] } });
+                        }
+                        catch (e) {
+                            drainSpawned = { isError: true, content: e instanceof Error ? e.message : String(e) };
+                        }
+                        if (drainSpawned.isError === true) {
+                            try {
+                                await opts.mailbox.releaseLease(scope, handle, drainLeaseOwner);
+                            }
+                            catch {
+                            }
+                            await rollbackDrain();
+                            return queueFullReceipt(`Reviving it to drain the backlog failed (${drainSpawned.content}) — this send did not start a backlog drain; a later resend will try again.`);
+                        }
+                        try {
+                            await opts.mailbox.ack(scope, handle, drainLeaseOwner, drainLease.maxSeq);
+                        }
+                        catch {
+                        }
+                        return queueFullReceipt(`The agent is being revived to digest its ${drainLease.messages.length} queued message(s) — resend after it settles.`);
+                    }
+                    finally {
+                        opts.registry.endDurableClaim(handle);
+                    }
+                }
                 if (!opts.registry.beginDurableClaim(handle)) {
                     return {
-                        content: `Message not sent: ${whoT3} is being revived or recycled right now — send again in a moment.`,
+                        content: `Message not sent: ${whoT3} is being revived or recycled right now — send again in a moment. ${DEDUP_RETRY_NOTE}`,
                         details: { error: "claim_contended", to },
                         isError: true,
                     };
@@ -235,13 +361,13 @@ export function createSendMessageTool(opts) {
                         }
                         if (fresh?.status === "running") {
                             return {
-                                content: `Message not sent: ${whoT3} was just revived by another delivery — it is running now. Send again to reach the running agent.`,
+                                content: `Message not sent: ${whoT3} was just revived by another delivery — it is running now. Send again to reach the running agent. ${DEDUP_RETRY_NOTE}`,
                                 details: { error: "claim_lost", to },
                                 isError: true,
                             };
                         }
                         return {
-                            content: `Message not sent: ${whoT3}'s durable record changed underneath this delivery — send again.`,
+                            content: `Message not sent: ${whoT3}'s durable record changed underneath this delivery — send again. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "claim_lost", to },
                             isError: true,
                         };
@@ -267,19 +393,19 @@ export function createSendMessageTool(opts) {
                             };
                         }
                         return {
-                            content: `Message not sent: ${whoT3}'s transcript store did not answer (${e instanceof Error ? e.message : String(e)}) — nothing was parked; send again.`,
+                            content: `Message not sent: ${whoT3}'s transcript store did not answer (${e instanceof Error ? e.message : String(e)}) — nothing was parked; send again. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "session_store_unavailable", to },
                             isError: true,
                         };
                     }
                     const clipped = clipCarrierMessage(message);
                     try {
-                        await opts.mailbox.append(scope, handle, { from: senderLabel, content: `[${summary}] ${clipped}`, sentAt: now });
+                        await opts.mailbox.append(scope, handle, { from: senderLabel, content: `[${summary}] ${clipped}`, sentAt: now, hopChain: prospectiveChain });
                     }
                     catch (e) {
                         await rollback();
                         return {
-                            content: `Message not sent: the durable mailbox refused the message (${e instanceof Error ? e.message : String(e)}) — nothing was parked and the agent was not revived.`,
+                            content: `Message not sent: the durable mailbox refused the message (${e instanceof Error ? e.message : String(e)}) — nothing was parked and the agent was not revived. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "mailbox_failed", to },
                             isError: true,
                         };
@@ -299,12 +425,13 @@ export function createSendMessageTool(opts) {
                             details: { error: "mailbox_leased", to },
                         };
                     }
-                    const revivePrompt = lease.messages
+                    const revivePrompt = `${lease.messages
                         .map((m) => frameTeammateMessage({ from: m.from ?? "main", text: m.content }))
-                        .join("\n");
+                        .join("\n")}\n\n${PEER_MESSAGE_NOTICE}`;
+                    const reviveSeed = lease.messages[lease.messages.length - 1]?.hopChain ?? [];
                     let spawned;
                     try {
-                        spawned = await opts.reviveSpawn({ row: claimed, rev: claimedRev, prompt: revivePrompt });
+                        spawned = await opts.reviveSpawn({ row: claimed, rev: claimedRev, prompt: revivePrompt, peerSeed: { hopChain: [...reviveSeed] } });
                     }
                     catch (e) {
                         spawned = { isError: true, content: e instanceof Error ? e.message : String(e), details: { error: "revive_failed" } };
@@ -418,8 +545,12 @@ export function createSendMessageTool(opts) {
             }
             if (row.status === "running" || row.status === "pending") {
                 return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
+                    const liveRecipientKey = peerAxisToken(resolvedAccess.scope, "h", targetId);
+                    const liveVerdict = admitFor(liveRecipientKey, [liveRecipientKey]);
+                    if (!liveVerdict.ok)
+                        return admissionRefusal(liveVerdict.reason, who);
                     const s2Clipped = clipCarrierMessage(message);
-                    const teammateXml = frameTeammateMessage({ from: senderLabel, summary, text: s2Clipped });
+                    const teammateXml = `${frameTeammateMessage({ from: senderLabel, summary, text: s2Clipped })}\n\n${PEER_MESSAGE_NOTICE}`;
                     const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
                         task_id: senderLabel,
                         task_type: "background_agent",
@@ -427,13 +558,14 @@ export function createSendMessageTool(opts) {
                         summary: `message from ${senderLabel}: ${summary}`,
                         result: teammateXml,
                         seq: ++uplinkSeqGlobal,
+                        peer: { hopChain: prospectiveChain },
                     }, { priority: "next" });
                     if (delivered.ok) {
                         const receiptText = delivered.disposition === "parked"
                             ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. You will be notified of its completion; continue with other work.`
                             : delivered.disposition === "pending"
-                                ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered.`
-                                : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll.`;
+                                ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered. ${DEDUP_RETRY_NOTE}`
+                                : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll. ${DEDUP_RETRY_NOTE}`;
                         return {
                             content: receiptText,
                             details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, summary },
@@ -441,15 +573,22 @@ export function createSendMessageTool(opts) {
                     }
                     if (delivered.reason === "no_channel") {
                         return {
-                            content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it.`,
+                            content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "still_running", to },
                             isError: true,
                         };
                     }
+                    if (delivered.reason === "queue_full") {
+                        return {
+                            content: `Message not sent: ${who} is still starting up and its startup message buffer is full — resend in a moment. ${DEDUP_RETRY_NOTE}`,
+                            details: { error: "queue_full", to },
+                            isError: true,
+                        };
+                    }
                     const nowRow = opts.registry.getAccessibleTask(targetId, resolvedAccess);
                     if (nowRow?.status === "parked") {
                         return {
-                            content: `Message not sent: ${who} is parked on a pending approval — it resumes when the approval is decided, not by message delivery. Send again after it resumes.`,
+                            content: `Message not sent: ${who} is parked on a pending approval — it resumes when the approval is decided, not by message delivery. Send again after it resumes. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "parked_pending_approval", to },
                             isError: true,
                         };
@@ -457,12 +596,12 @@ export function createSendMessageTool(opts) {
                     const stillLive = nowRow !== undefined && (nowRow.status === "running" || nowRow.status === "pending");
                     return stillLive
                         ? {
-                            content: `Message not sent: ${who} is still starting up (it has not begun reading messages yet) — the message was not delivered. Send again shortly.`,
+                            content: `Message not sent: ${who} is still starting up (it has not begun reading messages yet) — the message was not delivered. Send again shortly. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "settle_race", to },
                             isError: true,
                         }
                         : {
-                            content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript.`,
+                            content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "settle_race", to },
                             isError: true,
                         };
@@ -506,10 +645,20 @@ export function createSendMessageTool(opts) {
                 };
             }
             return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
+                const l3Entry = ledger.get(resumeToolUseId);
+                const l3RecipientKey = peerAxisToken(access.scope, "h", targetId);
+                const l3Verdict = admitFor(l3RecipientKey, [
+                    l3RecipientKey,
+                    ...(l3Entry?.childSessionId !== undefined ? [peerAxisToken(access.scope, "s", l3Entry.childSessionId)] : []),
+                ]);
+                if (!l3Verdict.ok)
+                    return admissionRefusal(l3Verdict.reason, who);
                 const resume = createSubagentResume({
                     ledger,
                     parentToolCallId: resumeToolUseId,
                     runner: opts.runner,
+                    peerOrigin: { hopChain: prospectiveChain },
+                    ...(opts.notify !== undefined && selfRef !== undefined ? { currentParentPeerRef: selfRef } : {}),
                     ...(opts.notify ? { notify: opts.notify } : {}),
                     ...(opts.sink ? { sink: opts.sink } : {}),
                     registry: opts.registry,
@@ -558,10 +707,11 @@ export function createSendMessageTool(opts) {
                                 : code === "resume.cap"
                                     ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
                                     : code === "steering.still_running"
-                                        ? `${who} (or a prior follow-up to it) is still running — wait for its completion notification.`
+                                        ?
+                                            `${who} (or a prior follow-up to it) is still running — wait for its completion notification. ${DEDUP_RETRY_NOTE}`
                                         : code === "resume.row_gone"
                                             ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
-                                            : `${e instanceof Error ? e.message : String(e)}`;
+                                            : `${e instanceof Error ? e.message : String(e)} ${DEDUP_RETRY_NOTE}`;
                     return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
                 }
             });

package/dist/agents/subagent.d.ts

@@ -6,8 +6,17 @@ import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
 export { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SubagentRetainLedger } from "./retain-ledger.js";
+import { type PeerSelfRef } from "./peer-admission.js";
 export type { SubagentStep, SubagentEditedFile } from "./subagent-steps.js";
 export declare function notifyResultField(result: string | undefined): string | undefined;
+interface ReviewSample {
+    text: string;
+    readChars: number;
+    totalChars: number;
+    sampled: boolean;
+    gaps: number;
+}
+export declare function layeredReviewSample(text: string, budget?: number, windows?: number): ReviewSample;
 export declare function inheritedManifestScopeFor(snapshot: readonly unknown[] | undefined): RunInternals["inheritedManifestScope"];
 export declare const DEFAULT_SUBAGENT_TOOL_NAME = "Agent";
 export declare const EXTRA_TOOLS_MAX_FACTORY_CALLS_PER_TREE = 64;
@@ -100,6 +109,10 @@ export declare function createSubagentResume(deps: {
     currentAutoModeReview?: {
         decider: import("../core/auto-mode.js").AutoModeDecider;
     };
+    peerOrigin?: {
+        hopChain: string[];
+    };
+    currentParentPeerRef?: PeerSelfRef;
     taskId?: string;
     taskAccess?: import("../core/task-registry.js").TaskAccess;
     bgSink?: (event: import("../core/types.js").BackgroundChildEvent) => void;

package/dist/agents/subagent.js

@@ -34,6 +34,7 @@ function delegatedCostField(stats) {
 }
 export { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getOrCreateSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
+import { createPeerInboundChainRef, createPeerSelfRef } from "./peer-admission.js";
 import { recordRosterSpawn } from "./roster-store.js";
 import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
@@ -54,6 +55,66 @@ export function notifyResultField(result) {
         ? `${result.slice(0, BG_AGENT_NOTIFY_RESULT_MAX)}\n[result truncated: ${result.length} chars total — call TaskOutput for the full text]`
         : result;
 }
+const HANDBACK_REVIEW_SAMPLE_BUDGET = 12_000;
+const HANDBACK_REVIEW_SAMPLE_WINDOWS = 5;
+const HANDBACK_REVIEW_SAMPLE_MAX_WINDOWS = 16;
+const HANDBACK_REVIEW_MARKER_COST = 32;
+const REVIEW_MARKER_SCAR = String.fromCharCode(0xff3b);
+function defuseGapMarkers(slice) {
+    return slice.replace(/\[…/g, `${REVIEW_MARKER_SCAR}…`);
+}
+function surrogateSafeSlice(text, from, width, anchorEnd = false) {
+    const isLow = (i) => text.charCodeAt(i) >= 0xdc00 && text.charCodeAt(i) <= 0xdfff;
+    const isHigh = (i) => text.charCodeAt(i) >= 0xd800 && text.charCodeAt(i) <= 0xdbff;
+    let start = from;
+    if (start > 0 && start < text.length && isLow(start) && isHigh(start - 1))
+        start--;
+    if (anchorEnd)
+        return { text: text.slice(start), start, end: text.length };
+    let end = Math.min(start + width, text.length);
+    if (end > start && end < text.length && isHigh(end - 1) && isLow(end))
+        end--;
+    return { text: text.slice(start, end), start, end };
+}
+export function layeredReviewSample(text, budget = HANDBACK_REVIEW_SAMPLE_BUDGET, windows = HANDBACK_REVIEW_SAMPLE_WINDOWS) {
+    const total = text.length;
+    const budgetChars = Number.isFinite(budget) ? Math.max(4, Math.floor(budget)) : HANDBACK_REVIEW_SAMPLE_BUDGET;
+    if (total <= budgetChars)
+        return { text, readChars: total, totalChars: total, sampled: false, gaps: 0 };
+    const requested = Number.isFinite(windows) ? Math.floor(windows) : HANDBACK_REVIEW_SAMPLE_WINDOWS;
+    const count = Math.max(2, Math.min(Math.max(2, requested), HANDBACK_REVIEW_SAMPLE_MAX_WINDOWS, Math.floor(budgetChars / HANDBACK_REVIEW_MARKER_COST)));
+    const size = Math.floor(budgetChars / count);
+    const span = total - size;
+    const parts = [];
+    let readChars = 0;
+    let prevEnd = 0;
+    let gaps = 0;
+    for (let i = 0; i < count; i++) {
+        const start = Math.round((span * i) / (count - 1));
+        const slice = surrogateSafeSlice(text, start, size, i === count - 1);
+        if (i > 0 && slice.start > prevEnd) {
+            parts.push(`\n[… ${slice.start - prevEnd} chars not shown …]\n`);
+            gaps++;
+        }
+        parts.push(defuseGapMarkers(slice.text));
+        readChars += slice.text.length;
+        prevEnd = slice.end;
+    }
+    const out = parts.join("");
+    if (out.length >= total)
+        return { text, readChars: total, totalChars: total, sampled: false, gaps: 0 };
+    return { text: out, readChars, totalChars: total, sampled: true, gaps };
+}
+function reviewCoverageNote(fields) {
+    const sampled = fields.filter((f) => f.sample.sampled);
+    if (sampled.length === 0)
+        return undefined;
+    return (sampled
+        .map((f) => `${f.field}: the classifier was shown ${f.sample.readChars} of ${f.sample.totalChars} characters (UTF-16 code units) ` +
+        `(layered head/middle/tail sample; the ${f.sample.gaps} skipped span(s) are marked in place as ` +
+        `"[… N chars not shown …]" — any further such marker in the text is the child's own writing, not this sampler's)`)
+        .join("; ") + " — the unshown spans were NOT reviewed; treat them as unknown, not as benign.");
+}
 const HANDBACK_ASK_MESSAGE = "Subagent has finished and is handing back control to the main agent. Review the subagent's work and flag if any action may violate security policy.";
 async function reviewHandback(opts) {
     const { review, evidence, signal } = opts;
@@ -63,15 +124,22 @@ async function reviewHandback(opts) {
         return undefined;
     if (!evidence.result && !evidence.steps && !evidence.edits && !evidence.partialText)
         return undefined;
+    const resultSample = evidence.result ? layeredReviewSample(evidence.result) : undefined;
+    const partialSample = evidence.partialText ? layeredReviewSample(evidence.partialText) : undefined;
+    const coverage = reviewCoverageNote([
+        ...(resultSample ? [{ field: "result", sample: resultSample }] : []),
+        ...(partialSample ? [{ field: "partialFindings", sample: partialSample }] : []),
+    ]);
     const verdict = await review.decider
         .decide({
         req: {
             toolName: opts.toolName,
             args: {
-                result: evidence.result?.slice(0, 2_000),
+                result: resultSample?.text,
                 toolSteps: evidence.steps,
                 editedFiles: evidence.edits,
-                ...(evidence.partialText ? { partialFindings: evidence.partialText.slice(0, 2_000) } : {}),
+                ...(partialSample ? { partialFindings: partialSample.text } : {}),
+                ...(coverage ? { reviewCoverage: coverage } : {}),
             },
             toolCallId: opts.toolCallId,
         },
@@ -437,7 +505,7 @@ export function createSubagentResume(deps) {
             entry.cycleSeq += 1;
             const resumeSpec = {
                 ...entry.specSnapshot,
-                objective: createResumePrompt(marker, content),
+                objective: createResumePrompt(marker, content, deps.peerOrigin !== undefined ? "peer" : "operator"),
                 sessionId: entry.childSessionId,
                 requireExistingSession: true,
                 ...(deps.currentOnQuestion !== undefined ? { onQuestion: deps.currentOnQuestion } : {}),
@@ -534,7 +602,10 @@ export function createSubagentResume(deps) {
                         },
                     }
                     : {}),
-                ...(deps.currentParentNotify !== undefined ? { parentNotify: deps.currentParentNotify } : {}),
+                ...(deps.currentParentNotify !== undefined
+                    ? { parentNotify: deps.currentParentNotify, parentPeerRef: deps.currentParentPeerRef }
+                    : {}),
+                peerInboundChainRef: createPeerInboundChainRef(deps.peerOrigin?.hopChain),
                 ...(reviveCycle !== undefined
                     ? {
                         onNotifyInjectorReady: (inject) => {
@@ -1499,6 +1570,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(treeScope !== undefined ? { registryScope: treeScope } : {}),
                 ...(ctx.inheritedGateForChildren ? { inheritedGate: ctx.inheritedGateForChildren() } : {}),
                 ownOrgAdmissionRef: { current: reviveClaim !== undefined ? readDurableOrgAdmission(reviveClaim.row) : undefined },
+                peerSelfRef: (() => {
+                    const ref = createPeerSelfRef(treeScope ?? "default");
+                    if (reviveClaim !== undefined)
+                        ref.addAxis("h", reviveClaim.row.handle);
+                    return ref;
+                })(),
+                peerInboundChainRef: createPeerInboundChainRef(reviveClaim?.peerSeed?.hopChain),
                 ...(childDefaultPersona !== undefined ? { defaultSystemPrompt: childDefaultPersona } : {}),
                 isDelegatedChild: true,
                 ...(ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : {}),
@@ -1520,7 +1598,12 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }),
                 ...(ctx.centerArtifactDigest !== undefined ? { parentCenterArtifactDigest: ctx.centerArtifactDigest } : {}),
                 ...(ctx.centerSourceRevision !== undefined ? { parentCenterSourceRevision: ctx.centerSourceRevision } : {}),
-                ...(ctx.onTaskNotification !== undefined ? { parentNotify: ctx.onTaskNotification } : {}),
+                ...(ctx.onTaskNotification !== undefined
+                    ? {
+                        parentNotify: ctx.onTaskNotification,
+                        ...(ctx.peerSelfRef !== undefined ? { parentPeerRef: ctx.peerSelfRef } : {}),
+                    }
+                    : {}),
                 ...(ctx.subagentRetain !== undefined ? { parentRetainLedger: ctx.subagentRetain } : {}),
                 onForwardEvent: recordingForward,
                 ...(worktreeDir !== undefined
@@ -1805,6 +1888,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const wt = await finishWorktree();
                         return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                     }
+                    childInternals.peerSelfRef?.addAxis("h", taskId);
                     bg.registry.bindBackgroundAgentSession(taskId, forkedId);
                     const forkBgHangAt = Date.now();
                     bg.registry.attachAgentTerminalNotifier(taskId, () => {
@@ -2255,6 +2339,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const wt = await finishWorktree();
                     return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                 }
+                childInternals.peerSelfRef?.addAxis("h", taskId);
                 if (agentName !== undefined) {
                     recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
                 }

package/dist/core/ask-question.js

@@ -174,7 +174,12 @@ export function createAskUserQuestionTool(onQuestion, source, opts) {
         description: "Ask the user a structured multiple-choice question when you are genuinely stuck or a decision is " +
             "the user's to make (which approach, which of these). Provide 1-4 questions, each with 2-4 options " +
             "(label + description). Use sparingly — not for anything you can determine yourself from the code or " +
-            "the task. If no human is available you will be told to proceed with your best judgment.\n" +
+            "the task. " +
+            (onQuestion !== undefined && opts?.posture === "interactive" && opts.interactiveFallback !== true
+                ? "If no human can be reached this call FAILS with a coded error — do not plan around being told to " +
+                    "proceed with your best judgment."
+                : "If no human is available you will be told to proceed with your best judgment.") +
+            "\n" +
             "\n" +
             "Usage notes:\n" +
             '- Users will always be able to select "Other" to provide custom text input\n' +
@@ -251,6 +256,16 @@ export function createAskUserQuestionTool(onQuestion, source, opts) {
                             details: { type: "ask-question", questionId: ctx.toolCallId, code: "question.human_unavailable", reason: "declined_unavailable" },
                         };
                     }
+                    if (opts?.posture === "interactive" && opts.interactiveFallback !== true) {
+                        return {
+                            content: `Error (AskUserQuestion): the wired human channel reported that nobody was reachable for this ` +
+                                `question. This run declared interaction posture "interactive", so the engine will not silently ` +
+                                `self-answer; re-deliver the question once a human is reachable (or opt into the synthetic ` +
+                                `continuation explicitly via interactiveQuestionFallback).`,
+                            isError: true,
+                            details: { type: "ask-question", questionId: ctx.toolCallId, code: "question.human_unavailable", reason: "declined_unavailable" },
+                        };
+                    }
                     discloseSyntheticContinuation(ctx.toolCallId, "declined_unavailable");
                     return {
                         content: NO_HUMAN,