agent policy: allow sub-agent (Kiln Task as Tool) creation with approval

[tawnymanticore]

What does this PR do?

Flip the agent policy on the two Kiln-task-as-tool mutation endpoints from DENY_AGENT to agent_policy_require_approval(...), so the chat agent can register / edit sub-agents on the user's behalf instead of falling back to a UI deep-link workaround.

• POST /api/projects/{project_id}/kiln_task_tool (add_kiln_task_tool)
• PATCH /api/projects/{project_id}/edit_kiln_task_tool/{tool_server_id} (edit_kiln_task_tool)
  Both routes are now permission: allow + requires_approval: true. The user sees a description of the action and explicitly accepts before the agent's call_kiln_api invocation runs. This matches the pattern already used by the fine-tune POST/PATCH and other state-changing endpoints. Approval descriptions name the feature as both "Kiln task tool" and "sub-agent" so the chat surface vocabulary matches what users actually say.
  Annotation JSONs under libs/server/kiln_server/utils/agent_checks/annotations/ regenerated via dump_annotations against the live OpenAPI spec.

Checklists

• Tests have been run locally and passed
• New tests have been added to any work in /lib

[coderabbitai]

Walkthrough

This PR updates the agent access control policy for two Kiln task tool endpoints. The endpoints transition from denying agent access entirely (DENY_AGENT) to allowing agent access with approval requirements (agent_policy_require_approval). Changes include a new import, updates to two endpoint definitions in Python, and corresponding policy annotations in JSON configuration files.

Changes

Agent Access Policy Relaxation

Layer / File(s)	Summary
Policy Function Import app/desktop/studio_server/tool_api.py	agent_policy_require_approval is imported alongside existing agent policy constants.
Endpoint Policy Updates app/desktop/studio_server/tool_api.py	POST /api/projects/{project_id}/kiln_task_tool and PATCH /api/projects/{project_id}/edit_kiln_task_tool/{tool_server_id} endpoints change from DENY_AGENT to agent_policy_require_approval(...) with approval descriptions.
Policy Annotations libs/server/kiln_server/utils/agent_checks/annotations/post_api_projects_project_id_kiln_task_tool.json, libs/server/kiln_server/utils/agent_checks/annotations/patch_api_projects_project_id_edit_kiln_task_tool_tool_server_id.json	Both endpoint annotations update agent_policy.permission from "deny" to "allow", set requires_approval to true, and add approval_description fields.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Kiln-AI/Kiln#1199: Similar OpenAPI agent-policy metadata updates, replacing DENY/ALLOW patterns with agent_policy_require_approval and updating annotation imports.

Suggested reviewers

• scosman
• leonardmq

Poem

🐰 The rabbit hops through access gates,

Where tools once denied, now approve with care,

Two endpoints bloom with thoughtful fates,

Agent requests dance in the air! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: allowing sub-agent (Kiln Task as Tool) creation with approval instead of denial.
Description check	✅ Passed	The description covers the main objective and includes a detailed explanation, but the checklists remain unchecked, which may indicate the author did not complete verification before submission.
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 mike/update-subagent-agent-permissions

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request updates the agent policy for the tool registration and editing endpoints. Specifically, it replaces the DENY_AGENT policy with agent_policy_require_approval for both the POST and PATCH methods related to Kiln task tools, and updates the corresponding JSON annotation files to reflect that these actions are now allowed with required approval and descriptive text. I have no feedback to provide.

[github-actions]

📊 Coverage Report

Overall Coverage: 92%

Diff: origin/main...HEAD

• app/desktop/studio_server/tool_api.py (100%)

Summary

• Total: 1 line
• Missing: 0 lines
• Coverage: 100%

---

• 📊 HTML Coverage Report - Interactive coverage report
• 📈 Diff Coverage Report - Detailed diff analysis
• Github Actions Run - View the full coverage report

[coderabbitai]

🧹 Nitpick comments (1)

app/desktop/studio_server/tool_api.py (1)

771-790: Consider whether archive_tool_server should also allow agent access with approval for kiln-task tools.

An agent can now create and edit sub-agents (kiln task tools) with approval, but the archive_tool_server endpoint remains DENY_AGENT. This means an agent that registers a sub-agent on a user's behalf has no way to deactivate it without the user navigating through the UI. Whether this gap is intentional (keeping destructive/lifecycle-ending operations human-only) is worth a deliberate decision.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/desktop/studio_server/tool_api.py` around lines 771 - 790, The
archive_tool_server endpoint is currently marked DENY_AGENT so agents cannot
archive kiln-task sub-agents; update it to permit agent-initiated archival with
approval for kiln-task tools by replacing or augmenting the DENY_AGENT
restriction and adding a runtime approval check: allow agent access when the
target tool_server (from tool_server_from_id) has type 'kiln-task' or equivalent
property and the incoming ToolServerArchiveRequest carries the required agent
approval flag/consent, otherwise keep DENY_AGENT for other tool types; ensure
you reference archive_tool_server, tool_server_from_id, ToolServerArchiveRequest
and the is_archived property when implementing the conditional
permission/approval logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@app/desktop/studio_server/tool_api.py`:
- Around line 771-790: The archive_tool_server endpoint is currently marked
DENY_AGENT so agents cannot archive kiln-task sub-agents; update it to permit
agent-initiated archival with approval for kiln-task tools by replacing or
augmenting the DENY_AGENT restriction and adding a runtime approval check: allow
agent access when the target tool_server (from tool_server_from_id) has type
'kiln-task' or equivalent property and the incoming ToolServerArchiveRequest
carries the required agent approval flag/consent, otherwise keep DENY_AGENT for
other tool types; ensure you reference archive_tool_server, tool_server_from_id,
ToolServerArchiveRequest and the is_archived property when implementing the
conditional permission/approval logic.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 96cb9e9b-7f50-40f8-997d-5613754b916e

📥 Commits

Reviewing files that changed from the base of the PR and between bef7fdd and 238be18.

📒 Files selected for processing (3)

• app/desktop/studio_server/tool_api.py
• libs/server/kiln_server/utils/agent_checks/annotations/patch_api_projects_project_id_edit_kiln_task_tool_tool_server_id.json
• libs/server/kiln_server/utils/agent_checks/annotations/post_api_projects_project_id_kiln_task_tool.json