Hermit/src/tools/registry.c

#ifndef _DEFAULT_SOURCE
#define _DEFAULT_SOURCE
#endif

#include <stdatomic.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <pthread.h>

#include "cJSON.h"
#include "cst_tools.h"
#include "cst_util.h"
#include "tools_internal.h"

static int run_read_file(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                         cst_tool_result_t *r) {
  return cst_tool_read_file2(ctx, c, r);
}
static int run_write_file(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                          cst_tool_result_t *r) {
  return cst_tool_write_file(ctx->workspace_root, c, r);
}
static int run_apply_patch(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                           cst_tool_result_t *r) {
  return cst_tool_apply_patch(ctx->workspace_root, c, r);
}
static int run_shell(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                     cst_tool_result_t *r) {
  int rc = cst_tool_run_shell_ex(ctx->workspace_root, c, r, ctx->sandbox);
  if (rc == 0 && ctx->compact && r->out) {
    size_t n = 0;
    char *s = cst_shell_compact(r->out, r->out_len, &n);
    if (s) {
      free(r->out);
      r->out = s;
      r->out_len = n;
    }
  }
  return rc;
}

#define S "string"
#define I "integer"
#define B "boolean"
#define NO_DYN NULL, NULL, NULL, NULL, NULL

static const cst_tool_def_t TOOLS[] = {
    {"read_file",
     "Read a text file. Output starts with `path · lines a-b of N` and "
     "prefixes lines with `N|` (not part of the file — never copy it into "
     "edits). Returns up to 2000 lines; continue with the offset it prints.",
     "Read a UTF-8 text file under the workspace.",
     {{"path", S, 1, "file path relative to the workspace"},
      {"offset", I, 0, "first line to return (1-based)"},
      {"limit", I, 0, "maximum number of lines"},
      {"line_numbers", B, 0, "`N|` line prefixes (default true)"}},
     CST_TP_READ, 1, run_read_file, NULL, NO_DYN},
    {"view_image",
     "Show a local image to yourself: PNG, JPEG, GIF, WebP or BMP, checked by "
     "content. The file is copied into the session store and comes back as an "
     "image you can actually see (not as text). Use it for screenshots, "
     "diagrams and UI checks; path resolves like read_file's.",
     NULL,
     {{"path", S, 1, "image file path relative to the workspace"},
      {"detail", S, 0, "low or high (provider hint; default auto)"}},
     CST_TP_READ, 0, cst_tool_view_image, NULL, NO_DYN},
    {"run_shell",
     "Run a non-interactive shell command in the workspace root for builds, "
     "tests, git and other CLIs (stdin is empty; long runs are killed). "
     "Returns stdout+stderr with colors stripped and long output cut to head "
     "+ tail. Prefer read_file/grep/glob/list_dir over cat/grep/find.",
     "Run a shell command in the workspace root (non-interactive, stdin is "
     "empty, killed after a timeout). Returns combined stdout+stderr.",
     {{"cmd", S, 1, "shell command"}},
     CST_TP_SHELL, 1, run_shell, NULL, NO_DYN},
    {"write_file",
     "Create a file or replace a whole file (parent directories are "
     "created). For changes to existing files prefer edit_file.",
     "Create or overwrite a whole file under the workspace (parent "
     "directories are created).",
     {{"path", S, 1, "file path"}, {"content", S, 1, "complete new content"}},
     CST_TP_WRITE, 1, run_write_file, cst_preview_write_file, NO_DYN},
    {"apply_patch",
     "Apply a unified diff (---/+++ headers, @@ -a,b +c,d @@ hunks, 3 "
     "context lines) across one or more files; all hunks apply or nothing "
     "changes. Use for multi-hunk or multi-file edits.",
     "Apply a unified diff (---/+++ headers, @@ -a,b +c,d @@ hunks with "
     "context lines) to one or more files. All hunks must apply or nothing "
     "changes.",
     {{"patch", S, 1, "unified diff text"}},
     CST_TP_WRITE, 1, run_apply_patch, cst_preview_apply_patch, NO_DYN},
    {"edit_file",
     "Replace an exact snippet in a file — the default for small edits. "
     "old_string must match byte-for-byte (indentation included, without "
     "read_file's `N|` prefixes) and be unique unless replace_all=true.",
     NULL,
     {{"path", S, 1, "file path"},
      {"old_string", S, 1, "exact text to replace"},
      {"new_string", S, 1, "replacement text"},
      {"replace_all", B, 0, "replace every occurrence"}},
     CST_TP_WRITE, 0, cst_tool_edit_file, cst_preview_edit_file, NO_DYN},
    {"list_dir",
     "Show a directory tree (dirs end with /, files show sizes, dirs at the "
     "depth limit show entry counts). Skips .git, node_modules and "
     ".gitignore'd paths.",
     NULL,
     {{"path", S, 0, "directory (default: workspace root)"},
      {"depth", I, 0, "levels to descend (default 2, max 6)"}},
     CST_TP_READ, 0, cst_tool_list_dir, NULL, NO_DYN},
    {"glob",
     "Find files by name, newest first (max 200). `*`/`?` stay within one "
     "path segment, `**` spans directories (`src/**/*.c`); a pattern without "
     "/ matches file names at any depth.",
     NULL,
     {{"pattern", S, 1, "glob relative to path"},
      {"path", S, 0, "directory to search (default: workspace root)"}},
     CST_TP_READ, 0, cst_tool_glob, NULL, NO_DYN},
    {"grep",
     "Search file contents with an extended regex (\\d \\w \\s work). "
     "Results are grouped by file as `line:text` under each path, with a "
     "total count first; narrow with path/glob when it is cut.",
     NULL,
     {{"pattern", S, 1, "extended regular expression"},
      {"path", S, 0, "file or directory (default: workspace root)"},
      {"glob", S, 0, "only files whose name matches, e.g. *.c"},
      {"ignore_case", B, 0, "case-insensitive"},
      {"context", I, 0, "lines of context around each match (max 5)"}},
     CST_TP_READ, 0, cst_tool_grep, NULL, NO_DYN},
    {"delete_file",
     "Delete one file (not directories). Undoable with /undo.",
     NULL,
     {{"path", S, 1, "file path"}},
     CST_TP_WRITE, 0, cst_tool_delete_file, cst_preview_delete_file, NO_DYN},
    {"move_file",
     "Move or rename a file; fails if the destination exists.",
     NULL,
     {{"from", S, 1, "existing file"}, {"to", S, 1, "new path"}},
     CST_TP_WRITE, 0, cst_tool_move_file, cst_preview_move_file, NO_DYN},
    {"todo_write",
     "Replace your task list for work with 3+ steps; keep exactly one item "
     "in progress. One item per line: `[ ] todo`, `[~] in progress`, `[x] "
     "done`.",
     NULL,
     {{"todos", S, 1, "the whole list, one item per line"}},
     CST_TP_META, 0, cst_tool_todo_write, NULL, NO_DYN},
    {"web_fetch",
     "Fetch an http(s) URL (docs, issues, APIs) and return its text; HTML "
     "is reduced to readable text.",
     NULL,
     {{"url", S, 1, "http:// or https:// URL"},
      {"max_bytes", I, 0, "maximum bytes to return (default 65536)"}},
     CST_TP_NET, 0, cst_tool_web_fetch, NULL, NO_DYN},
    {"ask_user",
     "Ask the user and wait for the answer. Only for decisions that are "
     "truly theirs (preferences, credentials, destructive choices).",
     NULL,
     {{"question", S, 1, "the question"},
      {"options", S, 0, "suggested answers, one per line"}},
     CST_TP_ASK, 0, cst_tool_ask_user, NULL, NO_DYN},
};
#define NTOOLS ((int)(sizeof(TOOLS) / sizeof(TOOLS[0])))

