/**
 * Runtime promotion for eval/wait.
 *
 * A bounded guidance block appended to the system prompt (via
 * `before_agent_start`) so models reach for the code-mode tools at the right
 * moments. Toggleable through the `promotion.enabled` setting (default true),
 * surfaced in the settings schema and the /codemode menu.
 */

/** The bounded guidance block; keep it a few lines and pointer-only. */
export function promotionBlock(toolSnapshotVersion?: string): string {
  return [
    "[pi-codemode] Code-mode tools are active:",
    ...(toolSnapshotVersion === undefined
      ? []
      : [
          `- Tool snapshot v${toolSnapshotVersion} is frozen for this session; use ALL_TOOLS or tool_schema() inside a cell.`,
        ]),
    "- eval: run ONE incremental code cell in a persistent kernel; batch any step needing more than one tool call into a single cell.",
    "- Use parallel(thunks) for fan-out research and computation; one eval call is one logical step.",
    "- wait: resume a detached eval cell (cell_id) for new output; long cells detach and notify when complete.",
    "- Large payloads: pass strings: {key: ...} and read π.key inside the cell.",
    "- State persists across cells; re-run setup only after reset or a kernel crash.",
  ].join("\n");
}