specmem-hardwicksoftware 3.7.32 → 3.7.34

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to SpecMem - we keep it real with semantic versioning. Deada
 
 ---
 
+## [3.7.34] - 2026-02-26
+
+### Fixed
+- System reminder dedup bug — `String.replace(string, '')` only removes first occurrence; duplicate identical reminders in same message block now fully nuked via `while(includes)` loop
+- Edit tool stripping bug — `smartStripEdit(block)` was passing the whole tool_use block instead of `block.input`, causing null return and no stripping of Edit payloads in old messages
+
+---
+
+## [3.7.33] - 2026-02-26
+
+### Fixed
+- Token compaction proxy reliability — resolved connection drops and socket failures under sustained load
+- Multi-project registry for translation socket resolution — daemon now iterates registered projects to find active socket instead of hardcoded path
+- System reminder stripping — strips redundant `<system-reminder>` blocks (keeps first occurrence), reduces token overhead per request
+- Compaction proxy minimum translate length removed — all content now eligible for compression regardless of size
+
+### Improved
+- Token usage efficiency — advanced stenographic compression now applied to all tool results and system prompts, measurably lower token consumption per session
+- Agent behavior modification hooks — agents now properly communicate via team messaging tools and use SpecMem tool calls as expected
+- Tool call enforcement — bash call enforcer upgraded with better debouncing and team comms validation
+- Team communications enforcer — improved reliability of inter-agent message routing
+- Multi-project resource sharing — compaction daemon tracks project registry with cache invalidation on changes
+- README updated with new "How to Install on Linux Systems" SVG featuring Debian, Ubuntu, Ubuntu LTS, Mint, and Kali Linux
+
+### Added
+- Project registry system in compaction proxy — tracks all registered projects for shared translation memory and synonym caches
+- Dynamic translate socket resolution across registered projects (sorted by last-seen)
+- `SYSTEM_REMINDER_STRIPPING` live config toggle
+- New skill commands for agent orchestration and autoclaude workflows
+
+---
+
 ## [3.7.32] - 2026-02-24
 
 ### Fixed

package/README.md

@@ -1,3 +1,5 @@
+## Token compression currently broken - please run specmem proxy off before running specmem init - until this is fixed!
+
 <!-- Debian/Ubuntu/Mint/Kali notice -->
 <div align="center">
 <table><tr><td align="center" style="background:#0d1117;border:1px solid #30363d;border-radius:8px;padding:12px 20px">
@@ -12,8 +14,8 @@
 
 <div align="center">
 
-<!-- Demo GIF -->
-<img src="./IMG_4365.gif" alt="SpecMem Demo" width="400">
+<!-- How to Install SVG -->
+<img src="./svg-sections/readme-how-to-install.svg" alt="How to Install SpecMem on Linux" width="800">
 
 <br/>
 <br/>

package/bin/specmem-cli.cjs

