xitto-kernel 0.1.0

package/src/app/templates/pack.js.tmpl

@@ -0,0 +1,32 @@
+// __NAME__ 領域 agent 的 DomainPack —— 你只需要寫「會什麼、守什麼、像什麼」。
+// runtime（多步循環/串流/權限/沙箱/CLI）由 xitto-kernel 提供，不用碰。
+import { defineDomainPack } from 'xitto-kernel';
+
+export function createPack({ cwd = process.cwd() } = {}) {
+  return defineDomainPack({
+    name: '__NAME__',
+    systemPrompt: '你是 __NAME__ 領域的 agent。在這裡寫行為準則、口吻、流程規矩。',
+
+    // 工具 = 這個 agent 能對世界做的動作。metadata 決定安全行為：
+    //   readOnly:true → 自動放行 ｜ mutating:true → 計劃模式擋、算進 mutatingTools
+    //   sandboxable:true → 走 shell，沙箱開時自動包 Seatbelt（需 params.command）
+    tools: () => [
+      {
+        name: 'example',
+        label: '範例工具',
+        description: '把這個換成你的領域動作（描述要清楚，模型靠它決定何時呼叫）',
+        readOnly: true,
+        parameters: { type: 'object', properties: { input: { type: 'string' } }, required: ['input'] },
+        execute: async (_id, { input }) => ({ content: [{ type: 'text', text: `（範例）收到：${input}` }] }),
+      },
+    ],
+
+    // ── 選填插槽（要更專業時才填；完整說明見 xitto-kernel docs/06）──
+    // contextFiles: ['__NAME__.md'],                  // 啟動載入的領域規範檔
+    // preToolPolicy: {                                // 領域硬規矩（程式擋，不靠模型自律）
+    //   check: (ctx) => { /* 例：做 X 前必先 Y，回 { block:true, reason } 擋下 */ },
+    // },
+    // verify: { run: async () => ({ ok: true }) },    // 每輪收尾自我驗收
+    // permissionPolicy: { sandbox: { enabled: false } },
+  });
+}

package/src/app/templates/package.json.tmpl

@@ -0,0 +1,12 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "xitto-kernel": "file:__KERNEL_PATH__"
+  }
+}

package/src/index.js

@@ -0,0 +1,15 @@
+// xitto-kernel 公開 API。
+export { createKernel } from './kernel/index.js';
+export { loadPack, validatePack } from './kernel/pack-loader.js';
+export { createToolRegistry, deriveMutatingTools, isReadOnly, isMutating, isSandboxable } from './kernel/tool-registry.js';
+export { composeGuards } from './kernel/guard-chain.js';
+
+/**
+ * 小幫手：定義一個 DomainPack（立即驗證，型別提示用）。
+ * @param {import('./types.js').DomainPack} pack
+ * @returns {import('./types.js').DomainPack}
+ */
+export function defineDomainPack(pack) {
+  // 不在此丟錯，交給 createKernel/loadPack 時驗證；此函數僅為可讀性與型別錨點。
+  return pack;
+}

package/src/kernel/agent-loop.js

