Bind agent tool calls to the run's repositories

agent.run_command and the git.* pull-request tools resolved a
model-supplied repositoryId by id and team only, so an agent could
clone, read, merge or comment on any repository of its team at any ref
it named, including repositories its run was never bound to and
unmerged branches, using that repository's connection credential.
Network Off and a read-only write scope did not stop it.

The run's bound repositories (its admitted task's workspace, with each
repository's access and ref) are now stamped server-side onto the
posture every tool call carries. NodeAgentTool holds every node that
declares a repository input (NodeManifest.RepositoryInput) to that set:
any other id gets the same "not found" a missing or foreign one gets.
Read-only context is the run's to read, not to write: an agent opens,
merges, reviews and comments on none of its pull requests, and a
command checks it out only at its bound or default branch. The pin
covers what a command checks out; the repository's pull requests stay
readable through the git read tools. A patch-only repository refuses
agent pull-request writes through the guard chain an agent's pushed
branch meets.

Each of these refusals is answered before a call is parked for
approval (IAgentTool.RefusalAsync), so a Standard or Trusted run never
asks a human to approve a call that could only be refused; the tool
checks again when the call runs, since a repository can change while a
card waits. RunCommandService keeps its own ref pin for a caller that
reaches it directly.

A supervisor-spawned child's related repositories carry the operator's
bound ref, not one the supervisor model authored: that ref is what the
child clones and what its read-only binding pins commands to.

A run whose write scope is read-only (an agent.run with readOnly, or a
Confined tier) is served a NonDestructive catalog: every tool that does
not write, so it can still ask a human through decision.request. The
fabric opt-out's ReadOnly slice is unchanged. Workflow-node calls carry
no calling run and are unchanged.

Author: ppXD

backend/src/CodeSpace.Core/Services/Agents/AgentRepositoryBinding.cs

@@ -0,0 +1,55 @@
+using CodeSpace.Messages.Agents;
+
+namespace CodeSpace.Core.Services.Agents;
+
+/// <summary>
+/// The calling run's hold on a repository its tool call names (<see cref="AgentRunPosture.Repositories"/>). Team scope
+/// alone let an agent reach every repository of its team at any ref it chose; the run's own binding is narrower. A
+/// repository outside it gets the "not found" a missing or foreign one gets, so a refusal never confirms that a guessed
+/// id exists. A writable repository is the run's own to work in, at any ref. Read-only context is something the run
+/// reads: a command checks out only its bound branch or its default branch, and an agent writes nothing to it — no pull
+/// request opened, merged, reviewed or commented on. Pure — consulted by <c>NodeAgentTool</c> for every
+/// manifest-declared repository input and by <c>RunCommandService</c> for an agent's command.
+///
+/// <para>The ref pin holds what a command CHECKS OUT, so the working tree an agent builds and runs from read-only
+/// context is the content the operator bound, never a branch it named. It does not hide what the provider publishes
+/// about a bound repository: its pull requests — their list, diffs and checks — are readable through the git read tools
+/// like the rest of the repository, whatever ref it is bound at. A repository whose open pull requests must stay out of
+/// a run's reach is one not to bind to it.</para>
+/// </summary>
+public static class AgentRepositoryBinding
+{
+    /// <summary>
+    /// The refusal for a repository outside the run's binding — the same answer whether the id is this team's, another
+    /// team's or nobody's, and byte-identical to <c>RunCommandService</c>'s own tenant-filter miss.
+    /// </summary>
+    public static string NotFound(Guid repositoryId) => $"Repository {repositoryId} not found.";
+
+    /// <summary>The refusal for a pull-request write to a repository the run is bound to only as read-only context.</summary>
+    public static string ReadOnlyContextWrite(Guid repositoryId) =>
+        $"Repository {repositoryId} is bound to this run as read-only context, so an agent may not open, merge, review or comment on its pull requests.";
+
+    /// <summary>The refusal for a command checking out a ref of read-only context outside its binding.</summary>
+    public static string RefOutsideBinding(Guid repositoryId, WorkspaceRepositorySpec bound, string? requestedRef, string defaultBranch) =>
+        $"Repository {repositoryId} is bound to this run as read-only context at '{bound.Ref ?? defaultBranch}', so a command may check out only that branch or the default branch '{defaultBranch}', not '{requestedRef}'.";
+
+    /// <summary>The run's binding of <paramref name="repositoryId"/>, or null when the run is not bound to it.</summary>
+    public static WorkspaceRepositorySpec? Find(AgentRunPosture caller, Guid repositoryId) =>
+        caller.Repositories.FirstOrDefault(repository => repository.RepositoryId == repositoryId);
+
+    /// <summary>Whether an agent may write to a bound repository through its provider: only a writable one. An access this code does not know is held like read-only context.</summary>
+    public static bool AllowsWrite(WorkspaceRepositorySpec bound) => bound.Access == WorkspaceAccess.Write;
+
+    /// <summary>
+    /// Whether a command may check out <paramref name="requestedRef"/> of a bound repository: any ref of a writable one;
+    /// of read-only context, its bound branch (else the default branch) or the default branch — compared exactly, as git
+    /// names refs. A blank ref is the default branch, as the clone reads it. An access this code does not know is held
+    /// like read-only context.
+    /// </summary>
+    public static bool AllowsRef(WorkspaceRepositorySpec bound, string? requestedRef, string defaultBranch)
+    {
+        if (AllowsWrite(bound) || string.IsNullOrWhiteSpace(requestedRef)) return true;
+
+        return requestedRef == defaultBranch || requestedRef == (bound.Ref ?? defaultBranch);
+    }
+}

