Usability pass: tool registry, TUI polish, saved keys and settings

Tools
- Table-driven tool registry with permission classes and default/minimal
  profiles; new tools: edit_file, list_dir, glob, grep, delete_file,
  move_file, todo_write, web_fetch, ask_user (plus read_file paging).
- Built-in Myers diff; write tools return unified diffs.
- Persistent permission rules (.agent/permissions.json), per-turn undo
  snapshots (.agent/undo), AGENTS.md project notes, auto-compact at 80%
  of the model context, cancellable run_shell with process-group kill.

TUI
- Table-driven slash commands: /provider /key /effort /status /tools
  /permissions /yolo /undo /retry /diff /export /copy /rename /delete
  /init /max-steps /todo, with / and @ completion.
- Permission modal with diff and prefix rules, ask_user modal, todo
  panel, header with model/effort/context, bracketed paste, line editing,
  wide-char cursor, NO_COLOR and ASCII fallback; Esc never quits.

Startup and configuration
- API keys are entered in the TUI (hidden) and saved per provider in
  <config>/credentials (0600); env variables are only a fallback.
- Last provider, per-provider model and reasoning effort are remembered
  in <config>/settings.json; --effort/-e and /effort send
  reasoning_effort (low|medium|high|max) to models that accept it.
- DeepSeek preset uses deepseek-flash / deepseek-v4-pro.
- Session flags --new/--continue/--resume/--list-sessions, --yolo,
  --confirm.

Compatibility and tests
- ncurses detection, macOS/Homebrew support, make install, XDG config
  dir, POSIX cleanups; Gitea CI (gcc/clang/asan/musl/macOS).
- Unit tests for diff, fs tools, registry, undo/perms and config;
  e2e fixtures multi_file_refactor and ask_or_todo; vendored cJSON.

src/agent_store.c

@@ -1,5 +1,8 @@
+#ifndef _DEFAULT_SOURCE
 #define _DEFAULT_SOURCE
+#endif
 
+#include "cJSON.h"
 #include "cst_agent.h"
 #include "os_compat.h"
 
@@ -38,6 +41,16 @@ int cst_agent_store_ensure(const char *workspace) {
     return -1;
   if (os_mkdir(sess, 0755) != 0)
     return -1;
+  /* keep sessions, undo snapshots and exports out of git */
+  char gi[OS_PATH_MAX];
+  if (os_path_join(gi, sizeof(gi), base, ".gitignore") == 0 &&
+      OS_ACCESS(gi, OS_F_OK) != 0) {
+    FILE *fp = fopen(gi, "w");
+    if (fp) {
+      fputs("*\n", fp);
+      fclose(fp);
+    }
+  }
   return 0;
 }
 
@@ -187,3 +200,122 @@ int cst_agent_store_list(const char *workspace, char ids[][128], int max_ids) {
   free(ents);
   return out_n;
 }
+
+static int side_path(const char *workspace, const char *id, const char *ext,
+                     char *out, size_t out_sz) {
+  char dir[OS_PATH_MAX], leaf[192];
+  if (!id || !id[0] || strchr(id, '/') || strchr(id, '\\') ||
+      cst_agent_store_dir(workspace, dir, sizeof(dir)) != 0)
+    return -1;
+  snprintf(leaf, sizeof(leaf), "%s%s", id, ext);
+  return os_path_join(out, out_sz, dir, leaf);
+}
+
+int cst_agent_store_title_set(const char *workspace, const char *id,
+                              const char *title) {
+  char p[OS_PATH_MAX];
+  if (side_path(workspace, id, ".title", p, sizeof(p)) != 0)
+    return -1;
+  if (!title || !title[0])
+    return remove(p) == 0 || errno == ENOENT ? 0 : -1;
+  FILE *fp = fopen(p, "w");
+  if (!fp)
+    return -1;
+  for (const char *c = title; *c; c++)
+    fputc(*c == '\n' || *c == '\r' ? ' ' : *c, fp);
+  fputc('\n', fp);
+  return fclose(fp) == 0 ? 0 : -1;
+}
+
+/* Cut to n bytes without splitting a UTF-8 sequence; newlines → spaces. */
+static void clip_line(char *dst, size_t n, const char *src) {
+  size_t i = 0;
+  while (src[i] && i + 1 < n) {
+    dst[i] = (src[i] == '\n' || src[i] == '\r' || src[i] == '\t') ? ' '
+                                                                 : src[i];
+    i++;
+  }
+  while (i > 0 && src[i] && ((unsigned char)src[i] & 0xC0) == 0x80)
+    i--;
+  dst[i] = 0;
+}
+
+int cst_agent_store_info(const char *workspace, const char *id,
+                         cst_session_info_t *info) {
+  if (!info)
+    return -1;
+  memset(info, 0, sizeof(*info));
+  snprintf(info->id, sizeof(info->id), "%s", id ? id : "");
+  char p[OS_PATH_MAX];
+  if (side_path(workspace, id, ".jsonl", p, sizeof(p)) != 0)
+    return -1;
+  struct stat st;
+  if (stat(p, &st) != 0)
+    return -1;
+  info->mtime = (long long)st.st_mtime;
+  char tp[OS_PATH_MAX];
+  if (side_path(workspace, id, ".title", tp, sizeof(tp)) == 0) {
+    FILE *tf = fopen(tp, "r");
+    if (tf) {
+      if (fgets(info->title, sizeof(info->title), tf)) {
+        size_t n = strlen(info->title);
+        while (n && (info->title[n - 1] == '\n' || info->title[n - 1] == '\r'))
+          info->title[--n] = 0;
+      }
+      fclose(tf);
+    }
+  }
+  FILE *fp = fopen(p, "r");
+  if (!fp)
+    return 0;
+  size_t cap = 1 << 16;
+  char *line = malloc(cap);
+  int have_first = 0;
+  while (line && fgets(line, (int)cap, fp)) {
+    size_t n = strlen(line);
+    if (n == cap - 1 && line[n - 1] != '\n') {
+      /* very long line: skip the rest, it is not the first user line */
+      int ch;
+      while ((ch = fgetc(fp)) != EOF && ch != '\n')
+        ;
+      info->messages++;
+      continue;
+    }
+    if (n <= 1)
+      continue;
+    info->messages++;
+    if (have_first)
+      continue;
+    cJSON *o = cJSON_Parse(line);
+    const cJSON *r = cJSON_GetObjectItemCaseSensitive(o, "role");
+    const cJSON *c = cJSON_GetObjectItemCaseSensitive(o, "content");
+    if (cJSON_IsString(r) && strcmp(r->valuestring, "user") == 0 &&
+        cJSON_IsString(c) && c->valuestring[0]) {
+      clip_line(info->first_user, sizeof(info->first_user), c->valuestring);
+      have_first = 1;
+    }
+    cJSON_Delete(o);
+  }
+  free(line);
+  fclose(fp);
+  return 0;
+}
+
+int cst_agent_store_delete(const char *workspace, const char *id) {
+  char p[OS_PATH_MAX];
+  if (side_path(workspace, id, ".jsonl", p, sizeof(p)) != 0)
+    return -1;
+  if (remove(p) != 0)
+    return -1;
+  if (side_path(workspace, id, ".title", p, sizeof(p)) == 0)
+    remove(p);
+  char cur[128];
+  if (cst_agent_store_get_current(workspace, cur, sizeof(cur)) == 0 &&
+      strcmp(cur, id) == 0) {
+    char dir[OS_PATH_MAX];
+    if (cst_agent_store_dir(workspace, dir, sizeof(dir)) == 0 &&
+        os_path_join(p, sizeof(p), dir, "CURRENT") == 0)
+      remove(p);
+  }
+  return 0;
+}

src/creds.c

@@ -1,4 +1,6 @@
+#ifndef _DEFAULT_SOURCE
 #define _DEFAULT_SOURCE
+#endif
 
 #include "cst_agent.h"
 #include "os_compat.h"
@@ -11,10 +13,13 @@
 #ifdef _WIN32
 #include <io.h>
 #else
+#include <fcntl.h>
+#include <termios.h>
 #include <unistd.h>
 #endif
 
