@raidiant/notifai 1.1.0 → 2.0.1

package/src/hooks.test.ts

@@ -89,6 +89,9 @@ interface Recorder {
   beforeReplies?: () => Promise<void>
   /** Per-request answer stream for multi-question ownership tests. */
   repliesFor?: (requestId: string) => ReplyView[]
+  acknowledgementRequiredFor?: (requestId: string) => boolean
+  acknowledged?: Set<string>
+  acknowledgementChecks?: string[]
 }
 
 function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
@@ -115,7 +118,7 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
           platform: 'ios' as const,
           permission_status: 'authorized',
           registration_healthy: true,
-          reply_protocol_version: 1,
+          reply_protocol_version: 2,
           last_seen_at: null,
         },
         {
@@ -124,13 +127,36 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
           platform: 'macos' as const,
           permission_status: 'authorized',
           registration_healthy: true,
-          reply_protocol_version: 1,
+          reply_protocol_version: 2,
           last_seen_at: null,
         },
       ],
     }),
     capabilities: notUsed,
     evidence: notUsed,
+    putAgentAcknowledgement: async (requestId, body) => {
+      recorder.acknowledged ??= new Set()
+      recorder.acknowledged.add(requestId)
+      return {
+        status: 'recorded',
+        agent_acknowledgement: {
+          text: body.text,
+          created_at: new Date(NOW).toISOString(),
+        },
+      }
+    },
+    agentAcknowledgement: async (requestId) => {
+      recorder.acknowledgementChecks ??= []
+      recorder.acknowledgementChecks.push(requestId)
+      const required = recorder.acknowledgementRequiredFor?.(requestId) ?? true
+      return {
+        request_id: requestId,
+        agent_acknowledgement_required: required,
+        agent_acknowledgement: recorder.acknowledged?.has(requestId)
+          ? { text: 'I will continue.', created_at: new Date(NOW).toISOString() }
+          : null,
+      }
+    },
     createMediaUpload: notUsed,
     uploadMedia: notUsed,
     health: async () => true,
@@ -145,6 +171,8 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
       return {
         request_id: requestId,
         reply_expires_at: new Date(NOW + 480_000).toISOString(),
+        agent_acknowledgement_required:
+          recorder.acknowledgementRequiredFor?.(requestId) ?? true,
         replayed: false,
         overall: 'provider_accepted_all',
         deliveries: [],
@@ -156,6 +184,11 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
       return ({
         request_id: requestId,
         reply_expires_at: null,
+        agent_acknowledgement_required:
+          recorder.acknowledgementRequiredFor?.(requestId) ?? true,
+        agent_acknowledgement: recorder.acknowledged?.has(requestId)
+          ? { text: 'I will continue.', created_at: new Date(NOW).toISOString() }
+          : null,
         replies: recordedReplies(requestId),
       }) satisfies ListRepliesResponse
     },
@@ -164,6 +197,11 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
       return {
         request_id: requestId,
         reply_expires_at: new Date(NOW).toISOString(),
+        agent_acknowledgement_required:
+          recorder.acknowledgementRequiredFor?.(requestId) ?? true,
+        agent_acknowledgement: recorder.acknowledged?.has(requestId)
+          ? { text: 'I will continue.', created_at: new Date(NOW).toISOString() }
+          : null,
         replies: recordedReplies(requestId),
       } satisfies ListRepliesResponse
     },
@@ -842,6 +880,8 @@ describe('nagging guards', () => {
     registerQuestion('n3', h.env, { question: 'First question?' }, NOW)
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'n3' }))
+    h.recorder.acknowledged ??= new Set()
+    h.recorder.acknowledged.add(h.recorder.receipts[0]!)
     await h.deps.sleep?.(1)
     registerQuestion('n3', h.env, { question: 'Follow-up question?' }, (h.deps.now?.() ?? NOW))
     h.io.outLines = []
@@ -1215,6 +1255,8 @@ describe('the waiter owning one question to the end', () => {
     ])
 
     answers.set('req_hook_2', [reply({ text: 'Second answer' })])
