Summary

Add a shared tool-runtime time context/advisory helper for tools whose side effects depend on the user's local time: email, calendars, agent mailbox, send/message tools, wait/scheduler/autonomy/watch tools, and future proactive tools.

This is the implementation fan-out from #17459. The policy direction is: surface time/contact-window facts to the agent and tool result; do not silently suppress, delay, or rewrite tool calls in the control plane.

Motivation

Quiet-hours enforcement in the control plane hides important runtime facts from the agent. For time-sensitive operations the agent should see:

• current time in the user's timezone
• configured/user timezone
• whether the action appears inside a normal contact window
• advisory text when it is outside that window

The agent can then decide whether to proceed, ask for confirmation, defer, or explain urgency.

Proposed shape

Add a small shared context/helper available to tool handlers, e.g.:

ToolRuntimeTimeContext(
    now=<aware datetime>,
    user_timezone="America/Los_Angeles",
    contact_window=("08:00", "23:00"),
    within_contact_window=True | False,
    advisory="It is 02:14 in the user's timezone; this may be outside their normal contact window. Ask/consider deferring unless urgent.",
)

Tools can include the advisory in returned JSON/result text when relevant. For example:

{
  "sent": false,
  "time_context": {
    "now": "2026-04-29T02:14:00-07:00",
    "user_timezone": "America/Los_Angeles",
    "contact_window": ["08:00", "23:00"],
    "within_contact_window": false,
    "advisory": "This is outside the user's normal contact window. Consider asking or deferring unless urgent."
  }
}

Initial tool surface

• email send / mailbox tools
• calendar tools for creating/updating events or reminders
• agent mailbox / inbox/outbox style tools
• send_message / gateway delivery tools where applicable
• wait / scheduler / cron / autonomy-watch style tools

Acceptance criteria

• Shared helper resolves aware now and configured user timezone consistently.
• Time-sensitive tools can include structured time/advisory metadata in tool results.
• Outside-contact-window behavior is advisory and visible to the agent by default.
• No default hidden control-plane blocking, delaying, or suppression is introduced.
• Tests cover inside-window and outside-window behavior.
• Docs link back to Rework quiet-hours/time awareness: surface time to agent/tools, don't enforce in control plane #17459 and explain how new tools should consume the helper.

Related

Parent: #17459
Depends on/aligns with: #10421, #15872, #10061