fix(security): scope session tools and webhook secret fallback

src/agents/openclaw-tools.sessions-visibility.e2e.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from "vitest";
+
+const callGatewayMock = vi.fn();
+vi.mock("../gateway/call.js", () => ({
+  callGateway: (opts: unknown) => callGatewayMock(opts),
+}));
+
+let mockConfig: Record<string, unknown> = {
+  session: { mainKey: "main", scope: "per-sender" },
+};
+vi.mock("../config/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../config/config.js")>();
+  return {
+    ...actual,
+    loadConfig: () => mockConfig,
+    resolveGatewayPort: () => 18789,
+  };
+});
+
+import "./test-helpers/fast-core-tools.js";
+import { createOpenClawTools } from "./openclaw-tools.js";
+
+describe("sessions tools visibility", () => {
+  it("defaults to tree visibility (self + spawned) for sessions_history", async () => {
+    mockConfig = {
+      session: { mainKey: "main", scope: "per-sender" },
+      tools: { agentToAgent: { enabled: false } },
+    };
+    callGatewayMock.mockReset();
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const req = opts as { method?: string; params?: Record<string, unknown> };
+      if (req.method === "sessions.list" && req.params?.spawnedBy === "main") {
+        return { sessions: [{ key: "subagent:child-1" }] };
+      }
+      if (req.method === "sessions.resolve") {
+        const key = typeof req.params?.key === "string" ? String(req.params?.key) : "";
+        return { key };
+      }
+      if (req.method === "chat.history") {
+        return { messages: [{ role: "assistant", content: [{ type: "text", text: "ok" }] }] };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({ agentSessionKey: "main" }).find(
+      (candidate) => candidate.name === "sessions_history",
+    );
+    expect(tool).toBeDefined();
+    if (!tool) {
+      throw new Error("missing sessions_history tool");
+    }
+
+    const denied = await tool.execute("call1", {
+      sessionKey: "agent:main:discord:direct:someone-else",
+    });
+    expect(denied.details).toMatchObject({ status: "forbidden" });
+
+    const allowed = await tool.execute("call2", { sessionKey: "subagent:child-1" });
+    expect(allowed.details).toMatchObject({
+      sessionKey: "subagent:child-1",
+    });
+  });
+
+  it("allows broader access when tools.sessions.visibility=all", async () => {
+    mockConfig = {
+      session: { mainKey: "main", scope: "per-sender" },
+      tools: { sessions: { visibility: "all" }, agentToAgent: { enabled: false } },
+    };
+    callGatewayMock.mockReset();
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const req = opts as { method?: string; params?: Record<string, unknown> };
+      if (req.method === "chat.history") {
+        return { messages: [{ role: "assistant", content: [{ type: "text", text: "ok" }] }] };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({ agentSessionKey: "main" }).find(
+      (candidate) => candidate.name === "sessions_history",
+    );
+    expect(tool).toBeDefined();
+    if (!tool) {
+      throw new Error("missing sessions_history tool");
+    }
+
+    const result = await tool.execute("call3", {
+      sessionKey: "agent:main:discord:direct:someone-else",
+    });
+    expect(result.details).toMatchObject({
+      sessionKey: "agent:main:discord:direct:someone-else",
+    });
+  });
+
+  it("clamps sandboxed sessions to tree when agents.defaults.sandbox.sessionToolsVisibility=spawned", async () => {
+    mockConfig = {
+      session: { mainKey: "main", scope: "per-sender" },
+      tools: { sessions: { visibility: "all" }, agentToAgent: { enabled: true, allow: ["*"] } },
+      agents: { defaults: { sandbox: { sessionToolsVisibility: "spawned" } } },
+    };
+    callGatewayMock.mockReset();
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const req = opts as { method?: string; params?: Record<string, unknown> };
+      if (req.method === "sessions.list" && req.params?.spawnedBy === "main") {
+        return { sessions: [] };
+      }
+      if (req.method === "chat.history") {
+        return { messages: [{ role: "assistant", content: [{ type: "text", text: "ok" }] }] };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({ agentSessionKey: "main", sandboxed: true }).find(
+      (candidate) => candidate.name === "sessions_history",
+    );
+    expect(tool).toBeDefined();
+    if (!tool) {
+      throw new Error("missing sessions_history tool");
+    }
+
+    const denied = await tool.execute("call4", {
+      sessionKey: "agent:other:main",
+    });
+    expect(denied.details).toMatchObject({ status: "forbidden" });
+  });
+});

src/agents/openclaw-tools.sessions.e2e.test.ts

@@ -20,6 +20,10 @@ vi.mock("../config/config.js", async (importOriginal) => {
         scope: "per-sender",
         agentToAgent: { maxPingPongTurns: 2 },
       },
+      tools: {
+        // Keep sessions tools permissive in this suite; dedicated visibility tests cover defaults.
+        sessions: { visibility: "all" },
+      },
     }),
     resolveGatewayPort: () => 18789,
   };

src/agents/openclaw-tools.subagents.sessions-spawn-normalizes-allowlisted-agent-ids.e2e.test.ts

@@ -0,0 +1,377 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { emitAgentEvent } from "../infra/agent-events.js";
+import { createOpenClawTools } from "./openclaw-tools.js";
+import "./test-helpers/fast-core-tools.js";
+import { resetSubagentRegistryForTests } from "./subagent-registry.js";
+
+type SessionsSpawnTestConfig = ReturnType<(typeof import("../config/config.js"))["loadConfig"]>;
+
+const hoisted = vi.hoisted(() => {
+  const callGatewayMock = vi.fn();
+  const defaultConfigOverride = {
+    session: {
+      mainKey: "main",
+      scope: "per-sender",
+    },
+  } as SessionsSpawnTestConfig;
+  const state = { configOverride: defaultConfigOverride };
+  return { callGatewayMock, defaultConfigOverride, state };
+});
+
+const callGatewayMock = hoisted.callGatewayMock;
+
+function resetConfigOverride() {
+  hoisted.state.configOverride = hoisted.defaultConfigOverride;
+}
+
+function setConfigOverride(next: SessionsSpawnTestConfig) {
+  hoisted.state.configOverride = next;
+}
+
+vi.mock("../gateway/call.js", () => ({
+  callGateway: (opts: unknown) => hoisted.callGatewayMock(opts),
+}));
+// Some tools import callGateway via "../../gateway/call.js" (from nested folders). Mock that too.
+vi.mock("../../gateway/call.js", () => ({
+  callGateway: (opts: unknown) => hoisted.callGatewayMock(opts),
+}));
+
+vi.mock("../config/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../config/config.js")>();
+  return {
+    ...actual,
+    loadConfig: () => hoisted.state.configOverride,
+    resolveGatewayPort: () => 18789,
+  };
+});
+
+// Same module, different specifier (used by tools under src/agents/tools/*).
+vi.mock("../../config/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../config/config.js")>();
+  return {
+    ...actual,
+    loadConfig: () => hoisted.state.configOverride,
+    resolveGatewayPort: () => 18789,
+  };
+});
+
+describe("openclaw-tools: subagents", () => {
+  beforeEach(() => {
+    resetConfigOverride();
+  });
+
+  it("sessions_spawn normalizes allowlisted agent ids", async () => {
+    resetSubagentRegistryForTests();
+    callGatewayMock.mockReset();
+    setConfigOverride({
+      session: {
+        mainKey: "main",
+        scope: "per-sender",
+      },
+      agents: {
+        list: [
+          {
+            id: "main",
+            subagents: {
+              allowAgents: ["Research"],
+            },
+          },
+        ],
+      },
+    });
+
+    let childSessionKey: string | undefined;
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const request = opts as { method?: string; params?: unknown };
+      if (request.method === "agent") {
+        const params = request.params as { sessionKey?: string } | undefined;
+        childSessionKey = params?.sessionKey;
+        return { runId: "run-1", status: "accepted", acceptedAt: 5200 };
+      }
+      if (request.method === "agent.wait") {
+        return { status: "timeout" };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({
+      agentSessionKey: "main",
+      agentChannel: "whatsapp",
+    }).find((candidate) => candidate.name === "sessions_spawn");
+    if (!tool) {
+      throw new Error("missing sessions_spawn tool");
+    }
+
+    const result = await tool.execute("call10", {
+      task: "do thing",
+      agentId: "research",
+    });
+
+    expect(result.details).toMatchObject({
+      status: "accepted",
+      runId: "run-1",
+    });
+    expect(childSessionKey?.startsWith("agent:research:subagent:")).toBe(true);
+  });
+  it("sessions_spawn forbids cross-agent spawning when not allowed", async () => {
+    resetSubagentRegistryForTests();
+    callGatewayMock.mockReset();
+    setConfigOverride({
+      session: {
+        mainKey: "main",
+        scope: "per-sender",
+      },
+      agents: {
+        list: [
+          {
+            id: "main",
+            subagents: {
+              allowAgents: ["alpha"],
+            },
+          },
+        ],
+      },
+    });
+
+    const tool = createOpenClawTools({
+      agentSessionKey: "main",
+      agentChannel: "whatsapp",
+    }).find((candidate) => candidate.name === "sessions_spawn");
+    if (!tool) {
+      throw new Error("missing sessions_spawn tool");
+    }
+
+    const result = await tool.execute("call9", {
+      task: "do thing",
+      agentId: "beta",
+    });
+    expect(result.details).toMatchObject({
+      status: "forbidden",
+    });
+    expect(callGatewayMock).not.toHaveBeenCalled();
+  });
+
+  it("sessions_spawn runs cleanup via lifecycle events", async () => {
+    resetSubagentRegistryForTests();
+    callGatewayMock.mockReset();
+    const calls: Array<{ method?: string; params?: unknown }> = [];
+    let agentCallCount = 0;
+    let deletedKey: string | undefined;
+    let childRunId: string | undefined;
+    let childSessionKey: string | undefined;
+    const waitCalls: Array<{ runId?: string; timeoutMs?: number }> = [];
+
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const request = opts as { method?: string; params?: unknown };
+      calls.push(request);
+      if (request.method === "agent") {
+        agentCallCount += 1;
+        const runId = `run-${agentCallCount}`;
+        const params = request.params as {
+          message?: string;
+          sessionKey?: string;
+          channel?: string;
+          timeout?: number;
+          lane?: string;
+        };
+        if (params?.lane === "subagent") {
+          childRunId = runId;
+          childSessionKey = params?.sessionKey ?? "";
+          expect(params?.channel).toBe("discord");
+          expect(params?.timeout).toBe(1);
+        }
+        return {
+          runId,
+          status: "accepted",
+          acceptedAt: 1000 + agentCallCount,
+        };
+      }
+      if (request.method === "agent.wait") {
+        const params = request.params as { runId?: string; timeoutMs?: number } | undefined;
+        waitCalls.push(params ?? {});
+        return {
+          runId: params?.runId ?? "run-1",
+          status: "ok",
+          startedAt: 1000,
+          endedAt: 2000,
+        };
+      }
+      if (request.method === "sessions.delete") {
+        const params = request.params as { key?: string } | undefined;
+        deletedKey = params?.key;
+        return { ok: true };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({
+      agentSessionKey: "discord:group:req",
+      agentChannel: "discord",
+    }).find((candidate) => candidate.name === "sessions_spawn");
+    if (!tool) {
+      throw new Error("missing sessions_spawn tool");
+    }
+
+    const result = await tool.execute("call1", {
+      task: "do thing",
+      runTimeoutSeconds: 1,
+      cleanup: "delete",
+    });
+    expect(result.details).toMatchObject({
+      status: "accepted",
+      runId: "run-1",
+    });
+
+    if (!childRunId) {
+      throw new Error("missing child runId");
+    }
+    vi.useFakeTimers();
+    try {
+      emitAgentEvent({
+        runId: childRunId,
+        stream: "lifecycle",
+        data: {
+          phase: "end",
+          startedAt: 1234,
+          endedAt: 2345,
+        },
+      });
+
+      await vi.runAllTimersAsync();
+    } finally {
+      vi.useRealTimers();
+    }
+
+    const childWait = waitCalls.find((call) => call.runId === childRunId);
+    expect(childWait?.timeoutMs).toBe(1000);
+
+    const agentCalls = calls.filter((call) => call.method === "agent");
+    const spawnCalls = agentCalls.filter((call) => {
+      const params = call.params as { lane?: string } | undefined;
+      return params?.lane === "subagent";
+    });
+    expect(spawnCalls).toHaveLength(1);
+    const announceCalls = agentCalls.filter((call) => {
+      const params = call.params as { sessionKey?: string; deliver?: boolean } | undefined;
+      return params?.deliver === true && params?.sessionKey === "discord:group:req";
+    });
+    expect(announceCalls).toHaveLength(1);
+
+    const first = spawnCalls[0]?.params as
+      | {
+          lane?: string;
+          deliver?: boolean;
+          sessionKey?: string;
+          channel?: string;
+        }
+      | undefined;
+    expect(first?.lane).toBe("subagent");
+    expect(first?.deliver).toBe(false);
+    expect(first?.channel).toBe("discord");
+    expect(first?.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
+    expect(childSessionKey?.startsWith("agent:main:subagent:")).toBe(true);
+
+    const second = announceCalls[0]?.params as
+      | {
+          sessionKey?: string;
+          message?: string;
+          deliver?: boolean;
+        }
+      | undefined;
+    expect(second?.sessionKey).toBe("discord:group:req");
+    expect(second?.deliver).toBe(true);
+    expect(second?.message).toContain("subagent task");
+
+    const sendCalls = calls.filter((c) => c.method === "send");
+    expect(sendCalls.length).toBe(0);
+
+    expect(deletedKey?.startsWith("agent:main:subagent:")).toBe(true);
+  });
+
+  it("sessions_spawn announces with requester accountId", async () => {
+    resetSubagentRegistryForTests();
+    callGatewayMock.mockReset();
+    const calls: Array<{ method?: string; params?: unknown }> = [];
+    let agentCallCount = 0;
+    let childRunId: string | undefined;
+
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const request = opts as { method?: string; params?: unknown };
+      calls.push(request);
+      if (request.method === "agent") {
+        agentCallCount += 1;
+        const runId = `run-${agentCallCount}`;
+        const params = request.params as { lane?: string; sessionKey?: string } | undefined;
+        if (params?.lane === "subagent") {
+          childRunId = runId;
+        }
+        return {
+          runId,
+          status: "accepted",
+          acceptedAt: 4000 + agentCallCount,
+        };
+      }
+      if (request.method === "agent.wait") {
+        const params = request.params as { runId?: string; timeoutMs?: number } | undefined;
+        return {
+          runId: params?.runId ?? "run-1",
+          status: "ok",
+          startedAt: 1000,
+          endedAt: 2000,
+        };
+      }
+      if (request.method === "sessions.delete" || request.method === "sessions.patch") {
+        return { ok: true };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({
+      agentSessionKey: "main",
+      agentChannel: "whatsapp",
+      agentAccountId: "kev",
+    }).find((candidate) => candidate.name === "sessions_spawn");
+    if (!tool) {
+      throw new Error("missing sessions_spawn tool");
+    }
+
+    const result = await tool.execute("call2", {
+      task: "do thing",
+      runTimeoutSeconds: 1,
+      cleanup: "keep",
+    });
+    expect(result.details).toMatchObject({
+      status: "accepted",
+      runId: "run-1",
+    });
+
+    if (!childRunId) {
+      throw new Error("missing child runId");
+    }
+    vi.useFakeTimers();
+    try {
+      emitAgentEvent({
+        runId: childRunId,
+        stream: "lifecycle",
+        data: {
+          phase: "end",
+          startedAt: 1000,
+          endedAt: 2000,
+        },
+      });
+
+      await vi.runAllTimersAsync();
+    } finally {
+      vi.useRealTimers();
+    }
+
+    const agentCalls = calls.filter((call) => call.method === "agent");
+    expect(agentCalls).toHaveLength(2);
+    const announceParams = agentCalls[1]?.params as
+      | { accountId?: string; channel?: string; deliver?: boolean }
+      | undefined;
+    expect(announceParams?.deliver).toBe(true);
+    expect(announceParams?.channel).toBe("whatsapp");
+    expect(announceParams?.accountId).toBe("kev");
+  });
+});

src/agents/tools/sessions-helpers.ts

@@ -44,6 +44,62 @@ export type SessionListRow = {
   messages?: unknown[];
 };
 
+export type SessionToolsVisibility = "self" | "tree" | "agent" | "all";
+
+export function resolveSessionToolsVisibility(cfg: OpenClawConfig): SessionToolsVisibility {
+  const raw = (cfg.tools as { sessions?: { visibility?: unknown } } | undefined)?.sessions
+    ?.visibility;
+  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  if (value === "self" || value === "tree" || value === "agent" || value === "all") {
+    return value;
+  }
+  return "tree";
+}
+
+export function resolveEffectiveSessionToolsVisibility(params: {
+  cfg: OpenClawConfig;
+  sandboxed: boolean;
+}): SessionToolsVisibility {
+  const visibility = resolveSessionToolsVisibility(params.cfg);
+  if (!params.sandboxed) {
+    return visibility;
+  }
+  const sandboxClamp = params.cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
+  if (sandboxClamp === "spawned" && visibility !== "tree") {
+    return "tree";
+  }
+  return visibility;
+}
+
+export async function listSpawnedSessionKeys(params: {
+  requesterSessionKey: string;
+  limit?: number;
+}): Promise<Set<string>> {
+  const limit =
+    typeof params.limit === "number" && Number.isFinite(params.limit)
+      ? Math.max(1, Math.floor(params.limit))
+      : 500;
+  try {
+    const list = await callGateway<{ sessions: Array<{ key?: unknown }> }>({
+      method: "sessions.list",
+      params: {
+        includeGlobal: false,
+        includeUnknown: false,
+        limit,
+        spawnedBy: params.requesterSessionKey,
+      },
+    });
+    const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
+    const keys = sessions
+      .map((entry) => (typeof entry?.key === "string" ? entry.key : ""))
+      .map((value) => value.trim())
+      .filter(Boolean);
+    return new Set(keys);
+  } catch {
+    return new Set();
+  }
+}
+
 function normalizeKey(value?: string) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : undefined;

src/agents/tools/sessions-history-tool.ts

@@ -8,6 +8,8 @@ import { truncateUtf16Safe } from "../../utils.js";
 import { jsonResult, readStringParam } from "./common.js";
 import {
   createAgentToAgentPolicy,
+  listSpawnedSessionKeys,
+  resolveEffectiveSessionToolsVisibility,
   resolveSessionReference,
   SessionListRow,
   resolveSandboxedSessionToolContext,
@@ -167,7 +169,6 @@ async function isSpawnedSessionAllowed(params: {
     return false;
   }
 }
-
 export function createSessionsHistoryTool(opts?: {
   agentSessionKey?: string;
   sandboxed?: boolean;
@@ -189,11 +190,12 @@ export function createSessionsHistoryTool(opts?: {
           agentSessionKey: opts?.agentSessionKey,
           sandboxed: opts?.sandboxed,
         });
+      const effectiveRequesterKey = requesterInternalKey ?? alias;
       const resolvedSession = await resolveSessionReference({
         sessionKey: sessionKeyParam,
         alias,
         mainKey,
-        requesterInternalKey,
+        requesterInternalKey: effectiveRequesterKey,
         restrictToSpawned,
       });
       if (!resolvedSession.ok) {
@@ -203,9 +205,9 @@ export function createSessionsHistoryTool(opts?: {
       const resolvedKey = resolvedSession.key;
       const displayKey = resolvedSession.displayKey;
       const resolvedViaSessionId = resolvedSession.resolvedViaSessionId;
-      if (restrictToSpawned && requesterInternalKey && !resolvedViaSessionId) {
+      if (restrictToSpawned && !resolvedViaSessionId && resolvedKey !== effectiveRequesterKey) {
         const ok = await isSpawnedSessionAllowed({
-          requesterSessionKey: requesterInternalKey,
+          requesterSessionKey: effectiveRequesterKey,
           targetSessionKey: resolvedKey,
         });
         if (!ok) {
@@ -215,11 +217,22 @@ export function createSessionsHistoryTool(opts?: {
           });
         }
       }
+      const visibility = resolveEffectiveSessionToolsVisibility({
+        cfg,
+        sandboxed: opts?.sandboxed === true,
+      });
 
       const a2aPolicy = createAgentToAgentPolicy(cfg);
-      const requesterAgentId = resolveAgentIdFromSessionKey(requesterInternalKey);
+      const requesterAgentId = resolveAgentIdFromSessionKey(effectiveRequesterKey);
       const targetAgentId = resolveAgentIdFromSessionKey(resolvedKey);
       const isCrossAgent = requesterAgentId !== targetAgentId;
+      if (isCrossAgent && visibility !== "all") {
+        return jsonResult({
+          status: "forbidden",
+          error:
+            "Session history visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.",
+        });
+      }
       if (isCrossAgent) {
         if (!a2aPolicy.enabled) {
           return jsonResult({
@@ -236,6 +249,28 @@ export function createSessionsHistoryTool(opts?: {
         }
       }
 
+      if (!isCrossAgent) {
+        if (visibility === "self" && resolvedKey !== effectiveRequesterKey) {
+          return jsonResult({
+            status: "forbidden",
+            error:
+              "Session history visibility is restricted to the current session (tools.sessions.visibility=self).",
+          });
+        }
+        if (visibility === "tree" && resolvedKey !== effectiveRequesterKey) {
+          const spawned = await listSpawnedSessionKeys({
+            requesterSessionKey: effectiveRequesterKey,
+          });
+          if (!spawned.has(resolvedKey)) {
+            return jsonResult({
+              status: "forbidden",
+              error:
+                "Session history visibility is restricted to the current session tree (tools.sessions.visibility=tree).",
+            });
+          }
+        }
+      }
+
       const limit =
         typeof params.limit === "number" && Number.isFinite(params.limit)
           ? Math.max(1, Math.floor(params.limit))

src/agents/tools/sessions-list-tool.ts

@@ -10,7 +10,9 @@ import {
   createAgentToAgentPolicy,
   classifySessionKind,
   deriveChannel,
+  listSpawnedSessionKeys,
   resolveDisplaySessionKey,
+  resolveEffectiveSessionToolsVisibility,
   resolveInternalSessionKey,
   resolveSandboxedSessionToolContext,
   type SessionListRow,
@@ -42,6 +44,11 @@ export function createSessionsListTool(opts?: {
           agentSessionKey: opts?.agentSessionKey,
           sandboxed: opts?.sandboxed,
         });
+      const effectiveRequesterKey = requesterInternalKey ?? alias;
+      const visibility = resolveEffectiveSessionToolsVisibility({
+        cfg,
+        sandboxed: opts?.sandboxed === true,
+      });
 
       const kindsRaw = readStringArrayParam(params, "kinds")?.map((value) =>
         value.trim().toLowerCase(),
@@ -72,15 +79,19 @@ export function createSessionsListTool(opts?: {
           activeMinutes,
           includeGlobal: !restrictToSpawned,
           includeUnknown: !restrictToSpawned,
-          spawnedBy: restrictToSpawned ? requesterInternalKey : undefined,
+          spawnedBy: restrictToSpawned ? effectiveRequesterKey : undefined,
         },
       });
 
       const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
       const storePath = typeof list?.path === "string" ? list.path : undefined;
       const a2aPolicy = createAgentToAgentPolicy(cfg);
-      const requesterAgentId = resolveAgentIdFromSessionKey(requesterInternalKey);
+      const requesterAgentId = resolveAgentIdFromSessionKey(effectiveRequesterKey);
       const rows: SessionListRow[] = [];
+      const spawnedKeys =
+        visibility === "tree"
+          ? await listSpawnedSessionKeys({ requesterSessionKey: effectiveRequesterKey })
+          : null;
 
       for (const entry of sessions) {
         if (!entry || typeof entry !== "object") {
@@ -93,8 +104,20 @@ export function createSessionsListTool(opts?: {
 
         const entryAgentId = resolveAgentIdFromSessionKey(key);
         const crossAgent = entryAgentId !== requesterAgentId;
-        if (crossAgent && !a2aPolicy.isAllowed(requesterAgentId, entryAgentId)) {
-          continue;
+        if (crossAgent) {
+          if (visibility !== "all") {
+            continue;
+          }
+          if (!a2aPolicy.isAllowed(requesterAgentId, entryAgentId)) {
+            continue;
+          }
+        } else {
+          if (visibility === "self" && key !== effectiveRequesterKey) {
+            continue;
+          }
+          if (visibility === "tree" && key !== effectiveRequesterKey && !spawnedKeys?.has(key)) {
+            continue;
+          }
         }
 
         if (key === "unknown") {

src/agents/tools/sessions-send-tool.ts

@@ -18,6 +18,8 @@ import { jsonResult, readStringParam } from "./common.js";
 import {
   createAgentToAgentPolicy,
   extractAssistantText,
+  listSpawnedSessionKeys,
+  resolveEffectiveSessionToolsVisibility,
   resolveInternalSessionKey,
   resolveMainSessionAlias,
   resolveSessionReference,
@@ -51,21 +53,25 @@ export function createSessionsSendTool(opts?: {
       const cfg = loadConfig();
       const { mainKey, alias } = resolveMainSessionAlias(cfg);
       const visibility = cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
-      const requesterInternalKey =
+      const requesterKeyInput =
         typeof opts?.agentSessionKey === "string" && opts.agentSessionKey.trim()
-          ? resolveInternalSessionKey({
-              key: opts.agentSessionKey,
-              alias,
-              mainKey,
-            })
-          : undefined;
+          ? opts.agentSessionKey
+          : "main";
+      const requesterInternalKey = resolveInternalSessionKey({
+        key: requesterKeyInput,
+        alias,
+        mainKey,
+      });
       const restrictToSpawned =
         opts?.sandboxed === true &&
         visibility === "spawned" &&
-        !!requesterInternalKey &&
         !isSubagentSessionKey(requesterInternalKey);
 
       const a2aPolicy = createAgentToAgentPolicy(cfg);
+      const sessionVisibility = resolveEffectiveSessionToolsVisibility({
+        cfg,
+        sandboxed: opts?.sandboxed === true,
+      });
 
       const sessionKeyParam = readStringParam(params, "sessionKey");
       const labelParam = readStringParam(params, "label")?.trim() || undefined;
@@ -199,7 +205,7 @@ export function createSessionsSendTool(opts?: {
       const displayKey = resolvedSession.displayKey;
       const resolvedViaSessionId = resolvedSession.resolvedViaSessionId;
 
-      if (restrictToSpawned && !resolvedViaSessionId) {
+      if (restrictToSpawned && !resolvedViaSessionId && resolvedKey !== requesterInternalKey) {
         const sessions = await listSessions({
           includeGlobal: false,
           includeUnknown: false,
@@ -227,6 +233,15 @@ export function createSessionsSendTool(opts?: {
       const requesterAgentId = resolveAgentIdFromSessionKey(requesterInternalKey);
       const targetAgentId = resolveAgentIdFromSessionKey(resolvedKey);
       const isCrossAgent = requesterAgentId !== targetAgentId;
+      if (isCrossAgent && sessionVisibility !== "all") {
+        return jsonResult({
+          runId: crypto.randomUUID(),
+          status: "forbidden",
+          error:
+            "Session send visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.",
+          sessionKey: displayKey,
+        });
+      }
       if (isCrossAgent) {
         if (!a2aPolicy.enabled) {
           return jsonResult({
@@ -245,6 +260,30 @@ export function createSessionsSendTool(opts?: {
             sessionKey: displayKey,
           });
         }
+      } else {
+        if (sessionVisibility === "self" && resolvedKey !== requesterInternalKey) {
+          return jsonResult({
+            runId: crypto.randomUUID(),
+            status: "forbidden",
+            error:
+              "Session send visibility is restricted to the current session (tools.sessions.visibility=self).",
+            sessionKey: displayKey,
+          });
+        }
+        if (sessionVisibility === "tree" && resolvedKey !== requesterInternalKey) {
+          const spawned = await listSpawnedSessionKeys({
+            requesterSessionKey: requesterInternalKey,
+          });
+          if (!spawned.has(resolvedKey)) {
+            return jsonResult({
+              runId: crypto.randomUUID(),
+              status: "forbidden",
+              error:
+                "Session send visibility is restricted to the current session tree (tools.sessions.visibility=tree).",
+              sessionKey: displayKey,
+            });
+          }
+        }
       }
 
       const agentMessageContext = buildAgentToAgentMessageContext({