@aion0/forge 0.5.12 → 0.5.15

package/.forge/agent-context.json

@@ -0,0 +1,6 @@
+{
+  "workspaceId": "656c9e65-9d73-4cb6-a065-60d966e1fc78",
+  "agentId": "engineer-1774920478256",
+  "agentLabel": "Engineer",
+  "forgePort": 8403
+}

package/RELEASE_NOTES.md

@@ -1,13 +1,23 @@
-# Forge v0.5.12
+# Forge v0.5.15
 
 Released: 2026-03-31
 
-## Changes since v0.5.11
+## Changes since v0.5.14
+
+### Features
+- feat: replace Stop button with Done/Failed/Idle for running agents
+- feat: Claude Code Stop hook for agent completion detection
 
 ### Bug Fixes
-- fix: correct bin paths in package.json
-- fix: merge pending upstream_complete — auto-complete older ones before sending new
-- fix: upstream_complete notification tells agent to ignore if busy or duplicate
+- fix: suppress session monitor for 10s after manual state change
+- fix: reset session monitor state when task status manually changed
+- fix: stop button resets task to idle for terminal agents, not smith down
+- fix: session monitor fallback timeout to 60min
+- fix: session monitor fallback timeout to 10min
+- fix: session monitor done threshold to 5min (hook is primary detection)
+- fix: add logging to agent-context.json write for debugging
+- fix: hook uses correct Claude Code schema + date-stamped backup
+- fix: hook reads agent context from file instead of env vars
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.11...v0.5.12
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.14...v0.5.15

package/components/WorkspaceView.tsx