+    h.recorder.acknowledged ??= new Set()
+    h.recorder.acknowledged.add(h.recorder.receipts[0]!)
     h.io.outLines = []
     await hookRunCommand(
       h.deps,
@@ -1621,6 +1663,8 @@ describe('several questions in flight', () => {
     expect(JSON.parse(h.io.outLines.at(-1)!).reason).toContain('Ship it')
     expect(readSessionState('answer-handoff', h.env).accepted).toBeDefined()
 
+    h.recorder.acknowledged ??= new Set()
+    h.recorder.acknowledged.add('req_existing')
     h.io.outLines = []
     await hookRunCommand(
       h.deps,
@@ -1638,6 +1682,104 @@ describe('several questions in flight', () => {
     ).toBe('answered')
   })
 
+  it('blocks Stop with the exact command until a required Agent Acknowledgement is recorded', async () => {
+    const h = harness([reply({ text: 'Ship it' })])
+    writeSessionState('ack-required', h.env, {
+      pending: [
+        {
+          question: 'Ship it?',
+          request_id: 'req_ack_required',
+          collapse_key: 'collapse-ack-required',
+          device_ids: ['dev_iphone'],
+          reply_deadline_at: NOW + 60_000,
+        },
+      ],
+    })
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-required' }))
+    expect(readSessionState('ack-required', h.env).acknowledgement_due).toEqual([
+      { request_id: 'req_ack_required', recorded_at: NOW },
+    ])
+
+    h.io.outLines = []
+    await hookRunCommand(
+      h.deps,
+      'stop',
+      stdin({ session_id: 'ack-required', stop_hook_active: true }),
+    )
+
+    const blocked = JSON.parse(h.io.outLines[0] ?? '{}') as { decision?: string; reason?: string }
+    expect(blocked.decision).toBe('block')
+    expect(blocked.reason).toContain('req_ack_required')
+    expect(blocked.reason).toContain(
+      'notifai acknowledge req_ack_required --text <text>',
+    )
+    expect(blocked.reason).toContain('concrete work')
+    expect(readSessionState('ack-required', h.env).accepted).toBeUndefined()
+  })
+
+  it('reconciles a server-recorded Agent Acknowledgement after a local clearing crash', async () => {
+    const h = harness([])
+    writeSessionState('ack-heal', h.env, {
+      acknowledgement_due: [{ request_id: 'req_ack_heal', recorded_at: NOW }],
+    })
+    h.recorder.acknowledged = new Set(['req_ack_heal'])
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-heal' }))
+
+    expect(h.recorder.acknowledgementChecks).toEqual(['req_ack_heal'])
+    expect(readSessionState('ack-heal', h.env).acknowledgement_due).toBeUndefined()
+    expect(h.io.outLines).toEqual([])
+  })
+
+  it('records only the requests whose immutable snapshot requires acknowledgement', async () => {
+    const h = harness([])
+    repliesByRequest(
+      h,
+      new Map([
+        ['req_hook_1', [reply({ text: 'Ship it' })]],
+        ['req_hook_2', [reply({ text: 'Staging' })]],
+      ]),
+    )
+    h.recorder.acknowledgementRequiredFor = (requestId) =>
+      h.recorder.aliases.get(requestId) === 1
+    writeSessionState('ack-mixed', h.env, { last_prompt_at: AWAY })
+    registerQuestion('ack-mixed', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion('ack-mixed', h.env, { question: 'Deploy where?' }, NOW + 1)
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-mixed' }))
+
+    const state = readSessionState('ack-mixed', h.env)
+    expect(state.acknowledgement_due?.map((entry) => entry.request_id)).toEqual([
+      h.recorder.receipts[0],
+    ])
+    const output = JSON.parse(h.io.outLines[0] ?? '{}') as { reason?: string }
+    expect(output.reason).toContain(h.recorder.receipts[0]!)
+    expect(output.reason).not.toContain(h.recorder.receipts[1]!)
+  })
+
+  it('lists every required request and command in a multi-answer continuation', async () => {
+    const h = harness([])
+    repliesByRequest(
+      h,
+      new Map([
+        ['req_hook_1', [reply({ text: 'Ship it' })]],
+        ['req_hook_2', [reply({ text: 'Staging' })]],
+      ]),
+    )
+    writeSessionState('ack-multiple', h.env, { last_prompt_at: AWAY })
+    registerQuestion('ack-multiple', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion('ack-multiple', h.env, { question: 'Deploy where?' }, NOW + 1)
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-multiple' }))
+
+    const output = JSON.parse(h.io.outLines[0] ?? '{}') as { reason?: string }
+    for (const requestId of h.recorder.receipts) {
+      expect(output.reason).toContain(requestId)
+      expect(output.reason).toContain(`notifai acknowledge ${requestId} --text <text>`)
+    }
+  })
+
   it('resumes with a partial answer and keeps the rest registered', async () => {
     const h = harness([])
     const byRequest = new Map([['req_hook_1', [reply({ text: 'Ship it' })]]])
@@ -1658,6 +1800,8 @@ describe('several questions in flight', () => {
     // The remaining question's answer arrives before the next turn ends; the
     // late-answer path hands it over without asking anything twice.
     byRequest.set('req_hook_2', [reply({ text: 'Staging' })])
+    h.recorder.acknowledged ??= new Set()
+    h.recorder.acknowledged.add(h.recorder.receipts[0]!)
     h.io.outLines = []
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'multi3', stop_hook_active: true }))
 
@@ -2179,6 +2323,8 @@ describe('user-prompt-submit hook', () => {
     registerQuestion('s16', h.env, { question: 'Ship it?' })
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 's16' }))
+    h.recorder.acknowledged ??= new Set()
+    h.recorder.acknowledged.add(h.recorder.receipts[0]!)
     await hookRunCommand(
       h.deps,
       'stop',
@@ -2399,6 +2545,8 @@ describe('telling concurrent agents apart', () => {
     registerQuestion('sess-abc', h.env, { question: 'Ship it?' }, NOW)
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sess-abc' }))
+    h.recorder.acknowledged ??= new Set()
+    h.recorder.acknowledged.add(h.recorder.receipts[0]!)
     await hookRunCommand(
       h.deps,
       'stop',

package/src/hooks.ts

@@ -118,6 +118,18 @@ export interface SessionState {
    * reaches the harness replays it instead of erasing it.
    */
   accepted?: AcceptedAnswerDelivery
+  /**
+   * Required Agent Acknowledgements that the resumed agent still owes. This is
+   * separate from answer delivery: the answer journal may settle as soon as a
+   * harness accepts the continuation, while this obligation must survive until
+   * the service confirms the agent-authored follow-up exists.
+   */
+  acknowledgement_due?: AcknowledgementDue[]
+}
+
+export interface AcknowledgementDue {
+  request_id: string
+  recorded_at: number
 }
 
 interface AcceptedAnswerDelivery {
@@ -784,6 +796,7 @@ export type GateReason =
   | 'continuation-repeat'
   | 'continuation-limit'
   | 'delivery-limit'
+  | 'acknowledgement-required'
   | 'notifications-off'
   | 'claimed-elsewhere'
   | 'no-devices'
@@ -977,7 +990,7 @@ async function answerableDevices(ctx: HookContext): Promise<string[]> {
       (device) =>
         (device.platform === 'ios' || device.platform === 'macos') &&
         device.registration_healthy &&
-        device.reply_protocol_version === 1,
+        device.reply_protocol_version === 2,
     )
     .filter((device) => configured === null || configured.includes(device.device_id))
     .map((device) => device.device_id)
@@ -1340,6 +1353,8 @@ interface AnsweredPending {
   pending: PendingQuestion
   reply: ReplyView
   replies: ReplyView[]
+  /** Immutable server snapshot for this request, known after a replies/close response. */
+  agent_acknowledgement_required?: boolean | undefined
 }
 
 interface FinalizedPending {
@@ -1364,7 +1379,15 @@ async function finalizePendings(
 function finalizedAnswer(finalized: FinalizedPending): AnsweredPending | null {
   const replies = finalized.response?.replies ?? []
   const reply = replies.at(-1)
-  return reply === undefined ? null : { pending: finalized.pending, reply, replies }
+  return reply === undefined
+    ? null
+    : {
+        pending: finalized.pending,
+        reply,
+        replies,
+        agent_acknowledgement_required:
+          finalized.response?.agent_acknowledgement_required,
+      }
 }
 
 /** Persist and surface one answer without letting the two representations drift. */
@@ -1476,13 +1499,45 @@ function answerContext(answered: AnsweredPending): string {
  * tied to the question that asked it, with a truthful note about anything
  * still waiting.
  */
+function acknowledgementCommand(requestId: string): string {
+  return `notifai acknowledge ${requestId} --text <text>`
+}
+
+function acknowledgementContext(answered: AnsweredPending[]): string {
+  const due = answered.filter(
+    (entry) =>
+      entry.agent_acknowledgement_required === true && entry.pending.request_id !== undefined,
+  )
+  if (due.length === 0) {
+    return ' Agent Acknowledgement is not required for the answered request(s).'
+  }
+  if (due.length === 1) {
+    const requestId = due[0]!.pending.request_id!
+    return (
+      ` Agent Acknowledgement is required for request ${requestId}. Immediately, before doing the resumed work or ending this turn, run ` +
+      `\`${acknowledgementCommand(requestId)}\` with non-empty text saying what concrete work you will do because of the reply; a bare acknowledgement is insufficient.`
+    )
+  }
+  const commands = due
+    .map((entry) => {
+      const requestId = entry.pending.request_id!
+      return `- ${requestId}: \`${acknowledgementCommand(requestId)}\``
+    })
+    .join('\n')
+  return (
+    ` Agent Acknowledgement is required for ${due.length} requests. Immediately, before doing the resumed work or ending this turn, run every command below with non-empty text saying what concrete work you will do because of that reply; a bare acknowledgement is insufficient:\n` +
+    commands
+  )
+}
+
 function answersContext(answered: AnsweredPending[], remaining: number): string {
   const tail =
     remaining > 0
       ? ` (${remaining} more registered question${remaining === 1 ? ' is' : 's are'} still waiting for an answer.)`
       : ''
+  const guidance = acknowledgementContext(answered)
   if (answered.length === 1) {
-    return answerContext(answered[0]!) + tail
+    return answerContext(answered[0]!) + tail + guidance
   }
   const lines = answered.map(({ pending, replies }) => {
     const latest = replies.at(-1)!
@@ -1494,7 +1549,7 @@ function answersContext(answered: AnsweredPending[], remaining: number): string
     const identity = ids.length === 0 ? '' : `question_id${ids.length === 1 ? '' : 's'} ${ids.join(', ')}: `
     return `- ${identity}${JSON.stringify(pending.question)} → ${answer}`
   })
-  return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}${tail}`
+  return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}${tail}${guidance}`
 }
 
 function stopAnswerOutput(context: string): string {
@@ -1525,12 +1580,25 @@ function stageAcceptedAnswers(
     const pendingRemaining = pendingList(current).filter(
       (entry) => !answered.some(({ pending }) => isSamePending(entry, pending)),
     )
+    const acknowledgementDue = [...(current.acknowledgement_due ?? [])]
+    for (const answer of answered) {
+      const requestId = answer.pending.request_id
+      if (
+        answer.agent_acknowledgement_required === true &&
+        requestId !== undefined &&
+        !acknowledgementDue.some((entry) => entry.request_id === requestId)
+      ) {
+        acknowledgementDue.push({ request_id: requestId, recorded_at: accepted.recorded_at })
+      }
+    }
     const next: SessionState = {
       ...current,
       accepted,
     }
     if (pendingRemaining.length > 0) next.pending = pendingRemaining
     else delete next.pending
+    if (acknowledgementDue.length > 0) next.acknowledgement_due = acknowledgementDue
+    else delete next.acknowledgement_due
     return next
   })
   return accepted
@@ -1547,6 +1615,68 @@ function amendAcceptedAnswers(
   )
 }
 
+export function clearAcknowledgementObligation(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  requestId: string,
+): boolean {
+  let cleared = false
+  updateSessionState(sessionId, env, (current) => {
+    const due = current.acknowledgement_due ?? []
+    const remaining = due.filter((entry) => entry.request_id !== requestId)
+    cleared = remaining.length !== due.length
+    if (!cleared) return current
+    const next = { ...current }
+    if (remaining.length > 0) next.acknowledgement_due = remaining
+    else delete next.acknowledgement_due
+    return next
+  })
+  return cleared
+}
+
+function acknowledgementBlockContext(due: readonly AcknowledgementDue[]): string {
+  const commands = due
+    .map((entry) => `- ${entry.request_id}: \`${acknowledgementCommand(entry.request_id)}\``)
+    .join('\n')
+  return (
+    `Notifai — required Agent Acknowledgement${due.length === 1 ? '' : 's'} still missing for request${due.length === 1 ? '' : 's'} ${due.map((entry) => entry.request_id).join(', ')}. ` +
+    `Before doing more resumed work or ending this turn, run ${due.length === 1 ? 'this command' : 'every command'} with non-empty text saying what concrete work you will do because of the reply; a bare acknowledgement is insufficient:\n${commands}`
+  )
+}
+
+async function reconcileAcknowledgementObligations(
+  ctx: HookContext,
+  sessionId: string,
+  due: readonly AcknowledgementDue[],
+): Promise<AcknowledgementDue[]> {
+  const unresolved: AcknowledgementDue[] = []
+  for (const obligation of due) {
+    try {
+      const snapshot = await ctx.client.agentAcknowledgement(obligation.request_id, {
+        waitSeconds: 0,
+      })
+      if (
+        snapshot.agent_acknowledgement_required === false ||
+        snapshot.agent_acknowledgement !== null
+      ) {
+        clearAcknowledgementObligation(sessionId, ctx.env, obligation.request_id)
+      } else {
+        unresolved.push(obligation)
+      }
+    } catch (err) {
+      unresolved.push(obligation)
+      ctx.log?.error('hook.gate', {
+        verdict: 'held',
+        reason: 'acknowledgement-required',
+        stage: 'reconcile-failed',
+        request_id: obligation.request_id,
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+  return unresolved
+}
+
 /**
  * Retire the answered questions and close the journal.
  *
@@ -1666,7 +1796,14 @@ export async function handleUserPromptSubmit(
           `could not confirm the close fence for ${entry.pending.request_id}; preserving the durable answer already observed`,
         )
       }
-      return { ...entry, replies, reply: replies.at(-1)! }
+      return {
+        ...entry,
+        replies,
+        reply: replies.at(-1)!,
+        agent_acknowledgement_required:
+          response?.agent_acknowledgement_required ??
+          entry.agent_acknowledgement_required,
+      }
     })
     if (answered.length > 0) {
       stageAcceptedAnswers(
@@ -1800,6 +1937,27 @@ export async function runEscalationWaiter(
     let state = readSessionState(sessionId, ctx.env)
     if (state.accepted !== undefined) {
       const accepted = state.accepted
+      if (envelope.stop_hook_active === true && pendingList(state).length > 0) {
+        const due = await reconcileAcknowledgementObligations(
+          ctx,
+          sessionId,
+          state.acknowledgement_due ?? [],
+        )
+        if (due.length > 0) {
+          gate(ctx, 'held', 'acknowledgement-required', {
+            request_ids: due.map((entry) => entry.request_id),
+          })
+          return {
+            stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
+            notes,
+            log: {
+              stage: 'acknowledgement-required',
+              request_ids: due.map((entry) => entry.request_id),
+            },
+          }
+        }
+        state = readSessionState(sessionId, ctx.env)
+      }
       // Acknowledgement is per route, because routes end in different places.
       //
       // A blocking continuation ends at this process's stdout, which the
@@ -1820,6 +1978,54 @@ export async function runEscalationWaiter(
       settleAcceptedAnswers(ctx, sessionId, accepted)
       settledAnswerThisPass = true
       state = readSessionState(sessionId, ctx.env)
+      const currentAcceptedIds = new Set(
+        accepted.answers.flatMap(({ pending }) =>
+          pending.request_id === undefined ? [] : [pending.request_id],
+        ),
+      )
+      const due = await reconcileAcknowledgementObligations(
+        ctx,
+        sessionId,
+        (state.acknowledgement_due ?? []).filter((entry) =>
+          currentAcceptedIds.has(entry.request_id),
+        ),
+      )
+      if (due.length > 0) {
+        gate(ctx, 'held', 'acknowledgement-required', {
+          request_ids: due.map((entry) => entry.request_id),
+        })
+        return {
+          stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
+          notes,
+          log: {
+            stage: 'acknowledgement-required',
+            request_ids: due.map((entry) => entry.request_id),
+          },
+        }
+      }
+      state = readSessionState(sessionId, ctx.env)
+    }
+
+    if (state.accepted === undefined && (state.acknowledgement_due?.length ?? 0) > 0) {
+      const due = await reconcileAcknowledgementObligations(
+        ctx,
+        sessionId,
+        state.acknowledgement_due!,
+      )
+      if (due.length > 0) {
+        gate(ctx, 'held', 'acknowledgement-required', {
+          request_ids: due.map((entry) => entry.request_id),
+        })
+        return {
+          stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
+          notes,
+          log: {
+            stage: 'acknowledgement-required',
+            request_ids: due.map((entry) => entry.request_id),
+          },
+        }
+      }
+      state = readSessionState(sessionId, ctx.env)
     }
 
     const pending = pendingList(state)
@@ -2014,7 +2220,14 @@ async function handleClaimedStop(
             `could not confirm the close fence for ${entry.pending.request_id}; delivering the durable answer already observed`,
           )
         }
-        return { ...entry, replies, reply: replies.at(-1)! }
+        return {
+        ...entry,
+        replies,
+        reply: replies.at(-1)!,
+        agent_acknowledgement_required:
+          response?.agent_acknowledgement_required ??
+          entry.agent_acknowledgement_required,
+      }
       })
       const accepted = stageAcceptedAnswers(
         ctx,
@@ -2429,7 +2642,13 @@ async function escalate(
     // unreachable, never discard the durable reply already observed.
     const finalReplies = finalized.response?.replies ?? []
     const authoritative = finalReplies.length > 0 ? finalReplies : replies
-    answered.push({ pending: entry, reply: authoritative.at(-1)!, replies: authoritative })
+    answered.push({
+      pending: entry,
+      reply: authoritative.at(-1)!,
+      replies: authoritative,
+      agent_acknowledgement_required:
+        finalized.response?.agent_acknowledgement_required,
+    })
     if (finalized.response === null) {
       notes.push(
         `could not confirm the close fence for ${entry.request_id}; delivering the durable answer already observed`,
@@ -2491,19 +2710,28 @@ export function handleSessionEnd(
       `queued ${orphans.length} question${orphans.length > 1 ? 's' : ''} for retirement on the next hook`,
     )
   }
-  if (state.accepted !== undefined) {
-    const preserved: SessionState = { accepted: state.accepted }
+  if (state.accepted !== undefined || (state.acknowledgement_due?.length ?? 0) > 0) {
+    const preserved: SessionState = {}
+    if (state.accepted !== undefined) preserved.accepted = state.accepted
+    if (state.acknowledgement_due !== undefined && state.acknowledgement_due.length > 0) {
+      preserved.acknowledgement_due = state.acknowledgement_due
+    }
     if (state.last_prompt_at !== undefined) preserved.last_prompt_at = state.last_prompt_at
     if (state.last_stop_at !== undefined) preserved.last_stop_at = state.last_stop_at
     if (state.continuation !== undefined) preserved.continuation = state.continuation
     writeSessionState(sessionId, env, preserved)
-    notes.push('preserved an accepted device answer for this exact session to resume')
+    notes.push(
+      state.accepted !== undefined
+        ? 'preserved an accepted device answer for this exact session to resume'
+        : 'preserved required Agent Acknowledgement obligations for this exact session',
+    )
     return {
       notes,
       log: {
-        outcome: 'answer-preserved',
+        outcome: state.accepted !== undefined ? 'answer-preserved' : 'acknowledgement-preserved',
         queued_retirements: orphans.length,
-        accepted_answers: state.accepted.answers.length,
+        accepted_answers: state.accepted?.answers.length ?? 0,
+        acknowledgement_due: state.acknowledgement_due?.length ?? 0,
       },
     }
   }

package/src/logging.ts

@@ -87,6 +87,10 @@ export const LOG_EVENTS = [
   'ask.registered',
   /** An answer came back from a device. */
   'reply.received',
+  /** An agent attempted to acknowledge the user's reply. */
+  'acknowledgement.attempted',
+  /** The service recorded or replayed an Agent Acknowledgement. */
+  'acknowledgement.outcome',
   /** A harness hook started. */
   'hook.start',
   /** A hook decided whether a question may leave the terminal, and why. */

package/src/main.ts

@@ -2,6 +2,7 @@
 import { readFileSync } from 'node:fs'
 import { Command } from 'commander'
 import {
+  acknowledgeCommand,
   askCommand,
   accessStatusCommand,
   authStatusCommand,
@@ -352,6 +353,19 @@ program
     process.exit(await repliesCommand(deps, requestId, opts))
   })
 
+program
+  .command('acknowledge <request_id>')
+  .helpGroup(GROUP.agent)
+  .summary("Tell the user what you'll do because of their reply")
+  .description(
+    'Record the required Agent Acknowledgement for a replied-to notification request; never prompts',
+  )
+  .requiredOption('--text <text>', 'concrete work you will do because of the reply')
+  .option('--json', 'machine-readable output')
+  .action(async (requestId: string, opts: { text: string; json?: boolean }) => {
+    process.exit(await acknowledgeCommand(deps, requestId, opts))
+  })
+
 program
   .command('status <request_id>')
   .helpGroup(GROUP.agent)
@@ -423,8 +437,9 @@ program
   .helpGroup(GROUP.agent)
   .summary('Retire a question so late answers are rejected')
   .description('Retire a question so late answers are rejected rather than lost')
-  .action(async (requestId: string) => {
-    process.exit(await closeCommand(deps, requestId))
+  .option('--json', 'machine-readable output')
+  .action(async (requestId: string, opts: { json?: boolean }) => {
+    process.exit(await closeCommand(deps, requestId, opts))
   })
 
 // Hidden, not removed. It is an entry point the hook installer writes into a