15 KiB
spec, decision, created, status
| spec | decision | created | status |
|---|---|---|---|
| docs/specs/agents/requirements/external-permission-resolution.md | docs/decisions/2026-08-11-live-agent-permission-authority.md | 2026-08-11 | complete |
Implementation Plan: External Agent Permission Resolution
Overview
Add a generation-safe live permission contract at agentctl, carry it through lifecycle into an authorized orchestrator service, and serialize resolutions with a durable transcript claim before the provider receives an option. The external MCP tools then become thin typed adapters over that service. The existing web response path adopts the same request identity without changing its UI, and public/internal documentation describes the new contract and privacy boundary.
This checkout is based on upstream kdlbs/kandev:main commit
66eb87ac307db76b8cb3ba5fcfae73ff6d7d3e6c as verified on 2026-08-11. Before implementation,
fetch upstream again and fast-forward/rebase the feature branch if main moved.
Existing-solution audit
- Upstream issues #717 and #1657 concern stale approval cards and pending UI indicators, not external enumeration/resolution.
- Merged PRs #2424, #2445, and #2442 supply pending-action cleanup, MCP profile, and external session-listing patterns but no permission tool.
- Merged PR #1037 fixed rendering approval buttons for Kandev MCP tool calls inside the existing web transcript. It did not expose live requests to the external MCP endpoint.
- Searches of open upstream PRs and public fork code for pending-permission list/resolve tool names,
agent.permissions.respondMCP adapters, and equivalent schemas found no complete competing implementation as of 2026-08-11.
Backend
Live agentctl request identity and presentation
- Add
RequestIDto permission events inapps/backend/internal/agentctl/types/streams/agent.goand define typed public snapshots, strict resolve requests/results, states, and sentinel errors besideapps/backend/internal/agentctl/types/streams/permission.go. - In
apps/backend/internal/agentctl/server/process/manager.go, generate a UUID request generation for every non-auto-approved prompt, deep-copy its options, and storepending/resolvingstate underpermissionMu. - Add
ListPendingPermissionsandResolvePendingPermission. Listing returns immutable copies sorted by creation time/request ID. Resolution holds the mutex while validating request ID, pending ID, state, and exact option membership, transitions once, and never looks up by title or command. - Keep the existing internal cancellation fallback for prompts with no reject option, but do not expose cancellation in the strict external contract.
- Add credential-text redaction and allowlisted action projection under
apps/backend/internal/common/securityutil/. Commands/titles/URLs are sanitized and bounded; environment, headers, raw MCP arguments, option metadata, file contents, and diffs are omitted. Redaction failure drops the field. - Add
agent.permissions.listand strict identity fields onagent.permissions.respondinapps/backend/internal/agentctl/server/api/agent.go, then add matching client methods inapps/backend/internal/agent/runtime/agentctl/agent.go. Map unknown, stale, replayed, and unknown-option failures to distinct stable error codes.
Durable permission audit claim
- Extend the permission-request message metadata written by
apps/backend/internal/backendapp/adapters.gowithrequest_idwhile retaining existingpending_id, options, action data, and status fields for compatibility. - Add typed
PermissionResolutionAuditand result constants inapps/backend/internal/task/models/models.go. - Extend
repository.MessageRepositoryandapps/backend/internal/task/repository/sqlite/message.gowith atomic methods that:- claim a pending permission message only when task session, request ID, pending ID, and current audit state match;
- distinguish claimed, already resolved, and resolution-in-progress;
- finalize only the same
claim_id; - work through the repository's SQLite/Postgres dialect abstraction.
- Add task-service wrappers in
apps/backend/internal/task/service/service_messages.gothat publish the existingmessage.updatedevent after a claim/finalization. The pre-delivery claim records actor, source, exact option identity, anddispatching; finalization records accepted, stale, failed, or indeterminate. A claim write failure prevents runtime delivery. - Never write raw action details, command strings, environment values, PAT values, or token IDs into the resolution audit. Structured logs contain IDs, option kind, source, and result only.
Authorized permission service and runtime path
- Carry
request_idthroughapps/backend/internal/agent/runtime/lifecycle/event_types.go,apps/backend/internal/agent/runtime/lifecycle/events.go, the watcher permission payload, andMessageCreator.CreatePermissionRequestMessage. - Add list/strict-resolve methods through lifecycle manager and executor interfaces. Every session lookup uses the server-owned current execution and verifies its task/session ownership; no MCP handler imports process-manager state.
- Move permission coordination into a focused orchestrator service file, for example
apps/backend/internal/orchestrator/agent_permissions.go, with:ListPendingAgentPermissions(ctx, taskID, sessionID);ResolveAgentPermission(ctx, request);- stable domain errors for not-found, stale, replay, in-progress, option, audit, and delivery failures.
- Call
authorizeTaskSessionPairbefore runtime/message access when a session is supplied. For a task-wide list, authorize the task, enumerate its task sessions through the task service, then query only their current live executions. Any enumeration failure returns an error rather than a misleading partial list. - Derive the audit actor from
authn.IdentityFromContext: browser session, PAT, synthetic identity, or trusted internal automation. User IDs may be stored; PAT secret material and token IDs may not. - Refactor
Service.RespondToPermissionand the existingpermission.respondWebSocket handler to use the same strict service. Addtask_idandrequest_idto the response request; keep the existing reject/cancel semantics and status projection for the web UI. - When runtime delivery succeeds but audit finalization fails, return a delivery/audit error while retaining the durable dispatch claim as the replay barrier. Do not retry against another live request.
External MCP handlers and tools
- Define a narrow
AgentPermissionServiceinterface and setter inapps/backend/internal/mcp/handlers/handlers.go; wire the orchestrator implementation fromapps/backend/internal/backendapp/helpers.go. - Add backend WebSocket actions in
pkg/websocketplusapps/backend/internal/mcp/handlers/agent_permissions.go. Handlers validate required fields, call only the service, preserve not-found privacy, and map domain errors to stable descriptive MCP failures. - Register
list_pending_agent_permissions_kandevandresolve_agent_permission_kandevonly onSurfaceExternalinapps/backend/internal/mcp/server/server.go. The schemas require the exact fields from the spec; the mutation schema has no cancellation, command, arbitrary metadata, or free-form option field. - Add server forwarding handlers and profile/registration tests. Discovery remains informational; backend authorization is mandatory on every invocation.
Frontend
Existing permission response compatibility
- Add
request_idtoPermissionRequestMetadatainapps/web/components/task/chat/messages/use-permission-handlers.ts. - Send the message's
task_id, task-sessionsession_id,request_id,pending_id, and selected option throughpermission.respond. Keep the current allow-once, allow-always, reject, no-reject cancellation, loading, and error behavior unchanged. - Update
use-permission-handlers.test.tsto assert the complete identity tuple and retain the existing option-selection cases.
External MCP catalog
- Add both tool names to the task group in
apps/web/lib/settings/external-mcp-tools.tsand remove/update its known-drift note if the implementation reconciles the full external tool set. - Add localized descriptions to
src/locales/en/settings.json,pseudo/settings.json,pt-pt/settings.json, andzh-cn/settings.json; update the catalog test and count. - This is copy/data-only inside the existing responsive Settings surface. It changes no layout, navigation, overlay, touch target, scrolling, or viewport behavior, so targeted catalog tests and a focused rendered Settings check satisfy mobile parity; no new mobile Playwright scenario is required.
Tests
- Live identity and strict option validation
- File:
internal/agentctl/server/process/manager_permission_test.go - How: table-driven/concurrent unit tests for ordered snapshots, deep copies, exact option validation, request replacement with reused pending ID, duplicate response, concurrent response, cancellation, and cleanup.
- File:
- Safe presentation and redaction
- File:
internal/common/securityutil/permission_test.go - How: table-driven tests containing PATs, bearer headers, API-key flags, URL user info/query, env maps, MCP arguments, option metadata, file diffs, and unknown provider shapes; assert no canary secret occurs in marshaled output or logs.
- File:
- Agentctl API/client contract
- Files:
internal/agentctl/server/api/agent_test.go,internal/agent/runtime/agentctl/agent_test.go - How: request/response tests for list, strict resolve, error-code preservation, and no raw details in JSON.
- Files:
- Audit CAS and replay barrier
- Files:
internal/task/repository/sqlite/message_test.go,internal/task/service/service_messages_test.go - How: real SQLite plus Postgres-dialect SQL tests for first claim, competing claim, wrong request/pending/session, exact-claim finalization, terminal replay, and finalization failure.
- Files:
- Authorization and service behavior
- Files:
internal/orchestrator/agent_permissions_test.go,internal/orchestrator/session_scope_matrix_test.go - How: service fakes/real message repo covering happy list/resolve, wrong user/task/session, unknown option, no execution, no pending request, replaced/expired request, duplicate/replay, audit failure before delivery, delivery failure after claim, and actor/result audit fields.
- Files:
- MCP handler-to-service integration
- Files:
internal/mcp/handlers/agent_permissions_test.go,internal/mcp/handlers/mcp_identity_scope_test.go,internal/integration/agent_permission_mcp_test.go - How: typed handler tests plus an authenticated external-MCP path using a real task/message repository and fake live runtime. Assert cross-user invisibility, task/session binding, exact schema, stable errors, and one provider response.
- Files:
- Tool registration and schema
- Files:
internal/mcp/server/agent_permissions_test.go, existing profile/tool-count tests - How: assert tools occur only on external surface and mutation schema exposes exactly five required string fields.
- Files:
- Web compatibility and catalog
- Files:
components/task/chat/messages/use-permission-handlers.test.ts,lib/settings/external-mcp-tools.test.ts - How: hook request-payload tests, existing allow/reject cases, catalog membership/count, i18n
checks, and the existing
e2e/tests/chat/permission-approval.spec.tsregression.
- Files:
E2E Tests
No new visual scenario is required: the new primary surface is an MCP contract and the Settings
change is catalog copy inside an unchanged responsive component. Re-run
apps/web/e2e/tests/chat/permission-approval.spec.ts to prove the existing desktop permission flow
still resolves sequential prompts and Kandev MCP tool prompts. Backend integration tests own the
external list/resolve security and race guarantees.
Documentation
- Update
docs/public/automation-and-mcp.md(how-to/explanation) with the two external tools, a list/resolve example, PAT/task scoping, stale/replay errors, and the rule that clients must display only the returned immutable options. - Update
docs/public/agents-and-profiles.md(explanation/reference) to mention that a person may answer structured ACP permission prompts through authorized external MCP as well as the session UI, without changing auto-approval defaults. - Update
docs/backend_agentctl_connectivity.mdwithagent.permissions.list, request generation, and strict resolution fields. - Correct the permission section in
docs/WEBSOCKET_API.mdto distinguish Kandev task-session IDs from ACP IDs and documentrequest_idon notification/response. - MCP JSON Schemas remain generated from
mcp.NewTooldeclarations at runtime; registration/schema tests are the checked contract. No hand-edited generated schema artifact exists.
Verification Results
- Task 01 passed its prescribed four-package Go test suite with the repository-pinned Go 1.26.0 toolchain.
- Task 02 repository/backendapp suites and focused task-service audit tests passed. The full
task-service suite has unrelated container parent-chain failures because
/is owned bynobody; details are recorded in the task file. - Task 03 passed its prescribed lifecycle/executor/orchestrator/handler/backendapp Go suite.
- Task 04 passed its handler, MCP server, and authenticated integration suites, including PAT scope, strict identity, replay rejection, and audit redaction coverage.
- Task 05 passed focused web tests (16), lint, typecheck, i18n and public-doc validation, backend and E2E builds, and the existing Chromium permission E2E (3 tests).
Implementation Waves And Parallel Candidates
Wave 1:
Wave 2:
Wave 3:
Wave 4 (parallel candidates after task 03; user authorization required):
Tasks 04 and 05 are parallel-safe only after their shared backend request contract is fixed in task 03; they own disjoint MCP-server versus frontend/docs files. The default remains sequential work in the primary conversation.