#undef S
#undef I
#undef B
#undef NO_DYN

int cst_tool_profile_parse(const char *s, int *out) {
  if (!s || !out)
    return -1;
  if (strcmp(s, "default") == 0 || strcmp(s, "full") == 0) {
    *out = CST_TOOLS_DEFAULT;
    return 0;
  }
  if (strcmp(s, "minimal") == 0) {
    *out = CST_TOOLS_MINIMAL;
    return 0;
  }
  return -1;
}

const char *cst_tool_profile_name(int p) {
  return p == CST_TOOLS_MINIMAL ? "minimal" : "default";
}

/* Dynamic tools: published append-only into a fixed table so readers on
 * other threads never see a half-built entry. */
#define DYN_MAX 256
static cst_tool_def_t *g_dyn[DYN_MAX];
static atomic_int g_ndyn;
static pthread_mutex_t g_dyn_mu = PTHREAD_MUTEX_INITIALIZER;
#define DYN_LOCK() pthread_mutex_lock(&g_dyn_mu)
#define DYN_UNLOCK() pthread_mutex_unlock(&g_dyn_mu)

int cst_tool_count(void) { return NTOOLS + atomic_load(&g_ndyn); }

const cst_tool_def_t *cst_tool_at(int i) {
  if (i < 0)
    return NULL;
  if (i < NTOOLS)
    return &TOOLS[i];
  i -= NTOOLS;
  return i < atomic_load(&g_ndyn) ? g_dyn[i] : NULL;
}

