ModApi: Hooks & Lifecycle

Feature Description

Disclaimer: This message was synthesized by an AI from a long, unstructured Markdown file of notes accumulated while building real mods. Use cases have been kept intentionally simple and generic. If anything seems off or incoherent, feel free to ask for clarification.

1. cmd.setInterval() — periodic refresh with automatic cleanup

Problem: Mods that need periodic refresh each implement their own setInterval / clearInterval tied to onSessionStart / onSessionEnd. It's identical boilerplate in every mod.

Use case: Any mod with a periodic refresh cycle should register it in one line with cleanup handled automatically at session end.

cmd.setInterval(() => {
  cmd.ui.refreshWidgets();
}, 1000); // auto-cleaned at session end

---

2. cmd.setFlag() — mutable flags at runtime

Problem: Flags (cmd.addFlag) cannot be updated at runtime. A mod that exposes a configurable option via a slash command must use a closure variable — not a real flag.

Use case: A mod configurable via /my-mod option value should update a real flag value live, so the next refresh picks it up immediately without a restart.

cmd.setFlag('mode', 'compact');

---

3. beforeToolBatch — view the full batch before execution

Problem: beforeToolCall fires per tool call. There's no way to analyze the full set of planned actions before any of them execute.

Use case: A safety-oriented mod that wants to warn the user when many actions are planned at once needs to see the full batch upfront.

cmd.hooks({
  beforeToolBatch: async ({ toolCalls }) => {
    if (toolCalls.length > 5) {
      const ok = await cmd.ui.confirm({ title: `${toolCalls.length} actions planned. Continue?` });
      if (!ok) return { block: true };
    }
  }
});

---

4. onStop with a granular stopReason

Problem: onStop fires when the model stops naturally, but also when an injected turn (from a stop_hook) ends. Distinguishing the two requires a custom state machine in every mod that needs it.

Use case: A mod that only wants to react to a natural end-of-run needs to filter on stopReason === 'end_turn' without building a two-phase state machine.

cmd.hooks({
  onStop: async ({ stopReason }) => {
    if (stopReason !== 'end_turn') return;
    // react only to natural run end
  }
});

---

5. afterModelResponse — hook on the model's final text

Problem: There's no way to inspect or modify the model's response before it's shown to the user.

Use case: A mod that monitors model output for specific patterns needs to read — and optionally annotate — the response before it reaches the feed.

cmd.hooks({
  afterModelResponse: async ({ text }) => {
    if (someCondition(text)) {
      return { text: "⚠️ Note:\n\n" + text };
    }
  }
});

---

6. afterToolCall — reliable toolName and input in hook payload

Problem: The docs say afterToolCall receives {toolCallId, toolName, input, result}, but in practice toolName and input don't seem consistently present. Mods end up guessing field names (input.file_path || input.path || input.file), which is fragile.

Use case: Any mod reacting to specific tool calls needs to reliably branch on toolName and read input without heuristics. This may just be a docs/typings issue — but it should be verified and guaranteed.

Use Case

No response

Additional Context

No response

How important is this to you?

None

首先定位 ModApi 中針對 setInterval、addFlag、beforeToolCall、onStop 和 afterToolCall 的命令與 hook 實作。追蹤現有的生命週期清理和 hook payload，然後確認每項提議的新增功能應如何運作，包括文件中說明的 toolName 和 input 欄位。完成的標準是：所要求的生命週期、批次處理、回應、停止原因、flag 和 payload 行為都已實作，並由相關測試涵蓋。