fix(agents): Always activate Pi built-ins, control them with rules

[mmabrouk]

Context

Every new Pi agent showed four rows in its Tools list: Read, Bash, Edit and Write. They looked like
tools you could add, remove or configure, but they were none of those things. Next to them the
Permissions area showed a read-only "Auto-approve" panel that listed rules you could not edit, and a
separate built-in multi-select that wrote back into the same tools array. Three surfaces, one
underlying setting, no clear owner.

Those four rows exist because of issue #5590. A Pi agent started from a trigger arrived at the
runner with tools: []. The runner read that field as the built-in grant list, granted nothing, and
the agent ran with no tools at all, so it could not read the mount it was created for. The
playground never showed the bug because the build kit injects tools at run time. The v0.107 fix put
four explicit {"type": "builtin", "name": ...} entries in the default template, which fixed the
trigger case but placed Pi-specific machinery in the top-level tools[] array and produced the
confusing UI above.

This PR removes built-ins from the config entirely. That makes the #5590 class impossible (there is
no grant list to be empty) and fixes the presentation at the same time.

What this changes

All seven Pi built-ins (read, bash, edit, write, grep, find, ls) are now active on every Pi run.
Our runner activates all seven each time it starts Pi; Pi on its own activates only four. Activation
is unconditional platform behavior, so the built-ins appear nowhere in the agent config and nowhere
in the Tools list.

Permission control for Pi now happens in exactly two places: the main policy
(runner.permissions.default: allow | allow_reads | ask | deny) and the three editable rule
lists harness.permissions.{allow, ask, deny}. Defaults are unchanged: all three lists empty, policy
allow_reads, so read/grep/find/ls run unattended while bash/edit/write show the approval card.

The Permissions area for a Pi agent now shows those three lists as tag selects, seeded with the seven
canonical names (Read, Bash, Edit, Write, Grep, Find, Ls) and accepting free-typed pattern rules such
as Bash(npm run:*). The view-only Auto-approve panel and the built-in multi-select are gone. A rule
created by the "Always allow" switch on an approval card lands in that same Allow list and can be
removed there.

Rule matching for the seven built-ins is now case-insensitive, so bash, Bash and BASH all name
the same tool. Custom tool names stay case-significant, and the body of a prefix pattern stays
case-sensitive because a shell command's case matters. Unknown tool names at the gate still fail
closed.

Old configs keep working. A {"type": "builtin", "name": ...} entry in tools[] is accepted,
ignored, and logged once per entry. It no longer occupies the custom-tool name namespace and renders
nowhere in the UI. Nothing writes new ones: the SDK template builder, the service's agent.json and
DEFAULT_TOOLS, the static catalog entry that seeds new accounts, and the build-kit authoring
instructions all stop emitting them.

The AGENTA_FORCED_TOOLS machinery in the Agenta harness (a forced read+bash union) is obsolete now
that all seven are always on, and is deleted along with force_tools and the API build-kit spread
that carried it.

Before / after

The default template's tools array:

// before (v0.107)
"tools": [
  {"type": "builtin", "name": "read"},
  {"type": "builtin", "name": "bash"},
  {"type": "builtin", "name": "edit"},
  {"type": "builtin", "name": "write"}
]

// after
"tools": []

How you allow bash without an approval card:

// before: a built-in multi-select wrote an entry into tools[], and the
// resulting auto-approve rule was visible but not editable.
// after:
"harness": {"permissions": {"allow": ["Bash"], "ask": [], "deny": []}}

The runner's plan no longer depends on the request's tools field:

// before
computeBuiltinGatingActive(isPi, permissionPlan, normalizePiBuiltinGrants(request.tools))
// after
computeBuiltinGatingActive(isPi, permissionPlan)   // policy alone decides

Decisions worth reviewing, and what they cost

A denied tool is refused at call time, not hidden from the model. The seven built-ins are always
advertised, so a deny: ["Bash"] rule does not remove bash from the model's tool list. The model can
still call it; the call is attempted and terminates as tool-output-denied with
"Denied by the permission policy.". The cost is one wasted model turn and prose that may mention
the attempt. The gain is a stable prompt (the same tool list regardless of rules, which keeps the
prompt cache warm) and a visible audit trail of what the agent tried. Live QA confirmed the wire
outcome (QA-4, QA-9).

