@zhushanwen/pi-system-prompt 1.0.1

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@zhushanwen/pi-system-prompt",
+  "version": "1.0.1",
+  "description": "System prompt injection extension for Pi — reads config and appends to system prompt",
+  "type": "module",
+  "main": "src/index.ts",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "extension",
+    "system-prompt",
+    "config"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/system-prompt.test.ts

@@ -0,0 +1,311 @@
+/**
+ * system-prompt extension 真实行为测试。
+ *
+ * 覆盖（替换原 expect(true) 占位，R3 extension-api SUGGESTION #1）：
+ * - readJsonIfValid 解析边界：文件缺失 / 畸形 JSON / 顶层 array / 顶层原始值 → 全部收敛 defaults
+ * - readSection 字段级防御：section 非对象、enabled 非 true、prompt 非字符串 / 空白 → 不注入
+ * - before_agent_start 注入顺序：base → global instructions → append config（indexOf 链锁定，
+ *   swap 注入顺序两行的 mutant 会被顺序用例 kill）
+ * - -nc / --no-context-files 守卫：global 注入跳过、append 不受影响
+ * - global 候选选择：候选序优先、空白内容跳过继续找、目录缺失降级
+ * - fail-safe：handler 全程 throw → return undefined + stderr 可观测；stderr 写失败的
+ *   终极兜底 console.debug；systemPrompt 非法类型的旧 quirk 锚定
+ *
+ * mock 策略（参照 msg-id-mapper 测试模式）：pi SDK import type 零运行时解析，
+ * ExtensionAPI 用结构化桩；node:fs mock 后按路径分流（env 指向假目录，不碰真实文件系统）。
+ *
+ * 运行：cd extensions/system-prompt && npx vitest run
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+import createExtension from '../index'
+import type { ExtensionAPI, BeforeAgentStartEvent } from '@earendil-works/pi-coding-agent'
+
+vi.mock('node:fs', () => ({
+  readFileSync: vi.fn(),
+  readdirSync: vi.fn(),
+  statSync: vi.fn(),
+}))
+
+const DATA_DIR = '/xyz-test/data'
+const GLOBAL_DIR = '/xyz-test/global-agents'
+const CONFIG_PATH = path.join(DATA_DIR, 'system-prompt.json')
+
+/** hook 注册表桩（参照 msg-id-mapper harness 模式） */
+function createHarness(): { beforeAgentStart: (event: BeforeAgentStartEvent) => unknown } {
+  const handlers = new Map<string, (...args: unknown[]) => unknown>()
+  const pi = {
+    on: (event: string, handler: (...args: unknown[]) => unknown) => {
+      handlers.set(event, handler)
+    },
+  } as unknown as ExtensionAPI
+  createExtension(pi)
+  return {
+    beforeAgentStart: (event) => handlers.get('before_agent_start')!(event),
+  }
+}
+
+/** 触发一次 hook 的便捷封装（常规 event：systemPrompt 字符串） */
+function runHook(systemPrompt: string): { systemPrompt?: string } | undefined {
+  const h = createHarness()
+  return h.beforeAgentStart({ type: 'before_agent_start', prompt: 'hi', systemPrompt }) as
+    | { systemPrompt?: string }
+    | undefined
+}
+
+/**
+ * fs mock 分流配置。
+ * - config：system-prompt.json 的文件内容（string）或 Error（readFileSync throw，默认 ENOENT）
+ * - globalEntries：global 目录 readdirSync 返回（默认 [] = 无候选）
+ * - globalFiles：候选文件名 → 内容（string）或 Error（stat/read throw）
+ */
+interface FsSetup {
+  config?: string | Error
+  globalEntries?: string[] | Error
+  globalFiles?: Record<string, string | Error>
+}
+
+function setupFs(setup: FsSetup = {}): void {
+  const { config = new Error("ENOENT: no such file or directory, open '" + CONFIG_PATH + "'") } = setup
+  const { globalEntries = [], globalFiles = {} } = setup
+  vi.mocked(readdirSync).mockImplementation(() => {
+    if (globalEntries instanceof Error) throw globalEntries
+    return globalEntries as unknown as string[]
+  })
+  vi.mocked(statSync).mockImplementation((p: unknown) => {
+    const name = path.basename(String(p))
+    if (!(name in globalFiles)) throw new Error('ENOENT stat ' + String(p))
+    if (globalFiles[name] instanceof Error) throw globalFiles[name]
+    return { isFile: () => true } as unknown as ReturnType<typeof statSync>
+  })
+  vi.mocked(readFileSync).mockImplementation((p: unknown) => {
+    const fp = String(p)
+    if (fp === CONFIG_PATH) {
+      if (config instanceof Error) throw config
+      return config
+    }
+    const name = path.basename(fp)
+    if (name in globalFiles) {
+      if (globalFiles[name] instanceof Error) throw globalFiles[name]
+      return globalFiles[name]
+    }
+    throw new Error('ENOENT: no such file, open ' + fp)
+  })
+}
+
+const ENV_KEYS = ['XYZ_AGENT_DATA_DIR', 'XYZ_GLOBAL_AGENTS_DIR', 'PI_CODING_AGENT_DIR'] as const
+const savedEnv: Record<string, string | undefined> = {}
+const savedArgv = process.argv
+
+beforeEach(() => {
+  vi.clearAllMocks() // 清跨用例的 fs mock 调用记录（「守卫不触发」类断言依赖零计数）
+  for (const k of ENV_KEYS) savedEnv[k] = process.env[k]
+  process.env.XYZ_AGENT_DATA_DIR = DATA_DIR
+  process.env.XYZ_GLOBAL_AGENTS_DIR = GLOBAL_DIR
+  delete process.env.PI_CODING_AGENT_DIR
+  setupFs()
+})
+
+afterEach(() => {
+  for (const k of ENV_KEYS) {
+    if (savedEnv[k] === undefined) delete process.env[k]
+    else process.env[k] = savedEnv[k]
+  }
+  process.argv = savedArgv
+  vi.restoreAllMocks()
+})
+
+describe('readJsonIfValid 解析边界（config 读取 → defaults 收敛）', () => {
+  it('config 文件缺失（ENOENT）→ defaults → 无注入，返回 undefined', () => {
+    setupFs({ config: new Error("ENOENT: no such file or directory, open '" + CONFIG_PATH + "'") })
+    expect(runHook('base prompt')).toBeUndefined()
+  })
+
+  it('config 畸形 JSON（parse throw）→ defaults → 无注入', () => {
+    setupFs({ config: '{broken json' })
+    expect(runHook('base prompt')).toBeUndefined()
+  })
+
+  it('config 顶层 array → isJsonObject 放行 quirk（数组不排除）→ 字段缺省收敛 defaults → 无注入', () => {
+    // R3 复核锚定的行为等价：顶层数组两版实现同走 typeof object 放行路径，无错误数据
+    setupFs({ config: '[1, 2]' })
+    expect(runHook('base prompt')).toBeUndefined()
+  })
+
+  it('config 顶层原始值（number / string / null 字面量）→ null → defaults → 无注入', () => {
+    for (const bad of ['42', '"a string"', 'null', 'true']) {
+      setupFs({ config: bad })
+      expect(runHook('base prompt')).toBeUndefined()
+    }
+  })
+})
+
+describe('readSection 字段级防御（append section）', () => {
+  it('append section 非对象（null / 字符串）→ {enabled:false, prompt:""} → 不注入', () => {
+    for (const section of ['null', '"just text"']) {
+      setupFs({ config: `{"append": ${section}}` })
+      expect(runHook('base prompt')).toBeUndefined()
+    }
+  })
+
+  it('append.enabled 非 true（字符串 "true"）→ 不视为开启 → 不注入', () => {
+    setupFs({ config: '{"append": {"enabled": "true", "prompt": "extra"}}' })
+    expect(runHook('base prompt')).toBeUndefined()
+  })
+
+  it('append.prompt 非字符串（number）→ 缺省 "" → 不注入', () => {
+    setupFs({ config: '{"append": {"enabled": true, "prompt": 123}}' })
+    expect(runHook('base prompt')).toBeUndefined()
+  })
+
+  it('append.enabled true 但 prompt 纯空白 → trim 后为空 → 不注入', () => {
+    setupFs({ config: '{"append": {"enabled": true, "prompt": "   \\n\\t "}}' })
+    expect(runHook('base prompt')).toBeUndefined()
+  })
+
+  it('append 合法（enabled true + 非空 prompt）→ 注入到 base 之后（\\n\\n 分隔）', () => {
+    setupFs({ config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}' })
+    expect(runHook('base prompt')).toEqual({ systemPrompt: 'base prompt\n\nAPPEND-TEXT' })
+  })
+})
+
+describe('before_agent_start 注入顺序（base → global → append）', () => {
+  it('三段齐备 → base 在前、global 段居中、append 文本最后（indexOf 链锁定）', () => {
+    setupFs({
+      config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
+      globalEntries: ['AGENTS.md'],
+      globalFiles: { 'AGENTS.md': 'GLOBAL-CONTENT' },
+    })
+    const result = runHook('BASE-PROMPT')
+    expect(result).toEqual({ systemPrompt: expect.stringContaining('APPEND-TEXT') })
+    const prompt = result!.systemPrompt as string
+
+    // 顺序锚点：base 最前 → global header → global 内容 → append 文本最后
+    const iBase = prompt.indexOf('BASE-PROMPT')
+    const iHeader = prompt.indexOf('# Global instructions')
+    const iGlobal = prompt.indexOf('GLOBAL-CONTENT')
+    const iAppend = prompt.indexOf('APPEND-TEXT')
+    expect(iBase).toBeGreaterThanOrEqual(0)
+    expect(iHeader).toBeGreaterThan(iBase)
+    expect(iGlobal).toBeGreaterThan(iHeader)
+    expect(iAppend).toBeGreaterThan(iGlobal)
+    expect(prompt.indexOf('APPEND-TEXT', iAppend + 1)).toBe(-1) // append 恰一次
+    // global header 带真实注入路径（可追溯）
+    expect(prompt).toContain(path.join(GLOBAL_DIR, 'AGENTS.md'))
+  })
+
+  it('global 无候选文件 → 只剩 base + append 两段', () => {
+    setupFs({
+      config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
+      globalEntries: [],
+    })
+    const result = runHook('BASE-PROMPT')
+    expect(result).toEqual({ systemPrompt: 'BASE-PROMPT\n\nAPPEND-TEXT' })
+    expect(result!.systemPrompt).not.toContain('# Global instructions')
+  })
+})
+
+describe('-nc / --no-context-files 守卫（contextFilesDisabled）', () => {
+  it('argv 含 --no-context-files → global 不注入，append 仍生效（用户显式退出不得溜回来）', () => {
+    setupFs({
+      config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
+      globalEntries: ['AGENTS.md'],
+      globalFiles: { 'AGENTS.md': 'GLOBAL-CONTENT' },
+    })
+    process.argv = ['node', 'pi', '--no-context-files']
+    expect(runHook('BASE-PROMPT')).toEqual({ systemPrompt: 'BASE-PROMPT\n\nAPPEND-TEXT' })
+    // 守卫在读 global 文件之前：readdirSync 不应被调用（global 目录完全不被触碰）
+    expect(readdirSync).not.toHaveBeenCalled()
+  })
+
+  it('argv 含 -nc 短形式 → 同样跳过 global 注入（与 argv-mirror 两种形式一致）', () => {
+    setupFs({
+      config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
+      globalEntries: ['AGENTS.md'],
+      globalFiles: { 'AGENTS.md': 'GLOBAL-CONTENT' },
+    })
+    process.argv = ['node', 'pi', '-nc']
+    expect(runHook('BASE-PROMPT')).toEqual({ systemPrompt: 'BASE-PROMPT\n\nAPPEND-TEXT' })
+  })
+})
+
+describe('global 候选文件选择（readGlobalAgentsFile）', () => {
+  it('候选序优先：AGENTS.MD 与 CLAUDE.md 并存 → AGENTS.MD 胜（候选列表顺序的第一个存在者）', () => {
+    setupFs({
+      globalEntries: ['AGENTS.MD', 'CLAUDE.md'],
+      globalFiles: { 'AGENTS.MD': 'FROM-AGENTS-UPPER', 'CLAUDE.md': 'FROM-CLAUDE' },
+    })
+    const result = runHook('BASE-PROMPT')
+    expect(result!.systemPrompt).toContain('FROM-AGENTS-UPPER')
+    expect(result!.systemPrompt).not.toContain('FROM-CLAUDE')
+    expect(result!.systemPrompt).toContain(path.join(GLOBAL_DIR, 'AGENTS.MD'))
+  })
+
+  it('首候选内容空白 → 跳过继续找下一候选（AGENTS.md 空白 + CLAUDE.md 有内容 → 注入 CLAUDE.md）', () => {
+    setupFs({
+      globalEntries: ['AGENTS.md', 'CLAUDE.md'],
+      globalFiles: { 'AGENTS.md': '   \n\t', 'CLAUDE.md': 'FROM-CLAUDE' },
+    })
+    const result = runHook('BASE-PROMPT')
+    expect(result!.systemPrompt).toContain('FROM-CLAUDE')
+    expect(result!.systemPrompt).toContain(path.join(GLOBAL_DIR, 'CLAUDE.md'))
+  })
+
+  it('global 目录不存在（readdirSync throw）→ 降级 null：不注入、不抛错', () => {
+    setupFs({ globalEntries: new Error('ENOENT: no such directory') })
+    expect(runHook('BASE-PROMPT')).toBeUndefined()
+  })
+})
+
+describe('fail-safe（外层 catch return undefined，永不阻断 agent loop）', () => {
+  it('handler 全程 throw（systemPrompt getter 抛错）→ return undefined + stderr 落盘可观测', () => {
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+    const h = createHarness()
+    const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
+    Object.defineProperty(event, 'systemPrompt', {
+      get() {
+        throw new Error('getter boom')
+      },
+    })
+    expect(h.beforeAgentStart(event)).toBeUndefined()
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('[xyz-system-prompt-extension] before_agent_start hook failed: Error: getter boom'),
+    )
+  })
+
+  it('stderr 写失败的终极兜底 → console.debug 吞掉，仍 return undefined', () => {
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => {
+      throw new Error('stderr gone')
+    })
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+    const h = createHarness()
+    const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
+    Object.defineProperty(event, 'systemPrompt', {
+      get() {
+        throw new Error('getter boom')
+      },
+    })
+    expect(h.beforeAgentStart(event)).toBeUndefined()
+    expect(debugSpy).toHaveBeenCalledWith(
+      expect.stringContaining('[xyz-system-prompt-extension] stderr write also failed:'),
+      expect.any(Error),
+    )
+  })
+
+  it('systemPrompt 非法类型（undefined）且无注入 → 旧 quirk 锚定：返回 {systemPrompt:""} 而非 undefined', () => {
+    // R3 复核锚定的返回值守卫 quirk（index.ts newPrompt === event.systemPrompt 比较）：
+    // base 收敛 ''，'' !== undefined → 返回 {systemPrompt: ''}。与重构前行为一致（非回归）。
+    const h = createHarness()
+    const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
+    expect(h.beforeAgentStart(event)).toEqual({ systemPrompt: '' })
+  })
+
+  it('systemPrompt 非法类型（undefined）但有 append 注入 → newPrompt = 空串 base + 分隔符 + append', () => {
+    setupFs({ config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}' })
+    const h = createHarness()
+    const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
+    // base 收敛 ''，拼接形态固定为 '' + '\n\n' + append（分隔符保留，与合法 base 一致）
+    expect(h.beforeAgentStart(event)).toEqual({ systemPrompt: '\n\nAPPEND-TEXT' })
+  })
+})

