feat(date-time): standardize time context and tool timestamps

docs/channels/discord.md

@@ -363,6 +363,7 @@ The agent can call `discord` with actions like:
 - `react` / `reactions` (add or list reactions)
 - `sticker`, `poll`, `permissions`
 - `readMessages`, `sendMessage`, `editMessage`, `deleteMessage`
+- Read/search/pin tool payloads include normalized `timestampMs` (UTC epoch ms) and `timestampUtc` alongside raw Discord `timestamp`.
 - `threadCreate`, `threadList`, `threadReply`
 - `pinMessage`, `unpinMessage`, `listPins`
 - `searchMessages`, `memberInfo`, `roleInfo`, `roleAdd`, `roleRemove`, `emojiList`

docs/channels/slack.md

@@ -327,4 +327,5 @@ Slack tool actions can be gated with `channels.slack.actions.*`:
 - Bot-authored messages are ignored by default; enable via `channels.slack.allowBots` or `channels.slack.channels.<id>.allowBots`.
 - Warning: If you allow replies to other bots (`channels.slack.allowBots=true` or `channels.slack.channels.<id>.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.slack.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
 - For the Slack tool, reaction removal semantics are in [/tools/reactions](/tools/reactions).
+- Read/pin tool payloads include normalized `timestampMs` (UTC epoch ms) and `timestampUtc` alongside raw Slack `ts`.
 - Attachments are downloaded to the media store when permitted and under the size limit.

docs/concepts/system-prompt.md

@@ -20,7 +20,7 @@ The prompt is intentionally compact and uses fixed sections:
 - **Workspace**: working directory (`agents.defaults.workspace`).
 - **Workspace Files (injected)**: indicates bootstrap files are included below.
 - **Sandbox** (when enabled): indicates sandboxed runtime, sandbox paths, and whether elevated exec is available.
-- **Time**: UTC default + the user’s local time (already converted).
+- **Current Date & Time**: user-local time, timezone, and time format.
 - **Reply Tags**: optional reply tag syntax for supported providers.
 - **Heartbeats**: heartbeat prompt and ack behavior.
 - **Runtime**: host, OS, node, model, thinking level (one line).
@@ -46,12 +46,19 @@ To inspect how much each injected file contributes (raw vs injected, truncation,
 
 ## Time handling
 
-The Time line is compact and explicit:
+The system prompt includes a dedicated **Current Date & Time** section when user
+time or timezone is known. It is explicit about:
 
-- Assume timestamps are **UTC** unless stated.
-- The listed **user time** is already converted to `agents.defaults.userTimezone` (if set).
+- The user’s **local time** (already converted).
+- The **time zone** used for the conversion.
+- The **time format** (12-hour / 24-hour).
 
-Use `agents.defaults.userTimezone` in `~/.clawdbot/clawdbot.json` to change the user time zone.
+Configure with:
+
+- `agents.defaults.userTimezone`
+- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
+
+See [Date & Time](/date-time) for full behavior details.
 
 ## Skills
 

docs/concepts/timezone.md

@@ -19,10 +19,15 @@ Inbound messages are wrapped in an envelope like:
 
 The timestamp in the envelope is **always UTC**, with minutes precision.
 
-## Tool payloads (raw provider data)
+## Tool payloads (raw provider data + normalized fields)
 
 Tool calls (`channels.discord.readMessages`, `channels.slack.readMessages`, etc.) return **raw provider timestamps**.
-These are typically UTC ISO strings (Discord) or UTC epoch strings (Slack). We do not rewrite them.
+We also attach normalized fields for consistency:
+
+- `timestampMs` (UTC epoch milliseconds)
+- `timestampUtc` (ISO 8601 UTC string)
+
+Raw provider fields are preserved.
 
 ## User timezone for the system prompt
 
@@ -31,10 +36,14 @@ unset, Clawdbot resolves the **host timezone at runtime** (no config write).
 
 ```json5
 {
-  agent: { userTimezone: "America/Chicago" }
+  agents: { defaults: { userTimezone: "America/Chicago" } }
 }
 ```
 
 The system prompt includes:
-- `User timezone: America/Chicago`
-- `Current user time: 2026-01-05 15:26`
+- `Current Date & Time` section with local time and timezone
+- `Time format: 12-hour` or `24-hour`
+
+You can control the prompt format with `agents.defaults.timeFormat` (`auto` | `12` | `24`).
+
+See [Date & Time](/date-time) for the full behavior and examples.

docs/date-time.md

@@ -0,0 +1,85 @@
+---
+summary: "Date and time handling across envelopes, prompts, tools, and connectors"
+read_when:
+  - You are changing how timestamps are shown to the model or users
+  - You are debugging time formatting in messages or system prompt output
+---
+
+# Date & Time
+
+Clawdbot uses **UTC for transport timestamps** and **user-local time only in the system prompt**.
+We avoid rewriting provider timestamps so tools keep their native semantics.
+
+## Message envelopes (UTC)
+
+Inbound messages are wrapped with a UTC timestamp (minute precision):
+
+```
+[Provider ... 2026-01-05T21:26Z] message text
+```
+
+This envelope timestamp is **always UTC**, regardless of the host timezone.
+
+## System prompt: Current Date & Time
+
+If the user timezone or local time is known, the system prompt includes a dedicated
+**Current Date & Time** section:
+
+```
+Thursday, January 15th, 2026 — 3:07 PM (America/Chicago)
+Time format: 12-hour
+```
+
+If only the timezone is known, we still include the section and instruct the model
+to assume UTC for unknown time references.
+
+## System event lines (UTC)
+
+Queued system events inserted into agent context are prefixed with a UTC timestamp:
+
+```
+System: [2026-01-12T20:19:17Z] Model switched.
+```
+
+### Configure user timezone + format
+
+```json5
+{
+  agents: {
+    defaults: {
+      userTimezone: "America/Chicago",
+      timeFormat: "auto" // auto | 12 | 24
+    }
+  }
+}
+```
+
+- `userTimezone` sets the **user-local timezone** for prompt context.
+- `timeFormat` controls **12h/24h display** in the prompt. `auto` follows OS prefs.
+
+## Time format detection (auto)
+
+When `timeFormat: "auto"`, Clawdbot inspects the OS preference (macOS/Windows)
+and falls back to locale formatting. The detected value is **cached per process**
+to avoid repeated system calls.
+
+## Tool payloads + connectors (raw provider time + normalized fields)
+
+Channel tools return **provider-native timestamps** and add normalized fields for consistency:
+
+- `timestampMs`: epoch milliseconds (UTC)
+- `timestampUtc`: ISO 8601 UTC string
+
+Raw provider fields are preserved so nothing is lost.
+
+- Slack: epoch-like strings from the API
+- Discord: UTC ISO timestamps
+- Telegram/WhatsApp: provider-specific numeric/ISO timestamps
+
+If you need local time, convert it downstream using the known timezone.
+
+## Related docs
+
+- [System Prompt](/concepts/system-prompt)
+- [Timezones](/concepts/timezone)
+- [Messages](/concepts/messages)

docs/gateway/configuration.md

@@ -1211,6 +1211,17 @@ message envelopes). If unset, Clawdbot uses the host timezone at runtime.
 }
 ```
 
+### `agents.defaults.timeFormat`
+
+Controls the **time format** shown in the system prompt’s Current Date & Time section.
+Default: `auto` (OS preference).
+
+```json5
+{
+  agents: { defaults: { timeFormat: "auto" } } // auto | 12 | 24
+}
+```
+
 ### `messages`
 
 Controls inbound/outbound prefixes and optional ack reactions.