feat(notify): pass STATUS, FAIL_REASON, BODY as env vars to notify hook

- Add NotifyContext type with status, failReason, body fields
- buildNotifyEnv injects STATUS, FAIL_REASON, BODY when provided
- maybeNotifyTaskCompletion extracts last assistant message as BODY
- launchNotifyScript accepts optional context parameter
- Add unit tests for new context env var injection
- Update docs with env variable table and iTerm2/macOS notify examples

Author: Lellansin

docs/configuration.md

@@ -67,12 +67,45 @@ Deep Code 使用 `settings.json` 设置文件进行持久化配置，支持两
 
 设置一个 Shell 脚本的完整路径。当 AI 助手完成一轮任务后，会自动执行该脚本，可用于发送通知（如 Slack 消息）。
 
+通知脚本执行时，会通过环境变量注入以下上下文信息：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `DURATION` | 会话耗时，单位秒（整数） |
+| `STATUS` | 会话状态：`"completed"` 或 `"failed"` |
+| `FAIL_REASON` | 失败原因（仅失败时设置） |
+| `BODY` | 最后一条 AI 助手回复的文本内容 |
+
 ```json
 {
   "notify": "/path/to/slack-notify.sh"
 }
 ```
 
+**iTerm2 终端通知示例**：
+
+如果你的终端是 iTerm2，可以直接通过 OSC 9 转义序列弹出通知，无需额外脚本。创建以下脚本（如 `~/.deepcode/notify.sh`）：
+
+```bash
+#!/bin/bash
+# iTerm2 OSC 9 通知
+echo -e "\x1b]9;DeepCode: task ${STATUS:-completed} (${DURATION}s)\x07"
+```
+
+```json
+{
+  "notify": "/Users/you/.deepcode/notify.sh"
+}
+```
+
+**macOS 系统通知示例**：
+
+```bash
+#!/bin/bash
+# macOS 系统通知
+osascript -e "display notification \"任务已${STATUS:-完成}，耗时 ${DURATION}s\" with title \"DeepCode\""
+```
+
 #### `webSearchTool` — 自定义联网搜索
 
 Deep Code 内置免费可用的 Web Search 工具。如果需要自定义搜索逻辑，可将 `webSearchTool` 设为一个可执行脚本的完整路径：

docs/configuration_en.md

@@ -67,12 +67,45 @@ When thinking mode is enabled, controls the depth of the model’s reasoning:
 
 Set a full path to a shell script. When the AI assistant finishes a round of tasks, the script is executed automatically, which can be used to send notifications (e.g., a Slack message).
 
+The following context is injected as environment variables when the notify script runs:
+
+| Variable | Description |
+|----------|-------------|
+| `DURATION` | Session duration in seconds (integer) |
+| `STATUS` | Session status: `"completed"` or `"failed"` |
+| `FAIL_REASON` | Failure reason (only set on failure) |
+| `BODY` | The text content of the last AI assistant reply |
+
 ```json
 {
   "notify": "/path/to/slack-notify.sh"
 }
 ```
 
+**iTerm2 Notification Example**:
+
+On iTerm2 you can use the OSC 9 escape sequence for native notifications. Create a script (e.g., `~/.deepcode/notify.sh`):
+
+```bash
+#!/bin/bash
+# iTerm2 OSC 9 notification
+echo -e "\x1b]9;DeepCode: task ${STATUS:-completed} (${DURATION}s)\x07"
+```
+
+```json
+{
+  "notify": "/Users/you/.deepcode/notify.sh"
+}
+```
+
+**macOS System Notification Example**:
+
+```bash
+#!/bin/bash
+# macOS system notification
+osascript -e "display notification \"Task ${STATUS:-completed}, took ${DURATION}s\" with title \"DeepCode\""
+```
+
 #### `webSearchTool` — Custom Web Search
 
 Deep Code has a built-in, free-to-use Web Search tool. If you need custom search logic, set `webSearchTool` to the full path of an executable script:

src/common/notify.ts

@@ -16,19 +16,40 @@ export function formatDurationSeconds(durationMs: number): string {
   return String(Math.floor(safeMs / 1000));
 }
 
