codex-copilot-dx 0.9.22 → 0.9.23

package/README.md

@@ -71,8 +71,10 @@ The dashboard does not poll in the background; refresh when needed.
   `gpt-6-luna`, with `low` reasoning when advertised. Requires a running local
   adapter and a recent Codex with paginated thread reads and MCP draft support.
 - Suggestions read only a bounded page from the host-identified current thread.
-  Images, reasoning items and tool outputs are excluded. There is no background
-  prediction or startup hook; selecting a model alone does not enable the feature.
+  Images, reasoning items and tool outputs are excluded. On supported runtimes,
+  `suggestion on` configures an async Stop hook; review it in Codex before it runs.
+  CCDX never grants trust. The panel reads saved suggestions; adding drafts is manual.
+  The dashboard shows settings and generation status. Model selection alone stays off.
   Existing user-managed MCP/profile configuration is preserved. Native prediction
   settings are untouched; account/remote defaults in all future clients cannot be
   reliably detected. Use `ccdx suggestion off` when preferring an official feature.

package/docs/REFERENCE.md

@@ -9,7 +9,7 @@ CCDX is a local compatibility adapter for Codex App. It configures Codex to use
 ### Optional next-message suggestions
 
 Suggestions are disabled by default. No suggestion MCP or skill is installed at
