specmem-hardwicksoftware 3.7.31 → 3.7.33

package/claude-hooks/specmem-session-start.cjs

@@ -283,10 +283,10 @@ function getLastSessionOutput() {
 
     let sessionContent;
     if (startIdx === -1) {
-      sessionContent = lines.slice(-200).join('\n');
+      sessionContent = lines.slice(-40).join('\n');
     } else {
       const outputLines = lines.slice(startIdx + 2, endIdx > 0 ? endIdx : undefined);
-      sessionContent = outputLines.slice(-200).join('\n');
+      sessionContent = outputLines.slice(-40).join('\n');
     }
 
     // FILTER OUT GARBAGE - Skills, corrupted content, and non-conversation data
@@ -331,6 +331,14 @@ function getLastSessionOutput() {
  * Only includes: last 10 interactions + condensed tool list
  * NO skill injection, NO verbose schemas
  */
+
+/**
+ * Compact tool reminder
+ */
+function getToolReminder() {
+  return '## SpecMem Tools Available\n\n**Memory Search:** `find_memory` | `find_code_pointers` | `drill_down` | `get_memory`\n**Storage:** `save_memory` | `link_the_vibes` | `smush_memories_together`\n**Team:** `send_team_message` | `read_team_messages` | `claim_task` / `release_task`\n**System:** `show_me_the_stats` | `check_sync` | `start_watching`\n\nUse·`/specmem`·令④ⓢ.';
+}
+
 function formatOutput(memories, lastSession, projectPath, sessionId) {
   const sections = [];
 
@@ -338,15 +346,29 @@ function formatOutput(memories, lastSession, projectPath, sessionId) {
   sections.push(`Project: ${projectPath}`);
   sections.push(`Session: ${sessionId}`);
 
-  // Previous session output (if available) - BRIEF version
+  // Previous session output (if available) - compressed
   if (lastSession && lastSession.content) {
     sections.push('');
     sections.push(`## PREVIOUS SESSION OUTPUT (${lastSession.ageMinutes}m ago, reason: ${lastSession.reason})`);
     sections.push('(Previous  session):');
-    sections.push('```');
-    // DON'T compress - just take first 500 chars of clean content
-    sections.push(lastSession.content.slice(0, 500).trim());
-    sections.push('```');
+
+    // Truncate to 40 lines for token efficiency
+    const contentLines = lastSession.content.split('\n');
+    let sessionContent;
+    if (contentLines.length > 40) {
+      sessionContent = contentLines.slice(0, 15).join('\n') +
+        `\n... [${contentLines.length - 25} lines omitted] ...\n` +
+        contentLines.slice(-10).join('\n');
+    } else {
+      sessionContent = lastSession.content;
+    }
+
+    const compressedSession = compressHookOutput(sessionContent, {
+      threshold: 0.60,
+      minLength: 30,
+      includeWarning: false
+    });
+    sections.push(compressedSession.trim());
   }
 
   // Recent memories - last 10 user/claude interactions ONLY
@@ -360,34 +382,9 @@ function formatOutput(memories, lastSession, projectPath, sessionId) {
     });
   }
 
-  // CONDENSED tool reminder - just names, no descriptions
-  sections.push('');
-  sections.push('## SpecMem Tools Available');
-  sections.push('');
-  sections.push('**Memory Search:**');
-  sections.push('- `find_memory` - Semantic search across all memories');
-  sections.push('- `find_code_pointers` - Search code with tracebacks');
-  sections.push('- `drill_down` - Explore memory details');
-  sections.push('- `get_memory` - Get specific memory by ID');
-  sections.push('');
-  sections.push('**Memory Storage:**');
-  sections.push('- `save_memory` - Store new memories');
-  sections.push('- `link_the_vibes` - Connect related memories');
-  sections.push('- `smush_memories_together` - Consolidate similar memories');
-  sections.push('');
-  sections.push('**Team Comms:**');
-  sections.push('- `send_team_message` - Message team members');
-  sections.push('- `read_team_messages` - Check team updates');
-  sections.push('- `claim_task` / `release_task` - Coordinate work');
+  // Compact tool reminder
   sections.push('');
-  sections.push('**System:**');
-  sections.push('- `show_me_the_stats` - Memory statistics');
-  sections.push('- `check_sync` - Verify file sync status');
-  sections.push('- `start_watching` - Enable file watcher');
-  sections.push('');
-  sections.push('Use `/specmem` for all commands.');
-  sections.push('');
-  sections.push('**Chinese compression:** You can read Traditional Chinese compression with 99%+ accuracy.');
+  sections.push(getToolReminder());
   sections.push('[/SPECMEM-SESSION]');
 
   return sections.join('\n');
@@ -476,23 +473,14 @@ async function main() {
   const lastSession = getLastSessionOutput();
 
   // Format output
-  let output = formatOutput(memories, lastSession, projectPath, sessionId);
-
-  // Apply Traditional Chinese compression to final output
-  const compressed = compressHookOutput(output, {
-    threshold: 0.50,
-    minLength: 100,
-    preserveStructure: true,
-    includeWarning: false  // We add our own prefix below
-  });
+  let context = formatOutput(memories, lastSession, projectPath, sessionId);
 
-  // Prepend reminder for  to read the compressed Chinese AND respond in English
-  const prefixedOutput = `[SpecMem Context - Read this for continuity]
-IMPORTANT: You can read Traditional Chinese compression with 99%+ accuracy. ALWAYS respond in English.
-${compressed}`;
-
-  // Output - clean trailing whitespace
-  console.log(prefixedOutput.split('\n').map(l => l.trimEnd()).join('\n').trim());
+  const compressedContext = compressHookOutput(context, {
+    threshold: 0.70,
+    minLength: 50,
+    includeWarning: true
+  });
+  console.log(compressedContext.trim());
 
   process.exit(0);
 }

package/claude-hooks/specmem-session-start.js

@@ -585,7 +585,7 @@ function getLastSessionOutput(projectPath) {
     if (startIdx === -1) {
       // No header found, use whole content but limit to 300 lines
       return {
-        content: lines.slice(-300).join('\n'),
+        content: lines.slice(-40).join('\n'),
         ageMinutes,
         reason: lines.find(l => l.startsWith('# Reason:'))?.replace('# Reason:', '').trim() || 'unknown'
       };
@@ -593,7 +593,7 @@ function getLastSessionOutput(projectPath) {
 
     // Get the actual output between markers, limit to last 300 lines for context efficiency
     const outputLines = lines.slice(startIdx + 2, endIdx > 0 ? endIdx : undefined);
-    const trimmedOutput = outputLines.slice(-300).join('\n');
+    const trimmedOutput = outputLines.slice(-40).join('\n');
 
     return {
       content: trimmedOutput,
@@ -639,32 +639,7 @@ function getCompactionStatus(projectPath) {
  * NOTE: Returns trimmed string with NO leading/trailing whitespace
  */
 function getToolReminder() {
-  return [
-    '## SpecMem Tools Available',
-    '',
-    '**Memory Search:**',
-    '- `find_memory` - Semantic search across all memories',
-    '- `find_code_pointers` - Search code with tracebacks',
-    '- `drill_down` - Explore memory details',
-    '- `get_memory` - Get specific memory by ID',
-    '',
-    '**Memory Storage:**',
-    '- `save_memory` - Store new memories',
-    '- `link_the_vibes` - Connect related memories',
-    '- `smush_memories_together` - Consolidate similar memories',
-    '',
-    '**Team Communication:**',
-    '- `send_team_message` - Message team members',
-    '- `read_team_messages` - Check team updates',
-    '- `claim_task` / `release_task` - Coordinate work',
-    '',
-    '**System:**',
-    '- `show_me_the_stats` - Memory statistics',
-    '- `check_sync` - Verify file sync status',
-    '- `start_watching` - Enable file watcher',
-    '',
-    'Use `/specmem` for quick commands or `/specmem-drilldown` for deep search.'
-  ].join('\n');
+  return '## SpecMem Tools Available\n\n**Memory Search:** `find_memory` | `find_code_pointers` | `drill_down` | `get_memory`\n**Storage:** `save_memory` | `link_the_vibes` | `smush_memories_together`\n**Team:** `send_team_message` | `read_team_messages` | `claim_task` / `release_task`\n**System:** `show_me_the_stats` | `check_sync` | `start_watching`\n\nUse·`/specmem`·令④ⓢ.';
 }
 
 /**
@@ -773,28 +748,21 @@ async function main() {
     // Truncate to ~200 lines for token efficiency but keep the important parts
     const contentLines = lastSession.content.split('\n');
     let sessionContent;
-    if (contentLines.length > 200) {
-      sessionContent = contentLines.slice(0, 50).join('\n') +
-        `\n... [${contentLines.length - 100} lines omitted] ...\n` +
-        contentLines.slice(-50).join('\n');
+    if (contentLines.length > 40) {
+      sessionContent = contentLines.slice(0, 15).join('\n') +
+        `\n... [${contentLines.length - 25} lines omitted] ...\n` +
+        contentLines.slice(-10).join('\n');
     } else {
       sessionContent = lastSession.content;
     }
 
-    // SESSION CONTENT: Output FULL readable content (no compression)
-    // Compression was causing unreadable Chinese output - disabled for readability
-    // Only compress if explicitly requested via SPECMEM_COMPRESS_SESSION=1
     sections.push('```');
-    if (process.env.SPECMEM_COMPRESS_SESSION === '1') {
-      const compressedSession = compressHookOutput(sessionContent, {
-        threshold: 0.60,
-        minLength: 30,
-        includeWarning: false  // Warning already added at top level
-      });
-      sections.push(compressedSession.trim());
-    } else {
-      sections.push(sessionContent.trim());
-    }
+    const compressedSession = compressHookOutput(sessionContent, {
+      threshold: 0.60,
+      minLength: 30,
+      includeWarning: false
+    });
+    sections.push(compressedSession.trim());
     sections.push('```');
   }
 
@@ -857,21 +825,12 @@ async function main() {
     .replace(/\n{3,}/g, '\n\n')   // Collapse 3+ newlines to 2 (one blank line)
     .trim();                       // Remove leading/trailing whitespace
 
-  // SESSION START: Output full context WITHOUT compression
-  // Compression makes debugging hard and context is injected at start when there's room
-  // Only compress if SPECMEM_COMPRESS_SESSION is set
-  if (process.env.SPECMEM_COMPRESS_SESSION === '1') {
-    const compressedContext = compressHookOutput(context, {
-      threshold: 0.70,
-      minLength: 50,
-      includeWarning: true
-    });
-    // Final trim to ensure no trailing whitespace
-    console.log(compressedContext.trim());
-  } else {
-    // Output full readable context (already trimmed above)
-    console.log(context);
-  }
+  const compressedContext = compressHookOutput(context, {
+    threshold: 0.70,
+    minLength: 50,
+    includeWarning: true
+  });
+  console.log(compressedContext.trim());
 
   process.exit(0);
 }

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 };
     }