Policy allow widens for agents that have custom tools. Under the old grant-list model, an agent
with custom tools and policy allow ended up with no built-ins at all, which was the #5590 bug. Such
an agent now runs all seven, and under allow that means bash, edit and write run unattended with no
card. This is the intended fix, but it is a real behavior change for any existing agent in that
state, so it belongs in the release notes.

grep, find and ls become visible to every Pi agent. They are classified read-only, so under the
default allow_reads policy they auto-run without a card, exactly like read. Agents that previously
had only four built-ins gain three read tools they did not have. The read-only classification is
pinned in the shared golden fixture so it cannot be flipped by accident.

The deprecated tools wire field keeps being sent, filled with all seven names. The new runner
ignores the field. An old runner (a self-hosted deployment whose API updates before the runner image)
still reads it as the grant list, and sending seven names gives it the same tool set the new runner
activates. Sending [] there would recreate #5590 during a version skew; omitting the key would give
Pi's own four. Claude still sends [], unchanged.

Built-in names are now reserved for custom tools. A custom tool named read used to shadow the
built-in silently. The resolver now raises ReservedToolNameError, and the runner skips a colliding
spec as a second line of defense. The reservation is harness-agnostic (the resolver has no harness
context), so a Claude config that names a custom tool write is refused too. That is stricter than
strictly necessary for Claude and is the one place this change can break a config that used to load.

No data migration. Revisions saved since 107 keep their four legacy entries in the database. A
silent rewrite on read raises a false "unsaved changes" marker the moment a drawer opens, and a
rewrite on commit mutates author data for no runtime benefit. The entries are inert. The builtin
arm of the config union should be removed one release from now, together with a permissive fallback
for unknown type values so older revisions still load.

New and changed user-visible strings

Everything below is either new or reworded. Nothing else user-facing changed.

In the Permissions editor (PiPermissionsControl):

• Row labels: Allow, Ask, Deny.
• Row help tooltips: "Tools that run without asking." / "Tools that ask before running." / "Tools
  that are never allowed to run."
• Tag select placeholder: Bash(npm run:*).

In the config schema tooltips (_HarnessPermissionsSchema and _HarnessSchema in
sdks/python/agenta/sdk/utils/types.py):

• The same three sentences as above, on the allow, ask and deny fields.
• permissions: "The allow / ask / deny rules that decide which tools may run." (was Claude-only
  wording).
• mode: "Claude's default permission mode (default / acceptEdits / plan / bypassPermissions). Not
  used by Pi."

In run errors:

• "Tool name '' is reserved: built-in tools are always available under these names. Rename the
  tool."

Log lines only (not shown in the product):

• SDK resolver, once per ignored legacy entry: "tool 'read': built-in tools are always available and
  are no longer configured here; this entry was ignored (use harness.permissions to allow, ask or
  deny it)".
• Runner: "skipped custom tool '': the name is a built-in tool".

One behavior detail with no new string: a rule created by the card's "Always allow" switch now reads
Bash instead of bash, matching the spelling the dropdown offers.

Tests

86 files changed. Every suite below was re-run after the final change.

Suite	Command	Result
Runner	pnpm run typecheck then pnpm test	clean; 91 files, 1409 tests
SDK	pytest oss/tests/pytest/unit -q	1871 passed, 10 xfailed
Services	pytest oss/tests/pytest/unit -q	100 passed
API	pytest oss/tests/pytest/unit -q	1597 passed, 28 skipped
Web types	pnpm --filter @agenta/oss exec tsgo --noEmit	clean
Web	@agenta/entity-ui / @agenta/playground / @agenta/oss unit	301 / 215 / 142 tests
Lint	pnpm lint-fix in web; ruff format + ruff check	clean

What the new tests pin, beyond the rewrites that follow the deleted code:

• One golden fixture (golden/pi_builtin_tools.json) now holds the canonical table of seven names,
  their rule-name capitalization and their read-only flag. Python asserts the names, the runner
  asserts the whole table, and the runner extension's own copy of the list is asserted against it
  too, so all three copies drift-check against one file.
