Skip to content

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

Open
YiRaaaan wants to merge 9 commits into
Piebald-AI:mainfrom
YiRaaaan:tool-schemas-poc
Open

Add tool-schemas/ — JSON input_schema for 35 builtin tools (refs #22)#24
YiRaaaan wants to merge 9 commits into
Piebald-AI:mainfrom
YiRaaaan:tool-schemas-poc

Conversation

@YiRaaaan

@YiRaaaan YiRaaaan commented Jun 8, 2026

Copy link
Copy Markdown

Seeded from #22. Thanks for the welcoming reply there — I went ahead and
captured the full default tool set rather than just Bash, since the data
turned out to make a small but interesting case for the approach.

What's added

A new top-level tool-schemas/ directory with 35 standalone JSON Schema
files, each the verbatim value of tools[i].input_schema from a real
POST /v1/messages request, plus a short README. No transformation, no
key reordering, no wrapping — just JSON.stringify(value, null, 2) so
diffs stay readable.

Files are grouped by what surfaces them in tools[]:

Group Count How to surface
Default main loop 29 Standard Claude Code session
Agent Teams 3 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 / --agent-teams
local-agent sub-agent 2 CLAUDE_CODE_ENTRYPOINT=local-agent (adds Glob/Grep)
Brief / KAIROS assistant 1 CLAUDE_CODE_BRIEF=1 (adds SendUserMessage)

Stability evidence (relevant to your maintenance-burden concern)

I compared captures from v2.1.161 through v2.1.168 (seven patch
releases). 28 of 29 default schemas are byte-identical across that
range. The only change was LSP, which gained a new query property
for the workspaceSymbol operation:

+ "query": {
+   "description": "The symbol name or partial name to search for (workspaceSymbol only). ...",
+   "type": "string"
+ }

That kind of contract change is exactly what schema tracking surfaces
and prose-description tracking cannot. Over the same seven versions,
prose descriptions for AskUserQuestion, LSP, NotebookEdit, and
Workflow changed — so schemas and descriptions vary on independent
axes.

Agent invariance

A given tool's input_schema is identical whether the request comes
from the main loop, the Explore subagent, a Workflow-spawned
subagent, or any other context. Comparing 188+ captures across those,
every shared tool name produces the same byte-for-byte schema.
Subagents differ from the main loop only in which tools they get,
not in schema content — so one file per tool is sufficient (no
need to partition by caller).

Deliberately excluded

StructuredOutput — a sub-agent tool whose input_schema is supplied
at spawn time by the caller (the workflow orchestration script), not
defined by Claude Code. Captures show two unrelated schemas for it
depending on the workflow; recording a fixed file would misrepresent
the tool.

Out of scope (left for follow-ups)

  • SendUserFile, Snip, WebBrowser — code is present in the public
    native binary but requires a server-side GrowthBook entitlement
    (tengu_kairos) not flippable from local env.
  • request_teach_access — comes from the mcp__computer-use__* MCP
    server, requires that server installed and connected.
  • PowerShell — Windows-only.

Open questions for you

  1. Naming: I used tool-schemas/<kebab>.json to keep schemas in a
    self-contained directory. If you'd rather mirror system-prompts/
    with tool-schema-<kebab>.json files inside that same directory,
    the rename is mechanical — happy to do it if you prefer.

  2. Main README integration: I haven't touched tools/updatePrompts.js
    or the main README.md listing — those are wired to your
    prompts-X.X.X.json extractor, which uses a different input path
    than these schemas. If you'd like the schemas to also appear in
    the main README's tool list (with versions / sizes / etc.), happy
    to follow up with a small updatePrompts.js patch that scans
    tool-schemas/ and adds a Tool Schemas section. Kept out of this
    PR to keep one change at a time.

  3. Maintenance: I'm happy to refresh these on the same cadence
    as your existing extractor — capturing through the proxy is a
    claude -p away and the diff per release looks small (often
    empty). Let me know if you'd rather do it yourselves or have me
    send PRs.

Branch / commit notes

Seven commits, atomic and reviewable in order. The early ones add
the default 29, the middle ones add the gated groups, and the last
slimming-down commits respond to a self-review pass.

Summary by CodeRabbit

  • Documentation
    • Added comprehensive JSON schemas documenting input contracts for many built-in tools (file ops, tasks, cron, notifications, messaging, web search, LSP, grep, shell, workflows, and more).
    • Added a README describing repo structure, naming/serialization conventions, capture method, schema grouping, and notes on which runtime-provided schemas are excluded.

@coderabbitai

coderabbitai Bot commented Jun 8, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Adds 35 draft-2020-12 JSON Schema documents under tool-schemas/ plus a README documenting provenance, capture method, serialization/naming, grouping, gating, and the explicit exclusion of StructuredOutput schemas.

Changes

Tool Schema Definitions

Layer / File(s) Summary
Schema Documentation and Architecture
tool-schemas/README.md
Documentation explaining the repo contains verbatim input_schema values captured from Anthropic API payloads, grouping/counts, build-time gated locations, serialization/naming rules, reverse-proxy capture method, and that StructuredOutput schemas are not stored.
File and Content Operations
tool-schemas/read.json, tool-schemas/write.json, tool-schemas/edit.json, tool-schemas/glob.json, tool-schemas/grep.json, tool-schemas/notebook-edit.json, tool-schemas/web-fetch.json
Schemas for file I/O and content search: read (file_path required, optional limit/offset/pages), write (file_path and content required), edit (file_path, old_string, new_string, optional replace_all), glob (pattern required), grep (rg-style options and output modes), notebook-edit (cell ops and edit_mode), web-fetch (url and prompt required).
Task, Project, and Workflow Management
tool-schemas/task-create.json, tool-schemas/task-get.json, tool-schemas/task-list.json, tool-schemas/task-update.json, tool-schemas/task-stop.json, tool-schemas/task-output.json, tool-schemas/workflow.json
Schemas for task lifecycle and workflows: create (subject/description/metadata), get (taskId), list (empty object), update (taskId plus status/owner/deps/metadata), stop (task_id), output (task_id, block, timeout defaults/limits), workflow (script/name/resumeFromRunId/args).
Communication, Messaging, and Collaboration
tool-schemas/ask-user-question.json, tool-schemas/send-message.json, tool-schemas/send-user-message.json, tool-schemas/push-notification.json
Schemas for user interactions: ask-user-question (1–4 questions with 2–4 options), send-message (string or typed variants like shutdown/approval), send-user-message (markdown message and optional attachments as paths or uploaded-file objects), push-notification (message + const status "proactive").
Planning Mode, Worktree Navigation, and Exit Handlers
tool-schemas/enter-plan-mode.json, tool-schemas/exit-plan-mode.json, tool-schemas/enter-worktree.json, tool-schemas/exit-worktree.json
Schemas for development environment transitions: enter-plan-mode (empty object), exit-plan-mode (allowedPrompts array with item {tool:"Bash", prompt}), enter-worktree (optional name/path), exit-worktree (action enum `keep
Execution, Scheduling, and Process Control
tool-schemas/bash.json, tool-schemas/cron-create.json, tool-schemas/cron-delete.json, tool-schemas/cron-list.json, tool-schemas/monitor.json, tool-schemas/schedule-wakeup.json, tool-schemas/agent.json
Schemas for execution and scheduling: bash (command, sandbox/timeout/background), cron-create/delete/list, monitor (command, persistent, timeout_ms), schedule-wakeup (delaySeconds/reason/prompt), agent (isolation/model/prompt/description).
Web Search, LSP, Team Management, Skills, and Remote Integration
tool-schemas/web-search.json, tool-schemas/lsp.json, tool-schemas/team-create.json, tool-schemas/team-delete.json, tool-schemas/skill.json, tool-schemas/remote-trigger.json
Schemas for integrations: web-search (query and optional domain allow/block lists), lsp (operation enum with file/line/character), team-create (team_name regex), team-delete (empty), skill (skill + args), remote-trigger (action enum, trigger_id pattern, optional body).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

  • Issue #22: This PR implements the proposal to add verbatim JSON input_schema files and README explaining capture methodology and organization; files like tool-schemas/bash.json directly match that proposal.

Poem

🐰 I hopped through schema fields tonight,

wrote types and enums by moonlight,
from bash and grep to workflow runs,
thirty-five contracts, tidy and done,
a rabbit’s cheer for clear JSON light.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title clearly and concisely summarizes the main change: adding a tool-schemas directory with JSON input schemas for 35 builtin tools, directly matching the primary objective of the changeset.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tool-schemas/README.md`:
- Line 3: Update the README text that reads "JSON `input_schema` for Claude
Code's builtin tools, captured verbatim from" to use the standard spelling
"built-in" (i.e., "JSON `input_schema` for Claude Code's built-in tools,
captured verbatim from"); search for other occurrences of "builtin" in the
README and replace them with "built-in" to keep user-facing docs consistent and
clear.
- Around line 31-33: Update the README entry that references
`tool-description-<tool>.md` so the hyperlink points directly to the actual file
pattern location instead of the parent directory; replace the link target
`../system-prompts/` with the precise path or pattern that resolves to
`system-prompts/tool-description-<tool>.md` (or a glob that navigates directly
to those files) and ensure the link label still mentions
`tool-description-<tool>.md` to avoid misleading readers.

In `@tool-schemas/task-stop.json`:
- Around line 9-11: The schemas are inconsistent: task-stop.json and
task-output.json use "task_id" while task-get.json and task-update.json use
"taskId"; pick one canonical field name (preferably "taskId" to match existing
camelCase usage) and update the schemas so all operations use the same property;
specifically change the "task_id" property in task-stop.json and
task-output.json to "taskId" (update description/type entries if necessary) and
run schema validation to ensure no other references expect the old name.
- Around line 1-15: Add a required constraint to the JSON schema so payloads
must include task_id; specifically, update the root schema (containing
properties "shell_id" and "task_id") to include a "required" array with
"task_id" (e.g., "required": ["task_id"]), leaving "shell_id"
optional/deprecated as-is so backward-compatibility is preserved but invalid
payloads without task_id are rejected.

In `@tool-schemas/workflow.json`:
- Around line 1-36: The schema currently allows calls with none of the workflow
specifiers set (no script, scriptPath or name); update the JSON Schema to
require exactly one of those properties by adding a top-level oneOf (or anyOf
with an additional dependent requirement) that lists objects with "required":
["script"], "required": ["scriptPath"], and "required": ["name"] (or use oneOf
to enforce exclusivity), referencing the existing property names "script",
"scriptPath", and "name" so validation fails unless one of those is provided.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e63ba804-aad9-4485-ae6c-59e94b9b3553

📥 Commits

Reviewing files that changed from the base of the PR and between 8643350 and 214eea6.

📒 Files selected for processing (36)
  • tool-schemas/README.md
  • tool-schemas/agent.json
  • tool-schemas/ask-user-question.json
  • tool-schemas/bash.json
  • tool-schemas/cron-create.json
  • tool-schemas/cron-delete.json
  • tool-schemas/cron-list.json
  • tool-schemas/edit.json
  • tool-schemas/enter-plan-mode.json
  • tool-schemas/enter-worktree.json
  • tool-schemas/exit-plan-mode.json
  • tool-schemas/exit-worktree.json
  • tool-schemas/glob.json
  • tool-schemas/grep.json
  • tool-schemas/lsp.json
  • tool-schemas/monitor.json
  • tool-schemas/notebook-edit.json
  • tool-schemas/push-notification.json
  • tool-schemas/read.json
  • tool-schemas/remote-trigger.json
  • tool-schemas/schedule-wakeup.json
  • tool-schemas/send-message.json
  • tool-schemas/send-user-message.json
  • tool-schemas/skill.json
  • tool-schemas/task-create.json
  • tool-schemas/task-get.json
  • tool-schemas/task-list.json
  • tool-schemas/task-output.json
  • tool-schemas/task-stop.json
  • tool-schemas/task-update.json
  • tool-schemas/team-create.json
  • tool-schemas/team-delete.json
  • tool-schemas/web-fetch.json
  • tool-schemas/web-search.json
  • tool-schemas/workflow.json
  • tool-schemas/write.json

Comment thread tool-schemas/README.md
Comment thread tool-schemas/README.md Outdated
Comment thread tool-schemas/task-stop.json
Comment thread tool-schemas/task-stop.json
Comment thread tool-schemas/workflow.json
@YiRaaaan

YiRaaaan commented Jun 8, 2026

Copy link
Copy Markdown
Author

Quick note on intent for future readers in response to the @coderabbitai review:

The files under tool-schemas/ are verbatim wire captures — each <tool>.json is the exact tools[i].input_schema value Anthropic receives from a real POST /v1/messages request, written with JSON.stringify(value, null, 2) and no transformation. That "no normalization" property is the PR's core credibility argument (no extraction heuristic, no key reordering, byte-stable across patch releases).

So 4 of the 5 suggestions land on the wrong side of that line:

Replied inline on each with the specific reason. Marking the review-requested-changes as intentional design rather than oversight.

@coderabbitai

coderabbitai Bot commented Jun 8, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

@YiRaaaan — thanks for the clear write-up; this is exactly the kind of intent note that helps calibrate future reviews.

The verbatim-capture constraint is a strong one and my suggestions violated it on all four counts. To summarise the corrections back:

Suggestion Why it was wrong
#3 — add required fields Would invent constraints absent from the wire payload
#5 — add oneOf Same — normative additions, not present in the captured schema
#4 — rename task_idtaskId Real naming inconsistency in Claude Code's source; preserving it is the point
#1builtinbuilt-in Matches upstream README spelling; no change needed

I'll add learnings so this doesn't recur on future reviews of this repo.

🐇 ✦


✏️ Learnings added
Learnt from: YiRaaaan
URL: https://github.com/Piebald-AI/claude-code-system-prompts/pull/24

Timestamp: 2026-06-08T06:31:44.273Z
Learning: In the Piebald-AI/claude-code-system-prompts repository, the files under `tool-schemas/` are **verbatim wire captures**: each `<tool>.json` is the exact `tools[i].input_schema` value from a real `POST /v1/messages` Anthropic API request, serialized with `JSON.stringify(value, null, 2)` and zero transformation. Reviewing these files should never suggest adding, removing, or renaming fields (e.g. adding `required`, `oneOf`, or renaming `task_id` to `taskId`), because that would alter the byte-level fidelity that is the core credibility argument of the PR. Field-naming inconsistencies (e.g. snake_case in `task-stop`/`task-output` vs camelCase in `task-get`/`task-update`) are intentional artifacts reflecting real inconsistencies in Claude Code's source code, and should be preserved and documented rather than normalized.

Learnt from: YiRaaaan
URL: https://github.com/Piebald-AI/claude-code-system-prompts/pull/24

Timestamp: 2026-06-08T06:31:44.273Z
Learning: In the Piebald-AI/claude-code-system-prompts repository, the spelling `builtin` (not `built-in`) is deliberately used in `tool-schemas/README.md` to match the spelling in the upstream main `README.md`. Do not suggest changing it to `built-in`.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

YiRaaaan added a commit to YiRaaaan/claude-code-system-prompts that referenced this pull request Jun 8, 2026
Per CodeRabbit suggestion on Piebald-AI#24: previous form labeled the link as a specific
file pattern (tool-description-<tool>.md) but pointed at the parent directory,
which could mislead readers expecting to land on one file. Make both the label
and the target the directory, and keep the glob as inline code.
@bl-ue

bl-ue commented Jun 8, 2026

Copy link
Copy Markdown
Member

@YiRaaaan Thank you, this looks great!

  1. Naming: I used tool-schemas/<kebab>.json to keep schemas in a self-contained directory. If you'd rather mirror system-prompts/ with tool-schema-<kebab>.json files inside that same directory, the rename is mechanical — happy to do it if you prefer.

tool-schemas/* is perfect.

  1. Main README integration: I haven't touched tools/updatePrompts.js or the main README.md listing — those are wired to your prompts-X.X.X.json extractor, which uses a different input path than these schemas. If you'd like the schemas to also appear in the main README's tool list (with versions / sizes / etc.), happy to follow up with a small updatePrompts.js patch that scans tool-schemas/ and adds a Tool Schemas section. Kept out of this PR to keep one change at a time.

Yes please, that would be great, thank you.

  1. Maintenance: I'm happy to refresh these on the same cadence as your existing extractor — capturing through the proxy is a claude -p away and the diff per release looks small (often empty). Let me know if you'd rather do it yourselves or have me send PRs.

We appreciate the offer! However, it would be inconvenient to have to rely on external contributions for something that's dependent on a product released as frequently as Claude Code, so we'd need to do that ourselves.

@YiRaaaan

YiRaaaan commented Jun 9, 2026

Copy link
Copy Markdown
Author

Thanks for the clear answers!

  1. Keeping tool-schemas/* flat as-is — no further changes in this PR.
  2. Follow-up PR for updatePrompts.js integration — preparing it now, will send shortly.
  3. Internal maintenance — totally understand given the release cadence.

Let me know if you'd like anything else changed here before merging.

@bl-ue

bl-ue commented Jun 10, 2026

Copy link
Copy Markdown
Member

Thank you for #25. I don't see any scripts or anything that would generate these JSON files—did you possibly forget to commit them?

YiRaaaan added a commit to YiRaaaan/claude-code-system-prompts that referenced this pull request Jun 11, 2026
…o per-tool schemas

Mirrors the existing prompt pipeline (`prompts-X.X.X.json` → `updatePrompts.js`
→ `system-prompts/*.md`): the script takes one or more captured
POST /v1/messages request bodies, merges by tool name (first-seen wins),
and writes each `tools[i].input_schema` to `tool-schemas/<kebab>.json`.

The capture step itself is delegated to whatever proxy the maintainer
prefers (mitmproxy, a small reverse proxy, etc.). The header doc on
the script explains the four `claude -p` runs that produce the current
35-tool set (default, --agent-teams, local-agent entrypoint, brief).

Why not bundle a Node proxy: Anthropic's OAuth bearer tokens appear
bound to the TLS/connection profile of the proxy that established
them — a freshly-started Node proxy gets `403 Request not allowed`
from upstream even with byte-identical headers to a working one. So
the script does the part that's stable (splitting JSON) and leaves
the capture to a proven proxy. mitmproxy in reverse mode (one line)
or any equivalent works.

Verified end-to-end: feeding the four captured request bodies through
the script produces 34/35 byte-identical files to what Piebald-AI#24 ships;
the one diff (`agent.json` gained a `mode` enum) reflects a real
upstream change in Claude Code since Piebald-AI#24 was captured.

Skipped tools:
- StructuredOutput — caller-supplied schema per workflow, no stable
  value (see tool-schemas/README.md).
YiRaaaan added a commit to YiRaaaan/claude-code-system-prompts that referenced this pull request Jun 11, 2026
Bundles a tiny HTTP intercept server with the four-run capture loop so
that, on any machine with `claude -p` installed, running

  node tools/captureToolSchemas.mjs

regenerates the full `tool-schemas/` directory in ~15s, with no external
proxy, no API key, no Anthropic account, no upstream call at all.

How it works:
  1. Server listens on 127.0.0.1:4099 (configurable via CAPTURE_PORT).
  2. Spawns `claude -p "ok"` four times, each with the env that surfaces
     a different tool set (default, --agent-teams, local-agent
     entrypoint, brief / KAIROS).
  3. On each spawn, claude POSTs to /v1/messages through ANTHROPIC_BASE_URL
     pointed at us. The server pulls `tools[]` out of the request body
     and replies with a stub 403 — claude exits immediately without
     retrying, and we move on to the next env.
  4. After all four runs, the unioned `tools[]` (first-seen wins per
     name) is sorted by tool name, each `input_schema` is recursively
     lexically key-sorted for byte-stable diffs, StructuredOutput is
     dropped (its schema is caller-supplied), and one file per tool is
     written under tool-schemas/.

Why a stub 403 instead of forwarding to api.anthropic.com:
  Anthropic's OAuth bearer tokens are bound to the TLS / connection
  profile of the proxy that established them. A fresh Node proxy
  forwarding identical headers gets `403 Request not allowed`
  consistently. So we don't forward — we capture the request body
  (which is what we actually want) and stub a fast-exit error
  response. Claude still emits the full tools[] before we reply.

Verified end-to-end on Claude Code v2.1.168: 33/35 output files are
byte-identical to PR Piebald-AI#24's committed schemas; the 2 deltas (agent.json,
…) reflect real-world wire changes since Piebald-AI#24 was captured. Two
back-to-back runs produce byte-identical output.
YiRaaaan added a commit to YiRaaaan/claude-code-system-prompts that referenced this pull request Jun 11, 2026
Complements Piebald-AI#24, which adds the `tool-schemas/` directory. Per the PR
discussion on Piebald-AI#24, the README listing should surface these alongside the
existing prompt categories.

Behavior:
- `getToolSchemas()` scans `tool-schemas/*.json` alphabetically; returns
  empty when the directory is absent, so the patch is a no-op on repos
  that haven't merged the schemas yet (safe to land in either order).
- `schemaFileToDisplayName()` does kebab→PascalCase with one explicit
  override (`lsp` → `LSP`). Add more overrides as needed.
- A new `### Tool Schemas` section is appended after the existing
  Builtin Tool Descriptions section, with a one-line intro and one
  bullet per file linking to `./tool-schemas/<file>.json`.

No changes to existing categories, prompt extraction, token counting,
or any other behavior. Only one new code path, guarded by directory
existence.
YiRaaaan added a commit to YiRaaaan/claude-code-system-prompts that referenced this pull request Jun 11, 2026
Bundles a tiny HTTP intercept server with the four-run capture loop so
that, on any machine with `claude -p` installed, running

  node tools/captureToolSchemas.mjs

regenerates the full `tool-schemas/` directory in ~15s, with no external
proxy, no API key, no Anthropic account, no upstream call at all.

How it works:
  1. Server listens on 127.0.0.1:4099 (configurable via CAPTURE_PORT).
  2. Spawns `claude -p "ok"` four times, each with the env that surfaces
     a different tool set (default, --agent-teams, local-agent
     entrypoint, brief / KAIROS).
  3. On each spawn, claude POSTs to /v1/messages through ANTHROPIC_BASE_URL
     pointed at us. The server pulls `tools[]` out of the request body
     and replies with a stub 403 — claude exits immediately without
     retrying, and we move on to the next env.
  4. After all four runs, the unioned `tools[]` (first-seen wins per
     name) is sorted by tool name, each `input_schema` is recursively
     lexically key-sorted for byte-stable diffs, StructuredOutput is
     dropped (its schema is caller-supplied), and one file per tool is
     written under tool-schemas/.

Why a stub 403 instead of forwarding to api.anthropic.com:
  Anthropic's OAuth bearer tokens are bound to the TLS / connection
  profile of the proxy that established them. A fresh Node proxy
  forwarding identical headers gets `403 Request not allowed`
  consistently. So we don't forward — we capture the request body
  (which is what we actually want) and stub a fast-exit error
  response. Claude still emits the full tools[] before we reply.

Verified end-to-end on Claude Code v2.1.168: 33/35 output files are
byte-identical to PR Piebald-AI#24's committed schemas; the 2 deltas (agent.json,
…) reflect real-world wire changes since Piebald-AI#24 was captured. Two
back-to-back runs produce byte-identical output.
YiRaaaan added 9 commits June 11, 2026 11:33
Seeded from issue Piebald-AI#22. Each file is a standalone JSON Schema document
captured verbatim from a real POST /v1/messages request, via a local
reverse proxy (flare).

Notes for reviewers:
- Schemas come from the API payload, not from parsing cli.js, so they
  are independent of bundler/minifier changes and require no addition
  to tools/updatePrompts.js.
- 28 of 29 schemas are byte-identical across v2.1.161 -> v2.1.168
  (seven patch releases); only LSP changed (new "query" property for
  the workspaceSymbol operation). README documents the data point.
- Files contain only input_schema; tool-level prose descriptions stay
  in system-prompts/tool-description-<tool>.md as the single source
  of truth.
Two follow-up findings from comparing 188+ captures across the main loop
and sub-agents (Explore, Workflow):

1. Schema is agent-invariant. Every shared tool name produces the same
   byte-for-byte input_schema across all callers. Sub-agents differ from
   the main loop only by subsetting the tool list (e.g. Explore drops
   write tools for its read-only mode), not by altering schemas. One
   tool-schemas/<tool>.json per tool is sufficient.

2. StructuredOutput is deliberately omitted. Its input_schema is
   supplied at call time by the workflow orchestration script that
   spawned the subagent, not defined by Claude Code. Two unrelated
   schemas appeared across captures. Including a fixed file would
   misrepresent the tool.
Move PR-rationale content (LSP diff, 28/29 stability, 188-capture forensics,
prose-description churn) out of the directory README — those belong in the
PR body, not in long-lived in-tree docs that will go stale.

Fix broken issue link (was Piebald-AI/system-prompts, should be
Piebald-AI/claude-code-system-prompts). Drop the hardcoded
cc_version=2.1.168.fc4 pin to avoid a per-release update treadmill.
Compress the StructuredOutput exclusion and the relationship-to-extractor
section to one sentence each. Add an offer to rename files to
tool-schema-<tool>.json if a closer mirror of system-prompts/ is preferred.
These appear in the API tools[] payload only when Agent Teams is
enabled via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 or --agent-teams
(see utils/agentSwarmsEnabled.ts). Captured from a v2.1.168 session
with the gate on.

README updated to split coverage into 29 default tools + 3 gated ones,
and to clearly call out which other gated tools are out of scope (e.g.
KAIROS/HISTORY_SNIP features that aren't shipped in the public npm
bundle, PowerShell which is Windows-only).
- glob.json, grep.json: surfaced under CLAUDE_CODE_ENTRYPOINT=local-agent.
  In sub-agent context Claude Code exposes the dedicated search tools
  instead of having the model shell out via Bash. grep.json fills the
  gap left by the existing tool-description-grep.md.

- send-user-message.json: surfaced under CLAUDE_CODE_BRIEF=1 (the
  KAIROS-style brief assistant entrypoint).

README rewritten as a 4-row 'how to surface' table covering all 35
schemas now in the directory. Build-time-gated tools that DO live in
the public native binary (SendUserFile, WebBrowser, Snip) require
a server-side GrowthBook entitlement (tengu_kairos) that cannot be
flipped from local env vars — left for a follow-up PR.
The 'Source' section linked to https://github.com/YiRaaaan/flare which is
private; reviewer click would 404. Just describe the proxy approach
without naming or linking the specific implementation.
Per CodeRabbit suggestion on Piebald-AI#24: previous form labeled the link as a specific
file pattern (tool-description-<tool>.md) but pointed at the parent directory,
which could mislead readers expecting to land on one file. Make both the label
and the target the directory, and keep the glob as inline code.
Two schemas changed since the initial capture against v2.1.168:

- agent.json: model enum gained "fable" (Fable 5 family).
- send-message.json: added length constraints — a 200-char maxLength
  on the top-level `summary` field and a matching ^[^\n\r]{1,200}$
  regex on the same field inside the nested shutdown_request /
  status_update message variants.

Regenerated with tools/captureToolSchemas.mjs (PR Piebald-AI#25). No other
schema bytes changed across the four runs.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
tool-schemas/README.md (1)

26-26: 💤 Low value

Consider mentioning the JSON Schema draft version.

If the .json files include a $schema field (e.g., "$schema": "https://json-schema.org/draft/2020-12/schema"), briefly noting the draft version in this line would help readers understand which JSON Schema spec applies—especially if they plan to validate or extend these schemas.

📝 Example phrasing
-Each `<tool>.json` is a standalone JSON Schema document — the exact value of
+Each `<tool>.json` is a standalone JSON Schema (draft 2020-12) document — the exact value of

(Adjust the draft version to match what's actually declared in the files, or skip this suggestion entirely if the files omit $schema.)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tool-schemas/README.md` at line 26, Update the README sentence to mention the
JSON Schema draft/version used by the tool JSON files: check the `.json` files
for a `$schema` field (e.g., `"$schema":
"https://json-schema.org/draft/2020-12/schema"`) and add a short clause stating
that each `<tool>.json` is a standalone JSON Schema document conforming to that
draft (or omit if no `$schema` is present); ensure the README line referencing
"Each `<tool>.json` is a standalone JSON Schema document" includes this
draft/version note so consumers know which JSON Schema spec applies.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tool-schemas/README.md`:
- Line 26: Update the README sentence to mention the JSON Schema draft/version
used by the tool JSON files: check the `.json` files for a `$schema` field
(e.g., `"$schema": "https://json-schema.org/draft/2020-12/schema"`) and add a
short clause stating that each `<tool>.json` is a standalone JSON Schema
document conforming to that draft (or omit if no `$schema` is present); ensure
the README line referencing "Each `<tool>.json` is a standalone JSON Schema
document" includes this draft/version note so consumers know which JSON Schema
spec applies.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 920933ea-440c-4fbd-bdc7-be65bb398f51

📥 Commits

Reviewing files that changed from the base of the PR and between 5f31a02 and 180bbfd.

📒 Files selected for processing (36)
  • tool-schemas/README.md
  • tool-schemas/agent.json
  • tool-schemas/ask-user-question.json
  • tool-schemas/bash.json
  • tool-schemas/cron-create.json
  • tool-schemas/cron-delete.json
  • tool-schemas/cron-list.json
  • tool-schemas/edit.json
  • tool-schemas/enter-plan-mode.json
  • tool-schemas/enter-worktree.json
  • tool-schemas/exit-plan-mode.json
  • tool-schemas/exit-worktree.json
  • tool-schemas/glob.json
  • tool-schemas/grep.json
  • tool-schemas/lsp.json
  • tool-schemas/monitor.json
  • tool-schemas/notebook-edit.json
  • tool-schemas/push-notification.json
  • tool-schemas/read.json
  • tool-schemas/remote-trigger.json
  • tool-schemas/schedule-wakeup.json
  • tool-schemas/send-message.json
  • tool-schemas/send-user-message.json
  • tool-schemas/skill.json
  • tool-schemas/task-create.json
  • tool-schemas/task-get.json
  • tool-schemas/task-list.json
  • tool-schemas/task-output.json
  • tool-schemas/task-stop.json
  • tool-schemas/task-update.json
  • tool-schemas/team-create.json
  • tool-schemas/team-delete.json
  • tool-schemas/web-fetch.json
  • tool-schemas/web-search.json
  • tool-schemas/workflow.json
  • tool-schemas/write.json
✅ Files skipped from review due to trivial changes (6)
  • tool-schemas/task-stop.json
  • tool-schemas/task-get.json
  • tool-schemas/edit.json
  • tool-schemas/lsp.json
  • tool-schemas/monitor.json
  • tool-schemas/enter-plan-mode.json
🚧 Files skipped from review as they are similar to previous changes (26)
  • tool-schemas/write.json
  • tool-schemas/glob.json
  • tool-schemas/schedule-wakeup.json
  • tool-schemas/exit-worktree.json
  • tool-schemas/cron-list.json
  • tool-schemas/task-output.json
  • tool-schemas/skill.json
  • tool-schemas/web-fetch.json
  • tool-schemas/team-create.json
  • tool-schemas/send-user-message.json
  • tool-schemas/notebook-edit.json
  • tool-schemas/cron-delete.json
  • tool-schemas/web-search.json
  • tool-schemas/task-create.json
  • tool-schemas/cron-create.json
  • tool-schemas/push-notification.json
  • tool-schemas/exit-plan-mode.json
  • tool-schemas/agent.json
  • tool-schemas/ask-user-question.json
  • tool-schemas/team-delete.json
  • tool-schemas/enter-worktree.json
  • tool-schemas/send-message.json
  • tool-schemas/task-list.json
  • tool-schemas/grep.json
  • tool-schemas/read.json
  • tool-schemas/task-update.json

@YiRaaaan

YiRaaaan commented Jun 11, 2026

Copy link
Copy Markdown
Author

Not forgotten — the generator lives in the follow-up #25, which I had split off before you asked since each PR does one thing (#24 commits the schemas; #25 adds the tooling).

It's tools/captureToolSchemas.mjs. Running it on any machine that has claude -p regenerates the full tool-schemas/ in ~8s — no Anthropic account, no API key, no upstream call needed: a tiny intercept server on 127.0.0.1 stubs a 403 immediately after pulling tools[] out of each request body. I just refreshed this PR's schemas with it (and rebased onto your latest main): the only delta from v2.1.168 to v2.1.172 was agent.json (the schema for the Agent tool, which spawns sub-agents) gaining "fable" in its model enum, and send-message.json gaining a 200-char maxLength + matching regex on summary. That's the kind of slow-moving change schema tracking is designed to surface.

Independent fresh-clone smoke-test of #25 just passed end to end (35/35 valid JSON, override path works, path-traversal guard works, ~8.3s wall clock) — should be safe to land #24 and #25 together (either order).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants