@raidiant/notifai 8.0.0 → 9.0.0

package/src/commands-hooks.ts

@@ -30,19 +30,28 @@ import {
 } from './hook-adapter.js'
 import {
   clearAcknowledgementObligation,
+  claimPromptActivation,
+  claimCursorStopActivation,
+  confirmCursorStopActivation,
+  dropPendingQuestion,
   handleSessionEnd,
   handleStop,
   handleUserPromptSubmit,
+  markSessionActivation,
+  parkForRetirement,
   parseHookInput,
   pruneAbandonedSessions,
   readMatchingProjectSessionPointer,
   readProjectSession,
   readSessionState,
+  resetCursorStopActivation,
   registerQuestion,
   waiterCeilingSeconds,
+  withdrawUnpushedQuestions,
   type EscalationDeliveryRoute,
   type HookContext,
   type HookHarness,
+  type PendingQuestion,
 } from './hooks.js'
 import {
   BLOCKING_STOP_TIMEOUT_SECONDS,
@@ -50,6 +59,7 @@ import {
   applyPlan,
   buildCursorHookConfig,
   buildHookConfig,
+  cleanupEmptiedCodexLayer,
   codexCoexistenceNotes,
   codexHomeNote,
   codexLayerDir,
@@ -76,6 +86,11 @@ import {
 import { logConfigResolved, logSettingsFrom } from './logging.js'
 import { isOurOpencodePlugin, opencodePluginSource } from './opencode-plugin.js'
 import { packageVersion } from './release.js'
+import { rejectAccidentalEscapedNewlines } from './send.js'
+import {
+  cursorStopActivationOutput,
+  sessionActivationOutput,
+} from './session-activation.js'
 import {
   CHOICE_USAGE,
   buildDraft,
@@ -87,6 +102,7 @@ import {
 import {
   EXIT,
   authedClient,
+  diagnoseIgnoredOriginOverride,
   loadLoggedConfig,
   log,
   makeClient,
@@ -112,9 +128,24 @@ import {
 // hook / ask / close — harness integration
 // ---------------------------------------------------------------------------
 
-export const HOOK_EVENTS = ['user-prompt-submit', 'stop', 'session-end'] as const
+export const HOOK_EVENTS = [
+  'session-start',
+  'subagent-start',
+  'activation-stop',
+  'user-prompt-submit',
+  'stop',
+  'session-end',
+] as const
 export type HookEvent = (typeof HOOK_EVENTS)[number]
 
+/** Lifecycle handlers one installed harness must carry in this CLI build. */
+export function requiredHookEvents(harness: Harness): readonly HookEvent[] {
+  if (harness === 'opencode') return []
+  return harness === 'cursor'
+    ? ['session-start', 'activation-stop', 'user-prompt-submit', 'stop', 'session-end']
+    : ['session-start', 'subagent-start', 'user-prompt-submit', 'stop', 'session-end']
+}
+
 /** SessionEnd cleanup must precede every diagnostic that can wait on a file lock. */
 export function hookDefersDiagnosticsUntilAfterCleanup(
   event: unknown,
@@ -124,8 +155,8 @@ export function hookDefersDiagnosticsUntilAfterCleanup(
 
 /**
  * Runs one harness hook. Contract with every harness: hook JSON arrives on
- * stdin, the decision (if any) goes to stdout, diagnostics go to stderr, and
- * exit 0 with no stdout means "no decision — carry on as normal".
+ * stdin, harness output (if any) goes to stdout, diagnostics go to stderr, and
+ * exit 0 with no stdout means "no decision or added context — carry on as normal".
  *
  * Every failure path in here must reach that no-decision state. A hook that
  * throws, or that blocks past the harness's timeout, degrades the agent for a
@@ -166,6 +197,21 @@ export async function hookRunCommand(
       ? { status: err.status, code: err.code, message: err.message, details: err.details }
       : { message: err instanceof Error ? err.message : String(err) }
 
+  // Cursor may load ~/.claude/settings.json in addition to its own native
+  // hooks. Cursor guarantees CURSOR_PROJECT_DIR to hook processes, so a Claude
+  // compatibility copy becomes a no-op and the native Cursor definition is
+  // the single owner. Real Claude hooks do not receive that hook-only marker.
+  if (harness === 'claude-code' && deps.env['CURSOR_PROJECT_DIR']) {
+    start({ outcome: 'cursor-compatibility-copy-skipped' })
+    logger.info('hook.end', {
+      hook: event,
+      outcome: 'ignored',
+      reason: 'cursor-native-handler-owns-event',
+      decided: false,
+    })
+    return EXIT.ok
+  }
+
   let raw: string
   try {
     raw = await readStdin()
@@ -209,6 +255,172 @@ export async function hookRunCommand(
   const cwd = envelope.cwd ?? deps.cwd
   const sessionEnd = hookDefersDiagnosticsUntilAfterCleanup(event)
   logger.bind({ session: envelope.session_id ?? null })
+  const declaredSourcePid = declaredHookSourcePid(deps)
+  const activationOwnerPid =
+    harness === 'claude-code'
+      ? (deps.claudeSourcePid ?? declaredSourcePid ?? claudeSessionPid(deps.env))
+      : harness === 'codex'
+        ? (deps.codexSourcePid ?? declaredSourcePid ?? process.ppid)
+        : undefined
+
+  // Session activation is local model context, not authenticated routing. It
+  // must survive the exact first-run states it exists to repair: no config,
+  // no credential, no Companion device, and no network.
+  if (event === 'session-start' || event === 'subagent-start') {
+    start({ cwd, source: envelope.source ?? null })
+    if (event === 'session-start' && harness === 'cursor' && envelope.session_id !== undefined) {
+      try {
+        resetCursorStopActivation(envelope.session_id, deps.env)
+      } catch (err) {
+        logger.error('hook.end', {
+          hook: event,
+          outcome: 'reset-failed',
+          ...failureData(err),
+        })
+      }
+    }
+    const stdout = sessionActivationOutput(
+      harness,
+      event === 'session-start' ? 'SessionStart' : 'SubagentStart',
+    )
+    if (stdout !== undefined) deps.io.out(stdout)
+    if (
+      stdout !== undefined &&
+      event === 'session-start' &&
+      activationOwnerPid !== undefined &&
+      envelope.session_id !== undefined
+    ) {
+      try {
+        // Write stdout first. If the process dies between these operations a
+        // later prompt may duplicate context, but it cannot suppress context
+        // that the host never received.
+        markSessionActivation(envelope.session_id, deps.env, now(), activationOwnerPid)
+      } catch (err) {
+        logger.error('hook.end', {
+          hook: event,
+          outcome: 'mark-failed',
+          reason: 'activation-state-failed',
+          ...failureData(err),
+        })
+      }
+    }
+    logger.info('hook.end', {
+      hook: event,
+      outcome: stdout === undefined ? 'unsupported-harness' : 'context-added',
+      decided: false,
+    })
+    return EXIT.ok
+  }
+
+  // SessionStart is the preferred model-visible activation seam. A few
+  // managed hosts regenerate older hook definitions that retain
+  // UserPromptSubmit but omit newer lifecycle events. Claim the first prompt
+  // once per exact session as a compatibility fallback, before config/auth/
+  // device/network work, and stay silent when SessionStart already ran.
+  let promptActivationStdout: string | undefined
+  if (
+    event === 'user-prompt-submit' &&
+    (harness === 'claude-code' || harness === 'codex') &&
+    activationOwnerPid !== undefined &&
+    envelope.session_id !== undefined
+  ) {
+    try {
+      if (claimPromptActivation(envelope.session_id, deps.env, now(), activationOwnerPid)) {
+        promptActivationStdout = sessionActivationOutput(harness, 'UserPromptSubmit')
+        if (promptActivationStdout !== undefined) deps.io.out(promptActivationStdout)
+      }
+    } catch (err) {
+      logger.error('hook.end', {
+        hook: event,
+        outcome: 'claim-failed',
+        reason: 'activation-state-failed',
+        ...failureData(err),
+      })
+    }
+  }
+
+  // Cursor has a confirmed host bug in which sessionStart.additional_context
+  // is accepted but never reaches the model. A native Stop follow-up is the
+  // host's guaranteed model-visible channel. Claim it once per conversation,
+  // before config/auth/network, and leave the ordinary Stop handler separate
+  // so question delivery is never displaced by activation.
+  if (event === 'activation-stop') {
+    start({ cwd, stop_hook_active: envelope.stop_hook_active ?? null })
+    if (harness !== 'cursor') {
+      logger.info('hook.end', { hook: event, outcome: 'unsupported-harness', decided: false })
+      return EXIT.ok
+    }
+    if (envelope.status === 'aborted') {
+      logger.info('hook.end', {
+        hook: event,
+        outcome: 'ignored',
+        reason: `turn-${envelope.status}`,
+        decided: false,
+      })
+      return EXIT.ok
+    }
+    if (envelope.session_id === undefined) {
+      logger.info('hook.end', {
+        hook: event,
+        outcome: 'ignored',
+        reason: 'missing-conversation-id',
+        decided: false,
+      })
+      return EXIT.ok
+    }
+    if (
+      envelope.session_id !== undefined &&
+      typeof envelope.loop_count === 'number' &&
+      envelope.loop_count > 0
+    ) {
+      let activationOwned = false
+      try {
+        activationOwned = confirmCursorStopActivation(envelope.session_id, deps.env, now())
+      } catch (err) {
+        logger.error('hook.end', {
+          hook: event,
+          outcome: 'confirm-failed',
+          ...failureData(err),
+        })
+      }
+      if (activationOwned) {
+        logger.info('hook.end', { hook: event, outcome: 'confirmed', decided: false })
+        return EXIT.ok
+      }
+    }
+    const cursorState = readSessionState(envelope.session_id, deps.env)
+    if (
+      (cursorState.pending?.length ?? 0) > 0 ||
+        cursorState.accepted !== undefined ||
+        (cursorState.acknowledgement_due?.length ?? 0) > 0
+    ) {
+      logger.info('hook.end', {
+        hook: event,
+        outcome: 'deferred',
+        reason: 'question-continuation-owns-stop',
+        decided: false,
+      })
+      return EXIT.ok
+    }
+    let claimed = false
+    try {
+      claimed = claimCursorStopActivation(envelope.session_id, deps.env, now())
+    } catch (err) {
+      logger.error('hook.end', {
+        hook: event,
+        outcome: 'claim-failed',
+        ...failureData(err),
+      })
+    }
+    logger.info('hook.end', {
+      hook: event,
+      outcome: claimed ? 'followup-added' : 'already-activated',
+      decided: claimed,
+    })
+    if (claimed) deps.io.out(cursorStopActivationOutput())
+    return EXIT.ok
+  }
+
   let config: CliConfig | null = null
   let configFailure: unknown
   try {
@@ -230,6 +442,7 @@ export async function hookRunCommand(
         hook: event,
         outcome: 'failed',
         reason: 'config-failed',
+        ...(promptActivationStdout === undefined ? {} : { activation: 'context-added' }),
         ...failureData(err),
       })
       for (const line of describeHookFailure(err)) deps.io.err(`notifai: ${line}`)
@@ -275,11 +488,7 @@ export async function hookRunCommand(
     // repository can commit `.notifai/config.toml`, and honouring a base_url
     // from it would hand this machine's bearer token to whatever host it names.
     const baseUrl = credential.baseUrl
-    if (resolved.base_url.source !== 'default' && resolved.base_url.value !== baseUrl) {
-      deps.io.err(
-        `notifai: ignoring base_url from ${resolved.base_url.source}; hooks only talk to ${baseUrl}`,
-      )
-    }
+    diagnoseIgnoredOriginOverride(deps.io, resolved, credential)
     // UserPromptSubmit runs in front of the user's own prompt under a 15s
     // harness ceiling and can make two calls, so each gets a small slice of it;
     // Stop is allowed to block and keeps the ordinary budget.
@@ -337,9 +546,10 @@ export async function hookRunCommand(
     const notes = outcome.notes.filter((note) => !/^(?:late )?answer from /.test(note))
     logger.info('hook.end', {
       hook: event,
-      // A hook that returns stdout has taken over the turn; one that does not
-      // has handed the terminal back. That distinction is the whole contract.
-      decided: outcome.stdout !== undefined,
+      // Stop stdout takes over the turn. UserPromptSubmit stdout may instead
+      // add context to the user's own turn, which is explicitly non-decisive.
+      decided: outcome.decided ?? outcome.stdout !== undefined,
+      ...(promptActivationStdout === undefined ? {} : { activation: 'context-added' }),
       ...(notes.length === 0 ? {} : { notes }),
       ...outcome.log,
     })
@@ -379,12 +589,13 @@ function stopWakeRoute(
   cwd: string,
 ): EscalationDeliveryRoute | undefined {
   if (sessionId === undefined) return undefined
+  const declaredSourcePid = declaredHookSourcePid(deps)
   if (harness === 'claude-code') {
     if ((deps.hookPlatform ?? process.platform) === 'win32') return undefined
     return claudeWakeRoute({
       sessionId,
       cwd,
-      sourcePid: deps.claudeSourcePid ?? claudeSessionPid(deps.env),
+      sourcePid: deps.claudeSourcePid ?? declaredSourcePid ?? claudeSessionPid(deps.env),
       ...(deps.claudeWake === undefined ? {} : { adapters: deps.claudeWake }),
     })
   }
@@ -392,7 +603,7 @@ function stopWakeRoute(
     return codexWakeRoute({
       threadId: sessionId,
       cwd,
-      sourcePid: deps.codexSourcePid ?? process.ppid,
+      sourcePid: deps.codexSourcePid ?? declaredSourcePid ?? process.ppid,
       env: deps.env,
       ...(deps.codexWake === undefined ? {} : { adapters: deps.codexWake }),
     })
@@ -400,6 +611,12 @@ function stopWakeRoute(
   return undefined
 }
 
+/** Stable harness parent propagated by the managed adapter across child tools. */
+function declaredHookSourcePid(deps: CommandDeps): number | undefined {
+  const value = Number(deps.env['NOTIFAI_HOOK_SOURCE_PID'])
+  return Number.isInteger(value) && value > 0 ? value : undefined
+}
+
 
 /**
  * What went wrong, in terms of what to do about it.
@@ -442,6 +659,8 @@ export interface AskFlags {
   multi?: boolean
   /** Optional Markdown context appended after the question block. */
   body?: string
+  /** Allow visible backslash-n sequences in `--body`. */
+  literalBackslashN?: boolean
   /** Raw JSON for a multi-question form; replaces the positional question. */
   form?: string
   image?: string[]
@@ -627,8 +846,9 @@ function recordRegisteredQuestion(
   draft: NotificationDraftT,
   json = false,
 ): number {
+  let questionId: string
   try {
-    registerQuestion(
+    questionId = registerQuestion(
       sessionId,
       deps.env,
       {
@@ -649,8 +869,9 @@ function recordRegisteredQuestion(
   log(deps).info('ask.registered', {
     ok: true,
     session: sessionId,
+    question_id: questionId,
     questions: built.questions.length,
-    text: built.questions[0]!.text,
+    text_chars: built.questions[0]!.text.length,
     choices: built.questions[0]!.choices?.length ?? 0,
     media: draft.presentation.media?.length ?? 0,
   })
@@ -663,12 +884,14 @@ function recordRegisteredQuestion(
       JSON.stringify(
         {
           registered: true,
+          question_id: questionId,
           questions: built.questions.map((entry) => ({
             id: entry.id,
             text: entry.text,
             ...(entry.choices === undefined ? {} : { choices: entry.choices }),
             ...(entry.multi === true ? { multi: true } : {}),
           })),
+          close: `notifai close ${questionId}`,
           next: {
             end_turn: true,
             in_this_turn:
@@ -677,6 +900,7 @@ function recordRegisteredQuestion(
               'Never say where the answer must arrive; it returns by whatever route the harness supports.',
             on_answer:
               'Acknowledge it, then resume the committed work without asking the user to confirm again.',
+            answered_outside_notifai: `If they answer in the conversation instead, run \`notifai close ${questionId}\` before ending the turn so a later Stop will not send this question.`,
           },
         },
         null,
@@ -696,8 +920,8 @@ function recordRegisteredQuestion(
   }
   deps.io.out(
     built.questions.length > 1
-      ? `${built.questions.length} questions registered as one form. Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
-      : 'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.',
+      ? `${built.questions.length} questions registered as one form (${questionId}). Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
+      : `Question registered (${questionId}). Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.`,
   )
   deps.io.out('Before ending this turn, pre-commit in your own words to the work you will resume:')
   for (const [index, entry] of built.questions.entries()) {
@@ -723,6 +947,9 @@ function recordRegisteredQuestion(
   deps.io.out(
     'A Notifai answer cannot answer a harness permission prompt or interactive picker; leave those to the harness and user.',
   )
+  deps.io.out(
+    `If they answer in this conversation instead, retire it with \`notifai close ${questionId}\` so a later Stop will not send it.`,
+  )
   return EXIT.ok
 }
 
@@ -742,7 +969,7 @@ async function uploadAskMedia(
       mediaIds.push(image)
       continue
     }
-    const uploaded = await uploadImage(deps, authed.client, image)
+    const uploaded = await uploadImage(deps, authed.client, image, config.media_origins.value)
     if (!uploaded.ok) {
       if (uploaded.error !== null) deps.io.err(uploaded.error)
       return uploaded.exit
@@ -770,6 +997,11 @@ export function askCommand(
   // Validate before route discovery. A malformed question belongs to the
   // caller and should not be hidden behind whichever harness setup issue
   // happens to exist on this machine.
+  const escapedBody = rejectAccidentalEscapedNewlines(flags.body, flags.literalBackslashN)
+  if (escapedBody !== null) {
+    deps.io.err(escapedBody)
+    return EXIT.usage
+  }
   const built = buildQuestions(flags, question)
   if (!built.ok) {
     deps.io.err(built.error)
@@ -1028,14 +1260,14 @@ export function hookActivationAdvice(installations: Installation[]): string {
       (installation) => installation.harness === 'claude-code' && !installation.global,
     )
   ) {
-    advice.push('Claude Code: send one new prompt; project hook files reload without a restart')
+    advice.push('Claude Code: start one fresh session, send one prompt, then run `notifai doctor`')
   }
   if (
     installations.some(
       (installation) => installation.harness === 'claude-code' && installation.global,
     )
   ) {
-    advice.push('Claude Code global hooks: send one prompt; start a new session only if it does not fire')
+    advice.push('Claude Code global hooks: start one fresh session, send one prompt, then run `notifai doctor`')
   }
   if (
     installations.some(
@@ -1043,7 +1275,7 @@ export function hookActivationAdvice(installations: Installation[]): string {
     )
   ) {
     advice.push(
-      'Cursor: send one prompt, then run `notifai doctor`; start a new session only if it still has not fired',
+      'Cursor: start one fresh conversation, send one prompt, finish its first turn, then run `notifai doctor`',
     )
   }
   if (
@@ -1051,11 +1283,11 @@ export function hookActivationAdvice(installations: Installation[]): string {
       (installation) => installation.harness === 'cursor' && installation.global,
     )
   ) {
-    advice.push('Cursor global hooks: send one prompt; start a new session only if it does not fire')
+    advice.push('Cursor global hooks: start one fresh conversation, send one prompt, finish its first turn, then run `notifai doctor`')
   }
   if (harnesses.has('codex')) {
     advice.push(
-      'Codex: send one prompt, then run `notifai doctor`; start a new session only if it still has not fired',
+      'Codex: approve the Notifai handlers in `/hooks` if asked, start one fresh session, send one prompt, then run `notifai doctor`',
     )
   }
   if (harnesses.has('opencode')) {
@@ -1095,7 +1327,6 @@ export async function acknowledgeCommand(
   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)
@@ -1114,7 +1345,7 @@ export async function acknowledgeCommand(
     logger.info('acknowledgement.outcome', {
       request_id: requestId,
       outcome: result.status,
-      text: result.agent_acknowledgement.text,
+      text_chars: result.agent_acknowledgement.text.length,
       created_at: result.agent_acknowledgement.created_at,
       agent_acknowledgement_required: true,
     })
@@ -1137,14 +1368,31 @@ export async function acknowledgeCommand(
 /** Retire a question so a late answer is rejected rather than silently lost. */
 export async function closeCommand(
   deps: CommandDeps,
-  requestId: string,
-  flags: { json?: boolean } = {},
+  requestId: string | undefined,
+  flags: { json?: boolean; pending?: boolean } = {},
 ): Promise<number> {
+  if (flags.pending === true && requestId !== undefined) {
+    deps.io.err('Pass a request id or --pending, not both.')
+    return EXIT.usage
+  }
+  if (flags.pending !== true && requestId === undefined) {
+    deps.io.err('Pass a request id or --pending.')
+    return EXIT.usage
+  }
+
+  if (flags.pending === true) {
+    return closePendingQuestions(deps, flags.json === true)
+  }
+
+  const local = await closeLocalQuestion(deps, requestId!, flags.json === true)
+  if (local !== null) return local
+
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const authed = authedClient(deps, config)
   if (!authed) return EXIT.auth
   try {
-    const response = await authed.client.closeReplies(requestId)
+    const response = await authed.client.closeReplies(requestId!)
+    forgetClosedQuestion(deps, requestId!)
     if (flags.json) {
       deps.io.out(
         JSON.stringify(
@@ -1172,6 +1420,176 @@ export async function closeCommand(
   }
 }
 
+/**
+ * Retire this session's outstanding questions, including registrations the
+ * Stop hook has not pushed yet. Unpushed entries only exist locally: dropping
+ * them is the whole retirement. Live ones still need their reply window closed.
+ */
+async function closePendingQuestions(deps: CommandDeps, json: boolean): Promise<number> {
+  const now = (deps.now ?? Date.now)()
+  const sessionId = readProjectSession(deps.cwd, deps.env, now)
+  if (sessionId === null) {
+    deps.io.err('No active session pointer is available in this directory.')
+    return EXIT.noReply
+  }
+  const pending = readSessionState(sessionId, deps.env).pending ?? []
+  if (pending.length === 0) {
+    if (json) {
+      deps.io.out(
+        JSON.stringify({ session_id: sessionId, withdrawn: [], closed: [] }, null, 2),
+      )
+    } else {
+      deps.io.err(`Session ${sessionId} has no registered question pending.`)
+    }
+    return EXIT.noReply
+  }
+
+  const withdrawn = withdrawUnpushedQuestions(sessionId, deps.env)
+  const live = (readSessionState(sessionId, deps.env).pending ?? []).filter(
+    (entry): entry is PendingQuestion & { request_id: string } =>
+      entry.request_id !== undefined,
+  )
+
+  const closed: string[] = []
+  if (live.length > 0) {
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+    const authed = authedClient(deps, config)
+    if (!authed) return EXIT.auth
+    for (const entry of live) {
+      try {
+        await authed.client.closeReplies(entry.request_id)
+        parkClosedQuestion(sessionId, deps.env, entry)
+        dropPendingQuestion(sessionId, deps.env, entry)
+        closed.push(entry.request_id)
+      } catch (err) {
+        return reportError(deps, err, { operation: 'close', request_id: entry.request_id })
+      }
+    }
+  }
+
+  const output = {
+    session_id: sessionId,
+    withdrawn: withdrawn.map((entry) => ({
+      question: entry.question,
+      ...(entry.question_id === undefined ? {} : { question_id: entry.question_id }),
+    })),
+    closed,
+  }
+  if (json) deps.io.out(JSON.stringify(output, null, 2))
+  else {
+    if (withdrawn.length > 0) {
+      deps.io.out(
+        withdrawn.length === 1
+          ? 'Withdrew 1 unpushed question so a later Stop will not send it.'
+          : `Withdrew ${withdrawn.length} unpushed questions so a later Stop will not send them.`,
+      )
+    }
+    for (const requestId of closed) {
+      deps.io.out(`Closed the reply window for ${requestId}.`)
+    }
+  }
+  return EXIT.ok
+}
+
+/**
+ * Close one outstanding question by the stable id `notifai ask` returned, or
+ * by a request id already on a device. Unpushed entries only exist locally.
+ * Returns null when this directory's session has no matching registration, so
+ * the caller can still close a live request id against the service.
+ */
+async function closeLocalQuestion(
+  deps: CommandDeps,
+  id: string,
+  json: boolean,
+): Promise<number | null> {
+  const now = (deps.now ?? Date.now)()
+  const sessionId = readProjectSession(deps.cwd, deps.env, now)
+  if (sessionId === null) return null
+  const entry = (readSessionState(sessionId, deps.env).pending ?? []).find(
+    (candidate) => candidate.question_id === id || candidate.request_id === id,
+  )
+  if (entry === undefined) return null
+
+  if (entry.request_id === undefined) {
+    dropPendingQuestion(sessionId, deps.env, entry)
+    const output = {
+      session_id: sessionId,
+      withdrawn: [
+        {
+          question: entry.question,
+          ...(entry.question_id === undefined ? {} : { question_id: entry.question_id }),
+        },
+      ],
+      closed: [] as string[],
+    }
+    if (json) deps.io.out(JSON.stringify(output, null, 2))
+    else {
+      deps.io.out(
+        `Withdrew unpushed question ${entry.question_id ?? id} so a later Stop will not send it.`,
+      )
+    }
+    return EXIT.ok
+  }
+
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  try {
+    const response = await authed.client.closeReplies(entry.request_id)
+    parkClosedQuestion(sessionId, deps.env, entry)
+    dropPendingQuestion(sessionId, deps.env, entry)
+    if (json) {
+      deps.io.out(
+        JSON.stringify(
+          {
+            ...response,
+            question_id: entry.question_id,
+            acknowledgement_command: acknowledgementCommand(
+              response.request_id,
+              response.agent_acknowledgement_required,
+              response.agent_acknowledgement_text_required,
+              response.agent_acknowledgement,
+              response.replies.length > 0,
+            ),
+          },
+          null,
+          2,
+        ),
+      )
+    } else {
+      deps.io.out(`Closed the reply window for ${entry.request_id}.`)
+      if (response.replies.length > 0) printAcknowledgementStatus(deps, response)
+    }
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err, { operation: 'close', request_id: entry.request_id })
+  }
+}
+
+function forgetClosedQuestion(deps: CommandDeps, requestId: string): void {
+  const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)())
+  if (sessionId === null) return
+  const entry = (readSessionState(sessionId, deps.env).pending ?? []).find(
+    (candidate) => candidate.request_id === requestId,
+  )
+  if (entry === undefined) return
+  parkClosedQuestion(sessionId, deps.env, entry)
+  dropPendingQuestion(sessionId, deps.env, entry)
+}
+
+function parkClosedQuestion(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  entry: PendingQuestion,
+): void {
+  try {
+    parkForRetirement(sessionId, env, entry, 'expired')
+  } catch {
+    // Incomplete identifiers cannot be retired on a device; dropping the
+    // local record is still the right way to stop a later Stop from waiting.
+  }
+}
+
 export interface HooksInstallFlags {
   harness?: string
   global?: boolean
@@ -1220,12 +1638,20 @@ function resolveHookAdapterTarget(deps: CommandDeps, flags: HooksInstallFlags):
 
 function printHooksInstallClose(deps: CommandDeps, harness: Harness, file: string): void {
   const label = HARNESS_LABELS[harness]
+  const activation =
+    harness === 'codex'
+      ? 'Approve the Notifai handlers in `/hooks` if Codex asks, then start one fresh Codex session, send one prompt, and run `notifai doctor`.'
+      : harness === 'cursor'
+        ? 'Start one fresh Cursor conversation, send one prompt, finish its first turn, then run `notifai doctor`.'
+        : harness === 'opencode'
+          ? 'Restart OpenCode, start one fresh session, send one prompt, then run `notifai doctor`.'
+          : `Start one fresh ${label} session, send one prompt, then run \`notifai doctor\`.`
   if (deps.io.interactive === true && deps.io.note) {
-    void deps.io.note(`${file}\nSend one ${label} prompt, then run \`notifai doctor\`.`, `${label} hooks installed`)
+    void deps.io.note(`${file}\n${activation}`, `${label} hooks installed`)
     return
   }
   deps.io.out(`Installed ${harness} hooks in ${file}`)
-  deps.io.out(`Send one ${label} prompt, then check \`notifai doctor\`.`)
+  deps.io.out(activation)
 }
 
 export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags): number {
@@ -1261,7 +1687,26 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   )
   const otherScope = existing.filter((installation) => installation.global !== wantGlobal)
   if (!wantGlobal && otherScope.some((installation) => installation.global)) {
-    const globalFile = otherScope.find((installation) => installation.global)?.file
+    const globalInstallations = otherScope.filter((installation) => installation.global)
+    const globalInstallation = globalInstallations[0]
+    const installedEvents = new Set(
+      globalInstallation?.handlers
+        .map((handler) => handlerEvent(handler.command))
+        .filter((event): event is HookEvent =>
+          event !== null && (HOOK_EVENTS as readonly string[]).includes(event),
+        ) ?? [],
+    )
+    if (
+      globalInstallations.length !== 1 ||
+      globalInstallations.some((installation) => (installation.problems?.length ?? 0) > 0) ||
+      globalInstallations.some(
+        (installation) => stopShapeProblems(installation, deps.hookPlatform).length > 0,
+      ) ||
+      !requiredHookEvents(harness).every((event) => installedEvents.has(event))
+    ) {
+      return hooksInstallCommand(deps, { ...flags, global: true, harness })
+    }
+    const globalFile = globalInstallation?.file
     deps.io.out(
       `${HARNESS_LABELS[harness]} hooks already cover this machine (${globalFile}). This project does not need its own copy. To wire only this project: notifai hooks uninstall --harness ${harness} --global && notifai hooks install --harness ${harness}`,
     )
@@ -1337,7 +1782,22 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
     installed =
       codexPaths === null
         ? withTargetFileLock(settingsTarget, () => installInto(settingsTarget))
-        : withCodexLayerTransaction(codexPaths, (inspection) => installInto(inspection.writeTarget))
+        : withCodexLayerTransaction(codexPaths, (inspection) => {
+            const staleTarget =
+              inspection.writeTarget === inspection.paths.hooksJson
+                ? inspection.paths.configToml
+                : inspection.paths.hooksJson
+            const staleEvents =
+              staleTarget === inspection.paths.hooksJson
+                ? inspection.ourJsonEvents
+                : inspection.ourTomlEvents
+            if (staleEvents.length > 0) {
+              const staleDocument = loadSettings(staleTarget)
+              const stripped = removeHooks(staleDocument, scriptPath)
+              if (stripped.replaced.length > 0) applyPlan(staleTarget, stripped.document)
+            }
+            return installInto(inspection.writeTarget)
+          })
   } catch (err) {
     deps.io.err(String(err))
     return EXIT.failed
@@ -1373,7 +1833,12 @@ function foreignStopHandlers(document: { hooks?: Record<string, { hooks?: { comm
   if (!Array.isArray(groups)) return []
   return groups
     .flatMap((group) => group.hooks ?? [])
-    .filter((handler) => !/ hook (user-prompt-submit|stop|session-end)\b/.test(handler.command))
+    .filter(
+      (handler) =>
+        !/ hook (session-start|subagent-start|activation-stop|user-prompt-submit|stop|session-end)\b/.test(
+          handler.command,
+        ),
+    )
 }
 
 /**
@@ -1503,7 +1968,11 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
     result =
       codexPaths === null
         ? removeInstalledHooks()
-        : withCodexLayerTransaction(codexPaths, removeInstalledHooks)
+        : withCodexLayerTransaction(codexPaths, (inspection) => {
+            const stripped = removeInstalledHooks()
+            cleanupEmptiedCodexLayer(inspection.paths)
+            return stripped
+          })
   } catch (err) {
     deps.io.err(String(err))
     return EXIT.failed