-startup, and the primary adapter does not import or start a predictor.
+startup, and the primary adapter does not start a predictor.
 
 ```bash
 ccdx suggestion on
@@ -23,7 +23,7 @@ Start CCDX, enable suggestions, then open **Next message / 下一句** from a lo
 conversation panel, or ask Codex for a next-message suggestion. **Add to draft /
 加入草稿** appends ordinary text and never sends. The user still presses Send.
 If the MCP has not appeared in an open App, restart the App once. There is no
-client patch, grey ghost text, automatic background prediction, or auto-approval.
+client patch, grey ghost text, automatic draft insertion, or auto-approval.
 Model selection alone keeps the feature disabled. The initial model is
 `gpt-6-luna`; `low` reasoning is used when advertised. No service tier is forced.
 
@@ -44,7 +44,8 @@ The MCP uses the host-supplied thread ID and the installed Codex's paginated
 user/assistant text excerpts and 16,000 characters. Images, reasoning items and
 tool outputs are excluded; there is no transcript scan, fork or resumed turn.
 Recent text is sent through the local CCDX adapter to the selected Copilot model
-only when the user requests a suggestion. Provider data policies still apply.
+when requested manually, or after a reply through the separately reviewed optional
+hook described below. Provider data policies still apply.
 Context lookup is capped at 5 seconds/2 MiB, the operation at 30 seconds, output
 at 64 KiB/300 characters, concurrent work at two, and in-memory candidates at 16.
 Candidates expire for adoption after 10 minutes and are bound to their thread
@@ -53,6 +54,31 @@ No additional retry is added by the suggestion feature. Existing adapter policie
 remain unchanged. App support requires MCP draft insertion; the executable can
 be selected explicitly with `CCDX_CODEX_BINARY` when automatic discovery fails.
 
+On supported macOS/Linux Codex runtimes, `suggestion on` also registers an
+asynchronous `Stop` hook. It generates after a finished reply only after the user
+reviews and trusts that exact `suggestion-auto.mjs` command through Codex's normal
+hook review screen (`/hooks` in Codex CLI). CCDX never writes hook trust or bypasses
+review. Existing handlers and native prediction settings are preserved. Windows,
+unsupported hook runtimes and conflicting hook declarations keep the manual panel.
+Existing 0.9.22 users can run `ccdx suggestion on` once to configure the hook.
+
+Automatic work has one local slot, a 30-second deadline, no added retries and one
+attempt per observed turn. It checks the latest turn before and after inference;
+newer turns or changed settings discard the result. The hook does not start a new
+turn, send a message, edit a draft or wait on the foreground reply. Enabled users
+incur additional selected-model usage after replies. `suggestion off` removes only
+the unchanged CCDX hook and disables both automatic and manual requests.
+
+Only the candidate and generation metadata are saved locally in `suggestion-state`
+beside settings, with at most 32 entries. Candidates expire for adoption after ten
+minutes; stale files are pruned on the next automatic operation. No context excerpts
+are saved there. The loopback dashboard reads settings and safe recent status only;
+it does not invoke a model or confirm hook trust. Refresh it after changing settings.
+Opening Next message reads a current cached candidate without a second model call.
+The user must still choose **Add to draft**, then Send. Closed panels cannot access
+the composer, and the host exposes no atomic empty-draft insertion; automatic
+draft filling is therefore intentionally unavailable.
+
 ### Core adapter
 
 One in-process adapter listens on `127.0.0.1:2026` by default and exposes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/adapter.mjs

@@ -64,7 +64,7 @@ export {
 
 const ADAPTER_RUNTIME_CONFIG = loadRuntimeConfig();
 const DASHBOARD_PATHS = new Set(["/", "/ui.css", "/theme.js", "/language.js", "/ui.js"]);
-const DASHBOARD_API_PATHS = new Set(["/_ccdx/ui/animation", "/_ccdx/ui/models/live", "/_ccdx/ui/usage", "/_ccdx/ui/auth"]);
+const DASHBOARD_API_PATHS = new Set(["/_ccdx/ui/animation", "/_ccdx/ui/models/live", "/_ccdx/ui/usage", "/_ccdx/ui/auth", "/_ccdx/ui/suggestion"]);
 
 export function requestPath(reqUrl) {
   return new URL(reqUrl || "/", "http://localhost").pathname;

package/src/cli-suggestion.mjs

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { atomicWriteFileIfChangedSync, atomicWriteFilePairSync } from "./atomic-file.mjs";
 import { loadAutoReviewModelCatalog } from "./auto-review-model.mjs";
 import { parseAdapterAddressOptions } from "./cli-options.mjs";
@@ -9,12 +11,20 @@ import { adapterBaseUrl } from "./running-adapter.mjs";
 import { terminalCell } from "./cli-table.mjs";
 import { resolveSuggestionCodexBinary } from "./suggestion-context.mjs";
 import { suggestionAdapterUrl } from "./suggestion-provider.mjs";
-import { computeSuggestionMcpConfig, readSuggestionCodexConfig, readSuggestionConfig, suggestionCodexConfigPath, suggestionConfigPath } from "./suggestion-config.mjs";
+import { computeSuggestionAutoHook, computeSuggestionMcpConfig, readSuggestionCodexConfig, readSuggestionConfig, suggestionCodexConfigPath, suggestionConfigPath } from "./suggestion-config.mjs";
+
+export async function supportsSuggestionHooks(binary) {
+  const directory=fs.mkdtempSync(path.join(os.tmpdir(),"ccdx-hook-probe-"));
+  try {
+    const {stdout}=await promisify(execFile)(binary,["features","list"],{cwd:directory,env:{CODEX_HOME:directory,PATH:process.env.PATH||""},timeout:1500,maxBuffer:128*1024,encoding:"utf8"});
+    return /^hooks\s+(?:stable|beta|experimental|under development)\s+true\s*$/m.test(stdout);
+  } catch {return false;} finally {fs.rmSync(directory,{recursive:true,force:true});}
+}
 
 export async function runSuggestionCommand({
   action = "status", model, commandName = "ccdx", env = process.env, home = os.homedir(),
   input = process.stdin, output = process.stdout, prompt,
-  loadCatalog = loadAutoReviewModelCatalog, resolveBinary = resolveSuggestionCodexBinary,
+  loadCatalog = loadAutoReviewModelCatalog, resolveBinary = resolveSuggestionCodexBinary, probeHooks = supportsSuggestionHooks,
 } = {}) {
   const filePath = suggestionConfigPath({ env, home });
   const codexPath = suggestionCodexConfigPath({ env, home });
@@ -25,7 +35,7 @@ export async function runSuggestionCommand({
     output.write(`Next-message suggestions: ${current.enabled ? "enabled" : "disabled"}\nModel: ${terminalCell(current.model)}\n`);
     if (preview.skipped) output.write(`${preview.reason}\n`);
     else if (current.enabled && preview.changed) output.write(`MCP registration is missing or disabled. Run ${commandName} suggestion on to repair it.\n`);
-    output.write("Ordinary draft only; no automatic sending or client patch.\n");
+    output.write(`Automatic generation: ${current.enabled && current.automatic ? "configured; Codex hook review is required before it can run" : "unavailable or not configured"}\nAutomatic draft insertion: unavailable; choose Add to draft.\n`);
     return { ...current, configured: !preview.changed && !preview.skipped };
   }
   if (!["on", "off", "model"].includes(action)) throw new Error("Suggestion action must be on, off, model, or status");
@@ -33,7 +43,8 @@ export async function runSuggestionCommand({
     output.write(`${preview.reason}. No changes made.\n`);
     return { changed: false, skipped: true };
   }
-  if (action === "on" && current.enabled && !preview.changed) {
+  const hookPreview=computeSuggestionAutoHook(original,{filePath,enabled:current.enabled&&current.automatic===true});
+  if (action === "on" && current.enabled && current.automatic !== undefined && !preview.changed && !hookPreview.changed) {
     output.write("Suggestions are already configured; kept unchanged.\n");
     return { changed: false, ...current };
   }
@@ -67,6 +78,11 @@ export async function runSuggestionCommand({
   }
   // Re-read both files after asynchronous model lookup/prompts; never overwrite
   // concurrent user edits or unrelated shared settings.
+  let binary,hookSupported=false;
+  if(action==="on" || action==="model" && current.enabled){
+    binary=resolveBinary(env);
+    hookSupported=process.platform!=="win32"&&await probeHooks(binary);
+  }
   const latest = readSuggestionConfig({ filePath, strict: true });
   if (action !== "model") {
     selected = latest.model;
@@ -80,21 +96,24 @@ export async function runSuggestionCommand({
     output.write(`${codex.reason}. No changes made.\n`);
     return { changed: false, skipped: true };
   }
-  const next = { ...latest, enabled, model: selected, reasoning_effort: reasoning ?? null };
+  const hook=computeSuggestionAutoHook(codex.content,{filePath,enabled:enabled&&hookSupported});
+  const next = { ...latest, enabled, model: selected, reasoning_effort: reasoning ?? null, automatic:enabled&&hookSupported&&!hook.skipped };
   if (enabled) {
     const address = parseAdapterAddressOptions(env);
     const host = ["0.0.0.0", "localhost"].includes(address.adapterHost) ? "127.0.0.1" : address.adapterHost === "::" ? "::1" : address.adapterHost;
     next.adapter_url = suggestionAdapterUrl(`${adapterBaseUrl(host, address.adapterPort)}/v1`);
-    next.codex_binary = resolveBinary(env);
+    next.codex_binary = binary;
     next.codex_home = path.dirname(codexPath);
   }
   const serialized = `${JSON.stringify(next, null, 2)}\n`;
   let changed;
-  if (codex.changed && !codex.skipped) {
-    atomicWriteFilePairSync(codexPath, codex.content, filePath, serialized, { writeFile: atomicWriteFileIfChangedSync });
+  if ((codex.changed || hook.changed) && !codex.skipped) {
+    atomicWriteFilePairSync(codexPath, hook.content, filePath, serialized, { writeFile: atomicWriteFileIfChangedSync });
     changed = true;
   } else changed = atomicWriteFileIfChangedSync(filePath, serialized);
   output.write(`Suggestions: ${next.enabled ? "enabled" : "disabled"}\nModel: ${terminalCell(next.model)}\n`);
+  output.write(`Automatic generation: ${next.automatic?"configured; review this CCDX Stop hook in Codex before it can run":"unavailable or disabled"}\nDraft insertion: choose Add to draft; never sends automatically.\n`);
+  if(next.automatic)output.write("Use Codex's hook review screen (or /hooks in Codex CLI). Trust only the CCDX suggestion-auto.mjs command. CCDX never grants hook trust.\n");
   if (codex.skipped) output.write(`${codex.reason}. CCDX suggestion requests are disabled.\n`);
   if (enabled) output.write("Open Next message in the conversation panel, or ask Codex for a next-message suggestion. Add to draft never sends.\nIf the tool is not visible, restart Codex App once. Official prediction settings are not modified.\n");
   return { ...next, changed };

package/src/dashboard/index.html

@@ -50,6 +50,12 @@
           </article>
         </section>
 
+        <section class="panel dashboard-section" id="suggestion-panel">
+          <div class="panel-heading"><h2 data-i18n>NEXT MESSAGE</h2><span data-i18n>OPTIONAL</span></div>
+          <dl class="stats"><div><dt data-i18n>Status</dt><dd id="suggestion-enabled">—</dd></div><div><dt data-i18n>Model</dt><dd id="suggestion-model">—</dd></div><div><dt data-i18n>Auto generation</dt><dd id="suggestion-auto">—</dd></div><div><dt data-i18n>Draft insertion</dt><dd data-i18n>Choose Add to draft</dd></div></dl>
+          <p id="suggestion-recent" class="hint" role="status">—</p><p id="suggestion-detail" class="hint">—</p><p class="hint"><span data-i18n>Commands</span>: <code>ccdx suggestion on|off|model|status</code></p>
+        </section>
+
         <details class="panel dashboard-section" id="request-context">
           <summary data-i18n>RECENT REQUEST CONTEXT</summary>
           <p id="context-note" class="table-note">—</p>

package/src/dashboard/language.js

@@ -1,5 +1,26 @@
 (() => {
   const translations = {
+    "NEXT MESSAGE":["NEXT MESSAGE","下一句"],
+    "Status":["Status","状态"],
+    "Auto generation":["Auto generation","自动生成"],
+    "Configured; review hook":["Configured; review hook","已配置，需审核"],
+    "{time} / {reason}":["{time} / {reason}","{time} / {reason}"],
+    "Context unavailable":["Context unavailable","无法读取对话。"],
+    "Model request failed":["Model request failed","模型请求失败。"],
+    "Settings changed":["Settings changed","设置已变化。"],
+    "Conversation changed":["Conversation changed","对话已变化。"],
+    "Suggestion timed out":["Suggestion timed out","建议生成超时。"],
+    "No recorded error":["No recorded error","暂无错误记录。"],
+    "Draft insertion":["Draft insertion","加入草稿"],
+    "Choose Add to draft":["Click to add","点击加入"],
+    "Commands":["Commands","命令"],
+    "No automatic suggestion yet":["No automatic suggestion yet.","暂无自动建议。"],
+    "Generating suggestion":["Generating…","正在生成。"],
+    "Suggestion ready; open Next message":["Ready. Open Next message.","已生成，请打开下一句。"],
+    "No useful suggestion":["No useful suggestion.","暂无合适建议。"],
+    "Suggestion failed; retry manually":["Failed. Retry in Next message.","生成失败，请手动重试。"],
+    "Suggestion cancelled":["Cancelled.","已取消。"],
+    "Run ccdx suggestion status":["Run ccdx suggestion status.","请用命令检查设置。"],
     "First output": ["First output", "首次输出"],
     "Token time": ["Token time", "输出耗时"],
     "Gateway timing. Token time is estimated.": ["Observed at the gateway. Token time is an estimate.", "网关观测时间。\n每Token耗时为估算值。"],

package/src/dashboard/ui.js

@@ -16,6 +16,7 @@ const finite = (value) => value !== null && value !== undefined && Number.isFini
 const number = (value) => finite(value) ? Math.max(0, Math.round(Number(value))).toLocaleString() : "—";
 const mib = (value) => finite(value) ? `${(Number(value) / 1048576).toFixed(1)} MiB` : "—";
 let authLoading = false;
+let suggestionLoading=false;
 let contextRequests = [];
 let contextCompactions = {};
 
@@ -40,6 +41,23 @@ async function loadAuth() {
   } finally { authLoading = false; }
 }
 
+async function loadSuggestion(){
+  if(suggestionLoading)return;
+  suggestionLoading=true;
+  try{
+    const response=await fetch("/_ccdx/ui/suggestion",{cache:"no-store",headers:{"X-CCDX-Dashboard":"1"},signal:AbortSignal.timeout(5000)});
+    const data=await response.json();
+    if(!response.ok||data.source!=="local_suggestion_settings")throw new Error();
+    text("suggestion-enabled",data.enabled?"ENABLED":"DISABLED");
+    element("suggestion-model").textContent=data.model;
+    text("suggestion-auto",data.automatic_generation_configured?"Configured; review hook":"DISABLED");
+    const state={idle:"No automatic suggestion yet",generating:"Generating suggestion",ready:"Suggestion ready; open Next message",empty:"No useful suggestion",failed:"Suggestion failed; retry manually",cancelled:"Suggestion cancelled",unknown:"Unknown"}[data.recent?.state]||"Unknown";
+    text("suggestion-recent",state);
+    text("suggestion-detail","{time} / {reason}",{time:data.recent?.at?new Date(data.recent.at).toLocaleTimeString():"—",reason:phrase({context_unavailable:"Context unavailable",model_failed:"Model request failed",settings_changed:"Settings changed",turn_changed:"Conversation changed",timeout:"Suggestion timed out"}[data.recent?.reason]||"No recorded error")});
+  }catch{text("suggestion-enabled","UNAVAILABLE");element("suggestion-model").textContent="—";text("suggestion-auto","UNAVAILABLE");text("suggestion-recent","Run ccdx suggestion status");element("suggestion-detail").textContent="—";}
+  finally{suggestionLoading=false;}
+}
+
 function duration(value) {
   if (!finite(value)) return "—";
   const seconds = Math.max(0, Math.round(Number(value) / 1000));
@@ -223,10 +241,11 @@ async function refresh() {
   }
 }
 
-element("refresh").addEventListener("click", () => { refresh(); loadAuth(); });
+element("refresh").addEventListener("click", () => { refresh(); loadAuth(); loadSuggestion(); });
 element("request-context").addEventListener("toggle", () => { if (element("request-context").open) renderContext(); });
 refresh();
 loadAuth();
+loadSuggestion();
 
 const animationRows = new Map();
 let animationTimelines = [];

package/src/dashboard-api.mjs

@@ -15,11 +15,14 @@ import { cacheReadTokens, summarizeUsageLogs, usageCacheHitRate } from "./usage-
 import { createUsageAnalytics } from "./usage-analytics.mjs";
 import { analyzeUsageLogs } from "./usage-analysis.mjs";
 import { readUserSettings, terminalAnimationPreference, writeTerminalAnimationTheme } from "./user-settings.mjs";
+import { readSuggestionConfig, suggestionConfigPath } from "./suggestion-config.mjs";
+import { automaticSuggestionStatus } from "./suggestion-auto.mjs";
 
 const ANIMATION_PATH = "/_ccdx/ui/animation";
 const MODELS_PATH = "/_ccdx/ui/models/live";
 const USAGE_PATH = "/_ccdx/ui/usage";
 const AUTH_PATH = "/_ccdx/ui/auth";
+const SUGGESTION_PATH = "/_ccdx/ui/suggestion";
 const DISABLED_ANIMATION = /^(0|false|no|off)$/i;
 
 function sendJson(res, statusCode, value) {
@@ -146,6 +149,15 @@ export async function handleDashboardApi(req, res, pathname, {
     }
     return;
   }
+  if(pathname===SUGGESTION_PATH && req.method==="GET"){
+    try{
+      const filePath=suggestionConfigPath({env,home}),config=readSuggestionConfig({filePath,strict:true});
+      sendJson(res,200,{source:"local_suggestion_settings",enabled:config.enabled,model:config.model,
+        automatic_generation_configured:config.enabled&&config.automatic===true,hook_trust:"unknown",automatic_insertion:false,
+        recent:config.enabled?automaticSuggestionStatus(filePath):{state:"idle",at:null,reason:null}});
+    }catch{sendJson(res,409,{error:"Suggestion settings are invalid; run ccdx suggestion status"})}
+    return;
+  }
 
   if (pathname === ANIMATION_PATH && req.method === "GET") {
     try {

package/src/suggestion-auto.mjs

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
+import { readSuggestionConfig, suggestionConfigPath } from "./suggestion-config.mjs";
+import { readSuggestionContext } from "./suggestion-context.mjs";
+import { generateSuggestion } from "./suggestion-provider.mjs";
+
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const RETENTION_MS = 10 * 60_000;
+function storeDirectory(filePath) { return path.join(path.dirname(filePath), "suggestion-state"); }
+function keyFile(filePath, threadId) {
+  if (!UUID.test(threadId)) throw new Error("Invalid suggestion conversation ID");
+  return path.join(storeDirectory(filePath), `${createHash("sha256").update(threadId).digest("hex")}.json`);
+}
+function readRecord(file) {
+  try {
+    const stat=fs.lstatSync(file);
+    if (!stat.isFile() || stat.size > 8192) return null;
+    const record = JSON.parse(fs.readFileSync(file,"utf8"));
+    return record && typeof record === "object" && !Array.isArray(record) ? record : null;
+  } catch { return null; }
+}
+export function readAutomaticSuggestion(filePath, threadId) { return readRecord(keyFile(filePath, threadId)); }
+function save(filePath, threadId, record) { atomicWriteFileIfChangedSync(keyFile(filePath,threadId),JSON.stringify(record)+"\n"); }
+function cleanup(directory, now) {
+  const files = fs.readdirSync(directory).filter(name=>/^[a-f0-9]{64}\.json$/.test(name));
+  const retained = [];
+  for (const name of files) {
+    const file=path.join(directory,name),record=readRecord(file);
+    if (!record || !Number.isFinite(record.at) || now-record.at>RETENTION_MS) fs.unlinkSync(file);
+    else retained.push({file,at:record.at});
+  }
+  retained.sort((a,b)=>b.at-a.at);
+  for(const record of retained.slice(31))fs.unlinkSync(record.file);
+}
+export function automaticSuggestionStatus(filePath, now = Date.now()) {
+  try {
+    const directory=storeDirectory(filePath);
+    const records=fs.readdirSync(directory).filter(name=>/^[a-f0-9]{64}\.json$/.test(name)).slice(0,64)
+      .map(name=>readRecord(path.join(directory,name))).filter(record=>record && Number.isFinite(record.at)&&now-record.at<=RETENTION_MS);
+    const recent=records.sort((a,b)=>b.at-a.at)[0];
+    return recent ? { state:["generating","ready","empty","failed","cancelled"].includes(recent.state)?recent.state:"unknown",
+      at:new Date(recent.at).toISOString(),reason:["context_unavailable","model_failed","settings_changed","turn_changed","timeout"].includes(recent.reason)?recent.reason:null } : {state:"idle",at:null,reason:null};
+  } catch { return {state:"idle",at:null,reason:null}; }
+}
+
+export async function runAutomaticSuggestion(event, {
+  filePath = suggestionConfigPath(), readContext = readSuggestionContext, generate = generateSuggestion,
+  now = Date.now, timeoutMs = 30_000,
+} = {}) {
+  const config=readSuggestionConfig({filePath});
+  if(!config.enabled || !config.automatic || event?.hook_event_name!=="Stop" || event.stop_hook_active===true
+    || !UUID.test(event.session_id||"") || !UUID.test(event.turn_id||"")) return {skipped:true};
+  const threadId=event.session_id,turnId=event.turn_id,directory=storeDirectory(filePath);
+  fs.mkdirSync(directory,{recursive:true,mode:0o700});
+  if(!fs.lstatSync(directory).isDirectory())return {skipped:true};
+  cleanup(directory,now());
+  const prior=readAutomaticSuggestion(filePath,threadId);
+  if(prior?.turnId===turnId)return {skipped:true};
+  // One local slot bounds independent asynchronous hook processes. Only owned
+  // lock files are reclaimed after their 30-second operation deadline.
+  let lock;
+  for(let slot=0;slot<1;slot++){
+    const file=path.join(directory,`slot-${slot}.lock`);
+    try{if(now()-fs.statSync(file).mtimeMs>60_000)fs.unlinkSync(file)}catch(error){if(error.code!=="ENOENT")return {skipped:true}}
+    try{const fd=fs.openSync(file,"wx",0o600);fs.closeSync(fd);lock=file;break}catch(error){if(error.code!=="EEXIST")return {skipped:true}}
+  }
+  if(!lock)return {skipped:true,busy:true};
+  const abort=new AbortController(),timer=setTimeout(()=>abort.abort(),timeoutMs);
+  let stage="context_unavailable";
+  try {
+    // The slot acquisition and marker commit are synchronous within this process.
+    if(readAutomaticSuggestion(filePath,threadId)?.turnId===turnId)return {skipped:true};
+    save(filePath,threadId,{state:"generating",at:now(),turnId,model:config.model});
+    const page=await readContext(threadId,config,{signal:abort.signal,includePage:true});
+    if(page.latestTurnId!==turnId){save(filePath,threadId,{state:"cancelled",at:now(),turnId,model:config.model,reason:"turn_changed"});return {skipped:true};}
+    const current=readSuggestionConfig({filePath});
+    if(!current.enabled||!current.automatic||current.model!==config.model||current.adapter_url!==config.adapter_url){stage="settings_changed";throw new Error();}
+    stage="model_failed";
+    const suggestion=await generate(page.messages,config,{signal:abort.signal});
+    abort.signal.throwIfAborted();
+    const latest=readSuggestionConfig({filePath});
+    if(!latest.enabled||!latest.automatic||latest.model!==config.model||latest.adapter_url!==config.adapter_url){stage="settings_changed";throw new Error();}
+    stage="context_unavailable";
+    const finalPage=await readContext(threadId,config,{signal:abort.signal,includePage:true});
+    if(finalPage.latestTurnId!==turnId){stage="turn_changed";throw new Error();}
+    const result={state:suggestion?"ready":"empty",at:now(),turnId,model:config.model,suggestion,candidate_id:suggestion?randomUUID():null};
+    save(filePath,threadId,result);return result;
+  } catch {
+    const result={state:abort.signal.aborted?"cancelled":"failed",at:now(),turnId,model:config.model,reason:abort.signal.aborted?"timeout":stage};
+    // Don't overwrite a newer hook's marker.
+    if(readAutomaticSuggestion(filePath,threadId)?.turnId===turnId)save(filePath,threadId,result);
+    return result;
+  } finally {clearTimeout(timer);try{fs.unlinkSync(lock)}catch{}}
+}
+
+async function main(){
+  let chunks=[],bytes=0;
+  for await(const chunk of process.stdin){bytes+=chunk.length;if(bytes>64*1024)return;chunks.push(chunk)}
+  let event;try{event=JSON.parse(Buffer.concat(chunks).toString("utf8"))}catch{return}
+  // Informational hook: no continuation, warnings, approval or user messages.
+  await runAutomaticSuggestion(event);
+  process.stdout.write("{}\n");
+}
+if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href)main().catch(()=>{process.stdout.write("{}\n")});

package/src/suggestion-config.mjs

@@ -19,6 +19,7 @@ export function readSuggestionConfig({ filePath = suggestionConfigPath(), strict
     const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
     if (!value || typeof value !== "object" || Array.isArray(value)
       || typeof value.enabled !== "boolean"
+      || (value.automatic !== undefined && typeof value.automatic !== "boolean")
       || typeof value.model !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value.model)) throw new Error();
     return value;
   } catch (error) {
@@ -64,6 +65,26 @@ export function computeSuggestionMcpConfig(content, { enabled, filePath }) {
   return { content: updated, changed: true };
 }
 
+export function computeSuggestionAutoHook(content, { enabled, filePath }) {
+  const parsed=parseCodexToml(content);
+  const quote=value=>`'${value.replaceAll("'", "'\\''")}'`;
+  const command=`CCDX_SUGGESTION_CONFIG=${quote(filePath)} ${quote(process.execPath)} ${quote(fileURLToPath(new URL("./suggestion-auto.mjs",import.meta.url)))}`;
+  const start="# ccdx:suggestion-auto:start",end="# ccdx:suggestion-auto:end";
+  const block=`${start}\n[[hooks.Stop]]\n[[hooks.Stop.hooks]]\ntype = "command"\ncommand = ${JSON.stringify(command)}\nasync = true\ntimeout = 35\n${end}\n`;
+  const owned=content.indexOf(start);
+  if(owned>=0){
+    if(!content.includes(block)||content.indexOf(start,owned+start.length)!==-1)return {content,changed:false,skipped:true};
+    if(enabled)return {content,changed:false};
+    const updated=content.replace(block,"");validateManagedConfigEdit(parsed,updated,[["hooks","Stop"]]);return {content:updated,changed:true};
+  }
+  if(!enabled)return {content,changed:false};
+  if(process.platform==="win32")return {content,changed:false,skipped:true};
+  const statements=codexTomlStatements(content);
+  if(statements.some(item=>item.kind==="value"&&item.keys[0]==="hooks"&&(item.keys.length===1||item.keys.length===2&&item.keys[1]==="Stop")))return {content,changed:false,skipped:true};
+  const updated=content+(content.endsWith("\n")?"\n":"\n\n")+block;
+  validateManagedConfigEdit(parsed,updated,[["hooks","Stop"]]);return {content:updated,changed:true};
+}
+
 export function suggestionCodexConfigPath({ env = process.env, home = os.homedir() } = {}) {
   return path.join(env.CODEX_HOME || path.join(home, ".codex"), "config.toml");
 }

package/src/suggestion-context.mjs

@@ -47,7 +47,7 @@ export function contextMessages(entries) {
 
 // Use the client's paginated reader: no transcript scans, SQLite access, forks,
 // turn starts, or writes to the user's conversation. Zstandard remains its job.
-export function readSuggestionContext(threadId, config, { signal, spawnFn = spawn } = {}) {
+export function readSuggestionContext(threadId, config, { signal, spawnFn = spawn, includePage = false } = {}) {
   if (!UUID.test(threadId)) return Promise.reject(new Error("Invalid conversation ID"));
   return new Promise((resolve, reject) => {
     const decoder = new StringDecoder("utf8");
@@ -95,7 +95,8 @@ export function readSuggestionContext(threadId, config, { signal, spawnFn = spaw
           } else {
             if (!Array.isArray(reply.result?.data)) { finish(new Error("Invalid conversation page")); return; }
             const messages = contextMessages(reply.result.data);
-            finish(messages.length ? null : new Error("No recent text messages are available for a suggestion"), messages);
+            finish(messages.length ? null : new Error("No recent text messages are available for a suggestion"), includePage
+              ? { messages, latestTurnId: reply.result.data[0]?.turnId || null } : messages);
           }
         }
       });

package/src/suggestion-mcp.mjs

@@ -5,6 +5,7 @@ import { StringDecoder } from "node:string_decoder";
 import { readSuggestionConfig, suggestionConfigPath } from "./suggestion-config.mjs";
 import { readSuggestionContext, suggestionThreadId } from "./suggestion-context.mjs";
 import { generateSuggestion } from "./suggestion-provider.mjs";
+import { readAutomaticSuggestion } from "./suggestion-auto.mjs";
 
 const URI = "ui://ccdx-suggestion/panel.html";
 const protocolVersions = new Set(["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28"]);
@@ -23,12 +24,19 @@ export const SUGGESTION_TOOLS = [
     annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
     _meta: { ui: { visibility: ["app"] } },
   },
+  {
+    name:"latest_suggestion",title:"Read latest suggestion",
+    description:"Read an already-generated candidate for this local conversation. Does not invoke a model or edit a draft.",
+    inputSchema:{type:"object",properties:{},additionalProperties:false},
+    annotations:{readOnlyHint:true,openWorldHint:false,destructiveHint:false},_meta:{ui:{visibility:["app"]}},
+  },
 ];
 
 export function createSuggestionMcp({
   loadConfig = () => readSuggestionConfig({ filePath: suggestionConfigPath() }),
   readContext = readSuggestionContext, generate = generateSuggestion,
   now = Date.now, timeoutMs = 30_000,
+  loadAutomatic = threadId => readAutomaticSuggestion(suggestionConfigPath(),threadId),
 } = {}) {
   const candidates = new Map();
   let active = 0;
@@ -55,10 +63,24 @@ export function createSuggestionMcp({
     const args = request.params?.arguments || {};
     if (typeof args !== "object" || Array.isArray(args)) throw new Error("Invalid suggestion parameters");
     prune();
+    const automatic = () => {
+      const item=loadAutomatic(threadId);
+      return item?.state==="ready" && typeof item.suggestion==="string" && item.suggestion.length<=300
+        && typeof item.candidate_id==="string" && item.model===config.model && Number.isFinite(item.at) && now()-item.at<=10*60_000 ? item : null;
+    };
+    if(request.params.name==="latest_suggestion"){
+      if(Object.keys(args).length)throw new Error("Invalid latest suggestion parameters");
+      const item=automatic();return result(item?{suggestion:item.suggestion,candidate_id:item.candidate_id,model:item.model}:{suggestion:null,candidate_id:null,model:config.model});
+    }
     if (request.params.name === "prepare_suggestion_draft") {
       if (Object.keys(args).some(key => key !== "candidate_id")) throw new Error("Invalid draft parameters");
-      const item = candidates.get(args.candidate_id);
+      const stored=automatic();
+      const item = candidates.get(args.candidate_id) || (stored?.candidate_id===args.candidate_id?{...stored,threadId}:null);
       if (!item || item.threadId !== threadId || item.model !== config.model) throw new Error("Suggestion expired or conversation changed; generate a new suggestion");
+      if(stored?.candidate_id===args.candidate_id){
+        const page=await readContext(threadId,config,{signal,includePage:true});
+        if(page.latestTurnId!==stored.turnId)throw new Error("Conversation changed; generate a new suggestion");
+      }
       return result({ candidate_id: args.candidate_id, suggestion: item.suggestion, model: item.model });
     }
     if (request.params.name !== "suggest_next_message" || Object.keys(args).length) throw new Error("Invalid suggestion tool or parameters");

package/src/suggestion-ui.html

@@ -21,6 +21,6 @@ addEventListener("message",event=>{if(event.source!==parent)return;const message
 $("generate").onclick=async()=>{if(busy||!ready)return;busy=true;buttons();$("status").textContent=words().generating;try{render(data(await request("tools/call",{name:"suggest_next_message",arguments:{}})));$("status").textContent=supportsDraft?"":words().unsupported}catch(error){$("status").textContent=error.message}finally{busy=false;buttons()}};
 $("adopt").onclick=async()=>{if(busy||!current?.candidate_id||!supportsDraft)return;busy=true;buttons();const id=current.candidate_id;try{const checked=data(await request("tools/call",{name:"prepare_suggestion_draft",arguments:{candidate_id:id}}));if(checked.candidate_id!==id||checked.suggestion!==current.suggestion)throw new Error(words().failed);await request("ui/message",{role:"user",content:[{type:"text",text:checked.suggestion}],_meta:{"openai/message":{target:"active",send:false}}});applied=id;$("status").textContent=words().added}catch(error){$("status").textContent=error.message}finally{busy=false;buttons()}};
 labels();$("status").textContent=words().connecting;
-request("ui/initialize",{appInfo:{name:"CCDX Next message",version:"1"},appCapabilities:{},protocolVersion:"2026-01-26"}).then(result=>{if(result.hostContext?.locale)zh=/^zh/i.test(result.hostContext.locale);labels();supportsDraft=Boolean(result.hostCapabilities?.experimental?.["openai/message"]?.draft);parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/initialized",params:{}},"*");ready=true;$("status").textContent=supportsDraft?"":words().unsupported;if(!current)$("suggestion").textContent=words().empty;buttons()}).catch(error=>{$("status").textContent=error.message});
+request("ui/initialize",{appInfo:{name:"CCDX Next message",version:"1"},appCapabilities:{},protocolVersion:"2026-01-26"}).then(async result=>{if(result.hostContext?.locale)zh=/^zh/i.test(result.hostContext.locale);labels();supportsDraft=Boolean(result.hostCapabilities?.experimental?.["openai/message"]?.draft);parent.postMessage({jsonrpc:"2.0",method:"ui/notifications/initialized",params:{}},"*");ready=true;$("status").textContent=supportsDraft?"":words().unsupported;if(!current){try{render(data(await request("tools/call",{name:"latest_suggestion",arguments:{}})))}catch{$("suggestion").textContent=words().empty}}buttons()}).catch(error=>{$("status").textContent=error.message});
 addEventListener("pagehide",()=>{for(const p of pending.values()){clearTimeout(p.timer);p.reject(new Error("Panel closed"))}pending.clear()});
 </script></html>