docs(agent): direct-call tools design (Workstream A)

docs/design/agent-workflows/projects/direct-call-tools/README.md

@@ -0,0 +1,23 @@
+# Direct-call tools (Workstream A)
+
+Make resolved agent tools carry their own call target, so the sidecar calls reference and
+platform tools directly and only gateway (Composio) tools route through the central
+`/tools/call`.
+
+## Files in this workspace
+
+- **`plan.md`** — the hand-off and the two-workstream split (A here, B on PRs #4860/#4877),
+  plus the Workstream A execution phases. This is the file the orchestrator was pointed at.
+- **`context.md`** — why this exists: the conversation, the decision, goals and non-goals.
+- **`research.md`** — the actual code seams with file:line, and the nuances that shape the
+  design (reference still needs the API; the args-placement wrinkle; the schema catalog).
+- **`design.md`** — the technical design: the `call` descriptor, the dispatch algorithm, the
+  per-tool-type table (config → resolved → dispatch), the platform-op catalog.
+- **`status.md`** — current state, what Workstream B is doing concurrently, open decisions,
+  next step. Source of truth for progress.
+
+## One-line state
+
+Planning. No code yet. Workstream B is active in parallel on the reference tool (PRs #4860 /
+#4877); the shared file `sdks/python/agenta/sdk/agents/tools/models.py` must be serialized.
+See `status.md`.

docs/design/agent-workflows/projects/direct-call-tools/context.md

@@ -0,0 +1,60 @@
+# Context
+
+## Where this came from
+
+In a design conversation, Mahmoud pushed on how agent tool calls route. Today every resolved
+callback tool POSTs to one endpoint, `/tools/call`, which re-parses a string `call_ref` and
+re-dispatches: `workflow.*` runs a referenced workflow, `tools.*` runs a Composio action. His
+objection, first raised as an inline comment on PR #4863 (`custom-tools-design.md` line 67):
+the proposed platform tools (create_workflow, annotate, ...) would have `/tools/call` make HTTP
+calls to other Agenta API endpoints. Calls between two API endpoints with no value. Those
+should be direct service calls.
+
+Generalized: a tool that points at another Agenta workflow ("reference") or runs an Agenta
+operation ("platform") is just an Agenta endpoint, and the sidecar already holds the caller's
+credential. So the `/tools/call` hop adds a step and no value for those two. Only gateway
+(Composio) tools need the server, because only the server can read the Composio secret from the
+vault.
+
+## The decision
+
+1. Resolved tools carry their own call target. The sidecar calls reference and platform tools
+   directly; gateway stays server-side through `/tools/call`.
+2. Drop the `@ag.reference` marker. A reference tool is just `type:"reference"` in the config
+   `tools` list. (This is Workstream B, on the existing reference PRs.)
+3. Keep `@ag.embed` (it inlines a value, a different feature). Hide it from the tool UI for now.
+4. A reference can point at an environment or a variant, each at latest or a pinned revision.
+   (Schema is Workstream B; resolution is Workstream A.)
+
+## Goals
+
+- Kill the endpoint-to-endpoint pattern for platform tools: they run as in-process service
+  calls behind one direct endpoint each, never `/tools/call` re-hitting `/api/...`.
+- Give the SDK the routing decision (each tool resolves to a concrete call target), and shrink
+  `/tools/call` to the gateway-only executor.
+- Keep the sidecar dumb and the Daytona sandbox unchanged (still name + args; the host runner
+  makes the direct call).
+- Keep one credential (the run's caller auth) and never let the model retarget a locked call.
+
+## Non-goals
+
+- Letting tools call non-Agenta hosts. Paths are relative; the sidecar joins its own Agenta
+  base. Off-Agenta targets are a deliberate later decision.
+- Changing gateway (Composio) execution. It keeps its server-side path.
+- Streaming a sub-agent's tokens into the parent model. A reference runs in batch; the model
+  gets the final output; the user sees the nested run through the trace.
+- Re-implementing the reference config schema (Workstream B owns it). A reuses it.
+
+## Why now
+
+The reference tool is already in review (PR #4860) with a frontend stacked on it (#4877). The
+custom-tools design note (#4863) is waiting on the execution model. Settling the routing now
+lets both land on the right shape instead of on `/tools/call` string-routing.
+
+## Merge, review, and ownership
+
+Mahmoud reviewed this design and is aligned with all the decisions. His one standing requirement
+is the ability to review before anything merges. Merge order, commit organization, and how the
+work is split across PRs are the orchestrator's call, not design decisions captured here. So the
+"sequencing notes" in `plan.md` and `status.md` are guidance for the orchestrator, not approvals
+Mahmoud owes.