int cst_tool_index(const char *name) {
  if (!name)
    return -1;
  int n = cst_tool_count();
  for (int i = 0; i < n; i++) {
    const cst_tool_def_t *t = cst_tool_at(i);
    if (t && strcmp(t->name, name) == 0)
      return i;
  }
  return -1;
}

const cst_tool_def_t *cst_tool_find(const char *name) {
  return cst_tool_at(cst_tool_index(name));
}

int cst_tool_known(const char *name) { return cst_tool_find(name) != NULL; }

void cst_tool_sanitize_name(const char *in, char *out, size_t out_sz) {
  size_t o = 0;
  for (size_t i = 0; in && in[i] && o + 1 < out_sz && o < 63; i++) {
    char c = in[i];
    int ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
             (c >= '0' && c <= '9') || c == '_' || c == '-';
    out[o++] = ok ? c : '_';
  }
  if (out_sz)
    out[o] = 0;
}

static char *dup_or_null(const char *s) { return s ? strdup(s) : NULL; }

static void dyn_free(cst_tool_def_t *t) {
  if (!t)
    return;
  free((char *)t->name);
  free((char *)t->desc);
  free((char *)t->schema_json);
  free((char *)t->owner);
  free(t);
}

int cst_tool_register(const cst_tool_def_t *def) {
  if (!def || !def->name || !def->name[0] || (!def->run && !def->run_ex))
    return -1;
  DYN_LOCK();
  int rc = -1;
  int n = atomic_load(&g_ndyn);
  if (n < DYN_MAX && cst_tool_index(def->name) < 0) {
    cst_tool_def_t *t = calloc(1, sizeof(*t));
    if (t) {
      *t = *def;
      t->min_desc = NULL;
      t->minimal = 0;
      t->name = dup_or_null(def->name);
      t->desc = dup_or_null(def->desc ? def->desc : "");
      t->schema_json = dup_or_null(def->schema_json);
      t->owner = dup_or_null(def->owner);
      if (t->name && t->desc) {
        g_dyn[n] = t;
        atomic_store(&g_ndyn, n + 1);
        rc = 0;
      } else {
        dyn_free(t);
      }
    }
  }
  DYN_UNLOCK();
  return rc;
}

int cst_tool_unregister_owner(const char *owner) {
  if (!owner)
    return 0;
  DYN_LOCK();
  int n = atomic_load(&g_ndyn), k = 0, removed = 0;
  for (int i = 0; i < n; i++) {
    if (g_dyn[i]->owner && strcmp(g_dyn[i]->owner, owner) == 0) {
      dyn_free(g_dyn[i]);
      removed++;
    } else {
      g_dyn[k++] = g_dyn[i];
    }
  }
  for (int i = k; i < n; i++)
    g_dyn[i] = NULL;
  atomic_store(&g_ndyn, k);
  DYN_UNLOCK();
  return removed;
}

int cst_tool_disabled(const cst_agent_config_t *cfg, const char *name) {
  if (!cfg || !name || !cfg->tools_off[0])
    return 0;
  char key[CTL_MAX_NAME + 2];
  snprintf(key, sizeof(key), ",%s,", name);
  return strstr(cfg->tools_off, key) != NULL;
}

