deepseek-harness/examples/acp-agent/tests/snapshots/plan-mode/tool-schemas.expected.json

{
  "initial": [
    {
      "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.",
      "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\"."
                },
                "options": {
                  "type": "array",
                  "description": "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" 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."
                }
              },
              "required": [
                "id",
                "question"
              ]
            }
          }
        },
        "required": [
          "questions"
        ]
      }
    },
    {
      "name": "bash",
      "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
      "parameters": {
        "type": "object",
        "properties": {
          "command": {
            "type": "string",
            "description": "The bash command to execute."
          },
          "description": {
            "type": "string",
            "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
          },
          "timeoutMs": {
            "type": "number",
            "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
          },
          "workdir": {
            "type": "string",
            "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
          },
          "run_in_background": {
            "type": "boolean",
            "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
          },
          "sandbox_permissions": {
            "type": "string",
            "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.",
            "enum": [
              "workspace-write",
              "danger-full-access"
            ]
          },
          "justification": {
            "type": "string",
            "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
          }
        },
        "required": [
          "command",
          "description"
        ]
      }
    },
    {
      "name": "create_goal",
      "description": "Create one persisted same-session completion goal when the current direct human request is a long-running objective that should continue across autonomous goal rounds. You may infer that intent without requiring the user to say \"create a goal\". Do not use this for trivial single-turn work. Execution rejects non-human and subagent authority.",
      "parameters": {
        "type": "object",
        "properties": {
          "objective": {
            "type": "string",
            "description": "The concrete completion objective inferred from the direct human request."
          },
          "max_goal_rounds": {
            "type": "number",
            "description": "Optional positive safe-integer limit on automatic continuation rounds."
          }
        },
        "required": [
          "objective"
        ]
      }
    },
    {
      "name": "edit",
      "description": "Edit an existing UTF-8 text file by replacing literal text.",
      "parameters": {
        "type": "object",
        "properties": {
          "file_path": {
            "type": "string",
            "description": "Path to edit, resolved by the filesystem backend."
          },
          "old_string": {
            "type": "string",
            "description": "Literal text to replace. Must match exactly."
          },
          "new_string": {
            "type": "string",
            "description": "Literal replacement text. Use an empty string to delete the match."
          },
          "replace_all": {
            "type": "boolean",
            "description": "Replace all matches. Defaults to false; when false, old_string must appear exactly once."
          },
          "sandbox_permissions": {
            "type": "string",
            "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.",
            "enum": [
              "workspace-write",
              "danger-full-access"
            ]
          },
          "justification": {
            "type": "string",
            "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
          }
        },
        "required": [
          "file_path",
          "old_string",
          "new_string"
        ]
      }
    },
    {
      "name": "exit_plan_mode",
      "description": "Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again.",
      "parameters": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string",
            "description": "The complete plan, as markdown, starting with a # heading that names it."
          }
        },
        "required": [
          "plan"
        ]
      }
    },
    {
      "name": "get_goal",
      "description": "Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal.",
      "parameters": {
        "type": "object",
        "properties": {}
      }
    },
    {
      "name": "ralph",
      "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.",
      "parameters": {
        "type": "object",
        "properties": {
          "objective": {
            "type": "string",
            "description": "The immutable completion objective for every fresh Ralph round."
          },
          "maxRounds": {
            "type": "number",
            "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling."
          }
        },
        "required": [
          "objective"
        ]
      }
    },
    {
      "name": "read",
      "description": "Read a UTF-8 text file and return line-numbered content.",
      "parameters": {
        "type": "object",
        "properties": {
          "file_path": {
            "type": "string",
            "description": "Path to read, resolved by the filesystem backend."
          },
          "offset": {
            "type": "number",
            "description": "1-based first line to return. Defaults to 1."
          },
          "limit": {
            "type": "number",
            "description": "Maximum number of lines to return. Defaults to 2000."
          }
        },
        "required": [
          "file_path"
        ]
      }
    },
    {
      "name": "skill",
      "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.",
      "parameters": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The exact skill name from the available skills list."
          }
        },
        "required": [
          "name"
        ]
      }
    },
    {
      "name": "subagent",
      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "A short (3-5 word) description of the delegated task, for display."
          },
          "prompt": {
            "type": "string",
            "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
          },
          "run_in_background": {
            "type": "boolean",
            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
          }
        },
        "required": [
          "description",
          "prompt"
        ]
      }
    },
    {
      "name": "subagent_fork",
      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "A short (3-5 word) description of the delegated task, for display."
          },
          "prompt": {
            "type": "string",
            "description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
          },
          "run_in_background": {
            "type": "boolean",
            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
          }
        },
        "required": [
          "description",
          "prompt"
        ]
      }
    },
    {
      "name": "task_kill",
      "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
      "parameters": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Task id returned by the tool that started the background work."
          },
          "reason": {
            "type": "string",
            "description": "Optional short reason, recorded in the log and forwarded to the task."
          }
        },
        "required": [
          "task_id"
        ]
      }
    },
    {
      "name": "task_list",
      "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
      "parameters": {
        "type": "object",
        "properties": {}
      }
    },
    {
      "name": "task_output",
      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
      "parameters": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Task id returned by the tool that started the background work."
          },
          "wait": {
            "type": "boolean",
            "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."
          },
          "timeout_ms": {
            "type": "number",
            "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
          }
        },
        "required": [
          "task_id"
        ]
      }
    },
    {
      "name": "todo_write",
      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
      "parameters": {
        "type": "object",
        "properties": {
          "todos": {
            "type": "array",
            "description": "The COMPLETE task list, replacing any previous list.",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "content": {
                  "type": "string",
                  "description": "What the task is — a short imperative line."
                },
                "status": {
                  "type": "string",
                  "description": "pending (not started) | in_progress (now) | completed (done).",
                  "enum": [
                    "pending",
                    "in_progress",
                    "completed"
                  ]
                }
              },
              "required": [
                "content",
                "status"
              ]
            }
          }
        },
        "required": [
          "todos"
        ]
      }
    },
    {
      "name": "update_goal",
      "description": "Update the exact current goal revision. edit, pause, and resume require a direct top-level human request. During an automatic continuation of the current goal, complete and blocked are also allowed. blocked is rejected before the configured minimum round count; the model remains responsible for judging that the same condition persisted across those rounds and must explain it in blocked_reason.",
      "parameters": {
        "type": "object",
        "properties": {
          "goal_id": {
            "type": "string",
            "description": "Exact id returned by get_goal."
          },
          "revision": {
            "type": "number",
            "description": "Exact positive revision returned by get_goal."
          },
          "action": {
            "type": "string",
            "description": "edit | pause | resume | complete | blocked",
            "enum": [
              "edit",
              "pause",
              "resume",
              "complete",
              "blocked"
            ]
          },
          "objective": {
            "type": "string",
            "description": "Replacement objective; valid only with action edit."
          },
          "max_goal_rounds": {
            "type": "number",
            "description": "Replacement cap; valid only with action edit."
          },
          "blocked_reason": {
            "type": "string",
            "description": "Concrete blocking condition; required only with action blocked."
          }
        },
        "required": [
          "goal_id",
          "revision",
          "action"
        ]
      }
    },
    {
      "name": "workflow",
      "description": "Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.",
      "parameters": {
        "type": "object",
        "properties": {
          "script": {
            "type": "string",
            "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."
          },
          "meta": {
            "type": "object",
            "description": "The workflow identity block (plain JSON — never code).",
            "additionalProperties": true,
            "properties": {
              "name": {
                "type": "string",
                "description": "Short kebab-case workflow name."
              },
              "description": {
                "type": "string",
                "description": "One-line description of what the workflow does."
              },
              "whenToUse": {
                "type": "string",
                "description": "Optional guidance on when this workflow applies."
              },
              "phases": {
                "type": "array",
                "description": "Optional phase declarations matched by phase() calls.",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "title": {
                      "type": "string",
                      "description": "The phase title phase() calls match by exact string."
                    },
                    "detail": {
                      "type": "string",
                      "description": "Optional one-line description of the phase."
                    },
                    "provider": {
                      "type": "string",
                      "description": "Optional provider override this phase is expected to use."
                    },
                    "model": {
                      "type": "string",
                      "description": "Optional model override this phase is expected to use."
                    }
                  },
                  "required": [
                    "title"
                  ]
                }
              }
            },
            "required": [
              "name",
              "description"
            ]
          },
          "args": {
            "type": "object",
            "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).",
            "additionalProperties": true
          }
        },
        "required": [
          "script",
          "meta"
        ]
      }
    },
    {
      "name": "write",
      "description": "Create or fully replace a UTF-8 text file.",
      "parameters": {
        "type": "object",
        "properties": {
          "file_path": {
            "type": "string",
            "description": "Path to write, resolved by the filesystem backend."
          },
          "content": {
            "type": "string",
            "description": "Full UTF-8 text content to write."
          },
          "sandbox_permissions": {
            "type": "string",
            "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.",
            "enum": [
              "workspace-write",
              "danger-full-access"
            ]
          },
          "justification": {
            "type": "string",
            "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
          }
        },
        "required": [
          "file_path",
          "content"
        ]
      }
    }
  ],
  "changes": [
    [
      {
        "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.",
        "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\"."
                  },
                  "options": {
                    "type": "array",
                    "description": "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" 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."
                  }
                },
                "required": [
                  "id",
                  "question"
                ]
              }
            }
          },
          "required": [
            "questions"
          ]
        }
      },
      {
        "name": "bash",
        "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
        "parameters": {
          "type": "object",
          "properties": {
            "command": {
              "type": "string",
              "description": "The bash command to execute."
            },
            "description": {
              "type": "string",
              "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
            },
            "timeoutMs": {
              "type": "number",
              "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
            },
            "workdir": {
              "type": "string",
              "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
            },
            "run_in_background": {
              "type": "boolean",
              "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
            },
            "sandbox_permissions": {
              "type": "string",
              "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.",
              "enum": [
                "workspace-write",
                "danger-full-access"
              ]
            },
            "justification": {
              "type": "string",
              "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
            }
          },
          "required": [
            "command",
            "description"
          ]
        }
      },
      {
        "name": "create_goal",
        "description": "Create one persisted same-session completion goal when the current direct human request is a long-running objective that should continue across autonomous goal rounds. You may infer that intent without requiring the user to say \"create a goal\". Do not use this for trivial single-turn work. Execution rejects non-human and subagent authority.",
        "parameters": {
          "type": "object",
          "properties": {
            "objective": {
              "type": "string",
              "description": "The concrete completion objective inferred from the direct human request."
            },
            "max_goal_rounds": {
              "type": "number",
              "description": "Optional positive safe-integer limit on automatic continuation rounds."
            }
          },
          "required": [
            "objective"
          ]
        }
      },
      {
        "name": "edit",
        "description": "Edit an existing UTF-8 text file by replacing literal text.",
        "parameters": {
          "type": "object",
          "properties": {
            "file_path": {
              "type": "string",
              "description": "Path to edit, resolved by the filesystem backend."
            },
            "old_string": {
              "type": "string",
              "description": "Literal text to replace. Must match exactly."
            },
            "new_string": {
              "type": "string",
              "description": "Literal replacement text. Use an empty string to delete the match."
            },
            "replace_all": {
              "type": "boolean",
              "description": "Replace all matches. Defaults to false; when false, old_string must appear exactly once."
            },
            "sandbox_permissions": {
              "type": "string",
              "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.",
              "enum": [
                "workspace-write",
                "danger-full-access"
              ]
            },
            "justification": {
              "type": "string",
              "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
            }
          },
          "required": [
            "file_path",
            "old_string",
            "new_string"
          ]
        }
      },
      {
        "name": "exit_plan_mode",
        "description": "Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again.",
        "parameters": {
          "type": "object",
          "properties": {
            "plan": {
              "type": "string",
              "description": "The complete plan, as markdown, starting with a # heading that names it."
            }
          },
          "required": [
            "plan"
          ]
        }
      },
      {
        "name": "get_goal",
        "description": "Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal.",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      },
      {
        "name": "ralph",
        "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.",
        "parameters": {
          "type": "object",
          "properties": {
            "objective": {
              "type": "string",
              "description": "The immutable completion objective for every fresh Ralph round."
            },
            "maxRounds": {
              "type": "number",
              "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling."
            }
          },
          "required": [
            "objective"
          ]
        }
      },
      {
        "name": "read",
        "description": "Read a UTF-8 text file and return line-numbered content.",
        "parameters": {
          "type": "object",
          "properties": {
            "file_path": {
              "type": "string",
              "description": "Path to read, resolved by the filesystem backend."
            },
            "offset": {
              "type": "number",
              "description": "1-based first line to return. Defaults to 1."
            },
            "limit": {
              "type": "number",
              "description": "Maximum number of lines to return. Defaults to 2000."
            }
          },
          "required": [
            "file_path"
          ]
        }
      },
      {
        "name": "skill",
        "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.",
        "parameters": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The exact skill name from the available skills list."
            }
          },
          "required": [
            "name"
          ]
        }
      },
      {
        "name": "subagent",
        "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
        "parameters": {
          "type": "object",
          "properties": {
            "description": {
              "type": "string",
              "description": "A short (3-5 word) description of the delegated task, for display."
            },
            "prompt": {
              "type": "string",
              "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
            },
            "run_in_background": {
              "type": "boolean",
              "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
            }
          },
          "required": [
            "description",
            "prompt"
          ]
        }
      },
      {
        "name": "subagent_fork",
        "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
        "parameters": {
          "type": "object",
          "properties": {
            "description": {
              "type": "string",
              "description": "A short (3-5 word) description of the delegated task, for display."
            },
            "prompt": {
              "type": "string",
              "description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
            },
            "run_in_background": {
              "type": "boolean",
              "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
            }
          },
          "required": [
            "description",
            "prompt"
          ]
        }
      },
      {
        "name": "task_kill",
        "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
        "parameters": {
          "type": "object",
          "properties": {
            "task_id": {
              "type": "string",
              "description": "Task id returned by the tool that started the background work."
            },
            "reason": {
              "type": "string",
              "description": "Optional short reason, recorded in the log and forwarded to the task."
            }
          },
          "required": [
            "task_id"
          ]
        }
      },
      {
        "name": "task_list",
        "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      },
      {
        "name": "task_output",
        "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
        "parameters": {
          "type": "object",
          "properties": {
            "task_id": {
              "type": "string",
              "description": "Task id returned by the tool that started the background work."
            },
            "wait": {
              "type": "boolean",
              "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."
            },
            "timeout_ms": {
              "type": "number",
              "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
            }
          },
          "required": [
            "task_id"
          ]
        }
      },
      {
        "name": "todo_write",
        "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
        "parameters": {
          "type": "object",
          "properties": {
            "todos": {
              "type": "array",
              "description": "The COMPLETE task list, replacing any previous list.",
              "items": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "What the task is — a short imperative line."
                  },
                  "status": {
                    "type": "string",
                    "description": "pending (not started) | in_progress (now) | completed (done).",
                    "enum": [
                      "pending",
                      "in_progress",
                      "completed"
                    ]
                  }
                },
                "required": [
                  "content",
                  "status"
                ]
              }
            }
          },
          "required": [
            "todos"
          ]
        }
      },
      {
        "name": "update_goal",
        "description": "Update the exact current goal revision. edit, pause, and resume require a direct top-level human request. During an automatic continuation of the current goal, complete and blocked are also allowed. blocked is rejected before the configured minimum round count; the model remains responsible for judging that the same condition persisted across those rounds and must explain it in blocked_reason.",
        "parameters": {
          "type": "object",
          "properties": {
            "goal_id": {
              "type": "string",
              "description": "Exact id returned by get_goal."
            },
            "revision": {
              "type": "number",
              "description": "Exact positive revision returned by get_goal."
            },
            "action": {
              "type": "string",
              "description": "edit | pause | resume | complete | blocked",
              "enum": [
                "edit",
                "pause",
                "resume",
                "complete",
                "blocked"
              ]
            },
            "objective": {
              "type": "string",
              "description": "Replacement objective; valid only with action edit."
            },
            "max_goal_rounds": {
              "type": "number",
              "description": "Replacement cap; valid only with action edit."
            },
            "blocked_reason": {
              "type": "string",
              "description": "Concrete blocking condition; required only with action blocked."
            }
          },
          "required": [
            "goal_id",
            "revision",
            "action"
          ]
        }
      },
      {
        "name": "workflow",
        "description": "Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.",
        "parameters": {
          "type": "object",
          "properties": {
            "script": {
              "type": "string",
              "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."
            },
            "meta": {
              "type": "object",
              "description": "The workflow identity block (plain JSON — never code).",
              "additionalProperties": true,
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Short kebab-case workflow name."
                },
                "description": {
                  "type": "string",
                  "description": "One-line description of what the workflow does."
                },
                "whenToUse": {
                  "type": "string",
                  "description": "Optional guidance on when this workflow applies."
                },
                "phases": {
                  "type": "array",
                  "description": "Optional phase declarations matched by phase() calls.",
                  "items": {
                    "type": "object",
                    "additionalProperties": true,
                    "properties": {
                      "title": {
                        "type": "string",
                        "description": "The phase title phase() calls match by exact string."
                      },
                      "detail": {
                        "type": "string",
                        "description": "Optional one-line description of the phase."
                      },
                      "provider": {
                        "type": "string",
                        "description": "Optional provider override this phase is expected to use."
                      },
                      "model": {
                        "type": "string",
                        "description": "Optional model override this phase is expected to use."
                      }
                    },
                    "required": [
                      "title"
                    ]
                  }
                }
              },
              "required": [
                "name",
                "description"
              ]
            },
            "args": {
              "type": "object",
              "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).",
              "additionalProperties": true
            }
          },
          "required": [
            "script",
            "meta"
          ]
        }
      },
      {
        "name": "write",
        "description": "Create or fully replace a UTF-8 text file.",
        "parameters": {
          "type": "object",
          "properties": {
            "file_path": {
              "type": "string",
              "description": "Path to write, resolved by the filesystem backend."
            },
            "content": {
              "type": "string",
              "description": "Full UTF-8 text content to write."
            },
            "sandbox_permissions": {
              "type": "string",
              "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.",
              "enum": [
                "workspace-write",
                "danger-full-access"
              ]
            },
            "justification": {
              "type": "string",
              "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
            }
          },
          "required": [
            "file_path",
            "content"
          ]
        }
      }
    ]
  ]
}