@polygraph/claude-plugin 0.4.47 → 0.4.48

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.47",
+  "version": "0.4.48",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/hooks/agent-session-finalize.mjs

@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function isManagedChildEnvironment(env) {
+  return Boolean(env && Object.hasOwn(env, 'POLYGRAPH_CHILD_AGENT'));
+}
+
+export function buildFinalizeAgentSessionArgs({
+  agentType,
+  agentSessionId,
+  cwd,
+  transcriptPath,
+  source,
+}) {
+  const harnessSession = nonEmptyString(agentSessionId);
+  const hookSource = nonEmptyString(source);
+  if (agentType !== 'claude') throw new Error(`Unsupported agent type: ${agentType}`);
+  if (!harnessSession) throw new Error('agentSessionId is required');
+  if (!hookSource) throw new Error('source is required');
+
+  const args = [
+    '_finalize-agent-session',
+    '--agent-type',
+    agentType,
+    '--agent-session-id',
+    harnessSession,
+  ];
+
+  const workingDirectory = nonEmptyString(cwd);
+  if (workingDirectory) args.push('--cwd', workingDirectory);
+
+  const transcript = nonEmptyString(transcriptPath);
+  if (transcript) args.push('--transcript-path', transcript);
+
+  args.push('--source', hookSource);
+  return args;
+}
+
+export function finalizeAgentSession(claim, spawn = spawnSync, env = process.env) {
+  if (isManagedChildEnvironment(env)) return false;
+
+  const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? 'polygraph';
+  const commandEnv = { ...env };
+  delete commandEnv.POLYGRAPH_SESSION_ID;
+  delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+
+  const result = spawn(command, buildFinalizeAgentSessionArgs(claim), {
+    encoding: 'utf8',
+    env: commandEnv,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+
+  if (result?.error) throw result.error;
+  if (result?.status !== 0) {
+    const detail = nonEmptyString(result?.stderr);
+    throw new Error(
+      `polygraph _finalize-agent-session exited with status ${String(result?.status)}` +
+        (detail ? `: ${detail}` : '')
+    );
+  }
+
+  return true;
+}
+
+export function buildCommandHookFinalize(payload, agentType, env = process.env) {
+  if (!payload || typeof payload !== 'object') return undefined;
+  if (isManagedChildEnvironment(env)) return undefined;
+  if (agentType !== 'claude' || payload.hook_event_name !== 'SessionEnd') {
+    return undefined;
+  }
+
+  const agentSessionId = nonEmptyString(payload.session_id);
+  if (!agentSessionId) return undefined;
+
+  return {
+    agentType,
+    agentSessionId,
+    cwd: nonEmptyString(payload.cwd),
+    transcriptPath: nonEmptyString(payload.transcript_path),
+    source: 'hook',
+  };
+}

package/hooks/agent-session-link.mjs

@@ -102,7 +102,11 @@ export function buildCommandHookLink(payload, agentType, env = process.env) {
 
   if (payload.hook_event_name === 'SessionStart') {
     const polygraphSessionId = nonEmptyString(env.POLYGRAPH_SESSION_ID);
-    return polygraphSessionId ? { ...common, polygraphSessionId } : undefined;
+    if (polygraphSessionId) return { ...common, polygraphSessionId };
+
+    // Ordinary Claude sessions are eligible for speculative capture. Other
+    // harnesses still require launch-provided Polygraph session evidence.
+    return agentType === 'claude' ? common : undefined;
   }
 
   if (payload.hook_event_name === 'PostToolUse') {

package/hooks/finalize-agent-session.mjs

@@ -0,0 +1,56 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildCommandHookFinalize,
+  finalizeAgentSession,
+} from './agent-session-finalize.mjs';
+import { logHookFailure } from './agent-session-link.mjs';
+
+function readPayload() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function main({
+  payload = readPayload(),
+  agentType = process.argv[2],
+  env = process.env,
+  spawn,
+} = {}) {
+  try {
+    const finalize = buildCommandHookFinalize(payload, agentType, env);
+    if (!finalize) return false;
+    return finalizeAgentSession(
+      {
+        ...finalize,
+        cwd: finalize.cwd ?? process.cwd(),
+      },
+      spawn,
+      env
+    );
+  } catch (error) {
+    logHookFailure(`${agentType || 'unknown'}:finalize-agent-session`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: payload?.session_id,
+    });
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main();
+}

package/hooks/hooks.json

@@ -33,7 +33,18 @@
           },
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/record-session-mapping.mjs claude"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/record-session-mapping.mjs claude",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/finalize-agent-session.mjs claude"
           }
         ]
       }

package/hooks/record-session-mapping.mjs

@@ -27,15 +27,18 @@ export function main({
     const link = buildCommandHookLink(payload, agentType, env);
     if (!link) return false;
 
-    return linkAgentSession(
-      {
-        ...link,
-        pid,
-        cwd: link.cwd ?? process.cwd(),
-      },
-      spawn,
-      env
-    );
+    const claim = {
+      ...link,
+      cwd: link.cwd ?? process.cwd(),
+    };
+    // Claude lifecycle hooks deliberately forward only the exact harness
+    // identity, transcript, cwd, and hook source. PID is not identity and can
+    // be stale by the time an asynchronous SessionStart hook runs.
+    if (!(agentType === 'claude' && payload?.hook_event_name === 'SessionStart')) {
+      claim.pid = pid;
+    }
+
+    return linkAgentSession(claim, spawn, env);
   } catch (error) {
     logHookFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
       hookEventName: payload?.hook_event_name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/claude-plugin",
-  "version": "0.4.47",
+  "version": "0.4.48",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,