@raidou/pi-notify 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+# @raidou/pi-notify
+
+A notification extension for the [pi](https://github.com/earendil-works/pi-coding-agent) coding agent.
+
+`@raidou/pi-notify` fires a native desktop notification on idle, configured tool calls (e.g., `Tool call: ask_user`), and custom pi events (default: `permissions:ui_prompt`).
+
+## Installation
+
+```bash
+pi install npm:@raidou/pi-notify
+```
+
+Or, for local development, add the repo path to your `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "extensions": ["/absolute/path/to/pi-notify"],
+}
+```
+
+## What triggers a notification
+
+| Event             | Source                                                      | Default body                                |
+| ----------------- | ----------------------------------------------------------- | ------------------------------------------- |
+| **Finished**      | `agent_settled` (pi idle, no active jobs)                   | `Idle`                                      |
+| **Tool calls**    | `tool_call` on tools in `notifyTools`                       | `Tool call: <toolName>`                     |
+| **Custom events** | Custom pi event channels (default: `permissions:ui_prompt`) | Customizable (default: `Permission prompt`) |
+
+### Job tracking for background tasks
+
+Extensions running background tasks can prevent spurious "Idle" notifications by emitting job lifecycle events. Notifications on `agent_settled` are suppressed while jobs are active. Custom event notifications are soft dependencies: if a package that broadcasts a specific event is not installed, that notification is skipped.
+
+```typescript
+import { JOB_START_EVENT, JOB_END_EVENT } from '@raidou/pi-notify'
+
+function startBackgroundJob(jobId: string): void {
+  pi.events.emit(JOB_START_EVENT, { id: jobId })
+}
+
+function endBackgroundJob(jobId: string): void {
+  pi.events.emit(JOB_END_EVENT, { id: jobId })
+}
+```
+
+Events are automatically cleaned up on `session_shutdown`.
+
+## Configuration
+
+All options live under the `piNotify` key in `~/.pi/agent/settings.json`. Everything is optional.
+
+```jsonc
+{
+  "piNotify": {
+    "enabled": true, // master on/off switch (default: true)
+    "notifyTools": ["ask_user", "ask_user_question"], // tools that trigger "Tool call" notifications
+    "tmuxSymbol": "🔔", // symbol appended to tmux window title (empty string to disable)
+    "finished": true, // enable/disable "Idle" notification
+    "events": {
+      "permissions:ui_prompt": "Permission prompt", // custom event channel -> notification message
+      "my:custom:event": "Custom event triggered", // add your own custom events
+    },
+    "finishedThrottleSecs": 0, // 0 = always notify; >0 = skip finished toasts for runs shorter than N seconds
+    "onlyNotifyWhenUnfocused": true, // only notify when user has been inactive
+    "unfocusedActivityThresholdSecs": 30, // seconds of inactivity before considering user "unfocused"
+  },
+}
+```
+
+### Disabling specific events
+
+To disable a specific event, set its message to an empty string:
+
+```jsonc
+{
+  "piNotify": {
+    "events": {
+      "permissions:ui_prompt": "", // disable permission notifications
+    },
+  },
+}
+```
+
+## Testing
+
+Run `/notify-test` inside pi to fire a test notification.
+Pass a string argument (e.g., `/notify-test hello`) to override the body.
+
+## Platform support
+
+`@raidou/pi-notify` prefers `node-notifier` (macOS Notification Center, Linux `notify-send`, native Windows toaster).
+
+**WSL2 note:** `node-notifier` reports `process.platform === "linux"` and would route to `notify-send`, which is usually not installed under WSL and fails silently. `@raidou/pi-notify` detects WSL and raises a Windows toast via `powershell.exe` directly, so notifications reach the Windows Action Center out of the box.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@raidou/pi-notify",
+  "version": "0.2.0",
+  "description": "Desktop notification extension for the pi coding agent.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "notifications",
+    "desktop",
+    "wsl"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/weirongxu/pi-notify.git"
+  },
+  "homepage": "https://github.com/weirongxu/pi-notify",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "main": "./src/index.ts",
+  "scripts": {
+    "test": "pnpm run test:types && pnpm run test:lint",
+    "test:types": "tsc --noEmit",
+    "test:lint": "eslint --fix ."
+  },
+  "dependencies": {
+    "node-notifier": "^10.0.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.79.0"
+  },
+  "devDependencies": {
+    "@raidou/eslint-config-base": "^4.4.3",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.7.0",
+    "prettier": "^3.9.5",
+    "typescript": "^5.6.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+
+interface NotifyEventsConfig {
+  readonly [channel: string]: string
+}
+
+interface NotifyConfig {
+  readonly enabled?: boolean
+  readonly notifyTools?: readonly string[]
+  readonly events?: NotifyEventsConfig
+  readonly finished?: boolean
+  readonly finishedThrottleSecs?: number
+  readonly onlyNotifyWhenUnfocused?: boolean
+  readonly unfocusedActivityThresholdSecs?: number
+  readonly tmuxSymbol?: string
+}
+
+export interface ResolvedNotifyConfig {
+  readonly enabled: boolean
+  readonly notifyTools: ReadonlySet<string>
+  readonly events: NotifyEventsConfig
+  readonly finished: boolean
+  readonly finishedThrottleMs: number
+  readonly onlyNotifyWhenUnfocused: boolean
+  readonly unfocusedActivityThresholdMs: number
+  readonly tmuxSymbol: string
+}
+
+/**
+ * Default tool names that trigger notifications.
+ *
+ * Note: These are built-in pi tool names. If pi renames these tools, the default should be updated.
+ * Source: @earendil-works/pi-coding-agent
+ */
+const DEFAULT_NOTIFY_TOOLS = ['ask_user', 'ask_user_question'] as const
+
+const DEFAULT_TMUX_SYMBOL = '🔔'
+
+const DEFAULT_EVENTS: NotifyEventsConfig = {
+  'permissions:ui_prompt': 'Permission prompt',
+}
+
+const SETTINGS_PATH = join(getAgentDir(), 'settings.json')
+
+function readRawConfig(): NotifyConfig {
+  if (!existsSync(SETTINGS_PATH)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(SETTINGS_PATH, 'utf8')) as {
+      piNotify?: NotifyConfig
+    }
+    return parsed.piNotify ?? {}
+  } catch {
+    // Malformed settings.json must not break the agent; fall back to defaults.
+    return {}
+  }
+}
+
+export function loadConfig(): ResolvedNotifyConfig {
+  const cfg = readRawConfig()
+  const events = cfg.events ?? DEFAULT_EVENTS
+  return {
+    enabled: cfg.enabled ?? true,
+    notifyTools: new Set(cfg.notifyTools ?? DEFAULT_NOTIFY_TOOLS),
+    events,
+    finished: cfg.finished ?? true,
+    finishedThrottleMs: Math.max(0, (cfg.finishedThrottleSecs ?? 0) * 1000),
+    onlyNotifyWhenUnfocused: cfg.onlyNotifyWhenUnfocused ?? true,
+    unfocusedActivityThresholdMs: Math.max(
+      0,
+      (cfg.unfocusedActivityThresholdSecs ?? 30) * 1000,
+    ),
+    tmuxSymbol: cfg.tmuxSymbol ?? DEFAULT_TMUX_SYMBOL,
+  }
+}

