token counts, and timestamps. Filter by kind (`main`, `group`, `cron`, `hook`,

`node`), exact `label`, exact `agentId`, search text, or recency

(`activeMinutes`). When you need mailbox-style triage, it can also ask for a

visibility-scoped derived title, a last-message preview snippet, or bounded

recent messages on each row. Derived titles and previews are produced only for

sessions the caller can already see under the configured session tool

visibility policy, so unrelated sessions stay hidden.

visibility-scoped derived title, a last-message preview snippet, or bounded recent

messages on each row. Derived titles and previews are produced only for sessions

the caller can already see under the configured session tool visibility policy, so

unrelated sessions stay hidden. When visibility is restricted, `sessions_list`

returns optional `visibility` metadata showing the effective mode and a warning that

results may be scope-limited.

`sessions_history` fetches the conversation transcript for a specific session.

By default, tool results are excluded -- pass `includeTools: true` to see them.

- `agent`: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).

- `all`: any session. Cross-agent targeting still requires `tools.agentToAgent`.

- Sandbox clamp: when the current session is sandboxed and `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility is forced to `tree` even if `tools.sessions.visibility="all"`.

- When not `all`, `sessions_list` includes a compact `visibility` field

describing the effective mode and a warning that some sessions may be

omitted outside the current scope.

</Accordion>

</AccordionGroup>

await Promise.all(Array.from({ length: maxConcurrent }, () => worker()));

}

const visibilityMetadata =

visibility === "all"

? undefined

: {

mode: visibility,

restricted: true,

warning: `Session visibility is restricted (effective tools.sessions.visibility=${visibility}). Results may omit sessions outside the current scope. The count field reflects only sessions within the current scope.`,

};

return jsonResult({

count: rows.length,

sessions: rows,

...(visibilityMetadata ? { visibility: visibilityMetadata } : {}),

});

},

};

const details = requireDetails(result);

expect(details.count).toBe(1);

expect(details.visibility).toBeUndefined();

const session = requireSessions(details)[0];

expect(session?.key).toBe("agent:codex:acp:child-1");

expect(session?.parentSessionKey).toBe(MAIN_AGENT_SESSION_KEY);

expect(callGatewayMock).toHaveBeenCalledTimes(1);

});

it("includes visibility metadata when session visibility is restricted", async () => {

loadConfigMock.mockReturnValue({

session: { scope: "per-sender", mainKey: "main" },

tools: {

agentToAgent: { enabled: true },

sessions: { visibility: "tree" },

},

});

const result = await createMainSessionsListTool().execute("call1", {});

const details = requireDetails(result);

expect(details.count).toBe(1);

expect(details.visibility).toMatchObject({

mode: "tree",

restricted: true,

warning:

"Session visibility is restricted (effective tools.sessions.visibility=tree). Results may omit sessions outside the current scope. The count field reflects only sessions within the current scope.",

});

});

it("keeps literal current keys for message previews", async () => {

callGatewayMock.mockReset();

callGatewayMock