@nightlab-agent/date-check 0.1.3 → 0.1.4

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "date-check",
       "source": "./",
       "description": "Checks the dates and times Claude Code writes into files against the real clock before the write lands.",
-      "version": "0.1.3",
+      "version": "0.1.4",
       "category": "productivity"
     }
   ],

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "date-check",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Checks the dates and times Claude Code writes into changelogs, logs, release notes and handoffs against the real clock before the write lands: a stamp in the future is refused with the real time, a stale one gets a note.",
   "homepage": "https://github.com/nightlab-agent/date-check#readme",
   "repository": "https://github.com/nightlab-agent/date-check",
@@ -39,6 +39,18 @@
       "title": "Notes on old stamps",
       "description": "Tell the agent when a stamp it adds is older than the limits above. Off: only stamps in the future are acted on.",
       "default": true
+    },
+    "promptClock": {
+      "type": "boolean",
+      "title": "The clock on every prompt",
+      "description": "Each prompt carries the local weekday, date, time and zone, and how long ago your previous message came, so Claude has the real time instead of a guess. Off: nothing is added to prompts.",
+      "default": true
+    },
+    "fill": {
+      "type": "boolean",
+      "title": "Fill placeholders",
+      "description": "Replace ⟦NOW⟧, ⟦DATE⟧, ⟦TIME⟧ and ⟦NOW-ISO⟧ in what Claude writes with the local time as the write lands, so Claude need not type the time. Off: placeholders stay as written.",
+      "default": true
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.4 (2026-11-02)
+
+- Every prompt now carries the clock, so Claude knows the time instead of guessing it: the
+  local weekday, date, time, UTC offset and zone name, and how long ago your previous message
+  came (`it is Sunday 2026-11-01 05:58 local time, UTC-05:00 (America/New_York, EST). The
+  person's previous message came 3 h 12 min ago.`). A background task's notification or
+  another plugin's prompt gets the time but does not count as your previous message. The
+  "clock on every prompt" setting turns it off. Before, Claude Code gave Claude the date only,
+  with no time and no zone.
+- Claude can leave the time to the clock: `⟦NOW⟧` (date and time), `⟦DATE⟧`, `⟦TIME⟧` or
+  `⟦NOW-ISO⟧` in what it writes (a Write or an Edit and its file name, a shell command) is replaced with the
+  machine's local time as the call lands, and Claude is told what went in. One inside
+  backticks or a code block is kept as written. The prompt clock tells Claude about `⟦NOW⟧`, `⟦DATE⟧`
+  and `⟦TIME⟧`; the "fill placeholders" setting turns them off. The names follow a request in
+  MikalaiKryvusha/KAIF#170, which found that a clock in the prompt still left an agent writing
+  the minute after.
+
 ## 0.1.3 (2026-11-01)
 
 - A new Markdown or text file whose name carries a date more than a day before today

package/README.md

@@ -3,13 +3,21 @@
 A Claude Code mod that checks the dates and times Claude writes into your files
 against the real clock, before the write lands.
 
+Install with one line at the Claude Code prompt (scopes, the shell form and npm
+are under [Install](#install)):
+
+```
+/plugin install date-check --marketplace nightlab-agent/date-check
+```
+
 Agents guess the time. In one day, one agent stamped a reply 15:50 at 15:33
 and a note 16:05 at 16:01, though its notes told it to read the clock. People
 ask for Claude to be told the time
 ([anthropics/claude-code#32913](https://github.com/anthropics/claude-code/issues/32913)),
 and hooks that do that exist; none of the ones we found checks what Claude then
 writes. A mod (a plugin that changes what Claude Code does) can read the real
-clock; this one reads it at the moment Claude writes a stamp.
+clock; this one does both: it tells Claude the time with every prompt, and it
+reads the clock again at the moment Claude writes a stamp.
 
 ![Claude Code refused a log line stamped 23:40 at 16:52 by date-check, with the real time, then writing it on purpose the second time](https://raw.githubusercontent.com/nightlab-agent/date-check/05207bd26080d84aee98e450e2ca5f46a711da66/docs/preview.png)
 
@@ -28,6 +36,33 @@ note on the old stamp gave it the real time, and it wrote the line it had held
 back as `- 02:11 release went out`. A stamp Claude guesses on its own has not
 yet been seen on a screen.
 
+![With date-check telling Claude the time on each prompt, Claude wrote a log line starting 05:54 at 05:54 without running a command, then named the day, the time zone and how long ago the previous message came](https://raw.githubusercontent.com/nightlab-agent/date-check/1f80c3f7744ebb8d6edab7dfb767d82b42cb2e5b/docs/preview-clock.png)
+
+Seen on 2026-11-01 at 05:54 EST, same terminal, with the clock on every
+prompt (new in 0.1.4). The same request as above, to
+start a log line with the current time and not run commands: this time Claude
+wrote `05:54 Release went out.` and said the time came from the session
+context. Asked what day and time it was, which zone, and how long ago the
+previous message came, it answered Sunday 1 November, 05:54, America/New_York
+on Eastern Standard Time, under a minute ago.
+
+- Each prompt carries one line Claude reads and you do not see: the local
+  weekday, date, time, UTC offset and zone name, and how long ago your
+  previous message came. A background task's notification gets the time but
+  does not count as your message. The "clock on every prompt" setting turns it off.
+- Claude can leave the time to the clock: `⟦NOW⟧` (date and time), `⟦DATE⟧`,
+  `⟦TIME⟧` or `⟦NOW-ISO⟧` in what it writes (a file and its name, an edit, a shell command)
+  is replaced with the machine's local time as the write lands, and Claude is
+  told what went in. One inside backticks or a code block is kept as written.
+  `⟦NOW⟧` has a space in it, so in a file name use `⟦DATE⟧`. The prompt clock
+  tells Claude about `⟦NOW⟧`, `⟦DATE⟧` and `⟦TIME⟧`; the "fill placeholders" setting turns them off.
+
+![Claude Code writing a log line, "06:14 The release went out.", and saying the time came from the clock](https://raw.githubusercontent.com/nightlab-agent/date-check/f2fc92e73b769c88db998d6d7078a25bbc5c5b70/docs/preview-fill.png)
+
+Seen in a preview on 2026-11-01: asked to start a log line with the exact time
+it is written, Claude wrote `06:14 The release went out.` and said the time
+was filled in from the clock as the file was written.
+
 - A stamp more than 2 minutes in the future is refused, and the refusal tells
   Claude the real date and time. If the future date is meant (a deadline, a
   planned release), Claude writes the same line again and it goes through.
@@ -86,11 +121,14 @@ year old and offered to rename it to `daily-brief-2026-11-01.md`.
 
 ## What it writes
 
-Nothing. It reads the file a Write or an Edit is about to change, to judge only the new
-lines. Nothing leaves your machine through this mod: it makes no network calls.
+No files. It adds one line beside each prompt for Claude to read (the clock, above), and it
+reads the file a Write or an Edit is about to change, to judge only the new lines. Nothing leaves your machine through this mod: it makes no network calls.
 
 ## How it works
 
+- One hook, `prompt.submit`, which Claude Code runs as each prompt enters: it reads Claude
+  Code's clock and attaches the clock line to the prompt. A failure of the mod lets the
+  prompt through unchanged.
 - One hook, `tool.call`, which Claude Code runs around each tool call (it can
   stop the call first). On Write, Edit and Bash it finds the stamps the call adds, compares
   each with Claude Code's clock, and either refuses the call with the real time

package/hooks/register.tsx

@@ -1,5 +1,5 @@
 import type { EngineInterface, Register } from 'claude-code'
-import { dateOfFile, dayOf, judge, judgeName, LIMITS, newStamps } from './stamps'
+import { clockText, dateOfFile, dayOf, fillNow, gapText, judge, judgeName, LIMITS, newStamps, unfill } from './stamps'
 import type { Limits, Verdict } from './stamps'
 
 // date-check, the hooks module. Before a Write, an Edit, or a shell command that appends to
@@ -13,8 +13,13 @@ import type { Limits, Verdict } from './stamps'
 //   on 2026-11-01) is refused once with the real date, the same way; a later day is a plan.
 // Lines the file already had are never judged: only what this call adds. Only Markdown and
 // text files (isText): a date in code is data, not a stamp.
+// And before the agent writes anything: each prompt carries the clock (promptClock), the local
+// weekday, date, time and zone, and how long ago the person's previous message came, so the
+// agent has the real time instead of a guess.
+// And so the agent need not type a time at all: ⟦NOW⟧, ⟦DATE⟧, ⟦TIME⟧ and ⟦NOW-ISO⟧ in what a
+// call writes are filled from the clock as it lands (fill; fillNow says which spellings).
 
-type Options = { aheadMinutes?: unknown; staleMinutes?: unknown; staleDays?: unknown; staleNotes?: unknown }
+type Options = { aheadMinutes?: unknown; staleMinutes?: unknown; staleDays?: unknown; staleNotes?: unknown; promptClock?: unknown; fill?: unknown }
 type Call = { tool: string; file_path?: string; content?: string; old_string?: string; new_string?: string; replace_all?: boolean; command?: string }
 
 const num = (v: unknown, d: number) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : d)
@@ -97,6 +102,31 @@ export const staleNote = (vs: Verdict[]) =>
   `date-check: ${vs.map(quote).join('; ')} ${vs.length === 1 ? 'is' : 'are'} older than now (${vs[0]!.real}). ` +
   `If ${vs.length === 1 ? 'it records' : 'they record'} something past, leave ${vs.length === 1 ? 'it' : 'them'}; if ${vs.length === 1 ? 'it was' : 'they were'} meant as now, correct ${vs.length === 1 ? 'it' : 'them'}.`
 
+/** Prompts the person sent: typed, from Remote Control or Slack, or the SDK host's own turn. */
+const PERSON = new Set(['composer', 'bridge', 'slack-ping', 'sdk'])
+
+export const clockLine = (now: number, since?: number, fill = true) =>
+  `date-check: it is ${clockText(now)}.` +
+  (since === undefined ? '' : ` The person's previous message came ${gapText(now - since)} ago.`) +
+  (fill ? ' To record the moment a file is written, write ⟦NOW⟧ (date and time), ⟦DATE⟧ (also in a file name) or ⟦TIME⟧: the clock fills it in as the write lands.' : '')
+
+/** The call with its placeholders filled from the clock (the text it writes, and a Write's or Edit's file path), and which ones were. */
+const filledCall = (x: Call, now: number): { call: Call; filled: string[] } => {
+  const key = x.tool === 'Write' ? 'content' : x.tool === 'Edit' ? 'new_string' : 'command'
+  const call: Call = { ...x }
+  const filled = new Set<string>()
+  const v = x[key]
+  if (typeof v === 'string' && v.includes('⟦')) {
+    const f = fillNow(v, now, x.tool !== 'Bash')
+    if (f.filled.length) { call[key] = f.text; f.filled.forEach(t => filled.add(t)) }
+  }
+  if (x.tool !== 'Bash' && x.file_path?.includes('⟦')) {
+    const f = fillNow(x.file_path, now, false)
+    if (f.filled.length) { call.file_path = f.text; f.filled.forEach(t => filled.add(t)) }
+  }
+  return filled.size ? { call, filled: [...filled] } : { call: x, filled: [] }
+}
+
 export const register: Register = (on, options: Options = {}) => {
   const limits: Limits = {
     aheadMinutes: num(options.aheadMinutes, LIMITS.aheadMinutes),
@@ -104,16 +134,59 @@ export const register: Register = (on, options: Options = {}) => {
     staleDays: num(options.staleDays, LIMITS.staleDays),
   }
   const notes = options.staleNotes !== false
+  const fill = options.fill !== false
   // A future stamp refused once, by file and line: written again after that refusal, it is
   // meant. Each refusal and each call's start take a number in order, so a call that began
   // before the refusal (two calls at once) is refused too.
   const meant = new Map<string, number>()
   let order = 0
 
+  if (options.promptClock !== false) {
+    // The person's prompts in the order they entered, each with its clock reading once it
+    // came back. A prompt measures its gap from the latest earlier one: not from a later one
+    // whose reading came back first (two at once), and not from one dropped beneath.
+    const sent: { at?: number; dropped?: boolean }[] = []
+    on('prompt.submit', async ($, e, next) => {
+      const me = PERSON.has(e.origin?.kind) ? { at: undefined as number | undefined, dropped: false } : undefined
+      const earlier = sent.slice()
+      if (me) sent.push(me)
+      if (sent.length > 50) sent.splice(0, sent.length - 50)
+      let line: string | undefined
+      try {
+        const now = await $.clock.now()
+        let since: number | undefined
+        if (me) {
+          const before = earlier.filter(x => !x.dropped)
+          // One still waiting for its reading entered with this one: under a minute.
+          since = before.some(x => x.at === undefined) ? now : before.length ? Math.max(...before.map(x => x.at!)) : undefined
+          me.at = now
+        }
+        line = clockLine(now, since, fill)
+      } catch {
+        // A failure of this mod never stops the prompt; a prompt with no reading is no one's previous one.
+        if (me) me.dropped = true
+      }
+      const done = await next(line ? { ...e, context: [...(e.context ?? []), line] } : e)
+      if (me && done.drop !== undefined) me.dropped = true
+      return done
+    })
+  }
+
   on('tool.call', async ($, e, next) => {
-    const x = e as unknown as Call
+    let x = e as unknown as Call
     if (x.tool !== 'Write' && x.tool !== 'Edit' && x.tool !== 'Bash') return next(e)
     const began = ++order
+    let filled: string[] = []
+    if (fill) {
+      try {
+        const f = filledCall(x, await $.clock.now())
+        x = f.call
+        filled = f.filled
+      } catch {
+        // No reading: the call goes on as written.
+      }
+    }
+    const sent = (filled.length ? { ...e, ...x } : e) as typeof e
     let verdicts: Verdict[] = []
     let name: ReturnType<typeof judgeName>
     let file = ''
@@ -132,7 +205,8 @@ export const register: Register = (on, options: Options = {}) => {
       verdicts = []
       name = undefined
     }
-    const key = (v: Verdict) => `${file}\n${v.stamp.line}`
+    // Keyed by the line as the agent wrote it, so a retry with the same placeholder a minute later is the same line.
+    const key = (v: Verdict) => `${file}\n${unfill(v.stamp.line, filled)}`
     const future = verdicts.filter(v => v.kind === 'future')
     const fresh = future.filter(v => !((meant.get(key(v)) ?? Infinity) < began))
     // By the file's name alone, so a retry spelled another way (relative, absolute) is the same file.
@@ -145,9 +219,10 @@ export const register: Register = (on, options: Options = {}) => {
       if (freshName) mark(nameKey)
       return { deny: [...(freshName ? [nameRefusal(file, freshName)] : []), ...(fresh.length ? [refusal(fresh)] : [])].join('\n') }
     }
-    const done = await next(e)
+    const done = await next(sent)
     if (done.deny !== undefined || done.isError) return done
     const said = [
+      ...(filled.length ? [`date-check: filled from the clock: ${filled.join(', ')}.`] : []),
       ...(name ? [`date-check: kept the date ${name.date} in the new file's name as written the second time.`] : []),
       ...(future.length ? [`date-check: kept ${future.map(v => `"${v.stamp.text}"`).join(', ')} as written the second time (a date in the future on purpose).`] : []),
       ...(notes && verdicts.some(v => v.kind === 'stale') ? [staleNote(verdicts.filter(v => v.kind === 'stale'))] : []),

package/hooks/stamps.ts

@@ -164,6 +164,76 @@ export const nowText = (ms: number) => {
   return `${dayOf(ms)} ${pad(d.getHours())}:${pad(d.getMinutes())} local time, ${zone}`
 }
 
+/**
+ * Placeholders the agent writes instead of typing a time, filled from the clock as the call
+ * lands: `⟦NOW⟧` 2026-11-01 06:20, `⟦DATE⟧` 2026-11-01, `⟦TIME⟧` 06:20, `⟦NOW-ISO⟧`
+ * 2026-11-01T06:20:41-05:00, all local. One in code is kept as written (a README that shows
+ * the placeholder): a code span, a ``` or ~~~ fence (closed by the same mark, as long or
+ * longer), and, in a file (`indented`), an indented code line, as the judge reads code.
+ * Exactly these spellings: `⟦now⟧`, `[NOW]` and `⟦NOW ⟧` are text. ⟦NOW⟧ has a space in
+ * it: in a file name or an unquoted shell word, ⟦DATE⟧ is the one to use.
+ */
+export const fillNow = (text: string, ms: number, indented = true): { text: string; filled: string[] } => {
+  const d = new Date(ms)
+  const o = -d.getTimezoneOffset()
+  const time = `${pad(d.getHours())}:${pad(d.getMinutes())}`
+  const iso = `${dayOf(ms)}T${time}:${pad(d.getSeconds())}${o < 0 ? '-' : '+'}${pad(Math.floor(Math.abs(o) / 60))}:${pad(Math.abs(o) % 60)}`
+  const value: Record<string, string> = { 'NOW-ISO': iso, NOW: `${dayOf(ms)} ${time}`, DATE: dayOf(ms), TIME: time }
+  const filled = new Set<string>()
+  let fence: string | undefined
+  const lines = text.split('\n').map(line => {
+    const mark = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1]
+    if (fence !== undefined) {
+      if (mark && mark[0] === fence[0] && mark.length >= fence.length && /^ {0,3}[`~]+\s*$/.test(line)) fence = undefined
+      return line
+    }
+    if (mark && !(mark[0] === '`' && line.slice(line.indexOf(mark) + mark.length).includes('`'))) { fence = mark; return line }
+    if (indented && indentedCode(line)) return line
+    return line.replace(/(?<!`)(`+)(?!`)[^]*?(?<!`)\1(?!`)|⟦(NOW-ISO|NOW|DATE|TIME)⟧/g, (m, code: string | undefined, tok: string | undefined) => {
+      if (code !== undefined || !tok) return m
+      filled.add(`⟦${tok}⟧ ${value[tok]}`)
+      return value[tok]!
+    })
+  })
+  return { text: lines.join('\n'), filled: [...filled] }
+}
+
+/** A line as written before filling: each filled value back to its placeholder, longest first. */
+export const unfill = (line: string, filled: string[]) =>
+  filled.map(f => [f.slice(0, f.indexOf('⟧') + 1), f.slice(f.indexOf('⟧') + 2)] as const)
+    .sort((x, y) => y[1].length - x[1].length)
+    .reduce((l, [tok, v]) => l.split(v).join(tok), line)
+
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+/** The zone's name where the runtime knows it (`America/New_York, EST`); '' where it does not. */
+const zoneName = (ms: number) => {
+  try {
+    const iana = Intl.DateTimeFormat().resolvedOptions().timeZone
+    const short = new Intl.DateTimeFormat('en-US', { timeZoneName: 'short' }).formatToParts(new Date(ms)).find(p => p.type === 'timeZoneName')?.value
+    return [...new Set([iana, short && !/^GMT[+-]/.test(short) ? short : ''].filter(Boolean))].join(', ')
+  } catch {
+    return ''
+  }
+}
+/**
+ * The clock a prompt carries: weekday, date, local time and offset, and the zone's name:
+ * `Sunday 2026-11-01 05:58 local time, UTC-05:00 (America/New_York, EST)`.
+ */
+export const clockText = (ms: number) => {
+  const name = zoneName(ms)
+  return `${DAYS[new Date(ms).getDay()]} ${nowText(ms)}${name ? ` (${name})` : ''}`
+}
+/** A span of time as a person says it: `under a minute`, `12 min`, `3 h 5 min`, `2 days 4 h`. */
+export const gapText = (ms: number) => {
+  const m = Math.floor(Math.max(0, ms) / 60000)
+  if (m < 1) return 'under a minute'
+  if (m < 60) return `${m} min`
+  const h = Math.floor(m / 60)
+  if (h < 24) return m % 60 ? `${h} h ${m % 60} min` : `${h} h`
+  const d = Math.floor(h / 24)
+  return `${d} day${d === 1 ? '' : 's'}${h % 24 ? ` ${h % 24} h` : ''}`
+}
+
 /** The local zone's UTC offset in minutes at a moment (New York in winter: -300). */
 export type ZoneAt = (ms: number) => number
 const localZone: ZoneAt = ms => -new Date(ms).getTimezoneOffset()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlab-agent/date-check",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Claude Code mod: checks the dates and times Claude Code writes into changelogs, logs, release notes and handoffs against the real clock before the write lands; a stamp in the future is refused with the real time.",
   "keywords": [
     "claude-code",