@@ -779,7 +779,7 @@ function manageProxy(args) {
   switch (sub) {
     case 'disable':
     case 'off': {
-      // Create disabled flag
+      // Create disabled flag — daemon stays running but in passthrough mode
       try {
         if (!fs.existsSync(claudeDir)) fs.mkdirSync(claudeDir, { recursive: true });
         fs.writeFileSync(disabledFile, new Date().toISOString(), { mode: 0o644 });
@@ -788,40 +788,17 @@ function manageProxy(args) {
         process.exit(1);
       }
 
-      // Remove port file so wrapper won't try
-      try { if (fs.existsSync(portFile)) fs.unlinkSync(portFile); } catch (e) { /* ok */ }
-
-      // Kill the running proxy if it's up
-      const port = process.env.COMPACTION_PROXY_PORT || '4080';
+      // Switch the running proxy to paused (passthrough) mode — don't kill it
+      const disablePort = process.env.COMPACTION_PROXY_PORT || '4080';
       try {
-        execSync(`curl -sf http://127.0.0.1:${port}/health`, { timeout: 1000, stdio: 'pipe' });
-        // Proxy is running — find and kill it
-        try {
-          const pid = execSync(`lsof -ti tcp:${port} -s tcp:listen 2>/dev/null`, { encoding: 'utf8' }).trim();
-          if (pid) {
-            process.kill(parseInt(pid), 'SIGTERM');
-            console.log(`${GREEN}✓${RESET} Killed running proxy (PID ${pid})`);
-          }
-        } catch (e) { /* couldn't find pid, that's ok */ }
+        execSync(`curl -sf -X POST http://127.0.0.1:${disablePort}/pause`, { timeout: 2000, stdio: 'pipe' });
+        console.log(`${GREEN}✓${RESET} Proxy switched to ${YELLOW}passthrough${RESET} mode`);
       } catch (e) {
-        // Proxy not running
+        // Proxy not running — that's fine, flag will keep next start paused
       }
 
-      // Remove the bashrc block that sets ANTHROPIC_BASE_URL so new shells don't get it
-      try {
-        const bashrc = path.join(os.homedir(), '.bashrc');
-        if (fs.existsSync(bashrc)) {
-          const content = fs.readFileSync(bashrc, 'utf8');
-          const cleaned = content.replace(/\n?# specmem-proxy-env\n(?:# [^\n]*\n)*if \[ -f "\$HOME\/\.claude\/\.compaction-proxy-port" \];[\s\S]*?fi\n?/g, '\n');
-          if (cleaned !== content) {
-            fs.writeFileSync(bashrc, cleaned);
-            console.log(`${GREEN}✓${RESET} Removed proxy env from .bashrc`);
-          }
-        }
-      } catch (e) { /* non-fatal */ }
-
-      console.log(`${GREEN}✓${RESET} Compaction proxy ${RED}disabled${RESET}`);
-      console.log(`  ${DIM}Proxy won't start on next session${RESET}`);
+      console.log(`${GREEN}✓${RESET} Compaction proxy ${RED}disabled${RESET} (passthrough — traffic still flows)`);
+      console.log(`  ${DIM}Proxy stays running but passes all requests through untouched${RESET}`);
       console.log(`\n  ${DIM}Re-enable with: ${CYAN}specmem proxy enable${RESET}`);
       break;
     }
@@ -831,9 +808,17 @@ function manageProxy(args) {
       // Remove disabled flag
       try { if (fs.existsSync(disabledFile)) fs.unlinkSync(disabledFile); } catch (e) { /* ok */ }
 
+      // Unpause the running proxy — activate compression immediately
+      const enablePort = process.env.COMPACTION_PROXY_PORT || '4080';
+      try {
+        execSync(`curl -sf -X POST http://127.0.0.1:${enablePort}/resume`, { timeout: 2000, stdio: 'pipe' });
+        console.log(`${GREEN}✓${RESET} Proxy compression ${GREEN}activated${RESET}`);
+      } catch (e) {
+        // Proxy not running — will start active on next session
+      }
+
       console.log(`${GREEN}✓${RESET} Compaction proxy ${GREEN}enabled${RESET}`);
-      console.log(`  ${DIM}Proxy will start on next Claude session${RESET}`);
-      console.log(`  ${DIM}Or restart Claude now to activate immediately${RESET}`);
+      console.log(`  ${DIM}Compression active immediately (no restart needed)${RESET}`);
       break;
     }
 

package/bootstrap.cjs

@@ -955,7 +955,11 @@ function syncProjectConfigs() {
       // Backup and write
       const backupPath = `${claudeJsonPath}.backup.${Date.now()}`;
       fs.copyFileSync(claudeJsonPath, backupPath);
-      fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeConfig, null, 2), 'utf-8');
+      // ATOMIC WRITE: write to temp file then rename to prevent corruption
+      // fs.writeFileSync truncates first, so Claude Code can read a partial file mid-write
+      const tmpPath = claudeJsonPath + '.tmp.' + process.pid;
+      fs.writeFileSync(tmpPath, JSON.stringify(claudeConfig, null, 2), 'utf-8');
+      fs.renameSync(tmpPath, claudeJsonPath);
       startupLog(`CONFIG SYNC: Fixed ${fixedProjects.length} stale project configs: ${fixedProjects.join(', ')}`);
 
       // Clean up old backups (keep last 3)

package/claude-hooks/agent-loading-hook.js

@@ -734,53 +734,37 @@ async function loadSkills() {
 function getMinimalTeamContext() {
   return `
 
-[MANDATORY-FIRST-ACTION]
-Before doing ANYTHING else, you MUST announce yourself:
-send_team_message({type:"status", message:"Starting: [your task summary]"})
-If you skip this, ALL your tool calls will be BLOCKED. No exceptions.
-[/MANDATORY-FIRST-ACTION]
-
-[TEAM CONTEXT]
-You are a developer on a software development team. The senior engineer on this team is skeptical of AI assistance, so you must perform your tasks efficiently and communicate well with your fellow developers.
-
-⚠️ CRITICAL: YOU MUST USE MCP TOOLS TO COMPLETE YOUR TASK ⚠️
-There is NO alternative path. The system ENFORCES MCP tool usage:
-- You CANNOT proceed without announcing via send_team_message FIRST
-- You CANNOT write code without claiming files via claim_task
-- You CANNOT search more than 3 times without using find_memory/find_code_pointers
-- Every 4 tool calls, you WILL BE BLOCKED until you check read_team_messages (team comms)
-- Every 5 tool calls, you WILL BE BLOCKED until you check read_team_messages with include_broadcasts:true
-- Every 8 tool calls, you WILL BE BLOCKED until you check get_team_status for help requests
-- These counters apply to ALL tool calls, including memory tools and searches - no exceptions
-If you want to complete your goal, you MUST use MCP tools. There is no workaround.
-
-TEAM COMMUNICATION (mcp__specmem__ prefix):
-- send_team_message({message, channel:"main"|"swarm-1".."swarm-5", type:"status"|"question"|"update", priority})
-- read_team_messages({limit:5, include_swarms:true}) - MANDATORY every 4 tool calls!
-- read_team_messages({include_broadcasts:true, include_swarms:true, limit:10}) - MANDATORY every 5 calls!
-- broadcast_to_team({message, broadcast_type:"status"|"progress"|"announcement", priority})
-- claim_task({description, files:["path1","path2"]}) - REQUIRED before editing
-- release_task({claimId:"all"|"<id>"}) - release when done
-- get_team_status({}) - see active claims, help requests, team activity
-- request_help({question, context, skills_needed:["skill1"]}) - ASK OTHER SWARMS FOR HELP!
-- respond_to_help({requestId, response}) - HELP OTHER SWARMS! Helping hands make the world go round!
-
-MEMORY TOOLS (MANDATORY - enforced by hooks):
-- find_memory({query, limit:10}) - semantic search for past conversations and decisions
-- find_code_pointers({query, limit:10, includeTracebacks:true}) - semantic code search with callers/callees
-- save_memory({content, importance, memoryType, tags}) - save important findings
-- drill_down({drilldownID}) - get full context on a memory result
-- getMemoryFull({id}) - get full memory with live code
-
-WORKFLOW (enforced - you cannot skip steps):
-1. START: send_team_message({type:"status", message:"Starting: [task]"})
-2. CLAIM: claim_task({description, files}) - REQUIRED before any writes
-3. SEARCH: find_memory/find_code_pointers FIRST, then Grep/Glob if needed
-4. EVERY 4 CALLS: read_team_messages({include_swarms:true, limit:5}) - MANDATORY, you WILL be blocked
-5. EVERY 5 CALLS: read_team_messages({include_broadcasts:true, include_swarms:true, limit:10}) - MANDATORY
-6. EVERY 8 CALLS: get_team_status() - check if anyone needs help!
-6. DONE: release_task({claimId:"all"}), send completion status
-[/TEAM CONTEXT]`;
+[TEAM COLLABORATION]
+Welcome! You're joining a team of developers working on this project together. To keep things running smoothly and avoid stepping on each other's toes, here's how the team stays coordinated:
+
+GETTING STARTED:
+First, let the team know you're here and what you'll be working on:
+  send_team_message({type:"status", message:"Starting: [your task summary]"})
+
+SEARCHING FOR CODE & CONTEXT:
+The project has semantic search tools that are much more effective than grep — use these first:
+  find_code_pointers({query:"what you're looking for"}) — semantic code search with tracebacks, shows who calls what
+  find_memory({query:"topic"}) — finds past discussions, decisions, and context from the user and other team members
+  drill_down({drilldownID: N}) — expand a result from find_code_pointers or find_memory for full detail
+If semantic search doesn't cover it, Grep/Glob are still available as a fallback.
+
+EDITING FILES:
+To avoid merge conflicts with other team members:
+  1. claim_task({description:"what you're doing", files:["path/to/file"]}) — claim before editing
+  2. Make your edits
+  3. release_task({claimId:"all"}) — release so others can work on those files
+If a file is already claimed by someone else, coordinate via send_team_message first.
+
+STAYING IN SYNC:
+Check in with the team periodically — other team members may have updates that affect your work:
+  read_team_messages({include_swarms:true, limit:5}) — see recent team activity
+  get_team_status() — see who's working on what, and if anyone needs help
+  respond_to_help({requestId, response}) — if you can help a teammate, do it!
+
+WHEN YOU'RE DONE:
+  release_task({claimId:"all"}) — free your claimed files
+  send_team_message({type:"status", message:"Completed: [summary of what you did]"})
+[/TEAM COLLABORATION]`;
 }
 
 // ============================================================================

package/claude-hooks/subagent-loading-hook.js

@@ -141,7 +141,7 @@ function handleSubagentStart(data) {
   // CRITICAL: The announcement requirement is MANDATORY and ENFORCED by team-comms-enforcer.cjs
   // Make it PROMINENT and FIRST in the context so agents don't miss it
   const shortPurpose = purpose.slice(0, 30).replace(/"/g, "'");
-  const loadingContext = '[AGENT-' + agentNum + '-MANDATORY-STARTUP] YOUR FIRST ACTION MUST BE: send_team_message({type:"status", message:"Starting: ' + shortPurpose + '"}) | WARNING: You WILL BE BLOCKED from ALL other tools until you announce via send_team_message. This is ENFORCED by hooks - no bypass possible. | Available MCP tools: send_team_message, read_team_messages, claim_task, release_task, get_team_status, find_memory, find_code_pointers | When done: send_team_message({type:"status", message:"Completed: [summary]"})';
+  const loadingContext = '[TEAM-MEMBER-' + agentNum + '] Hey! First, let the team know you are here: send_team_message({type:"status", message:"Starting: ' + shortPurpose + '"}) | For code search use find_code_pointers(), for past discussions use find_memory(), for detail use drill_down() | Before editing: claim_task(), after editing: release_task() | When done: send_team_message({type:"status", message:"Completed: [summary]"})';
 
   // suppressOutput: true = Context gets processed but doesn't spam terminal
   // The agent will output its OWN progress via team messages

package/claude-hooks/team-comms-enforcer.cjs

@@ -127,7 +127,7 @@ const WRITE_TOOLS = ['Edit', 'Write', 'NotebookEdit'];
 // - Task: can spawn sub-agents to bypass limits
 const FULL_COMPLIANCE_TOOLS = ['Bash', 'Task'];
 
-// Tools that are always allowed (reading team state + cross-swarm help)
+// Tools that are always allowed (reading team state + cross-swarm help + research)
 const ALWAYS_ALLOWED = [
   'mcp__specmem__read_team_messages',
   'mcp__specmem__get_team_status',
@@ -144,7 +144,12 @@ const ALWAYS_ALLOWED = [
   'mcp__specmem__save_memory',
   // Cross-swarm help - helping hands make the world go round!
   'mcp__specmem__request_help',
-  'mcp__specmem__respond_to_help'
+  'mcp__specmem__respond_to_help',
+  // Research tools — read-only, never block these
+  'WebFetch',
+  'WebSearch',
+  'ToolSearch',
+  'Read',
 ];
 
 // ============================================================================
@@ -214,25 +219,36 @@ function isSpecmemProject() {
  */
 function isRunningAsAgent() {
   // Method 1: Environment variable detection (most reliable)
-  // ONLY enforce for deployed team members, NOT built-in subagents (Explore, Plan, etc.)
-  // Built-in subagents have CLAUDE_SUBAGENT=1 but no MCP tools, so enforcement blocks them permanently.
+  // Deployed team members — always enforce
   if (isTeamMemberFn()) return true;
 
-  // Method 2: Check subagent tracking (from subagent-loading-hook.js SubagentStart)
-  try {
-    const agentsFile = `${PROJECT_TMP_DIR}/agents.json`;
-    if (fs.existsSync(agentsFile)) {
-      const data = JSON.parse(fs.readFileSync(agentsFile, 'utf8'));
-      const now = Date.now();
-      for (const agent of Object.values(data.agents || {})) {
-        // Agent started within last 10 min AND has no endTime = still running
-        if (!agent.endTime && agent.startTime && (now - agent.startTime < 600000)) {
-          return true;
+  // Method 2: General-purpose subagents (CLAUDE_SUBAGENT=1)
+  // These DO have MCP tools and SHOULD be enforced.
+  // Exclude Explore/Plan agents — they don't have MCP tools and can't comply.
+  // We check agents.json to see if the active subagent has MCP tools.
+  if (process.env.CLAUDE_SUBAGENT === '1' || process.env.CLAUDE_AGENT_ID) {
+    try {
+      const agentsFile = `${PROJECT_TMP_DIR}/agents.json`;
+      if (fs.existsSync(agentsFile)) {
+        const data = JSON.parse(fs.readFileSync(agentsFile, 'utf8'));
+        const now = Date.now();
+        for (const agent of Object.values(data.agents || {})) {
+          // Active agent (started within 10 min, no endTime)
+          if (!agent.endTime && agent.startTime && (now - agent.startTime < 600000)) {
+            // Check if this agent has MCP tools (general-purpose agents do)
+            const tools = agent.tools || [];
+            const hasMcpTools = tools.some(t => t.startsWith('mcp__specmem__'));
+            if (hasMcpTools) return true;
+          }
         }
       }
-    }
-  } catch {}
+    } catch {}
+    // No agents.json or no MCP tools found — this is likely Explore/Plan, skip enforcement
+    return false;
+  }
 
+  // Method 3: Check subagent tracking as fallback (parent context seeing active agents)
+  // This does NOT enforce on the parent — only on processes with CLAUDE_SUBAGENT=1
   return false;
 }
 
@@ -255,12 +271,15 @@ function isSpecmemEnabled() {
 // ============================================================================
 // BLOCK RESPONSE BUILDERS
 // ============================================================================
-function blockResponse(reason) {
+function blockResponse(tool, reason) {
+  // Each denial specifies the EXACT tool to call. Framed as team collaboration,
+  // not enforcement. "team member" language, never "agent".
+  const msg = `[TEAM COLLABORATION - call ${tool} then retry] ${reason}`;
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
       permissionDecision: 'deny',
-      permissionDecisionReason: reason
+      permissionDecisionReason: msg
     }
   });
 }
@@ -397,12 +416,8 @@ process.stdin.on('end', () => {
       state.blockedCount++;
       saveTracking(tracking);
       console.log(blockResponse(
-        `[BLOCKED] You MUST ANNOUNCE yourself first!\n\n` +
-        `This is your MANDATORY FIRST ACTION before any other tool:\n\n` +
-        `send_team_message({type:"status", message:"Starting: [describe your task]"})\n\n` +
-        `Note: If you were assigned to a specific channel (e.g. swarm-1, swarm-2), use that channel.\n` +
-        `Otherwise, the message will go to the main channel.\n\n` +
-        `After announcing, you can proceed with other tools.`
+        'mcp__specmem__send_team_message',
+        `Let other team members know what you're working on so nobody duplicates effort. Call: send_team_message({type:"status", message:"Starting: [your task]"})`
       ));
       return;
     }
@@ -424,10 +439,8 @@ process.stdin.on('end', () => {
       state.blockedCount++;
       saveTracking(tracking);
       console.log(blockResponse(
-        `[BLOCKED] MANDATORY team comms check! (${state.commsToolCount} tools since last check)\n\n` +
-        `REQUIRED: read_team_messages({include_swarms: true, limit: 5})\n\n` +
-        `You MUST check team messages every 4 tool calls. This is non-negotiable.\n` +
-        `Other agents may have critical updates for you. CHECK NOW.`
+        'mcp__specmem__read_team_messages',
+        `Quick check-in — other team members may have updates that affect your work. Call: read_team_messages({include_swarms: true, limit: 5})`
       ));
       return;
     }
@@ -441,10 +454,8 @@ process.stdin.on('end', () => {
       state.blockedCount++;
       saveTracking(tracking);
       console.log(blockResponse(
-        `[BLOCKED] MANDATORY broadcast check! (${state.broadcastToolCount} tools since last broadcast check)\n\n` +
-        `REQUIRED: read_team_messages({include_broadcasts: true, include_swarms: true, limit: 10})\n\n` +
-        `You MUST check broadcasts every 5 tool calls. This is non-negotiable.\n` +
-        `Team-wide announcements and status updates require your attention. CHECK NOW.`
+        'mcp__specmem__read_team_messages',
+        `Time to check for team-wide announcements — there may be important updates. Call: read_team_messages({include_broadcasts: true, include_swarms: true, limit: 10})`
       ));
       return;
     }
@@ -457,11 +468,8 @@ process.stdin.on('end', () => {
       state.blockedCount++;
       saveTracking(tracking);
       console.log(blockResponse(
-        `[BLOCKED] Time to check if anyone needs help! (${state.helpToolUsageCount} tools since last check)\n\n` +
-        `REQUIRED: get_team_status()\n\n` +
-        `This shows open help requests from ALL swarms. Helping hands make the world go round!\n` +
-        `If you see a request you can help with, use respond_to_help().\n` +
-        `After checking, you can continue working.`
+        'mcp__specmem__get_team_status',
+        `Quick check — another team member might need a hand. Call: get_team_status() — if someone needs help, respond_to_help().`
       ));
       return;
     }
@@ -480,7 +488,7 @@ process.stdin.on('end', () => {
     // ========================================================================
     if (state.commsToolCount === TEAM_COMMS_CHECK_INTERVAL - 1) {
       console.log(allowWithReminder(
-        `[HEADS UP] Next tool call will require team comms check. Do it now: read_team_messages({include_swarms: true, limit: 5})`
+        `Heads up — good time to check in with the team: read_team_messages({include_swarms: true, limit: 5})`
       ));
       // Don't return - continue to other checks
     }
@@ -499,12 +507,8 @@ process.stdin.on('end', () => {
         state.blockedCount++;
         saveTracking(tracking);
         console.log(blockResponse(
-          `[BLOCKED] ${state.searchCount} searches without using memory tools!\n\n` +
-          `YOU MUST USE THESE FIRST:\n` +
-          `• find_memory({query:"your search"}) - semantic memory search\n` +
-          `• find_code_pointers({query:"your search"}) - semantic code search with tracebacks\n\n` +
-          `These are MORE POWERFUL than Grep/Glob. USE THEM NOW.\n` +
-          `This resets every ${MAX_SEARCHES_BEFORE_BLOCK} searches — you must keep using them.`
+          'mcp__specmem__find_code_pointers',
+          `Grep/Glob haven't found what you need — try semantic search instead, it's much more effective. Call: find_code_pointers({query:"what you're looking for"}) — if you need more detail on a result, use drill_down(). To find what another team member or the user said, use find_memory({query:"topic"}).`
         ));
         return;
       }
@@ -513,7 +517,7 @@ process.stdin.on('end', () => {
       if (state.searchCount === MAX_SEARCHES_BEFORE_BLOCK) {
         saveTracking(tracking);
         console.log(allowWithReminder(
-          `[WARNING] Last search before BLOCK! Use find_memory() or find_code_pointers() NOW or next search will be blocked.`
+          `Tip: find_code_pointers() and find_memory() are much faster for semantic searches — try them next.`
         ));
         return;
       }
@@ -532,50 +536,63 @@ process.stdin.on('end', () => {
       const toolInput = data.tool_input || {};
       const filePath = toolInput.file_path || '';
 
-      if (!state.claimed) {
-        issues.push(`claim_task({description:"what you're doing", files:["${filePath || 'file.ts'}"]}) - CLAIM FIRST`);
-      }
-      if (!state.usedMemoryTools) {
-        issues.push(`find_memory() or find_code_pointers() to understand the code first`);
-      }
-
-      // Check file claims — agent must have THIS file in their own claim
-      // Uses GLOBAL claims file so cross-channel/cross-swarm agents see each other
+      // Check file claims — to avoid conflicts with other team members
+      let fileInOtherClaim = false;
+      let otherClaimDesc = '';
+      let fileInOwnClaim = false;
       if (filePath && state.claimed) {
         try {
           let claims = {};
           if (fs.existsSync(GLOBAL_CLAIMS_FILE)) {
             claims = JSON.parse(fs.readFileSync(GLOBAL_CLAIMS_FILE, 'utf8'));
           }
-            let fileInOwnClaim = false;
-            let fileInOtherClaim = false;
-            let otherClaimDesc = '';
-            for (const [claimId, claim] of Object.entries(claims)) {
-              if (claim.files && claim.files.some(f => filePath.endsWith(f) || f.endsWith(filePath) || f === filePath)) {
-                if (claim.sessionId === sessionId || claim.agentId === sessionId) {
-                  fileInOwnClaim = true;
-                } else {
-                  fileInOtherClaim = true;
-                  otherClaimDesc = claim.description || claim.agentId || 'another agent';
-                }
+          for (const [claimId, claim] of Object.entries(claims)) {
+            if (claim.files && claim.files.some(f => filePath.endsWith(f) || f.endsWith(filePath) || f === filePath)) {
+              if (claim.sessionId === sessionId || claim.agentId === sessionId) {
+                fileInOwnClaim = true;
+              } else {
+                fileInOtherClaim = true;
+                otherClaimDesc = claim.description || claim.agentId || 'another team member';
               }
             }
-            if (fileInOtherClaim) {
-              issues.push(`File "${filePath}" is claimed by: ${otherClaimDesc}\n   Wait for them to release_task() or coordinate via send_team_message()`);
-            } else if (!fileInOwnClaim) {
-              issues.push(`File "${filePath}" is NOT in your claim!\n   Update your claim: claim_task({description:"your task", files:["${filePath}"]})`);
-            }
+          }
         } catch (e) {}
       }
 
-      if (issues.length > 0) {
+      // Determine the specific blocker and give a targeted message
+      if (fileInOtherClaim) {
         state.blockedCount++;
         saveTracking(tracking);
         console.log(blockResponse(
-          `[BLOCKED] Cannot ${toolName} without proper preparation!\n\n` +
-          `YOU MUST DO THESE FIRST:\n` +
-          issues.map((i, idx) => `${idx + 1}. ${i}`).join('\n') + `\n\n` +
-          `Then retry your ${toolName}.`
+          'mcp__specmem__send_team_message',
+          `"${filePath}" is currently being edited by ${otherClaimDesc}. To avoid merge conflicts, coordinate with them first. Call: send_team_message({type:"status", message:"Waiting on ${filePath} — is it free yet?"})`
+        ));
+        return;
+      }
+      if (!state.claimed) {
+        state.blockedCount++;
+        saveTracking(tracking);
+        console.log(blockResponse(
+          'mcp__specmem__claim_task',
+          `To prevent edit conflicts with other team members, claim the file before editing. Call: claim_task({description:"${(filePath || 'editing').slice(0, 40)}", files:["${filePath || 'file'}"]})`
+        ));
+        return;
+      }
+      if (!fileInOwnClaim && filePath) {
+        state.blockedCount++;
+        saveTracking(tracking);
+        console.log(blockResponse(
+          'mcp__specmem__claim_task',
+          `"${filePath}" isn't in your current claim. Update it so other team members know you're working here. Call: claim_task({description:"your task", files:["${filePath}"]})`
+        ));
+        return;
+      }
+      if (!state.usedMemoryTools) {
+        state.blockedCount++;
+        saveTracking(tracking);
+        console.log(blockResponse(
+          'mcp__specmem__find_code_pointers',
+          `Before editing, check if there's existing context about this code. Call: find_code_pointers({query:"${(filePath || 'what you are editing').slice(0, 50)}"}) — or find_memory() to see what the user/team discussed about it.`
         ));
         return;
       }
@@ -601,11 +618,8 @@ process.stdin.on('end', () => {
         state.blockedCount++;
         saveTracking(tracking);
         console.log(blockResponse(
-          `[BLOCKED] You edited a file but didn't release your claim!\n\n` +
-          `File edited: ${state.editedFiles[state.editedFiles.length - 1]}\n\n` +
-          `REQUIRED: release_task({claimId:"${state.currentClaimId || 'your-claim-id'}"})\n\n` +
-          `Protocol: claim_task → Edit/Write → release_task (every time).\n` +
-          `Release now, then claim_task again for your next edit.`
+          'mcp__specmem__release_task',
+          `You're done editing ${state.editedFiles[state.editedFiles.length - 1]} — release the claim so other team members can work on it. Call: release_task({claimId:"${state.currentClaimId || 'your-claim-id'}"})`
         ));
         return;
       }
@@ -618,26 +632,31 @@ process.stdin.on('end', () => {
     if (FULL_COMPLIANCE_TOOLS.includes(toolName)) {
       const issues = [];
 
+      // Give the FIRST missing step as a specific tool call
       if (!state.announced) {
-        issues.push(`send_team_message({message:"Starting: [task]", type:"status"}) - ANNOUNCE FIRST`);
+        state.blockedCount++;
+        saveTracking(tracking);
+        console.log(blockResponse(
+          'mcp__specmem__send_team_message',
+          `Let the team know what you're working on first. Call: send_team_message({type:"status", message:"Starting: [your task]"})`
+        ));
+        return;
       }
       if (!state.claimed) {
-        issues.push(`claim_task({description:"what you're doing"}) - CLAIM YOUR WORK`);
+        state.blockedCount++;
+        saveTracking(tracking);
+        console.log(blockResponse(
+          'mcp__specmem__claim_task',
+          `Claim your task so other team members don't overlap. Call: claim_task({description:"what you're doing"})`
+        ));
+        return;
       }
       if (!state.usedMemoryTools) {
-        issues.push(`find_memory() or find_code_pointers() - USE SEMANTIC SEARCH FIRST`);
-      }
-
-      if (issues.length > 0) {
         state.blockedCount++;
         saveTracking(tracking);
-        const toolType = toolName === 'Task' ? 'sub-agents' : 'Bash';
         console.log(blockResponse(
-          `[BLOCKED] ${toolName} requires FULL protocol compliance!\n\n` +
-          `Nice try - no bypassing through ${toolType}.\n\n` +
-          `YOU MUST DO ALL OF THESE FIRST:\n` +
-          issues.map((i, idx) => `${idx + 1}. ${i}`).join('\n') + `\n\n` +
-          `NO SHORTCUTS. Follow the protocol.`
+          'mcp__specmem__find_code_pointers',
+          `Check existing context first — it'll save time. Call: find_code_pointers({query:"what you need"}) or find_memory({query:"topic"})`
         ));
         return;
       }
@@ -654,7 +673,7 @@ process.stdin.on('end', () => {
 
     if (!state.usedMemoryTools && state.searchCount > 0) {
       console.log(allowWithReminder(
-        `[REMINDER] Use find_memory() and find_code_pointers() for better results!`
+        `Tip: find_code_pointers() gives semantic code search with tracebacks, and find_memory() finds what the user or team discussed — both faster than grep.`
       ));
       return;
     }

package/dist/config/configSync.js

@@ -321,7 +321,10 @@ function syncProjectConfigs() {
         catch {
             // Ignore cleanup errors
         }
-        fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeConfig, null, 2), 'utf-8');
+        // ATOMIC WRITE: write to temp file then rename to prevent corruption
+        const tmpPath = claudeJsonPath + '.tmp.' + process.pid;
+        fs.writeFileSync(tmpPath, JSON.stringify(claudeConfig, null, 2), 'utf-8');
+        fs.renameSync(tmpPath, claudeJsonPath);
         logger.info({ projectsFixed }, '[ConfigSync] Project-level configs updated');
         return { fixed: true, projectsFixed };
     }