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,46 @@ Deep Code 使用 `settings.json` 设置文件进行持久化配置，支持两
 
 设置一个 Shell 脚本的完整路径。当 AI 助手完成一轮任务后，会自动执行该脚本，可用于发送通知（如 Slack 消息）。
 
+通知脚本执行时，会通过环境变量注入以下上下文信息：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `DURATION` | 会话耗时，单位秒（整数） |
+| `STATUS` | 会话状态：`"completed"` 或 `"failed"` |
+| `FAIL_REASON` | 失败原因（仅失败时设置） |
+| `BODY` | 最后一条 AI 助手回复的文本内容 |
+| `TITLE` | 会话标题（对应 resume 列表中的标题） |
+
 ```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,46 @@ 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 |
+| `TITLE` | Session title (matches the resume list title) |
+
 ```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,49 @@ 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;
+  title?: string;
+};
+
+export function buildNotifyEnv(
+  durationMs: number,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+  context: NotifyContext = {}
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
     ...baseEnv,
     DURATION: formatDurationSeconds(durationMs),
   };
+  delete env.STATUS;
+  delete env.FAIL_REASON;
+  delete env.BODY;
+  delete env.TITLE;
+
+  if (context.status) {
+    env.STATUS = context.status;
+  }
+  if (context.failReason) {
+    env.FAIL_REASON = context.failReason;
+  }
+  if (context.body) {
+    env.BODY = context.body;
+  }
+  if (context.title) {
+    env.TITLE = context.title;
+  }
+  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 +68,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,23 @@ ${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,
+      title: session.summary ?? undefined,
+    });
   }
 
   private addSessionProcess(sessionId: string, processId: string | number, command: string): void {

src/tests/session.test.ts

@@ -783,6 +783,68 @@ test("reporting a new prompt does not warn when the background request fails", a
   assert.deepEqual(warnings, []);
 });
 
+test(
+  "SessionManager notifies successful completion with session context",
+  { skip: process.platform === "win32" },
+  async () => {
+    const workspace = createTempDir("deepcode-notify-success-workspace-");
+    const home = createTempDir("deepcode-notify-success-home-");
+    setHomeDir(home);
+
+    const notifyOutput = path.join(workspace, "notify.jsonl");
+    const notifyScript = createNotifyRecorderScript(workspace);
+    const manager = createNotifyingSessionManager(
+      workspace,
+      [createChatResponse("final answer", { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 })],
+      notifyScript,
+      notifyOutput
+    );
+
+    await manager.createSession({ text: "notify success" });
+
+    const records = await waitForNotifyRecords(notifyOutput, 1);
+    assert.equal(records[0]?.STATUS, "completed");
+    assert.equal(records[0]?.FAIL_REASON, null);
+    assert.equal(records[0]?.BODY, "final answer");
+    assert.equal(records[0]?.TITLE, "notify success");
+    assert.match(String(records[0]?.DURATION), /^\d+$/);
+  }
+);
+
+test(
+  "SessionManager notifies failed completion with failure context",
+  { skip: process.platform === "win32" },
+  async () => {
+    const workspace = createTempDir("deepcode-notify-failure-workspace-");
+    const home = createTempDir("deepcode-notify-failure-home-");
+    setHomeDir(home);
+
+    const notifyOutput = path.join(workspace, "notify.jsonl");
+    const notifyScript = createNotifyRecorderScript(workspace);
+    const manager = createNotifyingSessionManager(
+      workspace,
+      [
+        createChatResponse("first answer", { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 }),
+        new Error("second request failed"),
+      ],
+      notifyScript,
+      notifyOutput
+    );
+
+    const sessionId = await manager.createSession({ text: "notify failure" });
+    await waitForNotifyRecords(notifyOutput, 1);
+    await manager.replySession(sessionId, { text: "second prompt" });
+
+    const records = await waitForNotifyRecords(notifyOutput, 2);
+    const failedRecord = records[1];
+    assert.equal(failedRecord?.STATUS, "failed");
+    assert.equal(failedRecord?.FAIL_REASON, "second request failed");
+    assert.equal(failedRecord?.BODY, "first answer");
+    assert.notEqual(failedRecord?.BODY, "stale-body");
+    assert.equal(failedRecord?.TITLE, "notify failure");
+  }
+);
+
 test("replySession continues without appending /continue as a user message", async () => {
   const workspace = createTempDir("deepcode-continue-workspace-");
   const home = createTempDir("deepcode-continue-home-");
@@ -1657,6 +1719,49 @@ function createSessionManager(projectRoot: string, machineId: string): SessionMa
   });
 }
 
+function createNotifyingSessionManager(
+  projectRoot: string,
+  responses: unknown[],
+  notifyPath: string,
+  notifyOutput: string
+): SessionManager {
+  const client = {
+    chat: {
+      completions: {
+        create: async () => {
+          const response = responses.shift();
+          assert.ok(response, "expected a queued chat response");
+          if (response instanceof Error) {
+            throw response;
+          }
+          return response;
+        },
+      },
+    },
+  };
+
+  return new SessionManager({
+    projectRoot,
+    createOpenAIClient: () => ({
+      client: client as any,
+      model: "test-model",
+      baseURL: "https://api.deepseek.com",
+      thinkingEnabled: false,
+      notify: notifyPath,
+      env: {
+        NOTIFY_OUTPUT: notifyOutput,
+        STATUS: "stale-status",
+        FAIL_REASON: "stale-failure",
+        BODY: "stale-body",
+        TITLE: "stale-title",
+      },
+    }),
+    getResolvedSettings: () => ({ model: "test-model" }),
+    renderMarkdown: (text) => text,
+    onAssistantMessage: () => {},
+  });
+}
+
 function createMockedClientSessionManager(projectRoot: string, responses: unknown[]): SessionManager {
   const client = {
     chat: {
@@ -1740,6 +1845,45 @@ function createTempDir(prefix: string): string {
   return dir;
 }
 
+function createNotifyRecorderScript(dir: string): string {
+  const scriptPath = path.join(dir, "notify-recorder.cjs");
+  fs.writeFileSync(
+    scriptPath,
+    `#!/usr/bin/env node
+const fs = require("fs");
+const keys = ["DURATION", "STATUS", "FAIL_REASON", "BODY", "TITLE"];
+const record = {};
+for (const key of keys) {
+  record[key] = Object.prototype.hasOwnProperty.call(process.env, key) ? process.env[key] : null;
+}
+fs.appendFileSync(process.env.NOTIFY_OUTPUT, JSON.stringify(record) + "\\n", "utf8");
+`,
+    "utf8"
+  );
+  fs.chmodSync(scriptPath, 0o755);
+  return scriptPath;
+}
+
+async function waitForNotifyRecords(
+  outputPath: string,
+  expectedCount: number
+): Promise<Array<Record<string, unknown>>> {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (fs.existsSync(outputPath)) {
+      const records = fs
+        .readFileSync(outputPath, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as Record<string, unknown>);
+      if (records.length >= expectedCount) {
+        return records;
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  assert.fail(`expected ${expectedCount} notify records in ${outputPath}`);
+}
+
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }