fix: prefer native worktree tool in description

[Astro-Han]

Summary

Clarify the enter-worktree tool description so PawWork's native worktree tool is the preferred path when users ask to create, enter, switch to, or move work into a worktree.

Why

After #360 added native worktree session binding, models can still be pulled toward generic worktree skills or shell-based git worktree workflows. The native tool is the only path that updates PawWork session execution context, so its tool description should make that routing explicit.

Related Issue

Follow-up to #360. No separate issue filed.

Human Review Status

Pending. A human should make the final merge decision after reviewing the final diff and verification evidence.

Review Focus

Please review whether the wording is strong enough to steer tool selection without over-scoping beyond session worktree transitions.

Risk Notes

Low risk. This changes only the enter-worktree tool description shown to models; it does not change execution behavior, permissions, Bash behavior, or skill routing.

How To Verify

Diff check: git diff --check passed for packages/opencode/src/tool/enter-worktree.txt
Final diff review: single tool-description text file changed, no generated files or dependency changes

Screenshots or Recordings

Not applicable; no visible UI change.

Checklist

• Human review status is stated above as pending, approved, or not required
• I linked the related issue, or stated why there is no issue
• This PR has type, scope, and priority labels, or I requested maintainer labeling
• I described the review focus and any meaningful risks
• I listed the relevant verification steps and the key result for each
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope
• I manually checked visible UI or copy changes when needed, with screenshots or recordings
• I considered macOS and Windows impact for desktop, packaging, updater, signing, paths, shell, or permissions changes
• I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant
• I reviewed the final diff for unrelated changes and suspicious dependency changes
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English

Summary by CodeRabbit

• Documentation
  • Clarified usage guidance for the worktree tool: when to invoke it, that it is the authoritative mechanism for session worktrees, and that it should be preferred over other workflows or shell commands. Also added an instruction not to invoke alternate worktree skills before using this tool.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7c3dde59-1a99-48fb-9bc3-b1739efda2b9

📥 Commits

Reviewing files that changed from the base of the PR and between a8f2101 and 67b990b.

📒 Files selected for processing (1)

• packages/opencode/src/tool/enter-worktree.txt

✅ Files skipped from review due to trivial changes (1)

• packages/opencode/src/tool/enter-worktree.txt

---

📝 Walkthrough

Walkthrough

Documentation added to the worktree tool guidance specifying when to use the tool to create/start/enter/open/switch into a worktree and instructing not to call a worktree skill first when this tool directly satisfies the request.

Changes

Worktree Tool Guidance

Layer / File(s)	Summary
Documentation packages/opencode/src/tool/enter-worktree.txt	Inserted usage guidance: invoke the worktree tool for create/start/enter/open/switch worktree requests; declared it the authoritative PawWork session-worktree mechanism; prefer it over skill-based or shell git worktree approaches because it binds session execution context for subsequent tool path resolution; added rule not to invoke a worktree skill first when this tool suffices.

Estimated Code Review Effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested labels

enhancement

Poem

🐰 I hop to docs with tiny feet,
A guide to make the pathways neat,
Enter the worktree, bold and true,
Session-bound — now workflows flew!
nibbles a carrot 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: updating the tool description to prefer the native worktree tool over alternatives.
Description check	✅ Passed	The description follows the template structure with all major sections completed: Summary, Why, Related Issue, Human Review Status, Review Focus, Risk Notes, How To Verify, Screenshots, and Checklist.
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
• Commit unit tests in branch pawwork/worktree-tool-description-route-text-fix

---

_{Review rate limit: 8/10 reviews remaining, refill in 9 minutes and 29 seconds.}

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

[gemini-code-assist]

Code Review

This pull request updates the documentation for the enter-worktree tool to clarify its role as the authoritative mechanism for session worktrees and to discourage the use of alternative shell-based commands. A review comment suggests refining the tool's description to avoid misleading the model into thinking it handles the migration of uncommitted changes.