- `attachments?` (optional array of inline files; subagent runtime only, ACP rejects). Each entry: `{ name, content, encoding?: "utf8" | "base64", mimeType? }`. Files are materialized into the child workspace at `.openclaw/attachments/<uuid>/`. Returns a receipt with sha256 per file.

- `attachAs?` (optional; `{ mountPath? }` hint reserved for future mount implementations)

Controls inline attachment support for `sessions_spawn`.

{

tools: {

sessions_spawn: {

attachments: {

enabled: false, // opt-in: set true to allow inline file attachments

maxTotalBytes: 5242880, // 5 MB total across all files

maxFiles: 50,

maxFileBytes: 1048576, // 1 MB per file

retainOnSessionKeep: false, // keep attachments when cleanup="keep"

},

},

},

}

Notes:

- Attachments are only supported for `runtime: "subagent"`. ACP runtime rejects them.

- Files are materialized into the child workspace at `.openclaw/attachments/<uuid>/` with a `.manifest.json`.

- Attachment content is automatically redacted from transcript persistence.

- Base64 inputs are validated with strict alphabet/padding checks and a pre-decode size guard.

- File permissions are `0700` for directories and `0600` for files.

- Cleanup follows the `cleanup` policy: `delete` always removes attachments; `keep` retains them only when `retainOnSessionKeep: true`.

- `sessions_spawn`: `task`, `label?`, `runtime?`, `agentId?`, `model?`, `thinking?`, `cwd?`, `runTimeoutSeconds?`, `thread?`, `mode?`, `cleanup?`, `sandbox?`, `attachments?`, `attachAs?`

- `sessions_spawn` supports inline file attachments for subagent runtime only (ACP rejects them). Each attachment has `name`, `content`, and optional `encoding` (`utf8` or `base64`) and `mimeType`. Files are materialized into the child workspace at `.openclaw/attachments/<uuid>/` with a `.manifest.json` metadata file. The tool returns a receipt with `count`, `totalBytes`, per file `sha256`, and `relDir`. Attachment content is automatically redacted from transcript persistence.

- Configure limits via `tools.sessions_spawn.attachments` (`enabled`, `maxTotalBytes`, `maxFiles`, `maxFileBytes`, `retainOnSessionKeep`).

- `attachAs.mountPath` is a reserved hint for future mount implementations.

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

} as unknown as Model<"openai-responses">,

import type { AgentMessage } from "@mariozechner/pi-agent-core";

import { describe, it, expect } from "vitest";

import { sanitizeToolCallInputs } from "./session-transcript-repair.js";

