doc(agent-workflows): remove stale built-in tool guidance

[tomatotomata]

Closes #5659

Summary

The agent-workflows design docs still told readers that AgentaHarness forces a tool set, and several runner references still pointed at the removed services/agent package. The built-in schema description also left the legacy builtin compatibility behavior implicit, while the built-in execution page used web_search, which is not one of Pi's native tools.

This updates the wording to match the current always-active seven-built-in behavior, points documentation at the current runner package, and records both the legacy compatibility behavior and the SDK/runner collision defenses.

Testing

Verified locally

• git diff --check
• The five issue checks for obsolete wording and paths return no matches.
• Every replacement source and test path was confirmed to exist in the current tree.

Added or updated tests

N/A. These changes only update design documentation, and the affected docs/design/ pages are not part of the Docusaurus build.

QA follow-up

N/A. No runtime or UI behavior changed.

Demo

N/A. This is documentation-only.

Checklist

• I have included a video or screen recording for UI changes, or marked Demo as N/A
• Relevant tests pass locally
• Relevant linting and formatting pass locally
• I have signed the CLA, or I will sign it when the bot prompts me

AI assistance disclosure

This change was prepared with OpenAI Codex (GPT-5-based, high reasoning effort). The session inspected the maintainer's checklist, verified the current repository paths, made the scoped documentation edits, and ran the checks listed above. I reviewed and take responsibility for every changed line; no AI tool is listed as a co-author.

[vercel]

@tomatotomata is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

✅ Thanks @tomatotomata! This PR now meets the contribution requirements and has been reopened. A maintainer will review it soon.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 400079ef-f53c-4ccf-a9fc-29ffdaf06873

📥 Commits

Reviewing files that changed from the base of the PR and between a308941 and 7f1eb31.

📒 Files selected for processing (1)

• docs/design/agent-workflows/documentation/adapters/agenta.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/design/agent-workflows/documentation/adapters/agenta.md

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Clarified that built-in tools—including reading, writing, searching, and shell access—are always available.
  • Updated runner and harness documentation to reflect current tool locations, ownership, skill loading, and interface paths.
  • Documented compatibility handling for legacy built-in tool settings, including warnings and non-rendering behavior.
  • Clarified permission behavior: read-only actions run automatically, while shell and file-modification actions require approval.
  • Documented that custom tools can retain explicit permission overrides.

Walkthrough

The documentation now describes always-active Pi built-ins, runner-owned implementation paths, legacy builtin handling, and permission behavior for built-in and custom tools.

Changes

Agent workflow documentation

Layer / File(s)	Summary
Built-in tools and permission semantics docs/design/agent-workflows/documentation/adapters/agenta.md, docs/design/agent-workflows/documentation/tools.md, docs/design/agent-workflows/interfaces/in-service/harness-adapters.md, docs/design/agent-workflows/interfaces/public-edge/agent-config-schema.md, docs/design/agent-workflows/projects/default-agent-builtins/addendum-always-active.md	The docs remove the forced-tool model, define always-active Pi built-ins, document legacy builtin entries, and clarify permission and collision handling.
Runner ownership and implementation paths docs/design/agent-workflows/documentation/tools.md, docs/design/agent-workflows/interfaces/README.md	References now use services/runner for protocols, execution, callbacks, Docker, implementation components, tests, and package ownership.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• Agenta-AI/agenta#5651: Introduced the always-active Pi built-in tool behavior documented here.
• Agenta-AI/agenta#5041: Added related runner permission-plan and built-in tool behavior.
• Agenta-AI/agenta#5066: Implemented related Pi built-in tool identity and permission handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: removing stale built-in tool guidance from agent-workflows documentation.
Description check	✅ Passed	The description directly explains the documentation corrections, linked issue, validation, and documentation-only scope.
Linked Issues check	✅ Passed	The changes address issue #5659 by correcting built-in behavior, paths, compatibility notes, permissions, examples, and collision defenses.
Out of Scope Changes check	✅ Passed	All modified files contain documentation updates directly related to the objectives in issue #5659.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2dc4d2a2-c36b-46fa-91a6-5ba7f43c2315

📥 Commits

Reviewing files that changed from the base of the PR and between ac6b154 and a308941.

📒 Files selected for processing (6)

• docs/design/agent-workflows/documentation/adapters/agenta.md
• docs/design/agent-workflows/documentation/tools.md
• docs/design/agent-workflows/interfaces/README.md
• docs/design/agent-workflows/interfaces/in-service/harness-adapters.md
• docs/design/agent-workflows/interfaces/public-edge/agent-config-schema.md
• docs/design/agent-workflows/projects/default-agent-builtins/addendum-always-active.md