@@ -2212,6 +2212,9 @@ interface AgentNodeData {
   onShowInbox: () => void;
   onOpenTerminal: () => void;
   onSwitchSession: () => void;
+  onMarkIdle?: () => void;
+  onMarkDone?: (notify: boolean) => void;
+  onMarkFailed?: (notify: boolean) => void;
   inboxPending?: number;
   inboxFailed?: number;
   [key: string]: unknown;
@@ -2325,8 +2328,14 @@ function AgentFlowNode({ data }: NodeProps<Node<AgentNodeData>>) {
       {/* Actions */}
       <div className="flex items-center gap-1 px-2 py-1.5" style={{ borderTop: `1px solid ${c.border}15` }}>
         {taskStatus === 'running' && (
-          <button onPointerDown={e => e.stopPropagation()} onClick={e => { e.stopPropagation(); onStop(); }}
-            className="text-[9px] px-1.5 py-0.5 rounded bg-red-600/20 text-red-400 hover:bg-red-600/30">■ Stop</button>
+          <>
+            <button onPointerDown={e => e.stopPropagation()} onClick={e => { e.stopPropagation(); data.onMarkIdle?.(); }}
+              className="text-[9px] px-1 py-0.5 rounded bg-gray-600/20 text-gray-400 hover:bg-gray-600/30" title="Silent stop — no notifications">■</button>
+            <button onPointerDown={e => e.stopPropagation()} onClick={e => { e.stopPropagation(); data.onMarkDone?.(true); }}
+              className="text-[9px] px-1 py-0.5 rounded bg-green-600/20 text-green-400 hover:bg-green-600/30" title="Mark done + notify">✓</button>
+            <button onPointerDown={e => e.stopPropagation()} onClick={e => { e.stopPropagation(); data.onMarkFailed?.(true); }}
+              className="text-[9px] px-1 py-0.5 rounded bg-red-600/20 text-red-400 hover:bg-red-600/30" title="Mark failed + notify">✕</button>
+          </>
         )}
         {/* Message button — send instructions to agent */}
         {smithStatus === 'active' && taskStatus !== 'running' && (
@@ -2469,6 +2478,9 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
             },
             onPause: () => wsApi(workspaceId!, 'pause', { agentId: agent.id }),
             onStop: () => wsApi(workspaceId!, 'stop', { agentId: agent.id }),
+            onMarkIdle: () => wsApi(workspaceId!, 'mark_done', { agentId: agent.id, notify: false }),
+            onMarkDone: (notify: boolean) => wsApi(workspaceId!, 'mark_done', { agentId: agent.id, notify }),
+            onMarkFailed: (notify: boolean) => wsApi(workspaceId!, 'mark_failed', { agentId: agent.id, notify }),
             onRetry: () => wsApi(workspaceId!, 'retry', { agentId: agent.id }),
             onEdit: () => setModal({ mode: 'edit', initial: agent, editId: agent.id }),
             onRemove: () => {
@@ -2517,43 +2529,20 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
                 },
               };
 
-              // If tmux session exists → attach (primary or non-primary)
-              if (existingTmux) {
-                wsApi(workspaceId, 'open_terminal', { agentId: agent.id });
-                setFloatingTerminals(prev => [...prev, {
-                  agentId: agent.id, label: agent.label, icon: agent.icon,
-                  cliId: agent.agentId || 'claude', ...launchInfo, workDir,
-                  tmuxSession: existingTmux, sessionName: sessName,
-                  isPrimary: agent.primary, skipPermissions: agent.skipPermissions !== false, persistentSession: agent.persistentSession, boundSessionId: agent.boundSessionId, initialPos,
-                }]);
-                return;
-              }
-
-              // Primary without session → open directly (no dialog)
-              if (agent.primary) {
-                const res = await wsApi(workspaceId, 'open_terminal', { agentId: agent.id }).catch(() => ({})) as any;
-                setFloatingTerminals(prev => [...prev, {
-                  agentId: agent.id, label: agent.label, icon: agent.icon,
-                  cliId: agent.agentId || 'claude', ...launchInfo, workDir,
-                  tmuxSession: res?.tmuxSession || sessName, sessionName: sessName,
-                  isPrimary: true, skipPermissions: agent.skipPermissions !== false, persistentSession: agent.persistentSession, boundSessionId: agent.boundSessionId, initialPos,
-                }]);
-                return;
-              }
-
-              // Non-primary: has boundSessionId → use it directly; no bound → show dialog
-              if (agent.boundSessionId) {
+              // All paths: let daemon create/ensure session, then attach
+              if (existingTmux || agent.primary || agent.persistentSession || agent.boundSessionId) {
+                // Daemon creates session via ensurePersistentSession (launch script, no truncation)
                 const res = await wsApi(workspaceId, 'open_terminal', { agentId: agent.id }).catch(() => ({})) as any;
+                const tmux = existingTmux || res?.tmuxSession || sessName;
                 setFloatingTerminals(prev => [...prev, {
                   agentId: agent.id, label: agent.label, icon: agent.icon,
-                  cliId: agent.agentId || 'claude', ...launchInfo, workDir,
-                  tmuxSession: res?.tmuxSession || sessName, sessionName: sessName,
-                  resumeSessionId: agent.boundSessionId,
-                  isPrimary: false, skipPermissions: agent.skipPermissions !== false, persistentSession: agent.persistentSession, boundSessionId: agent.boundSessionId, initialPos,
+                  cliId: agent.agentId || 'claude', workDir,
+                  tmuxSession: tmux, sessionName: sessName,
+                  isPrimary: agent.primary, skipPermissions: agent.skipPermissions !== false, persistentSession: agent.persistentSession, boundSessionId: agent.boundSessionId, initialPos,
                 }]);
                 return;
               }
-              // No bound session → show launch dialog (New / Resume / Select)
+              // No persistent session, no bound session → show launch dialog
               setTermLaunchDialog({ agent, sessName, workDir, sessions: [], supportsSession: resolveRes?.supportsSession ?? true, initialPos });
             },
             onSwitchSession: async () => {
@@ -2934,28 +2923,19 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
           onLaunch={async (resumeMode, sessionId) => {
             const { agent, sessName, workDir } = termLaunchDialog;
             setTermLaunchDialog(null);
-            const res = await wsApi(workspaceId, 'open_terminal', { agentId: agent.id });
-            if (res.ok) {
-              // Save selected session as boundSessionId if user chose a specific one
-              if (sessionId) {
-                wsApi(workspaceId, 'update', { agentId: agent.id, config: { ...agent, boundSessionId: sessionId } }).catch(() => {});
-              }
-              setFloatingTerminals(prev => [...prev, {
-                agentId: agent.id, label: agent.label, icon: agent.icon,
-                cliId: agent.agentId || 'claude',
-                cliCmd: res.cliCmd || 'claude',
-                cliType: res.cliType || 'claude-code',
-                workDir,
-                sessionName: sessName, resumeMode, resumeSessionId: sessionId, isPrimary: false, skipPermissions: agent.skipPermissions !== false, persistentSession: agent.persistentSession, boundSessionId: sessionId || agent.boundSessionId, initialPos: termLaunchDialog.initialPos,
-                profileEnv: {
-                  ...(res.env || {}),
-                  ...(res.model ? { CLAUDE_MODEL: res.model } : {}),
-                  FORGE_AGENT_ID: agent.id,
-                  FORGE_WORKSPACE_ID: workspaceId,
-                  FORGE_PORT: String(window.location.port || 8403),
-                },
-              }]);
+            // Save selected session as boundSessionId
+            if (sessionId) {
+              await wsApi(workspaceId, 'update', { agentId: agent.id, config: { ...agent, boundSessionId: sessionId } }).catch(() => {});
             }
+            // Daemon creates session (launch script), then attach
+            const res = await wsApi(workspaceId, 'open_terminal', { agentId: agent.id }).catch(() => ({})) as any;
+            const tmux = res?.tmuxSession || sessName;
+            setFloatingTerminals(prev => [...prev, {
+              agentId: agent.id, label: agent.label, icon: agent.icon,
+              cliId: agent.agentId || 'claude', workDir,
+              tmuxSession: tmux, sessionName: sessName,
+              isPrimary: false, skipPermissions: agent.skipPermissions !== false, persistentSession: agent.persistentSession, boundSessionId: sessionId || agent.boundSessionId, initialPos: termLaunchDialog.initialPos,
+            }]);
           }}
           onCancel={() => setTermLaunchDialog(null)}
         />

package/lib/workspace/orchestrator.ts

@@ -1103,6 +1103,31 @@ export class WorkspaceOrchestrator extends EventEmitter {
     console.log('[workspace] Daemon stopped');
   }
 
+  // ─── Hook-based completion ─────────────────────────────
+
+  /** Called by Claude Code Stop hook via HTTP — agent finished a turn */
+  handleHookDone(agentId: string): void {
+    const entry = this.agents.get(agentId);
+    if (!entry) return;
+    if (!this.daemonActive) return;
+
+    // Only transition running → done (ignore if already idle/done)
+    if (entry.state.taskStatus !== 'running') {
+      console.log(`[hook] ${entry.config.label}: Stop hook fired but task=${entry.state.taskStatus}, ignoring`);
+      return;
+    }
+
+    console.log(`[hook] ${entry.config.label}: Stop hook → done`);
+    entry.state.taskStatus = 'done';
+    entry.state.completedAt = Date.now();
+    this.emit('event', { type: 'task_status', agentId, taskStatus: 'done' } as any);
+    this.emit('event', { type: 'log', agentId, entry: { type: 'system', subtype: 'hook_done', content: 'Claude Code Stop hook: turn completed', timestamp: new Date().toISOString() } } as any);
+    this.handleAgentDone(agentId, entry, 'Stop hook');
+    this.sessionMonitor?.resetState(agentId);
+    this.saveNow();
+    this.emitAgentsChanged();
+  }
+
   // ─── Session File Monitor ──────────────────────────────
 
   private async startSessionMonitors(): Promise<void> {
@@ -1353,16 +1378,20 @@ export class WorkspaceOrchestrator extends EventEmitter {
         }
       }
 
-      // Case 4: Failed → notify sender so they know
-      if (msg.status === 'failed' && !this.forgeActedMessages.has(`failed-${msg.id}`)) {
-        const senderEntry = this.agents.get(msg.from);
-        const targetLabel = this.agents.get(msg.to)?.config.label || msg.to;
-        if (senderEntry && msg.from !== '_forge' && msg.from !== '_system') {
-          this.bus.send('_forge', msg.from, 'notify', {
-            action: 'update_notify',
-            content: `Your message to ${targetLabel} has failed. You may want to retry or take a different approach.`,
-          });
-          console.log(`[forge-agent] Notified ${senderEntry.config.label} that message to ${targetLabel} failed`);
+      // Case 4: Failed → notify sender (once per sender→target pair)
+      if (msg.status === 'failed') {
+        const failKey = `failed-${msg.from}->${msg.to}`;
+        if (!this.forgeActedMessages.has(failKey)) {
+          const senderEntry = this.agents.get(msg.from);
+          const targetLabel = this.agents.get(msg.to)?.config.label || msg.to;
+          if (senderEntry && msg.from !== '_forge' && msg.from !== '_system') {
+            this.bus.send('_forge', msg.from, 'notify', {
+              action: 'update_notify',
+              content: `Your message to ${targetLabel} has failed. You may want to retry or take a different approach.`,
+            });
+            console.log(`[forge-agent] Notified ${senderEntry.config.label} that message to ${targetLabel} failed (once)`);
+          }
+          this.forgeActedMessages.add(failKey);
         }
         this.forgeActedMessages.add(`failed-${msg.id}`);
       }
@@ -1498,9 +1527,63 @@ export class WorkspaceOrchestrator extends EventEmitter {
   }
 
   /** Stop a running agent */
+  /** Mark agent task as done (user manually confirms completion) */
+  markAgentDone(agentId: string, notify: boolean): void {
+    const entry = this.agents.get(agentId);
+    if (!entry) return;
+
+    // Mark running inbox messages as done
+    const runningMsgs = this.bus.getLog().filter(m => m.to === agentId && m.status === 'running' && m.type !== 'ack');
+    for (const m of runningMsgs) {
+      m.status = 'done' as any;
+      this.emit('event', { type: 'bus_message_status', messageId: m.id, status: 'done' } as any);
+    }
+
+    entry.state.taskStatus = notify ? 'done' : 'idle';
+    entry.state.completedAt = Date.now();
+    this.emit('event', { type: 'task_status', agentId, taskStatus: entry.state.taskStatus } as any);
+    if (notify) {
+      this.handleAgentDone(agentId, entry, 'Manually marked done');
+    }
+    this.sessionMonitor?.resetState(agentId);
+    this.saveNow();
+    this.emitAgentsChanged();
+    console.log(`[workspace] ${entry.config.label}: manually marked ${notify ? 'done' : 'idle'} (${runningMsgs.length} messages completed)`);
+  }
+
+  /** Mark agent task as failed (user manually marks failure) */
+  markAgentFailed(agentId: string, notify: boolean): void {
+    const entry = this.agents.get(agentId);
+    if (!entry) return;
+
+    // Mark running inbox messages as failed
+    const runningMsgs = this.bus.getLog().filter(m => m.to === agentId && m.status === 'running' && m.type !== 'ack');
+    for (const m of runningMsgs) {
+      m.status = 'failed' as any;
+      this.emit('event', { type: 'bus_message_status', messageId: m.id, status: 'failed' } as any);
+    }
+
+    entry.state.taskStatus = 'failed';
+    entry.state.error = 'Manually marked as failed';
+    this.emit('event', { type: 'task_status', agentId, taskStatus: 'failed' } as any);
+    if (notify) {
+      this.bus.notifyTaskComplete(agentId, [], 'Task failed');
+    }
+    this.sessionMonitor?.resetState(agentId);
+    this.saveNow();
+    this.emitAgentsChanged();
+    console.log(`[workspace] ${entry.config.label}: manually marked failed (${runningMsgs.length} messages failed)`);
+  }
+
+  /** Legacy stop — for headless mode */
   stopAgent(agentId: string): void {
     const entry = this.agents.get(agentId);
-    entry?.worker?.stop();
+    if (!entry) return;
+    if (entry.config.persistentSession) {
+      this.markAgentDone(agentId, false);
+    } else {
+      entry.worker?.stop();
+    }
   }
 
   /** Retry a failed agent from its last checkpoint */
@@ -1963,12 +2046,38 @@ export class WorkspaceOrchestrator extends EventEmitter {
       }
     }
 
+    // Write agent context file for hooks to read (workDir/.forge/agent-context.json)
+    try {
+      const forgeDir = join(workDir, '.forge');
+      const { mkdirSync: mkdirS } = require('node:fs');
+      mkdirS(forgeDir, { recursive: true });
+      const ctxPath = join(forgeDir, 'agent-context.json');
+      writeFileSync(ctxPath, JSON.stringify({
+        workspaceId: this.workspaceId,
+        agentId: config.id,
+        agentLabel: config.label,
+        forgePort: Number(process.env.PORT) || 8403,
+      }, null, 2));
+      console.log(`[daemon] ${config.label}: wrote agent-context.json to ${ctxPath}`);
+    } catch (err: any) {
+      console.error(`[daemon] ${config.label}: failed to write agent-context.json: ${err.message}`);
+    }
+
     // Check if tmux session already exists
     let sessionAlreadyExists = false;
     try {
       execSync(`tmux has-session -t "${sessionName}" 2>/dev/null`, { timeout: 3000 });
       sessionAlreadyExists = true;
       console.log(`[daemon] ${config.label}: persistent session already exists (${sessionName})`);
+      // Ensure FORGE env vars are set in the tmux session environment
+      // (for hooks that read them — set-environment makes them available to new processes in this session)
+      try {
+        execSync(`tmux set-environment -t "${sessionName}" FORGE_WORKSPACE_ID "${this.workspaceId}"`, { timeout: 3000 });
+        execSync(`tmux set-environment -t "${sessionName}" FORGE_AGENT_ID "${config.id}"`, { timeout: 3000 });
+        execSync(`tmux set-environment -t "${sessionName}" FORGE_PORT "${Number(process.env.PORT) || 8403}"`, { timeout: 3000 });
+      } catch {}
+      // Note: set-environment affects new processes in this tmux session.
+      // Claude Code hooks run as child processes of the shell, which inherits tmux environment.
     } catch {
       // Create new tmux session and start the CLI agent
       try {
@@ -2023,27 +2132,24 @@ export class WorkspaceOrchestrator extends EventEmitter {
 
         execSync(`tmux new-session -d -s "${sessionName}" -c "${workDir}"`, { timeout: 5000 });
 
-        // Reset profile env vars (unset any leftover from previous agent) then set new ones
-        const profileVarsToReset = ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_SMALL_FAST_MODEL', 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC', 'DISABLE_TELEMETRY', 'DISABLE_ERROR_REPORTING', 'DISABLE_AUTOUPDATER', 'DISABLE_NON_ESSENTIAL_MODEL_CALLS', 'CLAUDE_MODEL'];
-        const unsetCmd = profileVarsToReset.map(v => `unset ${v}`).join(' && ');
-        execSync(`tmux send-keys -t "${sessionName}" '${unsetCmd}' Enter`, { timeout: 5000 });
+        // Build launch script to avoid tmux send-keys truncation
+        const scriptLines: string[] = ['#!/bin/bash', `cd "${workDir}"`];
+
+        // Unset old profile vars
+        scriptLines.push('unset ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL ANTHROPIC_SMALL_FAST_MODEL CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC DISABLE_TELEMETRY DISABLE_ERROR_REPORTING DISABLE_AUTOUPDATER DISABLE_NON_ESSENTIAL_MODEL_CALLS CLAUDE_MODEL');
 
-        // Set FORGE env vars (short, separate command)
-        execSync(`tmux send-keys -t "${sessionName}" 'export FORGE_WORKSPACE_ID="${this.workspaceId}" FORGE_AGENT_ID="${config.id}" FORGE_PORT="${Number(process.env.PORT) || 8403}"' Enter`, { timeout: 5000 });
+        // Set FORGE env vars
+        scriptLines.push(`export FORGE_WORKSPACE_ID="${this.workspaceId}" FORGE_AGENT_ID="${config.id}" FORGE_PORT="${Number(process.env.PORT) || 8403}"`);
 
-        // Set profile env vars if any (separate command to avoid truncation)
+        // Set profile env vars
         if (envExports) {
-          execSync(`tmux send-keys -t "${sessionName}" '${envExports.replace(/ && $/, '')}' Enter`, { timeout: 5000 });
+          scriptLines.push(envExports.replace(/ && /g, '\n').replace(/\n$/, ''));
         }
 
-        // Build CLI start command
-        const parts: string[] = [];
+        // Build CLI command
         let cmd = cliCmd;
-
-        // Session resume: use bound session ID (primary from project-sessions, others from config)
         if (supportsSession) {
           let sessionId: string | undefined;
-
           if (config.primary) {
             try {
               const { getFixedSession } = await import('../project-sessions') as any;
@@ -2052,7 +2158,6 @@ export class WorkspaceOrchestrator extends EventEmitter {
           } else {
             sessionId = config.boundSessionId;
           }
-
           if (sessionId) {
             const sessionFile = join(this.getCliSessionDir(config.workDir), `${sessionId}.jsonl`);
             if (existsSync(sessionFile)) {
@@ -2061,15 +2166,16 @@ export class WorkspaceOrchestrator extends EventEmitter {
               console.log(`[daemon] ${config.label}: bound session ${sessionId} missing, starting fresh`);
             }
           }
-          // No bound session → start fresh (no -c, avoids "No conversation found")
         }
         if (modelFlag) cmd += modelFlag;
         if (config.skipPermissions !== false && skipPermissionsFlag) cmd += ` ${skipPermissionsFlag}`;
         if (mcpConfigFlag) cmd += mcpConfigFlag;
-        parts.push(cmd);
+        scriptLines.push(`exec ${cmd}`);
 
-        const startCmd = parts.join(' && ');
-        execSync(`tmux send-keys -t "${sessionName}" '${startCmd}' Enter`, { timeout: 5000 });
+        // Write script and execute in tmux
+        const scriptPath = `/tmp/forge-launch-${config.id.replace(/[^a-z0-9-]/g, '')}.sh`;
+        writeFileSync(scriptPath, scriptLines.join('\n'), { mode: 0o755 });
+        execSync(`tmux send-keys -t "${sessionName}" 'bash ${scriptPath}' Enter`, { timeout: 5000 });
 
         console.log(`[daemon] ${config.label}: persistent session created (${sessionName}) [${cliType}: ${cliCmd}]`);
 

package/lib/workspace/session-monitor.ts

@@ -27,9 +27,9 @@ export interface SessionMonitorEvent {
   detail?: string; // e.g., result summary
 }
 
-const POLL_INTERVAL = 1000;    // check every 1s (need to catch short executions)
-const IDLE_THRESHOLD = 10000;  // 10s of no file change → check for done
-const STABLE_THRESHOLD = 20000; // 20s of no change → force done
+const POLL_INTERVAL = 3000;      // check every 3s
+const IDLE_THRESHOLD = 3540000;  // 59min of no file change → check for result entry
+const STABLE_THRESHOLD = 3600000; // 60min of no change → force done (fallback if hook missed)
 
 export class SessionFileMonitor extends EventEmitter {
   private timers = new Map<string, NodeJS.Timeout>();
@@ -86,6 +86,20 @@ export class SessionFileMonitor extends EventEmitter {
     return this.currentState.get(agentId) || 'idle';
   }
 
+  /**
+   * Reset monitor state to idle and pause detection briefly.
+   * Call when orchestrator manually changes taskStatus (button/hook).
+   * Suppresses detection for 10s to avoid immediately flipping back.
+   */
+  private suppressUntil = new Map<string, number>();
+
+  resetState(agentId: string): void {
+    this.currentState.set(agentId, 'idle');
+    this.lastStableTime.set(agentId, Date.now());
+    // Suppress state changes for 10s after manual reset
+    this.suppressUntil.set(agentId, Date.now() + 10_000);
+  }
+
   /**
    * Resolve session file path for a project + session ID.
    */
@@ -202,6 +216,12 @@ export class SessionFileMonitor extends EventEmitter {
     const prev = this.currentState.get(agentId);
     if (prev === state) return;
 
+    // Suppress state changes if recently reset by orchestrator
+    const suppressed = this.suppressUntil.get(agentId);
+    if (suppressed && Date.now() < suppressed) {
+      return;
+    }
+
     this.currentState.set(agentId, state);
     const event: SessionMonitorEvent = { agentId, state, sessionFile: filePath, detail };
     this.emit('stateChange', event);

package/lib/workspace/skill-installer.ts

@@ -63,6 +63,9 @@ export function installForgeSkills(
     ensureForgePermissions(projectClaudeDir);
   }
 
+  // Install Stop hook in user-level settings (for agent completion detection)
+  installForgeStopHook(forgePort);
+
   return { installed };
 }
 
@@ -162,6 +165,90 @@ export function applyProfileToProject(
   }
 }
 
+const FORGE_HOOK_MARKER = '# forge-stop-hook';
+
+/**
+ * Install a Stop hook in user-level ~/.claude/settings.json.
+ * When Claude Code finishes a turn, the hook notifies Forge via HTTP.
+ * Preserves existing user hooks. Creates backup before modifying.
+ */
+function installForgeStopHook(forgePort: number): void {
+  const settingsFile = join(homedir(), '.claude', 'settings.json');
+  const now = new Date();
+  const dateStr = `${now.getFullYear()}${String(now.getMonth()+1).padStart(2,'0')}${String(now.getDate()).padStart(2,'0')}-${String(now.getHours()).padStart(2,'0')}${String(now.getMinutes()).padStart(2,'0')}`;
+  const backupFile = join(homedir(), '.claude', `settings.json.forge-backup-${dateStr}`);
+  const daemonPort = forgePort + 2; // 8403 → 8405
+
+  // Hook reads agent context from .forge/agent-context.json in the project dir.
+  // This file is written by ensurePersistentSession for each agent's workDir.
+  // Falls back to env vars if file doesn't exist.
+  const hookCommand = `${FORGE_HOOK_MARKER}\nCTX_FILE="$(pwd)/.forge/agent-context.json"; if [ -f "$CTX_FILE" ]; then WS_ID=$(python3 -c "import json;print(json.load(open('$CTX_FILE')).get('workspaceId',''))" 2>/dev/null); AG_ID=$(python3 -c "import json;print(json.load(open('$CTX_FILE')).get('agentId',''))" 2>/dev/null); elif [ -n "$FORGE_WORKSPACE_ID" ]; then WS_ID="$FORGE_WORKSPACE_ID"; AG_ID="$FORGE_AGENT_ID"; fi; if [ -n "$WS_ID" ] && [ -n "$AG_ID" ]; then curl -s -X POST "http://localhost:${daemonPort}/workspace/$WS_ID/agents" -H "Content-Type: application/json" -d "{\\"action\\":\\"agent_done\\",\\"agentId\\":\\"$AG_ID\\"}" > /dev/null 2>&1 & fi`;
+
+  try {
+    let settings: any = {};
+    if (existsSync(settingsFile)) {
+      const raw = readFileSync(settingsFile, 'utf-8');
+      settings = JSON.parse(raw);
+
+      // Check if hook already installed
+      // Remove old forge hook if present (will re-add with latest version)
+      if (settings.hooks?.Stop) {
+        settings.hooks.Stop = settings.hooks.Stop.filter((h: any) => {
+          if (h.command?.includes(FORGE_HOOK_MARKER) || h.command?.includes('agent_done')) return false;
+          if (h.hooks?.some((sub: any) => sub.command?.includes(FORGE_HOOK_MARKER) || sub.command?.includes('agent_done'))) return false;
+          return true;
+        });
+      }
+
+      // Backup before modifying
+      writeFileSync(backupFile, raw, 'utf-8');
+    }
+
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.Stop) settings.hooks.Stop = [];
+
+    // Add forge hook (Claude Code hooks schema: matcher + hooks array)
+    settings.hooks.Stop.push({
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: hookCommand,
+        timeout: 5000,
+      }],
+    });
+
+    mkdirSync(join(homedir(), '.claude'), { recursive: true });
+    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    console.log('[skills] Installed Forge Stop hook in ~/.claude/settings.json');
+  } catch (err: any) {
+    console.error('[skills] Failed to install Stop hook:', err.message);
+  }
+}
+
+/**
+ * Remove Forge Stop hook from user-level settings (cleanup).
+ */
+export function removeForgeStopHook(): void {
+  const settingsFile = join(homedir(), '.claude', 'settings.json');
+  try {
+    if (!existsSync(settingsFile)) return;
+    const settings = JSON.parse(readFileSync(settingsFile, 'utf-8'));
+    if (!settings.hooks?.Stop) return;
+
+    settings.hooks.Stop = settings.hooks.Stop.filter((h: any) => {
+      // Remove entries matching either old flat format or new nested format
+      if (h.command?.includes(FORGE_HOOK_MARKER) || h.command?.includes('agent_done')) return false;
+      if (h.hooks?.some((sub: any) => sub.command?.includes(FORGE_HOOK_MARKER) || sub.command?.includes('agent_done'))) return false;
+      return true;
+    });
+    if (settings.hooks.Stop.length === 0) delete settings.hooks.Stop;
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    console.log('[skills] Removed Forge Stop hook from ~/.claude/settings.json');
+  } catch {}
+}
+
 /**
  * Check if forge skills are already installed for this agent.
  */

package/lib/workspace-standalone.ts

@@ -190,6 +190,12 @@ async function handleAgentsPost(id: string, body: any, res: ServerResponse): Pro
           return jsonError(res, err.message);
         }
       }
+      case 'agent_done': {
+        // Called by Claude Code Stop hook — agent finished a turn
+        if (!agentId) return jsonError(res, 'agentId required');
+        orch.handleHookDone(agentId);
+        return json(res, { ok: true });
+      }
       case 'run': {
         if (!agentId) return jsonError(res, 'agentId required');
         if (!orch.isDaemonActive()) return jsonError(res, 'Start daemon first before running agents');
@@ -226,6 +232,16 @@ async function handleAgentsPost(id: string, body: any, res: ServerResponse): Pro
         orch.stopAgent(agentId);
         return json(res, { ok: true });
       }
+      case 'mark_done': {
+        if (!agentId) return jsonError(res, 'agentId required');
+        orch.markAgentDone(agentId, body.notify !== false);
+        return json(res, { ok: true });
+      }
+      case 'mark_failed': {
+        if (!agentId) return jsonError(res, 'agentId required');
+        orch.markAgentFailed(agentId, body.notify !== false);
+        return json(res, { ok: true });
+      }
       case 'retry': {
         if (!agentId) return jsonError(res, 'agentId required');
         if (!orch.isDaemonActive()) return jsonError(res, 'Start daemon first before retrying agents');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.5.12",
+  "version": "0.5.15",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {