feat: add persistent multi-model workers and orchestration budgets

src/subagent.c

@@ -24,6 +24,8 @@
 
 #define ROLE_FILE_MAX (64 * 1024)
 #define INDEX_MAX 2048
+static int worker_active(const char *path);
+static void worker_live(const char *path, cst_subagent_rec_t *record);
 
 static pthread_mutex_t g_hook_mu = PTHREAD_MUTEX_INITIALIZER;
 static pthread_mutex_t g_seq_mu = PTHREAD_MUTEX_INITIALIZER;
@@ -80,6 +82,16 @@ static char *slurp(const char *path, size_t max) {
   return cst_buf_steal(&b);
 }
 
+static int save_atomic(const char *path, const char *text) {
+  char tmp[OS_PATH_MAX + 160];
+  if (!text || snprintf(tmp, sizeof(tmp), "%s.tmp", path) >= (int)sizeof(tmp)) return -1;
+  FILE *f = fopen(tmp, "wb");
+  if (!f) return -1;
+  int ok = fputs(text, f) >= 0;
+  if (fclose(f) != 0) ok = 0;
+  return ok ? os_rename_replace(tmp, path) : -1;
+}
+
 static int find_role(const cst_agent_role_t *v, int n, const char *name) {
   for (int i = 0; i < n; i++)
     if (strcmp(v[i].name, name) == 0)
@@ -87,6 +99,161 @@ static int find_role(const cst_agent_role_t *v, int n, const char *name) {
   return -1;
 }
 
+typedef struct {
+  pthread_mutex_t mu;
+  int tasks, requests;
+  long prompt, cached, output, cache_write;
+  int cache_known;
+  double cost;
+  int priced;
+  char currency[8];
+} worker_budget_t;
+
+typedef struct {
+  worker_budget_t *shared;
+  int used, limit, total;
+} worker_gate_t;
+
+void *cst_worker_budget_new(void) {
+  worker_budget_t *b = calloc(1, sizeof(*b));
+  if (b) pthread_mutex_init(&b->mu, NULL);
+  return b;
+}
+void cst_worker_budget_free(void *p) {
+  worker_budget_t *b = p;
+  if (b) { pthread_mutex_destroy(&b->mu); free(b); }
+}
+void cst_worker_budget_reset(void *p) {
+  worker_budget_t *b = p;
+  if (!b) return;
+  pthread_mutex_lock(&b->mu);
+  b->tasks = b->requests = 0;
+  b->prompt = b->cached = b->output = 0;
+  b->cache_write = 0; b->cost = 0; b->priced = 1; b->currency[0] = 0;
+  b->cache_known = 1;
+  pthread_mutex_unlock(&b->mu);
+}
+char *cst_workers_budget_json(const cst_agent_config_t *cfg) {
+  worker_budget_t *b = cfg->worker_budget;
+  cJSON *j = cJSON_CreateObject();
+  if (b) {
+    pthread_mutex_lock(&b->mu);
+    cJSON_AddNumberToObject(j, "delegations", b->tasks);
+    cJSON_AddNumberToObject(j, "requests", b->requests);
+    cJSON_AddNumberToObject(j, "max_tasks", cfg->subagent_tasks);
+    cJSON_AddNumberToObject(j, "max_requests", cfg->subagent_total);
+    cJSON_AddNumberToObject(j, "prompt_tokens", b->prompt);
+    cJSON_AddNumberToObject(j, "output_tokens", b->output);
+    cJSON_AddNumberToObject(j, "cache_write_tokens", b->cache_write);
+    if (b->priced && b->currency[0]) {
+      cJSON_AddNumberToObject(j, "cost", b->cost);
+      cJSON_AddStringToObject(j, "currency", b->currency);
+    }
+    if (b->cache_known) cJSON_AddNumberToObject(j, "cached_tokens", b->cached);
+    else cJSON_AddNullToObject(j, "cached_tokens");
+    pthread_mutex_unlock(&b->mu);
+  }
+  char *s = cJSON_PrintUnformatted(j);
+  cJSON_Delete(j);
+  return s;
+}
+static int worker_request(void *p) {
+  worker_gate_t *g = p;
+  if (!g || !g->shared) return 0;
+  pthread_mutex_lock(&g->shared->mu);
+  int ok = g->used < g->limit && g->shared->requests < g->total;
+  if (ok) { g->used++; g->shared->requests++; }
+  pthread_mutex_unlock(&g->shared->mu);
+  return ok;
+}
+
+static void workers_path(const char *ws, char *path, size_t n) {
+  snprintf(path, n, "%s/.agent/workers.json", ws);
+}
+char *cst_workers_config_get(const char *ws) {
+  char path[OS_PATH_MAX];
+  workers_path(ws, path, sizeof(path));
+  char *s = slurp(path, ROLE_FILE_MAX);
+  return s ? s : strdup("{\"orchestrate\":false,\"max_steps\":20,\"max_tasks\":8,\"max_requests\":100,\"profiles\":{},\"roles\":{}}");
+}
+static cJSON *workers_json(const char *ws) {
+  char *s = cst_workers_config_get(ws);
+  cJSON *j = s ? cJSON_Parse(s) : NULL;
+  free(s);
+  return j;
+}
+static const char *json_string(const cJSON *o, const char *key) {
+  const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, key);
+  return cJSON_IsString(v) ? v->valuestring : "";
+}
+static int json_limit(const cJSON *o, const char *key, int fallback) {
+  const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, key);
+  return cJSON_IsNumber(v) && v->valueint > 0 ? v->valueint : fallback;
+}
+int cst_workers_config_set(const char *ws, const char *json, char *err,
+                           size_t err_sz) {
+  cJSON *j = cJSON_Parse(json);
+  const char *problem = NULL;
+  if (!cJSON_IsObject(j)) problem = "expected JSON object";
+  const char *limits[] = {"max_steps", "max_tasks", "max_requests"};
+  for (int i = 0; !problem && i < 3; i++) {
+    const cJSON *v = cJSON_GetObjectItemCaseSensitive(j, limits[i]);
+    if (v && (!cJSON_IsNumber(v) || v->valuedouble != v->valueint ||
+              v->valueint < 1 || v->valueint > 10000))
+      problem = "budgets must be integers from 1 to 10000";
+  }
+  const cJSON *profiles = cJSON_GetObjectItemCaseSensitive(j, "profiles");
+  const cJSON *roles = cJSON_GetObjectItemCaseSensitive(j, "roles");
+  if (!problem && ((profiles && !cJSON_IsObject(profiles)) ||
+                   (roles && !cJSON_IsObject(roles))))
+    problem = "profiles and roles must be objects";
+  const cJSON *mode = cJSON_GetObjectItemCaseSensitive(j, "orchestrate");
+  if (mode && !cJSON_IsBool(mode)) problem = "orchestrate must be boolean";
+  const cJSON *p;
+  cJSON_ArrayForEach(p, profiles) {
+    if (!cJSON_IsObject(p) || !cst_provider_find(json_string(p, "provider")) ||
+        !json_string(p, "model")[0] ||
+        cJSON_GetObjectItemCaseSensitive(p, "api_key"))
+      problem = "profile needs a known provider and model; use provider credentials";
+  }
+  cJSON_ArrayForEach(p, roles) {
+    if (!cJSON_IsString(p) || !cJSON_GetObjectItemCaseSensitive(profiles, p->valuestring))
+      problem = "role binding must name a configured profile";
+  }
+  if (problem) {
+    snprintf(err, err_sz, "%s", problem);
+    cJSON_Delete(j);
+    return -1;
+  }
+  char dir[OS_PATH_MAX], path[OS_PATH_MAX], tmp[OS_PATH_MAX + 8];
+  snprintf(dir, sizeof(dir), "%s/.agent", ws);
+  workers_path(ws, path, sizeof(path));
+  snprintf(tmp, sizeof(tmp), "%s.tmp", path);
+  char *s = cJSON_Print(j);
+  cJSON_Delete(j);
+  FILE *f = os_mkdir_p(dir, 0700) == 0 && s ? fopen(tmp, "wb") : NULL;
+  int ok = 0;
+  if (f) { ok = fputs(s, f) >= 0; if (fclose(f) != 0) ok = 0; }
+  free(s);
+  if (!ok || os_rename_replace(tmp, path) != 0) {
+    snprintf(err, err_sz, "cannot save worker configuration");
+    return -1;
+  }
+  return 0;
+}
+void cst_workers_config_apply(cst_agent_config_t *cfg) {
+  cJSON *j = workers_json(cfg->workspace_root);
+  if (j) {
+    cfg->orchestrate = cJSON_IsTrue(cJSON_GetObjectItemCaseSensitive(j, "orchestrate"));
+    cfg->subagent_steps = json_limit(j, "max_steps", 20);
+    cfg->subagent_tasks = json_limit(j, "max_tasks", 8);
+    cfg->subagent_total = json_limit(j, "max_requests", 100);
+  }
+  cJSON_Delete(j);
+  if (cfg->orchestrate_override)
+    cfg->orchestrate = cfg->orchestrate_override > 0;
+}
+
 /* "a, b ,c" -> ",a,b,c," */
 static void tool_list(const char *in, char *out, size_t sz) {
   size_t o = 0;
@@ -150,6 +317,8 @@ static void load_dir(const char *dir, const char *source, cst_agent_role_t *v,
       snprintf(r->desc, sizeof(r->desc), "%.255s", val);
     if (cst_fm_get(text, "model", val, sizeof(val)))
       snprintf(r->model, sizeof(r->model), "%.127s", val);
+    if (cst_fm_get(text, "profile", val, sizeof(val)))
+      snprintf(r->profile, sizeof(r->profile), "%.63s", val);
     if (cst_fm_get(text, "tools", val, sizeof(val)))
       tool_list(val, r->tools, sizeof(r->tools));
     if (cst_fm_get(text, "max_steps", val, sizeof(val)))
@@ -187,6 +356,13 @@ int cst_roles_list(const char *ws, cst_agent_role_t *out, int max) {
     load_dir(p, "user", out, &n, max);
   }
   /* custom roles after the built-ins, by name */
+  cJSON *settings = workers_json(ws ? ws : ".");
+  const cJSON *bindings = cJSON_GetObjectItemCaseSensitive(settings, "roles");
+  for (int i = 0; i < n; i++) {
+    const char *profile = json_string(bindings, out[i].name);
+    if (*profile) snprintf(out[i].profile, sizeof(out[i].profile), "%s", profile);
+  }
+  cJSON_Delete(settings);
   for (int i = NBUILTIN + 1; i < n; i++)
     for (int j = i; j > NBUILTIN && strcmp(out[j - 1].name, out[j].name) > 0;
          j--) {
@@ -213,8 +389,9 @@ char *cst_subagent_index(const char *ws) {
   cst_buf_puts(&b, "\nSub-agents (task tool, agent=<name>; default "
                    "general):\n");
   for (int i = 0; i < n && b.len < INDEX_MAX; i++)
-    cst_buf_printf(&b, "- %s%s: %.200s\n", v[i].name,
-                   v[i].read_only ? " (read-only)" : "", v[i].desc);
+    cst_buf_printf(&b, "- %s%s: %.200s [model profile: %s]\n", v[i].name,
+                   v[i].read_only ? " (read-only)" : "", v[i].desc,
+                   v[i].profile[0] ? v[i].profile : "inherits parent");
   cst_roles_free(v, n);
   free(v);
   return cst_buf_steal(&b);
@@ -290,12 +467,7 @@ static void write_meta(const char *dir, const char *file, const char *role,
   cJSON_AddNumberToObject(o, "ms", ms);
   char *txt = cJSON_PrintUnformatted(o);
   cJSON_Delete(o);
-  FILE *fp = txt ? fopen(p, "wb") : NULL;
-  if (fp) {
-    fputs(txt, fp);
-    fputc('\n', fp);
-    fclose(fp);
-  }
+  save_atomic(p, txt);
   free(txt);
 }
 
@@ -333,6 +505,24 @@ int cst_subagent_list(const char *ws, const char *parent_id,
     if ((it = cJSON_GetObjectItemCaseSensitive(o, "status")) &&
         it->valuestring)
       snprintf(r->status, sizeof(r->status), "%s", it->valuestring);
+    snprintf(r->provider, sizeof(r->provider), "%s", json_string(o, "provider"));
+    snprintf(r->model, sizeof(r->model), "%s", json_string(o, "model"));
+#define READ_NUMBER(field) do { const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, #field); if (cJSON_IsNumber(v)) r->field = v->valuedouble; } while (0)
+    READ_NUMBER(requests); READ_NUMBER(max_steps); READ_NUMBER(prompt_tokens);
+    READ_NUMBER(cached_tokens); READ_NUMBER(cache_write_tokens); READ_NUMBER(output_tokens);
+    READ_NUMBER(cost);
+#undef READ_NUMBER
+    r->priced = cJSON_IsNumber(cJSON_GetObjectItemCaseSensitive(o, "cost"));
+    r->cache_known = cJSON_IsNumber(cJSON_GetObjectItemCaseSensitive(o, "cached_tokens"));
+    snprintf(r->currency, sizeof(r->currency), "%s", json_string(o, "currency"));
+    if (strcmp(r->status, "running") == 0) {
+      char transcript[OS_PATH_MAX];
+      if (cst_subagent_path(ws, parent_id, r->file, transcript, sizeof(transcript)) == 0) {
+        if (!worker_active(transcript))
+          snprintf(r->status, sizeof(r->status), "interrupted");
+        else worker_live(transcript, r);
+      }
+    }
     if ((it = cJSON_GetObjectItemCaseSensitive(o, "steps")))
       r->steps = it->valueint;
     if ((it = cJSON_GetObjectItemCaseSensitive(o, "tools")))
@@ -459,6 +649,117 @@ static int out_text(cst_tool_result_t *r, int code, const char *text) {
   return 0;
 }
 
+static unsigned long worker_hash(const char *s) {
+  unsigned long h = 5381;
+  for (; *s; s++) h = h * 33 + (unsigned char)*s;
+  return h;
+}
+static pthread_mutex_t worker_mu = PTHREAD_MUTEX_INITIALIZER;
+static struct { char path[OS_PATH_MAX]; cst_agent_t *child; worker_gate_t *gate; } active_workers[64];
+static void worker_live(const char *path, cst_subagent_rec_t *r) {
+  pthread_mutex_lock(&worker_mu);
+  for (int i = 0; i < 64; i++) {
+    if (active_workers[i].gate && !strcmp(active_workers[i].path, path)) {
+      worker_gate_t *g = active_workers[i].gate;
+      pthread_mutex_lock(&g->shared->mu);
+      r->requests = g->used; r->max_steps = g->limit;
+      pthread_mutex_unlock(&g->shared->mu);
+    }
+  }
+  pthread_mutex_unlock(&worker_mu);
+}
+static int worker_active(const char *path) {
+  int found = 0;
+  pthread_mutex_lock(&worker_mu);
+  for (int i = 0; i < 64; i++)
+    if (active_workers[i].child && strcmp(active_workers[i].path, path) == 0)
+      found = 1;
+  pthread_mutex_unlock(&worker_mu);
+  return found;
+}
+int cst_worker_cancel(const char *ws, const char *pid, const char *id) {
+  char path[OS_PATH_MAX];
+  if (cst_subagent_path(ws, pid, id, path, sizeof(path)) != 0) return -1;
+  int found = 0;
+  pthread_mutex_lock(&worker_mu);
+  for (int i = 0; i < 64; i++) {
+    if (active_workers[i].child && strcmp(active_workers[i].path, path) == 0) {
+      cst_agent_request_cancel(active_workers[i].child);
+      found = 1;
+    }
+  }
+  pthread_mutex_unlock(&worker_mu);
+  return found ? 0 : -1;
+}
+
+static cJSON *worker_snapshot(const char *path, cst_agent_config_t *cc,
+                              const char *role, int save) {
+  char p[OS_PATH_MAX + 16];
+  snprintf(p, sizeof(p), "%s.worker", path);
+  cJSON *j;
+  if (!save) {
+    char *s = slurp(p, ROLE_FILE_MAX);
+    j = s ? cJSON_Parse(s) : NULL;
+    free(s);
+    return j;
+  }
+  j = cJSON_CreateObject();
+  cJSON_AddStringToObject(j, "role", role);
+  cJSON_AddStringToObject(j, "provider", cc->provider);
+  cJSON_AddStringToObject(j, "api_base", cc->api_base);
+  cJSON_AddStringToObject(j, "model", cc->model);
+  cJSON_AddStringToObject(j, "effort", cc->effort);
+  cJSON_AddStringToObject(j, "tools", cc->tools_only);
+  cJSON_AddStringToObject(j, "tools_off", cc->tools_off);
+  cJSON_AddNumberToObject(j, "protocol", cc->protocol);
+  cJSON_AddNumberToObject(j, "tool_profile", cc->tool_profile);
+  cJSON_AddStringToObject(j, "prompt", cc->role_prompt ? cc->role_prompt : "");
+  cJSON_AddBoolToObject(j, "readonly", cc->read_only);
+  cJSON_AddNumberToObject(j, "temperature", cc->temperature);
+  cJSON_AddNumberToObject(j, "top_p", cc->top_p);
+  cJSON_AddNumberToObject(j, "max_tokens", cc->max_tokens);
+  char *s = cJSON_PrintUnformatted(j);
+  int ok = save_atomic(p, s) == 0;
+  free(s);
+  if (!ok) { cJSON_Delete(j); return NULL; }
+  return j;
+}
+
+static void worker_usage(const char *dir, const char *file,
+                          const cst_agent_config_t *cc, cst_agent_t *child,
+                          int requests) {
+  char path[OS_PATH_MAX + 128];
+  snprintf(path, sizeof(path), "%s/%s.json", dir, file);
+  char *s = slurp(path, ROLE_FILE_MAX);
+  cJSON *j = s ? cJSON_Parse(s) : NULL;
+  free(s);
+  if (!j) return;
+  cJSON_AddStringToObject(j, "provider", cc->provider);
+  cJSON_AddStringToObject(j, "model", cc->model);
+  cJSON_AddNumberToObject(j, "requests", requests);
+  cJSON_AddNumberToObject(j, "max_steps", cc->max_steps);
+  cst_usage_t u;
+  memset(&u, 0, sizeof(u));
+  if (child) cst_agent_usage(child, NULL, &u);
+  cJSON_AddNumberToObject(j, "prompt_tokens", u.prompt);
+  if (u.requests > 0 && u.cache_known_requests == u.requests) {
+    cJSON_AddNumberToObject(j, "cached_tokens", u.cached);
+    cJSON_AddNumberToObject(j, "cache_write_tokens", u.write);
+  }
+  cJSON_AddNumberToObject(j, "output_tokens", u.out);
+  if (u.priced) {
+    cJSON_AddNumberToObject(j, "cost", u.cost);
+    cJSON_AddStringToObject(j, "currency", u.currency);
+  }
+  char *text = cJSON_PrintUnformatted(j);
+  cJSON_Delete(j);
+  save_atomic(path, text);
+  snprintf(path, sizeof(path), "%s/%s.runs.jsonl", dir, file);
+  FILE *f = text ? fopen(path, "ab") : NULL;
+  if (f) { fputs(text, f); fputc('\n', f); fclose(f); }
+  free(text);
+}
+
 static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                     cst_tool_result_t *r, void *ud) {
   (void)ud;
@@ -471,6 +772,7 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   const char *desc = arg(c, "description");
   const char *prompt = arg(c, "prompt");
   const char *want = arg(c, "agent");
+  const char *worker_id = arg(c, "worker_id");
   if (!want || !want[0])
     want = "general";
   if (!prompt || !prompt[0])
@@ -481,8 +783,27 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   cst_agent_role_t *roles = calloc(CST_ROLES_MAX, sizeof(*roles));
   if (!roles)
     return out_text(r, 1, "error: out of memory");
+  char pid[256], dir[OS_PATH_MAX], file[64], path[OS_PATH_MAX];
+  cst_agent_session_id(ctx->agent, pid, sizeof(pid));
+  cJSON *snapshot = NULL;
+  if (worker_id && worker_id[0]) {
+    int seq = 0, end = 0;
+    if (sscanf(worker_id, "sub-%d%n", &seq, &end) != 1 || seq < 1 ||
+        worker_id[end] || cst_subagent_path(ctx->workspace_root, pid,
+            worker_id, path, sizeof(path)) != 0)
+      { free(roles); return out_text(r, 1, "error: invalid worker_id"); }
+    snapshot = worker_snapshot(path, NULL, NULL, 0);
+    if (!snapshot) { free(roles); return out_text(r, 1, "error: worker not found"); }
+    want = json_string(snapshot, "role");
+  }
   int nr = cst_roles_list(ctx->workspace_root, roles, CST_ROLES_MAX);
   int ri = find_role(roles, nr, want);
+  if (ri < 0 && snapshot && nr < CST_ROLES_MAX) {
+    ri = nr++;
+    memset(&roles[ri], 0, sizeof(roles[ri]));
+    snprintf(roles[ri].name, sizeof(roles[ri].name), "%s", want);
+    roles[ri].prompt = strdup(json_string(snapshot, "prompt"));
+  }
   if (ri < 0) {
     cst_buf_t b = {0};
     cst_buf_printf(&b, "error: no agent named \"%s\" (available:", want);
@@ -491,6 +812,7 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
     cst_buf_puts(&b, ")");
     cst_roles_free(roles, nr);
     free(roles);
+    cJSON_Delete(snapshot);
     r->exit_code = 1;
     r->out_len = b.len;
     r->out = cst_buf_steal(&b);
@@ -498,28 +820,152 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   }
   const cst_agent_role_t *role = &roles[ri];
 
-  char pid[256], dir[OS_PATH_MAX], file[64], path[OS_PATH_MAX];
-  cst_agent_session_id(ctx->agent, pid, sizeof(pid));
   if (sub_dir(ctx->workspace_root, pid, dir, sizeof(dir)) != 0 ||
-      os_mkdir_p(dir, 0755) != 0 || next_file(dir, file, sizeof(file)) != 0 ||
+      os_mkdir_p(dir, 0755) != 0 ||
+      (!snapshot && next_file(dir, file, sizeof(file)) != 0) ||
+      (snapshot && snprintf(file, sizeof(file), "%s", worker_id) < 0) ||
       snprintf(path, sizeof(path), "%s/%s.jsonl", dir, file) >=
           (int)sizeof(path)) {
     cst_roles_free(roles, nr);
     free(roles);
+    cJSON_Delete(snapshot);
     return out_text(r, 1, "error: cannot create the sub-agent transcript");
   }
 
   cst_agent_config_t cc = *pcfg;
   cc.depth = pcfg->depth + 1;
   cc.plan_mode = 0;
-  cc.read_only = role->read_only || pcfg->plan_mode;
+  cc.read_only = role->read_only || pcfg->plan_mode || pcfg->read_only;
   snprintf(cc.tools_only, sizeof(cc.tools_only), "%s", role->tools);
   cst_tool_set_disabled(&cc, "ask_user", 1);
   cc.role_prompt = role->prompt;
   if (role->model[0])
     snprintf(cc.model, sizeof(cc.model), "%s", role->model);
-  if (role->max_steps > 0)
+  cc.max_steps = pcfg->subagent_steps > 0 ? pcfg->subagent_steps : 20;
+  if (role->max_steps > 0 && role->max_steps < cc.max_steps)
     cc.max_steps = role->max_steps;
+  const char *requested_steps = arg(c, "max_steps");
+  if (requested_steps) {
+    char *end;
+    long v = strtol(requested_steps, &end, 10);
+    if (*end || v < 1 || v > cc.max_steps) {
+      cst_roles_free(roles, nr); free(roles); cJSON_Delete(snapshot);
+      return out_text(r, 1, "error: max_steps must be within the configured limit");
+    }
+    cc.max_steps = (int)v;
+  }
+  cJSON *settings = workers_json(ctx->workspace_root);
+  const cJSON *profiles = cJSON_GetObjectItemCaseSensitive(settings, "profiles");
+  const cJSON *profile = cJSON_GetObjectItemCaseSensitive(profiles, role->profile);
+  if (!snapshot && role->profile[0]) {
+    const cst_provider_t *provider = cst_provider_find(json_string(profile, "provider"));
+    if (!provider || !json_string(profile, "model")[0]) {
+      cst_roles_free(roles, nr); free(roles); cJSON_Delete(settings);
+      return out_text(r, 1, "error: role model profile is missing or invalid");
+    }
+    snprintf(cc.provider, sizeof(cc.provider), "%s", provider->name);
+    snprintf(cc.api_base, sizeof(cc.api_base), "%s", provider->api_base);
+    snprintf(cc.model, sizeof(cc.model), "%s", json_string(profile, "model"));
+    snprintf(cc.effort, sizeof(cc.effort), "%s", json_string(profile, "effort"));
+    cc.temperature = 0; cc.top_p = 0; cc.max_tokens = 0;
+    const cJSON *v = cJSON_GetObjectItemCaseSensitive(profile, "temperature");
+    if (cJSON_IsNumber(v)) cc.temperature = v->valuedouble;
+    v = cJSON_GetObjectItemCaseSensitive(profile, "top_p");
+    if (cJSON_IsNumber(v)) cc.top_p = v->valuedouble;
+    cc.max_tokens = json_limit(profile, "max_tokens", 0);
+    cc.api_key[0] = 0;
+    if (!strcmp(cc.provider, pcfg->provider) && !strcmp(cc.api_base, pcfg->api_base))
+      snprintf(cc.api_key, sizeof(cc.api_key), "%s", pcfg->api_key);
+    if (!cc.api_key[0] && cst_creds_resolve(cc.provider, cc.api_key, sizeof(cc.api_key), NULL) != 0) {
+      cst_roles_free(roles, nr); free(roles); cJSON_Delete(settings);
+      return out_text(r, 1, "error: no provider credentials for role profile");
+    }
+  }
+  cJSON_Delete(settings);
+  if (snapshot) {
+    snprintf(cc.provider, sizeof(cc.provider), "%s", json_string(snapshot, "provider"));
+    snprintf(cc.api_base, sizeof(cc.api_base), "%s", json_string(snapshot, "api_base"));
+    snprintf(cc.model, sizeof(cc.model), "%s", json_string(snapshot, "model"));
+    snprintf(cc.effort, sizeof(cc.effort), "%s", json_string(snapshot, "effort"));
+    snprintf(cc.tools_only, sizeof(cc.tools_only), "%s", json_string(snapshot, "tools"));
+    const char *off = json_string(snapshot, "tools_off");
+    if (strlen(cc.tools_off) + strlen(off) < sizeof(cc.tools_off))
+      strcat(cc.tools_off, off);
+    else {
+      cst_roles_free(roles, nr); free(roles); cJSON_Delete(snapshot);
+      return out_text(r, 1, "error: tool restriction list exceeds capacity");
+    }
+    const cJSON *proto = cJSON_GetObjectItemCaseSensitive(snapshot, "protocol");
+    if (cJSON_IsNumber(proto)) cc.protocol = proto->valueint;
+    const cJSON *tp = cJSON_GetObjectItemCaseSensitive(snapshot, "tool_profile");
+    if (cJSON_IsNumber(tp)) cc.tool_profile = tp->valueint;
+    cc.role_prompt = json_string(snapshot, "prompt");
+    cc.read_only = cc.read_only || cJSON_IsTrue(cJSON_GetObjectItemCaseSensitive(snapshot, "readonly"));
+    if (strcmp(cc.provider, pcfg->provider) != 0 || strcmp(cc.api_base, pcfg->api_base) != 0) {
+      cc.api_key[0] = 0;
+      if (cst_creds_resolve(cc.provider, cc.api_key, sizeof(cc.api_key), NULL) != 0) {
+        cst_roles_free(roles, nr); free(roles); cJSON_Delete(snapshot);
+        return out_text(r, 1, "error: no credentials for resumed worker");
+      }
+    }
+    const cJSON *v = cJSON_GetObjectItemCaseSensitive(snapshot, "temperature");
+    cc.temperature = cJSON_IsNumber(v) ? v->valuedouble : 0;
+    v = cJSON_GetObjectItemCaseSensitive(snapshot, "top_p");
+    cc.top_p = cJSON_IsNumber(v) ? v->valuedouble : 0;
+    cc.max_tokens = json_limit(snapshot, "max_tokens", 0);
+  }
+  worker_budget_t *budget = pcfg->worker_budget;
+  if (pcfg->tools_only[0]) {
+    cst_agent_config_t permitted = cc;
+    cst_buf_t names = {0};
+    for (int i = 0; i < cst_tool_count(); i++) {
+      const cst_tool_def_t *tool = cst_tool_at(i);
+      if (cst_tool_active(pcfg, tool) && cst_tool_active(&permitted, tool))
+        cst_buf_printf(&names, ",%s,", tool->name);
+    }
+    snprintf(cc.tools_only, sizeof(cc.tools_only), "%s", names.buf ? names.buf : ",none,");
+    cst_buf_free(&names);
+  }
+  if (!snapshot) {
+    cst_buf_t tools = {0};
+    for (int i = 0; i < cst_tool_count(); i++) {
+      const cst_tool_def_t *tool = cst_tool_at(i);
+      if (cst_tool_active(&cc, tool)) cst_buf_printf(&tools, ",%s,", tool->name);
+    }
+    if (tools.len >= sizeof(cc.tools_only)) {
+      cst_buf_free(&tools); cst_roles_free(roles, nr); free(roles);
+      return out_text(r, 1, "error: worker tool list exceeds capacity");
+    }
+    snprintf(cc.tools_only, sizeof(cc.tools_only), "%s", tools.buf ? tools.buf : ",none,");
+    cst_buf_free(&tools);
+  }
+  if (!budget) {
+    cst_roles_free(roles, nr); free(roles); cJSON_Delete(snapshot);
+    return out_text(r, 1, "error: no shared worker budget");
+  }
+  pthread_mutex_lock(&budget->mu);
+  int allowed = budget->tasks < (pcfg->subagent_tasks > 0 ? pcfg->subagent_tasks : 8);
+  if (allowed) budget->tasks++;
+  pthread_mutex_unlock(&budget->mu);
+  if (!allowed) {
+    cst_roles_free(roles, nr); free(roles); cJSON_Delete(snapshot);
+    return out_text(r, 1, "error: delegation budget exhausted");
+  }
+  worker_gate_t gate = {budget, 0, cc.max_steps,
+                       pcfg->subagent_total > 0 ? pcfg->subagent_total : 100};
+  cc.request_gate = worker_request;
+  cc.request_gate_ud = &gate;
+  char cache_input[8192];
+  snprintf(cache_input, sizeof(cache_input), "%s|%s|%s|%s|%s|v4",
+           cc.workspace_root, cc.provider, cc.model, role->name, cc.tools_only);
+  snprintf(cc.cache_namespace, sizeof(cc.cache_namespace), "worker-%lx", worker_hash(cache_input));
+  if (!snapshot) {
+    snapshot = worker_snapshot(path, &cc, role->name, 1);
+    if (!snapshot) {
+      cst_roles_free(roles, nr); free(roles);
+      return out_text(r, 1, "error: cannot persist worker configuration");
+    }
+  }
   snprintf(cc.session_path, sizeof(cc.session_path), "%s", path);
   cst_agent_undo_key(ctx->agent, cc.undo_sid, sizeof(cc.undo_sid),
                      cc.undo_tag, sizeof(cc.undo_tag));
@@ -532,13 +978,36 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   run.role = role->name;
   run.ws = ctx->workspace_root;
   run.parent_cancel = parent_cancel;
+  pthread_mutex_lock(&worker_mu);
+  int slot = -1;
+  for (int i = 0; i < 64; i++) {
+    if (active_workers[i].path[0] && strcmp(active_workers[i].path, path) == 0) {
+      slot = -2; break;
+    }
+    if (!active_workers[i].path[0] && slot < 0) slot = i;
+  }
+  if (slot >= 0) {
+    snprintf(active_workers[slot].path, sizeof(active_workers[slot].path), "%s", path);
+  }
+  pthread_mutex_unlock(&worker_mu);
+  if (slot < 0) {
+    cst_roles_free(roles, nr); free(roles);
+    cJSON_Delete(snapshot);
+    return out_text(r, 1, "error: worker already busy or worker capacity reached");
+  }
   run.child = cst_agent_create(&cc);
+  pthread_mutex_lock(&worker_mu);
+  active_workers[slot].child = run.child;
+  active_workers[slot].gate = run.child ? &gate : NULL;
+  if (!run.child) active_workers[slot].path[0] = 0;
+  pthread_mutex_unlock(&worker_mu);
   if (!run.child) {
-    cst_roles_free(roles, nr);
-    free(roles);
+    cst_roles_free(roles, nr); free(roles); cJSON_Delete(snapshot);
+    os_set_cancel_flag(parent_cancel);
     return out_text(r, 1, "error: cannot start the sub-agent");
   }
   write_meta(dir, file, role->name, desc, "running", 0, 0, 0);
+  worker_usage(dir, file, &cc, NULL, 0);
 
   cst_agent_hooks_t h;
   memset(&h, 0, sizeof(h));
@@ -562,14 +1031,23 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   atomic_store(&run.done, 1);
   if (watching)
     pthread_join(watcher, NULL);
-  int cancelled = parent_cancel && *parent_cancel;
+  int cancelled = (parent_cancel && *parent_cancel) ||
+                  (rc != 0 && strstr(err, "cancel") != NULL);
 
   /* the report is the last assistant text after the prompt */
   cst_session_t *s = cst_agent_session(run.child);
   int n = cst_session_count(s), steps = 0;
   const char *final = NULL;
   int seen_user = 0;
+  /* Only report the newest assignment when resuming a persistent worker. */
+  int last_user = -1;
   for (int i = 0; i < n; i++) {
+    const cst_message_t *m = cst_session_get(s, i);
+    if (m->role == CST_ROLE_USER && !m->tool_call_id[0] &&
+        m->content && strcmp(m->content, prompt) == 0) last_user = i;
+  }
+  for (int i = 0; i < n; i++) {
+    if (i < last_user) continue;
     const cst_message_t *m = cst_session_get(s, i);
     if (m->role == CST_ROLE_USER && !m->tool_call_id[0] && !seen_user) {
       seen_user = 1;
@@ -594,6 +1072,17 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   } else if (rc == 0) {
     cst_buf_puts(&b, "(the sub-agent ended without a final report; its "
                      "transcript has the details)");
+  } else {
+    for (int i = n - 1; i > last_user; i--) {
+      const cst_message_t *m = cst_session_get(s, i);
+      if (m->role == CST_ROLE_TOOL && m->content && m->content[0]) {
+        size_t len = strlen(m->content);
+        if (len > 2048) len = cst_utf8_floor(m->content, 2048);
+        cst_buf_puts(&b, "\nLast tool result (partial task, verify before continuing):\n");
+        cst_buf_append(&b, m->content, len);
+        break;
+      }
+    }
   }
   while (b.len && (b.buf[b.len - 1] == '\n' || b.buf[b.len - 1] == ' '))
     b.buf[--b.len] = 0;
@@ -608,12 +1097,39 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   write_meta(dir, file, role->name, desc,
              rc == 0 ? "done" : cancelled ? "cancelled" : "error", steps,
              run.ntools, ms);
+  worker_usage(dir, file, &cc, run.child, gate.used);
+  cst_usage_t usage;
+  memset(&usage, 0, sizeof(usage));
+  cst_agent_usage(run.child, NULL, &usage);
+  pthread_mutex_lock(&budget->mu);
+  budget->prompt += usage.prompt;
+  budget->cached += usage.cached;
+  budget->output += usage.out;
+  budget->cache_write += usage.write;
+  if (usage.requests) {
+    if (!budget->currency[0]) snprintf(budget->currency, sizeof(budget->currency), "%s", usage.currency);
+    if (usage.priced && !strcmp(budget->currency, usage.currency)) budget->cost += usage.cost;
+    else budget->priced = 0;
+  }
+  if (usage.cache_known_requests != usage.requests) budget->cache_known = 0;
+  int remaining = gate.total - budget->requests;
+  pthread_mutex_unlock(&budget->mu);
+  cst_buf_printf(&b, "\n[worker_id=%s; model=%s/%s; requests=%d/%d]",
+                 file, cc.provider, cc.model, gate.used, gate.limit);
+  cst_buf_printf(&b, "\n[shared worker requests remaining=%d]", remaining);
+
+  pthread_mutex_lock(&worker_mu);
+  active_workers[slot].child = NULL;
+  active_workers[slot].gate = NULL;
+  active_workers[slot].path[0] = 0;
+  pthread_mutex_unlock(&worker_mu);
 
   cst_agent_destroy(run.child);
   /* run_turn and destroy re-pointed this thread's cancel flag */
   os_set_cancel_flag(parent_cancel);
   cst_roles_free(roles, nr);
   free(roles);
+  cJSON_Delete(snapshot);
   r->exit_code = rc == 0 ? 0 : cancelled ? 130 : 1;
   r->out_len = b.len;
   r->out = cst_buf_steal(&b);
@@ -623,12 +1139,10 @@ static int task_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
 /* Read-only roles may run side by side. */
 static int task_parallel(const ctl_tool_call_t *c, void *ud) {
   (void)ud;
+  if (arg(c, "worker_id")) return 0;
   const char *want = arg(c, "agent");
   if (!want || !want[0])
     return 0; /* general */
-  for (int i = 0; i < NBUILTIN; i++)
-    if (strcmp(BUILTIN[i].name, want) == 0)
-      return BUILTIN[i].read_only;
   cst_agent_role_t *v = calloc(CST_ROLES_MAX, sizeof(*v));
   if (!v)
     return 0;
@@ -661,6 +1175,8 @@ int cst_subagent_register_tool(const char *ws) {
       "summary shown to the user\"},"
       "\"prompt\":{\"type\":\"string\",\"description\":\"the complete task: "
       "goal, context, constraints and what to report back\"},"
+      "\"worker_id\":{\"type\":\"string\",\"description\":\"resume a worker from this session; omit to create\"},"
+      "\"max_steps\":{\"type\":\"integer\",\"minimum\":1,\"description\":\"request cap, at most the configured role limit\"},"
       "\"agent\":{\"type\":\"string\",\"description\":\"one of: %s "
       "(default general)\"}},"
       "\"required\":[\"description\",\"prompt\"]}",