feat(agent): make delegation and platform MCP capability-explicit - #3028
Merged
Conversation
Agent definitions now carry fixed delegate scopes and MCP policies through local, hosted, streaming, and child-fork execution. Environment configuration selects the trusted Veryfront endpoint but never grants tools; project and service policies remain authoritative, and malformed or widened request configuration fails closed. The package version advances to 0.1.1106 so merging this change produces a release. Constraint: Local projects pulled from Studio must work against the configured Veryfront API without granting capabilities from environment variables. Constraint: Hosted service MCP configuration is a hard ceiling that agents and request overrides may only narrow. Rejected: Synthesize platform tools from prompts or environment state | tool inventories must come from explicit agent grants and authoritative MCP discovery. Rejected: Preserve the generic invoke_agent surface for scoped agents | fixed agent_<id> tools make delegation auditable and capability-minimal. Confidence: high Scope-risk: broad Directive: Do not let endpoint configuration, request metadata, or child forks widen agent tools, delegates, or MCP policy. Tested: 285 changed-runtime tests; format; lint; typecheck; public-guide validation and contracts; npm build and root-import lifecycle at 0.1.1106. Not-tested: Full verify:quick completion is blocked by the pre-existing missing index.client API-reference example on origin/main.
The capability-bound hosted runtime changes now leave the cloud system-message test free of type errors, so the shrink-only baseline must stop grandfathering it. Constraint: CI rejects both new test type errors and stale baseline exceptions. Confidence: high Scope-risk: narrow Directive: Keep the test-typecheck baseline shrink-only. Tested: deno task lint:test-typecheck; 107 remaining grandfathered files and zero new failures. Not-tested: Full CI is rerun by the branch push.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR makes agent delegation and MCP tool access capability-explicit across local, hosted, streaming, and child-fork execution, with “narrowing-only” policy ceilings and safer project/identity binding for first-party MCP servers.
Changes:
- Adds explicit
delegatescapability that exposes fixedagent_<id>tools and enforces bounded nested delegation lineage. - Makes MCP connectivity capability-driven (implicit Veryfront API MCP only for unresolved explicitly named tools;
mcpServers: []hard opt-out), and enforces allow/deny policies on list and execute. - Hardens project scoping and remote discovery authority (no synthesizing missing tools; strips untrusted
project_referencewhere appropriate).
Verification
- Not run in this review environment.
- PR metadata reports: format, lint, typecheck, and multiple focused/full test suites passing (0 failures), plus guide validation and npm build checks at
0.1.1106.
Reviewed changes
Copilot reviewed 65 out of 65 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/utils/version-constant.ts | Bumps shared version constant to 0.1.1106. |
| deno.json | Bumps package version to 0.1.1106. |
| src/tool/project-scoped-remote-tools.ts | Makes remote tool discovery authoritative; rejects execution of non-advertised tools. |
| src/tool/project-scoped-remote-tools.test.ts | Adds coverage for rejecting non-advertised tool execution. |
| src/server/handlers/request/agent-stream.handler.ts | Makes platform MCP injection capability-explicit; binds platform tools to project identity; preserves MCP opt-outs. |
| src/server/handlers/request/agent-stream.handler.test.ts | Adds tests for explicit MCP opt-out, discovery failure fail-closed behavior, and project binding behavior. |
| src/platform/cloud/resolver.ts | Adds host-bootstrap resolver to isolate trusted server identity from request context. |
| src/platform/cloud/resolver.test.ts | Tests host bootstrap isolation from request-scoped context. |
| src/internal-agents/run-system-prompt.ts | Threads availableToolNames into internal agent prompt composition. |
| src/chat/stream-watchdog.ts | Supports long-running tool prefixes (for agent_ delegate tools). |
| src/chat/stream-watchdog.test.ts | Tests prefix-based long-running tool behavior. |
| src/agent/types.ts | Adds delegates?: string[] to AgentConfig. |
| src/agent/streaming/fork-runtime-stream.ts | Plumbs temperature through hosted fork start/step paths. |
| src/agent/runtime/stream-tool-authority.test.ts | New test: suppresses provider-dropped streamed tool calls (tool authority hardening). |
| src/agent/runtime/skill-prompt.ts | Updates skill prompt delegation guidance to prefer scoped agent_<id> tools when available. |
| src/agent/runtime/skill-prompt.test.ts | Adds tests for scoped delegation guidance and omission when unavailable. |
| src/agent/runtime/skill-metadata.ts | Makes delegation/override notes conditional on actual available delegation tools; treats empty tool surfaces explicitly. |
| src/agent/runtime/skill-metadata.test.ts | Expands coverage for explicit empty tool surfaces and scoped delegate availability behavior. |
| src/agent/runtime/mcp-server-tool-sources.ts | Introduces first-party MCP presets, policy-wrapping, project binding, and implicit API MCP only for unresolved explicit tools. |
| src/agent/runtime/mcp-server-tool-sources.test.ts | Extensive coverage for implicit/explicit MCP behavior, policy enforcement, discovery authority, and identity requirements. |
| src/agent/runtime/load-skill-tool.ts | Makes load-skill continuation/delegation guidance depend on available scoped delegate tools. |
| src/agent/runtime/load-skill-tool.test.ts | Tests scoped delegate naming and omission of legacy override forwarding when invoke_agent is absent. |
| src/agent/runtime/index.ts | Passes agent id into MCP source resolution; stabilizes tool-name ordering. |
| src/agent/runtime/agent-markdown-adapter.ts | Ensures markdown agents carry delegates/mcpServers so the factory can apply scoped delegate tooling. |
| src/agent/runtime/agent-markdown-adapter.test.ts | Updates/extends tests for delegates and MCP server preservation. |
| src/agent/runtime/agent-delegation.ts | Adds executor override to keep delegate tools fixed-target in hosted runtimes; updates delegation-cycle guidance. |
| src/agent/runtime/agent-delegation.test.ts | Adds test for fixed-target host execution path. |
| src/agent/runtime/agent-delegation-names.ts | Adds normalization/validation for delegate ids with clear diagnostics. |
| src/agent/runtime/agent-definition.ts | Extends markdown schema to include first-party MCP presets; tightens selector parsing and diagnostics. |
| src/agent/runtime/agent-definition.test.ts | Updates tests for malformed selectors, explicit empty delegates, MCP presets, and scalar rejection. |
| src/agent/project/agent-runtime.ts | Serializes delegates and first-party MCP presets; rejects serializing credentialed HTTP MCP servers into hosted definitions. |
| src/agent/project/agent-runtime.test.ts | Adds tests for delegate + MCP preset serialization and non-serializable HTTP MCP rejection. |
| src/agent/index.ts | Exposes additional MCP config types via public exports. |
| src/agent/hosted/veryfront-cloud-agent-service.ts | Materializes fixed delegate tools in hosted runs, narrows MCP servers under service ceilings, and configures child execution scopes. |
| src/agent/hosted/veryfront-cloud-agent-service.test.ts | Adds tests for hosted child tool lists, nested delegate context lineage, MCP ceiling narrowing, and temperature preservation. |
| src/agent/hosted/runtime-request-config.ts | Ensures request overrides can only narrow configured tool surfaces; includes delegates in configured tool set. |
| src/agent/hosted/runtime-request-config.test.ts | Updates tests to validate narrowing-only behavior and delegate inclusion. |
| src/agent/hosted/project-remote-tool-source.ts | Strips untrusted project_reference for non-navigation tools; avoids retry tool execution when unadvertised/outside allowlist; explicit Studio MCP errors. |
| src/agent/hosted/project-remote-tool-source.test.ts | Adds tests for project_reference stripping, retry safety, explicit Studio MCP failure modes, and no Studio inference under explicit API-only MCP. |
| src/agent/hosted/durable-child-fork-execution.ts | Threads trusted invocation context through durable child bootstrap to preserve lineage safely. |
| src/agent/hosted/durable-child-fork-execution.test.ts | Updates expected structured context to include root/parent message ids and delegation depth. |
| src/agent/hosted/default-project-steering-refresh.ts | Passes availableToolNames into hosted runtime instructions for correct delegation guidance. |
| src/agent/hosted/default-invoke-agent-tool.ts | Adds fixed-child execution config plumbing, durable enforcement controls, invocation lineage handling, and child-scope tool assembly. |
| src/agent/hosted/default-invoke-agent-tool.test.ts | Adds tests for child config application, durable enforcement, and fixed delegate behavior. |
| src/agent/hosted/cloud-runtime-system-messages.ts | Threads availableToolNames into hosted runtime system messages. |
| src/agent/hosted/cloud-runtime-system-messages.test.ts | Adds coverage for scoped delegation guidance in hosted system messages. |
| src/agent/hosted/cloud-prepared-chat-execution-runtime.ts | Configures watchdog to treat agent_ tools as long-running via prefixes. |
| src/agent/hosted/child-tool-input.ts | Adds temperature override and trusted invocation context with a delegation depth cap. |
| src/agent/hosted/child-tool-input.test.ts | Tests trusted lineage behavior, model-supplied reset suppression, and depth cap enforcement. |
| src/agent/hosted/child-requested-tools.ts | Differentiates requestedTools: undefined (inherit) vs [] (explicitly no tools). |
| src/agent/hosted/child-requested-tools.test.ts | Adds/updates tests for explicit empty tool grants. |
| src/agent/hosted/child-fork-tool-sources.ts | Enforces MCP tool policy at listing and execution for child forks; preserves explicit MCP opt-out. |
| src/agent/hosted/child-fork-tool-sources.test.ts | Adds extensive tests for MCP policy enforcement across API/generic/Studio and explicit opt-out. |
| src/agent/hosted/child-fork-execution-runner.ts | Plumbs temperature and invocation lineage controls through child fork execution path. |
| src/agent/hosted/child-fork-execution-runner.test.ts | Updates tests to validate temperature and lineage fields. |
| src/agent/hosted/chat-runtime-tool-assembly.test.ts | Adds test ensuring explicit API-only MCP does not grant Studio tools. |
| src/agent/hosted/chat-preparation.ts | Adds availableToolNames to hosted chat runtime instructions input shape. |
| src/agent/hosted/chat-preparation.test.ts | Updates expectations around provider tools narrowing behavior. |
| src/agent/hosted/chat-execution-runtime.ts | Treats scoped delegate tools as long-running in the default watchdog. |
| src/agent/factory.ts | Normalizes delegates, creates scoped delegate tools, and rejects delegates combined with tools: true. |
| src/agent/factory.test.ts | Adds coverage for delegate tool binding and tools: true rejection with delegates. |
| docs/guides/tools.md | Documents implicit Veryfront API MCP behavior and explicit opt-out/policy. |
| docs/guides/multi-agent.md | Documents declarative delegation for code + markdown, scoped tools, and depth-capped hosted lineage. |
| docs/guides/agents.md | Documents implicit MCP resolution, explicit opt-out, and new delegates config field. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d3d26288c9
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 65 out of 65 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
src/server/handlers/request/agent-stream.handler.ts:91
- Studio MCP source id is hard-coded as "veryfront-studio-mcp" here, while other MCP plumbing in this PR uses the canonical Studio source id "studio-mcp". If an injected Studio source uses the canonical id, the de-duplication check later in this file can miss it and add a second Studio MCP source, potentially widening exposure or creating duplicate discovery/execute calls.
Contributor
Author
Review: capability-explicit delegation & platform MCPReviewed the full 64-file diff with a focus on the security model in the PR description. Verdict: the capability model holds as documented — no blocking defects found. One defense-in-depth gap worth fixing before or shortly after merge, plus a handful of minors. Verified properties (traced against branch source, not just the diff)
Finding worth acting on
Minor findings
Nits
Trust-boundary note (out of diff scope)
Review process: five parallel reviewers over disjoint diff slices (runtime core, child-fork, hosted service, MCP/skills, server/docs) with adversarial cross-examination of every cross-slice assumption; all "can this widen?" questions were traced to resolution against the branch source. |
Review exposed that fixed child configuration was materialized before an explicit project switch. Resolve child steering against the requested project, reset stale branch context, standardize the Studio MCP source identity, and fail invalid markdown capability combinations during discovery. Constraint: Fixed delegate capabilities and remote MCP policy must match the project that actually executes the child run. Rejected: Mutate the parent run context before resolving child configuration | it would leak project switching into setup and failure paths. Confidence: high Scope-risk: narrow Directive: Keep child configuration resolution keyed to the effective run project, not the parent context snapshot. Tested: Full pre-push gate; 2608 tests / 21293 steps; focused hosted, handler, skill, and markdown parser suites; test typecheck baseline.
Negative trusted delegation depth can otherwise underflow the child depth cap, while plain MCP bootstrap errors prevent callers from handling configuration and permission failures consistently. Clamp only the lower bound and surface typed framework errors at the hosted and direct runtime boundaries. Constraint: Delegation depth and MCP trust failures must remain enforceable and classifiable across hosted and direct runtimes. Rejected: Clamp all depth values to the maximum | over-limit lineage must still fail closed. Confidence: high Scope-risk: narrow Reversibility: clean Directive: Preserve CONFIG_INVALID for host wiring failures and PERMISSION_DENIED for caller capability denials. Tested: Full pre-push gate; 2609 tests and 21293 steps passed with zero failures. Not-tested: Live hosted control-plane integration.
kwakayama
approved these changes
Jul 22, 2026
kojiwakayama
enabled auto-merge (squash)
July 22, 2026 21:47
Comment on lines
+184
to
+186
| const rawSource = createRemoteToolSource(remoteConfig); | ||
| const policySource = createHostedMcpToolPolicySource(rawSource, server.toolPolicy); | ||
| const rawDefinitions = await rawSource.listTools(); |
Comment on lines
+139
to
145
| return isLongRunningToolRunning( | ||
| currentState, | ||
| resolvedOptions.longRunningToolNames, | ||
| resolvedOptions.longRunningToolPrefixes, | ||
| ) | ||
| ? currentState | ||
| : createChatStreamWatchdogState("response_pending", undefined, resolvedOptions); |
Comment on lines
+151
to
157
| return isLongRunningToolRunning( | ||
| currentState, | ||
| resolvedOptions.longRunningToolNames, | ||
| resolvedOptions.longRunningToolPrefixes, | ||
| ) | ||
| ? currentState | ||
| : createChatStreamWatchdogState("response_pending", undefined, resolvedOptions); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Security model
Validation
Context
This branch is based on main after #3027 merged. The broader verify:quick path still reaches the pre-existing documentation validation gap for the missing index.client API-reference example; no file in this diff owns that gap.