Add tool-schemas/ — JSON input_schema for 35 builtin tools (refs #22)

tool-schemas/README.md

@@ -0,0 +1,57 @@
+# Tool Schemas
+
+JSON `input_schema` for Claude Code's builtin tools, captured verbatim from
+the API request body Claude Code sends to Anthropic.
+
+Seeded from issue
+[#22](https://github.com/Piebald-AI/claude-code-system-prompts/issues/22).
+
+35 schemas total, grouped by how they surface in the `tools[]` payload:
+
+| Group | Tools | How to surface |
+|---|---|---|
+| **Default main loop** (29) | `agent`, `ask-user-question`, `bash`, `cron-*`, `edit`, `enter-/exit-plan-mode`, `enter-/exit-worktree`, `lsp`, `monitor`, `notebook-edit`, `push-notification`, `read`, `remote-trigger`, `schedule-wakeup`, `skill`, `task-*`, `web-fetch`, `web-search`, `workflow`, `write` | Standard Claude Code session, no flags |
+| **Agent Teams** (3) | `send-message`, `team-create`, `team-delete` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` or `--agent-teams` (`utils/agentSwarmsEnabled.ts`) |
+| **`local-agent` entrypoint** (2) | `glob`, `grep` | `CLAUDE_CODE_ENTRYPOINT=local-agent` (sub-agent context that exposes the dedicated search tools instead of having the model shell out via `Bash`) |
+| **Brief / assistant mode** (1) | `send-user-message` | `CLAUDE_CODE_BRIEF=1` (KAIROS-style assistant entrypoint) |
+
+Build-time-gated tools (`SendUserFile`, `Snip`, `WebBrowser`, …) live
+behind `bun:bundle` `feature('KAIROS')` / `feature('WEB_BROWSER_TOOL')`
+macros. Their code is present in the public native binary but they
+require additional runtime gates not exposed by the env flags above;
+left for a follow-up PR. `PowerShell` is Windows-only.
+
+## File contents
+
+Each `<tool>.json` is a standalone JSON Schema document — the exact value of
+`tools[i].input_schema` from a real `POST /v1/messages` request, written with
+`JSON.stringify(value, null, 2)` so diffs stay readable. No wrapping, no key
+reordering, no other transformation.
+
+The tool's prose description is not duplicated here — it lives in the
+[`system-prompts/`](../system-prompts/) directory (files matching
+`tool-description-<tool>*.md`).
+
+## Source
+
+Captured at the wire level via a local reverse proxy sitting between
+Claude Code and `api.anthropic.com`. Because the schemas come from the API
+payload rather than from parsing `cli.js`, they are independent of
+bundler/minifier changes across Claude Code releases.
+
+## Naming
+
+`<kebab-case-tool-name>.json` — e.g. `bash.json`, `web-fetch.json`,
+`ask-user-question.json`. The tool name is in the filename only; the file
+body is the schema itself.
+
+If a layout closer to `system-prompts/tool-description-<tool>.md` is
+preferred (co-located, single dir, `tool-schema-<tool>.json` prefix), the
+files rename cleanly — happy to follow whatever convention the maintainers
+want.
+
+## Not covered
+
+`StructuredOutput`, a sub-agent tool whose `input_schema` is supplied at
+spawn time by the caller rather than defined by Claude Code, has no fixed
+shape to record.

tool-schemas/agent.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "description": {
+      "description": "A short (3-5 word) description of the task",
+      "type": "string"
+    },
+    "isolation": {
+      "description": "Isolation mode. \"worktree\" creates a temporary git worktree so the agent works on an isolated copy of the repo.",
+      "enum": [
+        "worktree"
+      ],
+      "type": "string"
+    },
+    "model": {
+      "description": "Optional model override for this agent. Takes precedence over the agent definition's model frontmatter. If omitted, uses the agent definition's model, or inherits from the parent.",
+      "enum": [
+        "sonnet",
+        "opus",
+        "haiku",
+        "fable"
+      ],
+      "type": "string"
+    },
+    "prompt": {
+      "description": "The task for the agent to perform",
+      "type": "string"
+    },
+    "run_in_background": {
+      "description": "Set to true to run this agent in the background. You will be notified when it completes.",
+      "type": "boolean"
+    },
+    "subagent_type": {
+      "description": "The type of specialized agent to use for this task",
+      "type": "string"
+    }
+  },
+  "required": [
+    "description",
+    "prompt"
+  ],
+  "type": "object"
+}

tool-schemas/ask-user-question.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "annotations": {
+      "additionalProperties": {
+        "additionalProperties": false,
+        "properties": {
+          "notes": {
+            "description": "Free-text notes the user added to their selection.",
+            "type": "string"
+          },
+          "preview": {
+            "description": "The preview content of the selected option, if the question used previews.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "description": "Optional per-question annotations from the user (e.g., notes on preview selections). Keyed by question text.",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "answers": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "User answers collected by the permission component",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "metadata": {
+      "additionalProperties": false,
+      "description": "Optional metadata for tracking and analytics purposes. Not displayed to user.",
+      "properties": {
+        "source": {
+          "description": "Optional identifier for the source of this question (e.g., \"remember\" for /remember command). Used for analytics tracking.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "questions": {
+      "description": "Questions to ask the user (1-4 questions)",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "header": {
+            "description": "Very short label displayed as a chip/tag (max 12 chars). Examples: \"Auth method\", \"Library\", \"Approach\".",
+            "type": "string"
+          },
+          "multiSelect": {
+            "default": false,
+            "description": "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive.",
+            "type": "boolean"
+          },
+          "options": {
+            "description": "The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). There should be no 'Other' option, that will be provided automatically.",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "description": {
+                  "description": "Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
+                  "type": "string"
+                },
+                "label": {
+                  "description": "The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.",
+                  "type": "string"
+                },
+                "preview": {
+                  "description": "Optional preview content rendered when this option is focused. Use for mockups, code snippets, or visual comparisons that help users compare options. See the tool description for the expected content format.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "label",
+                "description"
+              ],
+              "type": "object"
+            },
+            "maxItems": 4,
+            "minItems": 2,
+            "type": "array"
+          },
+          "question": {
+            "description": "The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: \"Which library should we use for date formatting?\" If multiSelect is true, phrase it accordingly, e.g. \"Which features do you want to enable?\"",
+            "type": "string"
+          }
+        },
+        "required": [
+          "question",
+          "header",
+          "options",
+          "multiSelect"
+        ],
+        "type": "object"
+      },
+      "maxItems": 4,
+      "minItems": 1,
+      "type": "array"
+    }
+  },
+  "required": [
+    "questions"
+  ],
+  "type": "object"
+}

tool-schemas/bash.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "command": {
+      "description": "The command to execute",
+      "type": "string"
+    },
+    "dangerouslyDisableSandbox": {
+      "description": "Set this to true to dangerously override sandbox mode and run commands without sandboxing.",
+      "type": "boolean"
+    },
+    "description": {
+      "description": "Clear, concise description of what this command does in active voice. Never use words like \"complex\" or \"risk\" in the description - just describe what it does.\n\nFor simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):\n- ls → \"List files in current directory\"\n- git status → \"Show working tree status\"\n- npm install → \"Install package dependencies\"\n\nFor commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:\n- find . -name \"*.tmp\" -exec rm {} \\; → \"Find and delete all .tmp files recursively\"\n- git reset --hard origin/main → \"Discard all local changes and match remote main\"\n- curl -s url | jq '.data[]' → \"Fetch JSON from URL and extract data array elements\"",
+      "type": "string"
+    },
+    "run_in_background": {
+      "description": "Set to true to run this command in the background.",
+      "type": "boolean"
+    },
+    "timeout": {
+      "description": "Optional timeout in milliseconds (max 600000)",
+      "type": "number"
+    }
+  },
+  "required": [
+    "command"
+  ],
+  "type": "object"
+}

tool-schemas/cron-create.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "cron": {
+      "description": "Standard 5-field cron expression in local time: \"M H DoM Mon DoW\" (e.g. \"*/5 * * * *\" = every 5 minutes, \"30 14 28 2 *\" = Feb 28 at 2:30pm local once).",
+      "type": "string"
+    },
+    "durable": {
+      "description": "true = persist to .claude/scheduled_tasks.json and survive restarts. false (default) = in-memory only, dies when this Claude session ends. Use true only when the user asks the task to survive across sessions.",
+      "type": "boolean"
+    },
+    "prompt": {
+      "description": "The prompt to enqueue at each fire time.",
+      "type": "string"
+    },
+    "recurring": {
+      "description": "true (default) = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete. Use false for \"remind me at X\" one-shot requests with pinned minute/hour/dom/month.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "cron",
+    "prompt"
+  ],
+  "type": "object"
+}

tool-schemas/cron-delete.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "description": "Job ID returned by CronCreate.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id"
+  ],
+  "type": "object"
+}

tool-schemas/cron-list.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {},
+  "type": "object"
+}

tool-schemas/edit.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "file_path": {
+      "description": "The absolute path to the file to modify",
+      "type": "string"
+    },
+    "new_string": {
+      "description": "The text to replace it with (must be different from old_string)",
+      "type": "string"
+    },
+    "old_string": {
+      "description": "The text to replace",
+      "type": "string"
+    },
+    "replace_all": {
+      "default": false,
+      "description": "Replace all occurrences of old_string (default false)",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "file_path",
+    "old_string",
+    "new_string"
+  ],
+  "type": "object"
+}

tool-schemas/enter-plan-mode.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {},
+  "type": "object"
+}

tool-schemas/enter-worktree.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "description": "Optional name for a new worktree. Each \"/\"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided. Mutually exclusive with `path`.",
+      "type": "string"
+    },
+    "path": {
+      "description": "Path to an existing worktree of the current repository to switch into instead of creating a new one. Must appear in `git worktree list` for the current repo. Mutually exclusive with `name`.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

tool-schemas/exit-plan-mode.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": {},
+  "properties": {
+    "allowedPrompts": {
+      "description": "Prompt-based permissions needed to implement the plan. These describe categories of actions rather than specific commands.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "prompt": {
+            "description": "Semantic description of the action, e.g. \"run tests\", \"install dependencies\"",
+            "type": "string"
+          },
+          "tool": {
+            "description": "The tool this prompt applies to",
+            "enum": [
+              "Bash"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "tool",
+          "prompt"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}