backend/src/CodeSpace.Core/Services/Agents/AgentRunExecutor.cs

@@ -3601,9 +3601,18 @@ internal static string BuildBranchName(Guid runId, long fenceEpoch = 1) =>
     /// selects <see cref="McpCatalogMode.Full"/> — the whole registry incl. the side-effecting fabric, byte-identical to
     /// before. OFF (the default) selects <see cref="McpCatalogMode.ReadOnly"/> — only read-only tools (e.g.
     /// <c>get_context</c> + the git reads) are served, so a default run still reaches the safe read tools without
-    /// exposing any side effect. Pure + internal so it's unit-pinned.
+    /// exposing any side effect. An opted-in run whose write scope is not <see cref="AgentWriteScope.Workspace"/> — an
+    /// author's <c>readOnly</c>, a Confined tier, or a scope this code does not know, read as read-only like
+    /// <see cref="ApplyWriteScope"/> reads it — is served <see cref="McpCatalogMode.NonDestructive"/>: "analysis-only (no
+    /// writes)" must hold for the tools it is handed, not only for its own sandbox, yet it keeps every tool that does not
+    /// write, the ask (<c>decision.request</c>) among them. Pure + internal so it's unit-pinned.
     /// </summary>
-    internal static McpCatalogMode ResolveMcpCatalogMode(AgentTask task) => UsesFullToolCatalog(task) ? McpCatalogMode.Full : McpCatalogMode.ReadOnly;
+    internal static McpCatalogMode ResolveMcpCatalogMode(AgentTask task)
+    {
+        if (!UsesFullToolCatalog(task)) return McpCatalogMode.ReadOnly;
+
+        return task.Permissions.WriteScope == AgentWriteScope.Workspace ? McpCatalogMode.Full : McpCatalogMode.NonDestructive;
+    }
 
     /// <summary>
     /// A BOOT diagnostic the worker host calls once at startup so a mis-configured tool fabric is VISIBLE at deploy time,
@@ -3672,9 +3681,13 @@ private static (string SocketPath, string Token) MintMcpConnect(Guid runId) =>
         // tools by default and the whole fabric only when the run opted in.
         var catalogMode = ResolveMcpCatalogMode(task);
 
+        // The repositories the admitted task bound the run to — the workspace it cloned — are the only ones its tool calls
+        // may name, stamped server-side here and never read from the model's arguments. A no-repository run binds none.
+        var repositories = RepositoryWorkspaceResolver.CanonicalWorkspace(task)?.Repositories ?? [];
+
         try
         {
-            return new AgentMcpEndpoint(runId, registry, autonomy, teamId, redactor, socketPath, token, connects, scope, ct, _logger, fenceEpoch, governanceEnabled, approvalConversationId, catalogMode, task.Permissions);
+            return new AgentMcpEndpoint(runId, registry, autonomy, teamId, redactor, socketPath, token, connects, scope, ct, _logger, fenceEpoch, governanceEnabled, approvalConversationId, catalogMode, task.Permissions, repositories);
         }
         // An over-length socket path throws ArgumentOutOfRangeException (UDS endpoint ctor); CreateDirectory can throw
         // IOException / UnauthorizedAccessException. The endpoint is optional infra, not the run, so any of these is a

backend/src/CodeSpace.Core/Services/Agents/Commands/RunCommandService.cs