• The runner's plan is invariant to the request's tools field in any form, and gating follows the
  policy alone.
• Case folding: mixed-case bare rules, mixed-case prefix rules, a case-significant prefix body, a
  case-significant custom tool name, and deny outranking ask outranking allow across mixed case.
• The permission editor's read/write helpers (11 cases), the card-to-allow-list path (a grant clears
  the same pattern from ask and deny first), and the tool-count filters that keep the Tools header,
  the list body and the conversation card in agreement on a legacy config.

The agent release gate resources are updated in the same change: the probe and product templates no
longer seed Pi tool lists, and four new journeys cover the permission model end to end (rule_deny,
rule_allow, rule_case, builtin_grep), all skipped on a non-Pi cell and documented in the gate's
coverage.md.

Live QA

Run twice against the EE dev stack serving this tree, with the runner container restarted first
(runner TypeScript does not hot-reload). Round 1 found one blocker and one cosmetic issue; both were
fixed and round 2 re-ran all nine items end to end. Round 2: nine of nine pass, no failures.

• Fresh agent shows no built-in rows and commits "tools": []; the static catalog seed carries no
  entries either.
• The Permissions area shows exactly three empty editable lists, a dropdown with exactly the seven
  names, and keeps Bash(npm run:*) as one tag.
• With empty rules, ls, grep and find all executed with real output and no approval card.
• deny: ["Bash"] produced an attempted call that terminated as tool-output-denied, no card, no
  execution, run ended normally. Uppercase BASH in deny behaved identically.
• allow: ["Bash"] and lowercase allow: ["bash"] both ran bash unattended.
• The card's "Always allow" switch wrote Bash into the editor's own Allow list, the re-run needed no
  card, and removing the tag brought the card back.
• A legacy agent whose committed config still holds the four builtin entries renders no tool rows
  anywhere, shows the same three empty rule lists, runs grep normally, and logs one ignored-entry
  warning per dropped entry.
• The (bug) Pi agents run with no read, bash, edit or write tools outside the playground #5590 scenario itself: an agent with one custom tool, invoked over the API rather than the
  playground (no build-kit injection), executed both ls and grep and still listed its custom tool.
  Round 1's blocker was a "4 tools" chip on the playground conversation card, which counted the
  ignored legacy entries; it now uses the same filter as the other three surfaces.

The stack has no reachable trigger target, so the non-playground path was exercised by calling
POST /services/agent/v0/invoke directly with the committed revision's parameters. That is the same
path a trigger takes minus the scheduler.

What reviewers should double-check

1. The reserved-name rule applied to Claude. ReservedToolNameError fires for any harness, so a
   Claude agent with a custom tool named read, bash, edit, write, grep, find or ls now
   fails to resolve where it used to work. If we have such configs in the wild, this needs to be
   scoped to Pi.
2. Policy allow plus custom tools. Confirm we are comfortable that agents in this state go from
   no built-ins to seven unattended built-ins, including bash, edit and write.
3. The tools wire field carrying seven names. An old runner receiving them computes
   builtinGatingActive = true even under policy allow, so built-in calls route through the
   extension dialog, which resolves to allow. Behavior is the same; only the code path differs.
4. The dual-read window actually closes. The build-kit authoring instructions were updated so a
   config-writing agent stops producing legacy entries. If any other generator writes tools, it
   needs the same treatment before the builtin arm is removed.
5. j_rule_deny is still assertion-loose. The journey asserts the bash outcome is present and not
   "available", and reports the observed value. Live QA pinned that value at denied in both
   rounds, so the assertion can now be tightened to == "denied". It has not been tightened in this
   PR; say the word and it is a one-line change.

What to QA

• Create a new agent from the default template. The Tools section shows the empty state, not four
  built-in rows, and the committed config has "tools": [].
• Open Permissions on that agent. Three editable rows (Allow, Ask, Deny), all empty, dropdown offers
  the seven names, and Bash(npm run:*) typed into Allow stays a single tag.
• Ask it to grep something and to ls its working directory. Both run with no approval card.
• Put Bash in Deny, ask it to run a shell command. The call is attempted and refused, and no output
  comes back. Swap Deny for Allow and the same command runs with no card.
