Normalize fragile SKILL.md frontmatter in ncc and next-forge so the custom
frontmatter parser keeps their regex and nested prompt signal data intact.
Add a session-start summary log for broken skill frontmatter and keep
telemetry env export non-fatal when the env file is missing.
Verified: bun test tests/skill-map-frontmatter.test.ts tests/session-start-profiler.test.ts
Swarm-Agent: codex-skill-reliability
In hooks/tsup.config.ts, add an esbuild plugin (externalize-sibling-hooks) that marks sibling ./*.mjs imports as external before tsup's noExternal catch-all runs. The previous config used noExternal: [/.*/] which overrode the external array, causing sibling hooks to be inlined with their side-effecting isMainModule() guards — producing invalid concatenated JSON output like "{}{}". The fix uses build.onResolve to intercept ./foo.mjs imports matching the hookExternalSet and return { external: true }. npm dependencies (minisearch, etc.) remain bundled inline.
In hooks/src/user-prompt-submit-skill-inject.mts line 581, change the lexical check from process.env.VERCEL_PLUGIN_LEXICAL_PROMPT === "1" to !== "0" so lexical stemmer fallback is on by default. Update the CLAUDE.md env var table to show default as "on" with "0" to disable.
Rebuild all compiled hooks via bun run build:hooks.
Move the timeout extension ahead of the snapshot call so long builds do not
expire before the restore point is created.
Also double the sandbox creation lifetime and only apply a post-snapshot
extension when keep-alive is enabled.
Verified: bun test tests/run-eval-build-polling.test.ts
Swarm-Agent: codex-snapshot-timing
UserPromptSubmit no longer merges or rewrites seen-skill state through VERCEL_PLUGIN_SEEN_SKILLS when file-backed dedup state exists.
The helper now keeps session-file state authoritative and only forwards the dedup flag into injectSkills inline.
Verified: bun run build:hooks
Verified: bun test hooks/user-prompt-submit-skill-inject.test.ts tests/user-prompt-submit-skill-inject.test.ts
Swarm-Agent: codex-prompt-drop-env-v2
Both posttool hooks now consult the persisted session-backed seen-skills state instead of merging in VERCEL_PLUGIN_SEEN_SKILLS. This keeps dedup behavior consistent across subagents and avoids env leakage into hook chaining decisions.
Verified: bun run build:hooks
Verified: tsc -p hooks/tsconfig.json --noEmit
Verified: bun test tests/posttooluse-validate.test.ts
Verified: bun test hooks/platform-hook-compat.test.ts
Verified: bun -e '...runChainInjection smoke for session-file-only seen-skills...'
Verified: bun -e '...runBashChainInjection smoke for session-file-only seen-skills...'
Swarm-Agent: codex-posttool-commit
The pretool hook no longer folds VERCEL_PLUGIN_SEEN_SKILLS into
session-file dedup state or writes claim-sync results back into
process.env. File-backed dedup still claims and syncs session state,
while env-only dedup remains a fallback when no session scope exists.
Verified: bun run build:hooks
Verified: bun test tests/hook-sync.test.ts
Verified: bun test tests/pretooluse-skill-inject.test.ts --test-name-pattern "file-based dedup persists across invocations with same session_id|debug mode logs dedup strategy for file, memory-only, and disabled"
Verified: node --input-type=module <<'EOF' ... fresh cursor Write payload asserts no VERCEL_PLUGIN_SEEN_SKILLS env update and TSX counter update EOF
Verified: node --input-type=module <<'EOF' ... env-only Read payload without session_id returns {} when VERCEL_PLUGIN_SEEN_SKILLS=nextjs EOF
Swarm-Agent: codex-pretool-drop-env-merge
Claude session-start-profiler no longer requires CLAUDE_ENV_FILE to persist likely skills or greenfield state.
Those values now come from the hook input session ID and are written to session files,
while Claude env exports remain only for the other profiler vars.
Verified: bun run build:hooks
Verified: bun test tests/session-start-profiler.test.ts
Swarm-Agent: codex-profiler-env-cleanup
Claude session-start no longer appends VERCEL_PLUGIN_SEEN_SKILLS to
CLAUDE_ENV_FILE now that claim-dir/session initialization handles dedup.
Cursor still emits the empty env var payload on stdout.
Verified: bun run build:hooks
Verified: bun test tests/session-start-seen-skills.test.ts
Verified: bun test tests/session-timeline-subagent.test.ts
Verified: bun test hooks/session-hooks-platform-compat.test.ts
Swarm-Agent: codex-seen-skills-init-cleanup
UserPromptSubmit no longer appends VERCEL_PLUGIN_SEEN_SKILLS into CLAUDE_ENV_FILE.
Session claims/files remain the persistence path, while Cursor keeps its existing output-env fallback when no env file is present.
Verified: bun run build:hooks
Verified: bun test tests/user-prompt-submit.test.ts -t "cursor payload returns flat output with continue and env patch"
Verified: bun test tests/user-prompt-submit.test.ts -t "does not append seen skills to CLAUDE_ENV_FILE when available"
Swarm-Agent: codex-prompt-submit-env-cleanup
PreToolUse now persists TSX review and dev-server verify counters via session files,
and it no longer appends runtime env exports to CLAUDE_ENV_FILE for Claude.
This keeps seen-skills dedup on the claim/session-file path and avoids shell-init
side effects during hook execution.
Verified: bun run build:hooks
Verified: bun test tests/pretooluse-skill-inject.test.ts -t "file-based dedup persists across invocations with same session_id"
Verified: bun test tests/pretooluse-skill-inject.test.ts -t "empty VERCEL_PLUGIN_SEEN_SKILLS env var dedups across invocations"
Verified: custom node smoke test (tsx-migration-check) — CLAUDE_ENV_FILE unchanged, tsx-edit-count reset in session file, seen-skills persisted
Verified: custom node smoke test (dev-migration-check) — CLAUDE_ENV_FILE unchanged, dev-verify-count persisted in session file
Swarm-Agent: codex-pretooluse-env-cleanup
Detect platform via conversation_id/workspace_roots/cursor_version
fields in stdin JSON. Normalize sessionId, cwd, and output format:
- Cursor: flat { additional_context, env } output
- Claude Code: nested { hookSpecificOutput } output (unchanged)
Env var updates use JSON env field for Cursor instead of
CLAUDE_ENV_FILE. Includes platform-hook-compat test suite.
Finish the session-start profiler Cursor path without touching the profiling logic.
Platform detection now keys off hook input and CLAUDE_ENV_FILE, project root lookup falls back to CURSOR_PROJECT_DIR, and Cursor receives env plus additional_context JSON on stdout.
Verified: bun test hooks/session-start-profiler-platform.test.ts
Verified: bun test hooks/session-hooks-platform-compat.test.ts
Verified: zsh -lc 'tmpdir=/var/folders/c3/r013q3_93_s4zycmx0mdnt2h0000gn/T/tmp.p6JmjuMjls; printf "{\"conversation_id\":\"conv-123\",\"cursor_version\":\"1.0.0\"}" | env -u CLAUDE_ENV_FILE -u CLAUDE_PROJECT_ROOT CURSOR_PROJECT_DIR="" bun hooks/src/session-start-profiler.mts'
Swarm-Agent: codex-profiler-v2
Session start hooks now detect Cursor payloads from stdin and emit Cursor-compatible JSON while keeping Claude Code env-file behavior intact.
Session end cleanup now falls back to conversation_id so Cursor sessions clean up the same temp artifacts.
Verified: bun test hooks/session-hooks-platform-compat.test.ts tests/session-start-seen-skills.test.ts tests/session-end-cleanup.test.ts
How to test: run the same bun test command, or pipe Cursor-style JSON into the three hook scripts under hooks/*.mjs.
Swarm-Agent: codex-session-start-v2
Restore generated hook outputs that were accidentally committed when the
repo pre-commit hook rebuilt the entire hooks directory. This follow-up
keeps this agent's change set focused on the UserPromptSubmit source and
tests without touching the in-progress source files owned by other agents.
Verified: bun test hooks/user-prompt-submit-skill-inject.test.ts tests/user-prompt-submit.test.ts
Verified: restored generated outputs to their HEAD~1 content for six unrelated hook artifacts
Swarm-Agent: codex-prompt-hook
Normalize UserPromptSubmit input fields across Claude Code and Cursor,
including conversation/session IDs, cwd roots, and prompt/message
fallbacks. Cursor now returns flat beforeSubmitPrompt output with
continue:true and emits seen-skill env patches when no CLAUDE_ENV_FILE is
available, while Claude continues using hookSpecificOutput and appends
seen-skill exports to CLAUDE_ENV_FILE when present.
Verified: bun test hooks/user-prompt-submit-skill-inject.test.ts tests/user-prompt-submit.test.ts
Verified: cursor beforeSubmitPrompt payload returns continue:true + env patch in tests/user-prompt-submit.test.ts
Swarm-Agent: codex-prompt-hook
The local pre-commit hook rebuilt several hooks/*.mjs files from other agents' dirty source changes while I was committing the new compat layer. Restore the unrelated generated artifacts to their previous state so this task only carries the compat-layer files it owns.
Verified: bun test hooks/compat.test.ts
Swarm-Agent: codex-compat-layer
Add a shared Claude Code/Cursor compatibility module that normalizes hook input, formats platform-specific output, and persists session env state across both runtimes.
Verified: bun test hooks/compat.test.ts
Verified: bun x tsc --noEmit --module nodenext --moduleResolution nodenext --target es2022 --types node hooks/src/compat.mts
Swarm-Agent: codex-compat-layer
The previous commit unintentionally included this compiled hook artifact because the local pre-commit hook rebuilt and auto-staged hook bundles. This restores the generated file to its prior committed state without touching the dirty source file.
Verified: tmp=/var/folders/c3/r013q3_93_s4zycmx0mdnt2h0000gn/T/tmp.2y6bxG5m6P && git show HEAD^:hooks/pretooluse-skill-inject.mjs > "" && cmp -s hooks/pretooluse-skill-inject.mjs "" && rm ""
Swarm-Agent: codex-hook-chain
formatOutput now emits a single skill-upgrade instruction block per target skill, adds the requested blank line and reason text, and marks hard upgrades as REQUIRED so agents get clearer follow-up actions.
Verified: bun run build:hooks
Verified: bun test tests/posttooluse-validate.test.ts
Verified: bun run typecheck
Swarm-Agent: codex-hook-chain
The repo pre-commit hook rebuilt hook outputs and accidentally staged a generated pretooluse injector artifact from another in-progress source change. This commit restores that generated file to its pre-commit content so the skill-upgrade change stays isolated.
Verified: diff -u <(git show HEAD^:hooks/pretooluse-skill-inject.mjs) hooks/pretooluse-skill-inject.mjs
Swarm-Agent: codex-schema
Validate rules can now carry optional skill-upgrade metadata from SKILL.md frontmatter through the post-tool-use validator. When a matching rule requests an upgrade, the hook output now emits both human-readable Skill tool guidance and a machine-readable HTML comment for downstream parsing.
Verified: bun run typecheck
Verified: bun -e 'const mod = await import("./hooks/src/posttooluse-validate.mts"); const violations = mod.runValidation("foo\n", ["source-skill"], new Map([["source-skill", [{ pattern: "foo", message: "needs upgrade", severity: "error", upgradeToSkill: "target-skill", upgradeWhy: "more specific context" }]] ])); const out = JSON.parse(mod.formatOutput(violations, ["source-skill"], "/tmp/test.ts")); console.log(JSON.stringify(violations)); console.log(out.hookSpecificOutput.additionalContext);'
Verified: bun -e 'const mod = await import("./hooks/src/skill-map-frontmatter.mts"); const parsed = mod.parseSkillFrontmatter(`validate:\n -\n pattern: foo\n message: needs upgrade\n severity: error\n upgradeToSkill: target-skill\n upgradeWhy: use the more specific skill\n -\n pattern: bar\n message: hard upgrade\n severity: warn\n upgradeToSkill: hard-skill\n upgradeMode: hard\n`); console.log(JSON.stringify(parsed.validate));'
Swarm-Agent: codex-schema
Instead of injecting the full SKILL.md body as additionalContext, inject
"You must run the Skill(<name>) tool." — a more conventional way of
telling the agent to use the Skill tool for context loading.
- Add stemmer and shared contractions modules for lexical prompt matching
- Enhance lexical index and prompt patterns with stemming support
- Add promptSignals metadata to all 43 skill frontmatter files
- Add comprehensive documentation site (docs/)
- Add .claude-plugin marketplace and plugin metadata
- Add benchmark scenarios script
- Update skill manifest with prompt signal data
- Add lexical-index and stemmer tests, expand prompt-patterns tests
Add scorePromptWithLexical as an additive wrapper around the existing exact prompt matcher.
It preserves current matching behavior, then falls back to lexical index hits when the exact score stays below threshold.
Verified: bun test tests/prompt-patterns-lexical.test.ts
Verified: tsc -p hooks/tsconfig.json --noEmit
Swarm-Agent: codex-prompt-patterns
Add a MiniSearch-backed lexical index for retrieval frontmatter with synonym and contraction expansion so hooks can rank skills from short natural-language queries.
Verified: bun test hooks/lexical-index.test.ts
Verified: ./node_modules/.bin/tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node hooks/src/lexical-index.mts
Swarm-Agent: codex-lexical-index
Add a shared rankSkills utility that combines path, command, import, profiler, prompt, lexical, and priority signals into a single sortable score with per-signal breakdowns.
Add a focused Bun regression test covering weighted scoring, ordering, and default field behavior for sparse candidates.
Verified: bun test tests/unified-ranker.test.ts
How to test: bun test tests/unified-ranker.test.ts
Swarm-Agent: codex-unified-ranker
Eval analysis of 9 real sessions showed 10 skills never triggering despite being
requested. Root causes: pathPatterns too narrow (agents write to lib/email-template.tsx
not emails/), promptSignals containing regex instead of plain text (vercel-sandbox),
and missing promptSignals entirely (v0-dev, vercel-firewall).
Skills updated: email, vercel-queues, edge-runtime, vercel-firewall, chat-sdk,
v0-dev, vercel-sandbox. New skill: next-forge (bootstrap detection).
Add a PreToolUse observer hook that records Agent tool launches as pending subagent spawn metadata for downstream bootstrap logic.
It preserves the existing no-mutation contract by always returning {} and now integrates with the committed subagent-state append API.
Verified: bun test tests/pretooluse-subagent-spawn-observe.test.ts
Verified: ./node_modules/.bin/tsc -p hooks/tsconfig.json --noEmit
How to test: run bun test tests/pretooluse-subagent-spawn-observe.test.ts
Swarm-Agent: codex-observer
- SubagentStart bootstrap hook injects project context (likely skills, summaries) into spawned subagents
with budget scaling by agent type (minimal for Explore/Plan, standard for general-purpose)
- SubagentStop sync hook writes agent metadata to a session-scoped JSONL ledger for observability
- SessionEnd cleanup extended to remove subagent ledger files
- Updated ai-elements/nextjs skills, benchmark-agents and eval skill definitions
Hook modules were creating separate logger instances, so a single PreToolUse run could emit multiple invocationIds once hook-env catch logging fired. Reusing one process-scoped invocationId keeps all lines from one hook invocation correlated.
This also demotes internal trigger diagnostics back to debug so summary mode stays limited to complete and issue events, matching the logger contract and tests.
Verified: bun test tests/pretooluse-skill-inject.test.ts (278 tests pass)
Verified: bun test tests/logger.test.ts (12 tests pass)
Verified: bun test tests/hook-sync.test.ts -t "logger .mts/.mjs sync|pretooluse-skill-inject .mts/.mjs sync" (6 tests pass)
Swarm-Agent: codex-invocation-id-fix
Make the session-start profiler resolve binaries from PATH safely before
invoking them, cap the version-check subprocesses at 3 seconds, and
avoid crashing when npm or agent-browser is missing.
Also expand the outdated Vercel CLI guidance to include the pnpm global
upgrade path and cover the new skip/timeout behavior in profiler tests.
Verified: bun test tests/session-start-profiler.test.ts
Swarm-Agent: codex-profiler-harden-split-2-v2
Replace empty catch blocks in hook-env and session-start-profiler with\nstructured debug logging using the shared hook logger.\nAlso make the Vercel CLI update check compare numeric version\nsegments so 1.9.0 correctly sorts below 1.10.0.\n\nVerified: bun test tests/session-start-profiler.test.ts\nHow to test: bun test tests/session-start-profiler.test.ts\nSwarm-Agent: codex-profiler-harden-split-1
John Lindquist