void cst_tool_set_disabled(cst_agent_config_t *cfg, const char *name,
                           int off) {
  if (!cfg || !name || !name[0])
    return;
  char key[CTL_MAX_NAME + 2];
  snprintf(key, sizeof(key), ",%s,", name);
  char *hit = strstr(cfg->tools_off, key);
  if (off && !hit) {
    size_t n = strlen(cfg->tools_off);
    if (n == 0)
      snprintf(cfg->tools_off, sizeof(cfg->tools_off), "%s", key);
    else if (n + strlen(key) < sizeof(cfg->tools_off))
      snprintf(cfg->tools_off + n, sizeof(cfg->tools_off) - n, "%s", key + 1);
  } else if (!off && hit) {
    /* drop ",name" keeping the trailing comma */
    size_t kl = strlen(key) - 1;
    memmove(hit, hit + kl, strlen(hit + kl) + 1);
    if (strcmp(cfg->tools_off, ",") == 0)
      cfg->tools_off[0] = 0;
  }
}

int cst_tool_is_shell(const char *name) {
  const cst_tool_def_t *t = cst_tool_find(name);
  return t && t->perm == CST_TP_SHELL;
}

int cst_tool_is_write(const char *name) {
  const cst_tool_def_t *t = cst_tool_find(name);
  return t && t->perm == CST_TP_WRITE;
}

int cst_tool_active(const cst_agent_config_t *cfg, const cst_tool_def_t *t) {
  if (!t)
    return 0;
  if (!cfg)
    return 1;
  if (cfg->tool_profile == CST_TOOLS_MINIMAL && !t->minimal)
    return 0;
  /* plan_mode is enforced when a call runs, so tools[] stays the same */
  if (cfg->read_only && (t->perm == CST_TP_WRITE || t->perm == CST_TP_SHELL))
    return 0;
  if (cfg->depth > 0 && strcmp(t->name, "task") == 0)
    return 0;
  if (cfg->tools_only[0]) {
    char key[CTL_MAX_NAME + 2];
    snprintf(key, sizeof(key), ",%s,", t->name);
    if (!strstr(cfg->tools_only, key))
      return 0;
  }
  return !cst_tool_disabled(cfg, t->name);
}

/* Parsed schema of a dynamic tool, or NULL. */
static cJSON *tool_schema(const cst_tool_def_t *t) {
  if (!t->schema_json)
    return NULL;
  cJSON *s = cJSON_Parse(t->schema_json);
  if (s && !cJSON_IsObject(s)) {
    cJSON_Delete(s);
    return NULL;
  }
  return s;
}

static int schema_required(const cJSON *schema, const char *key) {
  const cJSON *req = cJSON_GetObjectItemCaseSensitive(schema, "required");
  const cJSON *it = NULL;
  cJSON_ArrayForEach(it, req) {
    if (cJSON_IsString(it) && strcmp(it->valuestring, key) == 0)
      return 1;
  }
  return 0;
}

char *cst_tool_args_json(const cst_tool_def_t *t, const ctl_tool_call_t *c) {
  cJSON *schema = t ? tool_schema(t) : NULL;
  const cJSON *props = cJSON_GetObjectItemCaseSensitive(schema, "properties");
  cJSON *o = cJSON_CreateObject();
  for (int i = 0; i < c->nargs; i++) {
    const char *k = c->args[i].key;
    const char *v = c->args[i].value ? c->args[i].value : "";
    const char *type = NULL;
    const cJSON *pp = cJSON_GetObjectItemCaseSensitive(props, k);
    const cJSON *ty = cJSON_GetObjectItemCaseSensitive(pp, "type");
    if (cJSON_IsString(ty))
      type = ty->valuestring;
    for (int j = 0; !type && t && j < CST_TOOL_MAX_PARAMS && t->params[j].name;
         j++) {
      if (strcmp(t->params[j].name, k) == 0)
        type = t->params[j].type;
    }
    cJSON *val = NULL;
    if (!type || strcmp(type, "string") != 0) {
      const char *p = v;
      while (*p == ' ' || *p == '\n')
        p++;
      /* untyped: only structured values are taken as JSON */
      if (type || *p == '{' || *p == '[')
        val = cJSON_Parse(v);
      if (val && type && strcmp(type, "integer") == 0 && !cJSON_IsNumber(val)) {
        cJSON_Delete(val);
        val = NULL;
      }
    }
    if (!val)
      val = cJSON_CreateString(v);
    cJSON_AddItemToObject(o, k, val);
  }
  char *s = cJSON_PrintUnformatted(o);
  cJSON_Delete(o);
  cJSON_Delete(schema);
  return s;
}

static int is_minimal(const cst_agent_config_t *cfg) {
  return cfg && cfg->tool_profile == CST_TOOLS_MINIMAL;
}

