polygram 0.38.6 → 0.38.9

package/lib/codex/hooks/observer-entry.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// Stamped at process entry, before stdin is touched. Stamping after the drain
+// measures the writer rather than the hook, which silently inflates every
+// margin derived from the capture.
+const OBSERVED_AT_EPOCH_MS = Date.now();
+
+const { buildCaptureRecord, writeCaptureRecord } = require('./observer-capture.js');
+
+const MAX_PAYLOAD_BYTES = 256 * 1024;
+const STDIN_TIMEOUT_MS = 5_000;
+
+// An oversized payload is rejected whole. Parsing the prefix that arrived
+// before the limit would record a truncated turn as a complete observation.
+function readPayload(stdin, limit, timeoutMs) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let bytes = 0;
+    let settled = false;
+    const finish = (status, payload) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      stdin.removeAllListeners();
+      stdin.pause();
+      resolve({ status, payload, bytes });
+    };
+    const timer = setTimeout(() => finish('timeout', null), timeoutMs);
+    if (typeof timer.unref === 'function') timer.unref();
+    stdin.on('data', (chunk) => {
+      bytes += chunk.length;
+      if (bytes > limit) {
+        finish('overflow', null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    stdin.once('error', () => finish('unreadable', null));
+    stdin.once('end', () => finish('ok', Buffer.concat(chunks).toString('utf8')));
+  });
+}
+
+async function main(argv, stdin) {
+  const [event, captureDir] = argv;
+  if (typeof event !== 'string' || event.length === 0
+    || typeof captureDir !== 'string' || captureDir.length === 0) {
+    process.setExitCode(2);
+    return;
+  }
+  const read = await readPayload(stdin, MAX_PAYLOAD_BYTES, STDIN_TIMEOUT_MS);
+  let status = read.status;
+  let parsed = null;
+  if (status === 'ok') {
+    try {
+      parsed = JSON.parse(read.payload);
+    } catch {
+      status = 'unparsable';
+    }
+  }
+  writeCaptureRecord(captureDir, buildCaptureRecord({
+    event,
+    status,
+    observedAtEpochMs: OBSERVED_AT_EPOCH_MS,
+    payload: read.payload,
+    payloadBytes: read.bytes,
+    parsed,
+  }));
+}
+
+main(process.argv.slice(2), process.stdin).catch(() => {
+  // A hook that cannot record its observation must not take the turn down
+  // with it; the missing capture is the signal the gate reads.
+  process.setExitCode(1);
+});

package/lib/codex/runtime-controller.js

@@ -376,6 +376,7 @@ function createCodexRuntimeController({
       codexHome,
       binaryPath: configured.binary ?? processEnv.POLYGRAM_CODEX_BIN,
       sessionLauncher,
+      hooks: configured.hooks ?? null,
       daemonSecretRoots: [
         ...new Set([...defaultDaemonSecretRoots, ...configuredSecretRoots]),
       ],
@@ -452,14 +453,28 @@ function createCodexRuntimeController({
   }
 
   async function prepareCodexRequest({ sessionKey, request, state }) {
+    const configured = deploymentConfig();
+    const hookConfigFingerprint = digest(configured.hooks);
     const existing = receiptsBySession.get(sessionKey);
     if (existing && sameProfileRequest(
       existing.receipt.expectedStaticProfile,
       request,
-    )) {
+    ) && existing.hookConfigFingerprint === hookConfigFingerprint) {
       const catalogAgeMs = now() - existing.catalogPreparedAt;
       let currentCredentialState;
       try {
+        if (existing.receipt.expectedStaticProfile.hookManifest != null) {
+          if (typeof runtimeProfileBuilder.reattest !== 'function') {
+            throw controllerError(
+              'Codex hook profile cannot be re-attested.',
+              'CODEX_OWNED_HOOKS_DRIFT',
+              'Discard the profile and restore the hook-aware runtime builder.',
+            );
+          }
+          runtimeProfileBuilder.reattest(
+            existing.receipt.expectedStaticProfile,
+          );
+        }
         const homeAttestation = await attestCodexHome(
           existing.receipt.expectedStaticProfile.codexHome,
           existing.receipt.expectedStaticProfile.ownedConfigSha256,
@@ -478,14 +493,17 @@ function createCodexRuntimeController({
       }
       invalidatePreparedSession(sessionKey, existing);
     }
+    if (existing && receiptsBySession.get(sessionKey) === existing) {
+      invalidatePreparedSession(sessionKey, existing);
+    }
 
-    const configured = deploymentConfig();
     const key = digest({
       sessionKey,
       request,
       codexHome: configured.codexHome,
       binaryPath: configured.binaryPath,
       sessionLauncher: configured.sessionLauncher,
+      hooks: configured.hooks,
       daemonSecretRoots: configured.daemonSecretRoots,
     });
     if (preparingByKey.has(key)) return preparingByKey.get(key);
@@ -504,7 +522,18 @@ function createCodexRuntimeController({
         effort: request.effort,
         processEnv,
         sessionLauncher: configured.sessionLauncher,
+        ...(configured.hooks == null ? {} : { hooks: configured.hooks }),
       });
+      if (expectedStaticProfile.hookManifest != null) {
+        if (typeof runtimeProfileBuilder.reattest !== 'function') {
+          throw controllerError(
+            'Codex hook profile cannot be re-attested.',
+            'CODEX_OWNED_HOOKS_DRIFT',
+            'Discard the profile and restore the hook-aware runtime builder.',
+          );
+        }
+        runtimeProfileBuilder.reattest(expectedStaticProfile);
+      }
       const homeAttestation = await attestCodexHome(
         expectedStaticProfile.codexHome,
         expectedStaticProfile.ownedConfigSha256,
@@ -533,6 +562,13 @@ function createCodexRuntimeController({
           'Choose a model and effort returned by the authenticated Codex catalog.',
         );
       }
+      if (digest(deploymentConfig().hooks) !== hookConfigFingerprint) {
+        throw controllerError(
+          'Codex hook configuration changed during preflight.',
+          'CODEX_PREFLIGHT_PROFILE_MISMATCH',
+          'Retry after configuration changes settle.',
+        );
+      }
       const receipt = catalog.spawnProfile;
       const entry = {
         receipt,
@@ -543,6 +579,7 @@ function createCodexRuntimeController({
         catalogPreparedAt: now(),
         credentialStateFingerprint: attestedCredentialState,
         deploymentIdentity,
+        hookConfigFingerprint,
       };
       receiptsBySession.set(sessionKey, entry);
       return entry;
@@ -681,12 +718,25 @@ function createCodexRuntimeController({
         'Discard the stale spawn and rerun exact preflight.',
       );
     }
+    if (expectedStaticProfile.hookManifest != null) {
+      if (typeof runtimeProfileBuilder.reattest !== 'function') {
+        throw controllerError(
+          'Codex hook profile cannot be re-attested before spawn.',
+          'CODEX_OWNED_HOOKS_DRIFT',
+          'Discard the profile and restore the hook-aware runtime builder.',
+        );
+      }
+      runtimeProfileBuilder.reattest(expectedStaticProfile);
+    }
     return new orchestra.CodexAppServerClient({
       binary: expectedStaticProfile.binary,
       codexHome: expectedStaticProfile.codexHome,
       cwd: expectedStaticProfile.cwd,
       env: expectedStaticProfile.env,
       expectedConfigSha256: expectedStaticProfile.ownedConfigSha256,
+      ...(expectedStaticProfile.hookManifest == null ? {} : {
+        hookManifest: expectedStaticProfile.hookManifest,
+      }),
       ...(expectedStaticProfile.sessionLauncher == null ? {} : {
         sessionLauncher: expectedStaticProfile.sessionLauncher,
         expectedSessionLauncherSha256:

package/lib/codex/runtime-profile.js

@@ -21,6 +21,12 @@ const {
   characterizePinnedSessionLauncher,
   resolveCodexTargetPin,
 } = require('@shumkov/orchestra');
+const {
+  CAPTURE_DIRECTORY,
+  prepareHookRuntime,
+  reattestHookRuntime,
+  renderTrustTables,
+} = require('./hook-runtime');
 
 const CODEX_PERMISSION_PROFILE_ID = 'polygram-session';
 const CONTROLLED_PATH = '/usr/bin:/bin';
@@ -375,6 +381,8 @@ function renderOwnedConfig(config, {
     'trust_level = "untrusted"',
     '',
   );
+  const hookTables = renderTrustTables(config);
+  if (hookTables) lines.push(...hookTables.split('\n'));
   if (
     filesystem[':minimal'] !== 'read'
     || filesystem[codexHome] !== 'deny'
@@ -580,33 +588,6 @@ function provisionRuntimeFiles(options, temporaryRoots) {
     daemonSecretRoots,
   });
   const configPath = path.join(codexHome, 'config.toml');
-  if (existsSync(configPath)) {
-    assertOwnedMode(configPath, {
-      code: 'CODEX_OWNED_CONFIG_DRIFT',
-      kind: 'owned config.toml',
-      expectedMode: 0o600,
-      directory: false,
-    });
-    if (readFileSync(configPath, 'utf8') !== rawConfig) {
-      throw fail(
-        'Codex owned config.toml differs from the native-beta policy.',
-        'CODEX_OWNED_CONFIG_DRIFT',
-        'Back up config.toml outside CODEX_HOME, then remove or move the original and rerun startup to reprovision the exact owned config; Polygram never migrates or overwrites it automatically.',
-      );
-    }
-  } else {
-    try {
-      writeFileSync(configPath, rawConfig, { flag: 'wx', mode: 0o600 });
-      chmodSync(configPath, 0o600);
-    } catch (error) {
-      throw fail(
-        'Codex owned config.toml could not be provisioned.',
-        'CODEX_OWNED_CONFIG_DRIFT',
-        'Provision the exact owner-only config before enabling Codex.',
-        error,
-      );
-    }
-  }
 
   const authPath = path.join(codexHome, 'auth.json');
   if (existsSync(authPath)) {
@@ -624,6 +605,7 @@ function provisionRuntimeFiles(options, temporaryRoots) {
     daemonSecretRoots,
     commandHome,
     commandTmp,
+    configPath,
     ownedConfig,
     rawConfig,
     ownedConfigSha256: digest(rawConfig),
@@ -635,6 +617,38 @@ function provisionRuntimeFiles(options, temporaryRoots) {
   };
 }
 
+function provisionBaseConfig(materialized) {
+  const { configPath, rawConfig } = materialized;
+  if (existsSync(configPath)) {
+    assertOwnedMode(configPath, {
+      code: 'CODEX_OWNED_CONFIG_DRIFT',
+      kind: 'owned config.toml',
+      expectedMode: 0o600,
+      directory: false,
+    });
+    if (readFileSync(configPath, 'utf8') !== rawConfig) {
+      throw fail(
+        'Codex owned config.toml differs from the native-beta policy.',
+        'CODEX_OWNED_CONFIG_DRIFT',
+        'Back up config.toml outside CODEX_HOME, then remove or move the original and rerun startup to reprovision the exact owned config; Polygram never migrates or overwrites it automatically.',
+      );
+    }
+    return materialized;
+  }
+  try {
+    writeFileSync(configPath, rawConfig, { flag: 'wx', mode: 0o600 });
+    chmodSync(configPath, 0o600);
+  } catch (error) {
+    throw fail(
+      'Codex owned config.toml could not be provisioned.',
+      'CODEX_OWNED_CONFIG_DRIFT',
+      'Provision the exact owner-only config before enabling Codex.',
+      error,
+    );
+  }
+  return materialized;
+}
+
 function expectedFilesystem(materialized) {
   return {
     glob_scan_max_depth: null,
@@ -831,10 +845,100 @@ async function collectPermissionProfiles(client, workspace) {
   return profiles.sort((left, right) => left.id.localeCompare(right.id));
 }
 
+async function verifyHookPhase(materialized, {
+  binaryReceipt,
+  sessionLauncherReceipt,
+  clientFactory,
+  expectedConfigSha256,
+  hookManifest,
+  phase,
+}) {
+  let latchedFault = null;
+  const client = clientFactory({
+    binary: binaryReceipt.path,
+    sessionLauncher: sessionLauncherReceipt?.path ?? null,
+    expectedSessionLauncherSha256: sessionLauncherReceipt?.sha256 ?? null,
+    cwd: materialized.workspace,
+    codexHome: materialized.codexHome,
+    env: materialized.env,
+    expectedConfigSha256,
+    hookManifest,
+    onNotification: async () => {
+      throw fail(
+        'Codex hook verification received an unexpected notification.',
+        'CODEX_RUNTIME_POLICY_DRIFT',
+        'Disable hooks and inspect the pinned app-server protocol drift.',
+      );
+    },
+    onFault: (outcome) => {
+      outcome?.assertActive?.();
+      latchedFault = outcome;
+    },
+  });
+  if (
+    !client
+    || typeof client.start !== 'function'
+    || typeof client.verifyHooks !== 'function'
+    || typeof client.close !== 'function'
+    || typeof client.waitForFault !== 'function'
+  ) {
+    throw new TypeError('Codex hook clientFactory returned an invalid client');
+  }
+  let result;
+  let failure = null;
+  try {
+    await client.start();
+    result = await client.verifyHooks({ phase });
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    await client.close();
+  } catch (error) {
+    throw fail(
+      'Codex hook verification cleanup failed.',
+      'CODEX_RUNTIME_CLIENT_CLOSE_FAILED',
+      'Disable hooks and inspect the pinned app-server child cleanup.',
+      error,
+    );
+  }
+  let terminalFault;
+  try {
+    terminalFault = await client.waitForFault();
+  } catch (error) {
+    throw fail(
+      'Codex hook verification fault handoff failed.',
+      'CODEX_RUNTIME_CLIENT_FAULT',
+      'Disable hooks and inspect the pinned app-server fault handoff.',
+      error,
+    );
+  }
+  if (latchedFault || terminalFault) {
+    throw fail(
+      'Codex hook verification client faulted.',
+      'CODEX_RUNTIME_CLIENT_FAULT',
+      'Disable hooks and inspect the pinned app-server fault.',
+    );
+  }
+  if (failure) {
+    if (failure instanceof CodexRuntimeProfileError) throw failure;
+    throw fail(
+      'Codex hook verification failed closed.',
+      failure?.code === 'CODEX_HOOK_TRUST_UNVERIFIED'
+        ? 'CODEX_HOOK_TRUST_UNVERIFIED'
+        : 'CODEX_RUNTIME_POLICY_DRIFT',
+      'Restore the exact owned hook manifest and runtime policy.',
+      failure,
+    );
+  }
+  return result;
+}
+
 async function characterizeRuntime(materialized, {
   binaryReceipt,
   sessionLauncherReceipt,
   clientFactory,
+  hookManifest = null,
 }) {
   let latchedFault = null;
   const client = clientFactory({
@@ -845,6 +949,7 @@ async function characterizeRuntime(materialized, {
     codexHome: materialized.codexHome,
     env: materialized.env,
     expectedConfigSha256: materialized.ownedConfigSha256,
+    ...(hookManifest == null ? {} : { hookManifest }),
     onNotification: async () => {
       throw fail(
         'Codex runtime characterization received a state notification.',
@@ -871,6 +976,12 @@ async function characterizeRuntime(materialized, {
   let failure = null;
   try {
     await client.start();
+    if (hookManifest != null) {
+      if (typeof client.verifyHooks !== 'function') {
+        throw new TypeError('Codex runtime client lacks hook verification');
+      }
+      await client.verifyHooks({ phase: 'trusted' });
+    }
     const configRead = await client.request('config/read', {
       cwd: materialized.workspace,
       includeLayers: true,
@@ -952,7 +1063,8 @@ function createCodexRuntimeProfileBuilder({
     throw new TypeError('Codex runtime profile builder options are invalid');
   }
 
-  return Object.freeze({
+  const hookProfiles = new WeakMap();
+  const builder = {
     async prepare(options = {}) {
       const targetPin = resolveTargetPin();
       validateBinaryReceipt(options.binaryReceipt, protocolSchema, targetPin);
@@ -984,15 +1096,59 @@ function createCodexRuntimeProfileBuilder({
           'Restore the exact root-owned session launcher before enabling Codex.',
         );
       }
-      const materialized = provisionRuntimeFiles(options, temporaryRoots);
+      let materialized = provisionRuntimeFiles(options, temporaryRoots);
+      let hookMaterial = null;
+      if (options.hooks == null) {
+        provisionBaseConfig(materialized);
+      } else {
+        if (options.hooks.enabled === true) {
+          ensurePrivateDirectory(
+            path.join(materialized.workspace, CAPTURE_DIRECTORY),
+            'CODEX_COMMAND_DIR_UNSAFE',
+            'hook observation directory',
+          );
+        }
+        const hookState = await prepareHookRuntime({
+          hookOptions: options.hooks,
+          codexHome: materialized.codexHome,
+          workspace: materialized.workspace,
+          baseOwnedConfig: materialized.ownedConfig,
+          baseRawConfig: materialized.rawConfig,
+          renderOwnedConfig: (ownedConfig) => renderOwnedConfig(ownedConfig, {
+            codexHome: materialized.codexHome,
+            workspace: materialized.workspace,
+            daemonSecretRoots: materialized.daemonSecretRoots,
+          }),
+          verifyDiscovery: (hookManifest, expectedConfigSha256) => (
+            verifyHookPhase(materialized, {
+              binaryReceipt: options.binaryReceipt,
+              sessionLauncherReceipt,
+              clientFactory,
+              expectedConfigSha256,
+              hookManifest,
+              phase: 'discovery',
+            })
+          ),
+        });
+        hookMaterial = hookState.hookMaterial;
+        materialized = {
+          ...materialized,
+          ownedConfig: hookState.ownedConfig,
+          rawConfig: hookState.rawConfig,
+          ownedConfigSha256: digest(hookState.rawConfig),
+          hookManifest: hookState.hookManifest,
+          hookArtifactsSha256: hookState.hookArtifactsSha256,
+        };
+      }
       const characterized = await characterizeRuntime(materialized, {
         binaryReceipt: options.binaryReceipt,
         sessionLauncherReceipt,
         clientFactory,
+        hookManifest: materialized.hookManifest ?? null,
       });
       const model = requiredString(options.model, 'model');
       const effort = requiredString(options.effort, 'reasoning effort');
-      return deepFreeze({
+      const profile = deepFreeze({
         runtime: 'codex',
         binary: options.binaryReceipt.path,
         target: targetPin.target,
@@ -1016,9 +1172,37 @@ function createCodexRuntimeProfileBuilder({
         effort,
         sessionLauncher: sessionLauncherReceipt?.path ?? null,
         sessionLauncherSha256: sessionLauncherReceipt?.sha256 ?? null,
+        ...(materialized.hookManifest == null ? {} : {
+          hookManifest: materialized.hookManifest,
+          hookArtifactsSha256: materialized.hookArtifactsSha256,
+        }),
       });
+      if (hookMaterial != null) {
+        hookProfiles.set(profile, Object.freeze({
+          hookOptions: Object.freeze({ ...options.hooks }),
+          codexHome: materialized.codexHome,
+          workspace: materialized.workspace,
+        }));
+      }
+      return profile;
     },
-  });
+    reattest(profile) {
+      if (profile?.hookManifest == null) return null;
+      const binding = hookProfiles.get(profile);
+      if (!binding) {
+        throw fail(
+          'Codex hook profile is not owned by this runtime builder.',
+          'CODEX_OWNED_HOOKS_DRIFT',
+          'Discard the stale profile and rerun exact preflight.',
+        );
+      }
+      return reattestHookRuntime({
+        ...binding,
+        expected: profile,
+      });
+    },
+  };
+  return Object.freeze(builder);
 }
 
 const defaultBuilder = createCodexRuntimeProfileBuilder();

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "polygram",
-  "version": "0.38.6",
+  "version": "0.38.9",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {
     "polygram": "polygram.js",
     "polygram-split-db": "scripts/split-db.js",
     "polygram-ipc": "scripts/ipc-smoke.js",
-    "polygram-doctor": "scripts/doctor.js"
+    "polygram-doctor": "scripts/doctor.js",
+    "polygram-codex-hook-artifacts": "scripts/codex-hook-artifacts.js",
+    "polygram-build-codex-hook-bundle": "scripts/build-codex-hook-bundle.js"
   },
   "files": [
     "polygram.js",
@@ -16,11 +18,14 @@
     "scripts/split-db.js",
     "scripts/ipc-smoke.js",
     "scripts/doctor.js",
+    "scripts/build-codex-hook-bundle.js",
+    "scripts/codex-hook-artifacts.js",
     "skills/",
     "commands/",
     ".claude-plugin/",
     "ops/polygram.plist.example",
     "ops/README.md",
+    "docs/2026-08-16-003-codex-protected-hook-artifact-runbook.md",
     "config.example.json"
   ],
   "scripts": {
@@ -63,7 +68,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.123",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@shumkov/orchestra": "0.10.19",
+    "@shumkov/orchestra": "0.10.21",
+    "acorn": "8.18.0",
     "better-sqlite3": "^12.9.0",
     "grammy": "^1.42.0",
     "markdown-it": "^14.1.1",

package/scripts/build-codex-hook-bundle.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+'use strict';
+
+// Builds the single self-contained Codex hook bundle from the checked-in
+// sources. The build is a pure function of those sources, so `--check` is the
+// drift gate: a bundle that no longer regenerates is never installed.
+
+const { createHash } = require('node:crypto');
+const { readFileSync, writeFileSync } = require('node:fs');
+
+const {
+  HOOK_BUNDLE_PATH,
+  HOOK_BUNDLE_SOURCES,
+  buildHookBundle,
+} = require('../lib/codex/hook-bundle');
+
+const USAGE = 'usage: build-codex-hook-bundle [--check] [--out <path>]';
+
+function parseArgs(argv) {
+  const options = { check: false, out: HOOK_BUNDLE_PATH };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--check') {
+      options.check = true;
+    } else if (argument === '--out') {
+      index += 1;
+      options.out = argv[index];
+      if (typeof options.out !== 'string' || options.out.length === 0) {
+        throw new Error(USAGE);
+      }
+    } else {
+      throw new Error(`${USAGE}\nunknown argument ${argument}`);
+    }
+  }
+  return options;
+}
+
+function main(argv) {
+  const options = parseArgs(argv);
+  const bundle = buildHookBundle();
+  const sha256 = createHash('sha256').update(bundle).digest('hex');
+
+  if (options.check) {
+    let current = null;
+    try {
+      current = readFileSync(options.out, 'utf8');
+    } catch {
+      process.stderr.write(`missing bundle at ${options.out}\n`);
+      return 1;
+    }
+    if (current !== bundle) {
+      process.stderr.write(
+        `bundle at ${options.out} is not what the sources build; `
+          + 'rebuild it in the same change as the sources\n',
+      );
+      return 1;
+    }
+    process.stdout.write(`ok ${sha256}\n`);
+    return 0;
+  }
+
+  writeFileSync(options.out, bundle, { mode: 0o644 });
+  process.stdout.write(
+    `${options.out}\nsources ${HOOK_BUNDLE_SOURCES.join(' ')}\nsha256 ${sha256}\n`,
+  );
+  return 0;
+}
+
+try {
+  process.exitCode = main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}