@celestea/core 2.7.1

package/contracts/tools.json

@@ -0,0 +1,730 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Celestea engine tool specs (14 tools)",
+  "generatedAt": "2026-09-10T01:20:00Z",
+  "source": {
+    "liveEndpoint": "http://127.0.0.1:3777/api/tools (descriptions taken verbatim from the running engine)",
+    "schemas": "/src/celestea_harness/crates/tools/src/*.rs + crates/workers/src/tools.rs (hand-written ToolSpec.parameters, transcribed 1:1)",
+    "liveProbe": {
+      "checked": true,
+      "toolCount": 10,
+      "names": [
+        "http_request",
+        "list_dir",
+        "process_control",
+        "read_file",
+        "run_code",
+        "run_shell",
+        "session_send_message",
+        "spawn_worker",
+        "worker_status",
+        "write_file"
+      ],
+      "note": "W783: this is the FROZEN 2026-09-10 capture of the retired engine (10 tools) and is deliberately NOT rewritten. The TypeScript host now serves 11 tools; the delta is declared in `w783Delta` below."
+    },
+    "w783Delta": {
+      "addedTool": "ask_user_question",
+      "count": "10 -> 11",
+      "sourceRef": "packages/tools/src/tools/ask-user.ts (schema copied field-for-field from @deepseek-ai/dsh-tool-ask-user)",
+      "why": "The model needs to ask the user a question mid-turn. The answer arrives through POST /api/questions/{id}/answer (NOT /api/turn, which would be steering that a parked tool call never drains) and reaches the model as an ordinary tool_result.",
+      "notInRust": "The retired engine has no counterpart: /api/tools there answered 10 tools and this tool did not exist."
+    },
+    "w804Delta": {
+      "addedTool": "read_image",
+      "count": "11 -> 12",
+      "sourceRef": "docs/feature-multimodal-attachments.md#6",
+      "why": "The model needs to look at a local image (or a user-uploaded attachment by id) and have a vision-capable model actually see it; read_file is UTF-8 text only and rejects binary.",
+      "optionalMount": "builtinTools mounts read_image only when the host supplies a session attachment store; the default registry of record stays the 7 contract tools.",
+      "endpoints": "P0 adds ZERO endpoints: uploads ride POST /api/turn as inline base64 (attachment refs only in the log), so API_ENDPOINT_COUNT stays 51."
+    },
+    "w7Delta": {
+      "renamedTool": "session_send_message -> send_message",
+      "addedTool": "stop_worker",
+      "count": "12 -> 13",
+      "sourceRef": "packages/workers/src/tools.ts (W7; no Rust counterpart)",
+      "why": "The orchestration face needs a relay named for what it does (send_message) and a stop switch that halts a worker without deleting it (STOPPED terminal; row + session kept for audit).",
+      "notInRust": "The retired engine had neither the rename nor stop_worker.",
+      "endpoints": "W7 adds ZERO endpoints: stop_worker rides the existing worker tool dispatch, so API_ENDPOINT_COUNT stays 51."
+    },
+    "w884Delta": {
+      "addedTool": "load_skill",
+      "count": "13 -> 14",
+      "sourceRef": "packages/tools/src/tools/load-skill.ts (W884; reuses packages/core/src/skills.ts)",
+      "why": "Progressive disclosure for skills (W882 discovery + the W874/W879 non-system-prompt decision): the model must be able to load ONE skill's SKILL.md body on demand. The catalog (name + description only) is injected as durable user-role history at every turn start; the body enters the conversation only when this tool is called. Read-only: no writes, no process, no network; the name goes through W882's name contract (no path traversal).",
+      "executionKeepList": "W884 also adds load_skill to EXECUTION_TOOL_NAMES: it is a pure read and is NOT in SDK_TOOLS, so folding it would make skills unreachable in execution mode while the catalog still advertises them.",
+      "endpoints": "W884 adds ZERO endpoints: the catalog rides the existing turn-start context lane and the tool rides the existing dispatch, so API_ENDPOINT_COUNT stays 61."
+    }
+  },
+  "count": 18,
+  "tools": [
+    {
+      "name": "ask_user_question",
+      "description": "Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer. The call PAUSES until the user answers, then returns `{answers:[{id,selected,custom}],timed_out:false}` as an ordinary tool result and you continue. If you recommend one option, put it first and append \"（推荐）\" to that label. The user may always type a free-text answer instead of choosing. Waiting is bounded (default 300000 ms, overridable with `timeout_ms`): on expiry the call returns `{answers:[],timed_out:true}` and NO choice is made for you — do not ask the same question again; state the assumption you are proceeding on (or stop and report) and continue with your own judgement.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "questions": {
+            "type": "array",
+            "description": "Questions to ask the user before continuing.",
+            "items": {
+              "type": "object",
+              "additionalProperties": true,
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "Stable id for this question; echoed in the answer."
+                },
+                "question": {
+                  "type": "string",
+                  "description": "The specific question to ask the user."
+                },
+                "header": {
+                  "type": "string",
+                  "description": "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."
+                },
+                "detail": {
+                  "type": "string",
+                  "description": "Optional supporting detail shown with the question. Kept out of the option labels, so it never takes part in label matching."
+                },
+                "options": {
+                  "type": "array",
+                  "description": "Optional choices to show the user. If you recommend one, put it first and append \"（推荐）\" to that label.",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "properties": {
+                      "label": {
+                        "type": "string",
+                        "description": "Short user-facing option label."
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "One sentence explaining the tradeoff or impact."
+                      }
+                    },
+                    "required": [
+                      "label"
+                    ]
+                  }
+                },
+                "multi_select": {
+                  "type": "boolean",
+                  "description": "Whether the user may select more than one option. Defaults to false."
+                },
+                "intent": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "description": "Optional presentation intent. It changes how a capable UI renders the question, never the answer encoding; a UI that does not know the tag shows the generic option list.",
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "plan-review"
+                      ],
+                      "description": "A plan submitted for review."
+                    },
+                    "approve": {
+                      "type": "string",
+                      "description": "The option label that approves the plan; every other option declines it."
+                    }
+                  },
+                  "required": [
+                    "kind",
+                    "approve"
+                  ]
+                }
+              },
+              "required": [
+                "id",
+                "question"
+              ]
+            }
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Optional maximum wait in milliseconds for the whole batch. Default 300000; capped at 3600000. On expiry the call returns an empty answer set with timed_out:true."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "questions"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "W783: packages/tools/src/tools/ask-user.ts (schema copied from @deepseek-ai/dsh-tool-ask-user)"
+    },
+    {
+      "name": "browser_act",
+      "description": "Act on the page opened by browser_open: click, type into, press a key on, or scroll an element identified by its stable ref from the last snapshot. Returns the updated accessibility snapshot and screenshot. Like browser_open, this call runs with RLIMIT_AS EXEMPTED (virtual address space unbounded) and reports the isolation state in its result.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "click",
+              "type",
+              "key",
+              "scroll"
+            ],
+            "description": "What to do: click an element, type text into it, press a key, or scroll it."
+          },
+          "ref": {
+            "type": "string",
+            "description": "Stable ref from the last snapshot (required for click/type/scroll)."
+          },
+          "text": {
+            "type": "string",
+            "description": "Text to insert (action=type)."
+          },
+          "key": {
+            "type": "string",
+            "description": "Key name for action=key, e.g. Enter, Tab, Escape."
+          },
+          "delta_x": {
+            "type": "integer",
+            "description": "Horizontal scroll delta in pixels (action=scroll; default 0)."
+          },
+          "delta_y": {
+            "type": "integer",
+            "description": "Vertical scroll delta in pixels (action=scroll; default 0)."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "action"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "packages/tools/src/tools/browser.ts (F4 step 2b; drives packages/tools/src/browser/session.ts)"
+    },
+    {
+      "name": "browser_open",
+      "description": "Open an absolute http(s) URL in a session-scoped headless browser and return the page's accessibility snapshot (interactive elements with stable refs) plus a PNG screenshot. Use those refs with browser_act. Requires the session's network capability (the sandbox must share the host network so the DevTools endpoint is reachable) and a session attachment store for the screenshot. This call runs with RLIMIT_AS EXEMPTED: the browser's virtual address space is NOT bounded by the sandbox, because Chromium cannot start under an address-space cap. Every other sandbox limit and the exact isolation state are reported in the result's isolation block.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Absolute http(s) URL to open."
+          },
+          "viewport": {
+            "type": "object",
+            "description": "Optional viewport size in CSS pixels (default 800x600).",
+            "properties": {
+              "width": {
+                "type": "integer"
+              },
+              "height": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "width",
+              "height"
+            ],
+            "additionalProperties": false
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "packages/tools/src/tools/browser.ts (F4 step 2b; drives packages/tools/src/browser/session.ts)"
+    },
+    {
+      "name": "forget",
+      "description": "Retract a previously remembered fact by its `id` (as returned by `remember`) or by its exact `text`. This APPENDS a tombstone to the workspace's append-only memory log — history is never rewritten, the entry is hidden from future turns. Only entries in this workspace's GLOBAL memory layer can be forgotten; a project-layer MEMORY.md is read-only. The result reports the layer, the absolute file, and the id retired.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Entry id to retract (as returned by remember)."
+          },
+          "text": {
+            "type": "string",
+            "description": "Exact text of the entry to retract (alternative to id)."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "additionalProperties": false,
+        "required": []
+      },
+      "sourceRef": "packages/tools/src/tools/memory.ts (F3 P1; storage in packages/tools/src/memory/)"
+    },
+    {
+      "name": "http_request",
+      "description": "Send an HTTP(S) request and return {status, headers(subset), body, truncated}. Only http/https URLs are allowed (file:// etc. rejected); redirects are followed up to 5 hops; the response body is truncated at 1MB (truncated:true beyond). HTTP error statuses are preserved in `status` — not tool errors; transport failures are categorized as timeout | dns | connect | redirect | invalid_url | invalid_arg | target_forbidden. SSRF policy: when CELESTEA_HTTP_ALLOW / CELESTEA_HTTP_DENY (comma-separated IP/CIDR) are set, every resolved target IP — and every redirect hop — must pass them; default (unset) allows all hosts.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "method": {
+            "type": "string",
+            "description": "HTTP method (default GET).",
+            "enum": [
+              "GET",
+              "POST",
+              "PUT",
+              "DELETE",
+              "PATCH",
+              "HEAD"
+            ]
+          },
+          "url": {
+            "type": "string",
+            "description": "Target URL; only http/https schemes are allowed."
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Optional request headers as {name: value}."
+          },
+          "body": {
+            "type": "string",
+            "description": "Optional request body string."
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "description": "Optional timeout in milliseconds (default 15000, maximum 60000).",
+            "minimum": 1
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/tools/src/http.rs:238-254"
+    },
+    {
+      "name": "list_dir",
+      "description": "List the entry names in a directory.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Directory path to list."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/tools/src/builtin.rs:217-230"
+    },
+    {
+      "name": "load_skill",
+      "description": "Load one skill's full instructions (its SKILL.md BODY) into the conversation by name. The per-turn skill catalog lists the available names; call this before doing a task a skill covers. The result carries the skill's `body`, its `dir` (read anything the body references from there with read_file), and the `source` layer it won — a skill's child files (references/, scripts/) are NEVER inlined. An unknown name, a name that is not a lowercase `[a-z0-9-]` slug (path traversal included), or a SKILL.md whose frontmatter is invalid fails with a structured `load_skill: code=... msg=\"...\"` error naming the reason — never a silent empty result.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Skill name exactly as listed in the skill catalog (lowercase letters, digits, hyphens)."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "packages/tools/src/tools/load-skill.ts (W884; reuses packages/core/src/skills.ts)"
+    },
+    {
+      "name": "process_control",
+      "description": "Control a background process started by run_shell(background=true). Handles live in the session-scoped process registry and survive across turns; a process that exits stays pollable from a bounded tombstone (most recent 32, or 10 minutes), so poll AFTER exit returns {running:false, exit_code, signal, stdout_tail(<=4KB), stderr_tail, cpu_exceeded?} instead of an unknown handle. action=poll reads the current or terminal state; action=kill sends SIGTERM, waits a grace period, then SIGKILL and returns {killed:true}; action=stdin writes one line (content + newline) to the process stdin.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "handle": {
+            "type": "string",
+            "description": "Process handle returned by run_shell(background=true)."
+          },
+          "action": {
+            "type": "string",
+            "description": "poll | kill | stdin (see tool description).",
+            "enum": [
+              "poll",
+              "kill",
+              "stdin"
+            ]
+          },
+          "content": {
+            "type": "string",
+            "description": "Line to write to the process stdin (action=stdin only)."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "handle",
+          "action"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/tools/src/process.rs:462-479"
+    },
+    {
+      "name": "read_file",
+      "description": "Read a UTF-8 text file and return its contents as a string. A whole read is capped at 256 KiB; pass offset (0-based line) and/or limit (line count) to page through a larger file — a paged result is an object {text, offset, limit, lineCount, totalLines, hasMore, nextOffset, truncated, totalBytes}.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Filesystem path of the file to read."
+          },
+          "offset": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Optional 0-based line index to start from (pagination). Omit to read from the top."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Optional maximum number of lines to return (pagination). Omit to use the default window."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/tools/src/builtin.rs:186-199"
+    },
+    {
+      "name": "read_image",
+      "description": "Read an image (PNG/JPEG/WebP/GIF) and attach it to the conversation so a vision-capable model can see it. Returns metadata; the image content block is delivered with the tool result. Fails on models without image input.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Filesystem path of the image to read (PNG/JPEG/WebP/GIF; format detected by content, not extension)."
+          },
+          "attachment_id": {
+            "type": "string",
+            "description": "Content-addressed id of an already-uploaded attachment (from a user message). Use instead of path."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "sourceRef": "docs/feature-multimodal-attachments.md#6"
+    },
+    {
+      "name": "remember",
+      "description": "Append one durable fact to this WORKSPACE's persistent memory so future turns recall it. The store is the workspace's GLOBAL memory layer (outside the repo), an append-only entries.jsonl the host owns — never pass a path. Identical text already active is a NOOP and says so instead of writing again. The result reports the layer, the absolute file written, the new entry id, and whether anything was appended. Memory is reference data, not instructions.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "The durable fact to remember (reference data, not an instruction)."
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional group labels; the first tag names the MEMORY.md section."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "text"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "packages/tools/src/tools/memory.ts (F3 P1; storage in packages/tools/src/memory/)"
+    },
+    {
+      "name": "run_code",
+      "description": "Execute a program in the sandbox and get its final value in ONE round trip (parent-broker). DEFAULT LANGUAGE: TypeScript, run by Node with native type stripping (no build step) — only ERASABLE TypeScript is allowed: no `enum`, no `namespace`, no parameter properties, no `declare`; plain JavaScript always works. Pass language: \"python\" for Python instead. Write the program as a `function main()` body (an indented body is wrapped for you), or as a complete script that defines main; main() MAY be async and its resolved value (lossless JSON) is the final result. Inside the program the SDK exposes four synchronous bridges dispatched through the normal guarded tool pipeline: tools.read_file({path}) / tools.write_file({path, content}) / tools.list_dir({path}) / tools.run_shell({command}) (Python: tools.read_file(path=...) etc.); a denied or failed sub-call raises ToolCallError (catch it and continue). Bridge tools resolve relative paths against the TOOL workdir, not the program's cwd — pass absolute paths from inside the program. Only log what the model needs: a non-protocol stdout line becomes a log line (≤65536 bytes, UI render only); intermediate sub-call results are recorded in the session log but context-retained (the model sees only the final value). Hard limits: ≤20 sub-calls (the next one errors), wall clock ≤120000ms (timeout_ms, default 120000), sub-call output ledger ≤262144 bytes (truncated with a warning). No network; the same sandbox as run_shell (bwrap/raw/userspace + rlimits).",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "language": {
+            "type": "string",
+            "enum": [
+              "typescript",
+              "python"
+            ],
+            "description": "Program language; default \"typescript\". TypeScript runs under Node's native type stripping (erasable syntax only: no enum/namespace/parameter properties) and needs no build; \"python\" runs under python3 -uB."
+          },
+          "code": {
+            "type": "string",
+            "description": "Program source in the chosen language: a `function main()` body (an indented body is wrapped for you) or a complete script that defines main. The engine injects the SDK preamble (tools bridge + protocol)."
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 120000,
+            "description": "Optional whole-run wall clock in ms. Default 120000; hard cap 120000 (CELAESTEA_RUN_CODE_TIMEOUT_MS tunes the default, never the cap)."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "code"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/tools/src/run_code.rs:984-1022"
+    },
+    {
+      "name": "run_shell",
+      "description": "Run a shell command inside the sandbox (v2 OS isolation when available: namespaces + read-only root + resource limits, else the v1 userspace path; fixed workdir, sanitized env, bounded timeout and output) and return stdout, stderr, exit code, and a `sandbox` object {provider: bwrap|raw|userspace, net_isolated, tmp_private, seccomp} reporting the effective isolation (W249: network isolated and /tmp a private tmpfs by default; CELESTEA_SANDBOX_NET=1 / CELESTEA_SANDBOX_SHARE_TMP=1 restore the shared host net/tmp; CELESTEA_SANDBOX_SECCOMP=1 enables the seccomp whitelist). With background:true the command is spawned detached (no call-level timeout; resource limits still apply) and returns {background, handle, pid} immediately — control it with the process_control tool (poll / stdin / kill); background processes live in the session process registry and survive across turns. Default timeout is 30s; raise it with timeout_ms up to the cap configured by CELESTEA_SHELL_MAX_TIMEOUT_MS (default 300000ms). Optional cpu_sec overrides RLIMIT_CPU for THIS process (default 20s, foreground and background alike); values above the cap from CELESTEA_SHELL_MAX_CPU_SEC (default 600) are CLAMPED to it, and a CPU-cap kill is reported as cpu_exceeded.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string",
+            "description": "The command line to execute."
+          },
+          "workdir": {
+            "type": "string",
+            "description": "Optional working directory. Must already exist inside the sandbox root; relative paths resolve against the sandbox workdir."
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "description": "Optional per-call timeout in milliseconds. Default 30000; can be raised up to the cap from CELESTEA_SHELL_MAX_TIMEOUT_MS (default 300000). Ignored when background:true.",
+            "minimum": 1
+          },
+          "cpu_sec": {
+            "type": "integer",
+            "description": "Optional per-call CPU time limit in seconds (RLIMIT_CPU) for THIS process, foreground or background. Default 20; values above CELESTEA_SHELL_MAX_CPU_SEC (default 600) are clamped to that cap. A process killed by the CPU limit reports cpu_exceeded:true with a message naming the limit.",
+            "minimum": 1
+          },
+          "background": {
+            "type": "boolean",
+            "description": "Optional, default false. When true, spawn the command detached (no call-level timeout; rlimits including cpu_sec still apply) and return {background:true, handle, pid} immediately; control the process with process_control (poll / stdin / kill). A process that exits stays pollable from a bounded tombstone (most recent 32, or 10 minutes), so poll after exit still returns exit_code/signal and the tails."
+          },
+          "notify": {
+            "type": "boolean",
+            "description": "Optional, default true. When background:true, whether a NATURAL exit may be offered to a host completion sink. No sink is wired in this deployment, so read the terminal state with process_control(action=poll); the flag is kept for hosts that install one."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "command"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/tools/src/builtin.rs:232-258"
+    },
+    {
+      "name": "send_message",
+      "description": "向 harness 内另一个会话发送消息（会话间通讯，用于多 worker 联调、交叉审计、分工协作）。target 可用会话地址（session id）或会话命名（标题/项目/工作区名；按命名指定先解析到唯一地址，命中多个返回候选清单）。content 是发送给目标会话的正文；投递的消息会成为目标会话新一轮的用户输入（唤醒语义：引擎会驱动目标会话就这条消息跑新一轮处理），因此也是 worker 回执与跨会话协作的通道。需要对方回复时在 content 里写明要求，并告诉对方用本工具 target=<你的会话地址> 发回。发送者信息自动附带。",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "target": {
+            "type": "string",
+            "description": "目标会话地址（session id）或会话命名（标题/项目名）"
+          },
+          "content": {
+            "type": "string",
+            "description": "发送给目标会话的消息正文"
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "target",
+          "content"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/workers/src/tools.rs:75-90"
+    },
+    {
+      "name": "spawn_worker",
+      "description": "在 harness 内拉起一个 worker 会话：创建子会话（可入工作区分组）→ 命名（标题=<wid>·<短名>）→ 指定模型 → 投递自包含简报。worker 由 harness 自己的 agent-loop 驱动；看门狗按 registry 判定存活并自动重派失败项。wid 是 worker 编号（如 W101）；brief 是自包含任务简报文本。返回 {ok, sessionId, title, wid}。协作闭环：worker 完成后引擎自动写报告 results/<wid>-<short>.md 并发送 WORKER_<wid>_DONE/FAILED 回执到 report_to 目标会话；回执到达会唤醒目标会话的新一轮处理（主 agent 读报告整合结论）。spawn 后应等待回执到达或经 worker_status 查询进度，再整合各 worker 结论。 mode 是可选的工作方式（缺省继承父会话）；worker 报告头部会写明 mode。",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "wid": {
+            "type": "string",
+            "description": "worker 编号（如 W101）"
+          },
+          "brief": {
+            "type": "string",
+            "description": "自包含任务简报文本"
+          },
+          "title": {
+            "type": "string",
+            "description": "会话标题短名（不含 wid· 前缀，≤20 字；缺省取简报首行/文件名）"
+          },
+          "workspace": {
+            "type": "string",
+            "description": "工作区/项目根目录（cwd 分组；缺省 harness 工作区）"
+          },
+          "provider": {
+            "type": "string",
+            "description": "模型 provider（缺省取 harness 默认）"
+          },
+          "model": {
+            "type": "string",
+            "description": "模型名（缺省取 harness 默认）"
+          },
+          "reasoning_effort": {
+            "type": "string",
+            "description": "推理档位（可选）"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "standard",
+              "execution"
+            ],
+            "description": "worker 会话的会话模式（W729）：缺省继承父会话的 mode；standard=逐步直调工具，execution=优先用一个 run_code 程序完成多步依赖调用"
+          },
+          "permission": {
+            "type": "string",
+            "description": "worker 子会话的权限预设（W9）：read-only / write-read / full-access 或自定义预设 id；缺省继承 host 的权限解析（未设置=full-access）。落到子会话 meta 与 registry 行的 permission= token。"
+          },
+          "report_to": {
+            "type": "string",
+            "description": "回报目标会话 id：非空时在简报尾部注入中性回执提示；brief 轮结束后引擎机械写报告 results/<wid>-<short>.md 并发送 WORKER_<wid>_DONE/FAILED 回执到该会话 mailbox；回执到达会唤醒该目标会话新一轮处理（主 agent 读报告整合结论）"
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "wid",
+          "brief"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/workers/src/tools.rs:53-74"
+    },
+    {
+      "name": "stop_worker",
+      "description": "停止一个正在运行的 worker：把它的 registry 行写成 STOPPED 终态（中止 driver、保留会话与行，不删除）——与 spawn_worker 配对，供人工/主 agent 叫停。wid 是 worker 编号（如 W101）；reason 是可选的一行原因，落到行的 stop=<reason> token，worker_status 可见。只对处于 RUNNING 且属于本进程/host 的行生效；找不到或已终态返回 {ok:false,step:\"lookup\",error}。",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "wid": {
+            "type": "string",
+            "description": "要停止的 worker 编号（如 W101）"
+          },
+          "reason": {
+            "type": "string",
+            "description": "可选的一行原因，落成行的 stop=<reason> token；worker_status 可见。Keep it short."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "wid"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "packages/workers/src/tools.ts (W7; no Rust counterpart)"
+    },
+    {
+      "name": "worker_status",
+      "description": "查询 harness 侧 worker registry（registry.tsv）：返回 RUNNING/DONE/FAILED/STOPPED 汇总（RUNNING 行再按 state 标注细分 in-turn=正在跑 turn / idle=等待 mailbox 消息）；可选按 wid 过滤查看单个 worker 的会话与状态。",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "wid": {
+            "type": "string",
+            "description": "worker 编号（如 W101）；缺省返回全部汇总"
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/workers/src/tools.rs:91-104"
+    },
+    {
+      "name": "write_file",
+      "description": "Write text content to a file, creating or overwriting it.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Filesystem path of the file to write."
+          },
+          "content": {
+            "type": "string",
+            "description": "Text content to write."
+          },
+          "desc": {
+            "type": "string",
+            "description": "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short."
+          }
+        },
+        "required": [
+          "path",
+          "content"
+        ],
+        "additionalProperties": false
+      },
+      "sourceRef": "crates/tools/src/builtin.rs:201-215"
+    }
+  ]
+}