• Ask for a shell command with all three lists empty, then use "Always allow" on the card. The rule
  shows up as Bash in the Allow list, the next run needs no card, and deleting the tag brings the
  card back.
• Regression: open an agent created before this change that still carries the four legacy builtin
  entries. No tool rows, no tool count on the conversation card, and it still runs normally.

Follow-ups

• Remove the builtin arm from the tool-config union one release from now, with a permissive
  fallback for unknown type values so older revisions still load.
• Tighten j_rule_deny to assert bash_outcome == "denied" now that live QA has pinned the value.

https://claude.ai/code/session_01McMogkcDRV7UpSAjfd8VKG

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview	Aug 2, 2026 3:06pm

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Pi runs now activate all seven built-in tools automatically.
  • Added permission controls for Allow, Ask, and Deny rules.
  • Added case-insensitive matching for built-in tool permissions.
• Bug Fixes
  • Legacy built-in tool entries are ignored with warnings.
  • Custom tools can no longer use reserved built-in names.
  • Tool and capability counts now exclude hidden legacy built-ins.
• Documentation
  • Updated configuration guidance and compatibility behavior for always-active built-ins.

Walkthrough

The change removes Pi built-in tools from agent configuration. The runner always activates seven built-ins and uses harness.permissions for gating. SDK resolution, wire compatibility, UI controls, documentation, and QA coverage now follow this model.

Changes

Always-active Pi built-ins