@@ -44,7 +44,7 @@ public async Task<SandboxResult> RunAsync(RunCommandRequest request, Cancellatio
         // Repo-scoped → clone into a fresh per-run workspace the command runs in; ephemeral → no checkout.
         // The same runnerKind selects the matching workspace provider, so a future docker/k8s pair composes here.
         var workspace = request.RepositoryId is { } repositoryId
-            ? await _workspaces.Resolve(runnerKind).PrepareAsync(WorkspaceProvisionRequest.FromSingle(await BuildWorkspaceRequestAsync(repositoryId, request.Ref, request.TeamId, cancellationToken).ConfigureAwait(false)), cancellationToken).ConfigureAwait(false)
+            ? await _workspaces.Resolve(runnerKind).PrepareAsync(WorkspaceProvisionRequest.FromSingle(await BuildWorkspaceRequestAsync(repositoryId, request, cancellationToken).ConfigureAwait(false)), cancellationToken).ConfigureAwait(false)
             : null;
 
         try
@@ -161,14 +161,16 @@ private static SandboxSpec WithinCallerEgress(SandboxSpec spec, AgentPermissions
     /// token through the same provider auth layer the resolver uses, and reuse its provider→username table so
     /// there's one source of truth. A repo with no bound credential clones anonymously (public / local repo).
     /// </summary>
-    private async Task<WorkspaceRequest> BuildWorkspaceRequestAsync(Guid repositoryId, string? gitRef, Guid? teamId, CancellationToken cancellationToken)
+    private async Task<WorkspaceRequest> BuildWorkspaceRequestAsync(Guid repositoryId, RunCommandRequest request, CancellationToken cancellationToken)
     {
         // Fail-closed tenant scope: the repo is resolved ONLY within the run's team, so a model-supplied /
         // untrusted repositoryId can never clone another tenant's repo. No team context with a repo requested is
         // refused outright. A repo in another team falls out of the filter → the same non-leaking "not found".
-        if (teamId is not { } team)
+        if (request.TeamId is not { } team)
             throw new WorkspaceException("Cannot clone a repository without a team context for the run.");
 
+        var bound = CallerBinding(request.CallerPosture, repositoryId);
+
         var repo = await _db.Repository
             .Include(r => r.ProviderInstance)
             .Include(r => r.Credential)
@@ -178,17 +180,47 @@ private async Task<WorkspaceRequest> BuildWorkspaceRequestAsync(Guid repositoryI
         if (string.IsNullOrWhiteSpace(repo.CloneUrlHttps))
             throw new WorkspaceException($"Repository {repositoryId} has no HTTPS clone URL to clone from.");
 
+        EnsureRefWithinBinding(bound, request.Ref, repo);
+
         var token = await ResolveTokenAsync(repo, cancellationToken).ConfigureAwait(false);
 
         return new WorkspaceRequest
         {
             RepositoryUrl = repo.CloneUrlHttps,
-            Ref = string.IsNullOrWhiteSpace(gitRef) ? repo.DefaultBranch : gitRef,
+            Ref = string.IsNullOrWhiteSpace(request.Ref) ? repo.DefaultBranch : request.Ref,
             Token = token,
             TokenUsername = token is null ? null : RepositoryWorkspaceResolver.TokenUsernameFor(repo.ProviderInstance.Provider),
         };
     }
 
+    /// <summary>
+    /// The calling run's binding of the repository an agent's command names — null for a workflow node's command, which
+    /// has no calling run and resolves its authored repository within its team as before. A repository the run is not
+    /// bound to is refused with the same "not found" the tenant filter gives, before it is ever loaded.
+    /// </summary>
+    private static WorkspaceRepositorySpec? CallerBinding(AgentRunPosture? caller, Guid repositoryId)
+    {
+        if (caller is null) return null;
+
+        return AgentRepositoryBinding.Find(caller, repositoryId) ?? throw new WorkspaceException(AgentRepositoryBinding.NotFound(repositoryId));
+    }
+
+    /// <summary>
+    /// An agent's command checks out read-only context only at its bound branch or its default branch, so the tree it
+    /// builds and runs is the content the operator bound, never a branch the agent named (what the pin does and does not
+    /// cover is on <see cref="AgentRepositoryBinding"/>). A refusal rather than an approval card: the binding is the
+    /// operator's own narrowing, which a single approver's click should not widen mid-run, and the card cannot show the
+    /// ref it would be consenting to. The agent tool refuses it before the call is ever parked for approval too
+    /// (<c>NodeAgentTool</c>); this holds a caller that reaches the service directly. A writable repository, and a
+    /// workflow node's command (<paramref name="bound"/> null), take any ref.
+    /// </summary>
+    private static void EnsureRefWithinBinding(WorkspaceRepositorySpec? bound, string? requestedRef, Repository repo)
+    {
+        if (bound is null || AgentRepositoryBinding.AllowsRef(bound, requestedRef, repo.DefaultBranch)) return;
+
+        throw new WorkspaceException(AgentRepositoryBinding.RefOutsideBinding(repo.Id, bound, requestedRef, repo.DefaultBranch));
+    }
+
     private async Task<string?> ResolveTokenAsync(Repository repo, CancellationToken cancellationToken)
     {
         if (repo.Credential is null) return null;

backend/src/CodeSpace.Core/Services/Agents/Eval/Benchmark/BenchmarkRunner.cs

@@ -20,7 +20,7 @@ namespace CodeSpace.Core.Services.Agents.Eval.Benchmark;
 /// are GENUINELY differentiated within a SINGLE process: the runner stamps the per-run opt-in
 /// <c>AgentTask.EnableMcpEndpoint</c> from the mode, so the cli-mcp run opens the run-scoped MCP tool-fabric endpoint
 /// while the cli run does not — they execute observably differently, not merely under different scorecard labels. The
-/// resolved gate state (the SAME <c>AgentRunExecutor.UsesFullToolCatalog</c> the executor consults) is recorded on
+/// resolved gate state (the SAME <c>AgentRunExecutor.ResolveMcpCatalogMode</c> the executor consults) is recorded on
 /// <see cref="BenchmarkResult.McpFullCatalog"/>, so a row can never be mislabeled relative to what the executor did.
 /// <see cref="BenchmarkMode.WorkflowMap"/> is RESERVED, not wired in this slice: it would run through the composed
 /// planner→<c>flow.map</c>→synthesizer ENGINE path (a workflow, not a single agent run), which this single-run runner
@@ -67,9 +67,10 @@ public async Task<BenchmarkResult> RunAsync(BenchmarkTask task, BenchmarkMode mo
 
         var agentTask = BuildAgentTask(task, mode, workspaceDirectory, selection);
 
-        // The SAME gate the executor will consult to decide whether to open the run's MCP endpoint — recorded on the
-        // result so the cli vs cli-mcp rows can never be mislabeled relative to what the run actually did.
-        var mcpFullCatalog = AgentRunExecutor.UsesFullToolCatalog(agentTask);
+        // The SAME gate the executor will consult to decide which slice of the catalog the run's MCP endpoint serves —
+        // recorded on the result so the cli vs cli-mcp rows can never be mislabeled relative to what the run actually did
+        // (a read-only cell is served only the tools that do not write, even when its mode opts into the fabric).
+        var mcpFullCatalog = AgentRunExecutor.ResolveMcpCatalogMode(agentTask) == McpCatalogMode.Full;
 
         var attempts = await RunWithFormatFaultRespawnAsync(task, agentTask, context, cancellationToken).ConfigureAwait(false);
 

backend/src/CodeSpace.Core/Services/Agents/Mcp/AgentMcpEndpoint.cs

@@ -17,7 +17,7 @@ namespace CodeSpace.Core.Services.Agents.Mcp;
 /// One run's live MCP endpoint over a PER-RUN Unix-domain socket: it binds + listens on the run's socket path, accepts
 /// connections in a loop, and for each connection validates the per-run <c>CODESPACE_RUN_TOKEN</c> on the FIRST line
 /// before serving — then pumps one <see cref="McpFramingLoop"/> (a fresh <see cref="McpRequestHandler"/> bound to the
-/// run's tool registry + autonomy + permissions + team + secret redactor) over the socket's <see cref="NetworkStream"/>. Every
+/// run's tool registry + autonomy + permissions + bound repositories + team + secret redactor) over the socket's <see cref="NetworkStream"/>. Every
 /// tool-result text the handler returns is run through the run's <see cref="SecretRedactor"/>, so an echoed model key
 /// never reaches the model. The connect descriptor
 /// (socket path + token) is registered with the <see cref="IAgentMcpConnectRegistry"/> under the run id so a consumer
@@ -49,6 +49,7 @@ public sealed class AgentMcpEndpoint : IAsyncDisposable
     private readonly Guid? _approvalConversationId;
     private readonly McpCatalogMode _catalogMode;
     private readonly AgentPermissions? _permissions;
+    private readonly IReadOnlyList<WorkspaceRepositorySpec>? _repositories;
     private readonly ILogger _logger;
     private readonly CancellationTokenSource _cts;
     private readonly Socket _listener;
@@ -57,7 +58,7 @@ public sealed class AgentMcpEndpoint : IAsyncDisposable
 
     private bool _disposed;
 
-    public AgentMcpEndpoint(Guid runId, IAgentToolRegistry registry, AgentAutonomyLevel autonomy, Guid teamId, SecretRedactor redactor, string socketPath, string token, IAgentMcpConnectRegistry connects, IServiceScope scope, CancellationToken ct, ILogger logger, long fenceEpoch = 0, bool governanceEnabled = false, Guid? approvalConversationId = null, McpCatalogMode catalogMode = McpCatalogMode.Full, AgentPermissions? permissions = null)
+    public AgentMcpEndpoint(Guid runId, IAgentToolRegistry registry, AgentAutonomyLevel autonomy, Guid teamId, SecretRedactor redactor, string socketPath, string token, IAgentMcpConnectRegistry connects, IServiceScope scope, CancellationToken ct, ILogger logger, long fenceEpoch = 0, bool governanceEnabled = false, Guid? approvalConversationId = null, McpCatalogMode catalogMode = McpCatalogMode.Full, AgentPermissions? permissions = null, IReadOnlyList<WorkspaceRepositorySpec>? repositories = null)
     {
         _runId = runId;
         _registry = registry;
@@ -73,6 +74,7 @@ public AgentMcpEndpoint(Guid runId, IAgentToolRegistry registry, AgentAutonomyLe
         _approvalConversationId = approvalConversationId;
         _catalogMode = catalogMode;
         _permissions = permissions;
+        _repositories = repositories;
         _logger = logger;
         _cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
         _counters = new McpFabricCounters();
@@ -102,11 +104,11 @@ public AgentMcpEndpoint(Guid runId, IAgentToolRegistry registry, AgentAutonomyLe
     /// with a restricted author tool list still reaches the governed codespace tools the open endpoint serves. Computed
     /// from the SAME registry + autonomy this endpoint serves with (and the SAME server name the handler advertises), so
     /// the allow-list and the endpoint gate agree by construction. A tool the tier is Denied is omitted (never offered a
-    /// name it would be refused). In ReadOnly catalog mode only read-only tools are projected — the SAME slice the
-    /// handler lists + serves, so the allow-list never names a tool this run's mode would refuse.
+    /// name it would be refused). Only the catalog mode's slice is projected (<see cref="McpRequestHandler.Serves(McpCatalogMode, IAgentTool)"/>)
+    /// — the SAME slice the handler lists + serves, so the allow-list never names a tool this run's mode would refuse.
     /// </summary>
     public IReadOnlyList<string> AllowedToolNames() =>
-        McpAllowedTools.QualifiedNames(_registry.All.Where(t => _catalogMode == McpCatalogMode.Full || t.IsReadOnly), _autonomy, McpRequestHandler.ServerName).ToArray();
+        McpAllowedTools.QualifiedNames(_registry.All.Where(t => McpRequestHandler.Serves(_catalogMode, t)), _autonomy, McpRequestHandler.ServerName).ToArray();
 
     /// <summary>P0-B2: an authenticated client served the MCP <c>initialize</c> handshake at least once on this endpoint.</summary>
     public bool HandshakeObserved => _counters.Handshakes > 0;
@@ -189,7 +191,7 @@ private async Task ServeConnectionAsync(Socket conn, CancellationToken ct)
 
         var authorityContext = new McpAuthorityContext(_runId, _teamId, connectionScope.ServiceProvider.GetRequiredService<IAgentAuthorityCallGuard>(), _counters);
         var authorizedRegistry = new AuthorityCheckedToolRegistry(_registry, authorityContext);
-        var protocol = new McpRequestHandler(authorizedRegistry, _autonomy, _teamId, _redactor, _runId, ledger, _fenceEpoch, _governanceEnabled, _approvalConversationId, bot, waiters, components, _catalogMode, _counters, _logger, _permissions);
+        var protocol = new McpRequestHandler(authorizedRegistry, _autonomy, _teamId, _redactor, _runId, ledger, _fenceEpoch, _governanceEnabled, _approvalConversationId, bot, waiters, components, _catalogMode, _counters, _logger, _permissions, _repositories);
 
         var handler = new AuthorizedMcpRequestHandler(protocol, authorityContext);