Drive a governed Maestro tool call through Platform ToolExecution end to end

[haasonsaas]

Summary

Maestro has the design and partial bridge shape for Platform ToolExecution, but we need one real end-to-end governed execution path that proves the contract across Maestro runtime, Platform policy/approvals, ToolExecution state, CloudEvents, and timeline.

Start with one concrete tool class rather than trying to migrate every tool at once.

Why it matters

ToolExecution is the cleanest practical spine for the Maestro/Platform overlap. It is narrow enough to ship, but rich enough to validate the correlation model that later powers AgentRuntime, Slack decisions, audit, meter, governance learning, and timeline.

What to build

• Pick one high-signal tool path, preferably Bash/shell or one MCP tool path, and route it through Platform ExecuteTool when the Platform bridge is enabled.
• Send normalized execution context: organization, workspace, Maestro session, AgentRun, AgentRunStep, actor, surface/channel, cwd/repo, command/tool name, sanitized args, and correlation ids.
• Support observe-only mode and governed mode.
• In governed mode, block local execution until Platform returns allow or an approval is resolved.
• On approval-required, surface the pending request through Maestro's approval UI/headless protocol and resume through Platform ResumeToolExecution.
• Record tool_execution_id, approval_request_id, and governed outcome into Maestro events and runtime metadata.
• Preserve local/offline behavior and existing safety semantics when disabled.

Acceptance criteria

• A test or smoke path shows one Maestro tool call creating a Platform ToolExecution record.
• Approval-required flow produces a pending request, resolves it, resumes execution, and records the final result.
• The final Maestro tool result event includes Platform correlation ids.
• Deny/unavailable/malformed Platform responses have explicit user-facing behavior and tests.
• Platform timeline can show the same tool execution without requiring bespoke joins.

Related: #73, #74, evalops/platform#917, evalops/platform#919, evalops/platform#765.

[haasonsaas]

PR #173 is up for the next ToolExecution slice.

It adds normalized runtime context metadata to every observed/governed Maestro Platform ToolExecution request: AgentRun, AgentRun step, actor, correlation id, cwd, workspace root, repository root/name, git branch, and git commit. The request is built from Maestro/CI env plus process.cwd() without shelling out, so Platform timeline can join the execution to the same run/step/repo context without bespoke Maestro-only joins.

Local focused validation is green with Bun 1.3.6:

• npm test -- test/agent/tool-execution-bridge.test.ts test/platform/tool-execution-client.test.ts
• bunx biome check src/agent/transport/tool-execution-bridge.ts test/agent/tool-execution-bridge.test.ts docs/design/PLATFORM_TOOL_EXECUTION_BRIDGE.md
• git diff --check

[haasonsaas]

Update: #173 now has the required source-of-truth provenance via evalops/maestro-internal#1483, and the public require-internal-pr check reran green. Both PRs have auto-merge enabled and no review threads at the moment.

[haasonsaas]

Bugbot follow-up is now split out as a fix-forward: internal #1484 and public #174. It replaces the metadata scrubber split/map/join with a direct for...of loop while preserving behavior and keeping Biome happy. Both PRs have auto-merge enabled.

[haasonsaas]

PR #176 is up with internal source-of-truth PR evalops/maestro-internal#1485.

This slice completes the final-output leg for governed Platform ToolExecution: Maestro now calls RecordToolExecutionOutput after local governed execution completes, preserving tool_execution_id / approval correlation while sending a safe JSON summary, duration, local outcome, and runtime metadata back to Platform.

Focused validation is green:

• npm test -- test/platform/tool-execution-client.test.ts test/agent/tool-execution-bridge.test.ts test/agent/tool-execution-retry.test.ts
• bunx biome check src/platform/tool-execution-client.ts src/agent/transport/tool-execution-bridge.ts src/agent/transport/tool-execution.ts test/platform/tool-execution-client.test.ts test/agent/tool-execution-bridge.test.ts
• git diff --check

[haasonsaas]

Status refresh from the AgentRuntime lifecycle lane: evalops/maestro-internal#1610 is now open and keeps the governed-tool story attached to the Platform run spine.

The new smoke harness drives a governed-tool-shaped lifecycle against a live Platform AgentRuntime handler: Maestro session trigger -> worker lease -> tool-call-intent step -> approval wait/checkpoint -> resume -> completion -> Platform event read-back. I also reran the existing ToolExecution bridge and Platform timeline tests so this remains compatible with the ExecuteTool / approval / output path already landed for this issue.

Validation evidence:

• MAESTRO_PLATFORM_REPO=/Users/jonathanhaas/Documents/Projects/platform npm run platform:agentruntime-e2e -> 13 live Platform runtime events
• MAESTRO_PLATFORM_REPO=/Users/jonathanhaas/Documents/Projects/platform npm run platform:timeline-e2e
• npm run test -- test/agent/tool-execution-bridge.test.ts test/platform/maestro-timeline-client.test.ts