Clarify repo_run_commands capability discovery guidance

[kentcdodds]

Summary

• centralize the agent-facing repo_run_commands capability and commands-field guidance in shared constants
• update the deployed capability description, schema text, execute guidance, and matching docs to spell out parsed git-only command support and unsupported shell forms
• add focused tests covering the generated capability registry/detail surfaces that agents inspect during discovery

Testing

• npx vitest run --project node-unit --project workers-unit packages/worker/src/mcp/capabilities/build-capability-registry.workers.test.ts packages/worker/src/mcp/tools/search-format.node.test.ts
• npm run typecheck
• npx oxlint packages/worker/src/mcp/capabilities/build-capability-registry.workers.test.ts packages/worker/src/mcp/capabilities/repo/repo-run-commands-text.ts packages/worker/src/mcp/capabilities/repo/repo-run-commands.ts packages/worker/src/mcp/capabilities/repo/repo-shared.ts packages/worker/src/mcp/tools/execute.ts packages/worker/src/mcp/tools/search-format.node.test.ts

  

Summary by CodeRabbit

• Documentation

  • Updated comprehensive guidance clarifying that repo_run_commands accepts only parsed git commands and explicitly rejects shell syntax including pipes, command substitution, and non-git tools
  • Expanded details on supported git command forms and variants
  • Clarified that git clone remains unsupported

• Tests

  • Added test coverage verifying capability specifications enforce git-only command restrictions

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8ee08685-af08-46d1-866f-09f67102cc68

📥 Commits

Reviewing files that changed from the base of the PR and between 3263c87 and 0b0819a.

📒 Files selected for processing (11)

• docs/contributing/architecture/data-storage.md
• docs/contributing/packages-and-manifests.md
• docs/use/execute.md
• docs/use/packages.md
• docs/use/repo-sessions.md
• packages/worker/src/mcp/capabilities/build-capability-registry.workers.test.ts
• packages/worker/src/mcp/capabilities/repo/repo-run-commands-text.ts
• packages/worker/src/mcp/capabilities/repo/repo-run-commands.ts
• packages/worker/src/mcp/capabilities/repo/repo-shared.ts
• packages/worker/src/mcp/tools/execute.ts
• packages/worker/src/mcp/tools/search-format.node.test.ts

---

📝 Walkthrough

Walkthrough

Documentation and capability metadata for repo_run_commands are updated to explicitly specify that only parsed git commands are accepted, rejecting arbitrary shell syntax. A new constants module centralizes descriptions used across the capability spec, tools, and documentation.

Changes

Repo Run Commands Git-Only Constraint Documentation & Metadata

Layer / File(s)	Summary
Capability Text Constants packages/worker/src/mcp/capabilities/repo/repo-run-commands-text.ts	New file exports typed list of supported git forms and descriptions: repoRunCommandsSupportedForms, repoRunCommandsCapabilityDescription, repoRunCommandsUnsupportedSyntaxDescription, repoRunCommandsSupportedFormsDescription, repoRunCommandsCommandsFieldDescription, and repoRunCommandsExecuteSummary.
Capability & Schema Integration packages/worker/src/mcp/capabilities/repo/repo-run-commands.ts, packages/worker/src/mcp/capabilities/repo/repo-shared.ts	Capability spec and input schema commands field now reference imported text constants instead of inline strings.
Tool Description Wiring packages/worker/src/mcp/tools/execute.ts	The execute tool's description injects repoRunCommandsExecuteSummary to clarify repo-backed repo_run_commands behavior.
User-Facing Documentation docs/contributing/architecture/data-storage.md, docs/contributing/packages-and-manifests.md, docs/use/execute.md, docs/use/packages.md, docs/use/repo-sessions.md	All references to repo_run_commands updated to clarify newline-separated parsed git-command input, enumerate unsupported syntax (pipes, &&, non-git tools), and list supported git forms; git clone remains explicitly unsupported.
Capability Schema & Tool Description Tests packages/worker/src/mcp/capabilities/build-capability-registry.workers.test.ts, packages/worker/src/mcp/tools/search-format.node.test.ts	New test verifies repo_run_commands capability spec and tool descriptor expose git-only parsing guidance; existing test updated to assert formatted entity details surface parsed command semantics and supported/unsupported patterns.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• PR #129: Modifies packages/worker/src/mcp/tools/execute.ts description field alongside this PR's injection of repoRunCommandsExecuteSummary.
• PR #340: Extends the same repo_run_commands capability and test infrastructure with additional metadata and schema field updates.
• PR #303: Adjusts capability/type output formatting and schema description tests that overlap with this PR's new test assertions for formatted capability markdown.

Poem

🐰 A rabbit parsed the git forms with care,
No pipes or shells could slip through there!
Commands newline-split, git-only true,
Constants speak the spec—the docs ring new! ✨

🚥 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 title accurately summarizes the main objective of the pull request, which is to clarify and centralize the capability discovery guidance for repo_run_commands.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/-bc-0f4ba4cb-9a6d-4cec-9298-946fd028487e-eeed

---

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

[github-actions]

🔎 Preview deployed: https://kody-pr-343.kentcdodds.workers.dev

Worker: kody-pr-343
D1: kody-pr-343-db
KV: kody-pr-343-oauth-kv

Mocks:

• ai: https://kody-pr-343-mock-ai.kentcdodds.workers.dev/__mocks (kody-pr-343-mock-ai)
• cloudflare: https://kody-pr-343-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-343-mock-cloudflare)