package/src/events.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { ResolvedNotifyConfig } from './config.js'
+import type { NotifyAction, Unsubscribe } from './types.js'
+
+export const PI_NOTIFY_EVENT = 'pi-notify:notify'
+
+export class EventsNotifier {
+  private unsubscribes: Unsubscribe[] = []
+  private registered = false
+
+  constructor(
+    private readonly pi: ExtensionAPI,
+    private readonly config: ResolvedNotifyConfig,
+  ) {}
+
+  register(notify: NotifyAction): void {
+    if (this.registered) return
+    this.registered = true
+
+    for (const [channel, message] of Object.entries(this.config.events)) {
+      if (!message) continue
+      const unsubscribe = this.pi.events.on(channel, () => {
+        notify(message)
+      })
+      this.unsubscribes.push(unsubscribe)
+    }
+
+    const customEventUnsub = this.pi.events.on(PI_NOTIFY_EVENT, (payload) => {
+      notify(String(payload))
+    })
+    this.unsubscribes.push(customEventUnsub)
+
+    this.pi.on('session_shutdown', () => {
+      this.stop()
+    })
+  }
+
+  stop(): void {
+    this.unsubscribes.forEach((unsub) => {
+      unsub()
+    })
+    this.unsubscribes = []
+    this.registered = false
+  }
+}