package/src/index.ts

@@ -0,0 +1,212 @@
+/**
+ * System prompt injection extension for Pi.
+ *
+ * Registers a `before_agent_start` hook that:
+ *  1. Reads <dataDir>/system-prompt.json every turn (never cached).
+ *  2. When `append.enabled === true` and `append.prompt` is non-blank,
+ *     appends the user's text to the event's systemPrompt.
+ *  3. Reads the global instructions file `~/.agents/AGENTS.md` (candidates
+ *     AGENTS.md / AGENTS.MD / CLAUDE.md / CLAUDE.MD — mirroring pi's native
+ *     `loadContextFileFromDir`) every turn and appends it under a labeled
+ *     header. Opt-in by file existence: no file → no injection. Skipped when
+ *     pi was spawned with `--no-context-files` (consistent with pi's native
+ *     context-file opt-out). `XYZ_GLOBAL_AGENTS_DIR` overrides the global
+ *     directory (test hook / escape hatch).
+ *
+ * Injection order per turn: base prompt → global instructions → append config
+ * (the explicitly configured text wins last).
+ *
+ * Fail-safe: any error in the handler is swallowed and `undefined` is returned
+ * so the agent loop is never blocked.
+ */
+
+import path from 'node:path'
+import { homedir } from 'node:os'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import type { ExtensionAPI, BeforeAgentStartEvent } from '@earendil-works/pi-coding-agent'
+
+const CONFIG_FILE = 'system-prompt.json'
+
+/** Global instruction candidates, mirroring pi's loadContextFileFromDir. */
+const GLOBAL_AGENTS_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD']
+
+/**
+ * Resolve the data directory from the environment.
+ *
+ * Priority:
+ *  1. `process.env.XYZ_AGENT_DATA_DIR` (explicit)
+ *  2. `path.resolve(process.env.PI_CODING_AGENT_DIR ?? '', '..', '..')`
+ *     (PI_CODING_AGENT_DIR == <dataDir>/pi/agent, two levels up == dataDir)
+ *
+ * Re-read on every handler invocation so env changes between turns/sessions
+ * take effect without reloading the extension.
+ */
+function resolveDataDir(): string {
+  if (process.env.XYZ_AGENT_DATA_DIR) {
+    return process.env.XYZ_AGENT_DATA_DIR
+  }
+  return path.resolve(process.env.PI_CODING_AGENT_DIR ?? '', '..', '..')
+}
+
+/**
+ * Resolve the global agents directory.
+ *
+ * Priority:
+ *  1. `process.env.XYZ_GLOBAL_AGENTS_DIR` (explicit override; tests / escape
+ *     hatch)
+ *  2. `~/.agents` (the user-global agents dir that also hosts skills/templates)
+ *
+ * Re-read on every handler invocation so env changes take effect.
+ */
+function resolveGlobalAgentsDir(): string {
+  if (process.env.XYZ_GLOBAL_AGENTS_DIR) {
+    return process.env.XYZ_GLOBAL_AGENTS_DIR
+  }
+  return path.join(homedir(), '.agents')
+}
+
+/**
+ * Read the global instructions file. First candidate that exists and is a
+ * regular file with non-blank content wins (mirrors pi's loadContextFileFromDir
+ * semantics). Returns { path, content } or null; never throws.
+ */
+function readGlobalAgentsFile(): { path: string; content: string } | null {
+  const dir = resolveGlobalAgentsDir()
+  // Match candidates against real directory entries (exact case) instead of
+  // existsSync-per-candidate: on case-insensitive filesystems (macOS APFS
+  // default) existsSync('AGENTS.md') would hit a file actually named
+  // AGENTS.MD, reporting an injected path that differs from the on-disk
+  // filename and shadowing the later exact-case candidate.
+  let entries: Set<string>
+  try {
+    entries = new Set(readdirSync(dir))
+  } catch {
+    return null
+  }
+  for (const name of GLOBAL_AGENTS_CANDIDATES) {
+    if (!entries.has(name)) continue
+    const filePath = path.join(dir, name)
+    try {
+      if (statSync(filePath).isFile()) {
+        const content = readFileSync(filePath, 'utf-8')
+        if (content.trim()) {
+          return { path: filePath, content }
+        }
+      }
+    } catch (err) {
+      // best-effort：候选文件 stat/read 失败（如权限）→ 试下一个候选，never throw into the agent loop。
+      console.debug('[xyz-system-prompt-extension] candidate file read failed, trying next:', err)
+    }
+  }
+  return null
+}
+
+/**
+ * Read & parse the config file. Missing / malformed / partial → all-default.
+ * Returns the effective config object; never throws.
+ */
+function readConfig(dataDir: string): {
+  version: number
+  replace: { enabled: boolean; prompt: string }
+  append: { enabled: boolean; prompt: string }
+} {
+  const parsed = readJsonIfValid(path.join(dataDir, CONFIG_FILE))
+  if (!parsed) {
+    return {
+      version: 1,
+      replace: { enabled: false, prompt: '' },
+      append: { enabled: false, prompt: '' },
+    }
+  }
+  // Merge defensively — every field has its own default.
+  // replace 字段仅防御性解析保持 config 结构完整，不参与本 hook 逻辑——
+  // replace 走 --system-prompt CLI（ADR-0038），hook 只处理 append。
+  return {
+    version: typeof parsed.version === 'number' ? parsed.version : 1,
+    replace: readSection(parsed.replace),
+    append: readSection(parsed.append),
+  }
+}
+
+/** Read a JSON file and return it as an object; missing / malformed / non-object → null. */
+function readJsonIfValid(filePath: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(filePath, 'utf-8'))
+    return isJsonObject(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function isJsonObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === 'object'
+}
+
+/** Defensive field parsing for a `replace`/`append` config section. */
+function readSection(raw: unknown): { enabled: boolean; prompt: string } {
+  const section = isJsonObject(raw) ? raw : {}
+  return {
+    enabled: section.enabled === true,
+    prompt: typeof section.prompt === 'string' ? section.prompt : '',
+  }
+}
+
+/**
+ * pi 是否以 --no-context-files / -nc 启动。用户显式退出 AGENTS.md / CLAUDE.md
+ * 发现时，全局文件不得从这条通路溜回来。pi CLI 把 -nc 视为 --no-context-files
+ * 的等价短形式（cli/args.ts），两种形式都必须命中守卫——与镜像侧
+ * （argv-mirror.ts 同样解析两种形式）保持一致。
+ */
+function contextFilesDisabled(): boolean {
+  return process.argv.includes('--no-context-files') || process.argv.includes('-nc')
+}
+
+/** Append the global instructions (~/.agents/AGENTS.md ...) under a labeled header. */
+function withGlobalInstructions(prompt: string): string {
+  if (contextFilesDisabled()) return prompt
+  const global = readGlobalAgentsFile()
+  if (!global) return prompt
+  return prompt + '\n\n# Global instructions (' + global.path + ')\n\n' + global.content
+}
+
+/** Read the append config and apply it to the prompt (empty append → unchanged). */
+function withAppendPrompt(prompt: string): string {
+  const cfg = readConfig(resolveDataDir())
+  if (!cfg.append.enabled || !cfg.append.prompt.trim()) return prompt
+  return prompt + '\n\n' + cfg.append.prompt
+}
+
+/**
+ * Build the injected system prompt. Injection order per turn:
+ * base prompt → global instructions → append config (the explicitly
+ * configured text wins last). Returns the new systemPrompt, or undefined
+ * when nothing changed.
+ */
+function buildSystemPrompt(event: BeforeAgentStartEvent): { systemPrompt: string } | undefined {
+  const basePrompt = typeof event.systemPrompt === 'string' ? event.systemPrompt : ''
+  const newPrompt = withAppendPrompt(withGlobalInstructions(basePrompt))
+  return newPrompt === event.systemPrompt ? undefined : { systemPrompt: newPrompt }
+}
+
+/** 落盘诊断（pi stderr 经 rpc-client 写入 logs/pi-*.jsonl），不泄露配置内容。 */
+function logHookFailure(err: unknown): void {
+  try {
+    const msg = err instanceof Error ? `${err.name}: ${err.message}` : String(err)
+    process.stderr.write(`[xyz-system-prompt-extension] before_agent_start hook failed: ${msg}\n`)
+  } catch (nestedErr) {
+    // best-effort：stderr 写失败的终极兜底——console 内部吞错不会抛，仍不外泄到 agent loop。
+    console.debug('[xyz-system-prompt-extension] stderr write also failed:', nestedErr)
+  }
+}
+
+export default function (pi: ExtensionAPI): void {
+  pi.on('before_agent_start', (event: BeforeAgentStartEvent) => {
+    try {
+      return buildSystemPrompt(event)
+    } catch (err) {
+      // Never block the agent loop.
+      logHookFailure(err)
+      return undefined
+    }
+  })
+}