feat(pty): surface notify-on-exit guidance

Author: shekohex

src/plugin/pty/session-lifecycle.ts

@@ -150,6 +150,7 @@ export class SessionLifecycleManager {
       args: session.args,
       workdir: session.workdir,
       status: session.status,
+      notifyOnExit: session.notifyOnExit,
       exitCode: session.exitCode,
       exitSignal: session.exitSignal,
       pid: session.pid,

src/plugin/pty/tools/read.ts

@@ -6,6 +6,16 @@ import { formatLine } from '../formatters.ts'
 import type { PTYSessionInfo } from '../types.ts'
 import DESCRIPTION from './read.txt'
 
+const NOTIFY_ON_EXIT_REMINDER = [
+  `<system_reminder>`,
+  `This session was started with \`notifyOnExit=true\`.`,
+  `Completion signal is the future \`<pty_exited>\` message, not repeated \`pty_read\` calls.`,
+  `If you only need to know whether the command finished, stop polling and wait for \`<pty_exited>\`.`,
+  `Do not use sleep plus \`pty_read\` loops to check completion.`,
+  `Use \`pty_read\` only when you need live output now, the user explicitly asks for logs, or the exit notification reports a non-zero status and you need to investigate.`,
+  `</system_reminder>`,
+].join('\n')
+
 interface ReadArgs {
   id: string
   offset?: number
@@ -36,6 +46,14 @@ function formatPtyOutput(
   return output.join('\n')
 }
 
+function appendNotifyOnExitReminder(output: string, session: PTYSessionInfo): string {
+  if (!session.notifyOnExit || session.status !== 'running') {
+    return output
+  }
+
+  return `${output}\n\n${NOTIFY_ON_EXIT_REMINDER}`
+}
+
 /**
  * Validates and creates a RegExp from pattern string
  */
@@ -73,12 +91,15 @@ function handlePatternRead(
   }
 
   if (result.matches.length === 0) {
-    return [
-      `<pty_output id="${id}" status="${session.status}" pattern="${pattern}">`,
-      `No lines matched the pattern '${pattern}'.`,
-      `Total lines in buffer: ${result.totalLines}`,
-      `</pty_output>`,
-    ].join('\n')
+    return appendNotifyOnExitReminder(
+      [
+        `<pty_output id="${id}" status="${session.status}" pattern="${pattern}">`,
+        `No lines matched the pattern '${pattern}'.`,
+        `Total lines in buffer: ${result.totalLines}`,
+        `</pty_output>`,
+      ].join('\n'),
+      session
+    )
   }
 
   const formattedLines = result.matches.map((match) =>
@@ -88,14 +109,17 @@ function handlePatternRead(
   const paginationMessage = `(${result.matches.length} of ${result.totalMatches} matches shown. Use offset=${offset + result.matches.length} to see more.)`
   const endMessage = `(${result.totalMatches} match${result.totalMatches === 1 ? '' : 'es'} from ${result.totalLines} total lines)`
 
-  return formatPtyOutput(
-    id,
-    session.status,
-    pattern,
-    formattedLines,
-    result.hasMore,
-    paginationMessage,
-    endMessage
+  return appendNotifyOnExitReminder(
+    formatPtyOutput(
+      id,
+      session.status,
+      pattern,
+      formattedLines,
+      result.hasMore,
+      paginationMessage,
+      endMessage
+    ),
+    session
   )
 }
 
@@ -114,12 +138,15 @@ function handlePlainRead(
   }
 
   if (result.lines.length === 0) {
-    return [
-      `<pty_output id="${args.id}" status="${session.status}">`,
-      `(No output available - buffer is empty)`,
-      `Total lines: ${result.totalLines}`,
-      `</pty_output>`,
-    ].join('\n')
+    return appendNotifyOnExitReminder(
+      [
+        `<pty_output id="${args.id}" status="${session.status}">`,
+        `(No output available - buffer is empty)`,
+        `Total lines: ${result.totalLines}`,
+        `</pty_output>`,
+      ].join('\n'),
+      session
+    )
   }
 
   const formattedLines = result.lines.map((line, index) =>
@@ -129,14 +156,17 @@ function handlePlainRead(
   const paginationMessage = `(Buffer has more lines. Use offset=${result.offset + result.lines.length} to read beyond line ${result.offset + result.lines.length})`
   const endMessage = `(End of buffer - total ${result.totalLines} lines)`
 
-  return formatPtyOutput(
-    args.id,
-    session.status,
-    undefined,
-    formattedLines,
-    result.hasMore,
-    paginationMessage,
-    endMessage
+  return appendNotifyOnExitReminder(
+    formatPtyOutput(
+      args.id,
+      session.status,
+      undefined,
+      formattedLines,
+      result.hasMore,
+      paginationMessage,
+      endMessage
+    ),
+    session
   )
 }
 

src/plugin/pty/tools/read.txt

@@ -28,6 +28,7 @@ Tips:
 - To tail recent output, calculate offset as (totalLines - N) where N is how many recent lines you want
 - Lines longer than 2000 characters are truncated
 - Empty output may mean the process hasn't produced output yet
+- If the session was started with `notifyOnExit=true`, do not use repeated `pty_read` calls only to detect completion; wait for the future `<pty_exited>` message instead
 
 Examples:
 - Read first 100 lines: offset=0, limit=100

src/plugin/pty/tools/spawn.ts

@@ -3,6 +3,15 @@ import { manager } from '../manager.ts'
 import { checkCommandPermission, checkWorkdirPermission } from '../permissions.ts'
 import DESCRIPTION from './spawn.txt'
 
+const NOTIFY_ON_EXIT_INSTRUCTIONS = [
+  `<system_reminder>`,
+  `Completion signal for this session is the future \`<pty_exited>\` message.`,
+  `If you only need to know whether the command finished, do not call \`pty_read\`; wait for \`<pty_exited>\`.`,
+  `Never use sleep plus \`pty_read\` loops to check completion for this session.`,
+  `Call \`pty_read\` before exit only if you need live output now, the user explicitly asks for logs, or the exit notification reports a non-zero status and you need to investigate.`,
+  `</system_reminder>`,
+].join('\n')
+
 export const ptySpawn = tool({
   description: DESCRIPTION,
   args: {
@@ -52,7 +61,9 @@ export const ptySpawn = tool({
       `Workdir: ${info.workdir}`,
       `PID: ${info.pid}`,
       `Status: ${info.status}`,
+      `NotifyOnExit: ${info.notifyOnExit}`,
       `</pty_spawned>`,
+      ...(info.notifyOnExit ? ['', NOTIFY_ON_EXIT_INSTRUCTIONS] : []),
     ].join('\n')
 
     return output

src/plugin/pty/tools/spawn.txt

@@ -34,8 +34,11 @@ When `notifyOnExit` is true, you will receive a message when the process exits c
 - Last line of output (truncated to 250 chars)
 
 This is useful for long-running processes where you want to be notified when they complete
-instead of polling with `pty_read`. If the process fails (non-zero exit code), the notification
-will suggest using `pty_read` with the `pattern` parameter to search for errors.
+instead of polling with `pty_read`.
+- Completion signal is the future `<pty_exited>` message
+- If you only need to know whether the command finished, do not call `pty_read`; wait for `<pty_exited>`
+- Never use sleep plus `pty_read` loops to check completion
+- Use `pty_read` before exit only if you need live output now, the user explicitly asks for logs, or the exit notification reports a non-zero status and you need to investigate
 
 Examples:
 - Start a dev server: command="npm", args=["run", "dev"], title="Dev Server"

src/plugin/pty/types.ts

@@ -31,6 +31,7 @@ export interface PTYSessionInfo {
   args: string[]
   workdir: string
   status: PTYStatus
+  notifyOnExit: boolean
   exitCode?: number
   exitSignal?: number | string
   pid: number

test/pty-tools.test.ts

@@ -19,6 +19,7 @@ describe('PTY Tools', () => {
         workdir: opts.workdir || '/tmp',
         pid: 12345,
         status: 'running',
+        notifyOnExit: opts.notifyOnExit ?? false,
         createdAt: new Date().toISOString(),
         lineCount: 0,
       }))
@@ -58,7 +59,9 @@ describe('PTY Tools', () => {
       expect(result).toContain('<pty_spawned>')
       expect(result).toContain('ID: test-session-id')
       expect(result).toContain('Command: echo hello')
+      expect(result).toContain('NotifyOnExit: false')
       expect(result).toContain('</pty_spawned>')
+      expect(result).not.toContain('<system_reminder>')
     })
 
     it('should spawn with all optional args', async () => {
@@ -101,6 +104,14 @@ describe('PTY Tools', () => {
       expect(result).toContain('Command: node script.js')
       expect(result).toContain('PID: 12345')
       expect(result).toContain('Status: running')
+      expect(result).toContain('NotifyOnExit: true')
+      expect(result).toContain('<system_reminder>')
+      expect(result).toContain('Completion signal for this session is the future `<pty_exited>` message.')
+      expect(result).toContain(
+        'If you only need to know whether the command finished, do not call `pty_read`; wait for `<pty_exited>`.'
+      )
+      expect(result).toContain('Never use sleep plus `pty_read` loops to check completion for this session.')
+      expect(result).toContain('</system_reminder>')
     })
   })
 
@@ -114,6 +125,7 @@ describe('PTY Tools', () => {
         args: ['hello'],
         workdir: '/tmp',
         status: 'running',
+        notifyOnExit: false,
         pid: 12345,
         createdAt: new Date().toISOString(),
         lineCount: 2,
@@ -157,6 +169,46 @@ describe('PTY Tools', () => {
       expect(result).toContain('</pty_output>')
     })
 
+    it('should include notifyOnExit reminder for running sessions', async () => {
+      spyOn(manager, 'get').mockReturnValue({
+        id: 'test-session-id',
+        title: 'Test Session',
+        description: 'A session for testing',
+        command: 'echo',
+        args: ['hello'],
+        workdir: '/tmp',
+        status: 'running',
+        notifyOnExit: true,
+        pid: 12345,
+        createdAt: new Date().toISOString(),
+        lineCount: 2,
+      })
+
+      const args = { id: 'test-session-id' }
+      const ctx = {
+        sessionID: 'parent',
+        messageID: 'msg',
+        agent: 'agent',
+        abort: new AbortController().signal,
+        metadata: () => {},
+        ask: async () => {},
+        directory: '/tmp',
+        worktree: '/tmp',
+      }
+
+      const result = await ptyRead.execute(args, ctx)
+
+      expect(result).toContain('<system_reminder>')
+      expect(result).toContain('This session was started with `notifyOnExit=true`.')
+      expect(result).toContain(
+        'Completion signal is the future `<pty_exited>` message, not repeated `pty_read` calls.'
+      )
+      expect(result).toContain(
+        'If you only need to know whether the command finished, stop polling and wait for `<pty_exited>`.'
+      )
+      expect(result).toContain('</system_reminder>')
+    })
+
     it('should read with pattern', async () => {
       const args = { id: 'test-session-id', pattern: 'line' }
       const ctx = {
@@ -224,6 +276,7 @@ describe('PTY Tools', () => {
           command: 'echo',
           args: ['hello'],
           status: 'running' as const,
+          notifyOnExit: false,
           pid: 12345,
           lineCount: 10,
           workdir: '/tmp',

test/types.test.ts

@@ -26,6 +26,7 @@ describe('Web Types', () => {
           title: 'Test Session',
           command: 'echo',
           status: 'running',
+          notifyOnExit: false,
           pid: 1234,
           lineCount: 5,
           createdAt: new Date().toISOString(),
@@ -61,6 +62,7 @@ describe('Web Types', () => {
         title: 'Test Echo Session',
         command: 'echo',
         status: 'exited',
+        notifyOnExit: true,
         exitCode: 0,
         pid: 1234,
         lineCount: 2,
@@ -85,6 +87,7 @@ describe('Web Types', () => {
         title: 'Running Session',
         command: 'sleep',
         status: 'running',
+        notifyOnExit: false,
         pid: 5678,
         lineCount: 0,
         createdAt: new Date('2026-01-21T10:00:00.000Z').toISOString(),