static int is_external(const cst_tool_def_t *t) {
  return t->owner && strncmp(t->owner, "builtin:", 8) != 0;
}

static int by_name(const void *x, const void *y) {
  const cst_tool_def_t *a = *(const cst_tool_def_t *const *)x;
  const cst_tool_def_t *b = *(const cst_tool_def_t *const *)y;
  return strcmp(a->name, b->name);
}

void *cst_tools_schema_cfg(const cst_agent_config_t *cfg) {
  cJSON *arr = cJSON_CreateArray();
  if (!arr)
    return NULL;
  int legacy = is_minimal(cfg);
  int n = cst_tool_count();
  /* Built-ins in registry order, then plugin/MCP tools by name: servers
   * finish starting in any order, and tools[] is part of the cached prefix. */
  const cst_tool_def_t **order = calloc((size_t)(n ? n : 1), sizeof(*order));
  if (!order) {
    cJSON_Delete(arr);
    return NULL;
  }
  int nb = 0, no = 0;
  for (int i = 0; i < n; i++) {
    const cst_tool_def_t *t = cst_tool_at(i);
    if (t && cst_tool_active(cfg, t) && !is_external(t))
      order[no++] = t;
  }
  nb = no;
  for (int i = 0; i < n; i++) {
    const cst_tool_def_t *t = cst_tool_at(i);
    if (t && cst_tool_active(cfg, t) && is_external(t))
      order[no++] = t;
  }
  qsort(order + nb, (size_t)(no - nb), sizeof(*order), by_name);
  for (int i = 0; i < no; i++) {
    const cst_tool_def_t *t = order[i];
    cJSON *tool = cJSON_CreateObject();
    cJSON_AddStringToObject(tool, "type", "function");
    cJSON *fn = cJSON_AddObjectToObject(tool, "function");
    cJSON_AddStringToObject(fn, "name", t->name);
    cJSON_AddStringToObject(fn, "description",
                            legacy && t->min_desc ? t->min_desc : t->desc);
    cJSON *schema = tool_schema(t);
    if (t->schema_json) {
      if (!schema) {
        schema = cJSON_CreateObject();
        cJSON_AddStringToObject(schema, "type", "object");
        cJSON_AddObjectToObject(schema, "properties");
      }
      cJSON_AddItemToObject(fn, "parameters", schema);
      cJSON_AddItemToArray(arr, tool);
      continue;
    }
    cJSON *params = cJSON_AddObjectToObject(fn, "parameters");
    cJSON_AddStringToObject(params, "type", "object");
    cJSON *props = cJSON_AddObjectToObject(params, "properties");
    cJSON *req = cJSON_AddArrayToObject(params, "required");
    for (int k = 0; k < CST_TOOL_MAX_PARAMS && t->params[k].name; k++) {
      const cst_tool_param_t *pp = &t->params[k];
      if (legacy && !pp->required)
        continue;
      cJSON *p = cJSON_AddObjectToObject(props, pp->name);
      cJSON_AddStringToObject(p, "type", pp->type);
      if (!legacy && pp->desc)
        cJSON_AddStringToObject(p, "description", pp->desc);
      if (pp->required)
        cJSON_AddItemToArray(req, cJSON_CreateString(pp->name));
    }
    cJSON_AddItemToArray(arr, tool);
  }
  free(order);
  return arr;
}

void *cst_tools_schema(void) { return cst_tools_schema_cfg(NULL); }

char *cst_tools_prompt(const cst_agent_config_t *cfg) {
  cst_buf_t b = {0};
  cst_buf_puts(&b, "Tools:\n");
  int n = cst_tool_count();
  for (int i = 0; i < n; i++) {
    const cst_tool_def_t *t = cst_tool_at(i);
    if (!t || !cst_tool_active(cfg, t))
      continue;
    cst_buf_printf(&b, "- %s(", t->name);
    if (t->schema_json) {
      cJSON *schema = tool_schema(t);
      const cJSON *props =
          cJSON_GetObjectItemCaseSensitive(schema, "properties");
      const cJSON *it = NULL;
      int k = 0;
      cJSON_ArrayForEach(it, props) {
        cst_buf_printf(&b, "%s%s%s", k++ ? ", " : "", it->string,
                       schema_required(schema, it->string) ? "" : "?");
      }
      cJSON_Delete(schema);
    }
    for (int k = 0; !t->schema_json && k < CST_TOOL_MAX_PARAMS &&
                    t->params[k].name;
         k++)
      cst_buf_printf(&b, "%s%s%s", k ? ", " : "", t->params[k].name,
                     t->params[k].required ? "" : "?");
    /* first line of a long description is enough in the prompt */
    const char *d = t->desc ? t->desc : "";
    size_t dl = strlen(d);
    if (t->schema_json && dl > 300)
      dl = cst_utf8_floor(d, 300);
    cst_buf_printf(&b, "): %.*s%s\n", (int)dl, d,
                   dl < strlen(d) ? "…" : "");
  }
  return cst_buf_steal(&b);
}

