@ghl-ai/aw 0.1.93 → 0.2.1

package/commands/init.mjs

@@ -13,6 +13,7 @@ import {
   readdirSync,
   readFileSync,
   rmSync,
+  readlinkSync,
   realpathSync,
 } from 'node:fs';
 import { execSync } from 'node:child_process';
@@ -116,11 +117,31 @@ function formatIntegrationStatusSummary(statuses, installedNow = []) {
   ].join('\n');
 }
 
+// Copy the upgraded package's aw-usage scripts to ~/.aw/aw-usage directly,
+// so a failed aw-ecc clone below cannot leave the old scripts installed.
+// Packages older than the shared wiring module have no file to import; their
+// ECC sync refreshes the scripts through startup preferences instead.
+async function refreshAwUsageScriptsFromPackage(packageRoot, { silent }) {
+  const wiringPath = join(packageRoot, 'aw-usage-wiring.mjs');
+  if (!existsSync(wiringPath)) return;
+  try {
+    const wiring = await import(`${pathToFileURL(wiringPath).href}?aw-post-update=${Date.now()}`);
+    const result = wiring.copyAwUsageScripts(HOME);
+    if (result.failed > 0 && !silent) {
+      fmt.logWarn(`AW updated, but ${result.failed} aw-usage script(s) could not be copied to ~/.aw/aw-usage/`);
+    }
+  } catch (err) {
+    if (!silent) fmt.logWarn(`AW updated, but refreshing aw-usage scripts failed: ${err.message}`);
+  }
+}
+
 export async function syncEccAfterAwUpdate(updateResult, cwd, { silent = false } = {}) {
   if (updateResult?.status !== 'upgraded' || !updateResult.packageRoot) {
     return { synced: false, reason: updateResult?.reason || updateResult?.status || 'not-upgraded' };
   }
 
+  await refreshAwUsageScriptsFromPackage(updateResult.packageRoot, { silent });
+
   const eccModulePath = join(updateResult.packageRoot, 'ecc.mjs');
   if (!existsSync(eccModulePath)) {
     return { synced: false, reason: 'missing-ecc-module' };
@@ -278,6 +299,54 @@ export function ensureAwGitignore(awHome) {
   try { writeFileSync(excludePath, next); } catch (err) { void err; /* best effort */ }
 }
 
+// ── Recovery for a half-finished init ───────────────────────────────────
+
+// Backward-compat symlink: ~/.aw_registry/ → ~/.aw/.aw_registry/.
+// Uses lstatSync (not existsSync) so a dangling symlink is re-pointed instead
+// of tripping EEXIST on symlinkSync.
+function ensureRegistryLink({ silent = false } = {}) {
+  const target = join(AW_HOME, REGISTRY_DIR);
+
+  let link = null;
+  try { link = lstatSync(GLOBAL_AW_DIR); } catch { /* not there yet */ }
+
+  // Legacy plain directory — the migration path handles it, don't clobber it.
+  if (link && !link.isSymbolicLink()) return;
+
+  if (link) {
+    try {
+      if (readlinkSync(GLOBAL_AW_DIR) === target && existsSync(GLOBAL_AW_DIR)) return;
+    } catch { /* unreadable — re-point below */ }
+    try { rmSync(GLOBAL_AW_DIR); } catch (e) {
+      if (!silent) fmt.logWarn(`Could not replace ~/.aw_registry/: ${errorMessage(e)}`);
+      return;
+    }
+  }
+
+  try {
+    symlinkSync(target, GLOBAL_AW_DIR);
+    if (!silent) fmt.logStep('Registry linked');
+  } catch (e) {
+    if (!silent) fmt.logWarn(`Could not create symlink ~/.aw_registry/: ${errorMessage(e)}`);
+  }
+}
+
+// Namespaces the clone actually has checked out, so a rebuilt config matches
+// what is on disk instead of resetting the user to platform-only.
+function namespacesInSparseCheckout(awHome) {
+  let listed = '';
+  try {
+    listed = execSync('git sparse-checkout list', { cwd: awHome, stdio: 'pipe', encoding: 'utf8' });
+  } catch { return []; }
+
+  const prefix = `${REGISTRY_DIR}/`;
+  return listed.split('\n')
+    .map(line => line.trim().replace(/^\//, ''))
+    .filter(line => line.startsWith(prefix))
+    .map(line => line.slice(prefix.length).replace(/\/$/, ''))
+    .filter(ns => ns && ns !== 'platform' && !ns.includes('.'));
+}
+
 // ── IDE tasks for auto-pull ─────────────────────────────────────────────
 
 function installIdeTasks() {
@@ -428,10 +497,28 @@ export async function initCommand(args) {
   const _rawCwd = process.cwd();
   const cwd = (() => { try { return realpathSync(_rawCwd); } catch { return _rawCwd; } })();
 
+  if (!user) {
+    try {
+      user = execSync('git config user.name', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    } catch { /* git not configured */ }
+  }
+
   // ── Re-init path: already set up with native git clone ────────────────
 
   if (isGitNative) {
-    const cfg = config.load(GLOBAL_AW_DIR);
+    // An init interrupted after the clone but before the symlink and config
+    // were written leaves a clone that passes isValidClone() while every later
+    // command dies on config.load(). Repair that here rather than reporting
+    // "already initialized" and no-oping forever. (#852)
+    ensureRegistryLink({ silent });
+    let cfg = config.load(GLOBAL_AW_DIR);
+    if (!cfg) {
+      cfg = config.create(GLOBAL_AW_DIR, { namespace: activeNamespace(), user });
+      for (const ns of namespacesInSparseCheckout(AW_HOME)) {
+        cfg = config.addPattern(GLOBAL_AW_DIR, ns);
+      }
+      if (!silent) fmt.logStep('Recovered missing .sync-config.json from the existing clone');
+    }
 
     const isNewSubTeam = folderName && cfg && !cfg.include.includes(folderName);
     if (isNewSubTeam) {
@@ -600,12 +687,6 @@ export async function initCommand(args) {
 
   // ── Full init: first time setup ───────────────────────────────────────
 
-  if (!user) {
-    try {
-      user = execSync('git config user.name', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-    } catch { /* git not configured */ }
-  }
-
   // Determine sparse paths
   const sparsePaths = [`.aw_registry/platform`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR, `.aw_registry/AW-PROTOCOL.md`, `CODEOWNERS`];
   if (folderName) {
@@ -630,27 +711,7 @@ export async function initCommand(args) {
     fmt.cancel(e.message);
   }
 
-  // Create backward-compat symlink: ~/.aw_registry/ → ~/.aw/.aw_registry/
-  // Use lstatSync (not existsSync) so we handle dangling symlinks correctly.
-  let awRegistryLstat = null;
-  try { awRegistryLstat = lstatSync(GLOBAL_AW_DIR); } catch { /* doesn't exist */ }
-  if (!awRegistryLstat) {
-    try {
-      symlinkSync(join(AW_HOME, REGISTRY_DIR), GLOBAL_AW_DIR);
-      fmt.logStep('Registry linked');
-    } catch (e) {
-      fmt.logWarn(`Could not create symlink ~/.aw_registry/: ${e.message}`);
-    }
-  } else if (awRegistryLstat.isSymbolicLink()) {
-    // Stale or dangling — re-point to the new clone
-    try {
-      rmSync(GLOBAL_AW_DIR);
-      symlinkSync(join(AW_HOME, REGISTRY_DIR), GLOBAL_AW_DIR);
-      fmt.logStep('Registry linked');
-    } catch (e) {
-      fmt.logWarn(`Could not update symlink ~/.aw_registry/: ${e.message}`);
-    }
-  }
+  ensureRegistryLink({ silent });
 
   // Create sync config — default to 'platform' when no namespace specified
   const cfg = config.create(GLOBAL_AW_DIR, { namespace: activeNamespace(), user });

package/ecc.mjs

@@ -12,17 +12,17 @@ import { applyStoredStartupPreferences } from "./startup.mjs";
 
 const AW_ECC_REPO_SSH = "git@github.com:shreyansh-ghl/aw-ecc.git";
 const AW_ECC_REPO_HTTPS = "https://github.com/shreyansh-ghl/aw-ecc.git";
-export const AW_ECC_TAG = "v1.4.77";
+export const AW_ECC_TAG = "v1.5.0";
 const REQUIRED_ECC_FILES = [
   "package.json",
   "scripts/install-apply.js",
   "scripts/sync-ecc-to-codex.sh",
 ];
 
-const MARKETPLACE_NAME = "aw-marketplace";
+export const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
 
-function eccDir() { return join(homedir(), ".aw-ecc"); }
+export function eccDir() { return join(homedir(), ".aw-ecc"); }
 
 // "claude" uses a no-commands module set so hooks, rules, shared references,
 // and install-state land in ~/.claude/ — while slash commands stay owned by

package/hook-cleanup.mjs

@@ -12,6 +12,7 @@ import {
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
+import { isClaudeMemoryStopEntry, isClaudeTelemetryEntry } from './aw-usage-wiring.mjs';
 
 const SCHEMA_VERSION = 'aw-hooks.v1';
 const HOME = homedir();
@@ -19,10 +20,10 @@ const MANIFEST_PATH = join(HOME, '.aw', 'hooks', 'manifest.json');
 
 // ── Patterns matching AW-managed hook entries ────────────────────────────
 
+// AW-managed Claude entries: aw-usage telemetry (any install location) and the
+// AW memory Stop entry. Shared matchers keep prune, nuke and the writers aligned.
 function isManagedClaudeEntry(entry) {
-  if (entry?.description === 'AW usage telemetry') return true;
-  const cmds = Array.isArray(entry?.hooks) ? entry.hooks.map(h => h?.command || '') : [];
-  return cmds.some(c => c.includes('aw-usage-'));
+  return isClaudeTelemetryEntry(entry) || isClaudeMemoryStopEntry(entry);
 }
 
 function isManagedCursorEntry(entry) {

package/hooks/aw-usage/hooks/aw-usage-commit-created.js

@@ -6,6 +6,12 @@
  * Co-Authored-By trailer. Works for all harnesses (Claude, Cursor, Codex)
  * since it fires from a git-level hook, not a harness-specific one.
  *
+ * B9 origin: origin_harness / origin_session_id name the IDE session the
+ * commit came from — CLAUDE_CODE_SESSION_ID when git runs inside Claude Code,
+ * else the most recent session in the project activity index (last 2 hours),
+ * with ambiguous_session when another session was active too. The v1
+ * session_id / linked_session_source rule is unchanged.
+ *
  * Usage: node aw-usage-commit-created.js <commit_hash> <branch> [cwd]
  */
 
@@ -16,8 +22,22 @@ const {
   sendAsync,
   isDisabled,
   findRecentSdlcSessionForProject,
+  findRecentActiveSessionForProject,
+  computeProjectHash,
 } = require('../lib/aw-usage-telemetry');
 
+function commitOrigin(cwd) {
+  const claudeSession = process.env.CLAUDE_CODE_SESSION_ID;
+  if (claudeSession) return { origin_harness: 'claude', origin_session_id: claudeSession };
+  const recent = findRecentActiveSessionForProject(computeProjectHash(cwd));
+  if (!recent) return {};
+  return {
+    origin_harness: recent.harness,
+    origin_session_id: recent.session_id,
+    ...(recent.ambiguous ? { ambiguous_session: true } : {}),
+  };
+}
+
 function buildCommitCreatedEvent({ commitHash = 'unknown', branch = 'unknown', cwd = process.cwd() } = {}) {
   const linkedSession = findRecentSdlcSessionForProject(cwd);
   const event = buildEvent({
@@ -28,6 +48,7 @@ function buildCommitCreatedEvent({ commitHash = 'unknown', branch = 'unknown', c
     commit_sha: commitHash,
     branch,
     ...(linkedSession?.session_id ? { linked_session_source: 'project_recent_sdlc_session' } : {}),
+    ...commitOrigin(cwd),
   });
 
   // Override harness to 'git' since this fires from a git hook, not a harness.

package/hooks/aw-usage/hooks/aw-usage-commit-trailer.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * Commit attribution trailers — called from the prepare-commit-msg git hook.
+ *
+ * Adds to the commit message file:
+ *   Agent-Harness: <harness>; session=<id>   when git runs inside an agent session
+ *                                            (harness only when the id is unsafe)
+ *   AW-Skills: <a>, <b>, stage:<s>,          when that session ran an AW skill or
+ *   <co-author line> and AW-Version: <v>     stage at any point (aw_skills)
+ *
+ * The laptop records which AW skills ran; the server decides which are SDLC.
+ *
+ * The session comes from the variable each agent sets in its shell
+ * (CLAUDE_CODE_SESSION_ID, CURSOR_CONVERSATION_ID, CODEX_THREAD_ID). It is the
+ * same id the AW hooks send as session_id, so the server can join on it. A
+ * hand-typed commit has none of them and gets no trailer. Trailers the agent
+ * wrote itself are left alone. On --amend in the same session our own lines
+ * are replaced, not repeated; a message that already carries another session's
+ * Agent-Harness (rebase, cherry-pick, amend) is left unchanged. Any error
+ * leaves the message unchanged.
+ *
+ * Usage: node aw-usage-commit-trailer.js <commit-msg-file> <co-author-line>
+ */
+
+'use strict';
+
+const fs = require('fs');
+const { readSessionAwSkills, getAwCliVersionDetails } = require('../lib/aw-usage-telemetry');
+
+const SESSION_ENV = [
+  ['CLAUDE_CODE_SESSION_ID', 'claude'],
+  ['CURSOR_CONVERSATION_ID', 'cursor'],
+  ['CODEX_THREAD_ID', 'codex'],
+];
+// Also keeps the id from adding lines to the message or leaving the sessions folder.
+const SAFE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+// Lines this script owns: replaced on --amend so the latest values win.
+const OWN_TRAILER = /^(?:Agent-Harness|AW-Skills|AW-Version): /;
+
+function commitSession(env) {
+  for (const [name, harness] of SESSION_ENV) {
+    const id = env[name];
+    if (!id) continue;
+    // An unsafe id still tells us the harness; it is never written or used as a path.
+    if (!SAFE_SESSION_ID.test(id)) return { harness, sessionId: null };
+    // Cursor cloud agents get a bc-<uuid> conversation id; local agents a plain UUID.
+    return { harness: harness === 'cursor' && id.startsWith('bc-') ? 'cursor-cloud' : harness, sessionId: id };
+  }
+  return null;
+}
+
+function buildTrailers({ env, coAuthor }) {
+  const session = commitSession(env);
+  if (!session) return [];
+  if (!session.sessionId) return [`Agent-Harness: ${session.harness}`];
+  const trailers = [`Agent-Harness: ${session.harness}; session=${session.sessionId}`];
+  const skills = readSessionAwSkills(session.sessionId);
+  if (coAuthor && skills.length > 0) {
+    trailers.push(`AW-Skills: ${skills.join(', ')}`, coAuthor);
+    const version = getAwCliVersionDetails().version;
+    if (version) trailers.push(`AW-Version: ${version}`);
+  }
+  return trailers;
+}
+
+// git commit -v: git drops this line and everything below it (the diff).
+const SCISSORS = /^# -+ >8 -+$/;
+const TRAILER_LINE = /^[A-Za-z][A-Za-z0-9-]*: /;
+// Editor commits end with git's `#` help text, which git strips after the editor.
+// shortcut: assumes the default core.commentChar '#'; read it from git config if teams change it.
+const isComment = (line) => line.startsWith('#');
+
+function appendTrailers(message, trailers) {
+  const eol = message.includes('\r\n') ? '\r\n' : '\n';
+  const lines = message.split(/\r?\n/);
+  // A commit another session wrote (rebase, cherry-pick, amend) keeps its own
+  // attribution: replacing it would erase that session's evidence.
+  const harnessLines = lines.filter((line) => line.startsWith('Agent-Harness: '));
+  if (harnessLines.length > 0 && !harnessLines.includes(trailers[0])) return message;
+
+  // The message git keeps ends at the last line that is not blank, a comment or below the cut.
+  const cut = lines.findIndex((line) => SCISSORS.test(line));
+  const head = cut === -1 ? lines : lines.slice(0, cut);
+  let end = head.length;
+  while (end > 0 && (!head[end - 1].trim() || isComment(head[end - 1]))) end -= 1;
+  // Drop our own stale lines (from an earlier commit of this message) first.
+  const kept = head.slice(0, end).filter((line) => !OWN_TRAILER.test(line) || trailers.includes(line));
+  // No real content: leave it, so git still aborts an empty commit message.
+  if (!kept.some((line) => line.trim() && !isComment(line))) return message;
+  const missing = trailers.filter((trailer) => !kept.includes(trailer));
+  if (missing.length === 0) return message;
+
+  // Join the existing trailer block when the message already ends with one.
+  const body = kept.join('\n').replace(/\s+$/, '');
+  const lastParagraph = body.split(/\n\s*\n/).pop();
+  const endsWithTrailers = body.includes('\n') && lastParagraph.split('\n').every((line) => TRAILER_LINE.test(line));
+  const rest = [...head.slice(end), ...(cut === -1 ? [] : lines.slice(cut))].join('\n');
+  const updated = `${body}${endsWithTrailers ? '\n' : '\n\n'}${missing.join('\n')}\n${rest}`;
+  return eol === '\n' ? updated : updated.replace(/\n/g, eol);
+}
+
+function main() {
+  const [file, coAuthor] = process.argv.slice(2);
+  if (!file) return;
+  try {
+    const trailers = buildTrailers({ env: process.env, coAuthor });
+    if (trailers.length === 0) return;
+    const message = fs.readFileSync(file, 'utf8');
+    const updated = appendTrailers(message, trailers);
+    if (updated !== message) fs.writeFileSync(file, updated);
+  } catch {
+    // Never block or change a commit because attribution failed.
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  appendTrailers,
+  buildTrailers,
+  commitSession,
+};

package/hooks/aw-usage/hooks/aw-usage-post-tool-use.js

@@ -2,7 +2,14 @@
 /**
  * Usage telemetry — PostToolUse hook.
  *
- * Detects: skill invocations, agent spawns, skill pushes.
+ * Detects: skill invocations, agent spawns, skill pushes, and stage documents
+ * written by any write tool (sdlc_artifact_written: Write, Edit, MultiEdit,
+ * Codex apply_patch and shell `apply_patch` heredocs), and loop-aware stage
+ * start/finish events from state.json writes (lib/aw-usage-stage-events.js).
+ * Skill events say how the skill was reached (source: skill_tool, file_read,
+ * shell_read, or other_tool from the B6 Cursor probe), where its file came
+ * from (skill_origin) and whether it follows a typed command
+ * (follows_typed_command); see lib/aw-usage-skill-source.js.
  * PR contribution is tracked via Co-Authored-By trailer in prepare-commit-msg hook.
  * Outputs {} on stdout (Claude/Codex parse stdout as JSON).
  */
@@ -13,10 +20,14 @@ const {
   buildEvent,
   detectHarness,
   sendAsync,
-  readSessionSkill,
+  claimTypedCommandMatch,
+  computeProjectHash,
+  readSessionLastPrompt,
   readSessionLastSlashCommand,
   tryAcquireDedupe,
 } = require('../lib/aw-usage-telemetry');
+const { processStateJsonWrite } = require('../lib/aw-usage-stage-events');
+const { skillSourceFields, shellSkillReads, cursorProbeSkillReads } = require('../lib/aw-usage-skill-source');
 
 const MAX_STDIN = 1024 * 1024;
 
@@ -85,6 +96,85 @@ function detectSdlcArtifact(filePath) {
   }
   return null;
 }
+
+// ── Stage documents from every write tool (B5) ───────────────────────
+
+const PATCH_FILE_LINE = /^\*\*\* (Add|Update) File: (.+?)\s*$/gm;
+
+/** Files an apply_patch text adds or updates. Deleted files are left out. */
+function parsePatchFiles(text) {
+  const files = [];
+  for (const match of String(text || '').matchAll(PATCH_FILE_LINE)) {
+    files.push({ file_path: match[2], action: match[1] === 'Add' ? 'create' : 'edit' });
+  }
+  return files;
+}
+
+function projectRoot(input) {
+  const root = input?.cwd || (Array.isArray(input?.workspace_roots) && input.workspace_roots[0]) || '';
+  return normalizePath(root).replace(/\/+$/, '');
+}
+
+/**
+ * Path relative to the project root when inside it. Outside it, a feature
+ * document sends only its `.aw_docs/…` part (no home folder or user name);
+ * any other path is sent as given.
+ */
+function relativeToProject(filePath, input) {
+  const norm = normalizePath(filePath);
+  const root = projectRoot(input);
+  if (root && norm.startsWith(`${root}/`)) return norm.slice(root.length + 1);
+  const awDocs = norm.indexOf('/.aw_docs/');
+  return awDocs >= 0 ? norm.slice(awDocs + 1) : norm;
+}
+
+function absoluteInProject(filePath, input) {
+  const norm = normalizePath(filePath);
+  const root = projectRoot(input);
+  return root && !norm.startsWith('/') && !/^[A-Za-z]:\//.test(norm) ? `${root}/${norm}` : norm;
+}
+
+function writeAction(toolName, input) {
+  if (toolName === 'Edit' || toolName === 'MultiEdit') return 'edit';
+  // Cursor uses Write to create and to edit and does not say which.
+  if (detectHarness(input) === 'cursor') return 'write';
+  return toObject(parseMaybeJsonObject(input?.tool_response)).type === 'update' ? 'edit' : 'create';
+}
+
+function writtenFiles(toolName, input) {
+  if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+    const filePath = input?.tool_input?.file_path;
+    return filePath ? [{ file_path: filePath, action: writeAction(toolName, input) }] : [];
+  }
+  if (toolName === 'apply_patch') {
+    return parsePatchFiles(input?.tool_input?.command || input?.tool_input?.input || '');
+  }
+  if (toolName === 'Bash' || toolName === 'Shell') {
+    const command = getCommand(input);
+    return /\bapply_patch\b/.test(command) && command.includes('*** Begin Patch') ? parsePatchFiles(command) : [];
+  }
+  return [];
+}
+
+function stageDocumentEvents(toolName, input) {
+  const events = [];
+  for (const file of writtenFiles(toolName, input)) {
+    const artifact = detectSdlcArtifact(absoluteInProject(file.file_path, input));
+    if (!artifact) continue;
+    events.push({
+      eventType: 'sdlc_artifact_written',
+      payload: {
+        file_path: relativeToProject(file.file_path, input),
+        action: file.action,
+        tool_name: toolName,
+        artifact_type: artifact.artifact_type,
+        sdlc_stage: artifact.sdlc_stage,
+      },
+    });
+  }
+  return events;
+}
+
 function parseMaybeJsonObject(value) {
   if (typeof value !== 'string') return value;
   const trimmed = value.trim();
@@ -213,33 +303,48 @@ function shouldEmitSkillName(skillName) {
   return Boolean(skillName) && skillName !== 'using-aw-skills';
 }
 
+// One skill_invoked event. `skill` is { name, path? }: the path decides
+// skill_origin for file and shell reads, the name for the Skill tool.
+// follows_typed_command is added by processPostToolUseInput, which owns the
+// session state; this collector stays free of side effects.
+function skillEvent(source, input, skill, options) {
+  return {
+    eventType: 'skill_invoked',
+    payload: {
+      skill_name: skill.name,
+      ...skillSourceFields(source, input, skill, { home: options.home }),
+    },
+  };
+}
+
+function withTypedCommandMatch(event, claimTypedCommand) {
+  if (event.eventType !== 'skill_invoked' || !claimTypedCommand(event.payload.skill_name)) return event;
+  return { ...event, payload: { ...event.payload, follows_typed_command: true } };
+}
+
 function collectPostToolUseEvents(input, options = {}) {
   const events = [];
   const toolName = input?.tool_name || '';
-  const promptSkillOverride = options.promptSkillOverride || null;
   // Session-scoped slash command from the most recent /aw:*, /tdd, etc.
   // Used to correlate test/artifact writes back to the originating SDLC stage.
   const slashCmd = options.sessionSlashCommand || null;
 
   // Skill detection: Claude uses tool_name='Skill', Cursor reads SKILL.md via 'Read' tool.
   const filePath = input?.tool_input?.file_path || '';
-  const isSkillRead = toolName === 'Read' && /\/SKILL\.md$/i.test(filePath);
+  const skillPath = normalizePath(filePath);
+  const isSkillRead = toolName === 'Read' && /\/SKILL\.md$/i.test(skillPath);
 
   if (toolName === 'Skill' || isSkillRead) {
     let skillName = input?.tool_input?.skill || input?.tool_input?.args?.skill || '';
     // For Cursor: extract skill name from path (e.g. .../skills/<skill-name>/SKILL.md)
     if (!skillName && isSkillRead) {
-      const pathMatch = filePath.match(/\/skills\/([^/]+)\/SKILL\.md$/i);
-      skillName = pathMatch ? pathMatch[1] : filePath.split('/').slice(-2, -1)[0] || '';
+      const pathMatch = skillPath.match(/\/skills\/([^/]+)\/SKILL\.md$/i);
+      skillName = pathMatch ? pathMatch[1] : skillPath.split('/').slice(-2, -1)[0] || '';
     }
     if (shouldEmitSkillName(skillName)) {
-      events.push({
-        eventType: 'skill_invoked',
-        payload: {
-          skill_name: skillName,
-          args: input?.tool_input?.args || '',
-        },
-      });
+      events.push(toolName === 'Skill'
+        ? skillEvent('skill_tool', input, { name: skillName }, options)
+        : skillEvent('file_read', input, { name: skillName, path: skillPath }, options));
     }
   } else if (toolName === 'Agent') {
     events.push({
@@ -251,6 +356,15 @@ function collectPostToolUseEvents(input, options = {}) {
     });
   }
 
+  // B6 probe: remove in the release after the one that ships it
+  // (https://app.clickup.com/t/14zhcp5e0b5). Finds the tool Cursor uses to load
+  // a skill when it is not Read, a shell or a search tool.
+  if (detectHarness(input) === 'cursor') {
+    for (const read of cursorProbeSkillReads(toolName, input?.tool_input)) {
+      if (shouldEmitSkillName(read.name)) events.push(skillEvent('other_tool', input, read, options));
+    }
+  }
+
   const toolResult = normalizeToolResult(input);
   if (isExplicitFailureExitCode(toolResult.exitCode)
     || inferShellFailureFromMessage(toolName, toolResult.rawErrorMessage)) {
@@ -296,18 +410,10 @@ function collectPostToolUseEvents(input, options = {}) {
       });
     }
 
-    // Codex skill detection: Bash commands that read SKILL.md files.
-    if (!promptSkillOverride) {
-      const skillCmdMatch = cmd.match(/\/skills\/([^/]+)\/SKILL\.md/i);
-      if (skillCmdMatch && shouldEmitSkillName(skillCmdMatch[1])) {
-        events.push({
-          eventType: 'skill_invoked',
-          payload: {
-            skill_name: skillCmdMatch[1],
-            args: '',
-          },
-        });
-      }
+    // Codex loads skills with shell reads (`sed -n … SKILL.md` inside compound
+    // commands): one event per distinct SKILL.md, also while a typed command is active.
+    for (const read of shellSkillReads(cmd)) {
+      if (shouldEmitSkillName(read.name)) events.push(skillEvent('shell_read', input, read, options));
     }
     if (/\baw\s+push\b/.test(cmd)) {
       const skillMatch = cmd.match(/aw\s+push\s+(\S+)/);
@@ -361,22 +467,40 @@ function collectPostToolUseEvents(input, options = {}) {
     }
   }
 
+  events.push(...stageDocumentEvents(toolName, input));
+
   return events;
 }
 
+// B4: a write to .aw_docs/features/<slug>/state.json by any write tool.
+function stageEvents(input, sessionId) {
+  try {
+    const root = projectRoot(input);
+    const lastPromptCommands = readSessionLastPrompt(sessionId)?.commands || [];
+    return writtenFiles(input?.tool_name || '', input).flatMap(file => processStateJsonWrite({
+      filePath: file.file_path,
+      projectRoot: root,
+      projectHash: computeProjectHash(input?.cwd || (Array.isArray(input?.workspace_roots) && input.workspace_roots[0]) || null),
+      lastPromptCommands,
+    }));
+  } catch {
+    // Odd hook input: no stage events, but the other events of this tool call are still sent.
+    return [];
+  }
+}
+
 function processPostToolUseInput(input, deps = {}) {
   const emit = typeof deps.emit === 'function' ? deps.emit : () => {};
   const sessionId = getSessionId(input);
-  const promptSkillOverride = deps.promptSkillOverride || readSessionSkill(
-    sessionId,
-    input?.turn_id || null,
-  );
   const sessionSlashCommand = deps.sessionSlashCommand
     || readSessionLastSlashCommand(sessionId);
-  const events = collectPostToolUseEvents(input, {
-    promptSkillOverride,
-    sessionSlashCommand,
-  });
+  const claimTypedCommand = typeof deps.claimTypedCommand === 'function'
+    ? deps.claimTypedCommand
+    : skillName => claimTypedCommandMatch(sessionId, input?.turn_id || null, skillName);
+  const events = [
+    ...collectPostToolUseEvents(input, { sessionSlashCommand }).map(event => withTypedCommandMatch(event, claimTypedCommand)),
+    ...stageEvents(input, sessionId),
+  ];
   for (const event of events) {
     emit(event.eventType, event.payload);
   }
@@ -426,6 +550,8 @@ if (require.main === module) {
 
 module.exports = {
   collectPostToolUseEvents,
+  parsePatchFiles,
+  relativeToProject,
   detectDeployCommand,
   detectSdlcArtifact,
   detectTestFramework,