-/* Config dir via os_compat: ~/.config/cst-agent or %APPDATA%\cst-agent */
+/* Config dir via os_compat: $XDG_CONFIG_HOME/cst-agent (~/.config/cst-agent)
+ * or %APPDATA%\cst-agent */
 
 static int credentials_path(char *out, size_t n) {
   char dir[OS_PATH_MAX];
@@ -23,8 +28,24 @@ static int credentials_path(char *out, size_t n) {
   return os_path_join(out, n, dir, "credentials");
 }
 
-int cst_creds_load_api_key(char *out, size_t out_sz) {
-  if (!out || out_sz < 2)
+static void chomp(char *s) {
+  size_t len = strlen(s);
+  while (len > 0 && (s[len - 1] == '\n' || s[len - 1] == '\r' ||
+                     s[len - 1] == ' ' || s[len - 1] == '\t'))
+    s[--len] = 0;
+}
+
+static int same_base(const char *a, const char *b) {
+  size_t la = strlen(a), lb = strlen(b);
+  while (la > 0 && a[la - 1] == '/')
+    la--;
+  while (lb > 0 && b[lb - 1] == '/')
+    lb--;
+  return la == lb && strncmp(a, b, la) == 0;
+}
+
+int cst_creds_load(const char *provider, char *out, size_t out_sz) {
+  if (!provider || !provider[0] || !out || out_sz < 2)
     return -1;
   out[0] = 0;
   char path[OS_PATH_MAX];
@@ -33,108 +54,139 @@ int cst_creds_load_api_key(char *out, size_t out_sz) {
   FILE *fp = fopen(path, "r");
   if (!fp)
     return -1;
+  char want[64];
+  snprintf(want, sizeof(want), "%s.api_key=", provider);
+  size_t wl = strlen(want);
+  /* Old single-key files ("api_key=" + "api_base=") belong to the provider
+   * whose base URL matches; without a base they were MiniMax keys. */
+  char legacy_key[1024] = "", legacy_base[1024] = "";
   char line[1024];
+  int found = 0;
   while (fgets(line, sizeof(line), fp)) {
-    if (strncmp(line, "api_key=", 8) != 0)
-      continue;
-    char *v = line + 8;
-    size_t len = strlen(v);
-    while (len > 0 && (v[len - 1] == '\n' || v[len - 1] == '\r'))
-      v[--len] = 0;
-    if (len == 0 || len + 1 > out_sz) {
-      fclose(fp);
-      return -1;
+    chomp(line);
+    if (strncmp(line, want, wl) == 0 && line[wl]) {
+      snprintf(out, out_sz, "%s", line + wl);
+      found = 1;
+      break;
     }
-    memcpy(out, v, len + 1);
-    fclose(fp);
-    return 0;
+    if (strncmp(line, "api_key=", 8) == 0)
+      snprintf(legacy_key, sizeof(legacy_key), "%s", line + 8);
+    else if (strncmp(line, "api_base=", 9) == 0)
+      snprintf(legacy_base, sizeof(legacy_base), "%s", line + 9);
   }
   fclose(fp);
+  if (found)
+    return 0;
+  if (legacy_key[0]) {
+    const cst_provider_t *p = cst_provider_find(provider);
+    int match = p && (legacy_base[0] ? same_base(legacy_base, p->api_base)
+                                     : strcmp(provider, "minimax") == 0);
+    if (match && strlen(legacy_key) < out_sz) {
+      snprintf(out, out_sz, "%s", legacy_key);
+      return 0;
+    }
+  }
   return -1;
 }
 
-int cst_creds_save_api_key(const char *key) {
-  if (!key || !key[0])
+int cst_creds_save(const char *provider, const char *key) {
+  if (!provider || !provider[0] || !key || !key[0] || strchr(key, '\n'))
     return -1;
-  char dir[OS_PATH_MAX], path[OS_PATH_MAX];
-  if (os_config_dir(dir, sizeof(dir)) != 0)
+  char dir[OS_PATH_MAX], path[OS_PATH_MAX], tmp[OS_PATH_MAX + 8];
+  if (os_config_dir(dir, sizeof(dir)) != 0 || os_mkdir_p(dir, 0700) != 0 ||
+      credentials_path(path, sizeof(path)) != 0)
     return -1;
-  if (os_mkdir(dir, 0700) != 0)
+  if (snprintf(tmp, sizeof(tmp), "%s.tmp", path) >= (int)sizeof(tmp))
     return -1;
-  if (credentials_path(path, sizeof(path)) != 0)
+
+  char want[64];
+  snprintf(want, sizeof(want), "%s.api_key=", provider);
+  size_t wl = strlen(want);
+
+#ifdef _WIN32
+  FILE *out = fopen(tmp, "w");
+#else
+  /* never exists world-readable, even briefly */
+  int fd = open(tmp, O_WRONLY | O_CREAT | O_TRUNC, 0600);
+  FILE *out = fd >= 0 ? fdopen(fd, "w") : NULL;
+  if (!out && fd >= 0)
+    close(fd);
+#endif
+  if (!out)
     return -1;
-  FILE *fp = fopen(path, "w");
-  if (!fp)
+  FILE *in = fopen(path, "r");
+  if (in) {
+    char line[1024];
+    while (fgets(line, sizeof(line), in)) {
+      if (strncmp(line, want, wl) != 0)
+        fputs(line, out);
+    }
+    fclose(in);
+  }
+  fprintf(out, "%s%s\n", want, key);
+  if (fclose(out) != 0) {
+    remove(tmp);
     return -1;
-  fprintf(fp, "api_key=%s\n", key);
-  fprintf(fp, "api_base=https://api.minimax.cn/v1\n");
-  fprintf(fp, "model=MiniMax-M2.7\n");
-  fclose(fp);
+  }
+#ifdef _WIN32
+  remove(path);
+#endif
+  if (rename(tmp, path) != 0) {
+    remove(tmp);
+    return -1;
+  }
   (void)os_chmod_private(path);
   return 0;
 }
 
-/* Zenity on Unix; stdin prompt elsewhere / when zenity missing. */
-int cst_creds_prompt_api_key(char *out, size_t out_sz) {
+int cst_creds_resolve(const char *provider, char *out, size_t out_sz,
+                      const char **from) {
+  if (from)
+    *from = NULL;
+  if (cst_creds_load(provider, out, out_sz) == 0 && out[0]) {
+    if (from)
+      *from = "saved";
+    return 0;
+  }
+  const cst_provider_t *p = cst_provider_find(provider);
+  const char *env = p ? getenv(p->key_env) : NULL;
+  if (env && env[0]) {
+    snprintf(out, out_sz, "%s", env);
+    if (from)
+      *from = p->key_env;
+    return 0;
+  }
+  out[0] = 0;
+  return -1;
+}
+
+int cst_creds_prompt_console(const char *provider, char *out, size_t out_sz) {
   if (!out || out_sz < 2)
     return -1;
   out[0] = 0;
-
+  fprintf(stderr, "API key for %s (input hidden, saved to the config dir): ",
+          provider ? provider : "?");
+  fflush(stderr);
 #ifndef _WIN32
-  FILE *fp = popen(
-      "zenity --password --title='CST-Agent / MiniMax' "
-      "--text='请输入 MiniMax API Key（将保存到配置目录 credentials）' "
-      "2>/dev/null",
-      "r");
-  if (fp) {
-    if (fgets(out, (int)out_sz, fp)) {
-      int st = pclose(fp);
-      size_t len = strlen(out);
-      while (len > 0 && (out[len - 1] == '\n' || out[len - 1] == '\r'))
-        out[--len] = 0;
-      if (st == 0 && len > 0)
-        return 0;
-    } else {
-      pclose(fp);
-    }
-    out[0] = 0;
+  struct termios old, quiet;
+  int tty = isatty(STDIN_FILENO) && tcgetattr(STDIN_FILENO, &old) == 0;
+  if (tty) {
+    quiet = old;
+    quiet.c_lflag &= ~(tcflag_t)ECHO;
+    tcsetattr(STDIN_FILENO, TCSAFLUSH, &quiet);
   }
 #endif
-
-  /* Fallback: console prompt (headless / Windows / no zenity). */
-  fprintf(stderr, "CST-Agent: enter MiniMax API Key (saved to config dir): ");
-  fflush(stderr);
-  if (!fgets(out, (int)out_sz, stdin)) {
+  char *got = fgets(out, (int)out_sz, stdin);
+#ifndef _WIN32
+  if (tty) {
+    tcsetattr(STDIN_FILENO, TCSAFLUSH, &old);
+    fputc('\n', stderr);
+  }
+#endif
+  if (!got) {
     out[0] = 0;
     return -1;
   }
-  size_t len = strlen(out);
-  while (len > 0 && (out[len - 1] == '\n' || out[len - 1] == '\r'))
-    out[--len] = 0;
-  if (len == 0) {
-    out[0] = 0;
-    return -1;
-  }
-  return 0;
-}
-
-int cst_creds_ensure_api_key(char *out, size_t out_sz) {
-  const char *env = getenv("CST_API_KEY");
-  if (!env || !env[0])
-    env = getenv("MINIMAX_API_KEY");
-  if (!env || !env[0])
-    env = getenv("OPENAI_API_KEY");
-  if (env && env[0]) {
-    snprintf(out, out_sz, "%s", env);
-    return 0;
-  }
-  if (cst_creds_load_api_key(out, out_sz) == 0 && out[0])
-    return 0;
-  if (cst_creds_prompt_api_key(out, out_sz) != 0)
-    return -1;
-  if (cst_creds_save_api_key(out) != 0)
-    fprintf(stderr, "warning: failed to save credentials file\n");
-  else
-    fprintf(stderr, "saved API key to config directory\n");
-  return 0;
+  chomp(out);
+  return out[0] ? 0 : -1;
 }

src/ctl_parse.c

@@ -5,10 +5,13 @@
 #include <stdlib.h>
 #include <string.h>
 
+#define CTL_MAX_TAG 32
+
 typedef enum {
-  ST_TEXT = 0,     /* outside a call; accumulate text lines */
-  ST_LINE,         /* collecting a line (call/arg/end or text) */
-  ST_ARG_BODY,     /* reading nbytes of arg body */
+  ST_TEXT = 0,  /* outside a call; accumulate text lines */
+  ST_LINE,      /* collecting a line (call/arg/end or text) */
+  ST_ARG_BODY,  /* reading nbytes of arg body */
+  ST_HEREDOC,   /* reading heredoc lines until the tag line */
   ST_ERROR
 } ctl_state_t;
 
@@ -26,15 +29,43 @@ struct ctl_parser {
   size_t arg_cap;
   size_t arg_got;
   size_t arg_need;
+  char tag[CTL_MAX_TAG + 1];
   size_t pending;
-  size_t pending_peak;
+  ctl_parser_stats_t st;
   char errbuf[256];
+  /* last length-prefixed arg, for actionable contract-error messages */
+  char last_nkey[CTL_MAX_KEY];
+  size_t last_nbytes;
 };
 
+const char *ctl_error_kind_name(ctl_error_kind_t k) {
+  switch (k) {
+  case CTL_EK_NONE:
+    return "none";
+  case CTL_EK_BAD_CALL:
+    return "bad_call";
+  case CTL_EK_BAD_ARG:
+    return "bad_arg";
+  case CTL_EK_UNEXPECTED_LINE:
+    return "unexpected_line";
+  case CTL_EK_BODY_EOF:
+    return "body_eof";
+  case CTL_EK_HEREDOC_EOF:
+    return "heredoc_eof";
+  case CTL_EK_LINE_TOO_LONG:
+    return "line_too_long";
+  case CTL_EK_LIMIT:
+    return "limit";
+  case CTL_EK_OOM:
+    return "oom";
+  }
+  return "unknown";
+}
+
 static void bump_pending(ctl_parser_t *p, size_t n) {
   p->pending = n;
-  if (n > p->pending_peak)
-    p->pending_peak = n;
+  if (n > p->st.pending_peak)
+    p->st.pending_peak = n;
 }
 
 static void emit(ctl_parser_t *p, ctl_event_t *ev) {
@@ -42,9 +73,10 @@ static void emit(ctl_parser_t *p, ctl_event_t *ev) {
     p->on_event(ev, p->userdata);
 }
 
-static void fail(ctl_parser_t *p, const char *msg) {
+static void fail(ctl_parser_t *p, ctl_error_kind_t kind, const char *msg) {
   snprintf(p->errbuf, sizeof(p->errbuf), "%s", msg);
   p->state = ST_ERROR;
+  p->st.error_kind = kind;
   ctl_event_t ev = {0};
   ev.type = CTL_EV_ERROR;
   ev.error = p->errbuf;
@@ -70,6 +102,7 @@ static void reset_arg_body(ctl_parser_t *p) {
   p->arg_got = 0;
   p->arg_need = 0;
   p->arg_key[0] = 0;
+  p->tag[0] = 0;
 }
 
 ctl_parser_t *ctl_parser_create(ctl_on_event_fn on_event, void *userdata) {
@@ -99,15 +132,25 @@ void ctl_parser_reset(ctl_parser_t *p) {
   p->line_len = 0;
   p->in_call = 0;
   p->pending = 0;
-  /* keep pending_peak for experiment */
+  p->st.error_kind = CTL_EK_NONE;
+  p->last_nkey[0] = 0;
+  /* keep counters / pending_peak for experiments */
 }
 
-size_t ctl_parser_pending(const ctl_parser_t *p) {
-  return p ? p->pending : 0;
-}
+size_t ctl_parser_pending(const ctl_parser_t *p) { return p ? p->pending : 0; }
 
 size_t ctl_parser_pending_peak(const ctl_parser_t *p) {
-  return p ? p->pending_peak : 0;
+  return p ? p->st.pending_peak : 0;
+}
+
+void ctl_parser_stats(const ctl_parser_t *p, ctl_parser_stats_t *out) {
+  if (!out)
+    return;
+  if (!p) {
+    memset(out, 0, sizeof(*out));
+    return;
+  }
+  *out = p->st;
 }
 
 static int starts_with(const char *s, const char *pfx) {
@@ -132,6 +175,8 @@ static int parse_call_line(ctl_parser_t *p, const char *line) {
   if (!*sp)
     return -1;
   size_t nlen = strlen(sp);
+  while (nlen > 0 && (sp[nlen - 1] == ' ' || sp[nlen - 1] == '\t'))
+    nlen--;
   if (nlen == 0 || nlen >= CTL_MAX_NAME)
     return -1;
   for (size_t i = 0; i < nlen; i++) {
@@ -144,6 +189,7 @@ static int parse_call_line(ctl_parser_t *p, const char *line) {
   memcpy(p->call.name, sp, nlen);
   p->call.name[nlen] = 0;
   p->in_call = 1;
+  p->st.calls_open++;
   ctl_event_t ev = {0};
   ev.type = CTL_EV_CALL_OPEN;
   ev.call = &p->call;
@@ -151,12 +197,49 @@ static int parse_call_line(ctl_parser_t *p, const char *line) {
   return 0;
 }
 
-static int finish_arg(ctl_parser_t *p);
+static int finish_arg(ctl_parser_t *p) {
+  int i = p->call.nargs;
+  snprintf(p->call.args[i].key, CTL_MAX_KEY, "%s", p->arg_key);
+  if (!p->arg_buf) {
+    p->arg_buf = malloc(1);
+    if (!p->arg_buf)
+      return -1;
+  }
+  p->arg_buf[p->arg_got] = 0;
+  p->call.args[i].value = p->arg_buf;
+  p->call.args[i].value_len = p->arg_got;
+  p->arg_buf = NULL; /* ownership moved */
+  p->arg_cap = 0;
+  p->call.nargs++;
+  p->arg_need = 0;
+  p->arg_got = 0;
+  p->arg_key[0] = 0;
+  p->tag[0] = 0;
+  p->state = ST_LINE;
+  bump_pending(p, 0);
+  ctl_event_t ev = {0};
+  ev.type = CTL_EV_ARG;
+  ev.call = &p->call;
+  emit(p, &ev);
+  return 0;
+}
 
+static int valid_tag(const char *t, size_t n) {
+  if (n == 0 || n > CTL_MAX_TAG)
+    return 0;
+  for (size_t i = 0; i < n; i++) {
+    if (!(isalnum((unsigned char)t[i]) || t[i] == '_'))
+      return 0;
+  }
+  return 1;
+}
+
+/* Returns 0 ok, -1 contract error, -2 oom, -3 limit. */
 static int parse_arg_header(ctl_parser_t *p, const char *line) {
   /* Forms:
    *   arg <key> <nbytes>     → length-prefixed body follows
-   *   arg <key> <value...>   → value is rest of line (line-mode, confirmed now)
+   *   arg <key> <<TAG        → heredoc body until a line equal to TAG
+   *   arg <key> <value...>   → value is rest of line (confirmed now)
    */
   const char *s = line + 4;
   while (*s == ' ' || *s == '\t')
@@ -174,78 +257,81 @@ static int parse_arg_header(ctl_parser_t *p, const char *line) {
   if (!*sp)
     return -1;
   if (p->call.nargs >= CTL_MAX_ARGS)
-    return -1;
-
-  char *end = NULL;
-  unsigned long nbytes = strtoul(sp, &end, 10);
-  int length_prefixed = (end != sp && (*end == '\0' || *end == ' ' || *end == '\t'));
-  if (length_prefixed && end && *end != '\0') {
-    while (*end == ' ' || *end == '\t')
-      end++;
-    if (*end != '\0')
-      length_prefixed = 0; /* e.g. "9foo" or value starting with digits+text */
-  }
+    return -3;
 
   memcpy(p->arg_key, s, klen);
   p->arg_key[klen] = 0;
+  free(p->arg_buf);
+  p->arg_buf = NULL;
+  p->arg_cap = 0;
+  p->arg_got = 0;
+
+  if (sp[0] == '<' && sp[1] == '<') {
+    const char *t = sp + 2;
+    while (*t == ' ')
+      t++;
+    size_t tl = strlen(t);
+    while (tl > 0 && (t[tl - 1] == ' ' || t[tl - 1] == '\t'))
+      tl--;
+    if (tl >= 2 && (t[0] == '\'' || t[0] == '"') && t[tl - 1] == t[0]) {
+      t++;
+      tl -= 2;
+    }
+    if (!valid_tag(t, tl))
+      return -1;
+    memcpy(p->tag, t, tl);
+    p->tag[tl] = 0;
+    p->state = ST_HEREDOC;
+    p->st.args_heredoc++;
+    bump_pending(p, 0);
+    return 0;
+  }
+
+  char *end = NULL;
+  unsigned long nbytes = strtoul(sp, &end, 10);
+  int length_prefixed =
+      (end != sp && isdigit((unsigned char)sp[0]) &&
+       (*end == '\0' || *end == ' ' || *end == '\t'));
+  if (length_prefixed && *end != '\0') {
+    while (*end == ' ' || *end == '\t')
+      end++;
+    if (*end != '\0')
+      length_prefixed = 0; /* "9 apples" is an inline value */
+  }
 
   if (!length_prefixed) {
-    /* line-mode: entire remainder is the value */
     size_t vlen = strlen(sp);
     if (vlen > CTL_MAX_ARG_BYTES)
-      return -1;
-    free(p->arg_buf);
+      return -3;
     p->arg_buf = malloc(vlen + 1);
     if (!p->arg_buf)
       return -2;
     memcpy(p->arg_buf, sp, vlen);
-    p->arg_buf[vlen] = 0;
-    p->arg_need = vlen;
     p->arg_got = vlen;
     p->arg_cap = vlen;
-    finish_arg(p);
-    return 0;
+    p->st.args_inline++;
+    return finish_arg(p) == 0 ? 0 : -2;
   }
 
   if (nbytes > CTL_MAX_ARG_BYTES)
-    return -1;
+    return -3;
   p->arg_need = (size_t)nbytes;
-  p->arg_got = 0;
-  free(p->arg_buf);
-  p->arg_buf = NULL;
-  p->arg_cap = 0;
+  p->st.args_nbytes++;
+  snprintf(p->last_nkey, sizeof(p->last_nkey), "%s", p->arg_key);
+  p->last_nbytes = p->arg_need;
   if (p->arg_need > 0) {
     p->arg_buf = malloc(p->arg_need + 1);
     if (!p->arg_buf)
       return -2;
     p->arg_cap = p->arg_need;
   }
+  if (p->arg_need == 0)
+    return finish_arg(p) == 0 ? 0 : -2;
   p->state = ST_ARG_BODY;
   bump_pending(p, p->arg_need);
   return 0;
 }
 
-static int finish_arg(ctl_parser_t *p) {
-  int i = p->call.nargs;
-  snprintf(p->call.args[i].key, CTL_MAX_KEY, "%s", p->arg_key);
-  p->call.args[i].value = p->arg_buf;
-  p->call.args[i].value_len = p->arg_got;
-  if (p->arg_buf)
-    p->arg_buf[p->arg_got] = 0;
-  p->arg_buf = NULL; /* ownership moved */
-  p->call.nargs++;
-  p->arg_need = 0;
-  p->arg_got = 0;
-  p->arg_key[0] = 0;
-  p->state = ST_LINE;
-  bump_pending(p, 0);
-  ctl_event_t ev = {0};
-  ev.type = CTL_EV_ARG;
-  ev.call = &p->call;
-  emit(p, &ev);
-  return 0;
-}
-
 static void emit_text_line(ctl_parser_t *p, const char *line, size_t len) {
   /* include newline as confirmed text */
   char tmp[CTL_MAX_LINE + 1];
@@ -262,21 +348,55 @@ static void emit_text_line(ctl_parser_t *p, const char *line, size_t len) {
 }
 
 static int is_fence_line(const char *line) {
-  if (strncmp(line, "```", 3) == 0)
-    return 1;
-  if (strncmp(line, "~~~", 3) == 0)
-    return 1;
+  return strncmp(line, "```", 3) == 0 || strncmp(line, "~~~", 3) == 0;
+}
+
+static void emit_ready(ctl_parser_t *p) {
+  ctl_event_t ev = {0};
+  ev.type = CTL_EV_CALL_READY;
+  ev.call = &p->call;
+  p->st.calls_ready++;
+  emit(p, &ev);
+  clear_call_args(&p->call);
+  p->in_call = 0;
+  bump_pending(p, 0);
+  p->state = ST_LINE;
+}
+
+static int heredoc_line(ctl_parser_t *p, const char *line, size_t len) {
+  if (strcmp(line, p->tag) == 0)
+    return finish_arg(p) == 0 ? 0 : -1;
+  size_t need = p->arg_got + len + 1;
+  if (need > CTL_MAX_ARG_BYTES) {
+    fail(p, CTL_EK_LIMIT, "heredoc body too large");
+    return -1;
+  }
+  if (need + 1 > p->arg_cap) {
+    size_t nc = p->arg_cap ? p->arg_cap * 2 : 256;
+    while (nc < need + 1)
+      nc *= 2;
+    char *nb = realloc(p->arg_buf, nc);
+    if (!nb) {
+      fail(p, CTL_EK_OOM, "oom");
+      return -1;
+    }
+    p->arg_buf = nb;
+    p->arg_cap = nc;
+  }
+  memcpy(p->arg_buf + p->arg_got, line, len);
+  p->arg_got += len;
+  p->arg_buf[p->arg_got++] = '\n';
+  bump_pending(p, 0);
   return 0;
 }
 
 static int handle_line(ctl_parser_t *p, const char *line) {
   /* Ignore markdown fences so models can wrap CTL in code blocks. */
-  if (is_fence_line(line)) {
+  if (is_fence_line(line) && !p->in_call) {
     bump_pending(p, 0);
     return 0;
   }
-  /* Ignore blank lines between CTL frames. */
-  if (line[0] == '\0') {
+  if (line[0] == '\0' || (p->in_call && is_fence_line(line))) {
     bump_pending(p, 0);
     return 0;
   }
@@ -284,13 +404,13 @@ static int handle_line(ctl_parser_t *p, const char *line) {
   if (!p->in_call) {
     if (starts_with(line, "call ")) {
       if (parse_call_line(p, line) != 0) {
-        fail(p, "invalid call line");
+        fail(p, CTL_EK_BAD_CALL, "invalid call line");
         return -1;
       }
+      p->last_nkey[0] = 0;
       bump_pending(p, 0);
       return 0;
     }
-    /* confirmed text line */
     emit_text_line(p, line, strlen(line));
     bump_pending(p, 0);
     return 0;
@@ -300,29 +420,33 @@ static int handle_line(ctl_parser_t *p, const char *line) {
   if (starts_with(line, "arg ")) {
     int rc = parse_arg_header(p, line);
     if (rc == -2) {
-      fail(p, "oom");
+      fail(p, CTL_EK_OOM, "oom");
+      return -1;
+    }
+    if (rc == -3) {
+      fail(p, CTL_EK_LIMIT, "too many args or arg too large");
       return -1;
     }
     if (rc != 0) {
-      fail(p, "invalid arg header");
+      fail(p, CTL_EK_BAD_ARG, "invalid arg header");
       return -1;
     }
-    if (p->arg_need == 0)
-      finish_arg(p);
     return 0;
   }
   if (strcmp(line, "end") == 0) {
-    ctl_event_t ev = {0};
-    ev.type = CTL_EV_CALL_READY;
-    ev.call = &p->call;
-    emit(p, &ev);
-    clear_call_args(&p->call);
-    p->in_call = 0;
-    bump_pending(p, 0);
-    p->state = ST_LINE;
+    emit_ready(p);
     return 0;
   }
-  fail(p, "unexpected line inside call");
+  char msg[256];
+  if (p->last_nkey[0])
+    snprintf(msg, sizeof(msg),
+             "unexpected line \"%.40s\" inside call; arg %s declared %zu "
+             "bytes, so its real body was longer (byte count too small)",
+             line, p->last_nkey, p->last_nbytes);
+  else
+    snprintf(msg, sizeof(msg), "unexpected line \"%.40s\" inside call",
+             line);
+  fail(p, CTL_EK_UNEXPECTED_LINE, msg);
   return -1;
 }
 
@@ -345,30 +469,30 @@ ctl_status_t ctl_parser_feed(ctl_parser_t *p, const char *data, size_t len) {
         i += take;
         bump_pending(p, p->arg_need - p->arg_got);
       }
-      if (p->arg_got == p->arg_need) {
-        finish_arg(p);
-        /* continue with remaining bytes in LINE mode */
+      if (p->arg_got == p->arg_need && finish_arg(p) != 0) {
+        fail(p, CTL_EK_OOM, "oom");
+        return CTL_ERR_NOMEM;
       }
       continue;
     }
 
-    /* line accumulation */
-    p->state = ST_LINE;
+    if (p->state != ST_HEREDOC)
+      p->state = ST_LINE;
     unsigned char c = (unsigned char)data[i++];
     if (c == '\r')
       continue; /* normalize CRLF */
     if (c == '\n') {
       p->line[p->line_len] = 0;
-      if (handle_line(p, p->line) != 0)
-        return CTL_ERR_CONTRACT;
+      int rc = p->state == ST_HEREDOC ? heredoc_line(p, p->line, p->line_len)
+                                      : handle_line(p, p->line);
       p->line_len = 0;
-      if (p->state == ST_ARG_BODY && p->arg_need == 0) {
-        /* already finished empty arg */
-      }
+      if (rc != 0)
+        return p->st.error_kind == CTL_EK_LIMIT ? CTL_ERR_LIMIT
+                                                : CTL_ERR_CONTRACT;
       continue;
     }
     if (p->line_len + 1 >= CTL_MAX_LINE) {
-      fail(p, "line too long");
+      fail(p, CTL_EK_LINE_TOO_LONG, "line too long");
       return CTL_ERR_LIMIT;
     }
     p->line[p->line_len++] = (char)c;
@@ -384,9 +508,25 @@ ctl_status_t ctl_parser_finish(ctl_parser_t *p) {
     return CTL_ERR_CONTRACT;
   /* Mid-argument body cannot be confirmed at EOF. */
   if (p->state == ST_ARG_BODY) {
-    fail(p, "incomplete arg body at EOF");
+    char msg[200];
+    snprintf(msg, sizeof(msg),
+             "stream ended inside arg %s: declared %zu bytes but only %zu "
+             "arrived (byte count too large)",
+             p->arg_key, p->arg_need, p->arg_got);
+    fail(p, CTL_EK_BODY_EOF, msg);
     return CTL_ERR_CONTRACT;
   }
+  if (p->state == ST_HEREDOC) {
+    p->line[p->line_len] = 0;
+    if (p->line_len > 0 && strcmp(p->line, p->tag) == 0) {
+      p->line_len = 0;
+      if (finish_arg(p) != 0)
+        return CTL_ERR_NOMEM;
+    } else {
+      fail(p, CTL_EK_HEREDOC_EOF, "stream ended before heredoc terminator");
+      return CTL_ERR_CONTRACT;
+    }
+  }
   /* Trailing text without final newline is still confirmed text. */
   if (!p->in_call && p->line_len > 0) {
     p->line[p->line_len] = 0;
@@ -398,21 +538,16 @@ ctl_status_t ctl_parser_finish(ctl_parser_t *p) {
   if (p->in_call) {
     if (p->line_len > 0) {
       p->line[p->line_len] = 0;
-      /* leftover line must be end or fence/blank */
       if (strcmp(p->line, "end") == 0 || is_fence_line(p->line) ||
           p->line[0] == '\0') {
         p->line_len = 0;
       } else {
-        fail(p, "unexpected trailing line in call at EOF");
+        fail(p, CTL_EK_UNEXPECTED_LINE,
+             "unexpected trailing line in call at EOF");
         return CTL_ERR_CONTRACT;
       }
     }
-    ctl_event_t ev = {0};
-    ev.type = CTL_EV_CALL_READY;
-    ev.call = &p->call;
-    emit(p, &ev);
-    clear_call_args(&p->call);
-    p->in_call = 0;
+    emit_ready(p);
   }
   bump_pending(p, 0);
   return CTL_OK;

src/json_baseline.c

@@ -1,145 +1,45 @@
+#include "cJSON.h"
 #include "cst_agent.h"
 
 #include <stdio.h>
+#include <stdlib.h>
 #include <string.h>
 
-/* Minimal JSON tool object: {"name":"...","arguments":{...}}
- * Buffer-until-valid baseline (NOT bounded CST). */
-
-static const char *skip_ws(const char *p, const char *end) {
-  while (p < end && (*p == ' ' || *p == '\n' || *p == '\r' || *p == '\t'))
-    p++;
-  return p;
-}
-
-/* Find matching closing brace/bracket starting at open pos. Returns end ptr or
- * NULL if incomplete. Handles strings/escapes. */
-static const char *match_obj(const char *start, const char *end) {
-  if (start >= end || *start != '{')
-    return NULL;
-  int depth = 0;
-  int in_str = 0;
-  for (const char *p = start; p < end; p++) {
-    if (in_str) {
-      if (*p == '\\' && p + 1 < end) {
-        p++;
-        continue;
-      }
-      if (*p == '"')
-        in_str = 0;
-      continue;
-    }
-    if (*p == '"') {
-      in_str = 1;
-      continue;
-    }
-    if (*p == '{')
-      depth++;
-    else if (*p == '}') {
-      depth--;
-      if (depth == 0)
-        return p + 1;
-    }
-  }
-  return NULL; /* incomplete */
-}
-
-static int extract_string(const char *obj, const char *end, const char *key,
-                          char *out, size_t out_sz) {
-  char pat[128];
-  snprintf(pat, sizeof(pat), "\"%s\"", key);
-  const char *k = obj;
-  while (k && k < end) {
-    k = strstr(k, pat);
-    if (!k || k >= end)
-      return -1;
-    /* ensure key boundary */
-    const char *colon = k + strlen(pat);
-    colon = skip_ws(colon, end);
-    if (colon >= end || *colon != ':') {
-      k++;
-      continue;
-    }
-    colon++;
-    colon = skip_ws(colon, end);
-    if (colon >= end || *colon != '"')
-      return -1;
-    colon++;
-    size_t o = 0;
-    for (const char *p = colon; p < end && o + 1 < out_sz; p++) {
-      if (*p == '\\' && p + 1 < end) {
-        p++;
-        if (*p == 'n')
-          out[o++] = '\n';
-        else
-          out[o++] = *p;
-        continue;
-      }
-      if (*p == '"') {
-        out[o] = 0;
-        return 0;
-      }
-      out[o++] = *p;
-    }
-    return -1;
-  }
-  return -1;
-}
-
+/* JSON-buffer baseline: {"name":"...","arguments":{...}} is executable only
+ * once cJSON can parse the whole object (NOT bounded CST: nothing inside an
+ * unfinished object is ever confirmed). */
 int cst_json_try_parse_tool(const char *buf, size_t len, cst_json_tool_t *out) {
   if (!buf || !out)
     return 0;
   memset(out, 0, sizeof(*out));
-  const char *end = buf + len;
-  const char *p = buf;
+  const char *p = buf, *end = buf + len;
   while (p < end) {
-    p = skip_ws(p, end);
-    if (p >= end)
-      break;
     if (*p != '{') {
       p++;
       continue;
     }
-    const char *obj_end = match_obj(p, end);
-    if (!obj_end)
-      return 0; /* incomplete JSON — starvation failure mode */
-    if (extract_string(p, obj_end, "name", out->name, sizeof(out->name)) !=
-        0) {
-      p++;
-      continue;
+    const char *obj_end = NULL;
+    cJSON *o = cJSON_ParseWithLengthOpts(p, (size_t)(end - p), &obj_end, 0);
+    if (!o)
+      return 0; /* incomplete/invalid: the starvation failure mode */
+    const cJSON *name = cJSON_GetObjectItemCaseSensitive(o, "name");
+    const cJSON *args = cJSON_GetObjectItemCaseSensitive(o, "arguments");
+    int ok = 0;
+    if (cJSON_IsString(name) && args &&
+        strlen(name->valuestring) < sizeof(out->name)) {
+      char *a = cJSON_IsString(args) ? NULL : cJSON_PrintUnformatted(args);
+      const char *av = a ? a : (cJSON_IsString(args) ? args->valuestring : "");
+      if (strlen(av) < sizeof(out->arguments_json)) {
+        snprintf(out->name, sizeof(out->name), "%s", name->valuestring);
+        snprintf(out->arguments_json, sizeof(out->arguments_json), "%s", av);
+        out->ok = ok = 1;
+      }
+      free(a);
     }
-    /* arguments: object as raw substring */
-    const char *akey = strstr(p, "\"arguments\"");
-    if (!akey || akey >= obj_end) {
-      p = obj_end;
-      continue;
-    }
-    const char *colon = strchr(akey + 11, ':');
-    if (!colon || colon >= obj_end)
-      return 0;
-    colon++;
-    colon = skip_ws(colon, obj_end);
-    if (colon >= obj_end)
-      return 0;
-    if (*colon == '{') {
-      const char *ae = match_obj(colon, obj_end);
-      if (!ae)
-        return 0;
-      size_t n = (size_t)(ae - colon);
-      if (n >= sizeof(out->arguments_json))
-        return 0;
-      memcpy(out->arguments_json, colon, n);
-      out->arguments_json[n] = 0;
-    } else if (*colon == '"') {
-      if (extract_string(akey, obj_end, "arguments", out->arguments_json,
-                         sizeof(out->arguments_json)) != 0)
-        return 0;
-    } else {
-      p = obj_end;
-      continue;
-    }
-    out->ok = 1;
-    return 1;
+    cJSON_Delete(o);
+    if (ok)
+      return 1;
+    p = obj_end && obj_end > p ? obj_end : p + 1;
   }
   return 0;
 }

src/main.c

@@ -1,4 +1,5 @@
 #include "cst_agent.h"
+#include "cst_tools.h"
 #include "os_compat.h"
 
 #include <curl/curl.h>
@@ -6,30 +7,120 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include <time.h>
 #ifdef _WIN32
 #include <direct.h>
+#include <io.h>
 #else
 #include <unistd.h>
 #endif
 
 static void usage(const char *argv0) {
   fprintf(stderr,
-          "Usage: %s [--workspace DIR] [--session FILE] [--api-base URL]\n"
-          "          [--api-key KEY] [--model NAME] [--headless]\n"
-          "          [--prompt TEXT] [--demo-ctl] [--ask-key]\n"
+          "Usage: %s [options]        (works in the current directory)\n"
+          "  -P, --provider NAME   minimax | deepseek | openai (last used)\n"
+          "  -m, --model NAME      model (last used for the provider)\n"
+          "  -e, --effort LEVEL    low | medium | high | max (last used)\n"
+          "  -w, --workspace DIR   project directory (default: current)\n"
+          "  -c, --continue        reopen the last session (default)\n"
+          "  -N, --new             start a new session\n"
+          "  -R, --resume ID       open a session by id or unique prefix\n"
+          "  -L, --list-sessions   list sessions and exit\n"
+          "  -y, --yolo            never ask before shell / writes / web\n"
+          "  -C, --confirm LIST    shell,write,net (default) | none\n"
+          "  -r, --protocol P      native-eos (default) | native-inc | ctl |\n"
+          "                        ctl-heredoc | xml\n"
+          "  -T, --tools PROFILE   default (all tools) | minimal (paper set)\n"
+          "  -n, --max-steps N     model calls per turn (30)\n"
+          "  -H, --headless -p TEXT  run one prompt without the TUI\n"
+          "  -a, --ask-key         enter and save the provider's API key\n"
+          "  -k, --api-key KEY     use KEY for this run only (not saved)\n"
+          "  -b, --api-base URL    OpenAI-compatible base URL (…/v1)\n"
+          "  -s, --session FILE    explicit session file\n"
+          "  -d, --demo-ctl        local CTL parser demo (no API)\n"
           "\n"
-          "Defaults: api-base=https://api.minimax.cn/v1 model=MiniMax-M2.7\n"
-          "Session: <workspace>/.agent/sessions/<id>.jsonl (CURRENT tracked)\n"
-          "API key: CST_API_KEY / OPENAI_API_KEY / MINIMAX_API_KEY\n"
-          "Base:    CST_API_BASE / OPENAI_BASE_URL (OpenAI-compatible …/v1)\n"
-          "Model:   CST_MODEL / OPENAI_MODEL\n"
-          "Also:    CST_MODELS, CST_AUTO_APPROVE=1, CST_SHELL, CST_EXE_DIR\n"
-          "TUI: /new /session /model /compact /details /help\n"
-          "     Enter send · Ctrl+N newline · ↑↓ history · Esc cancel\n"
-          "     busy Enter queues · tool perm y/n/a=always · wheel scroll\n",
+          "API keys: the TUI asks for a missing key and saves it per provider\n"
+          "  in the config dir (credentials, mode 0600); /key changes it.\n"
+          "  Fallbacks: <provider env> (DEEPSEEK_API_KEY, ...), CST_API_KEY.\n"
+          "Settings: provider, models and effort are remembered in\n"
+          "  settings.json next to the credentials.\n"
+          "Env:  CST_PROVIDER CST_MODEL CST_EFFORT CST_PROTOCOL CST_TOOLS\n"
+          "      CST_CONFIRM CST_MAX_STEPS CST_TOOL_OUT_CAP CST_CTX_WINDOW\n"
+          "      CST_CTX_TOKENS CST_AUTO_COMPACT=0 CST_SHELL_TIMEOUT\n"
+          "      CST_METRICS=0 CST_RECORD_SSE CST_REPLAY_SSE CST_MODELS\n"
+          "      CST_AUTO_APPROVE=1 CST_SHELL CST_NO_PROJECT_NOTES=1 NO_COLOR\n"
+          "TUI: type /help inside for commands and keys\n",
           argv0);
 }
 
+static int parse_confirm(const char *s, cst_agent_config_t *cfg) {
+  cfg->confirm_shell = cfg->confirm_write = cfg->confirm_net = 0;
+  if (!s || strcmp(s, "none") == 0 || !s[0])
+    return 0;
+  char buf[128];
+  snprintf(buf, sizeof(buf), "%s", s);
+  for (char *tok = strtok(buf, ", "); tok; tok = strtok(NULL, ", ")) {
+    if (strcmp(tok, "shell") == 0)
+      cfg->confirm_shell = 1;
+    else if (strcmp(tok, "write") == 0)
+      cfg->confirm_write = 1;
+    else if (strcmp(tok, "net") == 0)
+      cfg->confirm_net = 1;
+    else if (strcmp(tok, "all") == 0)
+      cfg->confirm_shell = cfg->confirm_write = cfg->confirm_net = 1;
+    else
+      return -1;
+  }
+  return 0;
+}
+
+static int list_sessions(const char *ws) {
+  static char ids[200][128];
+  int n = cst_agent_store_list(ws, ids, 200);
+  char cur[128] = "";
+  cst_agent_store_get_current(ws, cur, sizeof(cur));
+  if (n == 0) {
+    printf("no sessions under %s/.agent/sessions\n", ws);
+    return 0;
+  }
+  for (int i = 0; i < n; i++) {
+    cst_session_info_t in;
+    if (cst_agent_store_info(ws, ids[i], &in) != 0)
+      continue;
+    char when[32] = "?";
+    time_t t = (time_t)in.mtime;
+    struct tm tm;
+    os_localtime(&t, &tm);
+    strftime(when, sizeof(when), "%Y-%m-%d %H:%M", &tm);
+    printf("%c %-24s %s %4d msgs  %s\n", strcmp(cur, ids[i]) == 0 ? '*' : ' ',
+           in.id, when, in.messages,
+           in.title[0] ? in.title : in.first_user);
+  }
+  return 0;
+}
+
+/* Exact id or unique prefix → id. */
+static int resolve_session_id(const char *ws, const char *want, char *out,
+                              size_t out_sz) {
+  static char ids[500][128];
+  int n = cst_agent_store_list(ws, ids, 500), hit = -1;
+  for (int i = 0; i < n; i++) {
+    if (strcmp(ids[i], want) == 0) {
+      hit = i;
+      break;
+    }
+    if (strncmp(ids[i], want, strlen(want)) == 0) {
+      if (hit >= 0)
+        return -2;
+      hit = i;
+    }
+  }
+  if (hit < 0)
+    return -1;
+  snprintf(out, out_sz, "%s", ids[hit]);
+  return 0;
+}
+
 static int g_ready;
 static ctl_tool_call_t g_call;
 
@@ -104,32 +195,52 @@ int main(int argc, char **argv) {
     snprintf(cwd, sizeof(cwd), ".");
   snprintf(cfg.workspace_root, sizeof(cfg.workspace_root), "%s", cwd);
   cfg.session_path[0] = 0; /* filled after workspace opts via .agent/store */
-  /* OpenAI-compatible base URL aliases */
-  const char *env_base = getenv("CST_API_BASE");
-  if (!env_base || !env_base[0])
-    env_base = getenv("OPENAI_BASE_URL");
-  if (!env_base || !env_base[0])
-    env_base = getenv("OPENAI_API_BASE");
-  const char *env_model = getenv("CST_MODEL");
-  if (!env_model || !env_model[0])
-    env_model = getenv("OPENAI_MODEL");
-  snprintf(cfg.api_base, sizeof(cfg.api_base), "%s",
-           env_base && env_base[0] ? env_base : "https://api.minimax.cn/v1");
+  cfg.api_base[0] = 0;
   cfg.api_key[0] = 0;
-  snprintf(cfg.model, sizeof(cfg.model), "%s",
-           env_model && env_model[0] ? env_model : "MiniMax-M2.7");
+  cfg.model[0] = 0;
+  cfg.protocol = CST_PROTO_NATIVE_EOS;
+  const char *env_proto = getenv("CST_PROTOCOL");
+  if (env_proto && env_proto[0] &&
+      cst_protocol_parse(env_proto, &cfg.protocol) != 0) {
+    fprintf(stderr, "unknown CST_PROTOCOL=%s\n", env_proto);
+    return 1;
+  }
+  cfg.max_steps = CST_DEFAULT_MAX_STEPS;
+  const char *env_steps = getenv("CST_MAX_STEPS");
+  if (env_steps && atoi(env_steps) > 0)
+    cfg.max_steps = atoi(env_steps);
+  cfg.tool_out_cap = CST_DEFAULT_TOOL_OUT_CAP;
+  const char *env_cap = getenv("CST_TOOL_OUT_CAP");
+  if (env_cap && atol(env_cap) > 0)
+    cfg.tool_out_cap = (size_t)atol(env_cap);
+  const char *provider_name = getenv("CST_PROVIDER");
   cfg.headless = 0;
   cfg.confirm_shell = 1;
   cfg.confirm_write = 1;
+  cfg.confirm_net = 1;
   cfg.auto_approve = 0;
+  cfg.tool_profile = CST_TOOLS_DEFAULT;
+  const char *env_tools = getenv("CST_TOOLS");
+  if (env_tools && env_tools[0] &&
+      cst_tool_profile_parse(env_tools, &cfg.tool_profile) != 0) {
+    fprintf(stderr, "unknown CST_TOOLS=%s (default | minimal)\n", env_tools);
+    return 1;
+  }
   if (getenv("CST_AUTO_APPROVE"))
     cfg.auto_approve = 1;
+  const char *env_confirm = getenv("CST_CONFIRM");
+  if (env_confirm && parse_confirm(env_confirm, &cfg) != 0) {
+    fprintf(stderr, "bad CST_CONFIRM=%s (shell,write,net | none)\n",
+            env_confirm);
+    return 1;
+  }
 
   int do_demo = 0;
   int force_ask_key = 0;
   int session_explicit = 0;
   const char *prompt = NULL;
-  int key_from_cli = 0;
+  int new_session = 0, do_list = 0;
+  const char *resume_id = NULL;
 
   static struct option opts[] = {
       {"workspace", required_argument, 0, 'w'},
@@ -137,14 +248,26 @@ int main(int argc, char **argv) {
       {"api-base", required_argument, 0, 'b'},
       {"api-key", required_argument, 0, 'k'},
       {"model", required_argument, 0, 'm'},
+      {"provider", required_argument, 0, 'P'},
+      {"protocol", required_argument, 0, 'r'},
+      {"max-steps", required_argument, 0, 'n'},
+      {"tools", required_argument, 0, 'T'},
       {"headless", no_argument, 0, 'H'},
       {"prompt", required_argument, 0, 'p'},
       {"demo-ctl", no_argument, 0, 'd'},
       {"ask-key", no_argument, 0, 'a'},
+      {"new", no_argument, 0, 'N'},
+      {"continue", no_argument, 0, 'c'},
+      {"resume", required_argument, 0, 'R'},
+      {"list-sessions", no_argument, 0, 'L'},
+      {"yolo", no_argument, 0, 'y'},
+      {"confirm", required_argument, 0, 'C'},
+      {"effort", required_argument, 0, 'e'},
       {"help", no_argument, 0, 'h'},
       {0, 0, 0, 0}};
   int c;
-  while ((c = getopt_long(argc, argv, "w:s:b:k:m:Hp:dah", opts, NULL)) != -1) {
+  while ((c = getopt_long(argc, argv, "w:s:b:k:m:P:r:n:T:Hp:dahNcR:LyC:e:", opts, NULL)) !=
+         -1) {
     switch (c) {
     case 'w':
       snprintf(cfg.workspace_root, sizeof(cfg.workspace_root), "%s", optarg);
@@ -158,11 +281,33 @@ int main(int argc, char **argv) {
       break;
     case 'k':
       snprintf(cfg.api_key, sizeof(cfg.api_key), "%s", optarg);
-      key_from_cli = 1;
       break;
     case 'm':
       snprintf(cfg.model, sizeof(cfg.model), "%s", optarg);
       break;
+    case 'P':
+      provider_name = optarg;
+      break;
+    case 'r':
+      if (cst_protocol_parse(optarg, &cfg.protocol) != 0) {
+        fprintf(stderr, "unknown protocol: %s\n", optarg);
+        curl_global_cleanup();
+        return 1;
+      }
+      break;
+    case 'n':
+      cfg.max_steps = atoi(optarg);
+      if (cfg.max_steps <= 0)
+        cfg.max_steps = CST_DEFAULT_MAX_STEPS;
+      break;
+    case 'T':
+      if (cst_tool_profile_parse(optarg, &cfg.tool_profile) != 0) {
+        fprintf(stderr, "unknown tool profile: %s (default | minimal)\n",
+                optarg);
+        curl_global_cleanup();
+        return 1;
+      }
+      break;
     case 'H':
       cfg.headless = 1;
       break;
@@ -175,6 +320,38 @@ int main(int argc, char **argv) {
     case 'a':
       force_ask_key = 1;
       break;
+    case 'N':
+      new_session = 1;
+      break;
+    case 'c':
+      new_session = 0;
+      resume_id = NULL;
+      break;
+    case 'R':
+      resume_id = optarg;
+      break;
+    case 'L':
+      do_list = 1;
+      break;
+    case 'y':
+      cfg.auto_approve = 1;
+      break;
+    case 'C':
+      if (parse_confirm(optarg, &cfg) != 0) {
+        fprintf(stderr, "bad --confirm %s (shell,write,net | none)\n", optarg);
+        curl_global_cleanup();
+        return 1;
+      }
+      break;
+    case 'e':
+      if (!cst_effort_valid(optarg)) {
+        fprintf(stderr, "bad --effort %s (low | medium | high | max)\n",
+                optarg);
+        curl_global_cleanup();
+        return 1;
+      }
+      snprintf(cfg.effort, sizeof(cfg.effort), "%s", optarg);
+      break;
     case 'h':
       usage(argv[0]);
       curl_global_cleanup();
@@ -186,6 +363,63 @@ int main(int argc, char **argv) {
     }
   }
 
+  if (do_list) {
+    int rc = list_sessions(cfg.workspace_root);
+    curl_global_cleanup();
+    return rc;
+  }
+
+  /* Explicit option > environment > last used (settings.json) > preset. */
+  cst_settings_t saved;
+  cst_settings_load(&saved);
+  if ((!provider_name || !provider_name[0]) &&
+      cst_provider_find(saved.provider))
+    provider_name = saved.provider;
+  const cst_provider_t *prov = cst_provider_default();
+  if (provider_name && provider_name[0]) {
+    prov = cst_provider_find(provider_name);
+    if (!prov) {
+      fprintf(stderr, "unknown provider: %s\n", provider_name);
+      curl_global_cleanup();
+      return 1;
+    }
+  }
+  snprintf(cfg.provider, sizeof(cfg.provider), "%s", prov->name);
+  if (!cfg.effort[0]) {
+    const char *e = getenv("CST_EFFORT");
+    if (!cst_effort_valid(e))
+      e = saved.effort;
+    snprintf(cfg.effort, sizeof(cfg.effort), "%s",
+             cst_effort_valid(e) ? e : CST_DEFAULT_EFFORT);
+  }
+  if (!cfg.api_base[0]) {
+    const char *env_base = getenv("CST_API_BASE");
+    if (!env_base || !env_base[0])
+      env_base = getenv("OPENAI_BASE_URL");
+    if (!env_base || !env_base[0])
+      env_base = getenv("OPENAI_API_BASE");
+    snprintf(cfg.api_base, sizeof(cfg.api_base), "%s",
+             env_base && env_base[0] ? env_base : prov->api_base);
+  }
+  if (!cfg.model[0]) {
+    const char *env_model = getenv("CST_MODEL");
+    if (!env_model || !env_model[0])
+      env_model = getenv("OPENAI_MODEL");
+    if (!env_model || !env_model[0])
+      env_model = cst_settings_model(&saved, prov->name);
+    snprintf(cfg.model, sizeof(cfg.model), "%s",
+             env_model && env_model[0] ? env_model : prov->model);
+  }
+  /* --api-key > saved key > provider env > CST_API_KEY; the TUI asks for
+   * a missing key itself. */
+  if (!cfg.api_key[0] && !force_ask_key &&
+      cst_creds_resolve(prov->name, cfg.api_key, sizeof(cfg.api_key), NULL) !=
+          0) {
+    const char *k = getenv("CST_API_KEY");
+    if (k && k[0])
+      snprintf(cfg.api_key, sizeof(cfg.api_key), "%s", k);
+  }
+
   /* trim trailing slash on api_base */
   size_t alen = strlen(cfg.api_base);
   while (alen > 0 && cfg.api_base[alen - 1] == '/')
@@ -196,7 +430,29 @@ int main(int argc, char **argv) {
     cfg.auto_approve = 1;
 
   /* Default session under <workspace>/.agent/sessions/ (OpenCode-like). */
-  if (!session_explicit) {
+  if (!session_explicit && (new_session || resume_id)) {
+    char id[128];
+    int rc = 0;
+    if (new_session) {
+      rc = cst_agent_store_ensure(cfg.workspace_root) != 0 ||
+                   cst_agent_store_new_id(id, sizeof(id)) != 0
+               ? -1
+               : 0;
+    } else {
+      rc = resolve_session_id(cfg.workspace_root, resume_id, id, sizeof(id));
+      if (rc != 0)
+        fprintf(stderr, "%s session: %s (see --list-sessions)\n",
+                rc == -2 ? "ambiguous" : "no such", resume_id);
+    }
+    if (rc != 0 || cst_agent_store_path_for_id(cfg.workspace_root, id,
+                                               cfg.session_path,
+                                               sizeof(cfg.session_path)) != 0) {
+      curl_global_cleanup();
+      return 1;
+    }
+    cst_agent_store_set_current(cfg.workspace_root, id);
+    fprintf(stderr, "session %s%s\n", id, new_session ? " (new)" : "");
+  } else if (!session_explicit) {
     char id[128];
     if (cst_agent_store_resolve_default(cfg.workspace_root, cfg.session_path,
                                         sizeof(cfg.session_path), id,
@@ -215,37 +471,41 @@ int main(int argc, char **argv) {
     return rc;
   }
 
-  if (force_ask_key || !key_from_cli) {
-    if (force_ask_key) {
-      if (cst_creds_prompt_api_key(cfg.api_key, sizeof(cfg.api_key)) != 0) {
-        fprintf(stderr, "API key prompt cancelled\n");
-        curl_global_cleanup();
-        return 1;
-      }
-      if (cst_creds_save_api_key(cfg.api_key) != 0)
-        fprintf(stderr, "warning: failed to save credentials\n");
-      else
-        fprintf(stderr, "saved API key to ~/.config/cst-agent/credentials\n");
-      /* --ask-key alone: save and exit unless running a turn/TUI */
-      if (!cfg.headless && !prompt) {
-        fprintf(stderr, "using %s model=%s\n", cfg.api_base, cfg.model);
-        curl_global_cleanup();
-        return 0;
-      }
-    } else if (!cfg.api_key[0]) {
-      if (cst_creds_ensure_api_key(cfg.api_key, sizeof(cfg.api_key)) != 0) {
-        fprintf(stderr, "no API key (set CST_API_KEY or use --ask-key)\n");
-        curl_global_cleanup();
-        return 1;
-      }
+  int need_console_key =
+      force_ask_key || (!cfg.api_key[0] && cfg.headless && isatty(0));
+  if (need_console_key) {
+    if (cst_creds_prompt_console(cfg.provider, cfg.api_key,
+                                 sizeof(cfg.api_key)) != 0) {
+      fprintf(stderr, "no API key entered\n");
+      curl_global_cleanup();
+      return 1;
     }
-  } else if (key_from_cli) {
-    /* persist CLI-provided key so next launch can reuse */
-    if (cst_creds_save_api_key(cfg.api_key) != 0)
+    char dir[1024] = "the config directory";
+    os_config_dir(dir, sizeof(dir));
+    if (cst_creds_save(cfg.provider, cfg.api_key) != 0)
       fprintf(stderr, "warning: failed to save credentials\n");
+    else
+      fprintf(stderr, "saved the %s API key to %s/credentials\n", cfg.provider,
+              dir);
+    /* --ask-key alone: save and exit */
+    if (force_ask_key && !cfg.headless && !prompt) {
+      curl_global_cleanup();
+      return 0;
+    }
+  }
+  if (!cfg.api_key[0] && cfg.headless) {
+    fprintf(stderr,
+            "no API key for %s: start cst-agent once to enter it, or run "
+            "cst-agent --ask-key --provider %s\n",
+            cfg.provider, cfg.provider);
+    curl_global_cleanup();
+    return 1;
   }
 
-  fprintf(stderr, "using %s model=%s\n", cfg.api_base, cfg.model);
+  fprintf(stderr,
+          "using %s model=%s effort=%s protocol=%s tools=%s max_steps=%d\n",
+          cfg.api_base, cfg.model, cfg.effort, cst_protocol_name(cfg.protocol),
+          cst_tool_profile_name(cfg.tool_profile), cfg.max_steps);
 
   cst_agent_t *agent = cst_agent_create(&cfg);
   if (!agent) {

src/metrics.c

@@ -0,0 +1,86 @@
+#include "cst_metrics.h"
+
+#include "cJSON.h"
+#include "os_compat.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+struct cst_metrics {
+  FILE *fp;
+  char path[OS_PATH_MAX];
+};
+
+cst_metrics_t *cst_metrics_open(const char *workspace, const char *session_path) {
+  const char *off = getenv("CST_METRICS");
+  if (off && strcmp(off, "0") == 0)
+    return NULL;
+  cst_metrics_t *m = calloc(1, sizeof(*m));
+  if (!m)
+    return NULL;
+  const char *override = getenv("CST_METRICS_PATH");
+  if (override && override[0]) {
+    snprintf(m->path, sizeof(m->path), "%s", override);
+  } else {
+    if (!workspace)
+      workspace = ".";
+    char dir[OS_PATH_MAX], agent[OS_PATH_MAX];
+    os_path_join(agent, sizeof(agent), workspace, ".agent");
+    os_mkdir(agent, 0755);
+    os_path_join(dir, sizeof(dir), agent, "metrics");
+    os_mkdir(dir, 0755);
+    const char *base = session_path ? session_path : "session.jsonl";
+    const char *s1 = strrchr(base, '/');
+    const char *s2 = strrchr(base, '\\');
+    if (s2 && (!s1 || s2 > s1))
+      s1 = s2;
+    if (s1)
+      base = s1 + 1;
+    char leaf[256];
+    snprintf(leaf, sizeof(leaf), "%s", base);
+    size_t n = strlen(leaf);
+    if (n > 6 && strcmp(leaf + n - 6, ".jsonl") == 0)
+      leaf[n - 6] = 0;
+    char file[300];
+    snprintf(file, sizeof(file), "%s.jsonl", leaf);
+    os_path_join(m->path, sizeof(m->path), dir, file);
+  }
+  m->fp = fopen(m->path, "a");
+  if (!m->fp) {
+    free(m);
+    return NULL;
+  }
+  return m;
+}
+
+void cst_metrics_close(cst_metrics_t *m) {
+  if (!m)
+    return;
+  if (m->fp)
+    fclose(m->fp);
+  free(m);
+}
+
+void cst_metrics_emit(cst_metrics_t *m, void *obj) {
+  cJSON *o = obj;
+  if (!o)
+    return;
+  if (m && m->fp) {
+    if (!cJSON_GetObjectItemCaseSensitive(o, "ts"))
+      cJSON_AddNumberToObject(o, "ts", (double)time(NULL));
+    char *txt = cJSON_PrintUnformatted(o);
+    if (txt) {
+      fputs(txt, m->fp);
+      fputc('\n', m->fp);
+      fflush(m->fp);
+      free(txt);
+    }
+  }
+  cJSON_Delete(o);
+}
+
+const char *cst_metrics_path(const cst_metrics_t *m) {
+  return m ? m->path : NULL;
+}

src/mm_tool.c

@@ -329,6 +329,8 @@ static void strip_stray_closes(mm_scan_t *s) {
 
 /* Process buffer: emit text before tools, parse complete tool blocks. */
 static void drain(mm_scan_t *s) {
+  if (!s->buf)
+    return;
   for (;;) {
     if (!s->in_tool) {
       strip_stray_closes(s);

src/models.c

@@ -6,6 +6,28 @@
 
 #define MODEL_MAX_LEN 128
 
+static const cst_provider_t PROVIDERS[] = {
+    {"minimax", "https://api.minimax.cn/v1", "MiniMax-M2.7", "MINIMAX_API_KEY"},
+    {"deepseek", "https://api.deepseek.com/v1", "deepseek-flash",
+     "DEEPSEEK_API_KEY"},
+    {"openai", "https://api.openai.com/v1", "gpt-4.1-mini", "OPENAI_API_KEY"},
+};
+
+const cst_provider_t *cst_provider_find(const char *name) {
+  if (!name || !name[0])
+    return NULL;
+  for (size_t i = 0; i < sizeof(PROVIDERS) / sizeof(PROVIDERS[0]); i++) {
+    if (strcmp(PROVIDERS[i].name, name) == 0)
+      return &PROVIDERS[i];
+  }
+  return NULL;
+}
+
+const cst_provider_t *cst_provider_default(void) {
+  const cst_provider_t *p = cst_provider_find(getenv("CST_PROVIDER"));
+  return p ? p : &PROVIDERS[0];
+}
+
 static int already(char out[][MODEL_MAX_LEN], int n, const char *name) {
   for (int i = 0; i < n; i++) {
     if (strcmp(out[i], name) == 0)
@@ -44,7 +66,6 @@ int cst_models_list(const char *current, char out[][128], int max_out) {
         p++;
       char save = *p;
       *p = 0;
-      /* trim trailing spaces */
       char *end = start + strlen(start);
       while (end > start && (end[-1] == ' ' || end[-1] == '\t'))
         *--end = 0;
@@ -54,10 +75,12 @@ int cst_models_list(const char *current, char out[][128], int max_out) {
         p++;
     }
   } else {
+    push(out, &n, max_out, "deepseek-flash");
+    push(out, &n, max_out, "deepseek-v4-pro");
     push(out, &n, max_out, "MiniMax-M2.7");
     push(out, &n, max_out, "MiniMax-M2.5");
+    push(out, &n, max_out, "gpt-4.1-mini");
     push(out, &n, max_out, "gpt-4o");
-    push(out, &n, max_out, "gpt-4o-mini");
   }
 
   if (current && current[0])
@@ -65,3 +88,55 @@ int cst_models_list(const char *current, char out[][128], int max_out) {
 
   return n;
 }
+
+/* Context window in tokens (CST_CTX_TOKENS overrides). Prefix match. */
+long cst_model_context_tokens(const char *model) {
+  const char *e = getenv("CST_CTX_TOKENS");
+  if (e && atol(e) > 0)
+    return atol(e);
+  static const struct {
+    const char *prefix;
+    long tokens;
+  } T[] = {{"deepseek", 128000}, {"MiniMax", 196608}, {"minimax", 196608},
+           {"gpt-4.1", 1047576}, {"gpt-4o", 128000},  {"gpt-5", 400000},
+           {"o3", 200000},       {"o4", 200000},      {"claude", 200000},
+           {"qwen", 131072},     {"glm", 128000},     {"kimi", 131072}};
+  if (model) {
+    for (size_t i = 0; i < sizeof(T) / sizeof(T[0]); i++) {
+      if (strncmp(model, T[i].prefix, strlen(T[i].prefix)) == 0)
+        return T[i].tokens;
+    }
+  }
+  return 128000;
+}
+
+int cst_effort_valid(const char *effort) {
+  static const char *const ok[] = {"low", "medium", "high", "max"};
+  for (size_t i = 0; effort && i < sizeof(ok) / sizeof(ok[0]); i++) {
+    if (strcmp(effort, ok[i]) == 0)
+      return 1;
+  }
+  return 0;
+}
+
+const char *cst_effort_wire(const char *provider, const char *model,
+                            const char *effort) {
+  if (!cst_effort_valid(effort) || !provider || !model)
+    return NULL;
+  if (strcmp(provider, "deepseek") == 0)
+    return effort;
+  /* OpenAI reasoning models take low | medium | high. */
+  if (strcmp(provider, "openai") == 0 &&
+      (strncmp(model, "o1", 2) == 0 || strncmp(model, "o3", 2) == 0 ||
+       strncmp(model, "o4", 2) == 0 || strncmp(model, "gpt-5", 5) == 0))
+    return strcmp(effort, "max") == 0 ? "high" : effort;
+  return NULL;
+}
+
+int cst_provider_count(void) {
+  return (int)(sizeof(PROVIDERS) / sizeof(PROVIDERS[0]));
+}
+
+const cst_provider_t *cst_provider_at(int i) {
+  return i >= 0 && i < cst_provider_count() ? &PROVIDERS[i] : NULL;
+}

src/os_compat.c

@@ -1,8 +1,14 @@
+#ifndef _DEFAULT_SOURCE
 #define _DEFAULT_SOURCE
+#endif
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif
 
+#ifdef __APPLE__
+#include <mach-o/dyld.h>
+#include <stdint.h>
+#endif
 #include "os_compat.h"
 
 #include <errno.h>
@@ -21,9 +27,12 @@
 #include <windows.h>
 #else
 #include <fcntl.h>
+#include <poll.h>
+#include <signal.h>
 #include <sys/stat.h>
 #include <sys/types.h>
 #include <sys/wait.h>
+#include <time.h>
 #include <unistd.h>
 #endif
 
@@ -146,6 +155,22 @@ int os_mkdir(const char *path, int mode) {
 #endif
 }
 
+int os_mkdir_p(const char *path, int mode) {
+  if (!path || !path[0])
+    return -1;
+  char tmp[OS_PATH_MAX];
+  snprintf(tmp, sizeof(tmp), "%s", path);
+  for (char *p = tmp + 1; *p; p++) {
+    if (*p == '/' || *p == '\\') {
+      char c = *p;
+      *p = 0;
+      os_mkdir(tmp, mode);
+      *p = c;
+    }
+  }
+  return os_mkdir(tmp, mode);
+}
+
 int os_config_dir(char *out, size_t out_sz) {
   if (!out || out_sz < 8)
     return -1;
@@ -157,10 +182,15 @@ int os_config_dir(char *out, size_t out_sz) {
     return -1;
   int n = snprintf(out, out_sz, "%s\\cst-agent", base);
 #else
+  const char *xdg = getenv("XDG_CONFIG_HOME");
   const char *home = getenv("HOME");
-  if (!home || !home[0])
+  int n;
+  if (xdg && xdg[0] == '/')
+    n = snprintf(out, out_sz, "%s/cst-agent", xdg);
+  else if (home && home[0])
+    n = snprintf(out, out_sz, "%s/.config/cst-agent", home);
+  else
     return -1;
-  int n = snprintf(out, out_sz, "%s/.config/cst-agent", home);
 #endif
   if (n < 0 || (size_t)n >= out_sz)
     return -1;
@@ -258,7 +288,12 @@ int os_exe_dir(char *out, size_t out_sz) {
   return 0;
 #else
   char buf[OS_PATH_MAX];
+#ifdef __APPLE__
+  uint32_t asz = (uint32_t)sizeof(buf);
+  ssize_t n = _NSGetExecutablePath(buf, &asz) == 0 ? (ssize_t)strlen(buf) : -1;
+#else
   ssize_t n = readlink("/proc/self/exe", buf, sizeof(buf) - 1);
+#endif
   if (n >= 0) {
     buf[n] = 0;
     char *slash = strrchr(buf, '/');
@@ -343,6 +378,77 @@ int os_resolve_shell(char *out, size_t out_sz) {
 #endif
 }
 
+static volatile int *g_run_cancel;
+static int g_run_timeout_s;
+
+void os_set_cancel_flag(volatile int *flag) { g_run_cancel = flag; }
+
+void os_set_run_timeout(int seconds) { g_run_timeout_s = seconds; }
+
+static int run_timeout_s(void) {
+  if (g_run_timeout_s > 0)
+    return g_run_timeout_s;
+  const char *e = getenv("CST_SHELL_TIMEOUT");
+  if (e && atoi(e) > 0)
+    return atoi(e);
+  return 120;
+}
+
+double os_now_ms(void) {
+#ifdef _WIN32
+  static LARGE_INTEGER freq;
+  LARGE_INTEGER now;
+  if (!freq.QuadPart)
+    QueryPerformanceFrequency(&freq);
+  QueryPerformanceCounter(&now);
+  return (double)now.QuadPart * 1000.0 / (double)freq.QuadPart;
+#else
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (double)ts.tv_sec * 1000.0 + (double)ts.tv_nsec / 1e6;
+#endif
+}
+
+/* Append to capture buffer, keeping at most max_out bytes. */
+static int cap_append(char **buf, size_t *len, size_t *cap, size_t max_out,
+                      const char *data, size_t n, int *truncated) {
+  if (*len >= max_out) {
+    *truncated = 1;
+    return 0;
+  }
+  if (*len + n > max_out) {
+    n = max_out - *len;
+    *truncated = 1;
+  }
+  if (*len + n + 1 > *cap) {
+    size_t nc = *cap ? *cap * 2 : 4096;
+    while (nc < *len + n + 1)
+      nc *= 2;
+    char *nb = realloc(*buf, nc);
+    if (!nb)
+      return -1;
+    *buf = nb;
+    *cap = nc;
+  }
+  memcpy(*buf + *len, data, n);
+  *len += n;
+  (*buf)[*len] = 0;
+  return 0;
+}
+
+static void cap_note(char **buf, size_t *len, size_t *cap, const char *note) {
+  size_t n = strlen(note);
+  if (*len + n + 1 > *cap) {
+    char *nb = realloc(*buf, *len + n + 1);
+    if (!nb)
+      return;
+    *buf = nb;
+    *cap = *len + n + 1;
+  }
+  memcpy(*buf + *len, note, n + 1);
+  *len += n;
+}
+
 #ifdef _WIN32
 int os_run_capture(const char *cwd, const char *const argv[], size_t max_out,
                    os_run_result_t *r) {
@@ -396,7 +502,9 @@ int os_run_capture(const char *cwd, const char *const argv[], size_t max_out,
   si.dwFlags = STARTF_USESTDHANDLES;
   si.hStdOutput = wr;
   si.hStdError = wr;
-  si.hStdInput = GetStdHandle(STD_INPUT_HANDLE);
+  HANDLE nul = CreateFileA("NUL", GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_WRITE,
+                           &sa, OPEN_EXISTING, 0, NULL);
+  si.hStdInput = nul != INVALID_HANDLE_VALUE ? nul : GetStdHandle(STD_INPUT_HANDLE);
   PROCESS_INFORMATION pi = {0};
 
   char *cmd_mut = _strdup(cmdline);
@@ -409,6 +517,8 @@ int os_run_capture(const char *cwd, const char *const argv[], size_t max_out,
                            cwd && cwd[0] ? cwd : NULL, &si, &pi);
   free(cmd_mut);
   CloseHandle(wr);
+  if (nul != INVALID_HANDLE_VALUE)
+    CloseHandle(nul);
   if (!ok) {
     CloseHandle(rd);
     return -1;
@@ -422,30 +532,54 @@ int os_run_capture(const char *cwd, const char *const argv[], size_t max_out,
     CloseHandle(pi.hThread);
     return -1;
   }
+  buf[0] = 0;
+  int truncated = 0, killed = 0;
+  double deadline = os_now_ms() + run_timeout_s() * 1000.0;
   for (;;) {
-    char tmp[1024];
-    DWORD n = 0;
-    if (!ReadFile(rd, tmp, sizeof(tmp), &n, NULL) || n == 0)
-      break;
-    if (len + n + 1 > cap) {
-      size_t nc = cap * 2;
-      if (nc < len + n + 1)
-        nc = len + n + 1;
-      char *nb = realloc(buf, nc);
-      if (!nb)
+    DWORD avail = 0;
+    if (!PeekNamedPipe(rd, NULL, 0, NULL, &avail, NULL))
+      break; /* writer closed */
+    if (avail > 0) {
+      char tmp[4096];
+      DWORD n = 0;
+      if (!ReadFile(rd, tmp, sizeof(tmp), &n, NULL) || n == 0)
         break;
-      buf = nb;
-      cap = nc;
+      cap_append(&buf, &len, &cap, max_out, tmp, n, &truncated);
+      continue;
     }
-    memcpy(buf + len, tmp, n);
-    len += n;
-    if (len >= max_out)
+    if (WaitForSingleObject(pi.hProcess, 50) == WAIT_OBJECT_0) {
+      /* drain what is left */
+      while (PeekNamedPipe(rd, NULL, 0, NULL, &avail, NULL) && avail > 0) {
+        char tmp[4096];
+        DWORD n = 0;
+        if (!ReadFile(rd, tmp, sizeof(tmp), &n, NULL) || n == 0)
+          break;
+        cap_append(&buf, &len, &cap, max_out, tmp, n, &truncated);
+      }
       break;
+    }
+    if ((g_run_cancel && *g_run_cancel) || os_now_ms() > deadline) {
+      killed = (g_run_cancel && *g_run_cancel) ? 2 : 1;
+      TerminateProcess(pi.hProcess, killed == 1 ? 124 : 130);
+      break;
+    }
   }
   CloseHandle(rd);
   WaitForSingleObject(pi.hProcess, INFINITE);
   DWORD code = 1;
   GetExitCodeProcess(pi.hProcess, &code);
+  if (truncated)
+    cap_note(&buf, &len, &cap, "\n...(output truncated)\n");
+  if (killed == 1) {
+    char note[96];
+    snprintf(note, sizeof(note), "\n[cst: killed after %ds timeout]\n",
+             run_timeout_s());
+    cap_note(&buf, &len, &cap, note);
+    code = 124;
+  } else if (killed == 2) {
+    cap_note(&buf, &len, &cap, "\n[cst: cancelled]\n");
+    code = 130;
+  }
   CloseHandle(pi.hProcess);
   CloseHandle(pi.hThread);
   buf[len] = 0;
@@ -473,7 +607,13 @@ int os_run_capture(const char *cwd, const char *const argv[], size_t max_out,
     return -1;
   }
   if (pid == 0) {
+    setpgid(0, 0);
     close(pipefd[0]);
+    int devnull = open("/dev/null", O_RDONLY);
+    if (devnull >= 0) {
+      dup2(devnull, STDIN_FILENO);
+      close(devnull);
+    }
     dup2(pipefd[1], STDOUT_FILENO);
     dup2(pipefd[1], STDERR_FILENO);
     close(pipefd[1]);
@@ -482,41 +622,85 @@ int os_run_capture(const char *cwd, const char *const argv[], size_t max_out,
     execvp(argv[0], (char *const *)argv);
     _exit(127);
   }
+  setpgid(pid, pid); /* also in parent: avoid racing the child */
   close(pipefd[1]);
   size_t cap = 4096, len = 0;
   char *buf = malloc(cap);
   if (!buf) {
     close(pipefd[0]);
+    kill(-pid, SIGKILL);
     waitpid(pid, NULL, 0);
     return -1;
   }
+  buf[0] = 0;
+  int truncated = 0, killed = 0;
+  int status = 0, reaped = 0, bg_killed = 0;
+  double reaped_at = 0, killed_at = 0;
+  double deadline = os_now_ms() + run_timeout_s() * 1000.0;
   for (;;) {
-    if (len + 1024 > cap) {
-      cap *= 2;
-      char *nb = realloc(buf, cap);
-      if (!nb)
+    struct pollfd pfd = {pipefd[0], POLLIN, 0};
+    int pr = poll(&pfd, 1, 100);
+    if (pr < 0 && errno != EINTR)
+      break;
+    if (pr > 0) {
+      char tmp[4096];
+      ssize_t n = read(pipefd[0], tmp, sizeof(tmp));
+      if (n == 0)
+        break; /* every writer closed */
+      if (n > 0)
+        cap_append(&buf, &len, &cap, max_out, tmp, (size_t)n, &truncated);
+      else if (errno != EINTR && errno != EAGAIN)
         break;
-      buf = nb;
     }
-    ssize_t n = read(pipefd[0], buf + len, 1024);
-    if (n < 0) {
-      if (errno == EINTR)
-        continue;
-      break;
+    double now = os_now_ms();
+    if (!reaped && waitpid(pid, &status, WNOHANG) == pid) {
+      reaped = 1;
+      reaped_at = now;
     }
-    if (n == 0)
-      break;
-    len += (size_t)n;
-    if (len >= max_out)
+    /* The shell exited but a background child still holds the pipe
+     * (`server &`): give it a moment, then end the group. */
+    if (reaped && !killed && !bg_killed && now - reaped_at > 1000) {
+      kill(-pid, SIGKILL);
+      bg_killed = 1;
+      killed_at = now;
+    }
+    /* Checked on every pass, so a chatty command still stops promptly. */
+    if (!reaped && !killed &&
+        ((g_run_cancel && *g_run_cancel) || now > deadline)) {
+      killed = (g_run_cancel && *g_run_cancel) ? 2 : 1;
+      killed_at = now;
+      kill(-pid, SIGTERM);
+    }
+    if (killed && !reaped && now - killed_at > 1000)
+      kill(-pid, SIGKILL);
+    /* a writer that left the process group can keep the pipe open */
+    if ((killed || bg_killed) && now - killed_at > 3000)
       break;
   }
   close(pipefd[0]);
-  int status = 0;
-  waitpid(pid, &status, 0);
-  buf[len] = 0;
+  if (pid > 0 && !reaped) {
+    if (killed)
+      kill(-pid, SIGKILL);
+    waitpid(pid, &status, 0);
+  }
+  if (truncated)
+    cap_note(&buf, &len, &cap, "\n...(output truncated)\n");
+  if (bg_killed)
+    cap_note(&buf, &len, &cap,
+             "\n[cst: background processes left running were stopped]\n");
   r->out = buf;
   r->out_len = len;
   r->exit_code = WIFEXITED(status) ? WEXITSTATUS(status) : 1;
+  if (killed == 1) {
+    char note[96];
+    snprintf(note, sizeof(note), "\n[cst: killed after %ds timeout]\n",
+             run_timeout_s());
+    cap_note(&r->out, &r->out_len, &cap, note);
+    r->exit_code = 124;
+  } else if (killed == 2) {
+    cap_note(&r->out, &r->out_len, &cap, "\n[cst: cancelled]\n");
+    r->exit_code = 130;
+  }
   return 0;
 }
 #endif

src/permissions.c

@@ -0,0 +1,223 @@
+/* Persistent "always allow" rules: <ws>/.agent/permissions.json
+ *   {"tools": ["write_file"], "shell_prefixes": ["make", "git status"]} */
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "cJSON.h"
+#include "cst_perms.h"
+#include "cst_util.h"
+#include "os_compat.h"
+
+#define PERM_MAX 64
+
+struct cst_perms {
+  char path[OS_PATH_MAX];
+  char tools[PERM_MAX][64];
+  int ntools;
+  char prefixes[PERM_MAX][128];
+  int nprefixes;
+};
+
+static void load(cst_perms_t *p) {
+  FILE *fp = fopen(p->path, "rb");
+  if (!fp)
+    return;
+  cst_buf_t b = {0};
+  char tmp[4096];
+  size_t n;
+  while ((n = fread(tmp, 1, sizeof(tmp), fp)) > 0 && b.len < 256 * 1024)
+    cst_buf_append(&b, tmp, n);
+  fclose(fp);
+  cJSON *root = b.buf ? cJSON_Parse(b.buf) : NULL;
+  cst_buf_free(&b);
+  const cJSON *it = NULL;
+  cJSON_ArrayForEach(it, cJSON_GetObjectItemCaseSensitive(root, "tools")) {
+    if (cJSON_IsString(it) && p->ntools < PERM_MAX)
+      snprintf(p->tools[p->ntools++], 64, "%.63s", it->valuestring);
+  }
+  cJSON_ArrayForEach(it,
+                     cJSON_GetObjectItemCaseSensitive(root, "shell_prefixes")) {
+    if (cJSON_IsString(it) && p->nprefixes < PERM_MAX && it->valuestring[0])
+      snprintf(p->prefixes[p->nprefixes++], 128, "%.127s", it->valuestring);
+  }
+  cJSON_Delete(root);
+}
+
+cst_perms_t *cst_perms_open(const char *workspace) {
+  cst_perms_t *p = calloc(1, sizeof(*p));
+  if (!p)
+    return NULL;
+  if (workspace)
+    snprintf(p->path, sizeof(p->path), "%s/.agent/permissions.json",
+             workspace);
+  load(p);
+  return p;
+}
+
+void cst_perms_close(cst_perms_t *p) { free(p); }
+
+static int save(const cst_perms_t *p) {
+  if (!p->path[0])
+    return -1;
+  char dir[OS_PATH_MAX];
+  snprintf(dir, sizeof(dir), "%s", p->path);
+  char *sl = strrchr(dir, '/');
+  if (sl) {
+    *sl = 0;
+    os_mkdir_p(dir, 0755);
+  }
+  cJSON *root = cJSON_CreateObject();
+  cJSON *t = cJSON_AddArrayToObject(root, "tools");
+  for (int i = 0; i < p->ntools; i++)
+    cJSON_AddItemToArray(t, cJSON_CreateString(p->tools[i]));
+  cJSON *s = cJSON_AddArrayToObject(root, "shell_prefixes");
+  for (int i = 0; i < p->nprefixes; i++)
+    cJSON_AddItemToArray(s, cJSON_CreateString(p->prefixes[i]));
+  char *txt = cJSON_Print(root);
+  cJSON_Delete(root);
+  if (!txt)
+    return -1;
+  FILE *fp = fopen(p->path, "wb");
+  int rc = -1;
+  if (fp) {
+    rc = fputs(txt, fp) >= 0 && fputs("\n", fp) >= 0 ? 0 : -1;
+    if (fclose(fp) != 0)
+      rc = -1;
+  }
+  free(txt);
+  return rc;
+}
+
+/* Commands chained or substituted can hide anything behind an allowed
+ * prefix, so they always ask. */
+static int has_shell_meta(const char *cmd) {
+  return strpbrk(cmd, ";&|`$<>\n\r(){}") != NULL;
+}
+
+int cst_perms_shell_allowed(const cst_perms_t *p, const char *cmd) {
+  if (!p || !cmd)
+    return 0;
+  while (*cmd == ' ' || *cmd == '\t')
+    cmd++;
+  if (!*cmd || has_shell_meta(cmd))
+    return 0;
+  for (int i = 0; i < p->nprefixes; i++) {
+    size_t n = strlen(p->prefixes[i]);
+    if (strncmp(cmd, p->prefixes[i], n) == 0 &&
+        (cmd[n] == 0 || cmd[n] == ' ' || cmd[n] == '\t'))
+      return 1;
+  }
+  return 0;
+}
+
+int cst_perms_tool_allowed(const cst_perms_t *p, const char *tool) {
+  if (!p || !tool)
+    return 0;
+  for (int i = 0; i < p->ntools; i++) {
+    if (strcmp(p->tools[i], tool) == 0)
+      return 1;
+  }
+  return 0;
+}
+
+int cst_perms_allow_tool(cst_perms_t *p, const char *tool) {
+  if (!p || !tool || !tool[0])
+    return -1;
+  if (cst_perms_tool_allowed(p, tool))
+    return 0;
+  if (p->ntools >= PERM_MAX)
+    return -1;
+  snprintf(p->tools[p->ntools++], 64, "%.63s", tool);
+  return save(p);
+}
+
+int cst_perms_allow_prefix(cst_perms_t *p, const char *prefix) {
+  if (!p || !prefix)
+    return -1;
+  while (*prefix == ' ')
+    prefix++;
+  if (!prefix[0] || has_shell_meta(prefix))
+    return -1;
+  for (int i = 0; i < p->nprefixes; i++) {
+    if (strcmp(p->prefixes[i], prefix) == 0)
+      return 0;
+  }
+  if (p->nprefixes >= PERM_MAX)
+    return -1;
+  snprintf(p->prefixes[p->nprefixes++], 128, "%.127s", prefix);
+  return save(p);
+}
+
+int cst_perms_reset(cst_perms_t *p) {
+  if (!p)
+    return -1;
+  p->ntools = p->nprefixes = 0;
+  return save(p);
+}
+
+char *cst_perms_describe(const cst_perms_t *p) {
+  cst_buf_t b = {0};
+  cst_buf_puts(&b, "always allowed tools: ");
+  if (!p || !p->ntools)
+    cst_buf_puts(&b, "(none)");
+  for (int i = 0; p && i < p->ntools; i++)
+    cst_buf_printf(&b, "%s%s", i ? ", " : "", p->tools[i]);
+  cst_buf_puts(&b, "\nallowed shell prefixes: ");
+  if (!p || !p->nprefixes)
+    cst_buf_puts(&b, "(none)");
+  for (int i = 0; p && i < p->nprefixes; i++)
+    cst_buf_printf(&b, "%s`%s`", i ? ", " : "", p->prefixes[i]);
+  cst_buf_puts(&b, "\n");
+  return cst_buf_steal(&b);
+}
+
+/* "git status -s" → "git status"; "make -j8" → "make"; "./run.sh x" →
+ * "./run.sh". Tools with sub-commands keep two words. */
+void cst_perms_suggest_prefix(const char *cmd, char *out, size_t out_sz) {
+  static const char *const two_word[] = {"git", "npm", "pnpm", "yarn",
+                                         "cargo", "go", "docker", "kubectl",
+                                         "pip", "python", "python3", "uv",
+                                         "bun", "dotnet", "mvn", "gradle"};
+  /* A prefix rule for these would allow almost anything. */
+  static const char *const never[] = {
+      "sudo", "su",   "doas",  "rm",   "dd",    "mkfs", "shutdown", "reboot",
+      "sh",   "bash", "zsh",   "fish", "dash",  "env",  "xargs",    "eval",
+      "exec", "nohup", "time", "nice", "timeout", "find", "chmod",  "chown",
+      "curl", "wget", "ssh",   "scp",  "node",  "perl", "ruby",     "busybox"};
+  out[0] = 0;
+  if (!cmd)
+    return;
+  while (*cmd == ' ' || *cmd == '\t')
+    cmd++;
+  size_t w1 = strcspn(cmd, " \t");
+  if (w1 == 0)
+    return;
+  for (size_t i = 0; i < sizeof(never) / sizeof(never[0]); i++) {
+    if (strlen(never[i]) == w1 && strncmp(cmd, never[i], w1) == 0)
+      return;
+  }
+  size_t take = w1;
+  for (size_t i = 0; i < sizeof(two_word) / sizeof(two_word[0]); i++) {
+    if (strlen(two_word[i]) == w1 && strncmp(cmd, two_word[i], w1) == 0) {
+      const char *r = cmd + w1;
+      while (*r == ' ' || *r == '\t')
+        r++;
+      size_t w2 = strcspn(r, " \t");
+      if (w2 == 0 || r[0] == '-')
+        return; /* "python3 -c ..." / bare "git": no safe rule */
+      take = (size_t)(r - cmd) + w2;
+      break;
+    }
+  }
+  if (take >= out_sz)
+    take = out_sz - 1;
+  memcpy(out, cmd, take);
+  out[take] = 0;
+  if (has_shell_meta(out))
+    out[0] = 0;
+}

src/sandbox.c

@@ -1,4 +1,6 @@
+#ifndef _DEFAULT_SOURCE
 #define _DEFAULT_SOURCE
+#endif
 
 #include <stdio.h>
 #include <stdlib.h>

src/session.c

@@ -1,10 +1,14 @@
+#ifndef _DEFAULT_SOURCE
 #define _DEFAULT_SOURCE
+#endif
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif
 
+#include "cJSON.h"
 #include "cst_agent.h"
 
+#include <pthread.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -49,6 +53,7 @@ struct cst_session {
   int nmsgs;
   int cap;
   FILE *fp;
+  pthread_mutex_t mu;
 };
 
 static char *xstrdup(const char *s) {
@@ -77,6 +82,8 @@ static const char *role_str(cst_role_t r) {
 }
 
 static cst_role_t role_from(const char *s) {
+  if (!s)
+    return CST_ROLE_USER;
   if (strcmp(s, "system") == 0)
     return CST_ROLE_SYSTEM;
   if (strcmp(s, "assistant") == 0)
@@ -86,60 +93,11 @@ static cst_role_t role_from(const char *s) {
   return CST_ROLE_USER;
 }
 
-static int json_escape_write(FILE *fp, const char *s) {
-  fputc('"', fp);
-  for (; s && *s; s++) {
-    unsigned char c = (unsigned char)*s;
-    if (c == '"' || c == '\\') {
-      fputc('\\', fp);
-      fputc(c, fp);
-    } else if (c == '\n') {
-      fputs("\\n", fp);
-    } else if (c == '\r') {
-      fputs("\\r", fp);
-    } else if (c == '\t') {
-      fputs("\\t", fp);
-    } else if (c < 0x20) {
-      fprintf(fp, "\\u%04x", c);
-    } else {
-      fputc(c, fp);
-    }
-  }
-  fputc('"', fp);
-  return 0;
-}
-
-/* Minimal extract "key":"value" from a single JSONL object line. */
-static int extract_str(const char *line, const char *key, char *out,
-                       size_t out_sz) {
-  char pat[64];
-  snprintf(pat, sizeof(pat), "\"%s\":\"", key);
-  const char *p = strstr(line, pat);
-  if (!p)
-    return -1;
-  p += strlen(pat);
-  size_t o = 0;
-  while (*p && o + 1 < out_sz) {
-    if (*p == '\\' && p[1]) {
-      p++;
-      if (*p == 'n')
-        out[o++] = '\n';
-      else if (*p == 'r')
-        out[o++] = '\r';
-      else if (*p == 't')
-        out[o++] = '\t';
-      else
-        out[o++] = *p;
-      p++;
-      continue;
-    }
-    if (*p == '"') {
-      out[o] = 0;
-      return 0;
-    }
-    out[o++] = *p++;
-  }
-  return -1;
+static void msg_free(cst_message_t *m) {
+  free(m->content);
+  free(m->tool_calls_json);
+  free(m->meta_json);
+  m->content = m->tool_calls_json = m->meta_json = NULL;
 }
 
 static int session_grow(cst_session_t *s) {
@@ -154,27 +112,30 @@ static int session_grow(cst_session_t *s) {
   return 0;
 }
 
-static int session_push_mem(cst_session_t *s, cst_role_t role, const char *content,
-                            const char *tool_id, const char *tool_name,
-                            const char *tool_calls_json) {
+static int session_push_mem(cst_session_t *s, const cst_message_t *src) {
   if (session_grow(s) != 0)
     return -1;
   cst_message_t *d = &s->msgs[s->nmsgs];
   memset(d, 0, sizeof(*d));
-  d->role = role;
-  d->content = xstrdup(content ? content : "");
+  d->role = src->role;
+  d->content = xstrdup(src->content ? src->content : "");
   if (!d->content)
     return -1;
-  if (tool_id)
-    snprintf(d->tool_call_id, sizeof(d->tool_call_id), "%s", tool_id);
-  if (tool_name)
-    snprintf(d->tool_name, sizeof(d->tool_name), "%s", tool_name);
-  if (tool_calls_json && tool_calls_json[0])
-    d->tool_calls_json = xstrdup(tool_calls_json);
+  snprintf(d->tool_call_id, sizeof(d->tool_call_id), "%s", src->tool_call_id);
+  snprintf(d->tool_name, sizeof(d->tool_name), "%s", src->tool_name);
+  if (src->tool_calls_json && src->tool_calls_json[0])
+    d->tool_calls_json = xstrdup(src->tool_calls_json);
+  if (src->meta_json && src->meta_json[0])
+    d->meta_json = xstrdup(src->meta_json);
   s->nmsgs++;
   return 0;
 }
 
+static const char *jstr(const cJSON *o, const char *key) {
+  const cJSON *it = cJSON_GetObjectItemCaseSensitive(o, key);
+  return cJSON_IsString(it) ? it->valuestring : NULL;
+}
+
 static void load_existing(cst_session_t *s) {
   FILE *rp = fopen(s->path, "r");
   if (!rp)
@@ -182,116 +143,142 @@ static void load_existing(cst_session_t *s) {
   char *line = NULL;
   size_t cap = 0;
   while (getline(&line, &cap, rp) != -1) {
-    char role[32] = {0};
-    char *content = malloc(cap > 8 ? cap : 4096);
-    char tid[CTL_MAX_ID] = {0};
-    char tname[CTL_MAX_NAME] = {0};
-    if (!content)
-      continue;
-    content[0] = 0;
-    if (extract_str(line, "role", role, sizeof(role)) != 0) {
-      free(content);
+    cJSON *o = cJSON_Parse(line);
+    if (!o || !cJSON_IsObject(o)) {
+      cJSON_Delete(o);
       continue;
     }
-    /* content may be large — reuse line extract into growing buffer */
-    free(content);
-    content = malloc(strlen(line) + 1);
-    if (!content)
-      continue;
-    if (extract_str(line, "content", content, strlen(line) + 1) != 0) {
-      free(content);
+    const char *role = jstr(o, "role");
+    if (!role) {
+      cJSON_Delete(o);
       continue;
     }
-    extract_str(line, "tool_call_id", tid, sizeof(tid));
-    extract_str(line, "tool_name", tname, sizeof(tname));
-    char *tcj = malloc(strlen(line) + 1);
-    const char *tcjp = NULL;
-    if (tcj) {
-      tcj[0] = 0;
-      if (extract_str(line, "tool_calls_json", tcj, strlen(line) + 1) == 0)
-        tcjp = tcj;
-    }
-    session_push_mem(s, role_from(role), content, tid[0] ? tid : NULL,
-                     tname[0] ? tname : NULL, tcjp);
+    cst_message_t m = {0};
+    m.role = role_from(role);
+    m.content = (char *)(jstr(o, "content") ? jstr(o, "content") : "");
+    const char *tid = jstr(o, "tool_call_id");
+    const char *tname = jstr(o, "tool_name");
+    if (tid)
+      snprintf(m.tool_call_id, sizeof(m.tool_call_id), "%s", tid);
+    if (tname)
+      snprintf(m.tool_name, sizeof(m.tool_name), "%s", tname);
+    char *tcj = NULL;
+    const cJSON *tc = cJSON_GetObjectItemCaseSensitive(o, "tool_calls");
+    if (cJSON_IsArray(tc))
+      tcj = cJSON_PrintUnformatted(tc);
+    else if (jstr(o, "tool_calls_json")) /* legacy string field */
+      tcj = xstrdup(jstr(o, "tool_calls_json"));
+    m.tool_calls_json = tcj;
+    char *meta = NULL;
+    const cJSON *mo = cJSON_GetObjectItemCaseSensitive(o, "meta");
+    if (cJSON_IsObject(mo))
+      meta = cJSON_PrintUnformatted(mo);
+    m.meta_json = meta;
+    session_push_mem(s, &m);
     free(tcj);
-    free(content);
+    free(meta);
+    cJSON_Delete(o);
   }
   free(line);
   fclose(rp);
 }
 
+static void free_all(cst_session_t *s) {
+  for (int i = 0; i < s->nmsgs; i++)
+    msg_free(&s->msgs[i]);
+  s->nmsgs = 0;
+}
+
 cst_session_t *cst_session_open(const char *path) {
   cst_session_t *s = calloc(1, sizeof(*s));
   if (!s)
     return NULL;
+  pthread_mutex_init(&s->mu, NULL);
   snprintf(s->path, sizeof(s->path), "%s", path ? path : "session.jsonl");
   load_existing(s);
   s->fp = fopen(s->path, "a+");
-  if (!s->fp) {
-    for (int i = 0; i < s->nmsgs; i++) {
-      free(s->msgs[i].content);
-      free(s->msgs[i].tool_calls_json);
-    }
+  if (!s->fp || session_grow(s) != 0) {
+    if (s->fp)
+      fclose(s->fp);
+    free_all(s);
     free(s->msgs);
+    pthread_mutex_destroy(&s->mu);
     free(s);
     return NULL;
   }
-  if (!s->msgs) {
-    s->cap = 32;
-    s->msgs = calloc((size_t)s->cap, sizeof(cst_message_t));
-    if (!s->msgs) {
-      fclose(s->fp);
-      free(s);
-      return NULL;
-    }
-  }
   return s;
 }
 
 void cst_session_close(cst_session_t *s) {
   if (!s)
     return;
-  for (int i = 0; i < s->nmsgs; i++) {
-    free(s->msgs[i].content);
-    free(s->msgs[i].tool_calls_json);
-  }
+  free_all(s);
   free(s->msgs);
   if (s->fp)
     fclose(s->fp);
+  pthread_mutex_destroy(&s->mu);
   free(s);
 }
 
+void cst_session_lock(cst_session_t *s) {
+  if (s)
+    pthread_mutex_lock(&s->mu);
+}
+
+void cst_session_unlock(cst_session_t *s) {
+  if (s)
+    pthread_mutex_unlock(&s->mu);
+}
+
+static int write_line(FILE *fp, const cst_message_t *msg) {
+  cJSON *o = cJSON_CreateObject();
+  if (!o)
+    return -1;
+  cJSON_AddStringToObject(o, "role", role_str(msg->role));
+  cJSON_AddStringToObject(o, "content", msg->content ? msg->content : "");
+  if (msg->tool_call_id[0])
+    cJSON_AddStringToObject(o, "tool_call_id", msg->tool_call_id);
+  if (msg->tool_name[0])
+    cJSON_AddStringToObject(o, "tool_name", msg->tool_name);
+  if (msg->tool_calls_json && msg->tool_calls_json[0]) {
+    cJSON *tc = cJSON_Parse(msg->tool_calls_json);
+    if (cJSON_IsArray(tc))
+      cJSON_AddItemToObject(o, "tool_calls", tc);
+    else {
+      cJSON_Delete(tc);
+      cJSON_AddStringToObject(o, "tool_calls_json", msg->tool_calls_json);
+    }
+  }
+  if (msg->meta_json && msg->meta_json[0]) {
+    cJSON *mo = cJSON_Parse(msg->meta_json);
+    if (cJSON_IsObject(mo))
+      cJSON_AddItemToObject(o, "meta", mo);
+    else
+      cJSON_Delete(mo);
+  }
+  char *txt = cJSON_PrintUnformatted(o);
+  cJSON_Delete(o);
+  if (!txt)
+    return -1;
+  fputs(txt, fp);
+  fputc('\n', fp);
+  free(txt);
+  fflush(fp);
+  return 0;
+}
+
 int cst_session_append(cst_session_t *s, const cst_message_t *msg) {
   if (!s || !msg)
     return -1;
-  if (session_push_mem(s, msg->role, msg->content, msg->tool_call_id,
-                       msg->tool_name, msg->tool_calls_json) != 0)
-    return -1;
-
-  fprintf(s->fp, "{\"role\":");
-  json_escape_write(s->fp, role_str(msg->role));
-  fprintf(s->fp, ",\"content\":");
-  json_escape_write(s->fp, msg->content ? msg->content : "");
-  if (msg->tool_call_id[0]) {
-    fprintf(s->fp, ",\"tool_call_id\":");
-    json_escape_write(s->fp, msg->tool_call_id);
-  }
-  if (msg->tool_name[0]) {
-    fprintf(s->fp, ",\"tool_name\":");
-    json_escape_write(s->fp, msg->tool_name);
-  }
-  if (msg->tool_calls_json && msg->tool_calls_json[0]) {
-    fprintf(s->fp, ",\"tool_calls_json\":");
-    json_escape_write(s->fp, msg->tool_calls_json);
-  }
-  fprintf(s->fp, "}\n");
-  fflush(s->fp);
-  return 0;
+  pthread_mutex_lock(&s->mu);
+  int rc = session_push_mem(s, msg);
+  if (rc == 0 && s->fp)
+    rc = write_line(s->fp, msg);
+  pthread_mutex_unlock(&s->mu);
+  return rc;
 }
 
-int cst_session_count(const cst_session_t *s) {
-  return s ? s->nmsgs : 0;
-}
+int cst_session_count(const cst_session_t *s) { return s ? s->nmsgs : 0; }
 
 const cst_message_t *cst_session_get(const cst_session_t *s, int i) {
   if (!s || i < 0 || i >= s->nmsgs)
@@ -303,9 +290,19 @@ const char *cst_session_path(const cst_session_t *s) {
   return s ? s->path : NULL;
 }
 
+static int reopen_truncate(cst_session_t *s) {
+  if (s->fp) {
+    fclose(s->fp);
+    s->fp = NULL;
+  }
+  s->fp = fopen(s->path, "w+");
+  return s->fp ? 0 : -1;
+}
+
 int cst_session_clear(cst_session_t *s, int keep_system) {
   if (!s)
     return -1;
+  pthread_mutex_lock(&s->mu);
   cst_message_t sys = {0};
   int have_sys = 0;
   if (keep_system) {
@@ -313,51 +310,49 @@ int cst_session_clear(cst_session_t *s, int keep_system) {
       if (s->msgs[i].role == CST_ROLE_SYSTEM) {
         sys.role = CST_ROLE_SYSTEM;
         sys.content = xstrdup(s->msgs[i].content ? s->msgs[i].content : "");
-        have_sys = 1;
+        have_sys = sys.content != NULL;
         break;
       }
     }
   }
-  for (int i = 0; i < s->nmsgs; i++) {
-    free(s->msgs[i].content);
-    free(s->msgs[i].tool_calls_json);
+  free_all(s);
+  int rc = reopen_truncate(s);
+  if (rc == 0 && have_sys) {
+    session_push_mem(s, &sys);
+    write_line(s->fp, &sys);
   }
-  s->nmsgs = 0;
-  if (s->fp) {
-    fclose(s->fp);
-    s->fp = NULL;
-  }
-  s->fp = fopen(s->path, "w+");
-  if (!s->fp) {
-    if (have_sys)
-      free(sys.content);
-    return -1;
-  }
-  if (have_sys) {
-    cst_session_append(s, &sys);
-    free(sys.content);
-  }
-  return 0;
+  free(sys.content);
+  pthread_mutex_unlock(&s->mu);
+  return rc;
 }
 
 int cst_session_rewrite(cst_session_t *s, const cst_message_t *msgs, int n) {
   if (!s || n < 0)
     return -1;
-  for (int i = 0; i < s->nmsgs; i++) {
-    free(s->msgs[i].content);
-    free(s->msgs[i].tool_calls_json);
-  }
-  s->nmsgs = 0;
-  if (s->fp) {
-    fclose(s->fp);
-    s->fp = NULL;
-  }
-  s->fp = fopen(s->path, "w+");
-  if (!s->fp)
+  /* msgs may point into this session's own storage: copy before freeing. */
+  cst_message_t *copy = calloc((size_t)(n ? n : 1), sizeof(*copy));
+  if (!copy)
     return -1;
   for (int i = 0; i < n; i++) {
-    if (cst_session_append(s, &msgs[i]) != 0)
-      return -1;
+    copy[i] = msgs[i];
+    copy[i].content = strdup(msgs[i].content ? msgs[i].content : "");
+    copy[i].tool_calls_json =
+        msgs[i].tool_calls_json ? strdup(msgs[i].tool_calls_json) : NULL;
+    copy[i].meta_json = msgs[i].meta_json ? strdup(msgs[i].meta_json) : NULL;
   }
-  return 0;
+  pthread_mutex_lock(&s->mu);
+  free_all(s);
+  int rc = reopen_truncate(s);
+  for (int i = 0; rc == 0 && i < n; i++) {
+    if (session_push_mem(s, &copy[i]) != 0 || write_line(s->fp, &copy[i]) != 0)
+      rc = -1;
+  }
+  pthread_mutex_unlock(&s->mu);
+  for (int i = 0; i < n; i++) {
+    free(copy[i].content);
+    free(copy[i].tool_calls_json);
+    free(copy[i].meta_json);
+  }
+  free(copy);
+  return rc;
 }

src/settings.c

@@ -0,0 +1,121 @@
+#include "cst_agent.h"
+#include "os_compat.h"
+
+#include "cJSON.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int settings_path(char *out, size_t n) {
+  char dir[OS_PATH_MAX];
+  if (os_config_dir(dir, sizeof(dir)) != 0)
+    return -1;
+  return os_path_join(out, n, dir, "settings.json");
+}
+
+static void copy_str(char *dst, size_t n, const cJSON *v) {
+  if (cJSON_IsString(v) && v->valuestring)
+    snprintf(dst, n, "%s", v->valuestring);
+}
+
+int cst_settings_load(cst_settings_t *s) {
+  memset(s, 0, sizeof(*s));
+  char path[OS_PATH_MAX];
+  if (settings_path(path, sizeof(path)) != 0)
+    return -1;
+  FILE *fp = fopen(path, "rb");
+  if (!fp)
+    return -1;
+  char buf[16384];
+  size_t n = fread(buf, 1, sizeof(buf) - 1, fp);
+  fclose(fp);
+  buf[n] = 0;
+  cJSON *root = cJSON_Parse(buf);
+  if (!cJSON_IsObject(root)) {
+    cJSON_Delete(root);
+    return -1;
+  }
+  copy_str(s->provider, sizeof(s->provider),
+           cJSON_GetObjectItemCaseSensitive(root, "provider"));
+  copy_str(s->effort, sizeof(s->effort),
+           cJSON_GetObjectItemCaseSensitive(root, "effort"));
+  const cJSON *models = cJSON_GetObjectItemCaseSensitive(root, "models");
+  const cJSON *m;
+  cJSON_ArrayForEach(m, models) {
+    if (s->nmodels >= CST_SETTINGS_MAX_MODELS)
+      break;
+    if (!m->string || !cJSON_IsString(m))
+      continue;
+    snprintf(s->models[s->nmodels].provider,
+             sizeof(s->models[s->nmodels].provider), "%s", m->string);
+    copy_str(s->models[s->nmodels].model, sizeof(s->models[s->nmodels].model),
+             m);
+    s->nmodels++;
+  }
+  cJSON_Delete(root);
+  return 0;
+}
+
+int cst_settings_save(const cst_settings_t *s) {
+  char dir[OS_PATH_MAX], path[OS_PATH_MAX], tmp[OS_PATH_MAX + 8];
+  if (os_config_dir(dir, sizeof(dir)) != 0 || os_mkdir_p(dir, 0700) != 0 ||
+      settings_path(path, sizeof(path)) != 0)
+    return -1;
+  if (snprintf(tmp, sizeof(tmp), "%s.tmp", path) >= (int)sizeof(tmp))
+    return -1;
+  cJSON *root = cJSON_CreateObject();
+  if (s->provider[0])
+    cJSON_AddStringToObject(root, "provider", s->provider);
+  if (s->effort[0])
+    cJSON_AddStringToObject(root, "effort", s->effort);
+  cJSON *models = cJSON_AddObjectToObject(root, "models");
+  for (int i = 0; i < s->nmodels; i++)
+    cJSON_AddStringToObject(models, s->models[i].provider, s->models[i].model);
+  char *text = cJSON_Print(root);
+  cJSON_Delete(root);
+  if (!text)
+    return -1;
+  FILE *fp = fopen(tmp, "wb");
+  int rc = -1;
+  if (fp) {
+    int ok = fputs(text, fp) >= 0 && fputc('\n', fp) != EOF;
+    if (fclose(fp) == 0 && ok) {
+#ifdef _WIN32
+      remove(path);
+#endif
+      rc = rename(tmp, path) == 0 ? 0 : -1;
+    }
+    if (rc != 0)
+      remove(tmp);
+  }
+  cJSON_free(text);
+  return rc;
+}
+
+const char *cst_settings_model(const cst_settings_t *s, const char *provider) {
+  for (int i = 0; provider && i < s->nmodels; i++) {
+    if (strcmp(s->models[i].provider, provider) == 0 && s->models[i].model[0])
+      return s->models[i].model;
+  }
+  return NULL;
+}
+
+int cst_settings_remember(const cst_agent_config_t *cfg) {
+  cst_settings_t s;
+  cst_settings_load(&s);
+  snprintf(s.provider, sizeof(s.provider), "%s", cfg->provider);
+  snprintf(s.effort, sizeof(s.effort), "%s", cfg->effort);
+  int i = 0;
+  while (i < s.nmodels && strcmp(s.models[i].provider, cfg->provider) != 0)
+    i++;
+  if (i == s.nmodels) {
+    if (s.nmodels >= CST_SETTINGS_MAX_MODELS)
+      return -1;
+    s.nmodels++;
+  }
+  snprintf(s.models[i].provider, sizeof(s.models[i].provider), "%s",
+           cfg->provider);
+  snprintf(s.models[i].model, sizeof(s.models[i].model), "%s", cfg->model);
+  return cst_settings_save(&s);
+}

src/tools/agent_tools.c

@@ -0,0 +1,108 @@
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "cst_tools.h"
+#include "cst_util.h"
+#include "tools_internal.h"
+
+/* Accepts `[ ] x`, `- [x] x`, `[~] x`, `* [-] x`; bare lines count as todo. */
+static int todo_line(const char *s, size_t n, char *mark, const char **text,
+                     size_t *tn) {
+  while (n && (*s == ' ' || *s == '\t')) {
+    s++;
+    n--;
+  }
+  while (n && (s[n - 1] == ' ' || s[n - 1] == '\r' || s[n - 1] == '\t'))
+    n--;
+  if (n && (*s == '-' || *s == '*') && n > 1 && s[1] == ' ') {
+    s += 2;
+    n -= 2;
+  }
+  if (!n)
+    return 0;
+  *mark = ' ';
+  if (n >= 3 && s[0] == '[' && s[2] == ']') {
+    char m = s[1];
+    if (m == 'x' || m == 'X')
+      *mark = 'x';
+    else if (m == '~' || m == '-' || m == '>' || m == '/')
+      *mark = '~';
+    s += 3;
+    n -= 3;
+    while (n && *s == ' ') {
+      s++;
+      n--;
+    }
+  }
+  if (!n)
+    return 0;
+  *text = s;
+  *tn = n;
+  return 1;
+}
+
+int cst_tool_todo_write(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                        cst_tool_result_t *r) {
+  size_t len = 0;
+  const char *todos = tool_arg_n(c, "todos", &len);
+  if (!todos)
+    return tool_set_result(r, "error: missing todos", 1);
+  cst_buf_t list = {0};
+  int total = 0, done = 0, doing = 0;
+  for (size_t i = 0; i < len;) {
+    const char *e = memchr(todos + i, '\n', len - i);
+    size_t end = e ? (size_t)(e - todos) : len;
+    char mark;
+    const char *text;
+    size_t tn;
+    if (todo_line(todos + i, end - i, &mark, &text, &tn)) {
+      cst_buf_printf(&list, "[%c] ", mark);
+      cst_buf_append(&list, text, tn);
+      cst_buf_puts(&list, "\n");
+      total++;
+      done += mark == 'x';
+      doing += mark == '~';
+    }
+    i = end + 1;
+  }
+  if (!total) {
+    cst_buf_free(&list);
+    return tool_set_result(r, "error: no todo items (one per line: `[ ] task`)",
+                           1);
+  }
+  if (ctx->set_todo)
+    ctx->set_todo(list.buf, ctx->todo_ud);
+  cst_buf_t b = {0};
+  cst_buf_printf(&b, "todo list updated: %d/%d done, %d in progress\n", done,
+                 total, doing);
+  cst_buf_append(&b, list.buf, list.len);
+  cst_buf_free(&list);
+  return tool_take_buf(r, &b, 0);
+}
+
+int cst_tool_ask_user(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                      cst_tool_result_t *r) {
+  const char *q = tool_arg(c, "question");
+  const char *opts = tool_arg(c, "options");
+  if (!q || !q[0])
+    return tool_set_result(r, "error: missing question", 1);
+  if (!ctx->ask)
+    return tool_set_result(r,
+                           "error: no interactive user is available (headless "
+                           "run). Decide yourself and state the assumption "
+                           "in your answer.",
+                           1);
+  char ans[2048];
+  ans[0] = 0;
+  if (ctx->ask(q, opts, ans, sizeof(ans), ctx->ask_ud) != 0)
+    return tool_set_result(r,
+                           "the user dismissed the question without "
+                           "answering; continue with your best judgement",
+                           1);
+  return tool_set_resultf(r, 0, "user answered: %s", ans);
+}

src/tools/diff.c

@@ -0,0 +1,280 @@
+/* Line diff (Myers O(ND)) rendered like GNU `diff -u`. */
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "cst_tools.h"
+#include "cst_util.h"
+
+#define DIFF_CONTEXT 3
+/* Edit distance beyond this falls back to "replace the changed middle" so
+ * the trace stays O(DMAX^2) ints. */
+#define DIFF_DMAX 2000
+
+typedef struct {
+  const char *p;
+  size_t n;
+  int nl; /* line ended with '\n' */
+  uint64_t h;
+} dline_t;
+
+typedef struct {
+  char op; /* ' ', '-', '+' */
+  const dline_t *l;
+} dop_t;
+
+static dline_t *split_lines(const char *s, size_t len, int *count) {
+  int cap = 64, n = 0;
+  dline_t *v = malloc((size_t)cap * sizeof(*v));
+  if (!v)
+    return NULL;
+  size_t i = 0;
+  while (i < len) {
+    const char *nl = memchr(s + i, '\n', len - i);
+    size_t e = nl ? (size_t)(nl - s) : len;
+    if (n == cap) {
+      cap *= 2;
+      dline_t *nv = realloc(v, (size_t)cap * sizeof(*v));
+      if (!nv) {
+        free(v);
+        return NULL;
+      }
+      v = nv;
+    }
+    v[n].p = s + i;
+    v[n].n = e - i;
+    v[n].nl = nl != NULL;
+    v[n].h = cst_fnv1a64(CST_FNV_INIT, s + i, e - i) ^ (uint64_t)v[n].nl;
+    n++;
+    i = nl ? e + 1 : len;
+  }
+  *count = n;
+  return v;
+}
+
+static int line_eq(const dline_t *a, const dline_t *b) {
+  return a->h == b->h && a->n == b->n && a->nl == b->nl &&
+         memcmp(a->p, b->p, a->n) == 0;
+}
+
+/* Middle section edit script into ops (appended). Returns 0 or -1 (oom). */
+static int myers(const dline_t *a, int N, const dline_t *b, int M, dop_t *ops,
+                 int *nops) {
+  int dmax = N + M;
+  if (dmax > DIFF_DMAX)
+    dmax = DIFF_DMAX;
+  int off = dmax + 1;
+  int *V = calloc((size_t)(2 * dmax + 3), sizeof(int));
+  int **trace = calloc((size_t)dmax + 1, sizeof(int *));
+  if (!V || !trace) {
+    free(V);
+    free(trace);
+    return -1;
+  }
+  int found = -1;
+  for (int d = 0; d <= dmax && found < 0; d++) {
+    for (int k = -d; k <= d; k += 2) {
+      int x;
+      if (k == -d || (k != d && V[off + k - 1] < V[off + k + 1]))
+        x = V[off + k + 1];
+      else
+        x = V[off + k - 1] + 1;
+      int y = x - k;
+      while (x < N && y < M && line_eq(&a[x], &b[y])) {
+        x++;
+        y++;
+      }
+      V[off + k] = x;
+      if (x >= N && y >= M) {
+        found = d;
+        break;
+      }
+    }
+    trace[d] = malloc((size_t)(2 * d + 1) * sizeof(int));
+    if (!trace[d]) {
+      found = -2;
+      break;
+    }
+    memcpy(trace[d], V + off - d, (size_t)(2 * d + 1) * sizeof(int));
+  }
+
+  int rc = 0;
+  if (found < 0) {
+    /* too different (or oom): delete the old middle, insert the new one */
+    for (int i = 0; i < N; i++)
+      ops[(*nops)++] = (dop_t){'-', &a[i]};
+    for (int j = 0; j < M; j++)
+      ops[(*nops)++] = (dop_t){'+', &b[j]};
+  } else {
+    /* backtrack into a reversed list */
+    dop_t *rev = malloc((size_t)(N + M + 1) * sizeof(dop_t));
+    if (!rev) {
+      rc = -1;
+    } else {
+      int nr = 0, x = N, y = M;
+      for (int d = found; d > 0; d--) {
+        const int *P = trace[d - 1]; /* index k + (d-1) */
+        int k = x - y;
+        int pk;
+        if (k == -d ||
+            (k != d && P[k - 1 + (d - 1)] < P[k + 1 + (d - 1)]))
+          pk = k + 1;
+        else
+          pk = k - 1;
+        int px = P[pk + (d - 1)];
+        int py = px - pk;
+        while (x > px && y > py) {
+          rev[nr++] = (dop_t){' ', &a[x - 1]};
+          x--;
+          y--;
+        }
+        if (x == px)
+          rev[nr++] = (dop_t){'+', &b[y - 1]};
+        else
+          rev[nr++] = (dop_t){'-', &a[x - 1]};
+        x = px;
+        y = py;
+      }
+      while (x > 0 && y > 0) {
+        rev[nr++] = (dop_t){' ', &a[x - 1]};
+        x--;
+        y--;
+      }
+      for (int i = nr - 1; i >= 0; i--)
+        ops[(*nops)++] = rev[i];
+      free(rev);
+    }
+  }
+  for (int d = 0; d <= dmax; d++)
+    free(trace[d]);
+  free(trace);
+  free(V);
+  return rc;
+}
+
+/* Within each run of changes put deletions before insertions (GNU order). */
+static void normalize_runs(dop_t *ops, int n, dop_t *tmp) {
+  int i = 0;
+  while (i < n) {
+    if (ops[i].op == ' ') {
+      i++;
+      continue;
+    }
+    int j = i;
+    while (j < n && ops[j].op != ' ')
+      j++;
+    int t = 0;
+    for (int k = i; k < j; k++)
+      if (ops[k].op == '-')
+        tmp[t++] = ops[k];
+    for (int k = i; k < j; k++)
+      if (ops[k].op == '+')
+        tmp[t++] = ops[k];
+    memcpy(ops + i, tmp, (size_t)(j - i) * sizeof(dop_t));
+    i = j;
+  }
+}
+
+static void range(cst_buf_t *b, char sign, int before, int count) {
+  int start = count == 0 ? before : before + 1;
+  if (count == 1)
+    cst_buf_printf(b, "%c%d", sign, start);
+  else
+    cst_buf_printf(b, "%c%d,%d", sign, start, count);
+}
+
+static void emit_line(cst_buf_t *b, const dop_t *o) {
+  cst_buf_append(b, &o->op, 1);
+  cst_buf_append(b, o->l->p, o->l->n);
+  cst_buf_puts(b, "\n");
+  if (!o->l->nl)
+    cst_buf_puts(b, "\\ No newline at end of file\n");
+}
+
+char *cst_diff_unified(const char *label, const char *a, size_t alen,
+                       const char *b, size_t blen) {
+  int na = 0, nb = 0;
+  dline_t *A = split_lines(a ? a : "", alen, &na);
+  dline_t *B = split_lines(b ? b : "", blen, &nb);
+  dop_t *ops = malloc((size_t)(na + nb + 1) * sizeof(dop_t));
+  dop_t *tmp = malloc((size_t)(na + nb + 1) * sizeof(dop_t));
+  char *res = NULL;
+  if (!A || !B || !ops || !tmp)
+    goto out;
+
+  int p = 0;
+  while (p < na && p < nb && line_eq(&A[p], &B[p]))
+    p++;
+  int s = 0;
+  while (s < na - p && s < nb - p && line_eq(&A[na - 1 - s], &B[nb - 1 - s]))
+    s++;
+  int nops = 0;
+  for (int i = 0; i < p; i++)
+    ops[nops++] = (dop_t){' ', &A[i]};
+  if (myers(A + p, na - p - s, B + p, nb - p - s, ops, &nops) != 0)
+    goto out;
+  for (int i = na - s; i < na; i++)
+    ops[nops++] = (dop_t){' ', &A[i]};
+  normalize_runs(ops, nops, tmp);
+
+  cst_buf_t o = {0};
+  int any = 0;
+  int old_before = 0, new_before = 0; /* lines consumed before op i */
+  int i = 0;
+  while (i < nops) {
+    if (ops[i].op == ' ') {
+      old_before++;
+      new_before++;
+      i++;
+      continue;
+    }
+    /* change at i: hunk starts DIFF_CONTEXT lines earlier */
+    int start = i - DIFF_CONTEXT < 0 ? 0 : i - DIFF_CONTEXT;
+    int back = i - start;
+    int ob = old_before - back, nbf = new_before - back;
+    int end = i;
+    for (;;) {
+      while (end < nops && ops[end].op != ' ')
+        end++;
+      int nx = end;
+      while (nx < nops && ops[nx].op == ' ')
+        nx++;
+      if (nx < nops && nx - end <= 2 * DIFF_CONTEXT) {
+        end = nx;
+        continue;
+      }
+      end = end + DIFF_CONTEXT > nops ? nops : end + DIFF_CONTEXT;
+      break;
+    }
+    int oc = 0, nc = 0;
+    for (int k = start; k < end; k++) {
+      if (ops[k].op != '+')
+        oc++;
+      if (ops[k].op != '-')
+        nc++;
+    }
+    if (!any) {
+      cst_buf_printf(&o, "--- a/%s\n+++ b/%s\n", label, label);
+      any = 1;
+    }
+    cst_buf_puts(&o, "@@ ");
+    range(&o, '-', ob, oc);
+    cst_buf_puts(&o, " ");
+    range(&o, '+', nbf, nc);
+    cst_buf_puts(&o, " @@\n");
+    for (int k = start; k < end; k++)
+      emit_line(&o, &ops[k]);
+    old_before = ob + oc;
+    new_before = nbf + nc;
+    i = end;
+  }
+  if (!o.buf)
+    cst_buf_puts(&o, "");
+  res = cst_buf_steal(&o);
+out:
+  free(A);
+  free(B);
+  free(ops);
+  free(tmp);
+  return res;
+}

src/tools/patch.c

@@ -0,0 +1,317 @@
+#include "cst_agent.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+  const char *p;
+  size_t n;
+} line_t;
+
+typedef struct {
+  line_t *v;
+  size_t n;
+  size_t cap;
+} lines_t;
+
+static int lines_push(lines_t *L, const char *p, size_t n) {
+  if (L->n == L->cap) {
+    size_t nc = L->cap ? L->cap * 2 : 64;
+    line_t *nv = realloc(L->v, nc * sizeof(*nv));
+    if (!nv)
+      return -1;
+    L->v = nv;
+    L->cap = nc;
+  }
+  L->v[L->n].p = p;
+  L->v[L->n].n = n;
+  L->n++;
+  return 0;
+}
+
+/* Split into lines without '\n'. A trailing newline does not add an empty
+ * final line. */
+static int split_lines(const char *s, size_t n, lines_t *out) {
+  size_t start = 0;
+  for (size_t i = 0; i < n; i++) {
+    if (s[i] == '\n') {
+      if (lines_push(out, s + start, i - start) != 0)
+        return -1;
+      start = i + 1;
+    }
+  }
+  if (start < n && lines_push(out, s + start, n - start) != 0)
+    return -1;
+  return 0;
+}
+
+static size_t rtrim_len(const line_t *l) {
+  size_t n = l->n;
+  while (n > 0 && (l->p[n - 1] == ' ' || l->p[n - 1] == '\t' ||
+                   l->p[n - 1] == '\r'))
+    n--;
+  return n;
+}
+
+static int line_eq(const line_t *a, const line_t *b, int loose) {
+  if (!loose)
+    return a->n == b->n && memcmp(a->p, b->p, a->n) == 0;
+  size_t na = rtrim_len(a), nb = rtrim_len(b);
+  return na == nb && memcmp(a->p, b->p, na) == 0;
+}
+
+static int seq_at(const lines_t *file, size_t pos, const lines_t *seq,
+                  int loose) {
+  if (pos + seq->n > file->n)
+    return 0;
+  for (size_t i = 0; i < seq->n; i++) {
+    if (!line_eq(&file->v[pos + i], &seq->v[i], loose))
+      return 0;
+  }
+  return 1;
+}
+
+/* Find seq in file at or after min_pos. hint<0 means unknown. Returns
+ * position, -1 when absent, -2 when ambiguous without a hint. */
+static long locate(const lines_t *file, size_t min_pos, const lines_t *seq,
+                   long hint, int loose) {
+  if (seq->n > file->n)
+    return -1;
+  size_t last = file->n - seq->n;
+  if (hint >= 0) {
+    long best = -1;
+    long best_d = 0;
+    for (size_t p = min_pos; p <= last; p++) {
+      if (!seq_at(file, p, seq, loose))
+        continue;
+      long d = (long)p - hint;
+      if (d < 0)
+        d = -d;
+      if (best < 0 || d < best_d) {
+        best = (long)p;
+        best_d = d;
+      }
+    }
+    return best;
+  }
+  long found = -1;
+  for (size_t p = min_pos; p <= last; p++) {
+    if (seq_at(file, p, seq, loose)) {
+      if (found >= 0)
+        return -2;
+      found = (long)p;
+    }
+  }
+  return found;
+}
+
+static int parse_hunk_header(const char *p, size_t n, long *a, long *b,
+                             long *c, long *d) {
+  /* "@@ -a[,b] +c[,d] @@..." */
+  char tmp[128];
+  if (n >= sizeof(tmp))
+    n = sizeof(tmp) - 1;
+  memcpy(tmp, p, n);
+  tmp[n] = 0;
+  *b = *d = 1;
+  if (sscanf(tmp, "@@ -%ld,%ld +%ld,%ld", a, b, c, d) == 4)
+    return 0;
+  *b = *d = 1;
+  if (sscanf(tmp, "@@ -%ld +%ld,%ld", a, c, d) == 3)
+    return 0;
+  *b = *d = 1;
+  if (sscanf(tmp, "@@ -%ld,%ld +%ld", a, b, c) == 3)
+    return 0;
+  *b = *d = 1;
+  if (sscanf(tmp, "@@ -%ld +%ld", a, c) == 2)
+    return 0;
+  return -1;
+}
+
+int cst_patch_apply_buffer(const char *orig, size_t olen, const char *hunks,
+                           size_t hlen, char **out, size_t *out_len,
+                           int *nhunks, char *err, size_t err_sz) {
+  lines_t file = {0}, hl = {0};
+  lines_t old_seq = {0}, new_seq = {0};
+  int rc = -1;
+  int count = 0;
+  long delta = 0;
+  size_t min_pos = 0;
+  int orig_final_nl = olen == 0 || orig[olen - 1] == '\n';
+  int final_nl = orig_final_nl;
+  if (err && err_sz)
+    err[0] = 0;
+  if (out)
+    *out = NULL;
+
+  if (split_lines(orig ? orig : "", olen, &file) != 0 ||
+      split_lines(hunks ? hunks : "", hlen, &hl) != 0) {
+    snprintf(err, err_sz, "oom");
+    goto done;
+  }
+
+  size_t i = 0;
+  while (i < hl.n) {
+    const line_t *h = &hl.v[i];
+    if (!(h->n >= 2 && h->p[0] == '@' && h->p[1] == '@')) {
+      i++;
+      continue;
+    }
+    long a = -1, b = -1, c = -1, d = -1;
+    int have_hint = parse_hunk_header(h->p, h->n, &a, &b, &c, &d) == 0;
+    i++;
+    old_seq.n = new_seq.n = 0;
+    int last_kind = 0; /* ' ', '-', '+' of previous body line */
+    int new_no_nl = 0, old_no_nl = 0;
+    for (; i < hl.n; i++) {
+      const line_t *l = &hl.v[i];
+      if (l->n >= 2 && l->p[0] == '@' && l->p[1] == '@')
+        break;
+      if (l->n == 0) {
+        /* models often drop the leading space of blank context lines; a
+         * blank line at the very end of the patch is just a terminator */
+        if (i + 1 == hl.n)
+          break;
+        lines_push(&old_seq, l->p, 0);
+        lines_push(&new_seq, l->p, 0);
+        last_kind = ' ';
+        continue;
+      }
+      char tag = l->p[0];
+      if (tag == ' ') {
+        lines_push(&old_seq, l->p + 1, l->n - 1);
+        lines_push(&new_seq, l->p + 1, l->n - 1);
+      } else if (tag == '-') {
+        if (l->n >= 4 && memcmp(l->p, "--- ", 4) == 0 && i + 1 < hl.n &&
+            hl.v[i + 1].n >= 4 && memcmp(hl.v[i + 1].p, "+++ ", 4) == 0)
+          break; /* next file header */
+        lines_push(&old_seq, l->p + 1, l->n - 1);
+      } else if (tag == '+') {
+        lines_push(&new_seq, l->p + 1, l->n - 1);
+      } else if (tag == '\\') {
+        if (last_kind == '+')
+          new_no_nl = 1;
+        else if (last_kind == '-')
+          old_no_nl = 1;
+        else if (last_kind == ' ')
+          new_no_nl = old_no_nl = 1;
+        continue;
+      } else {
+        break; /* diff --git, index ..., prose */
+      }
+      last_kind = tag;
+    }
+
+    long hint = -1;
+    if (have_hint) {
+      /* "-a,0" inserts after line a; otherwise a is 1-based start */
+      hint = (b == 0 ? a : a - 1) + delta;
+      if (hint < 0)
+        hint = 0;
+    }
+
+    long pos;
+    if (old_seq.n == 0) {
+      if (hint >= 0)
+        pos = hint > (long)file.n ? (long)file.n : hint;
+      else if (file.n == 0)
+        pos = 0;
+      else {
+        snprintf(err, err_sz,
+                 "hunk %d: pure insertion needs @@ -a,0 +c,d @@ line numbers",
+                 count + 1);
+        goto done;
+      }
+    } else {
+      pos = locate(&file, min_pos, &old_seq, hint, 0);
+      if (pos == -1)
+        pos = locate(&file, min_pos, &old_seq, hint, 1);
+      if (pos == -1 && min_pos > 0) {
+        pos = locate(&file, 0, &old_seq, hint, 0);
+        if (pos == -1)
+          pos = locate(&file, 0, &old_seq, hint, 1);
+      }
+      if (pos == -2) {
+        snprintf(err, err_sz,
+                 "hunk %d: ambiguous, context matches several places; add "
+                 "line numbers or more context",
+                 count + 1);
+        goto done;
+      }
+      if (pos < 0) {
+        snprintf(err, err_sz,
+                 "hunk %d: context/removed lines not found in file (first: "
+                 "\"%.*s\")",
+                 count + 1, (int)(old_seq.v[0].n > 80 ? 80 : old_seq.v[0].n),
+                 old_seq.v[0].p);
+        goto done;
+      }
+    }
+
+    /* splice: file[pos .. pos+old) -> new_seq */
+    size_t old_n = old_seq.n, new_n = new_seq.n;
+    size_t need = file.n - old_n + new_n;
+    if (need > file.cap) {
+      line_t *nv = realloc(file.v, (need + 16) * sizeof(line_t));
+      if (!nv) {
+        snprintf(err, err_sz, "oom");
+        goto done;
+      }
+      file.v = nv;
+      file.cap = need + 16;
+    }
+    memmove(&file.v[pos + new_n], &file.v[pos + old_n],
+            (file.n - (size_t)pos - old_n) * sizeof(line_t));
+    for (size_t k = 0; k < new_n; k++)
+      file.v[pos + k] = new_seq.v[k];
+    int touches_end = (size_t)pos + new_n == need;
+    file.n = need;
+    delta += (long)new_n - (long)old_n;
+    min_pos = (size_t)pos + new_n;
+    if (touches_end) {
+      if (new_no_nl)
+        final_nl = 0;
+      else if (old_no_nl)
+        final_nl = 1;
+    }
+    count++;
+  }
+
+  if (count == 0) {
+    snprintf(err, err_sz, "no @@ hunk found");
+    goto done;
+  }
+
+  {
+    size_t total = 1;
+    for (size_t k = 0; k < file.n; k++)
+      total += file.v[k].n + 1;
+    char *buf = malloc(total);
+    if (!buf) {
+      snprintf(err, err_sz, "oom");
+      goto done;
+    }
+    size_t o = 0;
+    for (size_t k = 0; k < file.n; k++) {
+      memcpy(buf + o, file.v[k].p, file.v[k].n);
+      o += file.v[k].n;
+      if (k + 1 < file.n || final_nl)
+        buf[o++] = '\n';
+    }
+    buf[o] = 0;
+    *out = buf;
+    if (out_len)
+      *out_len = o;
+  }
+  if (nhunks)
+    *nhunks = count;
+  rc = 0;
+
+done:
+  free(file.v);
+  free(hl.v);
+  free(old_seq.v);
+  free(new_seq.v);
+  return rc;
+}

src/tools/registry.c

@@ -0,0 +1,342 @@
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.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) {
+  return cst_tool_run_shell(ctx->workspace_root, c, r);
+}
+
+#define S "string"
+#define I "integer"
+#define B "boolean"
+
+static const cst_tool_def_t TOOLS[] = {
+    {"read_file",
+     "Read a UTF-8 text file. For big files pass offset (first line, "
+     "1-based) and limit (number of lines); line_numbers=true prefixes each "
+     "line with its number.",
+     "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, "prefix lines with their numbers"}},
+     CST_TP_READ, 1, run_read_file, NULL},
+    {"run_shell",
+     "Run a non-interactive shell command in the workspace root (stdin is "
+     "empty; long-running commands are killed). Returns stdout+stderr.",
+     "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},
+    {"write_file",
+     "Create or overwrite a whole file (parent directories are created).",
+     "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},
+    {"apply_patch",
+     "Apply a unified diff (---/+++ headers, @@ -a,b +c,d @@ hunks with 3 "
+     "context lines) to one or more files; all hunks apply or nothing "
+     "changes.",
+     "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},
+    {"edit_file",
+     "Replace an exact snippet in a file. old_string must match the file "
+     "byte-for-byte (including indentation) and be unique unless "
+     "replace_all=true. Best for small edits.",
+     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},
+    {"list_dir",
+     "List a directory as a tree (directories end with /). Skips .git, "
+     "node_modules, .agent and build output.",
+     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},
+    {"glob",
+     "Find files by name pattern, newest first. `*` and `?` 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},
+    {"grep",
+     "Search file contents with a POSIX extended regex. Returns "
+     "file:line:text matches.",
+     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},
+    {"delete_file",
+     "Delete a file (not directories).",
+     NULL,
+     {{"path", S, 1, "file path"}},
+     CST_TP_WRITE, 0, cst_tool_delete_file, cst_preview_delete_file},
+    {"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},
+    {"todo_write",
+     "Replace your task list for multi-step work. 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},
+    {"web_fetch",
+     "Fetch an http(s) URL and return its text (HTML is reduced to 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},
+    {"ask_user",
+     "Ask the user a question and wait for the answer. Use only for "
+     "decisions that are truly the user's.",
+     NULL,
+     {{"question", S, 1, "the question"},
+      {"options", S, 0, "suggested answers, one per line"}},
+     CST_TP_ASK, 0, cst_tool_ask_user, NULL},
+};
+#define NTOOLS ((int)(sizeof(TOOLS) / sizeof(TOOLS[0])))
+
+#undef S
+#undef I
+#undef B
+
+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";
+}
+
+int cst_tool_count(void) { return NTOOLS; }
+
+const cst_tool_def_t *cst_tool_at(int i) {
+  return i >= 0 && i < NTOOLS ? &TOOLS[i] : NULL;
+}
+
+int cst_tool_index(const char *name) {
+  if (!name)
+    return -1;
+  for (int i = 0; i < NTOOLS; i++) {
+    if (strcmp(TOOLS[i].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; }
+
+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;
+  int i = (int)(t - TOOLS);
+  return !(cfg->tools_off & (1ULL << i));
+}
+
+static int is_minimal(const cst_agent_config_t *cfg) {
+  return cfg && cfg->tool_profile == CST_TOOLS_MINIMAL;
+}
+
+void *cst_tools_schema_cfg(const cst_agent_config_t *cfg) {
+  cJSON *arr = cJSON_CreateArray();
+  if (!arr)
+    return NULL;
+  int legacy = is_minimal(cfg);
+  for (int i = 0; i < NTOOLS; i++) {
+    const cst_tool_def_t *t = &TOOLS[i];
+    if (!cst_tool_active(cfg, t))
+      continue;
+    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 *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);
+  }
+  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");
+  for (int i = 0; i < NTOOLS; i++) {
+    const cst_tool_def_t *t = &TOOLS[i];
+    if (!cst_tool_active(cfg, t))
+      continue;
+    cst_buf_printf(&b, "- %s(", t->name);
+    for (int k = 0; 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 ? "" : "?");
+    cst_buf_printf(&b, "): %s\n", t->desc);
+  }
+  return cst_buf_steal(&b);
+}
+
+char *cst_tools_names(const cst_agent_config_t *cfg) {
+  cst_buf_t b = {0};
+  int n = 0;
+  for (int i = 0; i < NTOOLS; i++) {
+    if (cst_tool_active(cfg, &TOOLS[i]))
+      cst_buf_printf(&b, "%s%s", n++ ? ", " : "", TOOLS[i].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) {
+  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);
+  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);
+}

src/tools/tools_internal.h

@@ -0,0 +1,63 @@
+#ifndef CST_TOOLS_INTERNAL_H
+#define CST_TOOLS_INTERNAL_H
+
+#include "cst_tools.h"
+#include "cst_util.h"
+
+#define READ_FILE_MAX (2 * 1024 * 1024)
+
+/* Value of key, or NULL when absent. */
+const char *tool_arg(const ctl_tool_call_t *call, const char *key);
+const char *tool_arg_n(const ctl_tool_call_t *call, const char *key,
+                       size_t *len);
+/* Integer arg, def when absent or empty. */
+long tool_arg_long(const ctl_tool_call_t *call, const char *key, long def);
+int tool_arg_bool(const ctl_tool_call_t *call, const char *key, int def);
+
+int tool_set_result(cst_tool_result_t *r, const char *s, int code);
+int tool_set_resultf(cst_tool_result_t *r, int code, const char *fmt, ...);
+int tool_take_buf(cst_tool_result_t *r, cst_buf_t *b, int code);
+
+/* Whole file (NULL when missing, unreadable or larger than max>0). */
+char *tool_slurp(const char *full, size_t *out_len, size_t max);
+int tool_write_whole(const char *full, const char *data, size_t n);
+void tool_ensure_parent_dirs(const char *workspace_root, const char *rel);
+void tool_append_diff(cst_buf_t *b, const char *relpath, const char *oldc,
+                      size_t olen, const char *newc, size_t nlen);
+int tool_is_binary(const char *s, size_t n);
+/* Workspace-relative display form of an absolute resolved path. */
+const char *tool_rel(const char *workspace_real, const char *full);
+
+int cst_tool_read_file2(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                        cst_tool_result_t *r);
+int cst_tool_list_dir(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                      cst_tool_result_t *r);
+int cst_tool_glob(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                  cst_tool_result_t *r);
+int cst_tool_grep(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                  cst_tool_result_t *r);
+int cst_tool_edit_file(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                       cst_tool_result_t *r);
+int cst_tool_delete_file(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                         cst_tool_result_t *r);
+int cst_tool_move_file(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                       cst_tool_result_t *r);
+int cst_tool_todo_write(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                        cst_tool_result_t *r);
+int cst_tool_ask_user(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                      cst_tool_result_t *r);
+int cst_tool_web_fetch(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                       cst_tool_result_t *r);
+
+int cst_preview_write_file(const cst_tool_ctx_t *ctx,
+                           const ctl_tool_call_t *c, char **out);
+int cst_preview_apply_patch(const cst_tool_ctx_t *ctx,
+                            const ctl_tool_call_t *c, char **out);
+int cst_preview_edit_file(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                          char **out);
+int cst_preview_delete_file(const cst_tool_ctx_t *ctx,
+                            const ctl_tool_call_t *c, char **out);
+int cst_preview_move_file(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                          char **out);
+
+#endif

src/tools/web.c

@@ -0,0 +1,285 @@
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+
+#include <curl/curl.h>
+
+#include "cst_tools.h"
+#include "cst_util.h"
+#include "tools_internal.h"
+
+#define FETCH_DOWNLOAD_MAX (5 * 1024 * 1024)
+#define FETCH_DEFAULT_OUT (64 * 1024)
+#define FETCH_MAX_OUT (1024 * 1024)
+
+typedef struct {
+  cst_buf_t body;
+  int overflow;
+} fetch_t;
+
+static size_t on_body(char *p, size_t sz, size_t n, void *ud) {
+  fetch_t *f = ud;
+  size_t len = sz * n;
+  if (f->body.len + len > FETCH_DOWNLOAD_MAX) {
+    f->overflow = 1;
+    return 0; /* abort */
+  }
+  cst_buf_append(&f->body, p, len);
+  return len;
+}
+
+static int tag_is(const char *p, const char *name) {
+  size_t n = strlen(name);
+  if (strncasecmp(p, name, n) != 0)
+    return 0;
+  char c = p[n];
+  return c == '>' || c == ' ' || c == '/' || c == '\t' || c == '\n' ||
+         c == '\r';
+}
+
+static const char *const BLOCK_TAGS[] = {
+    "p", "br", "div", "li", "tr", "h1", "h2", "h3", "h4", "h5", "h6",
+    "section", "article", "header", "footer", "pre", "table", "ul", "ol",
+    "blockquote", "hr"};
+
+static void put_entity(cst_buf_t *b, const char **pp, const char *end) {
+  static const struct {
+    const char *name;
+    const char *rep;
+  } ents[] = {{"&amp;", "&"},  {"&lt;", "<"},    {"&gt;", ">"},
+              {"&quot;", "\""}, {"&#39;", "'"},  {"&apos;", "'"},
+              {"&nbsp;", " "}};
+  const char *p = *pp;
+  for (size_t i = 0; i < sizeof(ents) / sizeof(ents[0]); i++) {
+    size_t n = strlen(ents[i].name);
+    if ((size_t)(end - p) >= n && strncmp(p, ents[i].name, n) == 0) {
+      cst_buf_puts(b, ents[i].rep);
+      *pp = p + n;
+      return;
+    }
+  }
+  if (end - p > 3 && p[1] == '#') {
+    char *e = NULL;
+    long cp = p[2] == 'x' || p[2] == 'X' ? strtol(p + 3, &e, 16)
+                                         : strtol(p + 2, &e, 10);
+    if (e && *e == ';' && cp > 0 && cp < 0x110000) {
+      char u[4];
+      int k = 0;
+      if (cp < 0x80) {
+        u[k++] = (char)cp;
+      } else if (cp < 0x800) {
+        u[k++] = (char)(0xC0 | (cp >> 6));
+        u[k++] = (char)(0x80 | (cp & 0x3F));
+      } else if (cp < 0x10000) {
+        u[k++] = (char)(0xE0 | (cp >> 12));
+        u[k++] = (char)(0x80 | ((cp >> 6) & 0x3F));
+        u[k++] = (char)(0x80 | (cp & 0x3F));
+      } else {
+        u[k++] = (char)(0xF0 | (cp >> 18));
+        u[k++] = (char)(0x80 | ((cp >> 12) & 0x3F));
+        u[k++] = (char)(0x80 | ((cp >> 6) & 0x3F));
+        u[k++] = (char)(0x80 | (cp & 0x3F));
+      }
+      cst_buf_append(b, u, (size_t)k);
+      *pp = e + 1;
+      return;
+    }
+  }
+  cst_buf_append(b, p, 1);
+  *pp = p + 1;
+}
+
+/* Crude HTML → text: drop script/style/head, tags become spaces or
+ * newlines, entities decoded, blank runs collapsed. */
+static char *html_to_text(const char *s, size_t n) {
+  cst_buf_t b = {0};
+  const char *p = s, *end = s + n;
+  for (const char *t = s; t + 7 < end; t++) {
+    if (*t == '<' && strncasecmp(t + 1, "title", 5) == 0) {
+      const char *gt = memchr(t, '>', (size_t)(end - t));
+      const char *e = gt ? gt + 1 : end;
+      while (e + 7 < end && strncasecmp(e, "</title", 7) != 0)
+        e++;
+      if (gt && e + 7 < end && e > gt + 1) {
+        cst_buf_puts(&b, "# ");
+        cst_buf_append(&b, gt + 1, (size_t)(e - gt - 1));
+        cst_buf_puts(&b, "\n\n");
+      }
+      break;
+    }
+  }
+  while (p < end) {
+    if (*p == '<') {
+      const char *q = p + 1;
+      int closing = *q == '/';
+      if (closing)
+        q++;
+      if (!closing && (tag_is(q, "script") || tag_is(q, "style") ||
+                       tag_is(q, "head") || tag_is(q, "noscript"))) {
+        const char *name = tag_is(q, "script")  ? "</script"
+                           : tag_is(q, "style") ? "</style"
+                           : tag_is(q, "head")  ? "</head"
+                                                : "</noscript";
+        const char *e = p;
+        size_t nl = strlen(name);
+        while (e < end && !(end - e >= (long)nl && strncasecmp(e, name, nl) == 0))
+          e++;
+        const char *gt = e < end ? memchr(e, '>', (size_t)(end - e)) : NULL;
+        p = gt ? gt + 1 : end;
+        continue;
+      }
+      if (end - p >= 4 && strncmp(p, "<!--", 4) == 0) {
+        const char *e = p + 4;
+        while (e + 2 < end && strncmp(e, "-->", 3) != 0)
+          e++;
+        p = e + 3 <= end ? e + 3 : end;
+        continue;
+      }
+      int block = 0;
+      for (size_t i = 0; i < sizeof(BLOCK_TAGS) / sizeof(BLOCK_TAGS[0]); i++)
+        if (tag_is(q, BLOCK_TAGS[i]))
+          block = 1;
+      const char *gt = memchr(p, '>', (size_t)(end - p));
+      p = gt ? gt + 1 : end;
+      cst_buf_puts(&b, block ? "\n" : " ");
+      continue;
+    }
+    if (*p == '&') {
+      put_entity(&b, &p, end);
+      continue;
+    }
+    cst_buf_append(&b, p, 1);
+    p++;
+  }
+  /* collapse whitespace: spaces within lines, at most one blank line */
+  cst_buf_t o = {0};
+  int nls = 0, sp = 0;
+  for (size_t i = 0; i < b.len; i++) {
+    char ch = b.buf[i];
+    if (ch == '\r')
+      continue;
+    if (ch == '\n') {
+      if (nls < 2 && o.len)
+        cst_buf_puts(&o, "\n");
+      nls++;
+      sp = 0;
+      continue;
+    }
+    if (ch == ' ' || ch == '\t') {
+      sp = 1;
+      continue;
+    }
+    if (sp && nls == 0 && o.len)
+      cst_buf_puts(&o, " ");
+    sp = 0;
+    nls = 0;
+    cst_buf_append(&o, &ch, 1);
+  }
+  cst_buf_free(&b);
+  if (!o.buf)
+    cst_buf_puts(&o, "");
+  return cst_buf_steal(&o);
+}
+
+static int textual(const char *ctype) {
+  if (!ctype || !ctype[0])
+    return 1;
+  return strncasecmp(ctype, "text/", 5) == 0 || strstr(ctype, "json") ||
+         strstr(ctype, "xml") || strstr(ctype, "javascript") ||
+         strstr(ctype, "yaml") || strstr(ctype, "toml");
+}
+
+int cst_tool_web_fetch(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                       cst_tool_result_t *r) {
+  (void)ctx;
+  const char *url = tool_arg(c, "url");
+  if (!url || !url[0])
+    return tool_set_result(r, "error: missing url", 1);
+  while (*url == ' ')
+    url++;
+  if (strncasecmp(url, "http://", 7) != 0 &&
+      strncasecmp(url, "https://", 8) != 0)
+    return tool_set_result(r, "error: only http:// and https:// URLs", 1);
+  long max_out = tool_arg_long(c, "max_bytes", FETCH_DEFAULT_OUT);
+  if (max_out <= 0)
+    max_out = FETCH_DEFAULT_OUT;
+  if (max_out > FETCH_MAX_OUT)
+    max_out = FETCH_MAX_OUT;
+
+  CURL *curl = curl_easy_init();
+  if (!curl)
+    return tool_set_result(r, "error: curl init failed", 1);
+  fetch_t f;
+  memset(&f, 0, sizeof(f));
+  char errbuf[CURL_ERROR_SIZE];
+  errbuf[0] = 0;
+  curl_easy_setopt(curl, CURLOPT_URL, url);
+  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
+  curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 5L);
+#if LIBCURL_VERSION_NUM >= 0x075500
+  curl_easy_setopt(curl, CURLOPT_PROTOCOLS_STR, "http,https");
+  curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS_STR, "http,https");
+#else
+  curl_easy_setopt(curl, CURLOPT_PROTOCOLS, (long)(CURLPROTO_HTTP | CURLPROTO_HTTPS));
+  curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS,
+                   (long)(CURLPROTO_HTTP | CURLPROTO_HTTPS));
+#endif
+  curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L);
+  curl_easy_setopt(curl, CURLOPT_TIMEOUT, 30L);
+  curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L);
+  curl_easy_setopt(curl, CURLOPT_USERAGENT, "cst-agent/1.0 (+web_fetch)");
+  curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, "");
+  curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, on_body);
+  curl_easy_setopt(curl, CURLOPT_WRITEDATA, &f);
+  curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf);
+  CURLcode rc = curl_easy_perform(curl);
+  long http = 0;
+  char *ctype = NULL;
+  char *final_url = NULL;
+  curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http);
+  curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ctype);
+  curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_URL, &final_url);
+  cst_buf_t b = {0};
+  int code = 0;
+  if (rc != CURLE_OK && !f.overflow) {
+    cst_buf_printf(&b, "error: fetch failed: %s",
+                   errbuf[0] ? errbuf : curl_easy_strerror(rc));
+    code = 1;
+  } else {
+    cst_buf_printf(&b, "HTTP %ld %s\ncontent-type: %s\n\n", http,
+                   final_url ? final_url : url, ctype ? ctype : "?");
+    if (http >= 400)
+      code = 1;
+    if (!textual(ctype)) {
+      cst_buf_printf(&b, "(non-text content, %zu bytes not shown)\n",
+                     f.body.len);
+    } else {
+      char *text = NULL;
+      size_t tlen = 0;
+      int html = ctype && strstr(ctype, "html");
+      if (html) {
+        text = html_to_text(f.body.buf ? f.body.buf : "", f.body.len);
+        tlen = text ? strlen(text) : 0;
+      }
+      const char *src = html ? text : (f.body.buf ? f.body.buf : "");
+      size_t slen = html ? tlen : f.body.len;
+      size_t keep = slen > (size_t)max_out
+                        ? cst_utf8_floor(src, (size_t)max_out)
+                        : slen;
+      size_t clean_len = 0;
+      char *clean = cst_utf8_sanitize(src, keep, &clean_len);
+      if (clean)
+        cst_buf_append(&b, clean, clean_len);
+      free(clean);
+      if (keep < slen || f.overflow)
+        cst_buf_printf(&b, "\n...(truncated; %zu%s bytes in total)\n", slen,
+                       f.overflow ? "+" : "");
+      free(text);
+    }
+  }
+  curl_easy_cleanup(curl);
+  cst_buf_free(&f.body);
+  return tool_take_buf(r, &b, code);
+}

src/undo.c

@@ -0,0 +1,296 @@
+/* Per-turn file snapshots under <ws>/.agent/undo/<session>/<tag>/ so the
+ * file changes of the latest turn can be rolled back (/undo). */
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+
+#ifndef _WIN32
+#include <dirent.h>
+#include <unistd.h>
+#endif
+
+#include "cst_agent.h"
+#include "cst_undo.h"
+#include "cst_util.h"
+#include "os_compat.h"
+
+#define UNDO_FILE_MAX (8 * 1024 * 1024)
+
+static int undo_root(const char *ws, const char *sid, char *out, size_t n) {
+  int k = snprintf(out, n, "%s/.agent/undo/%s", ws, sid && sid[0] ? sid : "_");
+  return k < 0 || (size_t)k >= n ? -1 : 0;
+}
+
+/* Workspace-relative, no "..", not absolute: undo may delete these paths. */
+static int rel_ok(const char *rel) {
+  if (!rel || !rel[0] || rel[0] == '/' || rel[0] == '\\' ||
+      (rel[0] && rel[1] == ':'))
+    return 0;
+  const char *p = rel;
+  while (*p) {
+    size_t n = strcspn(p, "/\\");
+    if (n == 2 && p[0] == '.' && p[1] == '.')
+      return 0;
+    p += n;
+    while (*p == '/' || *p == '\\')
+      p++;
+  }
+  return strchr(rel, '\n') == NULL && strchr(rel, '\t') == NULL;
+}
+
+static char *slurp(const char *p, size_t *len, size_t max) {
+  *len = 0;
+  FILE *fp = fopen(p, "rb");
+  if (!fp)
+    return NULL;
+  fseek(fp, 0, SEEK_END);
+  long sz = ftell(fp);
+  if (sz < 0 || (size_t)sz > max) {
+    fclose(fp);
+    return NULL;
+  }
+  rewind(fp);
+  char *b = malloc((size_t)sz + 1);
+  if (!b) {
+    fclose(fp);
+    return NULL;
+  }
+  *len = fread(b, 1, (size_t)sz, fp);
+  b[*len] = 0;
+  fclose(fp);
+  return b;
+}
+
+static int put(const char *p, const char *d, size_t n) {
+  FILE *fp = fopen(p, "wb");
+  if (!fp)
+    return -1;
+  int ok = n == 0 || fwrite(d, 1, n, fp) == n;
+  return fclose(fp) == 0 && ok ? 0 : -1;
+}
+
+static int manifest_has(const char *mf, const char *rel) {
+  FILE *fp = fopen(mf, "r");
+  if (!fp)
+    return 0;
+  char line[1400];
+  int found = 0;
+  while (!found && fgets(line, sizeof(line), fp)) {
+    char *t2 = strchr(line, '\t');
+    char *t3 = t2 ? strchr(t2 + 1, '\t') : NULL;
+    if (!t3)
+      continue;
+    t3++;
+    size_t n = strlen(t3);
+    if (n && t3[n - 1] == '\n')
+      t3[--n] = 0;
+    found = strcmp(t3, rel) == 0;
+  }
+  fclose(fp);
+  return found;
+}
+
+int cst_undo_snapshot(const char *ws, const char *sid, const char *tag,
+                      const char *rel) {
+  if (!ws || !tag || !rel_ok(rel))
+    return -1;
+  char full[OS_PATH_MAX];
+  if (cst_sandbox_resolve(ws, rel, full, sizeof(full)) != 0) {
+    /* parent missing: the file is new; record it as absent */
+    snprintf(full, sizeof(full), "%s", "");
+  }
+  char dir[OS_PATH_MAX], mf[OS_PATH_MAX];
+  if (undo_root(ws, sid, dir, sizeof(dir)) != 0)
+    return -1;
+  size_t dl = strlen(dir);
+  int k = snprintf(dir + dl, sizeof(dir) - dl, "/%s", tag);
+  if (k < 0 || (size_t)k >= sizeof(dir) - dl)
+    return -1;
+  if (os_mkdir_p(dir, 0755) != 0)
+    return -1;
+  k = snprintf(mf, sizeof(mf), "%s/MANIFEST", dir);
+  if (k < 0 || (size_t)k >= sizeof(mf))
+    return -1;
+  if (manifest_has(mf, rel))
+    return 0;
+  int idx = 0;
+  {
+    FILE *fp = fopen(mf, "r");
+    if (fp) {
+      int ch;
+      while ((ch = fgetc(fp)) != EOF)
+        idx += ch == '\n';
+      fclose(fp);
+    }
+  }
+  const char *state = "absent";
+  struct stat st;
+  if (full[0] && stat(full, &st) == 0 && S_ISREG(st.st_mode)) {
+    size_t n = 0;
+    char *data = slurp(full, &n, UNDO_FILE_MAX);
+    if (!data) {
+      state = "toolarge";
+    } else {
+      char bak[OS_PATH_MAX + 16];
+      int bl = snprintf(bak, sizeof(bak), "%s/%d.bak", dir, idx);
+      state = bl > 0 && (size_t)bl < sizeof(bak) && put(bak, data, n) == 0
+                  ? "file"
+                  : "toolarge";
+      free(data);
+    }
+  }
+  FILE *fp = fopen(mf, "a");
+  if (!fp)
+    return -1;
+  fprintf(fp, "%d\t%s\t%s\n", idx, state, rel);
+  fclose(fp);
+  return 0;
+}
+
+#ifndef _WIN32
+static int latest_tag(const char *root, char *tag, size_t n) {
+  DIR *d = opendir(root);
+  if (!d)
+    return -1;
+  struct dirent *de;
+  tag[0] = 0;
+  while ((de = readdir(d)) != NULL) {
+    if (de->d_name[0] == '.')
+      continue;
+    if (strcmp(de->d_name, tag) > 0)
+      snprintf(tag, n, "%s", de->d_name);
+  }
+  closedir(d);
+  return tag[0] ? 0 : -1;
+}
+
+static void rm_dir(const char *dir) {
+  DIR *d = opendir(dir);
+  if (d) {
+    struct dirent *de;
+    while ((de = readdir(d)) != NULL) {
+      if (strcmp(de->d_name, ".") == 0 || strcmp(de->d_name, "..") == 0)
+        continue;
+      char p[OS_PATH_MAX];
+      if (snprintf(p, sizeof(p), "%s/%s", dir, de->d_name) < (int)sizeof(p))
+        unlink(p);
+    }
+    closedir(d);
+  }
+  rmdir(dir);
+}
+
+int cst_undo_count(const char *ws, const char *sid) {
+  char root[OS_PATH_MAX];
+  if (undo_root(ws, sid, root, sizeof(root)) != 0)
+    return 0;
+  DIR *d = opendir(root);
+  if (!d)
+    return 0;
+  int n = 0;
+  struct dirent *de;
+  while ((de = readdir(d)) != NULL)
+    n += de->d_name[0] != '.';
+  closedir(d);
+  return n;
+}
+
+int cst_undo_restore_last(const char *ws, const char *sid, char *report,
+                          size_t report_sz) {
+  report[0] = 0;
+  char root[OS_PATH_MAX], tag[256], dir[OS_PATH_MAX], mf[OS_PATH_MAX];
+  if (undo_root(ws, sid, root, sizeof(root)) != 0 ||
+      latest_tag(root, tag, sizeof(tag)) != 0) {
+    snprintf(report, report_sz, "nothing to undo");
+    return -1;
+  }
+  if (snprintf(dir, sizeof(dir), "%s/%s", root, tag) >= (int)sizeof(dir) ||
+      snprintf(mf, sizeof(mf), "%s/MANIFEST", dir) >= (int)sizeof(mf)) {
+    snprintf(report, report_sz, "undo path too long");
+    return -1;
+  }
+  FILE *fp = fopen(mf, "r");
+  cst_buf_t rep = {0};
+  int restored = 0, failed = 0;
+  if (fp) {
+    char line[1400];
+    while (fgets(line, sizeof(line), fp)) {
+      size_t n = strlen(line);
+      if (n && line[n - 1] == '\n')
+        line[--n] = 0;
+      char *t2 = strchr(line, '\t');
+      char *t3 = t2 ? strchr(t2 + 1, '\t') : NULL;
+      if (!t3)
+        continue;
+      *t2++ = 0;
+      *t3++ = 0;
+      const char *rel = t3, *state = t2;
+      char full[OS_PATH_MAX];
+      struct stat lst;
+      if (!rel_ok(rel) || os_path_join(full, sizeof(full), ws, rel) != 0)
+        continue;
+      if (lstat(full, &lst) == 0 && S_ISLNK(lst.st_mode)) {
+        cst_buf_printf(&rep, "skipped %s (now a symlink)\n", rel);
+        failed++;
+        continue;
+      }
+      if (strcmp(state, "file") == 0) {
+        char bak[OS_PATH_MAX];
+        if (snprintf(bak, sizeof(bak), "%s/%s.bak", dir, line) >=
+            (int)sizeof(bak))
+          bak[0] = 0;
+        size_t len = 0;
+        char *data = slurp(bak, &len, UNDO_FILE_MAX);
+        char parent[OS_PATH_MAX];
+        snprintf(parent, sizeof(parent), "%s", full);
+        char *sl = strrchr(parent, '/');
+        if (sl) {
+          *sl = 0;
+          os_mkdir_p(parent, 0755);
+        }
+        if (data && put(full, data, len) == 0) {
+          cst_buf_printf(&rep, "restored %s\n", rel);
+          restored++;
+        } else {
+          cst_buf_printf(&rep, "FAILED to restore %s\n", rel);
+          failed++;
+        }
+        free(data);
+      } else if (strcmp(state, "absent") == 0) {
+        if (unlink(full) == 0) {
+          cst_buf_printf(&rep, "removed %s (did not exist before)\n", rel);
+          restored++;
+        }
+      } else {
+        cst_buf_printf(&rep, "skipped %s (too large to snapshot)\n", rel);
+        failed++;
+      }
+    }
+    fclose(fp);
+  }
+  rm_dir(dir);
+  if (!rep.buf)
+    cst_buf_puts(&rep, "nothing changed\n");
+  snprintf(report, report_sz, "%s", rep.buf);
+  cst_buf_free(&rep);
+  return failed && !restored ? -1 : 0;
+}
+#else
+int cst_undo_count(const char *ws, const char *sid) {
+  (void)ws;
+  (void)sid;
+  return 0;
+}
+int cst_undo_restore_last(const char *ws, const char *sid, char *report,
+                          size_t report_sz) {
+  (void)ws;
+  (void)sid;
+  snprintf(report, report_sz, "undo is not available on Windows");
+  return -1;
+}
+#endif

src/util.c

@@ -0,0 +1,163 @@
+#include "cst_util.h"
+
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int buf_reserve(cst_buf_t *b, size_t extra) {
+  if (b->len + extra + 1 <= b->cap)
+    return 0;
+  size_t nc = b->cap ? b->cap : 256;
+  while (nc < b->len + extra + 1)
+    nc *= 2;
+  char *nb = realloc(b->buf, nc);
+  if (!nb)
+    return -1;
+  b->buf = nb;
+  b->cap = nc;
+  return 0;
+}
+
+int cst_buf_append(cst_buf_t *b, const char *s, size_t n) {
+  if (!b)
+    return -1;
+  if (buf_reserve(b, n) != 0)
+    return -1;
+  if (n)
+    memcpy(b->buf + b->len, s, n);
+  b->len += n;
+  b->buf[b->len] = 0;
+  return 0;
+}
+
+int cst_buf_puts(cst_buf_t *b, const char *s) {
+  return cst_buf_append(b, s ? s : "", s ? strlen(s) : 0);
+}
+
+int cst_buf_printf(cst_buf_t *b, const char *fmt, ...) {
+  va_list ap;
+  va_start(ap, fmt);
+  va_list ap2;
+  va_copy(ap2, ap);
+  int n = vsnprintf(NULL, 0, fmt, ap);
+  va_end(ap);
+  if (n < 0 || buf_reserve(b, (size_t)n) != 0) {
+    va_end(ap2);
+    return -1;
+  }
+  vsnprintf(b->buf + b->len, (size_t)n + 1, fmt, ap2);
+  va_end(ap2);
+  b->len += (size_t)n;
+  return 0;
+}
+
+void cst_buf_free(cst_buf_t *b) {
+  if (!b)
+    return;
+  free(b->buf);
+  b->buf = NULL;
+  b->len = b->cap = 0;
+}
+
+char *cst_buf_steal(cst_buf_t *b) {
+  if (buf_reserve(b, 0) != 0)
+    return NULL;
+  char *s = b->buf;
+  b->buf = NULL;
+  b->len = b->cap = 0;
+  return s;
+}
+
+size_t cst_utf8_floor(const char *s, size_t n) {
+  if (!s || n == 0)
+    return 0;
+  size_t i = n;
+  /* walk back over at most 3 continuation bytes to the lead byte */
+  size_t back = 0;
+  while (i > 0 && back < 3 && ((unsigned char)s[i - 1] & 0xC0) == 0x80) {
+    i--;
+    back++;
+  }
+  if (i == 0)
+    return n;
+  unsigned char lead = (unsigned char)s[i - 1];
+  size_t need = 1;
+  if (lead >= 0xF0)
+    need = 4;
+  else if (lead >= 0xE0)
+    need = 3;
+  else if (lead >= 0xC0)
+    need = 2;
+  if (need == 1)
+    return n; /* ASCII lead; any continuation bytes after it are invalid
+                 anyway and get sanitized later */
+  if (back + 1 >= need)
+    return n;
+  return i - 1; /* sequence incomplete: cut before lead byte */
+}
+
+static size_t utf8_seq_ok(const unsigned char *p, size_t left) {
+  unsigned char c = p[0];
+  size_t need;
+  unsigned cp;
+  if (c < 0x80)
+    return 1;
+  if ((c & 0xE0) == 0xC0) {
+    need = 2;
+    cp = c & 0x1F;
+  } else if ((c & 0xF0) == 0xE0) {
+    need = 3;
+    cp = c & 0x0F;
+  } else if ((c & 0xF8) == 0xF0) {
+    need = 4;
+    cp = c & 0x07;
+  } else {
+    return 0;
+  }
+  if (left < need)
+    return 0;
+  for (size_t i = 1; i < need; i++) {
+    if ((p[i] & 0xC0) != 0x80)
+      return 0;
+    cp = (cp << 6) | (p[i] & 0x3F);
+  }
+  if ((need == 2 && cp < 0x80) || (need == 3 && cp < 0x800) ||
+      (need == 4 && (cp < 0x10000 || cp > 0x10FFFF)) ||
+      (cp >= 0xD800 && cp <= 0xDFFF))
+    return 0;
+  return need;
+}
+
+char *cst_utf8_sanitize(const char *s, size_t n, size_t *out_len) {
+  char *out = malloc(n + 1);
+  if (!out)
+    return NULL;
+  size_t o = 0;
+  const unsigned char *p = (const unsigned char *)(s ? s : "");
+  size_t i = 0;
+  while (i < n) {
+    size_t k = utf8_seq_ok(p + i, n - i);
+    if (k == 0) {
+      out[o++] = '?';
+      i++;
+      continue;
+    }
+    memcpy(out + o, p + i, k);
+    o += k;
+    i += k;
+  }
+  out[o] = 0;
+  if (out_len)
+    *out_len = o;
+  return out;
+}
+
+uint64_t cst_fnv1a64(uint64_t h, const void *data, size_t n) {
+  const unsigned char *p = data;
+  for (size_t i = 0; i < n; i++) {
+    h ^= p[i];
+    h *= 1099511628211ULL;
+  }
+  return h;
+}