package/src/focus.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { ResolvedNotifyConfig } from './config.js'
+import type { TmuxTitleTracker } from './tmux-title.js'
+import type { Unsubscribe } from './types.js'
+
+// xterm focus reporting (CSI ?1004): emitted by the terminal on focus gain/loss.
+const FOCUS_IN = '\x1b[I'
+const FOCUS_OUT = '\x1b[O'
+const ENABLE_FOCUS_REPORTING = '\x1b[?1004h'
+const DISABLE_FOCUS_REPORTING = '\x1b[?1004l'
+
+export class FocusTracker {
+  private _focused: boolean | undefined = undefined
+  private _lastActivityAt = Date.now()
+  private unsubscribe: Unsubscribe | undefined
+
+  constructor(
+    private readonly pi: ExtensionAPI,
+    private readonly titleTracker: TmuxTitleTracker,
+    private readonly config: ResolvedNotifyConfig,
+  ) {}
+
+  get isFocused(): boolean | undefined {
+    return this._focused
+  }
+
+  /** Timestamp of the last observed terminal input (fallback focus signal). */
+  get lastActivityAt(): number {
+    return this._lastActivityAt
+  }
+
+  register(): void {
+    this.pi.on('session_start', (_event, ctx) => {
+      const activate =
+        ctx.mode === 'tui' &&
+        (this.titleTracker.enabled || this.config.onlyNotifyWhenUnfocused)
+      if (!activate) return
+      this._lastActivityAt = Date.now()
+      process.stdout.write(ENABLE_FOCUS_REPORTING)
+      this.unsubscribe = ctx.ui.onTerminalInput((data) => {
+        this._lastActivityAt = Date.now()
+        const result = this.consume(data)
+        if (result.gainedFocus) this.titleTracker.restore()
+        return result.data === data ? undefined : { data: result.data }
+      })
+    })
+    this.pi.on('session_shutdown', () => {
+      this.stop()
+    })
+  }
+
+  stop(): void {
+    if (this.unsubscribe) {
+      process.stdout.write(DISABLE_FOCUS_REPORTING)
+      this.unsubscribe()
+      this.unsubscribe = undefined
+    }
+    this._focused = undefined
+  }
+
+  private consume(data: string): { data: string; gainedFocus: boolean } {
+    let current = data
+    let gainedFocus = false
+
+    if (current.includes(FOCUS_IN)) {
+      this._focused = true
+      gainedFocus = true
+      current = current.split(FOCUS_IN).join('')
+    }
+    if (current.includes(FOCUS_OUT)) {
+      this._focused = false
+      current = current.split(FOCUS_OUT).join('')
+    }
+
+    return { data: current, gainedFocus }
+  }
+}

package/src/idle.ts

