@raidiant/notifai 1.1.0 → 2.0.1

package/src/client.test.ts

@@ -80,6 +80,59 @@ describe('a server that never answers', () => {
     expect(result.replies).toEqual([])
   })
 
+  it('puts and fetches Agent Acknowledgements on the encoded request path', async () => {
+    const seen: { method?: string; url?: string; body?: unknown }[] = []
+    const baseUrl = await serving((request, response) => {
+      let raw = ''
+      request.on('data', (chunk) => {
+        raw += String(chunk)
+      })
+      request.on('end', () => {
+        seen.push({
+          method: request.method,
+          url: request.url,
+          ...(raw === '' ? {} : { body: JSON.parse(raw) as unknown }),
+        })
+        response.setHeader('content-type', 'application/json')
+        if (request.method === 'PUT') {
+          response.end(
+            JSON.stringify({
+              status: 'recorded',
+              agent_acknowledgement: {
+                text: 'I will deploy.',
+                created_at: '2026-08-13T12:01:00.000Z',
+              },
+            }),
+          )
+        } else {
+          response.end(
+            JSON.stringify({
+              request_id: 'req/encoded',
+              agent_acknowledgement_required: true,
+              agent_acknowledgement: null,
+            }),
+          )
+        }
+      })
+    })
+    const client = createClient(baseUrl, 'Bearer test')
+
+    await client.putAgentAcknowledgement('req/encoded', { text: 'I will deploy.' })
+    await client.agentAcknowledgement('req/encoded', { waitSeconds: 25 })
+
+    expect(seen).toEqual([
+      {
+        method: 'PUT',
+        url: '/api/v1/notifications/req%2Fencoded/agent-acknowledgement',
+        body: { text: 'I will deploy.' },
+      },
+      {
+        method: 'GET',
+        url: '/api/v1/notifications/req%2Fencoded/agent-acknowledgement?wait_seconds=25',
+      },
+    ])
+  })
+
   it('treats a truncated body as a transport failure, not a crash', async () => {
     // A body that stops mid-JSON used to escape as a raw parse error outside
     // the retry path, so nothing backed off and retried it.

package/src/client.ts

@@ -6,10 +6,13 @@ import type {
   CreateMediaUploadRequestT,
   CreateMediaUploadResponse,
   EvidenceSnapshot,
+  GetAgentAcknowledgementResponse,
   ListDevicesResponse,
   ListRepliesResponse,
   Platform,
   PollPairingResponse,
+  PutAgentAcknowledgementRequestT,
+  PutAgentAcknowledgementResponse,
   SubmissionReceipt,
   SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
@@ -72,6 +75,14 @@ export interface ApiClient {
   ): Promise<ListRepliesResponse>
   /** Retire a question and return the replies committed before the close fence. */
   closeReplies(requestId: string): Promise<ListRepliesResponse>
+  putAgentAcknowledgement(
+    requestId: string,
+    body: PutAgentAcknowledgementRequestT,
+  ): Promise<PutAgentAcknowledgementResponse>
+  agentAcknowledgement(
+    requestId: string,
+    options: { waitSeconds: number },
+  ): Promise<GetAgentAcknowledgementResponse>
   createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>
   uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>
   health(): Promise<boolean>
@@ -223,6 +234,19 @@ export function createClient(
         'POST',
         `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`,
       ),
+    putAgentAcknowledgement: (requestId, body) =>
+      call<PutAgentAcknowledgementResponse>(
+        'PUT',
+        `/api/v1/notifications/${encodeURIComponent(requestId)}/agent-acknowledgement`,
+        body,
+      ),
+    agentAcknowledgement: (requestId, { waitSeconds }) =>
+      call<GetAgentAcknowledgementResponse>(
+        'GET',
+        `/api/v1/notifications/${encodeURIComponent(requestId)}/agent-acknowledgement?wait_seconds=${waitSeconds}`,
+        undefined,
+        waitSeconds,
+      ),
     createMediaUpload: (body) => call('POST', '/api/v1/media', body),
     uploadMedia: async (grant, bytes) => {
       let response: Response

package/src/commands.test.ts

@@ -23,11 +23,13 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { ApiCallError, NetworkError, type ApiClient } from './client.js'
 import type { ClaudeWakeAdapters } from './claude-wake.js'
 import {
+  acknowledgeCommand,
   askCommand,
   accessStatusCommand,
   buildQuestions,
   assessReadiness,
   capabilitiesCommand,
+  closeCommand,
   configExplainCommand,
   configSetCommand,
   configShowCommand,
@@ -257,6 +259,8 @@ function isolatedEnv(cwd: string): NodeJS.ProcessEnv {
 
 const receipt: SubmissionReceipt = {
   request_id: 'req_reply_test',
+  reply_expires_at: '2026-08-02T18:00:00.000Z',
+  agent_acknowledgement_required: true,
   replayed: false,
   overall: 'provider_accepted_all',
   deliveries: [
@@ -285,10 +289,18 @@ const reply: ReplyView = {
   created_at: '2026-08-01T18:01:00.000Z',
 }
 
-function replyResponse(replies: ReplyView[] = []): ListRepliesResponse {
+function replyResponse(
+  replies: ReplyView[] = [],
+  options: {
+    required?: boolean
+    acknowledgement?: ListRepliesResponse['agent_acknowledgement']
+  } = {},
+): ListRepliesResponse {
   return {
     request_id: receipt.request_id,
     reply_expires_at: '2026-08-02T18:00:00.000Z',
+    agent_acknowledgement_required: options.required ?? true,
+    agent_acknowledgement: options.acknowledgement ?? null,
     replies,
   }
 }
@@ -635,7 +647,11 @@ describe('command contracts', () => {
     ).toBe(EXIT.ok)
     expect(polls).toHaveLength(3)
     expect(polls.every((poll) => poll.waitSeconds <= 25)).toBe(true)
-    expect(io.outLines.at(-1)).toBe('reply from iPhone: yes, after the migration')
+    expect(io.outLines).toContain('reply from iPhone: yes, after the migration')
+    expect(io.outLines).toContain('Agent Acknowledgement required.')
+    expect(io.outLines.join('\n')).toContain(
+      `notifai acknowledge ${receipt.request_id} --text <text>`,
+    )
     const received = readLogRecords(deps.env, { event: ['reply.received'] }).records
     expect(received).toHaveLength(1)
     expect(received[0]?.data).toMatchObject({
@@ -718,7 +734,11 @@ describe('command contracts', () => {
       }),
     ).toBe(EXIT.ok)
     expect(replyCalls).toBe(3)
-    expect(io.outLines.at(-1)).toBe('reply from iPhone: yes, after the migration')
+    expect(io.outLines).toContain('reply from iPhone: yes, after the migration')
+    expect(io.outLines).toContain('Agent Acknowledgement required.')
+    expect(io.outLines.join('\n')).toContain(
+      `notifai acknowledge ${receipt.request_id} --text <text>`,
+    )
     expect(io.errLines.join('\n')).not.toContain('internal_error')
   })
 
@@ -799,9 +819,14 @@ describe('command contracts', () => {
     expect(JSON.parse(io.outLines[1] ?? '{}')).toEqual({
       type: 'reply_result',
       request_id: receipt.request_id,
+      reply_expires_at: '2026-08-02T18:00:00.000Z',
       replies: [],
+      agent_acknowledgement_required: true,
+      agent_acknowledgement: null,
+      acknowledgement_command: null,
       degraded: false,
     })
+    expect(io.outLines).not.toContain('Agent Acknowledgement required.')
     expect(io.errLines.join('\n')).toContain(`notifai replies ${receipt.request_id}`)
     expect(io.errLines.join('\n')).toContain(`notifai close ${receipt.request_id}`)
   })
@@ -827,11 +852,227 @@ describe('command contracts', () => {
     expect(JSON.parse(io.outLines[1] ?? '{}')).toEqual({
       type: 'reply_result',
       request_id: receipt.request_id,
+      reply_expires_at: '2026-08-02T18:00:00.000Z',
       replies: [reply],
+      agent_acknowledgement_required: true,
+      agent_acknowledgement: null,
+      acknowledgement_command: `notifai acknowledge ${receipt.request_id} --text <text>`,
       degraded: false,
     })
   })
 
+  it('acknowledges non-interactively, trims text, emits JSON, and logs request identity', async () => {
+    const io = new CapturedIo()
+    let submitted: { requestId: string; text: string } | undefined
+    const client = {
+      putAgentAcknowledgement: async (requestId: string, body: { text: string }) => {
+        submitted = { requestId, text: body.text }
+        return {
+          status: 'recorded' as const,
+          agent_acknowledgement: {
+            text: body.text,
+            created_at: '2026-08-13T12:01:00.000Z',
+          },
+        }
+      },
+    } as unknown as ApiClient
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-acknowledge-log-'))
+    const deps = makeDeps(io, client)
+    deps.env = {
+      XDG_CONFIG_HOME: path.join(root, 'config'),
+      XDG_STATE_HOME: path.join(root, 'state'),
+    }
+    deps.logger = createLogger({ env: deps.env, cmd: 'acknowledge' })
+
+    expect(
+      await acknowledgeCommand(deps, receipt.request_id, {
+        text: '  I will deploy staging now.  ',
+        json: true,
+      }),
+    ).toBe(EXIT.ok)
+    expect(submitted).toEqual({
+      requestId: receipt.request_id,
+      text: 'I will deploy staging now.',
+    })
+    expect(JSON.parse(io.outLines[0] ?? '{}')).toEqual({
+      request_id: receipt.request_id,
+      outcome: 'recorded',
+      acknowledgement: {
+        text: 'I will deploy staging now.',
+        created_at: '2026-08-13T12:01:00.000Z',
+      },
+      agent_acknowledgement_required: true,
+    })
+    const events = readLogRecords(deps.env, {
+      request: receipt.request_id,
+      event: ['acknowledgement.attempted', 'acknowledgement.outcome'],
+    }).records
+    expect(events.map((event) => event.event)).toEqual([
+      'acknowledgement.attempted',
+      'acknowledgement.outcome',
+    ])
+  })
+
+  it('clears a matching active-session obligation after acknowledgement success', async () => {
+    const io = new CapturedIo()
+    const client = {
+      putAgentAcknowledgement: async () => ({
+        status: 'recorded' as const,
+        agent_acknowledgement: {
+          text: 'I will deploy staging now.',
+          created_at: '2026-08-13T12:01:00.000Z',
+        },
+      }),
+    } as unknown as ApiClient
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-ack-clear-'))
+    const deps = makeDeps(io, client)
+    deps.env = {
+      XDG_CONFIG_HOME: path.join(root, 'config'),
+      XDG_STATE_HOME: path.join(root, 'state'),
+    }
+    const now = 1_800_000_000_000
+    deps.now = () => now
+    writeSessionState('ack-session', deps.env, {
+      acknowledgement_due: [{ request_id: receipt.request_id, recorded_at: now }],
+    })
+    writeProjectSession(deps.cwd, deps.env, 'ack-session', now, 'codex')
+
+    expect(
+      await acknowledgeCommand(deps, receipt.request_id, {
+        text: 'I will deploy staging now.',
+      }),
+    ).toBe(EXIT.ok)
+    expect(readSessionState('ack-session', deps.env).acknowledgement_due).toBeUndefined()
+  })
+
+  it('reports idempotent acknowledgement replay in concise human output', async () => {
+    const io = new CapturedIo()
+    const client = {
+      putAgentAcknowledgement: async () => ({
+        status: 'replayed' as const,
+        agent_acknowledgement: {
+          text: 'I will deploy staging now.',
+          created_at: '2026-08-13T12:01:00.000Z',
+        },
+      }),
+    } as unknown as ApiClient
+
+    expect(
+      await acknowledgeCommand(makeDeps(io, client), receipt.request_id, {
+        text: 'I will deploy staging now.',
+      }),
+    ).toBe(EXIT.ok)
+    expect(io.outLines).toEqual([
+      `Agent Acknowledgement replayed for ${receipt.request_id} at 2026-08-13T12:01:00.000Z.`,
+    ])
+  })
+
+  it.each([
+    { text: undefined, message: '--text is required' },
+    { text: '   ', message: '--text is required' },
+    { text: 'x'.repeat(1001), message: 'at most 1000 characters' },
+  ])('rejects invalid acknowledgement text before network: $message', async ({ text, message }) => {
+    const io = new CapturedIo()
+    let calls = 0
+    const client = {
+      putAgentAcknowledgement: async () => {
+        calls += 1
+        throw new Error('should not be reached')
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await acknowledgeCommand(makeDeps(io, client), receipt.request_id, { text }),
+    ).toBe(EXIT.usage)
+    expect(calls).toBe(0)
+    expect(io.errLines.join('\n')).toContain(message)
+  })
+
+  it.each([
+    [new ApiCallError(409, 'conflict', 'A different acknowledgement is already recorded.'), EXIT.failed, 'conflict'],
+    [new ApiCallError(409, 'reply_not_enabled', 'Agent Acknowledgements are disabled.'), EXIT.failed, 'reply_not_enabled'],
+    [new ApiCallError(409, 'conflict', 'No user reply has been recorded yet.'), EXIT.failed, 'No user reply'],
+    [new ApiCallError(404, 'not_found', 'This request is unavailable or its content was purged.'), EXIT.failed, 'purged'],
+    [new ApiCallError(401, 'machine_revoked', 'This machine was revoked.'), EXIT.auth, 'machine_revoked'],
+    [new NetworkError('Could not reach the service'), EXIT.network, 'Could not reach'],
+  ] as const)(
+    'maps stable acknowledgement failure %#',
+    async (error, expectedExit, expectedCopy) => {
+      const io = new CapturedIo()
+      const client = {
+        putAgentAcknowledgement: async () => {
+          throw error
+        },
+      } as unknown as ApiClient
+
+      expect(
+        await acknowledgeCommand(makeDeps(io, client), receipt.request_id, { text: 'Next work.' }),
+      ).toBe(expectedExit)
+      expect(io.errLines.join('\n')).toContain(expectedCopy)
+    },
+  )
+
+  it('reports required-but-not-yet-due state before any user reply', async () => {
+    const io = new CapturedIo()
+    const client = {
+      replies: async () => replyResponse([]),
+    } as unknown as ApiClient
+
+    expect(await repliesCommand(makeDeps(io, client), receipt.request_id, {})).toBe(EXIT.noReply)
+    expect(io.outLines).toContain(
+      'Agent Acknowledgement: required after a user reply; no reply is recorded yet.',
+    )
+    expect(io.outLines.join('\n')).not.toContain('notifai acknowledge')
+  })
+
+  it('exposes disabled acknowledgement state without a follow-up command', async () => {
+    const io = new CapturedIo()
+    const client = {
+      replies: async () => replyResponse([reply], { required: false }),
+    } as unknown as ApiClient
+
+    expect(await repliesCommand(makeDeps(io, client), receipt.request_id, {})).toBe(EXIT.ok)
+    expect(io.outLines).toContain('Agent Acknowledgement: not required for this request.')
+    expect(io.outLines.join('\n')).not.toContain('notifai acknowledge')
+  })
+
+  it('exposes an existing acknowledgement without repeating the follow-up command', async () => {
+    const io = new CapturedIo()
+    const acknowledgement = {
+      text: 'I will deploy staging now.',
+      created_at: '2026-08-13T12:01:00.000Z',
+    }
+    const client = {
+      replies: async () => replyResponse([reply], { acknowledgement }),
+    } as unknown as ApiClient
+
+    expect(
+      await repliesCommand(makeDeps(io, client), receipt.request_id, { json: true }),
+    ).toBe(EXIT.ok)
+    expect(JSON.parse(io.outLines[0] ?? '{}')).toMatchObject({
+      agent_acknowledgement_required: true,
+      agent_acknowledgement: acknowledgement,
+      acknowledgement_command: null,
+    })
+  })
+
+  it('close exposes the acknowledgement requirement and exact follow-up command', async () => {
+    const io = new CapturedIo()
+    const client = {
+      closeReplies: async () => replyResponse([reply]),
+    } as unknown as ApiClient
+
+    expect(await closeCommand(makeDeps(io, client), receipt.request_id, { json: true })).toBe(
+      EXIT.ok,
+    )
+    expect(JSON.parse(io.outLines[0] ?? '{}')).toMatchObject({
+      request_id: receipt.request_id,
+      agent_acknowledgement_required: true,
+      agent_acknowledgement: null,
+      acknowledgement_command: `notifai acknowledge ${receipt.request_id} --text <text>`,
+    })
+  })
+
   it('passes the replies cursor and prints replies for later retrieval', async () => {
     const io = new CapturedIo()
     let requested: { waitSeconds: number; afterSeq: number } | undefined
@@ -851,7 +1092,11 @@ describe('command contracts', () => {
 
     expect(await repliesCommand(deps, receipt.request_id, { after: 7 })).toBe(EXIT.ok)
     expect(requested).toEqual({ waitSeconds: 0, afterSeq: 7 })
-    expect(io.outLines).toEqual(['reply from iPhone: yes, after the migration'])
+    expect(io.outLines).toEqual([
+      'reply from iPhone: yes, after the migration',
+      'Agent Acknowledgement required.',
+      `next: Run \`notifai acknowledge ${receipt.request_id} --text <text>\` with concrete text saying what you will do because of the reply.`,
+    ])
     expect(readLogRecords(deps.env, { event: ['reply.received'] }).records).toHaveLength(1)
   })
 
@@ -876,6 +1121,8 @@ describe('command contracts', () => {
     expect(io.outLines).toEqual([
       `pending request ${receipt.request_id}`,
       'reply from iPhone: yes, after the migration',
+      'Agent Acknowledgement required.',
+      `next: Run \`notifai acknowledge ${receipt.request_id} --text <text>\` with concrete text saying what you will do because of the reply.`,
     ])
   })
 
@@ -2156,7 +2403,7 @@ describe('init', () => {
     platform: 'ios' as const,
     permission_status: 'authorized',
     registration_healthy: true,
-    reply_protocol_version: 1,
+    reply_protocol_version: 2,
     last_seen_at: '2026-08-05T18:00:00.000Z',
   }
 

package/src/commands.ts

@@ -4,6 +4,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
 import {
+  AGENT_ACKNOWLEDGEMENT_MAX_LENGTH,
   CAPABILITIES_V1,
   QUESTION_TEXT_MAX_LENGTH,
   REPLY_MAX_QUESTIONS,
@@ -65,6 +66,7 @@ import {
 import type { Tone } from './ui/theme.js'
 import {
   WAITER_CEILING_SECONDS,
+  clearAcknowledgementObligation,
   handleSessionEnd,
   handleStop,
   handleUserPromptSubmit,
@@ -685,6 +687,7 @@ export async function sendCommand(
     title: flags.title,
     overall: receipt.overall,
     replayed: receipt.replayed,
+    agent_acknowledgement_required: receipt.agent_acknowledgement_required,
     deliveries: receipt.deliveries.length,
     wait_seconds: waitSeconds,
     exit: receiptExit,
@@ -715,6 +718,9 @@ export async function sendCommand(
               type: 'reply_result',
               request_id: receipt.request_id,
               replies: [],
+              agent_acknowledgement_required: receipt.agent_acknowledgement_required,
+              agent_acknowledgement: null,
+              acknowledgement_command: null,
               degraded: false,
             })
           : JSON.stringify(receipt, null, 2),
@@ -733,15 +739,15 @@ export async function sendCommand(
     recordReplies(deps, receipt.request_id, result.response.replies)
     if (flags.json) {
       deps.io.out(
-        JSON.stringify({
-          type: 'reply_result',
-          request_id: receipt.request_id,
-          replies: result.response.replies,
-          degraded: result.degraded,
-        }),
+        JSON.stringify(replyResultJson(result.response, result.degraded)),
       )
-    } else if (result.response.replies.length > 0) printReplies(deps, result.response.replies)
-    else printNoReply(deps, receipt.request_id, result.response.reply_expires_at)
+    } else if (result.response.replies.length > 0) {
+      printReplies(deps, result.response.replies)
+      printAcknowledgementStatus(deps, result.response)
+    } else {
+      printNoReply(deps, receipt.request_id, result.response.reply_expires_at)
+      printAcknowledgementStatus(deps, result.response)
+    }
     if (result.degraded) {
       log(deps).error('cli.error', {
         kind: 'network',
@@ -893,12 +899,14 @@ export async function repliesCommand(
         })
         recordReplies(deps, requestId, result.response.replies)
         if (flags.json) {
-          jsonBodies.push({ ...result.response, degraded: result.degraded })
+          jsonBodies.push(replyResultJson(result.response, result.degraded))
         } else if (result.response.replies.length > 0) {
           if (flags.pending === true) deps.io.out(`pending request ${requestId}`)
           printReplies(deps, result.response.replies)
+          printAcknowledgementStatus(deps, result.response)
         } else {
           printNoReply(deps, requestId, result.response.reply_expires_at)
+          printAcknowledgementStatus(deps, result.response)
         }
         anyReplies ||= result.response.replies.length > 0
         if (result.degraded) degradedRequestIds.push(requestId)
@@ -996,7 +1004,13 @@ export async function waitForReply(
   return {
     response:
       lastResponse ??
-      ({ request_id: requestId, reply_expires_at: null, replies: [] } satisfies ListRepliesResponse),
+      ({
+        request_id: requestId,
+        reply_expires_at: null,
+        agent_acknowledgement_required: false,
+        agent_acknowledgement: null,
+        replies: [],
+      } satisfies ListRepliesResponse),
     timedOut: true,
     // A poll succeeded at some point, so we do not throw — but the last thing
     // we know is that we could not reach the server. Reporting that as a plain
@@ -1036,6 +1050,56 @@ function isNonNegativeInteger(value: number): boolean {
   return Number.isInteger(value) && value >= 0
 }
 
+function acknowledgementCommand(
+  requestId: string,
+  required: boolean,
+  acknowledgement: ListRepliesResponse['agent_acknowledgement'],
+  hasReply = true,
+): string | null {
+  return required && acknowledgement === null && hasReply
+    ? `notifai acknowledge ${requestId} --text <text>`
+    : null
+}
+
+function replyResultJson(response: ListRepliesResponse, degraded: boolean): object {
+  return {
+    type: 'reply_result',
+    request_id: response.request_id,
+    reply_expires_at: response.reply_expires_at,
+    replies: response.replies,
+    agent_acknowledgement_required: response.agent_acknowledgement_required,
+    agent_acknowledgement: response.agent_acknowledgement,
+    acknowledgement_command: acknowledgementCommand(
+      response.request_id,
+      response.agent_acknowledgement_required,
+      response.agent_acknowledgement,
+      response.replies.length > 0,
+    ),
+    degraded,
+  }
+}
+
+function printAcknowledgementStatus(deps: CommandDeps, response: ListRepliesResponse): void {
+  if (!response.agent_acknowledgement_required) {
+    deps.io.out('Agent Acknowledgement: not required for this request.')
+    return
+  }
+  if (response.agent_acknowledgement !== null) {
+    deps.io.out(
+      `Agent Acknowledgement: recorded at ${response.agent_acknowledgement.created_at}: ${response.agent_acknowledgement.text}`,
+    )
+    return
+  }
+  if (response.replies.length > 0) {
+    deps.io.out('Agent Acknowledgement required.')
+    deps.io.out(
+      `next: Run \`${acknowledgementCommand(response.request_id, true, null)}\` with concrete text saying what you will do because of the reply.`,
+    )
+    return
+  }
+  deps.io.out('Agent Acknowledgement: required after a user reply; no reply is recorded yet.')
+}
+
 function recordReplies(deps: CommandDeps, requestId: string, replies: readonly ReplyView[]): void {
   const logger = log(deps)
   for (const reply of replies) {
@@ -2123,14 +2187,95 @@ function hookActivationAdvice(installations: Installation[]): string {
   return `${advice.join('. ')}.`
 }
 
+/** Record the one Agent Acknowledgement associated with a replied-to request. */
+export async function acknowledgeCommand(
+  deps: CommandDeps,
+  requestId: string,
+  flags: { text?: string; json?: boolean },
+): Promise<number> {
+  const text = flags.text?.trim() ?? ''
+  if (text.length === 0) {
+    deps.io.err('--text is required and must contain non-whitespace text.')
+    return EXIT.usage
+  }
+  if (text.length > AGENT_ACKNOWLEDGEMENT_MAX_LENGTH) {
+    deps.io.err(
+      `--text must be at most ${AGENT_ACKNOWLEDGEMENT_MAX_LENGTH} characters after trimming.`,
+    )
+    return EXIT.usage
+  }
+
+  const logger = log(deps)
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  logger.info('acknowledgement.attempted', {
+    request_id: requestId,
+    text,
+    characters: text.length,
+  })
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  try {
+    const result = await authed.client.putAgentAcknowledgement(requestId, { text })
+    const output = {
+      request_id: requestId,
+      outcome: result.status,
+      acknowledgement: result.agent_acknowledgement,
+      agent_acknowledgement_required: true,
+    }
+    logger.info('acknowledgement.outcome', {
+      request_id: requestId,
+      outcome: result.status,
+      text: result.agent_acknowledgement.text,
+      created_at: result.agent_acknowledgement.created_at,
+      agent_acknowledgement_required: true,
+    })
+    const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)())
+    if (sessionId !== null) {
+      clearAcknowledgementObligation(sessionId, deps.env, requestId)
+    }
+    if (flags.json) deps.io.out(JSON.stringify(output, null, 2))
+    else {
+      deps.io.out(
+        `Agent Acknowledgement ${result.status} for ${requestId} at ${result.agent_acknowledgement.created_at}.`,
+      )
+    }
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err, { operation: 'agent_acknowledgement', request_id: requestId })
+  }
+}
+
 /** Retire a question so a late answer is rejected rather than silently lost. */
-export async function closeCommand(deps: CommandDeps, requestId: string): Promise<number> {
+export async function closeCommand(
+  deps: CommandDeps,
+  requestId: string,
+  flags: { json?: boolean } = {},
+): Promise<number> {
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const authed = authedClient(deps, config)
   if (!authed) return EXIT.auth
   try {
-    await authed.client.closeReplies(requestId)
-    deps.io.out(`Closed the reply window for ${requestId}.`)
+    const response = await authed.client.closeReplies(requestId)
+    if (flags.json) {
+      deps.io.out(
+        JSON.stringify(
+          {
+            ...response,
+            acknowledgement_command: acknowledgementCommand(
+              response.request_id,
+              response.agent_acknowledgement_required,
+              response.agent_acknowledgement,
+              response.replies.length > 0,
+            ),
+          },
+          null,
+          2,
+        ),
+      )
+    } else {
+      deps.io.out(`Closed the reply window for ${requestId}.`)
+      if (response.replies.length > 0) printAcknowledgementStatus(deps, response)
+    }
     return EXIT.ok
   } catch (err) {
     return reportError(deps, err)