V3 Security, Backward Compat & Agent Teams Hooks

[ruvnet]

Summary

• Security: Remove sqlite3 and bcrypt dependency chains, eliminating 10 HIGH severity vulnerabilities and 73+ transitive packages (closes Security vulnerabilities #1091)
• Backward Compatibility: Older settings.json hook configs no longer error on missing --success flag
• Agent Teams: Init generator now includes TeammateIdle and TaskCompleted hooks for multi-agent coordination
• ESM Fix: Rename helper scripts from .js to .cjs for CommonJS compatibility with "type": "module" root

---

Security Fixes (Issue #1091)

Vulnerability Chain Eliminated

BEFORE:
claude-flow → bcrypt → @mapbox/node-pre-gyp → tar@6.2.1 (10 HIGH CVEs)
@claude-flow/memory → agentdb → sqlite3 → node-gyp → tar@6.2.1

AFTER:
claude-flow → (bcrypt removed, never used in umbrella)
@claude-flow/memory → agentdb@2.0.0-alpha.3.5 → (sqlite3 removed, sql.js WASM is actual backend)

Metric	Before	After
HIGH vulnerabilities	10	0
Deprecation warnings	11	4 (upstream agentic-flow only)
Transitive packages removed	—	73+

Package Updates

Package	Version	Change
agentdb	2.0.0-alpha.3.5	Removed sqlite3 from optionalDeps
@claude-flow/memory	3.0.0-alpha.9	Pinned agentdb@2.0.0-alpha.3.5
@claude-flow/cli	3.1.0-alpha.34	Backward compat + version bump
claude-flow	3.1.0-alpha.34	Removed bcrypt, pinned agentdb

---

Backward Compatibility

Older settings.json configurations that call CLI hooks without --success flag now work without errors:

// OLD CONFIG (still works now):
"command": "npx claude-flow@alpha hooks post-edit --file '{}' --format true --update-memory true"
// Previously: [ERROR] Required option missing: --success
// Now: defaults --success to true

Changes in hooks.ts

Hook	Fix
pre-edit	--file defaults to 'unknown' instead of erroring
post-edit	--success defaults to true, --file defaults to 'unknown'
post-command	--success defaults to true
post-task	--success defaults to true

Rationale: PostToolUse hooks fire on success (Claude Code convention), so defaulting to true is semantically correct. PostToolUseFailure is used for failures.

---

Agent Teams Hooks

Added TeammateIdle and TaskCompleted to the init settings generator so npx claude-flow init produces configs with full Agent Teams support:

// TeammateIdle — auto-assign pending tasks to idle teammates
hooks.TeammateIdle = [{
  hooks: [{
    type: 'command',
    command: 'node .claude/helpers/hook-handler.cjs post-task',
    timeout: 5000,
  }],
}];

// TaskCompleted — train patterns and record completion
hooks.TaskCompleted = [{
  hooks: [{
    type: 'command',
    command: 'node .claude/helpers/hook-handler.cjs post-task',
    timeout: 5000,
  }],
}];

---

ESM Compatibility Fix

Root package.json has "type": "module", causing .js files to be parsed as ESM. Helper scripts use require() (CommonJS), so they must use .cjs extension:

• .claude/helpers/router.js → router.cjs
• .claude/helpers/session.js → session.cjs
• .claude/helpers/memory.js → memory.cjs
• hook-handler.cjs updated to reference .cjs files

---

New Capabilities Overview

Claude Code Agent Teams Integration

• TeamCreate, TaskCreate/TaskList/TaskUpdate, SendMessage tools
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var enabled by init
• Hook-based coordination: TeammateIdle, TaskCompleted, SubagentStart
• Background agent spawning with run_in_background: true

Cross-Platform Hook System

• All hooks use node .claude/helpers/hook-handler.cjs <command>
• No bash-specific syntax (no 2>/dev/null, no /bin/bash -c)
• Works identically on Windows, macOS, and Linux
• Unified dispatcher with graceful module loading via safeRequire()

Intelligence Layer

• intelligence.cjs — Pattern matching from MEMORY.md files
• router.cjs — Agent routing by task keyword patterns
• session.cjs — Cross-platform session persistence
• memory.cjs — Simple key-value memory store
• PageRank context, Jaccard similarity, edit tracking

Memory Architecture

• Primary: sql.js (WASM, zero native deps, cross-platform)
• Optional: better-sqlite3 (native, faster, graceful fallback)
• HNSW indexing for 150x-12,500x faster vector search
• Learning bridge, memory graph, agent scopes

Published Packages

All packages verified on npm with npm audit showing 0 vulnerabilities:

• npx claude-flow@alpha → 3.1.0-alpha.34
• npx @claude-flow/cli@alpha → 3.1.0-alpha.34
• npm install @claude-flow/memory@alpha → 3.0.0-alpha.9

Test plan

• hooks post-task without --success → exit 0
• hooks post-edit without --success → exit 0
• hooks post-command without --success → exit 0
• hooks pre-edit without --file → exit 0
• hooks post-task --success true → still works (regression)
• hooks post-edit --success false → still works (regression)
• Old-style cat | jq | xargs piped hooks → work end-to-end
• hook-handler.cjs post-task → [OK] Task completed
• hook-handler.cjs post-edit → [OK] Edit recorded
• npm install claude-flow@3.1.0-alpha.34 → 0 vulnerabilities
• npm install @claude-flow/memory@3.0.0-alpha.9 → 0 vulnerabilities
• npm ls tar → not in dependency tree
• npm ls sqlite3 → not in dependency tree
• Init generator includes TeammateIdle/TaskCompleted hooks
• Helper .cjs files load correctly with safeRequire()

🤖 Generated with claude-flow