fix(cursor): preserve per-tool freeform input guidance

[lidge-jun]

Summary

Follow up #3707: freeform schema canonicalization discarded parser-owned input descriptions, including apply_patch envelope guidance. Both Cursor schema consumers now retain string input guidance while keeping the closed object, required string input and reserved shell-name guards. Existing #3628 authorship remains in the commit history.

Verification

• Exact head efe4616: remote Bun1.4.0 / Node22.22.0 typecheck, full suite19,570 pass /15skip /0fail, and425-page docs build passed. No local application tests/typecheck ran.
• Real Responses parser-to-protobuf regressions cover guidance, namespace/reserved names, per-tool isolation, malformed metadata and unchanged closed shapes. Independent review passed.
• Current hosted jobs are tracked separately and any queued job is not claimed passed. The maintainer authorized admin integration; actual integrated dev CI remains required before batch closeout.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. The correction changes metadata, not execution authority or credential handling.

Co-authored-by: SB Yoon 44089734+yansigit@users.noreply.github.com

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 69 / 80

이 PR은 #3707 랜딩 뒤 남은 freeform input description 유실을 고칩니다. 지금 dev HEAD 6dd23d631 의 src/adapters/cursor/tool-schemas.ts 115·130행은 freeform이면 무조건 CURSOR_FREEFORM_INPUT_SCHEMA 를 돌려줍니다. 그 상수에는 input.description 이 없습니다. 그런데 Responses 파서 buildTools (src/responses/parser-tools.ts)는 apply_patch에 Begin Patch 봉투 안내를, 다른 custom에는 일반 freeform 안내를 parameters.properties.input.description 에 넣습니다. Cursor 광고/정규화가 그 문자열을 버리면, 모델은 닫힌 input 문자열 스키마만 보고 패치 문법을 놓치기 쉽습니다. 실행·승인 정책은 안 바꿉니다.

고치는 방법은 작은 헬퍼 cursorFreeformInputSchema(tool) 입니다. string 타입 description만 복사해 닫힌 객체 위에 얹고, 없거나 타입이 아니면 기존 상수를 그대로 씁니다. cursorToolInputSchema 와 cursorToolArgNormalizeSchema 두 곳 모두 같은 헬퍼를 쓰므로 live-transport 정규화 맵과 protobuf 광고가 어긋나지 않습니다. 테스트는 진짜 buildTools 에서 스키마 선택기, buildCursorToolDefinitions protobuf 디코드까지 잠그고, 빈 문자열 보존·공유 상수 미변이·이상한 parameters fallback·추가 키 무시까지 넣었습니다. docs/structure 문장도 구조는 닫히되 도구별 안내 문자열은 남긴다고 맞춰졌습니다.

스택만 주의하세요. 베이스가 dev/#3707이 아니라 #3712 브랜치 codex/d-3625-logs-filters-01a07265 입니다. 본문이 #3712의 자식으로 히스토리를 보존한다고 했고, 코드 충돌 축은 Logs가 아니라 Cursor 스키마입니다. #3712가 먼저 안 들어가면 이 PR만 dev에 단독 머지하면 안 됩니다. #3712 이후 dev retarget이 정석입니다. 원본 #3628은 이미 closed이고 #3707로 들어갔으니, 이번 건은 새 follow-up으로 남기면 됩니다.

경로/심볼 - src/adapters/cursor/tool-schemas.ts cursorFreeformInputSchema - string description만 복사.
라인 - cursorToolInputSchema / cursorToolArgNormalizeSchema freeform return - 상수 직반환을 헬퍼로 교체.
경로 - tests/providers/cursor/cursor-tool-definitions.test.ts freeform input guidance - buildTools에서 protobuf까지 회귀.
경로 - CURSOR_FREEFORM_INPUT_SCHEMA 변이 금지 테스트 - 공유 객체 오염 방지.
경로 - docs adapters.md / structure/04 - ownership 문장 보강.
경로 - 실행/approval/transport - 변경 없음(범위 올바름).

메인테이너의 판단이 필요한 지점

• #3712 머지 전 draft로 둘지, #3712와 한 트레인으로 묶을지
• #3712와 무관하니 #3707 직후 dev로 베이스만 바꿔 단독 랜딩할지(충돌이 없다면 더 빠름)
• 리뷰 스레드 #3707 discussion_r3941721795 를 이 PR 머지 후 resolve할지

너의 추천
가능하면 베이스를 dev(또는 #3707 ancestry)로 바꿔 Logs 스택과 분리해 단독 머지하세요. 충돌이 커서 어렵다면 #3712 랜딩 직후 retarget·exact-head CI 후 머지. types/config 분할 무효화 대상 아님. 미리보기 배포 없음.

이 댓글은 grok-bot이 작성했습니다

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-05T21:14:01.777583Z	efe4616	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.