char *cst_tools_names(const cst_agent_config_t *cfg) {
  cst_buf_t b = {0};
  int n = 0, cnt = cst_tool_count();
  for (int i = 0; i < cnt; i++) {
    const cst_tool_def_t *t = cst_tool_at(i);
    if (t && cst_tool_active(cfg, t))
      cst_buf_printf(&b, "%s%s", n++ ? ", " : "", t->name);
  }
  if (!b.buf)
    cst_buf_puts(&b, "");
  return cst_buf_steal(&b);
}

static int parse_int_value(const char *v, long *out) {
  while (*v == ' ' || *v == '"' || *v == '\'')
    v++;
  char *end = NULL;
  long x = strtol(v, &end, 10);
  if (end == v)
    return -1;
  while (*end == ' ' || *end == '"' || *end == '\'' || *end == '\n')
    end++;
  if (*end)
    return -1;
  *out = x;
  return 0;
}

int cst_tool_validate(const cst_tool_def_t *t, const ctl_tool_call_t *call,
                      char *err, size_t err_sz) {
  if (t->schema_json) {
    cJSON *schema = tool_schema(t);
    const cJSON *req = cJSON_GetObjectItemCaseSensitive(schema, "required");
    const cJSON *it = NULL;
    int rc = 0;
    cJSON_ArrayForEach(it, req) {
      if (cJSON_IsString(it) && !tool_arg(call, it->valuestring)) {
        snprintf(err, err_sz, "error: %s needs argument \"%s\"", t->name,
                 it->valuestring);
        rc = -1;
        break;
      }
    }
    cJSON_Delete(schema);
    return rc;
  }
  for (int k = 0; k < CST_TOOL_MAX_PARAMS && t->params[k].name; k++) {
    const cst_tool_param_t *p = &t->params[k];
    const char *v = tool_arg(call, p->name);
    if (!v && strcmp(t->name, "run_shell") == 0)
      v = tool_arg(call, "command");
    if (!v) {
      if (p->required) {
        snprintf(err, err_sz, "error: %s needs argument \"%s\"", t->name,
                 p->name);
        return -1;
      }
      continue;
    }
    long x;
    if (strcmp(p->type, "integer") == 0 && v[0] && parse_int_value(v, &x)) {
      snprintf(err, err_sz, "error: %s: argument \"%s\" must be an integer",
               t->name, p->name);
      return -1;
    }
  }
  return 0;
}

int cst_tool_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call,
                 cst_tool_result_t *r) {
  if (!ctx || !call || !r)
    return -1;
  memset(r, 0, sizeof(*r));
  const cst_tool_def_t *t = cst_tool_find(call->name);
  if (!t)
    return tool_set_resultf(r, 1, "error: unknown tool: %.64s", call->name);
  char err[256];
  if (cst_tool_validate(t, call, err, sizeof(err)) != 0)
    return tool_set_result(r, err, 1);
  if (t->run_ex)
    return t->run_ex(ctx, call, r, t->ud);
  return t->run(ctx, call, r);
}

int cst_tool_preview(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call,
                     char **out) {
  *out = NULL;
  const cst_tool_def_t *t = cst_tool_find(call->name);
  if (!t || !t->preview)
    return -1;
  char err[256];
  if (cst_tool_validate(t, call, err, sizeof(err)) != 0) {
    *out = strdup(err);
    return -1;
  }
  return t->preview(ctx, call, out);
}

int cst_tool_dispatch(const char *workspace_root, const ctl_tool_call_t *call,
                      cst_tool_result_t *r) {
  cst_tool_ctx_t ctx = {0};
  ctx.workspace_root = workspace_root;
  return cst_tool_run(&ctx, call, r);
}