@@ -0,0 +1,285 @@
+// 自寫 agent loop — 取代 @mariozechner/pi-agent-core 的 Agent，保留 pi-ai 串流(streamFn)。
+// 依 docs/agent-loop-spec.md 對齊契約。關鍵差異：直接在 live this._state.messages 上 push/replace
+// (不像 pi 的 createContextSnapshot 做 slice)，每輪迭代用當下 messages 建 llmContext——
+// 為「回合內真壓縮」(階段二)鋪路。階段一行為先對齊 pi。
+
+const EMPTY_USAGE = {
+  input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+const DEFAULT_MODEL = {
+  id: 'unknown', name: 'unknown', api: 'unknown', provider: 'unknown', baseUrl: '',
+  reasoning: false, input: [], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 0, maxTokens: 0,
+};
+
+// 預設：送給 LLM 的訊息過濾成 user/assistant/toolResult
+function defaultConvertToLlm(messages) {
+  return messages.filter((m) => m.role === 'user' || m.role === 'assistant' || m.role === 'toolResult');
+}
+const errResult = (msg) => ({ content: [{ type: 'text', text: msg }], details: {} });
+
+// steering / followUp 佇列(預設 one-at-a-time)
+class Queue {
+  constructor(mode = 'one-at-a-time') { this.mode = mode; this.items = []; }
+  enqueue(m) { this.items.push(m); }
+  hasItems() { return this.items.length > 0; }
+  drain() {
+    if (this.mode === 'all') { const d = this.items; this.items = []; return d; }
+    return this.items.length ? [this.items.shift()] : [];
+  }
+  clear() { this.items = []; }
+}
+
+export class Agent {
+  constructor(options = {}) {
+    const init = options.initialState || {};
+    let messages = (init.messages || []).slice();
+    let tools = (init.tools || []).slice();
+    this._state = {
+      systemPrompt: init.systemPrompt ?? '',
+      model: init.model ?? DEFAULT_MODEL,
+      thinkingLevel: init.thinkingLevel ?? 'off',
+      get tools() { return tools; },
+      set tools(v) { tools = (v || []).slice(); },
+      get messages() { return messages; },        // getter 回 live 陣列；可直接 push/replace
+      set messages(v) { messages = (v || []).slice(); }, // setter 才 slice(對齊 pi)
+      isStreaming: false,
+      streamingMessage: undefined,
+      errorMessage: undefined,
+    };
+    this.listeners = new Set();
+    this.streamFn = options.streamFn;               // 必傳(xitto 都注入；缺則無法串流)
+    this.getApiKey = options.getApiKey;
+    this.beforeToolCall = options.beforeToolCall;
+    this.afterToolCall = options.afterToolCall;
+    this.onPayload = options.onPayload;
+    this.convertToLlm = options.convertToLlm || defaultConvertToLlm;
+    // 回合內真壓縮鉤子(可選)：async () => info|null。每次串流前呼叫，可就地改寫 this._state.messages。
+    // pi-agent-core 因 snapshot 做不到回合中途壓縮；自寫 loop 直接操作 live messages，故此鉤子有效。
+    this.maybeCompactInTurn = options.maybeCompactInTurn;
+    this.toolExecution = options.toolExecution || 'parallel';
+    this.steeringQueue = new Queue(options.steeringMode);
+    this.followUpQueue = new Queue(options.followUpMode);
+    this.activeRun = undefined;
+  }
+
+  get state() { return this._state; }
+  get signal() { return this.activeRun?.abortController.signal; }
+  subscribe(l) { this.listeners.add(l); return () => this.listeners.delete(l); }
+  steer(m) { this.steeringQueue.enqueue(m); }
+  followUp(m) { this.followUpQueue.enqueue(m); }
+  abort() { this.activeRun?.abortController.abort(); }
+  waitForIdle() { return this.activeRun?.promise ?? Promise.resolve(); }
+  reset() {
+    this._state.messages = [];
+    this._state.isStreaming = false;
+    this._state.streamingMessage = undefined;
+    this._state.errorMessage = undefined;
+    this.steeringQueue.clear();
+    this.followUpQueue.clear();
+  }
+
+  // 依序 await 所有 listener(對齊 pi processEvents)；同時維護 streamingMessage
+  async emit(event) {
+    if (event.type === 'message_start' || event.type === 'message_update') this._state.streamingMessage = event.message;
+    else if (event.type === 'message_end' || event.type === 'agent_end') this._state.streamingMessage = undefined;
+    else if (event.type === 'turn_end' && event.message?.errorMessage) this._state.errorMessage = event.message.errorMessage;
+    const signal = this.activeRun?.abortController.signal;
+    for (const l of this.listeners) await l(event, signal);
+  }
+
+  async prompt(input) {
+    if (this.activeRun) throw new Error('Agent is already processing a prompt. Use steer()/followUp() or wait.');
+    let msgs;
+    if (Array.isArray(input)) msgs = input;
+    else if (typeof input === 'string') msgs = [{ role: 'user', content: [{ type: 'text', text: input }], timestamp: Date.now() }];
+    else msgs = [input];
+    await this.runWithLifecycle((signal) => this.runLoop(msgs, signal));
+  }
+
+  async runWithLifecycle(executor) {
+    const abortController = new AbortController();
+    let resolve = () => {};
+    const promise = new Promise((r) => { resolve = r; });
+    this.activeRun = { promise, resolve, abortController };
+    this._state.isStreaming = true;
+    this._state.streamingMessage = undefined;
+    this._state.errorMessage = undefined;
+    try { await executor(abortController.signal); }
+    catch (err) { await this.handleRunFailure(err, abortController.signal.aborted); }
+    finally {
+      this._state.isStreaming = false;
+      this._state.streamingMessage = undefined;
+      this.activeRun?.resolve();
+      this.activeRun = undefined;
+    }
+  }
+
+  async handleRunFailure(error, aborted) {
+    const m = this._state.model;
+    const failureMessage = {
+      role: 'assistant', content: [{ type: 'text', text: '' }],
+      api: m.api, provider: m.provider, model: m.id, usage: EMPTY_USAGE,
+      stopReason: aborted ? 'aborted' : 'error',
+      errorMessage: error instanceof Error ? error.message : String(error),
+      timestamp: Date.now(),
+    };
+    this._state.messages.push(failureMessage);
+    this._state.errorMessage = failureMessage.errorMessage;
+    await this.emit({ type: 'agent_end', messages: [failureMessage] });
+  }
+
+  // 主迴圈(對齊 spec §6)
+  async runLoop(initialMessages, signal) {
+    const newMessages = [];
+    let pending = initialMessages.slice();
+    let firstTurn = true;
+    while (true) {
+      let hasMoreToolCalls = true;
+      while (hasMoreToolCalls || pending.length) {
+        if (!firstTurn) await this.emit({ type: 'turn_start' }); else firstTurn = false;
+        for (const m of pending) {
+          await this.emit({ type: 'message_start', message: m });
+          await this.emit({ type: 'message_end', message: m });
+          this._state.messages.push(m); newMessages.push(m);
+        }
+        pending = [];
+
+        // abort 守衛：迴圈邊界若已中止，立即走 handleRunFailure(aborted)。
+        // 真實 provider 由 fetch signal 中止串流；此守衛確保 fake/工具觸發的 abort 也確定性收尾。
+        if (signal.aborted) throw new Error('Aborted');
+        const message = await this.streamAssistant(signal);
+        newMessages.push(message);
+        if (message.stopReason === 'error' || message.stopReason === 'aborted') {
+          await this.emit({ type: 'turn_end', message, toolResults: [] });
+          await this.emit({ type: 'agent_end', messages: newMessages });
+          return;
+        }
+        const toolCalls = (message.content || []).filter((c) => c.type === 'toolCall');
+        const toolResults = [];
+        hasMoreToolCalls = false;
+        if (toolCalls.length) {
+          const batch = await this.executeTools(message, toolCalls, signal);
+          for (const r of batch.messages) { this._state.messages.push(r); newMessages.push(r); toolResults.push(r); }
+          hasMoreToolCalls = !batch.terminate;
+        }
+        await this.emit({ type: 'turn_end', message, toolResults });
+        pending = this.steeringQueue.drain();
+      }
+      const followUps = this.followUpQueue.drain();
+      if (followUps.length) { pending = followUps; continue; }
+      break;
+    }
+    await this.emit({ type: 'agent_end', messages: newMessages });
+  }
+
+  // 串流一次 assistant 回應(消費 streamFn 事件)。用 live messages 建 llmContext。
+  async streamAssistant(signal) {
+    // 回合內真壓縮：串流前若上下文逼近上限，就地壓縮 live this._state.messages 後續跑同一回合。
+    // 失敗不阻斷回合(由上層熔斷 fallback 兜底)。這是自寫 loop 相對 pi-agent-core 的核心優勢。
+    if (this.maybeCompactInTurn) {
+      try { await this.maybeCompactInTurn(); } catch { /* 壓縮失敗不應阻斷回合 */ }
+    }
+    const llmMessages = await this.convertToLlm(this._state.messages);
+    const llmContext = { systemPrompt: this._state.systemPrompt, messages: llmMessages, tools: this._state.tools };
+    const apiKey = this.getApiKey ? await this.getApiKey(this._state.model.provider) : undefined;
+    const opts = {
+      model: this._state.model,
+      reasoning: this._state.thinkingLevel === 'off' ? undefined : this._state.thinkingLevel,
+      transport: 'sse',
+      onPayload: this.onPayload,
+      toolExecution: this.toolExecution,
+      apiKey,
+      signal,
+    };
+    const response = await this.streamFn(this._state.model, llmContext, opts);
+
+    let partial = null;
+    let addedPartial = false;
+    const finalize = async () => {
+      const finalMessage = await response.result();
+      if (addedPartial) this._state.messages[this._state.messages.length - 1] = finalMessage;
+      else { this._state.messages.push(finalMessage); await this.emit({ type: 'message_start', message: { ...finalMessage } }); }
+      await this.emit({ type: 'message_end', message: finalMessage });
+      return finalMessage;
+    };
+
+    for await (const event of response) {
+      switch (event.type) {
+        case 'start':
+          partial = event.partial; this._state.messages.push(partial); addedPartial = true;
+          await this.emit({ type: 'message_start', message: { ...partial } });
+          break;
+        case 'text_start': case 'text_delta': case 'text_end':
+        case 'thinking_start': case 'thinking_delta': case 'thinking_end':
+        case 'toolcall_start': case 'toolcall_delta': case 'toolcall_end':
+          if (partial) {
+            partial = event.partial;
+            this._state.messages[this._state.messages.length - 1] = partial;
+            await this.emit({ type: 'message_update', assistantMessageEvent: event, message: { ...partial } });
+          }
+          break;
+        case 'done': case 'error':
+          return finalize();
+        default:
+          break;
+      }
+    }
+    return finalize(); // 串流自然結束(無 done/error)
+  }
+
+  // 執行一批 tool call(sequential：xitto 用；parallel 亦支援)
+  async executeTools(assistantMessage, toolCalls, signal) {
+    const sequential = this.toolExecution === 'sequential'
+      || toolCalls.some((tc) => this._state.tools.find((t) => t.name === tc.name)?.executionMode === 'sequential');
+
+    const runOne = async (toolCall) => {
+      await this.emit({ type: 'tool_execution_start', toolCallId: toolCall.id, toolName: toolCall.name, args: toolCall.arguments });
+      const prep = await this.prepareTool(assistantMessage, toolCall, signal);
+      let result; let isError;
+      if (prep.kind === 'immediate') { result = prep.result; isError = prep.isError; }
+      else {
+        try {
+          result = await prep.tool.execute(toolCall.id, prep.args, signal, (partialResult) => {
+            this.emit({ type: 'tool_execution_update', toolCallId: toolCall.id, toolName: toolCall.name, args: toolCall.arguments, partialResult });
+          });
+          isError = false;
+        } catch (e) { result = errResult(e instanceof Error ? e.message : String(e)); isError = true; }
+      }
+      if (result == null || typeof result !== 'object') result = errResult('工具未回傳有效結果');
+      await this.emit({ type: 'tool_execution_end', toolCallId: toolCall.id, toolName: toolCall.name, result, isError });
+      const trMsg = {
+        role: 'toolResult', toolCallId: toolCall.id, toolName: toolCall.name,
+        content: result.content, details: result.details, isError, timestamp: Date.now(),
+      };
+      return { result, trMsg };
+    };
+
+    let finalized;
+    if (sequential) {
+      finalized = [];
+      for (const tc of toolCalls) finalized.push(await runOne(tc));
+    } else {
+      finalized = await Promise.all(toolCalls.map(runOne));
+    }
+    const terminate = finalized.length > 0 && finalized.every((f) => f.result.terminate === true);
+    return { messages: finalized.map((f) => f.trMsg), terminate };
+  }
+
+  async prepareTool(assistantMessage, toolCall, signal) {
+    const tool = this._state.tools.find((t) => t.name === toolCall.name);
+    if (!tool) return { kind: 'immediate', result: errResult(`Tool ${toolCall.name} not found`), isError: true };
+    try {
+      const args = toolCall.arguments; // pi-ai 已解析；工具層另有 coerceArgs 包裝
+      if (this.beforeToolCall) {
+        const ctx = { assistantMessage, toolCall, args, context: { systemPrompt: this._state.systemPrompt, messages: this._state.messages, tools: this._state.tools } };
+        const before = await this.beforeToolCall(ctx, signal);
+        if (before?.block) return { kind: 'immediate', result: errResult(before.reason || 'Tool execution was blocked'), isError: true };
+      }
+      return { kind: 'prepared', toolCall, tool, args };
+    } catch (e) {
+      return { kind: 'immediate', result: errResult(e instanceof Error ? e.message : String(e)), isError: true };
+    }
+  }
+}

package/src/kernel/compaction.js

@@ -0,0 +1,65 @@
+// 回合內上下文壓縮 — kernel 內建。上下文逼近 model 視窗時，把較舊對話摘要成一段、保留最近數輪，
+// 避免長對話爆窗。對標 xitto-code compaction.js（自足版：以字元/4 粗估 tokens，不依賴 pi-coding-agent）。
+import { completeSimple } from '@mariozechner/pi-ai';
+import { cacheRetentionFor } from './provider.js';
+
+export const DEFAULT_COMPACTION = { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000 };
+
+const asText = (m) => (Array.isArray(m.content) ? m.content.filter((c) => c.type === 'text').map((c) => c.text).join(' ') : String(m?.content || ''));
+const estimateTokens = (m) => { try { return Math.ceil(JSON.stringify(m.content ?? m).length / 4); } catch { return 0; } };
+const totalTokens = (messages) => messages.reduce((s, m) => s + estimateTokens(m), 0);
+const shouldCompact = (tokens, win, s) => s.enabled !== false && tokens > (win || 32000) - (s.reserveTokens || DEFAULT_COMPACTION.reserveTokens);
+
+export function isContextOverThreshold(messages, win, s = DEFAULT_COMPACTION) {
+  return shouldCompact(totalTokens(messages), win, s);
+}
+
+// 切點：從最新往回累加，達 keepRecentTokens 後切在最近的 user 訊息邊界（保留完整輪次）
+export function findCutIndex(messages, keepRecent) {
+  let acc = 0;
+  for (let i = messages.length - 1; i > 0; i--) {
+    acc += estimateTokens(messages[i]);
+    if (acc >= keepRecent && messages[i].role === 'user') return i;
+  }
+  return -1;
+}
+
+async function summarize(older, model, reserveTokens, apiKey) {
+  const text = older.map((m) => `${m.role}: ${asText(m).slice(0, 1500)}`).join('\n').slice(0, 24000);
+  const ctx = {
+    systemPrompt: '把以下對話濃縮成要點摘要：決策、已確認的事實、待辦、檔案/狀態改動，供後續延續。只輸出摘要本身。',
+    messages: [{ role: 'user', content: [{ type: 'text', text }], timestamp: Date.now() }],
+  };
+  const res = await completeSimple(model, ctx, { maxTokens: Math.floor(0.8 * (reserveTokens || 2000)), apiKey, cacheRetention: cacheRetentionFor(model) });
+  if (res.stopReason === 'error') return null;
+  return res.content.filter((c) => c.type === 'text').map((c) => c.text).join('').trim();
+}
+
+// 就地壓縮 agent.state.messages。回 info（壓了）/ null（未達閾值）/ {error}（摘要失敗）。
+export async function maybeCompact(agent, model, apiKey, settings = DEFAULT_COMPACTION) {
+  const messages = agent.state.messages;
+  const tokens = totalTokens(messages);
+  if (!shouldCompact(tokens, model.contextWindow || 32000, settings)) return null;
+  const cut = findCutIndex(messages, settings.keepRecentTokens || DEFAULT_COMPACTION.keepRecentTokens);
+  if (cut <= 0) return null; // 切不動（最近輪次已佔滿）→ 交由上層熔斷
+  const older = messages.slice(0, cut);
+  const recent = messages.slice(cut);
+  let summary;
+  try { summary = await summarize(older, model, settings.reserveTokens, apiKey); } catch { return { error: true }; }
+  if (!summary) return { error: true };
+  const summaryMsg = { role: 'user', content: [{ type: 'text', text: `# 先前對話摘要（已壓縮）\n${summary}` }], timestamp: Date.now() };
+  agent.state.messages = [summaryMsg, ...recent];
+  return { tokensBefore: tokens, tokensAfter: totalTokens(agent.state.messages), summarized: older.length, kept: recent.length };
+}
+
+// 正規化設定 + 安全 clamp（reserve+keepRecent 不逼近視窗，否則永遠切不動）
+export function resolveCompactionSettings(override = {}, contextWindow) {
+  const s = { ...DEFAULT_COMPACTION, ...(override || {}) };
+  const win = (Number.isFinite(contextWindow) && contextWindow > 0) ? contextWindow : null;
+  if (win) {
+    const cap = Math.floor(win * 0.9);
+    if (s.reserveTokens > cap) s.reserveTokens = cap;
+    if (s.reserveTokens + s.keepRecentTokens > cap) s.keepRecentTokens = Math.max(0, cap - s.reserveTokens);
+  }
+  return s;
+}

package/src/kernel/guard-chain.js

@@ -0,0 +1,42 @@
+// beforeToolCall 守衛鏈 — kernel 固定順序，pack 只能在第 3 格插領域守衛。
+// 安全性靠順序保證：pack 無法重排或跳過 permission/hooks（只能「額外多擋」）。
+// 對應 docs/03-kernel-contract.md「C. beforeToolCall 守衛鏈」。
+
+/**
+ * 固定六步順序：
+ *   1. planGuard       計劃模式擋 mutating 工具（kernel）
+ *   2. circuitBreaker  上下文熔斷（kernel）
+ *   3. packPreTool     領域守衛（PACK 唯一插槽，如 read-before-edit）
+ *   4. preToolHooks    使用者 PreToolUse hooks（kernel）
+ *   5. permission      權限/沙箱/危險命令/白名單（kernel）
+ * 任一步回 {block:true,reason} 即短路擋下；全通過回 undefined（放行）。
+ *
+ * 各步驟以注入函數提供（領域無關、可 fake 測試）。未提供的步驟自動略過。
+ *
+ * @param {Object} steps
+ * @param {Function} [steps.planGuard]
+ * @param {Function} [steps.circuitBreaker]
+ * @param {import('../types.js').PreToolPolicy} [steps.packPreTool]
+ * @param {Function} [steps.preToolHooks]
+ * @param {Function} [steps.permission]
+ * @param {import('../types.js').KernelServices} [steps.services]
+ * @returns {(ctx: object) => Promise<import('../types.js').PolicyDecision>}
+ */
+export function composeGuards({ planGuard, circuitBreaker, packPreTool, preToolHooks, permission, services } = {}) {
+  // 固定順序；第 3 格是 pack 的 preToolPolicy.check（注入 services）
+  const chain = [
+    planGuard,
+    circuitBreaker,
+    packPreTool ? (ctx) => packPreTool.check(ctx, services) : null,
+    preToolHooks,
+    permission,
+  ].filter((step) => typeof step === 'function');
+
+  return async function runGuards(ctx) {
+    for (const step of chain) {
+      const decision = await step(ctx);
+      if (decision && decision.block) return decision; // 短路：擋下即停，後續步驟不執行
+    }
+    return undefined; // 全通過 → 放行
+  };
+}

package/src/kernel/hooks.js

@@ -0,0 +1,47 @@
+// PreToolUse / PostToolUse hooks — kernel 內建，由 .xitto-kernel/<pack>/settings.json 驅動。
+// Pre：matched 工具執行前跑命令，非零退出→擋下。Post：matched 工具成功後跑命令，失敗→回灌讓 agent 修正。
+// 對標 xitto-code hooks.js。settings.json: { "hooks": { "PreToolUse": [{matcher, command, timeout}], "PostToolUse": [...] } }
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+const asRules = (x) => (Array.isArray(x) ? x.filter((r) => r && typeof r.command === 'string') : []);
+
+export function loadHooks(settingsPath) {
+  if (!existsSync(settingsPath)) return { PreToolUse: [], PostToolUse: [] };
+  try {
+    const h = (JSON.parse(readFileSync(settingsPath, 'utf8')).hooks) || {};
+    return { PreToolUse: asRules(h.PreToolUse), PostToolUse: asRules(h.PostToolUse) };
+  } catch { return { PreToolUse: [], PostToolUse: [] }; }
+}
+
+const matches = (rule, name) => { try { return new RegExp(rule.matcher || '.*').test(name); } catch { return false; } };
+
+function runRule(rule, cwd) {
+  try {
+    const out = execSync(rule.command, { cwd, encoding: 'utf8', timeout: rule.timeout || 60000, stdio: ['ignore', 'pipe', 'pipe'] });
+    return { ok: true, output: out || '' };
+  } catch (e) {
+    return { ok: false, output: (`${e.stdout || ''}${e.stderr || ''}` || e.message || '').toString() };
+  }
+}
+
+// PreToolUse：任一 matched hook 非零退出 → 回 block（理由含輸出）
+export function runPreToolHooks(hooks, name, cwd) {
+  for (const rule of hooks.PreToolUse) {
+    if (!matches(rule, name)) continue;
+    const r = runRule(rule, cwd);
+    if (!r.ok) return { block: true, reason: `PreToolUse hook 阻止 ${name}：\n${r.output.slice(0, 1000)}` };
+  }
+  return undefined;
+}
+
+// PostToolUse：回失敗清單 [{command, output}]（供呼叫端回灌給 agent）
+export function runPostToolHooks(hooks, name, cwd) {
+  const fails = [];
+  for (const rule of hooks.PostToolUse) {
+    if (!matches(rule, name)) continue;
+    const r = runRule(rule, cwd);
+    if (!r.ok) fails.push({ command: rule.command, output: r.output });
+  }
+  return fails;
+}