Summary

• Problem: the message tool dropped agent-scoped media roots for runs without an agentSessionKey, and the image tool could not read iMessage attachments after 2026.2.26 because attachmentRoots never reached its local allowlist.
• Why it matters: cron/hook sessions could not send workspace files, and iMessage attachments that passed channel validation still failed image-tool local path checks.
• What changed: forward an explicit/default agent id into the message tool path, merge iMessage attachment roots into agent-scoped media roots, use those roots in the image tool, and honor wildcard local roots during local media validation.
• What did NOT change (scope boundary): no new media directories were exposed beyond the existing agent workspace and configured iMessage attachment roots.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes message tool uses default media roots instead of agent-scoped roots openclaw/openclaw#36185
• Closes Regression (2026.2.26): image tool can't read iMessage attachments — mediaLocalRoots doesn't include attachmentRoots openclaw/openclaw#30170
• Related fix(message-tool): use agent-scoped media roots for path validation openclaw/openclaw#36219
• Related fix(agents): resolve agentId unconditionally in message tool for cron/hook sessions openclaw/openclaw#36236
• Related fix(media): merge iMessage attachmentRoots into image tool local roots openclaw/openclaw#30363

User-visible / Behavior Changes

• Cron/hook-style agent runs can send files from the configured agent workspace again.
• The image tool can read iMessage attachment paths allowed by configured attachmentRoots, including wildcard roots such as /Users/*/Library/Messages/Attachments.
• CHANGELOG.md now includes entries for both fixes with thanks to @ravz, @macminikenny1, and @vincentkoc.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local pnpm workspace
• Model/provider: MiniMax image tool test fixture
• Integration/channel: message tool + iMessage attachment roots
• Relevant config (redacted): agent workspace override, channels.imessage.attachmentRoots

Steps

1. Configure an agent workspace outside the default OpenClaw media roots and run a cron/hook-style send without an agentSessionKey.
2. Configure iMessage attachmentRoots, send an attachment, and use the image tool on that local path.
3. Validate local media loading against a wildcard root such as /tmp/*/Library/Messages/Attachments.

Expected

• Workspace files are accepted by the message tool.
• iMessage attachments are accepted by the image tool.
• Wildcard local roots match local attachment paths.

Actual

• Before this change, workspace files failed with path-not-allowed, iMessage attachments were rejected by the image tool, and wildcard local roots never matched.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: targeted regression tests for message-tool agent resolution, image-tool iMessage attachment access, merged media roots, and wildcard local root validation.
• Edge cases checked: explicit agent override without session key, preserved workspace-only fs policy, wildcard root matching through the shared media loader.
• What I did not verify: end-to-end sends against a live iMessage account or a live cron/hook deployment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert the commits touching message-tool, image-tool, local-roots, and web/media.
• Files/config to restore: src/agents/tools/message-tool.ts, src/agents/openclaw-tools.ts, src/agents/tools/image-tool.ts, src/media/local-roots.ts, src/web/media.ts
• Known bad symptoms reviewers should watch for: unexpected local media allowlist expansions outside configured workspaces or iMessage attachment roots.

Risks and Mitigations

• Risk: wildcard local-root handling could over-match if non-iMessage patterns are malformed.
  • Mitigation: matching reuses the existing inbound path wildcard policy and keeps explicit-root behavior unchanged.