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

Start by locating the ModApi command and hook implementations for setInterval, addFlag, beforeToolCall, onStop, and afterToolCall. Trace the existing lifecycle cleanup and hook payloads, then verify how each proposed addition should behave, including the documented toolName and input fields. Done means the requested lifecycle, batching, response, stop-reason, flag, and payload behavior is implemented and covered by the relevant tests.