Layer / File(s)	Summary
Configuration contract and release QA .agents/skills/agent-release-gate/*, docs/design/agent-workflows/*, api/oss/src/core/workflows/build_kit.py, services/oss/src/agent/config.py	Templates and overlays no longer grant built-in tools. Legacy builtin entries and the deprecated tools wire field remain compatibility inputs but do not control activation.
SDK tool resolution and wire compatibility sdks/python/agenta/sdk/agents/*, sdks/python/agenta/sdk/utils/types.py	The SDK defines seven canonical Pi built-ins, ignores legacy builtin entries, rejects reserved custom names, and emits canonical names only for compatibility wire payloads.
Runner activation and permission gating services/runner/src/engines/sandbox_agent/*, services/runner/src/extensions/agenta.ts, services/runner/src/permission-plan.ts, services/runner/src/protocol.ts	Pi activation is independent from permission gating. Built-in grants and grant environment variables are removed. Built-in matching is case-insensitive.
Permission editor and builtin visibility web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/*, web/oss/src/components/AgentChatSlice/*	Pi permissions are edited through Allow, Ask, and Deny lists. Legacy harness built-ins are excluded from visible tool counts and rendering summaries.
Validation and parity coverage */tests/*, sdks/python/oss/tests/*	Tests cover canonical identities, activation, gating, reserved names, deprecated fields, permission precedence, UI filtering, wire contracts, and shared fixture parity.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• Agenta-AI/agenta#5041: Modifies the same Pi permission-plan and runner wiring.
• Agenta-AI/agenta#5066: Directly overlaps Pi built-in activation and permission gating paths.
• Agenta-AI/agenta#5597: Provides the superseded configured-grant behavior replaced by this change.

Sequence Diagram(s)

sequenceDiagram
  participant AgentConfig
  participant SDK
  participant RunPlan
  participant PiExtension
  participant PermissionPlan
  AgentConfig->>SDK: provide tools and harness.permissions
  SDK->>SDK: ignore legacy builtin entries
  SDK-->>RunPlan: return custom tool specs and compatibility names
  RunPlan->>PermissionPlan: evaluate allow, ask, and deny rules
  PermissionPlan-->>RunPlan: return builtinGatingActive
  RunPlan->>PiExtension: enable all seven Pi built-ins
  PiExtension->>PermissionPlan: check builtin execution
  PermissionPlan-->>PiExtension: allow, ask, or deny outcome

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.14% which is insufficient. The required threshold is 60.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: always activating Pi built-ins and controlling them with permission rules.
Description check	✅ Passed	The description directly explains the built-in activation, permission, compatibility, UI, testing, and QA changes.
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.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/pi-builtins-always-active

---

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.}

[mmabrouk]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 11

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4e9b1f24-78ce-4db8-84e4-c30143de1b16

📥 Commits

Reviewing files that changed from the base of the PR and between abaf519 and 8bc748a.

📒 Files selected for processing (81)

• .agents/skills/agent-release-gate/resources/LESSONS.md
• .agents/skills/agent-release-gate/resources/coverage.md
• .agents/skills/agent-release-gate/resources/qa_longctx.py
• .agents/skills/agent-release-gate/resources/qa_probe.py
• .agents/skills/agent-release-gate/resources/qa_product.py
• api/oss/src/core/workflows/build_kit.py
• api/oss/tests/pytest/unit/applications/test_build_kit_overlay.py
• api/oss/tests/pytest/unit/resources/test_workflow_catalog.py
• 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
• docs/design/agent-workflows/projects/default-agent-builtins/design.md
• docs/design/agent-workflows/projects/default-agent-builtins/status.md
• docs/design/agent-workflows/projects/default-agent-builtins/testing.md
• docs/design/agent-workflows/projects/pi-builtin-gating/status.md
• sdks/python/agenta/sdk/agents/__init__.py
• sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py
• sdks/python/agenta/sdk/agents/adapters/harnesses.py
• sdks/python/agenta/sdk/agents/dtos.py
• sdks/python/agenta/sdk/agents/handler.py
• sdks/python/agenta/sdk/agents/pi_builtins.py
• sdks/python/agenta/sdk/agents/tools/__init__.py
• sdks/python/agenta/sdk/agents/tools/errors.py
• sdks/python/agenta/sdk/agents/tools/models.py
• sdks/python/agenta/sdk/agents/tools/resolver.py
• sdks/python/agenta/sdk/utils/types.py
• sdks/python/oss/tests/pytest/integration/agents/_qa_transcripts.py
• sdks/python/oss/tests/pytest/unit/agents/golden/pi_builtin_tools.json
• sdks/python/oss/tests/pytest/unit/agents/golden/run_request.attachment.json
• sdks/python/oss/tests/pytest/unit/agents/golden/run_request.pi_core.json
• sdks/python/oss/tests/pytest/unit/agents/platform/test_resolve.py
• sdks/python/oss/tests/pytest/unit/agents/test_agenta_builtins_reference_files.py
• sdks/python/oss/tests/pytest/unit/agents/test_dtos_harness_configs.py
• sdks/python/oss/tests/pytest/unit/agents/test_harness_adapters.py
• sdks/python/oss/tests/pytest/unit/agents/test_pi_builtins_parity.py
• sdks/python/oss/tests/pytest/unit/agents/test_wire_contract.py
• sdks/python/oss/tests/pytest/unit/agents/tools/test_models.py
• sdks/python/oss/tests/pytest/unit/agents/tools/test_resolver.py
• services/oss/src/agent/config.py
• services/oss/tests/pytest/integration/agent/tools/test_gateway_http.py
• services/oss/tests/pytest/unit/agent/test_config_template_fallback.py
• services/oss/tests/pytest/unit/agent/test_default_agent_template.py
• services/oss/tests/pytest/unit/agent/test_invoke_handler.py
• services/oss/tests/pytest/unit/agent/tools/test_resolution.py
• services/runner/config/agent.json
• services/runner/src/engines/sandbox_agent/environment-setup.ts
• services/runner/src/engines/sandbox_agent/pi-assets.ts
• services/runner/src/engines/sandbox_agent/run-plan.ts
• services/runner/src/engines/sandbox_agent/session-identity.ts
• services/runner/src/extensions/agenta.ts
• services/runner/src/permission-plan.ts
• services/runner/src/protocol.ts
• services/runner/tests/unit/extension-tools.test.ts
• services/runner/tests/unit/permission-plan.test.ts
• services/runner/tests/unit/pi-builtin-activation.test.ts
• services/runner/tests/unit/pi-builtin-tools-parity.test.ts
• services/runner/tests/unit/sandbox-agent-pi-assets.test.ts
• services/runner/tests/unit/sandbox-agent-qa-transcript-replay.test.ts
• services/runner/tests/unit/sandbox-agent-run-plan.test.ts
• services/runner/tests/unit/session-pool.test.ts
• services/runner/tests/unit/wire-contract.test.ts
• web/oss/src/components/AgentChatSlice/components/AgentChatEmptyState.test.ts
• web/oss/src/components/AgentChatSlice/components/AgentChatEmptyState.tsx
• web/oss/src/hooks/useAlwaysAllowTool.tsx
• web/packages/agenta-entity-ui/package.json
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/AgentTemplateControl.tsx
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/PiPermissionsControl.tsx
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/agentTemplate/ToolManagementList.tsx
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/agentTemplate/itemDescriptors.tsx
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/agentTemplate/useModelHarness.tsx
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/index.ts
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/piPermissions.ts
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/toolPermission.ts
• web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/toolUtils.ts
• web/packages/agenta-entity-ui/tests/unit/itemDescriptors.test.ts
• web/packages/agenta-entity-ui/tests/unit/piPermissions.test.ts
• web/packages/agenta-entity-ui/tests/unit/toolPermission.test.ts
• web/packages/agenta-playground/tests/unit/agentRequest.test.ts

💤 Files with no reviewable changes (6)

• services/runner/src/engines/sandbox_agent/environment-setup.ts
• services/oss/tests/pytest/unit/agent/tools/test_resolution.py
• sdks/python/oss/tests/pytest/unit/agents/platform/test_resolve.py
• sdks/python/agenta/sdk/agents/handler.py
• services/runner/src/engines/sandbox_agent/session-identity.ts
• api/oss/src/core/workflows/build_kit.py

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Align all documentation with the always-active built-in contract.

These pages retain pre-rework built-in semantics. Remove the stale claims and use the seven-name, legacy-ignored contract consistently.

• docs/design/agent-workflows/documentation/adapters/agenta.md#L34-L36: Remove the remaining forced-tool claims.
• docs/design/agent-workflows/interfaces/in-service/harness-adapters.md#L16-L23: Describe pi_agenta as forcing skills and prompts only.
• docs/design/agent-workflows/documentation/tools.md#L399-L404: Remove or qualify web_search because it is not in the seven-name runner contract.
• docs/design/agent-workflows/interfaces/public-edge/agent-config-schema.md#L24-L24: Describe builtin as legacy, accepted, and ignored.

📍 Affects 4 files

• docs/design/agent-workflows/documentation/adapters/agenta.md#L34-L36 (this comment)
• docs/design/agent-workflows/interfaces/in-service/harness-adapters.md#L16-L23
• docs/design/agent-workflows/documentation/tools.md#L399-L404
• docs/design/agent-workflows/interfaces/public-edge/agent-config-schema.md#L24-L24

[mmabrouk]

🤖 The AI agent says: Confirmed against origin/main, all four sites. adapters/agenta.md still opens with a "Forced tools: always unioned…" bullet (L8-10) that contradicts its own L34-36; harness-adapters.md still says AgentaHarness "forces the Agenta tool set" and its wire-shape table says "forced set"; tools.md L386 lists web_search among Pi's own implementations while the runner contract activates exactly the seven names; agent-config-schema.md L24 lists builtin in the runnable-type enum without the legacy note (the Default cell and the schema listing at L179 already carry the correct contract). Real follow-up: a docs sweep to align these pages with the always-active seven-name contract. Tracked as follow-up work; no code impact.

[coderabbitai]

@mmabrouk, acknowledged. The finding is valid and is out of scope for this pull request.

The follow-up should align the four documented locations with the seven always-active Pi built-ins and the legacy-ignored builtin contract. No change is required in this PR.

_{You are interacting with an AI system.}

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Normalize interface documentation paths.

The changed references do not consistently point to the current source layout.

• docs/design/agent-workflows/documentation/tools.md#L106-L107: Replace services/agent/src/protocol.ts with services/runner/src/protocol.ts.
• docs/design/agent-workflows/interfaces/README.md#L47-L47: Make sdk/agents/pi_builtins.py consistent with the documented SDK package root.

📍 Affects 2 files

• docs/design/agent-workflows/documentation/tools.md#L106-L107 (this comment)
• docs/design/agent-workflows/interfaces/README.md#L47-L47

[mmabrouk]

🤖 The AI agent says: Confirmed. services/agent/ does not exist on main; the TypeScript protocol lives at services/runner/src/protocol.ts. The same stale services/agent/... prefix also survives in several test-path references inside interfaces/README.md, so the sweep should catch those too. The sdk/agents/pi_builtins.py vs full sdks/python/agenta/sdk/agents/... root is the same normalization. Folding into the docs-sweep follow-up.

[coderabbitai]

@mmabrouk, acknowledged. The docs sweep should replace the stale services/agent/... references and normalize the SDK paths to sdks/python/agenta/sdk/.... The current finding remains open until that follow-up applies the corrections.

_{You are interacting with an AI system.}

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Scope the “only” claim to built-in permission control.

The shared tool model still allows an explicit permission on custom tools to override authored rules and the default. If this item describes only the seven Pi built-ins, say so explicitly; otherwise “permission control for Pi happens only through” is too broad.

[mmabrouk]

🤖 The AI agent says: Fair wording nit, verified: a custom tool's explicit permission does override the default at the runner (permission-plan.ts carries the resolved spec's explicit author permission into effectivePermission). The "only" holds for the seven built-ins — which can no longer carry per-tool config anywhere — but not for Pi runs as a whole. The item will be scoped to the built-ins explicitly in the docs sweep.

[coderabbitai]

@mmabrouk, agreed. The statement should apply only to the seven Pi built-ins. Custom tools can still use an explicit permission override. I will keep the comment open until the documentation update is complete.

---

✏️ Learnings added

Learnt from: mmabrouk
Repo: Agenta-AI/agenta PR: 5651
File: docs/design/agent-workflows/projects/default-agent-builtins/addendum-always-active.md:33-37
Timestamp: 2026-08-02T17:48:33.669Z
Learning: In `services/runner/src/permission-plan.ts`, a resolved custom tool specification can provide an explicit `permission` that overrides authored harness permission rules and the default permission. This override does not apply to the seven Pi built-ins because they cannot carry per-tool configuration.

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.

_{You are interacting with an AI system.}

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Validate reserved names before resolving custom tools.

Line 229 runs after secret lookup and adapter resolution. A CodeToolConfig named read with a missing secret raises MissingToolSecretError instead of ReservedToolNameError. A reserved gateway or reference name can also reach its adapter before rejection.

Validate declared custom names before secret or adapter work. Keep the final validation for names produced by adapters.

Based on PR objectives, custom tool names must not use reserved built-in names.

[mmabrouk]

🤖 The AI agent says: Confirmed on the facts: _validate_unique_names runs last (L229), so a reserved-named CodeToolConfig with a missing secret surfaces MissingToolSecretError instead of ReservedToolNameError, and reserved-named gateway/reference/platform configs reach their resolver adapters before rejection. Two qualifiers on severity: the reserved name is still always rejected before any spec leaves resolve(), so nothing ever reaches the runner — this is error-precedence plus wasted adapter calls, not a gate bypass; Minor rather than Major. The right fix matches the suggestion: validate declared config names up front and keep the final pass for adapter-produced names. Real follow-up, tracked.

[coderabbitai]

@mmabrouk, agreed. This is a Minor issue.

The current code does not allow a reserved custom tool to reach the runner. The impact is incorrect error precedence and unnecessary resolver work.

The follow-up should validate declared custom tool names before secret lookup and adapter resolution. The final _validate_unique_names(tool_specs) call should remain to validate adapter-produced tool specifications.

_{You are interacting with an AI system.}

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Pass parsed tool configurations to ToolResolver.resolve.

coerce_tool_configs() returns ToolConfigParseResult, not Sequence[ToolConfig]. This test does not reliably exercise the coerced BuiltinToolConfig. Pass coerce_tool_configs(["read"]).tool_configs to the resolver.

Proposed fix

-    resolved = await ToolResolver().resolve(coerce_tool_configs(["read"]))
+    parsed = coerce_tool_configs(["read"])
+    resolved = await ToolResolver().resolve(parsed.tool_configs)

Based on PR objectives, legacy builtin entries must be ignored by the resolver.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	async def test_a_bare_tool_name_string_is_ignored_too():
	# `coerce_tool_config` turns a bare string into a BuiltinToolConfig.
	resolved = await ToolResolver().resolve(coerce_tool_configs(["read"]))
	assert resolved.tool_specs == []
	async def test_a_bare_tool_name_string_is_ignored_too():
	# `coerce_tool_config` turns a bare string into a BuiltinToolConfig.
	parsed = coerce_tool_configs(["read"])
	resolved = await ToolResolver().resolve(parsed.tool_configs)
	assert resolved.tool_specs == []

[mmabrouk]

🤖 The AI agent says: Confirmed — the test is vacuous. coerce_tool_configs returns a ToolConfigParseResult (a pydantic model), and iterating a pydantic model yields (field, value) tuples, so resolve() sees no BuiltinToolConfig at all and returns an empty set for the wrong reason: green without exercising the coercion path. The fix is exactly coerce_tool_configs(["read"]).tool_configs. Real follow-up, tracked.

[coderabbitai]

@mmabrouk, confirmed. The test must pass coerce_tool_configs(["read"]).tool_configs to ToolResolver.resolve().

The current test does not validate the coercion-to-resolution path. I will leave the finding open until the follow-up patch is available.

_{You are interacting with an AI system.}

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Treat an omitted harness kind as pi_core.

isPiHarness is false when harness.kind is absent. The runner resolves an absent harness to pi_core, so this UI hides the Pi permission rules while Pi built-ins remain active. Include the absent value in the Pi condition and add coverage for {harness: {}}.

Proposed fix

-    const isPiHarness = harnessValue === "pi_core" || harnessValue === "pi_agenta"
+    const isPiHarness =
+        !harnessValue || harnessValue === "pi_core" || harnessValue === "pi_agenta"

Based on supplied runner contract, services/runner/src/engines/sandbox_agent/pi-model-config.ts resolves a missing harness as pi_core.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const hasPiPermissions = isPiHarness
	const isPiHarness =
	!harnessValue || harnessValue === "pi_core" || harnessValue === "pi_agenta"

[mmabrouk]

🤖 The AI agent says: Confirmed real. useModelHarness.tsx leaves harnessValue null when harness.kind is absent, so isPiHarness is false and the Pi permission rules UI is hidden — while the runner resolves a missing harness to pi_core (pi-model-config.ts isPiHarness, mirroring buildRunPlan) with all seven built-ins active and gated. Any config authored without harness.kind (SDK- or API-side) hits this. The one-line fix (!harnessValue || …) plus a {harness: {}} test case is right. One severity note: the built-ins still run under the default allow_reads policy, so this hides the controls rather than dropping the gate — a UI visibility gap, not a permission bypass. Real follow-up, tracked.

[coderabbitai]

@mmabrouk Confirmed. The severity is a UI visibility gap, not a permission bypass.

When harness.kind is absent, the runner uses pi_core and applies the permission gate. The UI must use the same default so it renders PiPermissionsControl. The tracked fix should include the omitted-kind case.

🐇

---

✏️ Learnings added

Learnt from: mmabrouk
Repo: Agenta-AI/agenta PR: 5651
File: web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/agentTemplate/useModelHarness.tsx:379-379
Timestamp: 2026-08-02T17:49:02.474Z
Learning: For Pi agent configurations, the runner resolves an omitted `harness.kind` as `pi_core`. In `web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/agentTemplate/useModelHarness.tsx`, Pi-specific permission controls must therefore treat an absent harness kind as Pi. Without this handling, the UI hides `PiPermissionsControl` while the runner still activates Pi built-ins and gates them with the default `allow_reads` permission policy. This is a UI visibility gap, not a permission bypass.

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.

_{You are interacting with an AI system.}

[github-actions]

Railway Preview Environment

Preview URL	https://gateway-production-024b.up.railway.app/w
Project	agenta-oss-pr-5651
Image tag	pr-5651-a46168f
Status	Deployed
Railway logs	Open logs
Workflow logs	View workflow run
Updated at 2026-08-02T15:15:54.480Z