-export function buildNotifyEnv(durationMs: number, baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  return {
+export type NotifyContext = {
+  status?: string;
+  failReason?: string;
+  body?: string;
+};
+
+export function buildNotifyEnv(
+  durationMs: number,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+  context: NotifyContext = {}
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
     ...baseEnv,
     DURATION: formatDurationSeconds(durationMs),
   };
+  if (context.status) {
+    env.STATUS = context.status;
+  }
+  if (context.failReason) {
+    env.FAIL_REASON = context.failReason;
+  }
+  if (context.body) {
+    env.BODY = context.body;
+  }
+  return env;
 }
 
 export function launchNotifyScript(
   notifyPath: string | undefined,
   durationMs: number,
   workingDirectory?: string,
   spawnProcess: NotifySpawn = spawn as unknown as NotifySpawn,
-  configuredEnv: Record<string, string> = {}
+  configuredEnv: Record<string, string> = {},
+  context: NotifyContext = {}
 ): void {
   const commandPath = notifyPath?.trim();
   if (!commandPath) {
@@ -38,7 +59,7 @@ export function launchNotifyScript(
   const options = {
     cwd: workingDirectory,
     detached: process.platform !== "win32",
-    env: buildNotifyEnv(durationMs, { ...process.env, ...configuredEnv }),
+    env: buildNotifyEnv(durationMs, { ...process.env, ...configuredEnv }, context),
     stdio: "ignore" as const,
   };
 

src/session.ts

@@ -2124,7 +2124,22 @@ ${skillMd}
       return;
     }
 
-    launchNotifyScript(notifyCommand, Date.now() - startedAt, this.projectRoot, undefined, configuredEnv);
+    // Find the last assistant message body for the BODY env variable.
+    let body: string | undefined;
+    const messages = this.listSessionMessages(sessionId);
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg && msg.role === "assistant" && msg.content) {
+        body = msg.content;
+        break;
+      }
+    }
+
+    launchNotifyScript(notifyCommand, Date.now() - startedAt, this.projectRoot, undefined, configuredEnv, {
+      status: session.status,
+      failReason: session.failReason ?? undefined,
+      body,
+    });
   }
 
   private addSessionProcess(sessionId: string, processId: string | number, command: string): void {

src/tests/settings-and-notify.test.ts

@@ -1,6 +1,12 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { buildNotifyEnv, formatDurationSeconds, launchNotifyScript, type NotifySpawn } from "../common/notify";
+import {
+  buildNotifyEnv,
+  formatDurationSeconds,
+  launchNotifyScript,
+  type NotifyContext,
+  type NotifySpawn,
+} from "../common/notify";
 import { applyModelConfigSelection, resolveSettings, resolveSettingsSources } from "../settings";
 
 const TEST_PROCESS_ENV = {};
@@ -358,14 +364,38 @@ test("formatDurationSeconds preserves sub-second precision and trims trailing ze
   assert.equal(formatDurationSeconds(4000), "4");
 });
 
-test("buildNotifyEnv injects DURATION", () => {
+test("buildNotifyEnv injects DURATION without context", () => {
   const env = buildNotifyEnv(2750, { HOME: "/tmp/home" });
   assert.equal(env.HOME, "/tmp/home");
   assert.equal(env.DURATION, "2");
+  assert.equal(env.STATUS, undefined);
+  assert.equal(env.FAIL_REASON, undefined);
+  assert.equal(env.BODY, undefined);
+});
+
+test("buildNotifyEnv injects STATUS, FAIL_REASON, and BODY from context", () => {
+  const context: NotifyContext = {
+    status: "failed",
+    failReason: "API key not found",
+    body: "Hello, this is the last assistant message.",
+  };
+  const env = buildNotifyEnv(5000, { HOME: "/tmp/home" }, context);
+  assert.equal(env.HOME, "/tmp/home");
+  assert.equal(env.DURATION, "5");
+  assert.equal(env.STATUS, "failed");
+  assert.equal(env.FAIL_REASON, "API key not found");
+  assert.equal(env.BODY, "Hello, this is the last assistant message.");
+});
+
+test("buildNotifyEnv omits optional context fields when not provided", () => {
+  const env = buildNotifyEnv(1000, { HOME: "/tmp/home" }, { status: "completed" });
+  assert.equal(env.STATUS, "completed");
+  assert.equal(env.FAIL_REASON, undefined);
+  assert.equal(env.BODY, undefined);
 });
 
 test(
-  "launchNotifyScript passes DURATION and falls back to /bin/sh for non-executable scripts",
+  "launchNotifyScript passes DURATION, context vars, and falls back to /bin/sh for non-executable scripts",
   { skip: process.platform === "win32" },
   () => {
     const calls: Array<{
@@ -390,17 +420,27 @@ test(
       };
     };
 
-    launchNotifyScript("/tmp/notify.sh", 2750, "/tmp/project", spawnProcess, { WEBHOOK: "configured" });
+    const context: NotifyContext = {
+      status: "completed",
+      body: "Task finished successfully.",
+    };
+
+    launchNotifyScript("/tmp/notify.sh", 2750, "/tmp/project", spawnProcess, { WEBHOOK: "configured" }, context);
 
     assert.equal(calls.length, 2);
     assert.equal(calls[0]?.command, "/tmp/notify.sh");
     assert.deepEqual(calls[0]?.args, []);
     assert.equal(calls[0]?.options.cwd, "/tmp/project");
     assert.equal(calls[0]?.options.env?.DURATION, "2");
     assert.equal(calls[0]?.options.env?.WEBHOOK, "configured");
+    assert.equal(calls[0]?.options.env?.STATUS, "completed");
+    assert.equal(calls[0]?.options.env?.FAIL_REASON, undefined);
+    assert.equal(calls[0]?.options.env?.BODY, "Task finished successfully.");
     assert.equal(calls[1]?.command, "/bin/sh");
     assert.deepEqual(calls[1]?.args, ["/tmp/notify.sh"]);
     assert.equal(calls[1]?.options.cwd, "/tmp/project");
     assert.equal(calls[1]?.options.env?.DURATION, "2");
+    assert.equal(calls[1]?.options.env?.STATUS, "completed");
+    assert.equal(calls[1]?.options.env?.BODY, "Task finished successfully.");
   }
 );