docs(planning): implementation plan for the three operator follow-ups

[ginccc]

A hand-off document for the three open operator follow-ups, written so another agent can pick any of them up cold — no chat history needed.

• A — operator can converse with other agents/groups (Manager)
• B — operator conversation survives navigation + restart, plus a history tab (Manager)
• C — a tool call whose body is invalid JSON should fail before the API call (EDDI)

Structure: shared background first (what the operator actually is, why a capability is an allow-list entry rather than a tool, the gate model, the constraints already decided in operator-write-scope-plan.md §5, and the verification traps in both repos), then per-task problem → route → decisions → tests → risks.

Two findings in it are worth not rediscovering:

1. converse_with_agent is the wrong route for A. It needs enableBuiltInTools + builtInToolsWhitelist (which setup-api never sends) and dynamicAgents.enabled + allowDelegation — which escalation-flags.ts deliberately flags to approvers as an escalation. Using EDDI's own REST conversation endpoints fits the operator's architecture instead.
2. Exempting a conversation POST is currently impossible. verifyGateInstalled rejects any exempt beginning http.post: — including a narrow one — so activation would fail its own verification. Approve-every-message is the only option available without a deliberate security-boundary edit, and the plan says so rather than leaving the next agent to discover it.

Task A has since been implemented in EDDI-Manager#156; the plan is kept as the reasoning record and for B and C.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e0a4fff9-fa3f-47da-b525-c618c7b85240

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[Copilot]

Pull request overview

Adds a hand-off plan for Platform Operator follow-ups, preserving Task A’s rationale and planning Tasks B and C.

Changes:

• Documents operator architecture and HITL constraints.
• Plans conversation persistence/history.
• Plans invalid JSON request-body validation.

Suppressed comments (4)

planning/operator-followups-plan.md:260

• This implementation route was disproved while implementing Task A. EDDI-Manager#156 found that method-based grantsWriteCapability treats these POSTs as writes; putting them in READ_ENDPOINTS incorrectly removes the read-only prompt rules. The merged implementation keeps the three GETs in READ_ENDPOINTS and places the three POSTs in TEST_DRIVE_WRITES/WRITE_ENDPOINTS, so this reasoning record should capture that correction.

1. **`src/lib/operator/tool-scopes.ts`**
   - Add the six endpoints above to `READ_ENDPOINTS` (all of them — `READ_ENDPOINTS` is the
     *granted* set, not "only GETs"; the gate is what distinguishes them). Group them under a
     `// Test-drive: talk to an agent or group` comment explaining that the POSTs are gated and that

planning/operator-followups-plan.md:407

• This guard runs inside the tool executor, but gated POST tools are paused before their executor is invoked. The invalid body would therefore still consume the human approval that §D says Task C prevents. The plan needs validation in a pre-gate path (plus a gated end-to-end test proving no pause is created), or it must explicitly narrow the goal to preventing only the HTTP request.

In `HttpCallToolsProvider` (the executor lambda, ~line 182), before calling
`apiCallExecutor.execute(...)`:

planning/operator-followups-plan.md:419

• A hard-coded requestBody lookup misses generated tools where McpApiToolBuilder renames that variable on collision with a path/query parameter (for example, to requestBodyBody). In that valid OpenAPI case invalid JSON still reaches the API. Validate the fully rendered request body that will be sent, rather than one argument-map key, and add a collision test.

Where to read the argument: `templateDataFor(memory, toolRequest)` already deserialises
`toolRequest.arguments()` into a map and merges it. Read `requestBody` from that map rather than
re-parsing the arguments string.

planning/operator-followups-plan.md:280

• These scope expectations no longer match the merged implementation: a read-only operator deliberately cannot create conversation records, so the POST endpoints are absent there. Keeping this assertion would send the next agent toward the same capability-classification regression fixed in EDDI-Manager#156.

   - the six endpoints are present in `endpointsForScope("read_only")` and `("read_write")`;
   - `/resume`, `/state`, `/cancel` are **absent** from both — assert this explicitly, it is the
     regression that matters;
   - `buildToolApprovals()` still returns exempt `["http.get:*"]` only (proves A1 did not silently
     become A2);

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.