@@ -0,0 +1,48 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { ResolvedNotifyConfig } from './config.js'
+import type { JobTracker } from './jobs.js'
+import type { NotifyAction } from './types.js'
+
+const IDLE_TIMEOUT_MS = 10000
+
+export class IdleNotifier {
+  private timer: NodeJS.Timeout | null = null
+
+  constructor(
+    private readonly pi: ExtensionAPI,
+    private readonly config: ResolvedNotifyConfig,
+    private readonly jobTracker: JobTracker,
+  ) {}
+
+  clearIdleTimer(): void {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+  startIdleTimer(notify: NotifyAction): void {
+    this.clearIdleTimer()
+    this.timer = setTimeout(() => {
+      this.clearIdleTimer()
+      notify('Idle')
+    }, IDLE_TIMEOUT_MS)
+  }
+
+  register(notify: NotifyAction): void {
+    if (!this.config.finished) return
+
+    this.pi.on('turn_start', () => {
+      this.clearIdleTimer()
+    })
+
+    this.pi.on('agent_settled', () => {
+      if (this.jobTracker.hasActiveJobs) return
+      this.startIdleTimer(notify)
+    })
+
+    this.jobTracker.onEnd(() => {
+      this.startIdleTimer(notify)
+    })
+  }
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+import { basename } from 'node:path'
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import { loadConfig } from './config.js'
+import { EventsNotifier } from './events.js'
+import { FocusTracker } from './focus.js'
+import { IdleNotifier } from './idle.js'
+import { JobTracker } from './jobs.js'
+import { notify } from './notifier.js'
+import { NotifyTest } from './notify-test.js'
+import { SessionState } from './states.js'
+import { TmuxTitleTracker } from './tmux-title.js'
+import { ToolCallNotifier } from './tool.js'
+
+export { PI_NOTIFY_EVENT } from './events.js'
+export { JOB_END_EVENT, JOB_START_EVENT } from './jobs.js'
+
+export default function piNotifyExtension(pi: ExtensionAPI): void {
+  const config = loadConfig()
+  const dirName = basename(process.cwd())
+  const title = `pi — ${dirName}`
+
+  const tmuxTitleTracker = new TmuxTitleTracker(pi, config)
+  const focusTracker = new FocusTracker(pi, tmuxTitleTracker, config)
+  const eventsNotifier = new EventsNotifier(pi, config)
+  const toolNotifier = new ToolCallNotifier(pi, config)
+  const jobTracker = new JobTracker(pi)
+  const idleNotifier = new IdleNotifier(pi, config, jobTracker)
+  const notifyTest = new NotifyTest(pi, title, tmuxTitleTracker)
+  const sessionState = new SessionState(pi)
+
+  function notifyReal(body: string): void {
+    if (!config.enabled || !sessionState.hasUI) return
+    if (config.onlyNotifyWhenUnfocused) {
+      // Prefer the real focus state; fall back to inactivity timing for
+      // terminals that lack focus reporting.
+      const recentlyActive =
+        Date.now() - focusTracker.lastActivityAt <=
+        config.unfocusedActivityThresholdMs
+      if (focusTracker.isFocused ?? recentlyActive) return
+    }
+    tmuxTitleTracker.mark()
+    notify(title, body)
+  }
+
+  tmuxTitleTracker.register()
+  focusTracker.register()
+  jobTracker.register()
+  eventsNotifier.register(notifyReal)
+  toolNotifier.register(notifyReal)
+  idleNotifier.register(notifyReal)
+  notifyTest.register()
+}

package/src/jobs.ts

@@ -0,0 +1,70 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { Unsubscribe } from './types.js'
+
+export const JOB_START_EVENT = 'pi-notify:job:start'
+export const JOB_END_EVENT = 'pi-notify:job:end'
+
+export class JobTracker {
+  private activeJobs = new Set<string>()
+  private unsubscribes: Unsubscribe[] = []
+  private registered = false
+  private onEndListeners: Array<() => void> = []
+
+  constructor(private readonly pi: ExtensionAPI) {}
+
+  get hasActiveJobs(): boolean {
+    return this.activeJobs.size > 0
+  }
+
+  onEnd(listener: () => void): () => void {
+    this.onEndListeners.push(listener)
+    return () => {
+      const index = this.onEndListeners.indexOf(listener)
+      if (index !== -1) this.onEndListeners.splice(index, 1)
+    }
+  }
+
+  register(): void {
+    if (this.registered) return
+    this.registered = true
+
+    const startUnsub = this.pi.events.on(JOB_START_EVENT, (params) => {
+      if (
+        typeof params === 'object' &&
+        params !== null &&
+        'id' in params &&
+        typeof params.id === 'string'
+      ) {
+        this.activeJobs.add(params.id)
+      }
+    })
+    this.unsubscribes.push(startUnsub)
+
+    const endUnsub = this.pi.events.on(JOB_END_EVENT, (params) => {
+      if (
+        typeof params === 'object' &&
+        params !== null &&
+        'id' in params &&
+        typeof params.id === 'string'
+      ) {
+        for (const listener of this.onEndListeners) listener()
+        this.activeJobs.delete(params.id)
+      }
+    })
+    this.unsubscribes.push(endUnsub)
+
+    this.pi.on('session_shutdown', () => {
+      this.stop()
+    })
+  }
+
+  stop(): void {
+    this.unsubscribes.forEach((unsub) => {
+      unsub()
+    })
+    this.unsubscribes = []
+    this.activeJobs.clear()
+    this.registered = false
+  }
+}

package/src/node-notifier.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Minimal type declaration for `node-notifier` (ships without bundled types).
+ * Only the surface this extension uses is modeled.
+ */
+declare module 'node-notifier' {
+  export interface NodeNotifierOptions {
+    title?: string
+    message: string
+    wait?: boolean
+  }
+
+  export interface NodeNotifier {
+    notify(
+      options: NodeNotifierOptions,
+      callback?: (error: Error | null) => void,
+    ): void
+  }
+
+  const notifier: NodeNotifier
+  export default notifier
+}

package/src/notifier.ts

@@ -0,0 +1,55 @@
+import { execFile } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+
+/**
+ * WSL reports `process.platform === "linux"` but the user's desktop is Windows.
+ * node-notifier would route to `notify-send` (not installed) and silently fail,
+ * so we bypass it and call `powershell.exe` directly to raise a Windows toast.
+ */
+const isWSL = detectWSL()
+
+function detectWSL(): boolean {
+  if (process.platform !== 'linux') return false
+  if (process.env.WSL_DISTRO_NAME ?? process.env.WT_SESSION) return true
+  try {
+    return /microsoft/i.test(readFileSync('/proc/version', 'utf8'))
+  } catch {
+    return false
+  }
+}
+
+function escapePowerShell(value: string): string {
+  return value.replace(/'/g, "''").replace(/\r?\n/g, ' ')
+}
+
+function windowsToast(title: string, body: string): void {
+  const app = escapePowerShell(title)
+  const text = escapePowerShell(body)
+  // `.Item(0)` (not the `[0]` indexer) avoids a PowerShell 5.1 enumeration
+  // quirk that throws "Collection was modified" on the live XmlNodeList.
+  const script = [
+    '[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null',
+    `$t = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText01)`,
+    `[void] $t.GetElementsByTagName('text').Item(0).AppendChild($t.CreateTextNode('${text}'))`,
+    `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${app}').Show([Windows.UI.Notifications.ToastNotification]::new($t))`,
+  ].join('; ')
+  const exe = process.platform === 'win32' ? 'powershell' : 'powershell.exe'
+  execFile(exe, ['-NoProfile', '-NonInteractive', '-Command', script], () => {})
+}
+
+async function piNotify(title: string, body: string): Promise<void> {
+  if (isWSL || process.platform === 'win32') {
+    windowsToast(title, body)
+    return
+  }
+  const notifier = (await import('node-notifier')).default
+  await new Promise<void>((resolve) => {
+    notifier.notify({ title, message: body, wait: false }, () => {
+      resolve()
+    })
+  })
+}
+
+export function notify(title: string, body: string): void {
+  void piNotify(title, body).catch(() => {})
+}

package/src/notify-test.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import { notify } from './notifier.js'
+import type { TmuxTitleTracker } from './tmux-title.js'
+import { sleep } from './utils.js'
+
+const DEFAULT_BODY = 'This is a test notification.'
+
+export class NotifyTest {
+  constructor(
+    private readonly pi: ExtensionAPI,
+    private readonly title: string,
+    private readonly titleTracker: TmuxTitleTracker,
+  ) {}
+
+  register(): void {
+    this.pi.registerCommand('notify-test', {
+      description: 'Fire a test notification',
+      handler: async (args) => {
+        await sleep(3000)
+        this.titleTracker.mark()
+        notify(this.title, args.trim() || DEFAULT_BODY)
+      },
+    })
+  }
+}

package/src/states.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+export class SessionState {
+  public hasUI = false
+
+  constructor(private readonly pi: ExtensionAPI) {
+    this.register()
+  }
+
+  private register(): void {
+    this.pi.on('session_start', (_event, ctx) => {
+      this.hasUI = ctx.hasUI
+    })
+    this.pi.on('session_shutdown', () => {
+      this.hasUI = false
+    })
+  }
+}

package/src/tmux-title.ts

@@ -0,0 +1,221 @@
+import { execFileSync } from 'node:child_process'
+import { readlinkSync } from 'node:fs'
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { ResolvedNotifyConfig } from './config.js'
+
+const WINDOW_ID_FORMAT = '#{window_id}'
+const WINDOW_NAME_FORMAT = '#{window_name}'
+const LIST_FORMAT = '#{pane_tty}\t#{window_id}'
+const NEWLINE = '\n'
+const TAB = '\t'
+
+export class TmuxTitleTracker {
+  private windowId: string | undefined
+  private originalTitle: string | undefined
+  private autoRename: boolean | undefined
+  private modified = false
+
+  constructor(
+    private readonly pi: ExtensionAPI,
+    private readonly config: ResolvedNotifyConfig,
+  ) {}
+
+  get enabled(): boolean {
+    return this.config.tmuxSymbol.length > 0
+  }
+
+  register(): void {
+    this.pi.on('session_start', (_event, ctx) => {
+      if (ctx.mode !== 'tui' || !this.enabled) return
+      // Resolve pi's own window up front via its controlling tty, so mark/restore
+      // keep targeting it even if the user switches windows during /new.
+      const id = this.queryCurrentWindowId()
+      if (id === undefined) return
+      this.windowId = id
+      this.originalTitle = this.queryWindowName(id)
+      this.autoRename = this.queryAutomaticRename(id)
+    })
+    this.pi.on('session_shutdown', () => {
+      this.stop()
+    })
+  }
+
+  mark(): void {
+    if (
+      !this.enabled ||
+      this.modified ||
+      this.windowId === undefined ||
+      this.originalTitle === undefined
+    )
+      return
+    this.renameWindow(
+      this.windowId,
+      `${this.originalTitle}${this.config.tmuxSymbol}`,
+    )
+    this.modified = true
+  }
+
+  restore(): void {
+    if (
+      !this.modified ||
+      this.windowId === undefined ||
+      this.originalTitle === undefined
+    )
+      return
+    this.renameWindow(this.windowId, this.originalTitle)
+    if (this.autoRename === undefined) {
+      this.unsetAutomaticRename(this.windowId)
+    } else {
+      this.setAutomaticRename(this.windowId, this.autoRename)
+    }
+    this.modified = false
+  }
+
+  stop(): void {
+    this.windowId = undefined
+    this.originalTitle = undefined
+    this.autoRename = undefined
+    this.modified = false
+  }
+
+  private queryCurrentWindowId(): string | undefined {
+    if (process.env.TMUX === undefined) return undefined
+    const tty = this.ourTty()
+    if (tty !== undefined) {
+      const id = this.findWindowByTty(tty)
+      if (id !== undefined) return id
+    }
+    return this.queryActiveWindowId()
+  }
+
+  private queryWindowName(windowId: string): string | undefined {
+    try {
+      const name = execFileSync(
+        'tmux',
+        ['display-message', '-t', windowId, '-p', WINDOW_NAME_FORMAT],
+        {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        },
+      )
+      return name.trim() || undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  private renameWindow(windowId: string, name: string): void {
+    try {
+      execFileSync('tmux', ['rename-window', '-t', windowId, name], {
+        stdio: 'ignore',
+      })
+    } catch {
+      // best-effort; the window title is non-critical
+    }
+  }
+
+  private ourTty(): string | undefined {
+    for (const fd of ['0', '1', '2']) {
+      try {
+        const target = readlinkSync(`/proc/self/fd/${fd}`)
+        if (target.startsWith('/dev/')) return target
+      } catch {
+        // fd is not a tty, or platform without /proc/self/fd
+      }
+    }
+    return undefined
+  }
+
+  private findWindowByTty(tty: string): string | undefined {
+    try {
+      const out = execFileSync(
+        'tmux',
+        ['list-panes', '-a', '-F', LIST_FORMAT],
+        {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        },
+      )
+      for (const line of out.split(NEWLINE)) {
+        const [paneTty, windowId] = line.split(TAB)
+        if (paneTty === tty) return windowId
+      }
+      return undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  private queryActiveWindowId(): string | undefined {
+    try {
+      const id = execFileSync(
+        'tmux',
+        ['display-message', '-p', WINDOW_ID_FORMAT],
+        {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        },
+      )
+      return id.trim() || undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  private queryAutomaticRename(windowId: string): boolean | undefined {
+    try {
+      const value = execFileSync(
+        'tmux',
+        ['show-window-options', '-t', windowId, '-v', 'automatic-rename'],
+        {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        },
+      )
+      const trimmed = value.trim()
+      // Empty output means no window-local override exists; the window
+      // inherits the global option. Restore by unsetting, not by forcing
+      // a value, so it keeps inheriting whatever the global is.
+      if (trimmed === '') return undefined
+      return trimmed === 'on'
+    } catch {
+      return undefined
+    }
+  }
+
+  private setAutomaticRename(windowId: string, enabled: boolean): void {
+    try {
+      execFileSync(
+        'tmux',
+        [
+          'set-window-option',
+          '-t',
+          windowId,
+          'automatic-rename',
+          enabled ? 'on' : 'off',
+        ],
+        {
+          stdio: 'ignore',
+        },
+      )
+    } catch {
+      // best-effort; the window title is non-critical
+    }
+  }
+
+  private unsetAutomaticRename(windowId: string): void {
+    try {
+      execFileSync(
+        'tmux',
+        ['set-window-option', '-t', windowId, '-u', 'automatic-rename'],
+        {
+          stdio: 'ignore',
+        },
+      )
+    } catch {
+      // best-effort; the window title is non-critical
+    }
+  }
+}

package/src/tool.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import type { ResolvedNotifyConfig } from './config.js'
+import type { NotifyAction } from './types.js'
+
+export class ToolCallNotifier {
+  constructor(
+    private readonly pi: ExtensionAPI,
+    private readonly config: ResolvedNotifyConfig,
+  ) {}
+
+  register(notify: NotifyAction): void {
+    this.pi.on('tool_call', (event) => {
+      if (!this.config.notifyTools.has(event.toolName)) return
+      notify(`Tool call: ${event.toolName}`)
+    })
+  }
+}

package/src/types.ts

@@ -0,0 +1,3 @@
+export type Unsubscribe = () => void
+
+export type NotifyAction = (body: string) => void

package/src/utils.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}