function mkSessionsSpawnToolCall(content: string): AgentMessage {

return {

role: "assistant",

content: [

{

type: "toolCall",

id: "call_1",

name: "sessions_spawn",

arguments: {

task: "do thing",

attachments: [

{

name: "README.md",

encoding: "utf8",

content,

},

],

},

},

],

timestamp: Date.now(),

} as unknown as AgentMessage;

describe("sanitizeToolCallInputs redacts sessions_spawn attachments", () => {

it("replaces attachments[].content with __OPENCLAW_REDACTED__", () => {

const secret = "SUPER_SECRET_SHOULD_NOT_PERSIST";

const input = [mkSessionsSpawnToolCall(secret)];

const out = sanitizeToolCallInputs(input);

expect(out).toHaveLength(1);

const msg = out[0] as { content?: unknown[] };

const tool = (msg.content?.[0] ?? null) as {

name?: string;

arguments?: { attachments?: Array<{ content?: string }> };

} | null;

expect(tool?.name).toBe("sessions_spawn");

expect(tool?.arguments?.attachments?.[0]?.content).toBe("__OPENCLAW_REDACTED__");

expect(JSON.stringify(out)).not.toContain(secret);

});

it("redacts attachments content from tool input payloads too", () => {

const secret = "INPUT_SECRET_SHOULD_NOT_PERSIST";

const input = [

{

role: "assistant",

content: [

{

type: "toolUse",

id: "call_2",

name: "sessions_spawn",

input: {

task: "do thing",

attachments: [{ name: "x.txt", content: secret }],

},

},

],

},

] as unknown as AgentMessage[];

const out = sanitizeToolCallInputs(input);

const msg = out[0] as { content?: unknown[] };

const tool = (msg.content?.[0] ?? null) as {

// Some providers emit tool calls as `input`/`toolUse`. We normalize to `toolCall` with `arguments`.

input?: { attachments?: Array<{ content?: string }> };

arguments?: { attachments?: Array<{ content?: string }> };

} | null;

expect(

tool?.input?.attachments?.[0]?.content || tool?.arguments?.attachments?.[0]?.content,

).toBe("__OPENCLAW_REDACTED__");

expect(JSON.stringify(out)).not.toContain(secret);

});

stripToolResultDetails,

it("preserves toolUse input shape for sessions_spawn when no attachments are present", () => {

const input = [

{

role: "assistant",

content: [

{

type: "toolUse",

id: "call_1",

name: "sessions_spawn",

input: { task: "hello" },

},

],

},

] as unknown as AgentMessage[];

const out = sanitizeToolCallInputs(input);

const toolCalls = getAssistantToolCallBlocks(out) as Array<Record<string, unknown>>;

expect(toolCalls).toHaveLength(1);

expect(Object.hasOwn(toolCalls[0] ?? {}, "input")).toBe(true);

expect(Object.hasOwn(toolCalls[0] ?? {}, "arguments")).toBe(false);

expect((toolCalls[0] ?? {}).input).toEqual({ task: "hello" });

});

it("redacts sessions_spawn attachments for mixed-case and padded tool names", () => {

const input = [

{

role: "assistant",

content: [

{

type: "toolUse",

id: "call_1",

name: " SESSIONS_SPAWN ",

input: {

task: "hello",

attachments: [{ name: "a.txt", content: "SECRET" }],

},

},

],

},

] as unknown as AgentMessage[];

const out = sanitizeToolCallInputs(input);

const toolCalls = getAssistantToolCallBlocks(out) as Array<Record<string, unknown>>;

expect(toolCalls).toHaveLength(1);

expect((toolCalls[0] ?? {}).name).toBe("SESSIONS_SPAWN");

const inputObj = (toolCalls[0]?.input ?? {}) as Record<string, unknown>;

const attachments = (inputObj.attachments ?? []) as Array<Record<string, unknown>>;

expect(attachments[0]?.content).toBe("__OPENCLAW_REDACTED__");

});

describe("stripToolResultDetails", () => {

it("removes details only from toolResult messages", () => {

const input = [

{

role: "toolResult",

toolCallId: "call_1",

toolName: "read",

content: [{ type: "text", text: "ok" }],

details: { internal: true },

},

{ role: "assistant", content: [{ type: "text", text: "keep me" }], details: { no: "touch" } },

{ role: "user", content: "hello" },

] as unknown as AgentMessage[];

const out = stripToolResultDetails(input) as unknown as Array<Record<string, unknown>>;

expect(Object.hasOwn(out[0] ?? {}, "details")).toBe(false);

expect((out[0] ?? {}).role).toBe("toolResult");

// Non-toolResult messages are preserved as-is.

expect(Object.hasOwn(out[1] ?? {}, "details")).toBe(true);

expect((out[1] ?? {}).role).toBe("assistant");

expect((out[2] ?? {}).role).toBe("user");

});

it("returns the same array reference when there are no toolResult details", () => {

const input = [

{ role: "assistant", content: [{ type: "text", text: "a" }] },

{

role: "toolResult",

toolCallId: "call_1",

toolName: "read",

content: [{ type: "text", text: "ok" }],

},

{ role: "user", content: "b" },

] as unknown as AgentMessage[];

const out = stripToolResultDetails(input);

expect(out).toBe(input);

});