Skip to content

AIFACTORY-FEAT-029: ToolAdapterService: complete delivery

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Tools & MCP Platform (PF-05) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 68 of 185 (Factory code)

ToolAdapterService is the service of bounded context BC-08 (Tool Execution). The one path for every tool call (GW-05): descriptor validation, permission and policy, class raised by the environment, approval binding for gated classes, brokered credentials and sandbox, execution of native, MCP or shell tools, sanitized results, receipts and audit; unconfirmed effects settle as Uncertain (BC-08). Its own repository is ConnectSoft.AI.SoftwareFactory.ToolAdapterService.

Delivers ToolAdapterService (complete)
Stubs —
Realizes adrs: ADR-0014, ADR-0015, ADR-0021, ADR-0022
Requirements FR-05, FR-06, FR-10, FUX-05, FUX-07, NFR-02, NFR-04, NFR-05, NFR-10, XL-03, XL-06, XL-10, XL-16
Depends on —
Sources model/services/tools-mcp/ToolAdapterService.yaml

Scenarios to trace (16, catalog): SCN-ToolAdapterService-001 ✓, SCN-ToolAdapterService-002 ✓, SCN-ToolAdapterService-003 ✓, SCN-ToolAdapterService-004 ✓, SCN-ToolAdapterService-005 ✓, SCN-ToolAdapterService-006 ✓, SCN-ToolAdapterService-007 ✓, SCN-ToolAdapterService-008 ✓, SCN-ToolAdapterService-009 ✓, SCN-ToolAdapterService-010 ✓, SCN-ToolAdapterService-011 ✓, SCN-ToolAdapterService-012 ✓, SCN-ToolAdapterService-013 ✓, SCN-ToolAdapterService-014 ✓, SCN-ToolAdapterService-015 ✓, SCN-ToolAdapterService-016 ✓

AIFACTORY-US-014: Tools run in a sandbox under policy

behavior · persona operator As an operator, I want every write, shell and build tool an agent calls to run inside a leased sandbox after a policy decision, so that generated code is built and tested without touching anything outside the run.

This is the integration PBI of the governed tool executor. Every tool call of the Factory passes ToolAdapterService (ADR-0022 decision 2, GW-05). In I1 every call it serves is bound to a run, a step and an attempt; IDE clients and partner agents arrive with the complete McpServerRegistryService in I5 (D121). An agent host of the Agent Mesh sends the call with the Factory tool client of the pinned AI libraries (feature component-extensions-ai) through the gateway ToolExecutorHost to ToolAdapterService/ToolExecutor.Invoke, under a workload token and with the fencing token of its lease. The pipeline order is fixed and no stage is skipped: schema validation, agent permission, tenant policy, side-effect classification, approval where the policy decision asks for one, credential broker, sandbox, execution, result sanitization, audit. In the first outcome the nine agents of the chain read the workspace of their run, write files, build and test in a leased sandbox, validate and submit blueprint versions and propose one change set. The workspace of a run belongs to ExecutionCapacityService, which feature execution-capacity-service-thin delivers: that service creates it with the first lease of the run, keeps it between leases and removes it on a terminal run event, and the executor mounts it by lease and neither stores nor removes it (D121). Two tools of the chain are of class shared-write. blueprint-submit-version is called by four of the six definitions of the chain and stores a Draft version, which is autonomous by default and gated only where the project policy says so (ADR-0026 amendment D64). propose-change-set executes only with an approval that RunControlService owns, unless the project policy allows autonomous proposals. Whether a call needs an approval is therefore read from the outcome of the policy decision and never from the class alone (AIFACTORY-US-604). The owner confirmed this reading and the invariant of ToolInvocation states it: an approval is needed only when Policy.Decide answers allow-with-approval, allow executes without one, deny ends the invocation Denied, allow-with-constraints executes with the constraints applied, a constraint that cannot be applied denies the call, and decision D64 stays (D121). The rule is the only gate for every side-effect class, shared-write, production, publication, external and spend alike, and the default policy bundle that answers allow-with-approval for production, publication, external and spend calls belongs to PolicyEngineService (D123). The feature is delivered by thirteen further PBIs: the seeded descriptors of the sixteen tools the chain names (AIFACTORY-US-598), the descriptor read model with activation and retirement (AIFACTORY-US-599), descriptor health and availability (AIFACTORY-US-600), validation and dry run (AIFACTORY-US-601), the pipeline of a call up to its receipt (AIFACTORY-US-602), denials (AIFACTORY-US-603), gated calls and their approval binding (AIFACTORY-US-604), sandbox leases and brokered credentials (AIFACTORY-US-605), the executors of native and shell tools (AIFACTORY-US-606), MCP tools and the hosted MCP endpoint (AIFACTORY-US-607), interruption and uncertain effects (AIFACTORY-US-608), the finding of the Operator on an uncertain effect, which RunControlService records in the same act as the decision of the Operator (AIFACTORY-US-609) and the receipts of a run (AIFACTORY-US-610). The repository ConnectSoft.AI.SoftwareFactory.ToolAdapterService is created and scaffolded in I0 by AIFACTORY-TASK-076 of feature repository-and-pipeline-conventions (D140) from the pinned base template package with UseFactoryProfile, and this feature starts from that scaffold, so token validation, the scope chain with its 401, 403 and 404 answers, the tenant row filter, health, readiness and the telemetry wiring come from the profile. The service owns tool-adapter-sql with the tables ToolDescriptors, ToolInvocations and SandboxLeases, serialises the pipeline of one invocation in its ToolInvocationGrain and writes its seven events in the run event envelope of the pinned contracts package through the Orleans outbox of the messaging profile tool-adapter, each in the transaction of the state change it announces. The delivery states its limits. The handler of DeletionOrderIssued is built in I4 with RetentionResidencyService and is not registered here. The thin AgentRegistryService of this increment publishes no release event, so descriptors come from the seed; the thin McpServerRegistryService holds no server, so no MCP call leaves a deployed instance and the MCP path is proven against a fixture server. Telemetry follows the Factory conventions: metrics carry tenant and project beside their modelled dimensions, activities and log records carry run, step and attempt, and no tool argument, tool output or credential reaches a metric, an activity or a log record; a hash or an artifact reference stands in its place (ADR-0019).

Acceptance criteria

AC1 Given the repository ConnectSoft.AI.SoftwareFactory.ToolAdapterService created and scaffolded in I0 by AIFACTORY-TASK-076 of feature repository-and-pipeline-conventions with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ToolAdapterService --UseFactoryProfile true from the pinned template package, when its pipeline runs, then the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/tools-mcp/ToolAdapterService.yaml).
AC2 Given an attempt of the chain that holds a lease and the seeded sandbox-class tool build-and-test, when its agent host calls ToolAdapterService/ToolExecutor.Invoke, then the decision is obtained through PolicyEngineService/Policy.Decide, a sandbox is leased through ExecutionCapacityService/Capacity.AcquireLease with ToolAdapterService/SandboxLeased written, the ToolAdapterService/ToolInvocation is recorded with its declared and its effective class and ends Observed with a receipt and ToolAdapterService/ToolInvoked, as AIFACTORY-US-602 and AIFACTORY-US-605 prove (FR-05).
AC3 Given a tool whose descriptor names a secret dependency, when it runs, then a short-lived credential is issued through SecretBrokerService/SecretBroker.Issue, is injected into the sandbox or the connector call and appears in no result, receipt, event, log record or reply to the agent (ADR-0022, docs/planes/capability-tools/tool-policies.md).
AC4 Given a read tool of the chain, when it runs, then it sees the workspace of its run only; given a call the policy denies, when it is refused, then ToolAdapterService/ToolInvocationDenied is written with the reason and the stage and the agent receives the refusal as the reply of ToolAdapterService/ToolExecutor.Invoke, as AIFACTORY-US-603 and AIFACTORY-US-606 prove (FR-05, ADR-0015).
AC5 Given invocations of two tenants and projects, when metrics, activities and log records are read, then the seven metrics of model/services/tools-mcp/ToolAdapterService.yaml are recorded with their modelled dimensions and with tenant and project, activities and log records carry run, step and attempt, and no record holds a tool argument, a tool output or a credential (ADR-0019, NFR-10).
Traces: services ToolAdapterService, ToolExecutorHost, PolicyEngineService, ExecutionCapacityService, SecretBrokerService, RepositoryIntelligenceService, McpServerRegistryService
Traces: aggregates ToolAdapterService/ToolInvocation, ToolAdapterService/ToolDescriptor, PolicyEngineService/PolicyDecision
Traces: apis ToolAdapterService/ToolExecutor.Invoke, PolicyEngineService/Policy.Decide, ExecutionCapacityService/Capacity.AcquireLease, SecretBrokerService/SecretBroker.Issue
Traces: events ToolAdapterService/ToolInvoked, ToolAdapterService/ToolInvocationDenied, ToolAdapterService/SandboxLeased
Traces: tools shell-sandbox, apply-patch, write-file, build-and-test, list-files, search-text, search-symbols, find-references, read-range, get-dependencies, get-git-diff, blueprint-submit-version, record-generated-output, propose-change-set
Traces: adrs ADR-0014, ADR-0015, ADR-0019, ADR-0022, ADR-0026, ADR-0028
Traces: requirements FR-05, NFR-02, NFR-10
Depends on AIFACTORY-US-598, AIFACTORY-US-599, AIFACTORY-US-600, AIFACTORY-US-601, AIFACTORY-US-602, AIFACTORY-US-603, AIFACTORY-US-604, AIFACTORY-US-605, AIFACTORY-US-606, AIFACTORY-US-607, AIFACTORY-US-608, AIFACTORY-US-609, AIFACTORY-US-610, feature:policy-engine-service, feature:execution-capacity-service-thin, feature:secret-broker-service, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:component-extensions-ai, feature:component-observability-factory-conventions
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/backlog/features/tools-mcp.yaml, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/architecture/adr/0026-requirements-to-ux-handoff.md, docs/architecture/adr/0019-data-governance.md, model/tools/blueprint-submit-version.yaml, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-077 Domain model: ToolDescriptor and ToolInvocation with its SandboxLease implementation The two aggregates and the SandboxLease entity carry the fields, the invariants and the sixteen transitions of InvocationState as model/services/tools-mcp/ToolAdapterService.yaml states them: the fixed pipeline order, the approval binding of a call only when the policy decision answers allow-with-approval, the denial of a call whose constraint cannot be applied (ConstraintNotApplicable), one execution per idempotency key, the Uncertain end of an unconfirmed effect, the two transitions out of Uncertain that a recorded finding causes (EffectConfirmedApplied to Observed, EffectConfirmedNotApplied to Failed, D121) and the sanitized result; the invocation carries the step id beside the run and the attempt; unit tests cover every invariant and every transition, and a transition the model does not list is refused. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-078 Persistence in tool-adapter-sql: ToolDescriptors, ToolInvocations and SandboxLeases migration Mappings and migrations for the three modelled tables with their tenant columns under the row filter, the nullable StepId column of ToolInvocations beside RunId and AttemptId (D121), the nullable EffectFinding column that keeps the finding ConfirmToolEffect recorded, so that a repeat with the same finding answers as the first and another finding answers 409 (D125), the unique index UX_Invocations_Scope_Idempotency on tenant, project and idempotency key, the indexes on run and attempt, on tenant and state, on active descriptors and on open leases; no column holds an argument, a result or a credential value, only hashes and artifact references; mapping tests run against an isolated test database, never a shared one. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-079 API hosting skeleton: REST and gRPC hosts, scope enforcement, problem responses and contract documents for the 6 REST and 3 gRPC operations implementation The six REST routes and the three gRPC methods of the model are hosted from the service descriptor with JWT validation, the scope of each route (factory.tools.read, factory.runs.read, factory.tools.operate), problem responses for every modelled refusal code, workload identity and service scope checks on ToolExecutor.Invoke, ToolExecutor.Validate and ToolExecutor.Interrupt, and the OpenAPI and proto documents. ConfirmToolEffect is hosted as an internal operation whose one caller is RunControlService and which admits no user token (D121). The proto fixes the request message of ToolExecutor.Invoke as the tool-invocation-v1 document, which carries the optional members fencingToken and toolVersion since D121, so no wrapping message exists; the tenant and the project of a workload call travel in the gRPC metadata. A contract test validates the request message against docs/reference/schemas/tool-invocation.schema.json and the receipt against tool-receipt-v1 with its six statuses, Cancelled among them, and holds both with golden files. The behaviour of each operation is delivered by AIFACTORY-US-599 to AIFACTORY-US-610, not here. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-080 Messaging skeleton: outbox and inbox wiring of the tool-adapter profile for 7 published and 9 consumed events implementation The outbox writer enlists in the transaction of the invocation and descriptor commands and the dispatcher of the tool-adapter messaging profile publishes the seven modelled events in the run event envelope of the pinned contracts package (ToolDescriptorActivated, ToolDescriptorRetired, ToolInvoked, ToolInvocationDenied, ToolEffectUncertain, SandboxLeased, SandboxReleased); the inbox registers nine of the ten consumed events of the model with idempotency on the event id, and DeletionOrderIssued is not registered, because its handler is built in I4 with RetentionResidencyService; what each handler does is delivered by AIFACTORY-US-599 and AIFACTORY-US-600. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-081 Worker and grain hosting skeleton: schedules, partitioning and retry policies of UncertainEffectReconciler, SandboxReaper and DescriptorHealthProbe, and the reminders of ToolInvocationGrain implementation The three workers are hosted with their modelled schedules, retry policies, partitioning and idempotency keys, and a duplicate trigger has no second effect; ToolInvocationGrain is registered as a non-reentrant grain keyed by invocationId with its timeout and credential-expiry reminders; what each worker and reminder does is delivered by AIFACTORY-US-600, AIFACTORY-US-605 and AIFACTORY-US-608. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-082 Security, tenancy and telemetry of ToolAdapterService implementation Scopes and roles of the model are enforced, every query is tenant-filtered, a resource of another tenant is answered 404 and NOT_FOUND, the secrets messaging-transport and mcp-signing-key come from their secret references, and the seven metrics of the model are recorded through the helper of the pinned observability packages with their modelled dimensions and with tenant and project; activities and log records carry run, step and attempt, and a conformance test fails when a tool argument, a tool output or a credential reaches a metric, an activity or a log record (ADR-0019). ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-791 Verify tools-in-a-sandbox by running the declared command verification Run dotnet test -c Release --filter Category=Acceptance in the pipeline of the repository; a run that discovers no test counts as a failure; it passes and proves AC1 to AC5 of AIFACTORY-US-014: the scaffold, one sandbox-class call of the chain from ToolAdapterService/ToolExecutor.Invoke to ToolAdapterService/ToolInvoked with its lease, a brokered credential that appears nowhere, a read tool bound to the workspace of its run, a denied call, and the telemetry conformance test over two tenants and projects. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-598: Register the seeded descriptors of the sixteen tools the first-outcome chain names

enabling · persona platform-admin As a platform admin, I want the descriptors of the tools of the first-outcome chain registered when the executor starts, so that an attempt can call its tools before tool releases are published through the registry.

A descriptor becomes active when the handler ActivateDescriptors projects a Published tool asset from AssetReleasePublished. The thin AgentRegistryService of this increment publishes no event: publication arrives with feature agent-registry-service-publication in I2 (D140). Until then the descriptors the first outcome needs are registered by a seed, the same way the thin registry seeds its Draft releases. The seed set holds one descriptor for each tool that the six workflow definitions of the chain and their nine agents name, sixteen tools of the catalogue under model/tools: knowledge-search, graph-query, list-files, search-text, search-symbols, find-references, read-range, get-dependencies, get-git-diff, write-file, build-and-test, blueprint-validate, blueprint-submit-version, get-approved-recipe, record-generated-output and propose-change-set. record-generated-output joined the set with decision D133, which binds it to the skill microservice-generator-record-outputs of the step record-outputs of generate-product. The catalogue states for each tool its kind, its side-effect class, its authentication, its limits (timeout, rate per minute, retries) and the fields its audit requires. It does not state a version, a release id, a risk class, a sandbox kind or the JSON schema of input and output, all of which a ToolDescriptor requires, so the seed entry states them, and who authors the sixteen descriptor documents is an open point reported to the owner together with the question the thin registry already records for its manifests. The loader reads the seed set from one configured location, the directory named by the configuration key Tools:Seed:Path, a key the model does not list and that stays until the tool assets are published through the publication path of AgentRegistryService, feature agent-registry-service-publication of I2 (D140). The directory holds one JSON file per tool with the descriptor document and its hash. A tool descriptor is also an element of the closure of the seeded agent releases, which the runtime verifies by hash, so the version and the hash of a seed entry must equal the closure entry of the agents that name the tool. When the service starts, the loader validates each entry: the side-effect class is one of the seven classes and equals the class of the catalogue, the schema is a valid JSON schema, a secret dependency is a reference and never a value. It then writes the descriptor through the same activation path as the handler, active and healthy, in the platform tenant, the tenant of ConnectSoft-published assets that every tenant reads, and ToolDescriptorActivated is written in the same transaction. The table requires ReleaseId; no tool release exists in the thin AgentRegistryService, whose seed holds workflow and agent releases only, so the loader stores the release id the descriptor document carries, and whether a tool is a release of its own before the publication path of I2 (D140) is part of the open point. The loader is idempotent: a descriptor whose tool id, version and hash are already registered is left as it is and no second event is written. An entry with a wrong hash, an unknown class or an invalid schema fails the loader with the entry named, and no partial descriptor stays registered for it. Readiness stays unready until every seed entry is registered, so the service never answers that a tool of the chain is inactive because its seed was not loaded; the loader is retried in the running process with backoff, without a restart, and liveness keeps answering meanwhile. The acceptance suite proves the loader on a fixture set in the same file shape.

Acceptance criteria

AC1 Given an empty tool-adapter-sql and the seed set of sixteen entries in the configured seed location, when the service starts, then ToolDescriptors holds sixteen active and healthy ToolAdapterService/ToolDescriptor rows in the platform tenant, each with its tool id, version, kind, side-effect class, schema reference, limits and audit requirements, and the side-effect class of each equals the class of its entry under model/tools (ADR-0022).
AC2 Given the seed registered for the first time, when the outbox is read, then one ToolAdapterService/ToolDescriptorActivated record per descriptor was written in the transaction that registered it; given the service starts again or two replicas start together, when the loader runs, then no row is duplicated or changed and no second event is written (model/services/tools-mcp/ToolAdapterService.yaml).
AC3 Given a seed entry whose hash does not match its document, whose side-effect class is not one of the seven classes or whose schema is not a valid JSON schema, when the loader runs, then it fails with the entry named, no partial ToolAdapterService/ToolDescriptor stays registered for that entry, readiness stays unready until every entry is registered and the loader is retried in the running process with backoff, so that readiness turns ready once the entry is corrected (docs/planes/capability-tools/tool-registry.md).
AC4 Given the seed registered, when the sixteen descriptors are compared with the closure entries of the seeded agent releases that name them, then the version and the hash of each descriptor equal those of the closure entry, so the runtime that verified the closure and the executor that validates the call hold the same descriptor (ADR-0021, model/backlog/pbis/control-plane/agent-registry-service-thin.yaml).
Traces: services ToolAdapterService
Traces: aggregates ToolAdapterService/ToolDescriptor
Traces: events ToolAdapterService/ToolDescriptorActivated
Traces: tools knowledge-search, graph-query, list-files, search-text, search-symbols, find-references, read-range, get-dependencies, get-git-diff, write-file, build-and-test, blueprint-validate, blueprint-submit-version, get-approved-recipe, record-generated-output, propose-change-set
Traces: adrs ADR-0021, ADR-0022
Depends on feature:component-base-template-factory-profile, feature:agent-registry-service-thin
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/tools/propose-change-set.yaml, model/tools/build-and-test.yaml, model/tools/record-generated-output.yaml, model/backlog/pbis/control-plane/agent-registry-service-thin.yaml, docs/planes/capability-tools/tool-registry.md#descriptor

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2407 Seed loader of the tool descriptors: sixteen descriptors of the chain registered through the activation path implementation At start the loader reads the seed set from the directory named by the configuration key Tools:Seed:Path, one JSON file per tool with the descriptor document and its hash, validates the class, the schema and the secret references of each entry, registers the descriptor active and healthy in the platform tenant through the same activation path as the ActivateDescriptors handler with its ToolDescriptorActivated outbox record in one transaction, is idempotent on tool id, version and hash across restarts and concurrent replicas, and fails with the entry named on a wrong hash, an unknown class or an invalid schema; a readiness check reports unready until every seed entry is registered and a failed run is retried in the running process with backoff. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2408 Seed set fixture of sixteen descriptor documents and of the broken entries for the acceptance suite fixture The acceptance suite holds a seed directory in the file shape of AIFACTORY-TASK-2407 with one descriptor document per tool the chain names, each with the kind, the side-effect class, the limits and the audit fields of its entry under model/tools and with a version, a release id, a risk class, a sandbox kind and a JSON schema, an entry with a wrong hash, an entry with an unknown class and an entry with an invalid schema. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2409 Verify the seed registration of the tool descriptors through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=SeededToolDescriptors"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-598: sixteen active descriptors whose classes equal model/tools, one ToolAdapterService/ToolDescriptorActivated record each, the idempotent restart, the refused broken entries with readiness unready until the retry succeeds, and the comparison of version and hash with the closure entries of the fixture agent releases. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-599: List and read tool descriptors and activate or retire them from the release and connector events

behavior · persona asset-maintainer As an asset maintainer, I want to see which tool versions are callable, with their class, limits and health, and to have a published or withdrawn release change that set, so that an agent can only call a tool version whose descriptor is active and whose class its owner declared.

A caller whose scope carries factory.tools.read lists the active tool descriptors through ToolAdapterService/ListTools and reads one through ToolAdapterService/GetTool; the user token is forwarded by ToolExecutorHost unchanged and the service takes the tenant from it. The list is paged and holds the descriptors visible to the caller, those of the tenant of the caller and those of the platform tenant, each with tool id, version, kind, side-effect class, risk class, the MCP server it is bound to when it has one, and its health. GetTool addresses a tool id and returns its active descriptor with the schema reference, the authorization the caller needs, the secret dependencies as references and never as values, timeout, retry policy, rate limits and audit requirements; when more than one version of the tool is active, the request names the version, and without it the highest active version is returned. A tool id that is unknown, inactive or owned by another tenant is answered 404, the same answer in the three cases (ADR-0015 amendment D113); a call without a token is answered 401 and a token without the scope 403. Nothing is written by a read. The set of descriptors changes through the inbox. ActivateDescriptors handles AssetReleasePublished: for a release of asset kind Tool it loads the manifest through AgentRegistryService/AssetPublication.LoadRelease, fetches the descriptor document by its content reference from ArtifactService, validates it and writes the ToolDescriptor active and healthy with ToolDescriptorActivated in the same transaction; a release of another kind is acknowledged and changes nothing. A descriptor whose side-effect class is missing or not one of the seven classes is not activated, because the class is declared by the tool owner at publication and the executor never lowers it. RetireDescriptors handles AssetReleaseRevoked by deactivating the descriptors of the release at once and AssetReleaseDeprecated by the in-flight policy the event states: under revoke the descriptors are deactivated at once. Each deactivation writes ToolDescriptorRetired with the reason in the same transaction, and a call to a retired descriptor is denied as AIFACTORY-US-603 states. Under the policies finish and drain a descriptor is to stay callable for the runs that already pinned the release; the model does not say how the executor tells such a run from a new one, nor what differs between the two policies for a tool descriptor, so this delivery keeps the descriptor active under them, records the stated policy, and reports the question to the owner. The handlers of ConnectorActivated and ConnectorDeprecated are registered and idempotent, but the two events carry the connector id, version and provider and the model names neither a field by which a descriptor names its connector nor an operation that returns the descriptors of a connector version; that is reported as well, and until it is decided the handlers acknowledge the event and change no descriptor. Every handler is idempotent on the event id. In this increment no release event is published, so the handlers are proven with events the suite publishes in the run event envelope, and the deployed set of descriptors is the seed of AIFACTORY-US-598.

Acceptance criteria

AC1 Given a caller with factory.tools.read and active descriptors in the tenant of the caller, in the platform tenant and in another tenant, when ToolAdapterService/ListTools is called, then the response is 200 with the descriptors of the first two only, each with tool id, version, kind, side-effect class, risk class, server and health, paged; a call without a token is answered 401 and a token without the scope 403, and nothing is written (SCN-ToolAdapterService-001, ADR-0015).
AC2 Given an active ToolAdapterService/ToolDescriptor, when ToolAdapterService/GetTool is called with its tool id, then the response is 200 with the schema reference, the authorization, the secret dependencies as references without a value, timeout, retry policy, rate limits and audit requirements; given a tool id that is unknown, inactive or owned by another tenant, then the response is 404 with a problem response, the same in the three cases, and no state changes (SCN-ToolAdapterService-002, ADR-0015).
AC3 Given AgentRegistryService/AssetReleasePublished for a release of asset kind Tool, when ActivateDescriptors handles it, then the manifest is loaded through AgentRegistryService/AssetPublication.LoadRelease, the descriptor is written active and healthy with its declared side-effect class and the ToolAdapterService/ToolDescriptorActivated outbox record is written in the same transaction; the event is then published on tool-execution.descriptors.v1.tool-descriptor-activated in the run event envelope with toolId, version, tenantId, sideEffectClass and kind, and a transport outage is retried with backoff without loss or duplicate under its event id (SCN-ToolAdapterService-010, ADR-0014).
AC4 Given AgentRegistryService/AssetReleaseRevoked, or AgentRegistryService/AssetReleaseDeprecated with the in-flight policy revoke, for the release of an active descriptor, when RetireDescriptors handles it, then the descriptor is inactive and the ToolAdapterService/ToolDescriptorRetired outbox record with toolId, version, tenantId and reason is written in the same transaction and published on tool-execution.descriptors.v1.tool-descriptor-retired with the same retry guarantee; under the policy finish or drain the descriptor stays active and the policy is recorded (SCN-ToolAdapterService-011, model/services/control-plane/AgentRegistryService.yaml).
AC5 Given any of the five consumed events redelivered with the same event id, a release event of another asset kind, or a descriptor document whose side-effect class is missing, when the handler runs, then the redelivery changes nothing and writes no second event, the other kind is acknowledged without a descriptor, and the classless document is not activated and the refusal is logged with the release id (SCN-ToolAdapterService-010, ADR-0022).
Traces: services ToolAdapterService, AgentRegistryService, ConnectorRegistryService
Traces: aggregates ToolAdapterService/ToolDescriptor
Traces: apis ToolAdapterService/ListTools, ToolAdapterService/GetTool, AgentRegistryService/AssetPublication.LoadRelease
Traces: events ToolAdapterService/ToolDescriptorActivated, ToolAdapterService/ToolDescriptorRetired, AgentRegistryService/AssetReleasePublished, AgentRegistryService/AssetReleaseDeprecated, AgentRegistryService/AssetReleaseRevoked
Traces: adrs ADR-0014, ADR-0015, ADR-0022
Traces: requirements FR-05, NFR-02
Traces: scenarios SCN-ToolAdapterService-001, SCN-ToolAdapterService-002, SCN-ToolAdapterService-010, SCN-ToolAdapterService-011
Depends on AIFACTORY-US-598, feature:agent-registry-service-thin, feature:artifact-service, feature:contracts-package
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/control-plane/AgentRegistryService.yaml, model/services/integration/ConnectorRegistryService.yaml, docs/planes/capability-tools/tool-registry.md#descriptor, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2410 ListTools and GetTool read model over the descriptors of the tenant and of the platform tenant implementation ListTools returns the active descriptors of the tenant of the caller and of the platform tenant paged, with tool id, version, kind, side-effect class, risk class, server and health; GetTool returns the active descriptor of a tool id, the named version or the highest active one, with schema reference, authorization, secret dependencies as references, limits and audit requirements, and answers 404 alike for an unknown, an inactive and a foreign tool id (ADR-0015); both answer 401 and 403 through the policies of the Factory profile and write nothing. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2411 ActivateDescriptors and RetireDescriptors inbox handlers of the release and connector events implementation The handler of AssetReleasePublished loads the manifest of a Tool release through AssetPublication.LoadRelease, fetches and validates the descriptor document and writes the descriptor with its ToolDescriptorActivated outbox record in one transaction; the handlers of AssetReleaseRevoked and AssetReleaseDeprecated deactivate at once on a revocation and under the in-flight policy revoke, write ToolDescriptorRetired with the reason, and keep the descriptor active with the policy recorded under finish and drain; the handlers of ConnectorActivated and ConnectorDeprecated acknowledge the event and change no descriptor until the owner states how a descriptor names its connector; every handler is idempotent on the event id. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2412 Verify the descriptor read model and its handlers through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolAdapterService-001\|Scenario=SCN-ToolAdapterService-002\|Scenario=SCN-ToolAdapterService-010\|Scenario=SCN-ToolAdapterService-011)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-599 with a three-tenant fixture, release events the suite publishes in the run event envelope, a fake of AgentRegistryService and of ArtifactService, redelivered events and a stopped transport; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-600: Keep descriptors healthy or unhealthy from the probe and from the server, secret, connection and environment events

behavior · persona operator As an operator, I want a tool whose server, credential reference, connection or target environment is not usable to stop being called before it fails inside a run, so that a run fails fast with a reason I can act on, never halfway through an effect.

A descriptor is usable only while it is active and healthy. This PBI delivers what keeps that state true between calls. The worker DescriptorHealthProbe runs every five minutes over the active descriptors, partitioned by kind with at most four in parallel: for a native tool it checks that the executor of the tool answers, which for a tool owned by another service is the health of that service, and for a tool of kind Mcp it performs the handshake and the schema fetch through the client of the pinned MCP library and compares the schema hash. It marks the descriptor healthy or unhealthy, retries a failed probe twice with a fixed backoff of fifteen seconds, is idempotent on tool id, version and probe window, and publishes no event. A call to an unhealthy descriptor fails fast with the failure class transient and executes nothing (AIFACTORY-US-602). Four inbox handlers act on what other services announce, each idempotent on the event id. UpdateServerHealth handles McpServerStateChanged: the descriptors bound to a server that became Degraded are marked unhealthy, those of a server that became Active again healthy, and those of a Retired server unhealthy and inactive, with ToolDescriptorRetired written for each in the same transaction. DisableToolsOnRevocation handles SecretReferenceRevoked: from then on a call of that tenant to a tool whose secretDependencies name the revoked reference is denied before any credential is requested. UpdateConnectionAvailability handles ConnectionStateChanged: the tools of that tenant that are bound to the connection are refused while it is Suspended or Revoked and allowed again when it is Active. ApplyFreeze handles EnvironmentStateChanged: a call of class shared-write or production that targets a Frozen environment is refused, and the freeze ends when the environment is Active again. The model gives the service three tables and none for these three gates, so the announced state of a reference, a connection and an environment is kept in the cache store of the service. A lost cache entry never lets a refused call through: the class and the state of the target environment are read again through EnvironmentService/Environments.GetPolicyClass on every call, the Secret Broker issues nothing for a revoked reference, and a suspended connection does not resolve. How a Degraded connection is treated the model does not say, which is reported to the owner. The refusals themselves, with their stage and reason, are those of AIFACTORY-US-603. In this increment the thin McpServerRegistryService publishes no state change, so UpdateServerHealth is proven with events the suite publishes.

Acceptance criteria

AC1 Given active descriptors of the kinds Native and Mcp, when DescriptorHealthProbe runs and the executor of one native tool and the handshake of one MCP tool do not answer after two retries, then those two ToolAdapterService/ToolDescriptor rows are unhealthy and the others healthy, a second run in the same probe window changes nothing, and a later run in which both answer marks them healthy again (model/services/tools-mcp/ToolAdapterService.yaml).
AC2 Given descriptors bound to an MCP server, when McpServerRegistryService/McpServerStateChanged announces Degraded, then they are unhealthy; when it announces Active again, then they are healthy; when it announces Retired, then they are unhealthy and inactive and one ToolAdapterService/ToolDescriptorRetired outbox record per descriptor is written in the same transaction; a redelivery of the same event id changes nothing (ADR-0022).
AC3 Given SecretBrokerService/SecretReferenceRevoked for a reference of tenant A, when tenant A and tenant B each call a tool whose secretDependencies name a reference of that id, then the call of tenant A is denied before SecretBrokerService/SecretBroker.Issue is called and the call of tenant B is not affected; given IntegrationService/ConnectionStateChanged to Suspended or Revoked, then the tools of that tenant bound to the connection are refused, and after a change to Active they are allowed again (ADR-0015).
AC4 Given EnvironmentService/EnvironmentStateChanged announces an environment Frozen, when a call of effective class shared-write or production targets it, then the call is refused and a read or sandbox call that targets it is not; given the cache of the service was lost, when the same call arrives, then the state read through EnvironmentService/Environments.GetPolicyClass refuses it all the same; after the environment is Active again the call passes (model/services/control-plane/EnvironmentService.yaml).
Traces: services ToolAdapterService, McpServerRegistryService, SecretBrokerService, IntegrationService, EnvironmentService
Traces: aggregates ToolAdapterService/ToolDescriptor
Traces: apis EnvironmentService/Environments.GetPolicyClass, SecretBrokerService/SecretBroker.Issue
Traces: events ToolAdapterService/ToolDescriptorRetired, McpServerRegistryService/McpServerStateChanged, SecretBrokerService/SecretReferenceRevoked, IntegrationService/ConnectionStateChanged, EnvironmentService/EnvironmentStateChanged
Traces: adrs ADR-0015, ADR-0022
Traces: requirements XL-16, NFR-02
Depends on AIFACTORY-US-599, feature:mcp-server-registry-service-thin, feature:secret-broker-service, feature:integration-service-thin, feature:environment-service, feature:component-mcp
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/tools-mcp/McpServerRegistryService.yaml, model/services/control-plane/EnvironmentService.yaml, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#workers-and-jobs

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2413 DescriptorHealthProbe over the active descriptors of the kinds Native and Mcp implementation The worker probes every active descriptor on its five-minute schedule, partitioned by kind with at most four in parallel: the executor of a native tool, and the handshake and schema fetch of an MCP tool through the client of the pinned MCP library; it marks the descriptor healthy or unhealthy, retries twice with a fixed backoff of fifteen seconds, is idempotent on tool id, version and probe window and publishes no event. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2414 UpdateServerHealth, DisableToolsOnRevocation, UpdateConnectionAvailability and ApplyFreeze inbox handlers implementation The handler of McpServerStateChanged marks the descriptors of a Degraded server unhealthy, of an Active server healthy and of a Retired server unhealthy and inactive with ToolDescriptorRetired in the same transaction; the handlers of SecretReferenceRevoked, ConnectionStateChanged and EnvironmentStateChanged keep the announced state of the reference, the connection and the environment per tenant in the cache store of the service, from which the pipeline refuses the affected calls; each handler is idempotent on the event id, and a lost cache entry lets no refused call through because the environment state is read again on every call and the broker and the connection refuse on their own. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2415 Verify descriptor health and availability through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=DescriptorHealthAndAvailability"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-600 with a fake executor and a fixture MCP server that stop answering, the events McpServerRegistryService/McpServerStateChanged, SecretBrokerService/SecretReferenceRevoked, IntegrationService/ConnectionStateChanged and EnvironmentService/EnvironmentStateChanged published by the suite, redeliveries, a two-tenant fixture and a cleared cache. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-601: Validate the arguments of a tool call and preview its pipeline outcome without executing it

behavior · persona asset-maintainer As an asset maintainer, I want to see whether a call is valid and what the pipeline would do with it before anything runs, so that I learn the class, the policy outcome and the approval a tool needs without causing an effect.

Two operations answer what the pipeline would do with a call and execute nothing. A caller whose scope carries factory.tools.read posts arguments to ToolAdapterService/DryRunTool for a tool id; an agent host or another service calls the internal gRPC method ToolAdapterService/ToolExecutor.Validate with a tool-invocation-v1 request under a workload token that holds the service scope that names ToolAdapterService. Both run the first stages of the fixed pipeline as a preview. The arguments are validated against the JSON schema of the active descriptor, and every violation is reported with its path. The effective side-effect class is computed: it is the class the tool owner declared, raised to production when the call names a target environment whose class is Production, which the service reads through EnvironmentService/Environments.GetPolicyClass, and raised further when the policy says so; it is never lowered. The policy outcome is obtained through PolicyEngineService/Policy.Decide for the subject, the tool and the effective class under the active revision, which records its evaluation as it records every evaluation. The answer states whether the arguments are valid, the declared and the effective class, the policy outcome with its reason, whether an approval is needed and the sandbox kind the descriptor names. The need for an approval is read from the outcome of the decision, one of the four outcomes of policy-decision-v1, and from nothing else: allow-with-approval means that an approval is needed, allow that none is, deny that the call would be denied at the policy stage, and allow-with-constraints that the call would run without an approval under the constraints the decision lists, which the preview returns. The default policy bundle of PolicyEngineService answers allow-with-approval for the classes production, publication, external and spend (D123); of the two shared-write tools of the chain propose-change-set is answered allow-with-approval, and blueprint-submit-version for a Draft version is answered allow unless the project policy gates blueprint drafts, as ADR-0026 amendment D64 decides. Nothing else happens: no ToolInvocation is written, no idempotency key is consumed, no credential is issued, no sandbox is leased, no tool runs and no event of this service is published, so a dry run can be repeated at will. Invalid arguments are a result and not a refusal: the answer is 200, or a normal gRPC reply, with the violations. DryRunTool answers 401 without a token, 403 without the scope and 404 for a tool id that is unknown, inactive or owned by another tenant. ToolExecutor.Validate refuses a caller without a workload identity with UNAUTHENTICATED, a token without the service scope with PERMISSION_DENIED, a request that is no well-formed tool-invocation-v1 with INVALID_ARGUMENT and an unknown or foreign tool with NOT_FOUND, the same answer for both; an attempt that receives this NOT_FOUND takes the failure class permanent and is not retried (ADR-0015 amendment D113). PolicyEngineService and EnvironmentService are fail-fast dependencies: when one does not answer, the preview fails with a problem response or UNAVAILABLE that names the dependency, and no partial preview is returned. The model lists DryRunTool under the class sandbox although it runs nothing; the class is kept as modelled and reported.

Acceptance criteria

AC1 Given a caller with factory.tools.read and the active descriptor of a sandbox-class tool, when ToolAdapterService/DryRunTool is called with valid arguments, then the response is 200 with the arguments valid, the declared and the effective class, the policy outcome obtained through PolicyEngineService/Policy.Decide, no approval needed and the sandbox kind of the descriptor; no ToolAdapterService/ToolInvocation is written, no credential is issued, no sandbox is leased and no event of this service is published (SCN-ToolAdapterService-003).
AC2 Given arguments that violate the schema of the descriptor, a call that names an environment whose class EnvironmentService/Environments.GetPolicyClass returns as Production with a decision of allow-with-approval, the tool propose-change-set with a decision of allow-with-approval, and the tool blueprint-submit-version for a Draft version with a decision of allow, when ToolAdapterService/DryRunTool is called for each, then the first answers 200 with every violation and its path, the second states the effective class production and that an approval is needed, the third states that an approval is needed, and the fourth states the class shared-write and that no approval is needed; a decision of allow-with-constraints is previewed with its constraints and without an approval, and a decision of deny as a denial at the policy stage (SCN-ToolAdapterService-003, ADR-0022, ADR-0026).
AC3 Given a call without a token, a token without factory.tools.read, or a tool id that is unknown, inactive or owned by another tenant, when ToolAdapterService/DryRunTool is called, then the response is 401, 403 or 404 with a problem response, the 404 the same in the three cases, and no state changes (SCN-ToolAdapterService-003, ADR-0015).
AC4 Given a workload token that holds the service scope and a tool-invocation-v1 request, when ToolAdapterService/ToolExecutor.Validate is called, then the reply carries the same preview as the dry run and nothing is executed or written; a caller without a workload identity, a token without the service scope, a malformed request and an unknown or foreign tool are refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and NOT_FOUND respectively (SCN-ToolAdapterService-008, ADR-0015).
AC5 Given PolicyEngineService or EnvironmentService does not answer, when ToolAdapterService/DryRunTool or ToolAdapterService/ToolExecutor.Validate is called, then the call fails with a problem response or UNAVAILABLE that names the dependency and no partial preview is returned (SCN-ToolAdapterService-003, SCN-ToolAdapterService-008, model/services/tools-mcp/ToolAdapterService.yaml).
Traces: services ToolAdapterService, PolicyEngineService, EnvironmentService
Traces: aggregates ToolAdapterService/ToolDescriptor, ToolAdapterService/ToolInvocation
Traces: apis ToolAdapterService/DryRunTool, ToolAdapterService/ToolExecutor.Validate, PolicyEngineService/Policy.Decide, EnvironmentService/Environments.GetPolicyClass
Traces: descriptors tool-invocation-v1, policy-decision-v1
Traces: tools propose-change-set, blueprint-submit-version
Traces: adrs ADR-0015, ADR-0022, ADR-0026
Traces: requirements FR-05
Traces: scenarios SCN-ToolAdapterService-003, SCN-ToolAdapterService-008
Depends on AIFACTORY-US-599, feature:policy-engine-service, feature:environment-service
Sources model/services/tools-mcp/ToolAdapterService.yaml, docs/reference/schemas/tool-invocation.schema.json, docs/reference/schemas/policy-decision.schema.json, docs/planes/capability-tools/tool-policies.md#decision-outcomes

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2416 Pipeline preview shared by DryRunTool and ToolExecutor.Validate implementation One preview component validates the arguments against the schema of the active descriptor, computes the effective class from the declared class, the class of the target environment read through Environments.GetPolicyClass and the policy, obtains the policy outcome through Policy.Decide and states whether an approval is needed, which it reads from the outcome alone (allow-with-approval needs one, allow needs none, deny is a denial at the policy stage, allow-with-constraints needs none and lists its constraints), and which sandbox kind applies; DryRunTool and ToolExecutor.Validate return it with their refusals (401, 403 and 404, or UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and NOT_FOUND) and write no invocation, issue no credential, lease no sandbox and publish no event. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2417 Verify validation and dry run through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolAdapterService-003\|Scenario=SCN-ToolAdapterService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-601 with fakes of PolicyEngineService and EnvironmentService that answer each of the four outcomes of policy-decision-v1 and that stop answering, with propose-change-set under allow-with-approval and blueprint-submit-version for a Draft version under allow among the cases, and assert after every case that the tables ToolInvocations and SandboxLeases and the outbox are unchanged. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-602: Execute a tool call for an attempt through the fixed pipeline, once per idempotency key, and end it with a receipt

behavior · persona requester As a requester, I want every tool call of my run to pass one governed pipeline and leave a receipt, so that what an agent did on my behalf is decided by policy, done once and recorded with its hashes.

An agent host calls ToolAdapterService/ToolExecutor.Invoke through ToolExecutorHost. The request message of the method, fixed by the proto of AIFACTORY-TASK-079, is a tool-invocation-v1 document. The document holds what its schema allows: the invocation id, the tool id, the scope, the run, the step and the attempt, the class of the step, the idempotency key, the arguments with their hash, the policy decision the runtime obtained for the step and, where the policy decision of the call answers allow-with-approval, the approval id. Since D121 the schema also has two optional members, fencingToken, the fencing token of the lease of the attempt that makes the call, and toolVersion, the exact version of the tool the call names, so both travel inside the document and ToolInvocations stores them from it. The Factory tool client sends both for every call of an attempt; the fencing check applies to every call that carries a token, and a call that names no version is recorded with the highest active version of the tool, the version GetTool returns by default. The caller presents a workload token; the service reads the tenant and the project the caller forwards in the gRPC metadata only when the token holds the service scope that names ToolAdapterService (ADR-0015 amendment D114). The model also lists the scope factory.tools.invoke for attempts; this delivery admits an attempt by the service scope alone and requires factory.tools.invoke of the callers of the hosted MCP endpoint (AIFACTORY-US-607), and how the two scopes relate for a workload token is reported to the owner. The method is a server stream: it sends progress messages for a long tool and ends with the receipt. The ToolInvocationGrain of the invocation serialises the pipeline. Reception records the ToolInvocation in state Received with its scope, its run, step and attempt, its caller kind, which in I1 is always agent because only calls bound to a run, a step and an attempt are served (D121), its tool version, request hash, idempotency key and declared class. The unique index on tenant, project and idempotency key makes a call happen once: the same key with the same request hash returns the existing receipt and executes nothing, and the same key with another request hash is refused as a conflict with ALREADY_EXISTS (ADR-0014 decision 3). The fencing check is keyed by tenant, run and step, because the document carries stepId and RunControlService gives a new lease of a step a token greater than every earlier token of that step: a call whose fencing token is lower than the highest token the service has seen for its run and step is refused with FAILED_PRECONDITION, whether it arrives late from the same attempt or from a superseded attempt whose lease expired and whose step was dispatched again under a new attempt id. ToolInvocations stores the step id of every call (D121), so the mark per run and step is read back from the table as the highest token stored for the tenant, the run and the step; the cache store of the service only spares that read, and a lost cache entry loses nothing. The mark knows only tokens it has seen, so a superseded attempt that calls before its successor has called passes it. Closing that gap, and refusing a call for a run that is cancelled or terminal, needs the run and lease state of RunControlService, which the model names as a purpose of that dependency. The delivery reads it through the same client port as the approval of AIFACTORY-US-604: a call for a run the port reports as Cancelled or otherwise terminal, or for a step whose current fencing token the port reports as higher than that of the call, is refused with FAILED_PRECONDITION and records no invocation. The only internal read the model lists for a worker is the stream RunControl.WatchRun, which is not stated to return the current lease of a step or the state of a run at the moment of a call, so the port is proven against a fake and the missing operation is reported with the approval read of AIFACTORY-US-604. The arguments are validated against the schema of the active descriptor and the invocation moves to Validated (trigger SchemaValid). The service then checks the authorization the descriptor requires of the caller, reads the class of the target environment through EnvironmentService/Environments.GetPolicyClass and obtains its own decision through PolicyEngineService/Policy.Decide for the subject, the tool, the class and the environment under the policy revision the run pinned. The policyDecision the document must carry is the decision the runtime obtained for the step: the executor takes the pinned policy revision from it, never executes on it and never lets it replace its own decision; a carried decision whose subject names another tenant than the forwarded one is refused with INVALID_ARGUMENT, and whether the carried decision is meant to be more than this input is reported to the owner. The effective class is the declared class raised by the class of the target environment or by the policy and never lowered; the invocation moves to Authorized (trigger PermissionAndPolicyPassed) with policyDecisionId and effectiveClass. The outcome of the decision, one of the four of policy-decision-v1, steers the rest. deny denies the call (AIFACTORY-US-603). allow-with-approval gates it (AIFACTORY-US-604). allow lets it proceed without an approval, which under the default policy is the case for the classes read and sandbox and for blueprint-submit-version on a Draft version (ADR-0026 amendment D64). allow-with-constraints lets it proceed without an approval under the constraints the decision lists: a constraint that narrows the egress allow list or a limit of the sandbox is applied by the broker stage (AIFACTORY-US-605), the constraints that were applied are part of the limits recorded on the SandboxLease, and a constraint the executor cannot apply denies the call, which moves from Authorized to Denied (trigger ConstraintNotApplicable) at the stage policy, because a decision is never executed more widely than it was given (D121); the vocabulary of constraints is not modelled and is reported to the owner. A call that needs no approval has its credentials and its sandbox brokered as AIFACTORY-US-605 states and the invocation moves to Brokered (trigger CredentialsAndSandboxLeased), then to Executing (trigger Started) when the executor of its kind starts (AIFACTORY-US-606, AIFACTORY-US-607). When the result is observed it is sanitized before it can reach a model: secrets are stripped by the sanitizer patterns and the redaction is recorded in the audit evidence, the size is bounded by Tools:Execution:MaxResultBytes with a truncation marker, the provenance is tagged as a tool result and instructions inside the result stay data. The sanitized result and the receipt, a tool-receipt-v1, are stored by hash through ArtifactService/Artifacts.Store; the invocation moves to Observed (trigger ResultObserved) with resultRef, resultHash, receiptRef and auditRef, and ToolInvoked is written in the same transaction with the state, the hashes, the decision id and the approval id. The status of a receipt is one of the six values tool-receipt-v1 allows, and the states of an invocation map onto them by one rule that every PBI of the feature uses: Observed is written as Succeeded, Denied as Denied, Uncertain as Uncertain, Cancelled as Cancelled, the status of an invocation that was interrupted before any effect (D121), and Failed as Failed, except that an invocation the timeout reminder settled as Failed without a possible effect is written as TimedOut. An error before any effect moves the invocation to Failed (trigger ErrorBeforeEffect) with its failure class, a receipt and ToolInvoked in state Failed; the executor repeats an execution on its own only within the retry policy of the descriptor, only for an effective class of read or sandbox and only for a transient error before an effect. It never repeats a call of class shared-write or above: its outcome is reported as it is, and whether the step is retried is decided by RunControlService (ADR-0014 amendment D114). The audit stage writes one evidence record of the invocation through the sink of the pinned audit library, as the event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in the transaction of the receipt, with the invocation as subject, its request hash, the actor and the outcome and without arguments or result; the action values of audit-evidence-v1 name none for a tool invocation, which is reported to the owner. A call to an unhealthy descriptor and a required dependency that does not answer before execution (PolicyEngineService, EnvironmentService, RunControlService, SecretBrokerService, ExecutionCapacityService, McpServerRegistryService or ArtifactService) fail the call fast with UNAVAILABLE, the dependency named and the failure class transient, and nothing executes: without a decision no tool runs. The model has no transition to Failed before Executing, so which state the invocation keeps in that case is reported to the owner; the suite asserts that nothing executed and that a repeat under the same key after recovery executes once. A call above the rate limit of its descriptor is refused with RESOURCE_EXHAUSTED before reception. connectsoft.factory.tools.invocations counts every settled invocation by tool, effective class and state and connectsoft.factory.tools.latency records pipeline and execution time; the objective of the model for the pipeline overhead without execution and approval wait is 300 milliseconds at the 95th percentile, and a receipt exists for every settled invocation past validation; AIFACTORY-TASK-2420 measures the first from connectsoft.factory.tools.latency and asserts the second on receiptRef.

Acceptance criteria

AC1 Given an attempt with a lease, a workload token that holds the service scope and an active read-class tool, when ToolAdapterService/ToolExecutor.Invoke is called with a tool-invocation-v1 document that carries its optional members fencingToken and toolVersion, then the document validates against docs/reference/schemas/tool-invocation.schema.json, the ToolAdapterService/ToolInvocation is recorded with the run, the step and the attempt of the call and moves Received, Validated, Authorized, Brokered, Executing and Observed in that order with policyDecisionId from the own call to PolicyEngineService/Policy.Decide under the policy revision of the carried decision and with its declared and effective class, the stream ends with a receipt of status Succeeded, and the result and the tool-receipt-v1 are stored through ArtifactService/Artifacts.Store with resultRef, resultHash and receiptRef on the row (SCN-ToolAdapterService-007, FR-05).
AC2 Given the same call repeated with the same idempotency key and request hash, the same key with another request hash, a call under a fencing token lower than the highest seen for its run and step, once from the same attempt and once from a superseded attempt of the step whose successor already called, and a call for a run that the Run Control port reports as Cancelled, when ToolAdapterService/ToolExecutor.Invoke is called, then the first returns the existing receipt and executes nothing, the second is refused with ALREADY_EXISTS and the other three with FAILED_PRECONDITION; a caller without a workload identity, a token without the service scope and a malformed request are refused with UNAUTHENTICATED, PERMISSION_DENIED and INVALID_ARGUMENT, and no state changes in any refusal (SCN-ToolAdapterService-007, ADR-0014, ADR-0015).
AC3 Given a result that contains a secret pattern and exceeds Tools:Execution:MaxResultBytes, when the invocation is observed, then the stored result has the secret redacted and is truncated with a marker, the receipt states sanitized true, the redaction is named in the evidence record, and one AuditEvidenceSubmitted record of the invocation is in the outbox of the receipt transaction without arguments or result, as docs/reference/schemas/audit-evidence.schema.json shapes it (SCN-ToolAdapterService-007, ADR-0019).
AC4 Given an invocation that ended Observed, Failed or Cancelled, when the outbox dispatcher publishes ToolAdapterService/ToolInvoked on tool-execution.invocations.v1.tool-invoked, then the outbox record was written in the same transaction as the terminal transition, the receipt of the invocation carries the status Succeeded, Failed, TimedOut or Cancelled by the mapping of this PBI, the event is sent in the run event envelope with invocationId, tenantId, projectId, runId, attemptId, toolId, toolVersion, effectiveClass, state, policyDecisionId, approvalId, requestHash and resultHash, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ToolAdapterService-012, ADR-0014).
AC5 Given a transient error before any effect on a read-class tool whose descriptor allows two retries, an unhealthy descriptor, and a PolicyEngineService that does not answer, when ToolAdapterService/ToolExecutor.Invoke is called for each, then the first is repeated within the retry policy and, when it still fails, ends Failed with the failure class transient and ToolAdapterService/ToolInvoked in state Failed, and the other two fail fast with UNAVAILABLE and the class transient while nothing executes; a repeat under the same key after recovery executes once (SCN-ToolAdapterService-007, model/services/tools-mcp/ToolAdapterService.yaml).
Traces: services ToolAdapterService, PolicyEngineService, EnvironmentService, ArtifactService, RunControlService
Traces: aggregates ToolAdapterService/ToolInvocation, ToolAdapterService/ToolDescriptor
Traces: apis ToolAdapterService/ToolExecutor.Invoke, PolicyEngineService/Policy.Decide, EnvironmentService/Environments.GetPolicyClass, ArtifactService/Artifacts.Store
Traces: events ToolAdapterService/ToolInvoked
Traces: descriptors tool-invocation-v1, tool-receipt-v1, policy-decision-v1, audit-evidence-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0019, ADR-0022
Traces: requirements FR-05, NFR-05, XL-06
Traces: scenarios SCN-ToolAdapterService-007, SCN-ToolAdapterService-012
Relates: nfrs NFR-10
Depends on AIFACTORY-US-599, feature:policy-engine-service, feature:environment-service, feature:artifact-service, feature:run-control-service, feature:contracts-package, feature:component-audit-factory-evidence, feature:component-extensions-ai
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/control-plane/RunControlService.yaml, docs/reference/schemas/tool-invocation.schema.json, docs/reference/schemas/policy-decision.schema.json, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#sagas-and-long-running-flows

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-218 Tool invocation pipeline: receive, validate, decide, classify, broker, execute, sanitize, record implementation ToolExecutor.Invoke runs the fixed pipeline of the model in the ToolInvocationGrain: reception under the unique index on tenant, project and idempotency key, the fencing token check against the highest token seen for the tenant, run and step, read back from the step id that ToolInvocations stores (D121) and only cached in the cache store, the read of run and lease state through the Run Control port that refuses a call for a cancelled or terminal run and for a superseded lease with FAILED_PRECONDITION, schema validation, the authorization of the descriptor, the own decision of Policy.Decide under the policy revision of the carried decision, which is never executed on, the effective class from the declared class, the environment class and the policy, the branch on the four outcomes of policy-decision-v1 (deny, allow-with-approval, allow, allow-with-constraints with its constraints handed to the broker stage or the call denied through ConstraintNotApplicable when one cannot be applied), the hand-over to the broker stage of AIFACTORY-US-605 and to the executor of the kind, and the terminal transitions Observed and Failed with the receipt and the ToolInvoked outbox record in one transaction; the stream sends progress and ends with the receipt; one path serves every tool, and the class of the step and of the tool are enforced and never lowered. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2418 Result sanitizer, receipt writer and audit evidence of an invocation implementation The sanitizer strips secrets by its patterns, bounds the result by Tools:Execution:MaxResultBytes with a truncation marker, tags the provenance as tool result and never interprets instructions in a result; the receipt writer builds tool-receipt-v1 with effect, usage, the sanitized flag, the receipt hash and the status by the one mapping of the feature (Observed as Succeeded, Denied as Denied, Uncertain as Uncertain, Cancelled as Cancelled, Failed as Failed and a timeout without a possible effect as TimedOut) and stores result and receipt through Artifacts.Store; the audit stage writes one evidence record per receipt through the sink of the pinned audit library as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in the transaction of the receipt, with the redactions named and without arguments or result, and keeps its id in auditRef. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2419 Fakes of the pipeline dependencies and the invocation fixture of the acceptance suite fixture The acceptance suite holds fakes of PolicyEngineService, EnvironmentService, RunControlService, SecretBrokerService, ExecutionCapacityService, McpServerRegistryService and ArtifactService that record their calls, answer a configured outcome and can stop answering, the fake of RunControlService behind the one client port that answers the approval of an id, the state of a run and the current fencing token of a step, the fake of PolicyEngineService answering each of the four outcomes of policy-decision-v1, a fake executor per tool kind that returns a configured result, error or delay, workload tokens with and without the service scope, and a two-tenant, two-project invocation fixture; every later verification task of the feature uses it (model/services/tools-mcp/ToolAdapterService.yaml). ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2420 Verify the pipeline of a call and its receipt through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolAdapterService-007\|Scenario=SCN-ToolAdapterService-012)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-602: the tool-invocation-v1 document with fencingToken and toolVersion validated against docs/reference/schemas/tool-invocation.schema.json, the run, step and attempt on the row, the six states in order, the idempotent repeat, the key conflict, the stale fencing token of the same attempt, the token of a superseded attempt of the same run and step refused with FAILED_PRECONDITION after its successor called, also after the cache was cleared, because the mark is read back by run and step, the call for a cancelled run, the three gRPC refusals, the sanitized result with its evidence record, the publication and payload of ToolInvoked with a stopped transport, the retry of a read tool and the fail-fast answers; every receipt the suite reads is asserted on its status (Succeeded for Observed, Failed for Failed, TimedOut for a timeout without a possible effect, Cancelled for Cancelled) and validated against the schema; a measured run of read-class calls against the fakes reports the pipeline overhead without execution from connectsoft.factory.tools.latency and compares its 95th percentile with the objective of 300 milliseconds of the model, and an assertion over the whole suite finds receiptRef on every settled invocation past Validated; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-603: Deny a tool call at the stage that refuses it, record the reason and announce the denial

behavior · persona operator As an operator, I want a refused tool call to state which stage refused it and why, so that I can tell a wrong argument from a missing permission, a policy rule, a blocked command or a frozen environment.

A call that the pipeline refuses ends in state Denied, and nothing after the refusing stage happens: no credential is issued, no sandbox is leased and no tool runs. The stage and the reason are recorded on the ToolInvocation and announced by ToolInvocationDenied, written in the same transaction as the transition. At the schema stage a call is denied when its arguments violate the JSON schema of the descriptor or when the tool id and version name no active descriptor, because it was never registered, was retired or belongs to another tenant (trigger SchemaInvalidOrToolInactive, failure class validation); a tool of kind Mcp whose binding the registry answers NOT_FOUND is denied here as unbound. A descriptor of another tenant is never confirmed: the receipt, the reason and ToolInvocationDenied of a call that names it equal those of a call that names a tool id nobody registered, apart from the ids of the two invocations, and the reason of both says only that no active descriptor of that tool id and version exists for the caller. A retired descriptor of the tenant of the caller or of the platform tenant may name its retirement. The invocation keeps the failure class validation, and the attempt that receives the denial of an unknown or a foreign tool takes the failure class permanent and is not retried, as it does for the NOT_FOUND of ToolExecutor.Validate and ToolExecutor.Interrupt (AIFACTORY-US-601, AIFACTORY-US-608; ADR-0015 amendments D113 and D114). At the permission stage a call is denied when the caller lacks the scopes and roles the authorization of the descriptor requires, when the tool depends on a secret reference that was revoked for the tenant, or when the connection it is bound to is Suspended or Revoked. At the policy stage a call is denied when PolicyEngineService/Policy.Decide answers deny, when a shell command matches the block list and the policy denies it, or when a call of effective class shared-write or production targets a Frozen environment (trigger PolicyDenied, failure class policy). A decision of allow-with-constraints with a constraint the executor cannot apply is denied at the same stage, after the invocation was Authorized (trigger ConstraintNotApplicable, failure class policy, D121). At the approval stage a call the policy gates is denied when its approval was rejected or expired, as AIFACTORY-US-604 states. A call that is bound to no run is no denial: in I1 the hosted MCP endpoint serves only calls bound to a run, a step and an attempt and refuses any other before reception, so it leaves no invocation (AIFACTORY-US-607, D121). Over the hosted MCP endpoint a scope argument that contradicts the token is refused by the MCP library before the handler with a typed tool error whose reason is scope-mismatch, and that refusal is recorded as a denial at the permission stage (AIFACTORY-US-607). The caller receives the denial as the end of the ToolExecutor.Invoke stream: a tool-receipt-v1 with the status Denied, by the mapping of AIFACTORY-US-602, whose error names the stage and a reason that is redacted and never repeats an argument; the agent takes it as its observation, and an attempt that fails on it carries the failure class policy-denied for a policy or approval denial. A receipt is stored for every denial past validation. The denial is idempotent: a repeat with the same key and request hash returns the same denial and writes no second event. ToolInvocationDenied carries invocationId, tenantId, toolId, reason and stage; StudioBff, DashboardService and AuditService consume it in their own PBIs. The evidence record that the audit stage writes with the receipt of a denial carries the action policy-denied, the one action audit-evidence-v1 names for it. connectsoft.factory.tools.denials counts each denial by stage and reason with tenant and project. A caller that is not admitted at all, without a workload identity or without the service scope, is no denial: it is refused before reception as AIFACTORY-US-602 states and leaves no invocation.

Acceptance criteria

AC1 Given arguments that violate the schema of the descriptor, a tool id and version that name a retired descriptor, a tool id nobody registered and the tool id of a descriptor of another tenant, when ToolAdapterService/ToolExecutor.Invoke is called for each, then the ToolAdapterService/ToolInvocation moves from Received to Denied with the stage schema and the failure class validation, the reply ends with a receipt of status Denied whose reason repeats no argument, and no policy decision, credential or sandbox is requested; the receipt, the reason and ToolAdapterService/ToolInvocationDenied of the foreign tool equal those of the unregistered tool apart from the invocation ids and never confirm the descriptor, and the attempt takes the failure class permanent for both (SCN-ToolAdapterService-013, ADR-0015).
AC2 Given a caller that lacks a scope the authorization of the descriptor requires, a PolicyEngineService/Policy.Decide that answers deny, and a call of effective class shared-write that targets a Frozen environment, when ToolAdapterService/ToolExecutor.Invoke is called for each, then the invocation moves from Validated to Denied with the stage permission or policy and its reason, a receipt of status Denied is stored, nothing executes and no credential or sandbox is requested (SCN-ToolAdapterService-013, FR-05).
AC3 Given a denial at any stage, when the outbox dispatcher publishes ToolAdapterService/ToolInvocationDenied on tool-execution.invocations.v1.tool-invocation-denied, then the outbox record was written in the same transaction as the transition to Denied, the event is sent in the run event envelope with invocationId, tenantId, toolId, reason and stage, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ToolAdapterService-013, ADR-0014).
AC4 Given a denied call repeated with the same idempotency key and request hash, when it arrives, then the same denial is returned, no second ToolAdapterService/ToolInvocationDenied is written and connectsoft.factory.tools.denials was counted once with its stage, reason, tenant and project (SCN-ToolAdapterService-013, model/services/tools-mcp/ToolAdapterService.yaml).
Traces: services ToolAdapterService, PolicyEngineService
Traces: aggregates ToolAdapterService/ToolInvocation
Traces: apis ToolAdapterService/ToolExecutor.Invoke, PolicyEngineService/Policy.Decide
Traces: events ToolAdapterService/ToolInvocationDenied
Traces: descriptors tool-receipt-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0022
Traces: requirements FR-05, NFR-04
Traces: scenarios SCN-ToolAdapterService-013
Depends on AIFACTORY-US-600, AIFACTORY-US-602, feature:policy-engine-service, feature:contracts-package
Sources model/services/tools-mcp/ToolAdapterService.yaml, docs/planes/capability-tools/tool-policies.md#decision-outcomes, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#domain-model

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2421 Denial transitions of the pipeline with stage, reason, receipt and the ToolInvocationDenied outbox record implementation The pipeline moves an invocation to Denied through SchemaInvalidOrToolInactive, PolicyDenied, ConstraintNotApplicable and ApprovalRejectedOrExpired with the stage (schema, permission, policy or approval), a redacted reason and the failure class, gives a call to a descriptor of another tenant the same receipt, reason and event as a call to an unknown tool id so that the descriptor is never confirmed, stores a receipt of status Denied for every denial past validation, writes ToolInvocationDenied in the transaction of the transition, returns the same denial for a repeat under the same key, requests no credential and no sandbox after the refusing stage, and counts connectsoft.factory.tools.denials by stage and reason. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2422 Verify the denials through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ToolAdapterService-013"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-603 with one case per stage and reason (invalid arguments, retired descriptor, unknown tool id, foreign descriptor, unbound MCP tool, missing scope, revoked secret reference, suspended connection, policy deny, a constraint that cannot be applied, blocked shell command, frozen environment), the publication and payload of ToolInvocationDenied with a stopped transport and the idempotent repeat; the receipt, the reason and the event payload of the foreign descriptor are compared with those of the unknown tool id byte for byte apart from the invocation ids and the times, and every receipt is asserted on the status Denied; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-604: A call the policy gates executes only with an approval bound to its request hash and tool version, which Run Control owns, and a call the policy allows runs without one

behavior · persona reviewer As a reviewer, I want my approval to release exactly the call I was shown and nothing else, so that a changed argument or another tool version can never run under a decision I gave for something different.

Whether a call needs an approval is stated by the policy and by nothing else. The tool service reads it from the outcome of its own decision through PolicyEngineService/Policy.Decide, one of the four outcomes of policy-decision-v1: allow-with-approval gates the call, allow and allow-with-constraints do not, and deny denies it. This one rule holds for every side-effect class, shared-write, production, publication, external and spend alike: the outcome of the policy decision is the only gate, and the tool service gates no class on its own (D123). Which calls the policy gates is the matter of the policy bundles, which belong to PolicyEngineService: its default policy bundle answers allow-with-approval for a call of effective class production, publication, external or spend, so a project must change its policy to drop that approval (D123). The chain of the first outcome holds two shared-write tools, and the policy treats them differently. propose-change-set is answered allow-with-approval and stays approval-bound, unless a project policy allows autonomous proposals, as the definition of generate-product foresees. blueprint-submit-version for a Draft version is answered allow, because ADR-0026 amendment D64 makes a Draft submission autonomous by default: such a call moves from Authorized to Brokered with no approvalId and executes. Only where the project policy gates blueprint drafts is it answered allow-with-approval, and it then waits like any gated call. Without this reading the four definitions of the chain that submit a blueprint version would stall at every submission. The reading is taken from D64, from the approvals section of the workflow definitions and from the outcomes of policy-decision-v1, and the owner confirmed it (D121) and decided that it reaches every class (D123): the invariant of ToolInvocation states that an invocation of any side-effect class needs a bound approval only when Policy.Decide answers allow-with-approval, that allow executes without one, that deny ends the invocation Denied and that allow-with-constraints executes without one with its constraints applied, and tool-invocation-v1 requires the approval id only for a call whose decision answers allow-with-approval; decision D64 stays. A call that carries an approvalId is treated as gated whatever the outcome, because its caller states that a decision was taken for it, and no call ever executes under an approval id that does not bind. A decision of allow-with-constraints needs no approval: the call proceeds under the constraints of the decision, which the broker stage applies to the egress allow list and the limits of the sandbox lease (AIFACTORY-US-605), and a constraint that cannot be applied denies the call (AIFACTORY-US-603). A gated call executes only with an approval bound to the request hash of this invocation and to the exact tool version, and a different hash needs a new approval. The tool service never opens and never decides an approval. An approval is an ApprovalRequest of RunControlService: the lease holder requests it for the step with the hash of the exact proposal, a Reviewer decides it, and the agent runtime issues the gated call from its checkpoint once the decision is Approved. When a gated call arrives with an approvalId, the service validates the binding through its RunControlService client port before any credential or sandbox is brokered: the approval is of the same tenant and run, its state is Approved, its proposalHash equals the request hash of the invocation, and the request hash covers the tool id, the tool version and the arguments, so an approval given for another version or other arguments does not match. A bound approval moves the invocation on to Brokered with approvalId recorded, and the receipt and ToolInvoked carry it. When a gated call arrives without an approvalId, the invocation moves from Authorized to AwaitingApproval (trigger GatedClassWithoutApproval): the reply states that an approval for this request hash and tool version is required, nothing executes, and connectsoft.factory.tools.approvals_waiting goes up. The caller obtains the approval from RunControlService and repeats the call under the same idempotency key with the approvalId; the service validates the binding and the invocation moves from AwaitingApproval to Brokered (trigger ApprovalBound). The seven values of ApprovalState are answered one by one. Approved binds when hash, run and tenant match. Pending keeps the invocation AwaitingApproval and the reply says that the decision is pending. Rejected and Expired move the invocation to Denied at the stage approval (trigger ApprovalRejectedOrExpired) with ToolInvocationDenied, and the attempt fails with the failure class policy-denied. ChangesRequested and Stale bind nothing and the invocation stays AwaitingApproval: the proposal changes, a changed proposal has another request hash, and the runtime issues it as a new invocation under a new idempotency key, because the old key with another hash would be a conflict. Cancelled binds nothing and the invocation stays AwaitingApproval until the owner states whether a cancelled approval denies it. An approval of another hash, another run or another tenant binds nothing either: the invocation stays AwaitingApproval and the reply says so, the same answer for an approval of another tenant as for an unknown approval id. The model names a transition from AwaitingApproval to Denied only for Rejected and Expired, so an invocation whose approval ended ChangesRequested, Stale or Cancelled waits without an end, which is reported to the owner. RunControlService is a fail-fast dependency: when it does not answer, the gated call does not execute and fails with UNAVAILABLE. Three points of the read side are open and reported to the owner. The model names RunControlService as the dependency that validates the approval bound to the request hash, but the only internal read its service file lists for a worker is the server stream RunControl.WatchRun. That stream announces run and approval state changes; it is not stated to return an approval by its id with its proposal hash, its run and its tenant at the moment of a call, nor to replay the current state to a new subscriber, so it does not serve a validation that must precede the broker stage. The tool service consumes no ApprovalDecided either. The delivery puts the validation behind one client port, the port that also reads run and lease state for AIFACTORY-US-602, and proves it against a fake until the operation is named. For the same reason an invocation that waits and is never repeated cannot learn that its approval expired, although the model states that it is then Denied; the delivery denies it when the repeated call finds the approval Rejected or Expired. Which component defines the canonical request hash is reported with them: in generate-product the approval is requested on the step approve-proposal for the hash of the generated outputs, while propose-change-set is called by a later step, so the proposal hash of the approval equals the request hash the executor computes only when one rule defines both.

Acceptance criteria

AC1 Given a call of propose-change-set whose decision through PolicyEngineService/Policy.Decide is allow-with-approval, with an approvalId whose RunControlService/ApprovalRequest is Approved for the same tenant and run and whose proposalHash equals the request hash of the invocation, when ToolAdapterService/ToolExecutor.Invoke is called, then the binding is validated before any credential or sandbox is requested, the ToolAdapterService/ToolInvocation moves on to Brokered with approvalId recorded, the tool executes once, and the receipt and ToolAdapterService/ToolInvoked carry the approval id (FR-06, ADR-0022).
AC2 Given a call whose decision is allow-with-approval and that carries no approvalId, among them a call whose class the environment raised to production, when ToolAdapterService/ToolExecutor.Invoke is called, then the invocation moves from Authorized to AwaitingApproval, the reply states that an approval for this request hash and tool version is required, nothing executes, no approval is opened by the tool service and connectsoft.factory.tools.approvals_waiting is incremented; when the call is repeated under the same key with a bound, Approved approval, then the invocation moves to Brokered through ApprovalBound and executes once (FR-06, model/services/tools-mcp/ToolAdapterService.yaml).
AC3 Given a waiting invocation, when the call is repeated with an approvalId whose RunControlService/ApprovalRequest is Pending, then the invocation stays AwaitingApproval and the reply says that the decision is pending; when the approval is Rejected or Expired, then the invocation moves from AwaitingApproval to Denied at the stage approval, ToolAdapterService/ToolInvocationDenied is written in the same transaction, the receipt carries the status Denied, nothing executes and connectsoft.factory.tools.approvals_waiting is decremented (FR-06, ADR-0014).
AC4 Given an approval that is ChangesRequested, Stale or Cancelled, or that is Approved for other arguments, for another tool version, for another run or for another tenant, when the call is repeated with its approvalId, then nothing is bound, the invocation stays AwaitingApproval, nothing executes and the reply for an approval of another tenant equals that for an unknown approval id; given the regenerated proposal is called under a new idempotency key, then it is a new invocation with its own request hash; given RunControlService does not answer, when a gated call arrives, then it fails with UNAVAILABLE and nothing executes (FR-06, ADR-0015, model/services/control-plane/RunControlService.yaml).
AC5 Given a call of blueprint-submit-version for a Draft version under the default policy, whose decision through PolicyEngineService/Policy.Decide is allow, when ToolAdapterService/ToolExecutor.Invoke is called without an approvalId, then the invocation moves from Authorized to Brokered, executes once and ends Observed with no approvalId on the row, the receipt or ToolAdapterService/ToolInvoked, the Run Control port is not asked for an approval and connectsoft.factory.tools.approvals_waiting does not move; given a project policy that gates blueprint drafts, whose decision is allow-with-approval, then the same call moves to AwaitingApproval; given a decision of allow-with-constraints, then the call proceeds without an approval and the constraints are applied to the egress allow list and the limits of its lease; and given a call of effective class production, publication, external or spend whose decision is allow, because the policy of its project dropped the approval the default policy bundle asks for, then it moves from Authorized to Brokered without an approval like any allowed call, the tool service adding no gate of its own for a class (D123, ADR-0026, model/tools/blueprint-submit-version.yaml, docs/reference/schemas/policy-decision.schema.json).
Traces: services ToolAdapterService, RunControlService, PolicyEngineService
Traces: aggregates ToolAdapterService/ToolInvocation, RunControlService/ApprovalRequest
Traces: apis ToolAdapterService/ToolExecutor.Invoke, PolicyEngineService/Policy.Decide
Traces: events ToolAdapterService/ToolInvoked, ToolAdapterService/ToolInvocationDenied
Traces: tools propose-change-set, blueprint-submit-version
Traces: descriptors policy-decision-v1, tool-receipt-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0022, ADR-0026
Traces: requirements FR-06, FUX-05, XL-10, NFR-04
Depends on AIFACTORY-US-602, AIFACTORY-US-603, feature:run-control-service, feature:policy-engine-service
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/control-plane/RunControlService.yaml, model/tools/blueprint-submit-version.yaml, model/tools/propose-change-set.yaml, model/workflows/vision-to-blueprint.yaml, model/workflows/generate-product.yaml, docs/architecture/adr/0026-requirements-to-ux-handoff.md, docs/reference/schemas/approval.schema.json, docs/reference/schemas/policy-decision.schema.json, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#context-and-boundaries

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2423 Approval stage that reads the need for an approval from the policy outcome, with the AwaitingApproval wait and the validation port to Run Control implementation The pipeline gates a call when its own decision through Policy.Decide is allow-with-approval or when the call carries an approvalId, and lets a decision of allow or allow-with-constraints pass to the broker stage without an approval, by one rule for every side-effect class, shared-write, production, publication, external and spend alike, with no gate of its own for a class, the default policy bundle that asks for the approval of production, publication, external and spend calls being the matter of PolicyEngineService (D123), so that blueprint-submit-version for a Draft version runs autonomously under the default policy (ADR-0026 amendment D64) and propose-change-set stays approval-bound; it validates a supplied approvalId through one client port to RunControlService (same tenant and run, state Approved, proposalHash equal to the request hash, which covers tool id, tool version and arguments), moves the invocation to AwaitingApproval when none is bound, to Brokered through ApprovalBound on a bound approval and to Denied on a Rejected or Expired one, keeps it AwaitingApproval for Pending, ChangesRequested, Stale and Cancelled and for an approval of another hash, run or tenant, repeats the stage when the call returns under the same idempotency key, moves connectsoft.factory.tools.approvals_waiting with every entry and exit, opens and decides no approval, and fails with UNAVAILABLE when RunControlService does not answer; the port has one implementation slot for the operation of RunControlService that the model has yet to name, because RunControl.WatchRun is a stream of changes and no read of an approval by its id. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2424 Verify the approval binding of gated calls and the autonomous Draft submission through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=GatedToolCalls"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-604 against the fakes of PolicyEngineService and RunControlService: propose-change-set under allow-with-approval with a RunControlService/ApprovalRequest that is Approved and bound, missing, Pending, Rejected, Expired, ChangesRequested, Stale, Cancelled, of other arguments, of another tool version, of another run and of another tenant, and with the fake stopped; blueprint-submit-version for a Draft version under allow, which goes from Authorized to Brokered with no approvalId and without a call to the Run Control port, and under a gating project policy with allow-with-approval, which goes to AwaitingApproval; a call under allow-with-constraints whose lease carries the narrowed egress allow list and limits; and one call of each effective class production, publication, external and spend, which waits for its approval under allow-with-approval and goes from Authorized to Brokered without one under allow (D123). ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-605: Broker short-lived credentials and a sandbox with the workspace of the run for a call, and release both when it ends

behavior · persona operator As an operator, I want every tool that writes, builds or runs a command to work in a leased sandbox with credentials that expire, so that nothing an agent runs touches the host, another run or a secret that outlives the call.

After authorization and, where the policy gates the call, after the approval is bound, the pipeline brokers what the call needs to run and nothing more. Credentials come first. For each secret dependency the descriptor names, the service asks SecretBrokerService/SecretBroker.Issue for a short-lived credential scoped to the subject and the purpose of this call, with the policy decision id; the credential is delivered once, is injected into the sandbox or into the connector call, and is never written to the result, the receipt, an event, a log record or the reply to the agent. A tool without a secret dependency receives none. The sandbox follows. A descriptor names its sandbox kind; the kind None is allowed only for a native tool of class read that is answered by its owning service, which needs no sandbox. The seven repository read tools are of class read and still name a sandbox kind, because in this increment they execute inside the sandbox of the run over the workspace mounted read-only (decision D125, AIFACTORY-US-606). For every other tool the service asks ExecutionCapacityService/Capacity.AcquireLease for a sandbox of that kind with the tenant, project, run and attempt of the call. The model names the pool manager as the target of this dependency, which the service registry records as merged into ExecutionCapacityService. The lease carries the limits of the call: cpu, memory, timeout, read-only mounts and the egress allow list, by default Tools:Sandbox:DefaultEgressAllowList; any other destination is unreachable from the sandbox. When the decision of the call is allow-with-constraints, a constraint that narrows the egress allow list or a limit is applied to the lease before anything runs, and a lease never carries a wider limit than the decision gave (AIFACTORY-US-602). A lease and a workspace have different lifetimes, and the first outcome depends on the difference: a file that one step writes must still be there when a later step, under another attempt and another lease, builds it and proposes the change set. The workspace belongs to the run, and ExecutionCapacityService owns it (D121). That service creates the isolated workspace of a run with the first lease of the run, keeps it between leases, hands it to the lease holder through the workspaceRef of the lease and removes it when it consumes a terminal run event of RunControlService, RunCompleted, RunFailed or RunCancelled. A run has one workspace: every later lease of the same run, of any step and attempt, names the run and receives the same reference. ToolAdapterService mounts the workspace by the lease that hands it over and records the reference on each SandboxLease; it neither stores nor removes a workspace and consumes no event of a run. Releasing or reaping a lease ends the sandbox and its credentials, frees the capacity and leaves the workspace of the run in place. The creation, the keeping and the removal of the workspace are delivered by feature execution-capacity-service-thin, on which this PBI depends, and are not built here. The invocation moves to Brokered, from Authorized with the trigger CredentialsAndSandboxLeased or, for a gated call, from AwaitingApproval with the trigger ApprovalBound, and SandboxLeased is written in the same transaction. Calls of the same attempt that arrive while a lease of that attempt is open reuse it and renew it through ExecutionCapacityService/Capacity.RenewLease; a call of another attempt of the run takes a lease of its own on the same workspace. connectsoft.factory.tools.sandboxes_open follows the open leases and connectsoft.factory.tools.sandbox_capacity reports what capacity states as available. While a call executes, the reminder credential-expiry of the grain fires before a brokered credential expires and a fresh one is issued for a call that still runs. The worker SandboxReaper runs every two minutes, partitioned by pool with at most four in parallel: it releases a lease once no invocation that uses it is in a non-terminal state or once its expiry passed, sets releasedAt and writes SandboxReleased with the reason in the same transaction, idempotently on the lease id and with five exponential retries. ExecutionCapacityService frees the capacity and SecretBrokerService revokes the issuances of the sandbox when they consume that event, in their own PBIs. On release the service reports the minutes of the lease through CostUsageService/Usage.RecordUsage as a usage-record-v1 on the meter sandbox.minutes, the value of the descriptor for the meter the model of this service names SandboxMinutes, with the lease id as its source receipt, so a repeated report is recorded once. CostUsageService is a dependency that degrades: a release never waits for it, the report is retried with the retries of the worker, and no receipt is held back for a missing price, because CostUsageService stores an unpriced receipt as Uncertain. Whether the minutes of a failed or cancelled invocation are metered is an input of the owner and is not decided here: the report states the state of the invocation in its dimensions. The usage of the invocation itself reaches CostUsageService through ToolInvoked, from which that service records the meter tools.invocations. SecretBrokerService and ExecutionCapacityService are fail-fast dependencies: when the broker does not answer, the call fails with UNAVAILABLE and no sandbox is leased; when capacity denies the lease because the pool is exhausted, the call waits and asks again with backoff until the deadline the caller set from its attempt budget, then fails with RESOURCE_EXHAUSTED and the failure class transient, and nothing executed. The capacity alert the model names for this failure mode reads two signals this service emits: the gauge connectsoft.factory.tools.sandbox_capacity, which then reports no available sandbox of the kind, and the transient failures that connectsoft.factory.tools.invocations counts; the alert rule itself is defined with the observability platform and not here. A sandbox whose heartbeat is lost while a call executes is the case of AIFACTORY-US-608. The model has no column that marks a usage report as acknowledged, so a report that every retry failed to deliver is logged and counted and reported to the owner as a gap.

Acceptance criteria

AC1 Given an authorized call to a sandbox-class tool whose descriptor names one secret dependency, when the broker stage runs, then one credential is issued through SecretBrokerService/SecretBroker.Issue with the policy decision id, a sandbox is leased through ExecutionCapacityService/Capacity.AcquireLease with the workspace of the run and the egress allow list, narrowed by the constraints of a decision of allow-with-constraints where there is one, the ToolAdapterService/ToolInvocation moves to Brokered with its sandboxLeaseId, and the credential value appears in no row, receipt, event or log record; a second call of the same attempt while the lease is open reuses it and renews it through ExecutionCapacityService/Capacity.RenewLease and writes no second ToolAdapterService/SandboxLeased, and a read-class native tool whose sandbox kind is None is brokered without a lease (ADR-0022, docs/planes/capability-tools/tool-policies.md).
AC2 Given the lease was recorded, when the outbox dispatcher publishes ToolAdapterService/SandboxLeased on tool-execution.sandboxes.v1.sandbox-leased, then the outbox record was written in the same transaction as the transition to Brokered, the event is sent in the run event envelope with leaseId, invocationId, tenantId, kind and poolId, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id; given SecretBrokerService does not answer, and given ExecutionCapacityService/Capacity.AcquireLease denies the lease until the deadline of the call, then the first call fails with UNAVAILABLE and the second waits, asks again with backoff and fails with RESOURCE_EXHAUSTED and the failure class transient while connectsoft.factory.tools.sandbox_capacity reports no available sandbox, and in both nothing executes and no event is written (SCN-ToolAdapterService-015, ADR-0014).
AC3 Given an open lease whose invocations all ended, or whose expiry passed, when SandboxReaper runs, then releasedAt is set and the ToolAdapterService/SandboxReleased outbox record with leaseId, tenantId and reason is written in the same transaction and published on tool-execution.sandboxes.v1.sandbox-released with the same retry guarantee; a second run for the same lease id changes nothing, a lease that an executing invocation still uses is not released, and the release ends the sandbox and its credentials and leaves the workspace of the run in place (SCN-ToolAdapterService-016, ADR-0014).
AC4 Given a released lease, when the release is processed, then CostUsageService/Usage.RecordUsage is called with a usage-record-v1 whose meter is sandbox.minutes, with the minutes between leasedAt and releasedAt, the state of the invocation in its dimensions and the lease id as sourceReceipt; given CostUsageService does not answer, then the release is not held back and the report is retried, and a report delivered twice is recorded once (model/services/control-plane/CostUsageService.yaml, docs/reference/schemas/usage-record.schema.json).
AC5 Given a run whose first attempt wrote a file through a sandbox-class call and whose lease SandboxReaper has released, when a call of a later attempt of the same run is brokered through ExecutionCapacityService/Capacity.AcquireLease, then the lease hands over the same workspaceRef as the released one and the new SandboxLease records it, the call reads the file the first attempt wrote and builds it, a call of another run never receives that workspace, and ToolAdapterService has neither stored nor removed a workspace, because ExecutionCapacityService owns it (SCN-ToolAdapterService-016, FR-05, model/services/runtime-cloud/ExecutionCapacityService.yaml).
Traces: services ToolAdapterService, SecretBrokerService, ExecutionCapacityService, CostUsageService
Traces: aggregates ToolAdapterService/ToolInvocation
Traces: apis SecretBrokerService/SecretBroker.Issue, ExecutionCapacityService/Capacity.AcquireLease, ExecutionCapacityService/Capacity.RenewLease, CostUsageService/Usage.RecordUsage
Traces: events ToolAdapterService/SandboxLeased, ToolAdapterService/SandboxReleased
Traces: descriptors usage-record-v1
Traces: adrs ADR-0014, ADR-0022
Traces: requirements FR-05, NFR-02, XL-16
Traces: scenarios SCN-ToolAdapterService-015, SCN-ToolAdapterService-016
Depends on AIFACTORY-US-602, feature:secret-broker-service, feature:execution-capacity-service-thin, feature:cost-usage-service-complete, feature:contracts-package
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/runtime-cloud/ExecutionCapacityService.yaml, model/services/governance/SecretBrokerService.yaml, model/services/control-plane/CostUsageService.yaml, docs/reference/schemas/usage-record.schema.json

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2425 Broker stage: credentials from the Secret Broker and the sandbox lease with the workspace of the run, limits and egress allow list implementation The broker stage issues one credential per secret dependency through SecretBroker.Issue with the policy decision id and injects it into the sandbox or the connector call without persisting or logging its value, acquires the sandbox through Capacity.AcquireLease with the tenant, project, run and attempt, the limits and the egress allow list (Tools:Sandbox:DefaultEgressAllowList by default), narrows the egress allow list and the limits by the constraints of a decision of allow-with-constraints and never widens them, records the SandboxLease with the workspaceRef the lease hands over, the reference of the one workspace of the run, which ExecutionCapacityService creates with the first lease of the run and keeps between leases (D121), mounts that workspace whatever the attempt and never creates or stores one itself, reuses an open lease of the same attempt and renews it through Capacity.RenewLease, writes SandboxLeased in the transaction of the Brokered transition (from Authorized through CredentialsAndSandboxLeased, from AwaitingApproval through ApprovalBound), leases nothing for a read-class native tool of sandbox kind None, renews a credential on the credential-expiry reminder, fails with UNAVAILABLE when the broker does not answer and with RESOURCE_EXHAUSTED when capacity denies the lease until the deadline of the call, and records connectsoft.factory.tools.sandbox_capacity and the transient failure in connectsoft.factory.tools.invocations, the two signals the capacity alert reads. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2426 SandboxReaper with the SandboxReleased outbox record and the sandbox minutes report, releasing the lease and never the workspace of the run implementation The reaper releases a lease once no invocation that uses it is non-terminal or once its expiry passed, on its two-minute schedule partitioned by pool with at most four in parallel, sets releasedAt and writes SandboxReleased with the reason in one transaction, idempotently on the lease id and with five exponential retries; the release ends the sandbox and its credentials and never removes the workspace of the run, which ExecutionCapacityService owns and removes on a terminal run event (D121); the reference stays on the released SandboxLease and the next lease of the run hands over the same one; on release it reports the minutes of the lease through Usage.RecordUsage as a usage-record-v1 on the meter sandbox.minutes with the lease id as source receipt and the state of the invocation in the dimensions, never holds a release back for the report, and logs and counts a report that every retry failed to deliver. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-219 Build tooling and egress enforcement of the sandbox worker image of the pool implementation The sandbox worker of the one pool, its lease, the workspace of a run with its creation at the first lease of the run, its keeping between leases and its removal on a terminal run event (D121), the mount of the workspace and the destruction of a sandbox at release are owned by the thin delivery of feature execution-capacity-service-thin and are not planned again here. This task adds only what the tools of the chain need and that feature does not state: the worker image carries the build tooling of the chain (the dotnet toolchain, git and the node toolchain behind the shell allow list of model/services/tools-mcp/ToolAdapterService.yaml), and the worker enforces the egress allow list and the limits a lease of ToolAdapterService carries, so that a destination outside the list is unreachable from a sandbox; the destruction of a sandbox leaves the workspace of its run in place. ConnectSoft.AI.SoftwareFactory.ExecutionCapacityService
AIFACTORY-TASK-2427 Verify the sandbox lease, the credentials, the release and the workspace of the run through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolAdapterService-015\|Scenario=SCN-ToolAdapterService-016)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-605 with the fakes of SecretBrokerService, ExecutionCapacityService and CostUsageService and a sandbox fixture with a workspace: the credential that appears nowhere, the lease narrowed by the constraints of a decision, the reused lease renewed through ExecutionCapacityService/Capacity.RenewLease, the read tool without a lease, the publication and payload of SandboxLeased and SandboxReleased with a stopped transport, the stopped broker, the exhausted pool with its capacity signal, the idempotent reaper, the usage-record-v1 on the meter sandbox.minutes delivered once, and a file that a call of one attempt wrote and that a call of a later attempt of the same run reads and builds after the first lease was reaped; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-606: Execute the native tools of the chain through the service that owns each, and shell commands in the sandbox under the allow list and the block list

behavior · persona requester As a requester, I want the tools my run needs to read its workspace, write files, build, validate blueprints and propose a change to work behind the one executor, so that the agents of my run produce a built and tested change set without any tool running outside the pipeline.

When an invocation reaches Executing, the executor of its kind runs the tool, and a native tool wrapped as a descriptor looks to the pipeline like any other (ADR-0022 decision 1). The sixteen tools of the chain are native, and each executes where its catalogue entry places it. The seven repository read tools (list-files, search-text, search-symbols, find-references, read-range, get-dependencies and get-git-diff) are owned by RepositoryIntelligenceService, and in this increment they execute inside the sandbox of the run (decision D125). The executor leases the sandbox as for every sandboxed tool (AIFACTORY-US-605); the lease mounts the workspace of the run read-only, and ToolExecutorHost runs in that sandbox the read-tool handlers of the RepositoryIntelligenceService repository, packaged as a tool component that answers the same seven methods with the same contract as the complete service of I5. The executor calls the method of the tool on that component with the invocation and the workspaceRef of the run, which it reads from the lease. No deployed service reads a workspace from outside a sandbox before I5, so a read tool sees the workspace of its run only and never another run or the host, and since ExecutionCapacityService creates the workspace with the first lease of the run (D121), a read tool always finds one. The arguments of each read tool follow the golden argument shape of its method: a path prefix, a name pattern and a depth for ListFiles; the text and an optional path prefix for SearchText; a name, a kind and a container for SearchSymbols; a symbol for FindReferences; a path and a line range for ReadRange; a path or a symbol for GetDependencies; optional paths for GetHistory, which serves get-git-diff. Each shape also holds the continuation token of a paged answer, and arguments that do not match the shape are refused with INVALID_ARGUMENT, which ends the invocation Failed with the failure class validation. knowledge-search and graph-query are owned by VectorMemoryService, whose thin delivery answers with an empty, well-formed result. blueprint-validate and blueprint-submit-version are calls to the methods Blueprints.Validate and Blueprints.SubmitDraftVersion of BlueprintService, and get-approved-recipe is a call to Recipes.GetApprovedRecipe of GenerationRecipeService; both services name ToolAdapterService as an inbound caller, and each call carries the scope of the run. From I2 every service call a run-bound tool makes also carries in its call metadata the requester of the run as delegatedUserId and the runId and stepRunId of the calling step, so that the promotion request of the deploy-environment tool is decided for the run requester and the completion events of the promotion or of a change proposal find the waiting step (D141). blueprint-submit-version is a shared write that the default policy lets run without an approval for a Draft version (AIFACTORY-US-604). Its effect is the stored version: the receipt carries the reference of the blueprint version as its effect and the audit fields of its catalogue entry, blueprintId, version, kind and documentHash. The catalogue declares it naturally idempotent on the document hash and without a retry of the executor, so a second call with the same document, also under another idempotency key, returns the same version from BlueprintService and creates none. record-generated-output is the tool of the step record-outputs of generate-product, bound to the skill microservice-generator-record-outputs (decision D133). It is a shared write that the default policy lets run without an approval: the executor calls Recipes.RecordOutput of GenerationRecipeService with its own workload identity and the scope factory.recipes.write, with the change set of change-set-v1 that the step produced, so that the recipe reaches Generated and GenerationCompleted is published in this increment. The catalogue declares it naturally idempotent on run, recipe and change set hash and without a retry of the executor, so a repeated call records nothing new, and its receipt carries the audit fields recipeId, recipeVersion, runId, moduleName and changeSetHash. The tools the executor owns itself run in the leased sandbox: write-file creates, deletes or moves files inside the workspace, apply-patch applies a unified diff to it, build-and-test builds and tests the workspace and returns its report as an artifact, and each refuses a path that leaves the workspace. propose-change-set is the first write of a run to a shared system. Under the default policy it is gated: after its approval is bound (AIFACTORY-US-604) it pushes the workspace diff as a branch and opens the change proposal through the connection of the project, resolved through IntegrationService with a credential from the Secret Broker, and returns the reference of the proposal as the effect of the receipt. A shell tool runs a command in the sandbox under two lists. A command that matches Tools:Shell:AllowList runs as sandbox class. A command that matches Tools:Shell:BlockList is passed to the policy decision with the match and is then denied with the reason block-list or escalated to the effective class production, which the policy gates; it never runs as sandbox class. A command on neither list does not run as sandbox class either, because the service page states that shell tools run only allow-listed commands as sandbox class: it is passed to the policy decision as not allow-listed and is denied or escalated like a block-listed one, and only which of the two the default policy chooses is reported to the owner. The command line, the exit code and the duration are recorded as the audit requirements of the descriptor ask, and the output is sanitized like every result. The seed of this increment holds the sixteen tools of the chain and neither apply-patch nor shell-sandbox, so these two are not callable on a deployed instance: their executors are built here and proven on fixture descriptors of the acceptance suite, and they become callable when their descriptors are published through the registry. Every executor respects the timeout of the descriptor, or Tools:Execution:DefaultTimeoutSeconds when it sets none, through the reminder timeout of the grain. The read-tool component in the sandbox, VectorMemoryService and IntegrationService degrade: when one does not answer, the call that needs it ends Failed with the failure class transient (trigger ErrorBeforeEffect) and ToolInvoked in state Failed, the probe marks its descriptors unhealthy, and the other tools keep working. The outbound dependencies of the model do not list BlueprintService and GenerationRecipeService although both name the executor as their caller; the delivery treats them as it treats the other owning services, and the missing rows are reported. The service summary names the execution of native, MCP and shell tools; the kind enum also lists Http, Browser and Agent, for which this feature builds no executor and no tool is seeded, so a call to a descriptor of such a kind is denied at the schema stage with the reason that its kind has no executor, and which feature delivers them is reported to the owner.

Acceptance criteria

AC1 Given a run and the seeded read tools, when each of the seven repository read tools is called through ToolAdapterService/ToolExecutor.Invoke with arguments in the golden shape of its method, then it executes inside the leased sandbox of the run, where the workspace is mounted read-only and the read-tool component that ToolExecutorHost runs answers the method of the tool with the workspaceRef of the lease, the result is sanitized and receipted, a path outside the workspace of the run is refused, and arguments that do not match the shape end Failed with the failure class validation; given the component does not answer, then the read tool ends Failed with the failure class transient and ToolAdapterService/ToolInvoked in state Failed while build-and-test still executes (FR-05, XL-03, D125, model/services/knowledge/RepositoryIntelligenceService.yaml).
AC2 Given a leased sandbox with the workspace of the run, when the seeded tools write-file and build-and-test and, on a fixture descriptor because the seed does not hold it, apply-patch are called through ToolAdapterService/ToolExecutor.Invoke, then the file and the patch are in the workspace, the build and the tests ran inside the sandbox on them, the report is stored as an artifact referenced by the receipt, each ToolAdapterService/ToolInvocation ends Observed, and a path that leaves the workspace ends Failed without a write (FR-05, ADR-0022).
AC3 Given the seeded tools blueprint-validate, blueprint-submit-version, get-approved-recipe, knowledge-search and graph-query, when each is called through ToolAdapterService/ToolExecutor.Invoke, then the executor calls BlueprintService/Blueprints.Validate, BlueprintService/Blueprints.SubmitDraftVersion and GenerationRecipeService/Recipes.GetApprovedRecipe with the scope of the run, the receipt of blueprint-submit-version carries the reference of the version as its effect and the audit fields blueprintId, version, kind and documentHash of model/tools/blueprint-submit-version.yaml, a second call with the same document hash under another idempotency key returns the same version and creates none, and the two tools of the thin VectorMemoryService end Observed with an empty, well-formed result; given the seeded tool record-generated-output called in the step record-outputs, when it executes, then the executor calls GenerationRecipeService/Recipes.RecordOutput with its workload identity and the scope factory.recipes.write, the receipt carries the audit fields of model/tools/record-generated-output.yaml, and a repeat with the same run, recipe and change set hash records nothing new (FR-05, ADR-0026, D133).
AC4 Given the shell tool on its fixture descriptor, because the seed does not hold shell-sandbox, and the default lists of the model, when the commands dotnet build, rm -rf with a policy that denies the block list, terraform destroy with a policy that escalates and a command on neither list are called, then the first runs in the sandbox as sandbox class with command line, exit code and duration recorded, the second is denied with the reason block-list and runs nothing, the third takes the effective class production and waits for an approval as AIFACTORY-US-604 states, and the fourth does not run as sandbox class and is denied or escalated by the decision (model/services/tools-mcp/ToolAdapterService.yaml, docs/planes/capability-tools/tool-policies.md).
AC5 Given propose-change-set under a decision of allow-with-approval with a bound approval, when it executes, then the diff of the workspace is pushed as a branch and the change proposal is opened through the connection of the project with a brokered credential, the receipt carries the reference of the proposal as its effect and ToolAdapterService/ToolInvoked carries the approval id, and without a bound approval nothing is pushed; given a tool that runs past the timeout of its descriptor, then the timeout reminder stops it and it is settled as AIFACTORY-US-608 states; given a descriptor of kind Http, Browser or Agent, then the call is denied because its kind has no executor (XL-10, FR-06, model/services/tools-mcp/ToolAdapterService.yaml).
Traces: services ToolAdapterService, RepositoryIntelligenceService, VectorMemoryService, BlueprintService, GenerationRecipeService, IntegrationService
Traces: aggregates ToolAdapterService/ToolInvocation
Traces: apis ToolAdapterService/ToolExecutor.Invoke, BlueprintService/Blueprints.Validate, BlueprintService/Blueprints.SubmitDraftVersion, GenerationRecipeService/Recipes.GetApprovedRecipe, GenerationRecipeService/Recipes.RecordOutput
Traces: events ToolAdapterService/ToolInvoked
Traces: tools record-generated-output, list-files, search-text, search-symbols, find-references, read-range, get-dependencies, get-git-diff, knowledge-search, graph-query, blueprint-validate, blueprint-submit-version, get-approved-recipe, write-file, apply-patch, build-and-test, shell-sandbox, propose-change-set
Traces: adrs ADR-0022, ADR-0026
Traces: requirements FR-05, FR-06, XL-03, XL-10
Depends on AIFACTORY-US-602, AIFACTORY-US-604, AIFACTORY-US-605, feature:execution-capacity-service-thin, feature:repository-intelligence-service-thin, feature:vector-memory-service-thin, feature:blueprint-service, feature:generation-recipe-service, feature:integration-service-thin
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/knowledge/RepositoryIntelligenceService.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/GenerationRecipeService.yaml, model/tools/shell-sandbox.yaml, model/tools/propose-change-set.yaml, model/tools/blueprint-submit-version.yaml, model/tools/record-generated-output.yaml, model/services/tools-mcp/ToolExecutorHost.yaml, docs/planes/capability-tools/tool-registry.md#the-executor-gw-05

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2428 Executors of the native tools owned by other services and of the workspace tools of the executor implementation One executor per owning service forwards the invocation to the gRPC method of its tool with the scope of the run: for the seven read tools, the read-tool component of the RepositoryIntelligenceService repository that ToolExecutorHost runs inside the leased sandbox of the run, where the workspace is mounted read-only, with the workspaceRef of the lease and the arguments in the golden shape of each method, a mismatch ending Failed with the class validation (D125); Recipes.RecordOutput of GenerationRecipeService for record-generated-output, called with the workload identity of the executor and the scope factory.recipes.write, without a retry and naturally idempotent on run, recipe and change set hash, with the audit fields of its catalogue entry on the receipt (D133); VectorMemoryService for knowledge-search and graph-query; Blueprints.Validate and Blueprints.SubmitDraftVersion of BlueprintService for blueprint-validate and blueprint-submit-version; Recipes.GetApprovedRecipe of GenerationRecipeService for get-approved-recipe. The receipt of blueprint-submit-version carries the reference of the version as its effect and the audit fields blueprintId, version, kind and documentHash, and the executor does not repeat that call, whose idempotency on the document hash lies with BlueprintService. write-file, apply-patch and build-and-test run in the leased sandbox on the workspace and refuse a path that leaves it; propose-change-set pushes the workspace diff and opens the change proposal through the connection of the project with a brokered credential and returns its reference as the effect; every executor honours the timeout reminder and ends Failed with the class transient when its owning service or the read-tool component does not answer. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2429 Shell executor in the sandbox with the allow list, the block list and the recorded command line implementation The shell executor matches a command against Tools:Shell:AllowList and Tools:Shell:BlockList, both reloadable: an allow-listed command runs in the leased sandbox as sandbox class; a block-listed command is passed to the policy decision with its match and is denied with the reason block-list or raised to the effective class production; a command on neither list never runs as sandbox class and is passed to the policy decision as not allow-listed, which denies or escalates it; command line, exit code and duration are recorded as the audit requirements of the descriptor ask and the output is sanitized. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-220 Contract of the seven repository read tool methods as the executor calls them on the read-tool component in the sandbox of the run contract The read implementation over the mounted workspace of the run and its packaging as a tool component are owned by the thin delivery of feature repository-intelligence-service-thin and are not planned again here. This task fixes only what this feature adds: the contract of the seven tool methods of RepositoryIntelligenceService (ListFiles, SearchText, SearchSymbols, FindReferences, ReadRange, GetDependencies and GetHistory for get-git-diff) as the executor calls them on the component that ToolExecutorHost runs in the sandbox of the run, with the invocation, the scope of the run and the workspaceRef of the lease, the seven golden argument shapes (a path prefix, a name pattern and a depth; the text and an optional path prefix; a name, a kind and a container; a symbol; a path and a line range; a path or a symbol; optional paths), each with the continuation token of a paged answer and a mismatch refused with INVALID_ARGUMENT, the refusal of a path outside that workspace, and replies in ranges and never a whole repository; a contract test in the repository of that service holds the seven shapes against the calls of the executor, the same set of shapes that the contract of that thin delivery holds (D125, model/services/knowledge/RepositoryIntelligenceService.yaml, model/backlog/features/knowledge.yaml). ConnectSoft.AI.SoftwareFactory.RepositoryIntelligenceService
AIFACTORY-TASK-2430 Verify the native and shell executors through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=NativeAndShellTools"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-606 through ToolAdapterService/ToolExecutor.Invoke with fakes of the owning services and a sandbox fixture with a workspace: the seven read tools on the read-tool component in the sandbox fixture with the workspace mounted read-only, their golden argument shapes and a mismatched shape, a stopped component, record-generated-output calling a fake GenerationRecipeService/Recipes.RecordOutput with the workload identity of the executor and its repeat that records nothing new, write-file and build-and-test on their seeded descriptors and apply-patch on a fixture descriptor, the calls of BlueprintService/Blueprints.Validate, BlueprintService/Blueprints.SubmitDraftVersion and GenerationRecipeService/Recipes.GetApprovedRecipe with the scope of the run, the receipt of blueprint-submit-version with its version reference and audit fields, the repeat with the same document hash that returns the same version, the empty results of knowledge-search and graph-query, the shell tool on a fixture descriptor with the three listed commands under both policy outcomes and a command on neither list, propose-change-set with and without a bound approval against a fake connection, and a descriptor of a kind without an executor; the suite asserts that apply-patch and shell-sandbox are absent from the seed of sixteen descriptors. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-607: Execute a tool of kind Mcp through the MCP library client and host the MCP endpoint of the Factory with authorization on

behavior · persona asset-maintainer As an asset maintainer, I want a tool served by an MCP server, and a client that reaches the Factory over MCP, to pass the same executor with the same identity rules, so that no MCP path exists that is anonymous, ungoverned or outside the receipts.

MCP is the tool protocol of the Factory (ADR-0022), and both directions use the pinned MCP library (feature component-mcp); the service writes no protocol code of its own. Outbound, a descriptor of kind Mcp names its mcpServerId. When such an invocation reaches Executing, the executor asks McpServerRegistryService/McpRegistry.ResolveTool for the server, the transport, the binding and the authentication of the tool. For a consumed server on the streamable HTTP transport it resolves the connection of the server through IntegrationService, and the client call of the library carries a token obtained through the credential port of the library from the Secret Broker, never a raw secret (ADR-0022 decision 6). A server on the stdio transport runs as the sandboxed command of its registration inside a leased sandbox, and the library client speaks to it through the bridge in that sandbox. The governance policy the registration names is applied to the call through the governance integration of the library, which fails closed. The result of an MCP tool is untrusted content like any tool result and is sanitized before it reaches a model. A NOT_FOUND from the registry denies the call as unbound (AIFACTORY-US-603); a registry that does not answer and a descriptor that a degraded server made unhealthy fail the call fast with the failure class transient (AIFACTORY-US-600, AIFACTORY-US-602). Inbound, the service hosts the MCP endpoint of the Factory with the hosting of the library, and ToolExecutorHost routes the transport to it. Authorization is on by default for any exposure beyond the local process: a client without a token is refused with the protected-resource challenge of the library, and anonymous exposure would need a declared exception, which this service does not declare. The scope of the authenticated caller reaches every tool handler. A tool call through the endpoint requires factory.tools.invoke. In I1 the endpoint serves only calls bound to a run, a step and an attempt; IDE clients and partner agents arrive with the complete McpServerRegistryService in I5, and the caller kinds ide-client and partner-agent, a call without a run and the approval of such a call are no part of this delivery (D121). Tenant and project come from the token, which the library refuses before the handler when it carries no tenant or no project, and the run, the step and the attempt come from the token through the scope accessor of the library. A call whose token carries no run, step and attempt identity is refused by the endpoint before reception with a typed tool error whose reason says that the call is bound to no run: no ToolInvocation is recorded, no ToolInvocationDenied is written and nothing executes. A bound call enters the same pipeline as ToolAdapterService/ToolExecutor.Invoke with the caller kind agent, so it is validated, decided, classified, brokered, executed, sanitized and receipted like every call of an attempt: the endpoint builds the tool-invocation-v1 of the call from the MCP call and the scope the library hands it, the run, the step and the attempt are stored on the invocation, the fencing check of AIFACTORY-US-602 applies when the call carries the fencing token of its lease, the receipt is listed under the run, and a call the policy gates waits for the approval of its run and executes only with that approval bound (AIFACTORY-US-604). The idempotency key, which ToolInvocations requires and holds unique per tenant and project, is the key the caller supplies in the request metadata of the tool call when it supplies one; otherwise the endpoint derives it from the session id of the MCP connection and the request id of the call, so the same request sent again in the same session returns the existing receipt and a new request is a new invocation. A declared scope argument of a tool call, tenantId, projectId or a parameter the tool declares as scope, that contradicts the token is refused by the library before the handler with a typed tool error whose reason is scope-mismatch. The list of tools the endpoint offers is the answer of McpServerRegistryService/McpRegistry.ListCapabilities for the scope of the caller. The signing key of the endpoint is read from the secret reference mcp-signing-key. An agent is never exposed as a raw tool: ADR-0022 decision 7 allows it only through the lifecycle pipeline, and no tool of kind Agent exists here. In this increment the registry is static and holds no server: on a deployed instance no call leaves the service over MCP and the endpoint lists no tool. The delivery is therefore proven against a fixture MCP server with authorization on and against a fake registry that returns a binding, and the first registered server arrives with feature mcp-server-registry-service-complete.

Acceptance criteria

AC1 Given an active descriptor of kind Mcp and a fake registry whose McpServerRegistryService/McpRegistry.ResolveTool returns a binding to a fixture server on streamable HTTP that requires authorization, when the tool is called through ToolAdapterService/ToolExecutor.Invoke, then the client of the pinned MCP library calls the server with a token obtained through its credential port, no raw secret is held by the service, the result is sanitized and the ToolAdapterService/ToolInvocation ends Observed with a receipt (ADR-0022, model/backlog/pbis/component-extensions/component-mcp.yaml).
AC2 Given a registry that answers NOT_FOUND, a registry that does not answer, and a fixture server that returns a result containing an instruction and a secret pattern, when the MCP tool is called for each, then the first is denied as unbound, the second fails fast with UNAVAILABLE and the failure class transient, and the third ends Observed with the secret redacted and the instruction kept as data; in the first two no call reaches a server (ADR-0022, docs/planes/capability-tools/tool-policies.md).
AC3 Given the hosted MCP endpoint, when a client connects without a token, and when a caller whose token carries factory.tools.invoke and the run, step and attempt identity calls a tool, then the first is refused with the protected-resource challenge and no handler runs, and the second enters the pipeline of ToolAdapterService/ToolExecutor.Invoke with the caller kind agent, the scope of the token in the handler, the run, the step and the attempt on its ToolAdapterService/ToolInvocation and a receipt at its end that is listed under the run (ADR-0022, ADR-0015).
AC4 Given a tool call through the endpoint whose tenantId or projectId argument contradicts the token, when it arrives, then it is refused before the handler with a typed tool error whose reason is scope-mismatch and no tool runs; given the deployed thin registry, when a client lists the tools of the endpoint, then the list is the empty answer of McpServerRegistryService/McpRegistry.ListCapabilities (ADR-0015, model/backlog/pbis/component-extensions/component-mcp.yaml).
AC5 Given a caller of the hosted endpoint whose token carries factory.tools.invoke and no run, step and attempt identity, when it calls a tool, then the call is refused before reception with a typed tool error whose reason says that the call is bound to no run, no ToolAdapterService/ToolInvocation is recorded, no ToolAdapterService/ToolInvocationDenied is written and nothing executes, because in I1 the endpoint serves only calls bound to a run, a step and an attempt; given a bound call, then its idempotency key is taken from the request metadata of the call or derived from the session id and the request id, the same request sent again in the same session returns the existing receipt, and a call whose policy decision is allow-with-approval moves to AwaitingApproval and executes only with the approval of its run bound, as every gated call does (ADR-0022, model/services/tools-mcp/ToolAdapterService.yaml, model/services/control-plane/RunControlService.yaml).
Traces: services ToolAdapterService, McpServerRegistryService, IntegrationService
Traces: aggregates ToolAdapterService/ToolInvocation
Traces: apis ToolAdapterService/ToolExecutor.Invoke, McpServerRegistryService/McpRegistry.ResolveTool, McpServerRegistryService/McpRegistry.ListCapabilities
Traces: events ToolAdapterService/ToolInvocationDenied
Traces: adrs ADR-0015, ADR-0022
Traces: requirements FR-05, NFR-02
Depends on AIFACTORY-US-602, AIFACTORY-US-603, AIFACTORY-US-605, feature:component-mcp, feature:mcp-server-registry-service-thin, feature:integration-service-thin, feature:secret-broker-service
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/tools-mcp/McpServerRegistryService.yaml, model/backlog/pbis/component-extensions/component-mcp.yaml, model/services/control-plane/RunControlService.yaml, docs/architecture/adr/0022-mcp-as-tool-protocol.md, docs/planes/capability-tools/mcp.md#security-notes

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2431 MCP executor on the client of the pinned MCP library with the credential port and the sandboxed stdio bridge implementation The executor of kind Mcp resolves the tool through McpRegistry.ResolveTool, calls a streamable HTTP server through the client of the pinned ConnectSoft.Extensions.ModelContextProtocol package with a token obtained through its credential port from the Secret Broker and the connection of the server, runs a stdio server as its sandboxed command inside a leased sandbox, applies the governance policy of the registration through the governance integration of the library with fail-closed handling, sanitizes the result, denies the call as unbound on NOT_FOUND and fails fast with the class transient when the registry does not answer; the library is consumed by its pinned version and no protocol code is copied. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2432 Hosted MCP endpoint with authorization on by default and tool calls that enter the pipeline implementation The service hosts its MCP endpoint with the hosting of the pinned library: authorization is on and no anonymous exception is declared, the scope of the caller reaches every handler, a tool call requires factory.tools.invoke and, in I1, a token that carries the run, step and attempt identity (D121); a call bound to no run is refused before reception with a typed tool error and leaves no invocation and no event; a bound call enters the pipeline of ToolExecutor.Invoke with the caller kind agent, the tenant and the project of the token, the run, the step and the attempt from the scope accessor of the library, and an idempotency key taken from the request metadata of the call or derived from the session id of the connection and the request id, and a gated call waits for the approval of its run like every gated call; the caller kinds ide-client and partner-agent are not served before I5; a scope argument that contradicts the token is refused by the library with the typed tool error scope-mismatch, the tool list is the answer of McpRegistry.ListCapabilities for the scope of the caller, and the signing key is read from the secret reference mcp-signing-key. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2433 Fixture MCP server and fake registry of the acceptance suite fixture The acceptance suite holds a fixture MCP server on streamable HTTP that requires authorization, lists two tools and can return a result with an instruction and a secret pattern, a fixture stdio server command, and a fake of McpServerRegistryService that answers McpRegistry.ResolveTool with a binding, with NOT_FOUND or not at all and McpRegistry.ListCapabilities with an empty or a filled list (model/services/tools-mcp/McpServerRegistryService.yaml). ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2434 Verify the MCP executor and the hosted endpoint through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=McpToolsAndEndpoint"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-607: the authenticated client call through McpServerRegistryService/McpRegistry.ResolveTool and the credential port, the unbound and the unavailable registry, the sanitized hostile result, the refused anonymous client, the tool call of a token with a run, step and attempt identity that enters the pipeline of ToolAdapterService/ToolExecutor.Invoke with the caller kind agent and is listed under its run, the scope-mismatch refusal, the empty tool list of the thin registry, the supplied or derived idempotency key of a bound call, the same request repeated in one session that returns the existing receipt, a bound call of a gated decision that moves to AwaitingApproval, and the call of a token without a run identity, which is refused before reception, records no invocation, writes no ToolAdapterService/ToolInvocationDenied and executes nothing. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-608: Interrupt an executing call and settle it as observed, cancelled or uncertain, and never repeat an effect that could not be confirmed

behavior · persona operator As an operator, I want a call that was stopped, timed out or lost its host to be reported as what is known about its effect, so that nobody repeats a write that may already have happened.

A call that is executing can end without a result in four ways: the runtime interrupts it, its timeout fires, its sandbox is lost, or the replica that runs it crashes. In each the service settles the invocation as what it can prove and never as what it assumes. AgentRuntimeService calls the internal gRPC method ToolAdapterService/ToolExecutor.Interrupt when a run is cancelled or the call timeout of an attempt fires, with the invocation id under a workload token that holds the service scope that names ToolAdapterService. The grain stops the executor. When the tool had not started an effect, the invocation moves from Executing to Cancelled (trigger InterruptedBeforeEffect) with a receipt of status Cancelled and ToolInvoked in state Cancelled. When the result had already been observed, the invocation is Observed and stays so. When an effect may have happened and cannot be confirmed, the invocation moves to Uncertain (trigger EffectUnconfirmed). The reply is ack-v1 with the settled state, a repeated interrupt returns the same answer and changes nothing, and an invocation that is already terminal is answered with its state. A caller without a workload identity is refused with UNAUTHENTICATED, a token without the service scope with PERMISSION_DENIED, a request without an invocation id with INVALID_ARGUMENT, and an invocation that is unknown or of another tenant with NOT_FOUND, the same answer for both, for which the calling attempt takes the failure class permanent (ADR-0015 amendment D113). What decides between Cancelled, Failed and Uncertain is whether an effect was possible and whether it can be confirmed, and the rule follows the failure modes of the model, which make no exception for a class other than read. A tool of effective class read has no effect at any time: a stopped call of that class is Cancelled when it was interrupted and Failed with the failure class transient otherwise, which is the case the model describes as Failed when no effect was possible. For every other class, sandbox included, the executor of the tool tells its grain when it hands the call to the sandbox or to the owning service, the moment from which an effect may have begun. Before that moment an interrupt settles the invocation Cancelled and a timeout settles it Failed. After it, an invocation whose result was not observed is Uncertain, whatever stopped it. A lost sandbox and a crashed replica take away the only component that knew whether the effect had begun, so an invocation of a class other than read that they end is always Uncertain, as the two failure modes of the model state. The receipts follow the mapping of AIFACTORY-US-602: Cancelled is written with the status Cancelled, which tool-receipt-v1 has for an invocation that was interrupted before any effect (D121), a timeout without a possible effect with the status TimedOut, every other Failed with the status Failed and Uncertain with the status Uncertain. Another reading would let a sandbox-class call never end Uncertain, because its effect stays inside the workspace of the run and ADR-0014 amendment D114 allows the retry of a sandbox step. That reading is not taken, since it retries on a workspace that may be half written, and it is reported to the owner with two questions the model leaves open: what happens to a partly written workspace before a retry, and what RunControlService does with an Uncertain outcome on a step of class sandbox, for which ADR-0014 amendment D119 names no Operator decision. The same rule serves the other three ways. The reminder timeout of the grain fires at the timeout of the descriptor, or at Tools:Execution:DefaultTimeoutSeconds when it sets none, and stops the executor. A lost lease heartbeat means the sandbox is gone in the middle of the execution. The worker UncertainEffectReconciler runs every minute, partitioned by tenant with at most four in parallel, over the Executing invocations whose grain is inactive or whose timeout passed, which is how a crashed replica is found; it settles each one, idempotently on invocation id and state, with three retries at a fixed backoff of thirty seconds, and its sandbox is released by the reaper. An Uncertain invocation writes a tool-receipt-v1 with the status Uncertain and ToolEffectUncertain in the same transaction, and connectsoft.factory.tools.uncertain goes up. The service never repeats an Uncertain call and never repeats a write on its own. The attempt that made the call ends with the outcome Uncertain, reports it and waits for nothing; its outcome marks this invocation as the one whose effect is uncertain, in the optional member uncertainToolInvocationId of attempt-outcome-v1, and the approval request of the operator decision keeps that id (D123). RunControlService opens the operator decision for an Uncertain outcome on a step of class shared-write or above (ADR-0014 amendment D119), the Operator decides there with a finding, applied or not-applied, and RunControlService records that finding through ConfirmToolEffect for the invocation the request keeps, which moves the invocation out of Uncertain to Observed or Failed (AIFACTORY-US-609, D121). No operator acts in the tool service directly. The idempotency key of an Uncertain invocation stays taken, so the same call can never execute a second time under it. The model has no transition out of a state before Executing other than Denied, so an interrupt of an invocation that waits for its approval or its sandbox is answered with its state and changes nothing, which is reported to the owner.

Acceptance criteria

AC1 Given an Executing invocation of a read-class tool, and one of a sandbox-class tool whose executor has not yet handed the call to the sandbox, when ToolAdapterService/ToolExecutor.Interrupt is called under a workload token that holds the service scope, then the executor is stopped, each ToolAdapterService/ToolInvocation moves to Cancelled with a receipt of status Cancelled and ToolAdapterService/ToolInvoked in state Cancelled, the reply is ack-v1 with the settled state, and a repeated interrupt returns the same answer and writes nothing; a read-class call that its timeout reminder stops ends Failed with a receipt of status TimedOut (SCN-ToolAdapterService-009, FR-10).
AC2 Given an Executing invocation of effective class sandbox and one of class shared-write, each handed on by its executor and without an observed result, when it is interrupted or when its timeout reminder fires, and given an Executing invocation of either class whose sandbox lease loses its heartbeat, then it moves to Uncertain, a receipt with the status Uncertain is stored, ToolAdapterService/ToolEffectUncertain is written in the same transaction, connectsoft.factory.tools.uncertain is incremented and the service starts no second execution, under the same key or any other (SCN-ToolAdapterService-009, XL-06, ADR-0014).
AC3 Given an Uncertain settlement, when the outbox dispatcher publishes ToolAdapterService/ToolEffectUncertain on tool-execution.invocations.v1.tool-effect-uncertain, then the outbox record was written in the same transaction as the transition, the event is sent in the run event envelope with invocationId, tenantId, runId, attemptId, toolId and effectiveClass, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ToolAdapterService-014, ADR-0014).
AC4 Given Executing invocations whose grain is inactive after a replica crash, one of class read, one of class sandbox and one of class shared-write, when UncertainEffectReconciler runs, then the first is settled Failed with the failure class transient, a receipt of status Failed and ToolAdapterService/ToolInvoked, the other two Uncertain with a receipt of status Uncertain and ToolAdapterService/ToolEffectUncertain, a second run for the same invocation and state changes nothing, and the sandbox of each is released by the reaper while the workspace of the run stays (SCN-ToolAdapterService-014, model/services/tools-mcp/ToolAdapterService.yaml).
AC5 Given a caller without a workload identity, a token without the service scope, a request without an invocation id, or an invocation that is unknown or of another tenant, when ToolAdapterService/ToolExecutor.Interrupt is called, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT or NOT_FOUND respectively, the NOT_FOUND the same for an unknown and a foreign invocation, and no state changes; an invocation that is already terminal or still waits before execution is answered with its state and is not changed (SCN-ToolAdapterService-009, ADR-0015).
Traces: services ToolAdapterService
Traces: aggregates ToolAdapterService/ToolInvocation
Traces: apis ToolAdapterService/ToolExecutor.Interrupt
Traces: events ToolAdapterService/ToolEffectUncertain, ToolAdapterService/ToolInvoked
Traces: descriptors ack-v1, tool-receipt-v1
Traces: adrs ADR-0014, ADR-0015
Traces: requirements FR-10, FUX-07, XL-06, NFR-05
Traces: scenarios SCN-ToolAdapterService-009, SCN-ToolAdapterService-014
Depends on AIFACTORY-US-602, AIFACTORY-US-605, feature:contracts-package
Sources model/services/tools-mcp/ToolAdapterService.yaml, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#failure-and-recovery, docs/planes/capability-tools/tool-registry.md#the-executor-gw-05

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2435 ToolExecutor.Interrupt and the settlement rule of a stopped, timed-out or lost execution implementation ToolExecutor.Interrupt stops the executor of an Executing invocation through its grain and answers ack-v1 with the settled state, idempotently; the executor of every tool tells the grain when it hands the call to the sandbox or to the owning service; one settlement rule, which follows the failure modes of the model, serves the interrupt, the timeout reminder and the lost lease heartbeat: Observed when the result was observed; for a call of class read, Cancelled through InterruptedBeforeEffect on an interrupt and Failed with the class transient on a timeout or a lost sandbox; for a call of any other class, sandbox included, Cancelled on an interrupt and Failed on a timeout only before the hand-over, and Uncertain through EffectUnconfirmed after it and always when the sandbox was lost; each settlement writes its receipt with the status of the mapping of AIFACTORY-US-602 (Cancelled for Cancelled, TimedOut for a timeout without a possible effect, Failed, Uncertain) and its ToolInvoked or ToolEffectUncertain outbox record in one transaction; the refusals are UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT and NOT_FOUND, and an Uncertain invocation is never executed again. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2436 UncertainEffectReconciler over Executing invocations without a live grain or past their timeout implementation The worker finds the Executing invocations whose grain is inactive or whose timeout passed on its one-minute schedule, partitioned by tenant with at most four in parallel, applies the settlement rule of AIFACTORY-TASK-2435 for a lost grain, by which an invocation of class read is settled Failed with the class transient and an invocation of any other class, sandbox included, Uncertain, writes ToolEffectUncertain or ToolInvoked in the transaction of the settlement, is idempotent on invocation id and state, retries three times with a fixed backoff of thirty seconds, and moves connectsoft.factory.tools.uncertain with every Uncertain settlement. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2437 Verify interruption and uncertain effects through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolAdapterService-009\|Scenario=SCN-ToolAdapterService-014)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-608 with fake executors that block before and after the hand-over of the call, for the classes read, sandbox and shared-write, a fired timeout reminder, a lost lease heartbeat, a deactivated grain, the publication and payload of ToolEffectUncertain with a stopped transport, the four refusals and the assertion that no second execution starts for an Uncertain invocation; every receipt is asserted on its status and validated against docs/reference/schemas/tool-invocation.schema.json: Cancelled for a Cancelled invocation, TimedOut for a read-class call its timeout stopped, Failed for a read-class call of a lost sandbox or a crashed replica, and Uncertain for every invocation settled Uncertain; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-609: RunControlService records the finding of the Operator on an Uncertain invocation, applied or not-applied, and the invocation is settled with a receipt

behavior · persona operator As an operator, I want the finding I give with my decision at Run Control, from the receipt and from what I find in the target system, to settle the uncertain invocation in the tool service, so that the run continues from a known fact and the write is never repeated on a guess.

An Uncertain invocation waits for a finding, and the finding comes from one act of the Operator (D121). The Operator of the project decides the operator decision that RunControlService opened for the Uncertain outcome of the step, with the tool receipt in view (AIFACTORY-US-610), and states with that decision whether the effect was applied or not. RunControlService records the finding in the tool service as part of the same act by calling ToolAdapterService/ConfirmToolEffect for the invocation, which is the one the Uncertain outcome of the attempt marked in uncertainToolInvocationId and whose id the approval request of the operator decision keeps (D123). No operator acts in the tool service directly: the operation is internal, its one caller is RunControlService and the Studio offers no confirmation of its own. RunControlService calls through ToolExecutorHost under its workload token, which holds the scope factory.tools.operate and the service scope that names ToolAdapterService, and forwards the tenant and the project of the run, which the tool service reads only under that service scope (ADR-0015 amendment D114); the token names the Operator who decided as the user on whose behalf the workload acts. This token is decided (D123): for ConfirmToolEffect RunControlService presents a workload token that holds factory.tools.operate and names the Operator as the user it acts for, and the value operator of callerKind stays. The body states the finding, applied or not-applied, and the reason the decision carries. Whether the decider was eligible, as the Operator of the project or as the member who requested the run, is checked by RunControlService and not again here. The command applies to an invocation in state Uncertain only. It records the finding, the Operator as the actor and the reason on the invocation, writes the final tool-receipt-v1 and settles the invocation: the finding applied moves it from Uncertain to Observed (trigger EffectConfirmedApplied) with the status Succeeded, and the finding not-applied moves it from Uncertain to Failed (trigger EffectConfirmedNotApplied) with the status Failed, by the mapping of AIFACTORY-US-602. ToolInvoked is written in the same transaction with the settled state, which is the result event the model names for this command, and connectsoft.factory.tools.uncertain goes down. The audit stage writes one evidence record of the finding through the sink of the pinned audit library, as AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in the transaction of the command, with the Operator as actor, the invocation and its request hash as subject and the finding as outcome. A decision without a finding never reaches the tool service, because RunControlService answers it 400, and when the tool service does not answer the call, RunControlService answers the decision 503 and records nothing, so that the Operator takes the decision again and the call arrives again; the decision and the finding therefore never diverge (D123). The command is naturally idempotent, which RunControlService relies on when it repeats the call after a lost answer or after such a repeated decision: the same finding posted again returns the same result and writes nothing; a different finding for an invocation that a finding already settled, and a finding for an invocation that is not Uncertain, are refused with 409. A call without a token is answered 401; a token without factory.tools.operate, and every user token, because the operation admits no caller but RunControlService, 403; an invocation that is unknown or of another tenant 404, the same answer in both cases (ADR-0015 amendment D113). The command executes nothing and repeats nothing. What follows for the step is the choice the Operator made in the same decision, retry, compensate or fail: RunControlService refuses the choice retry unless the finding is not-applied, and a retry is a new call of the runtime under a new idempotency key, because the key of the settled invocation stays taken. The action values of audit-evidence-v1 name none for the finding on an effect, which is reported with the question of AIFACTORY-US-602.

Acceptance criteria

AC1 Given an Uncertain ToolAdapterService/ToolInvocation and the operator decision of its run, a RunControlService/ApprovalRequest that keeps the id of that invocation in uncertainToolInvocationId and that the Operator decided through RunControlService/DecideApproval with the finding applied, when RunControlService calls ToolAdapterService/ConfirmToolEffect for that id under its workload token, which holds factory.tools.operate and names the Operator as the user it acts for (D123), with the finding applied and the reason of the decision, then the response is 200, the invocation moves from Uncertain to Observed through EffectConfirmedApplied with the finding, the actor and the reason recorded, the final receipt carries the status Succeeded, ToolAdapterService/ToolInvoked is written in the same transaction and connectsoft.factory.tools.uncertain is decremented (SCN-ToolAdapterService-006, FR-10).
AC2 Given the same invocation and the finding not-applied, when RunControlService calls ToolAdapterService/ConfirmToolEffect, then the invocation moves from Uncertain to Failed through EffectConfirmedNotApplied with a receipt of status Failed, ToolAdapterService/ToolInvoked carries the state Failed, and the service starts no execution; a later call of the runtime for the same step under a new idempotency key, after the Operator chose retry, is a new invocation, while the key of the settled one still returns its receipt (SCN-ToolAdapterService-006, XL-06).
AC3 Given a call without a token, a workload token without factory.tools.operate, the user token of an Operator, an invocation that is unknown or of another tenant, an invocation that is not Uncertain, or a different finding for an invocation that a finding already settled, when ToolAdapterService/ConfirmToolEffect is called, then the response is 401, 403, 403, 404, 409 or 409 respectively with a problem response and no state changes, so no operator acts in the tool service directly; the same finding posted again by RunControlService returns 200 with the same result and writes nothing, which is also the answer when the Operator repeats a decision that RunControlService answered 503 because the answer of the first call was lost (SCN-ToolAdapterService-006, ADR-0015, D123).
AC4 Given a finding was recorded, when the outbox of its transaction is read, then it holds one AuditEvidenceSubmitted record for audit.evidence.v1.evidence-submitted with the Operator as actor, the invocation and its request hash as subject and the finding, applied or not-applied, as outcome, shaped as docs/reference/schemas/audit-evidence.schema.json states and without arguments or result (SCN-ToolAdapterService-006, ADR-0019).
Traces: services ToolAdapterService, RunControlService
Traces: aggregates ToolAdapterService/ToolInvocation, RunControlService/ApprovalRequest
Traces: apis ToolAdapterService/ConfirmToolEffect, RunControlService/DecideApproval
Traces: events ToolAdapterService/ToolInvoked
Traces: descriptors tool-receipt-v1, audit-evidence-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0019
Traces: requirements FR-10, FUX-07, XL-06, NFR-04
Traces: scenarios SCN-ToolAdapterService-006
Depends on AIFACTORY-US-608, AIFACTORY-US-610, feature:run-control-service, feature:component-audit-factory-evidence, feature:contracts-package
Sources model/services/tools-mcp/ToolAdapterService.yaml, model/services/control-plane/RunControlService.yaml, docs/reference/schemas/approval.schema.json, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2438 ConfirmToolEffect as the internal operation of RunControlService with the finding, the settlement of the Uncertain invocation and its evidence record implementation ConfirmToolEffect is an internal operation whose one caller is RunControlService (D121): it accepts the finding (applied or not-applied) and the reason of the operator decision for an Uncertain invocation, requires the workload token of the caller with factory.tools.operate and the service scope, under which it reads the forwarded tenant and project, takes the Operator from the user the token names as the one the caller acts for, the value operator of callerKind staying (D123), and refuses a user token with 403; it records the finding, the Operator the caller acts for as actor and the reason, writes the final receipt, settles the invocation to Observed through EffectConfirmedApplied or to Failed through EffectConfirmedNotApplied with its ToolInvoked outbox record and one AuditEvidenceSubmitted record in one transaction, moves connectsoft.factory.tools.uncertain down, returns the same result for the same finding posted again, and answers 401, 403, 404 (also for an invocation of another tenant, ADR-0015) and 409 as the PBI states; it starts no execution. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2439 Verify the confirmation of an uncertain effect through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ToolAdapterService-006"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-609 with a caller that stands for RunControlService, over the matrix of token kind and tenant: both findings with their transitions out of Uncertain, each sent under a workload token that holds factory.tools.operate and names the Operator as the user the caller acts for (D123), the idempotent repeat, the six refusals, among them the user token of an Operator, the evidence record in the outbox and the assertion that no execution starts and that a new key is a new invocation. ConnectSoft.AI.SoftwareFactory.ToolAdapterService

AIFACTORY-US-610: Read the tool receipts of a run and one invocation with its pipeline stages, sandbox lease and receipt

behavior · persona requester As a requester, I want to see every tool call of my run with its class, decision, approval, outcome and hashes, so that I can account for what the agents did and open the one call I need to understand.

A caller whose scope carries factory.runs.read reads what the executor recorded. ToolAdapterService/ListRunToolReceipts returns the receipts of a run, paged in the order the calls were received: for each invocation the tool id and version, the effective class, the policy decision id, the approval id when the call was gated, the outcome, that is the state with the failure class or the denial stage and reason where there is one, and the request hash, the result hash and the receipt reference. ToolAdapterService/GetToolInvocation returns one invocation: its scope, caller kind, declared and effective class, the pipeline stages it passed with the time of each, its sandbox lease with kind, pool, limits and the times it was leased and released, and its receipt. Neither answer inlines arguments or results. The service stores hashes and artifact references only, and the caller fetches a result from ArtifactService under its own scope; a credential is in no row and therefore in no answer. Both reads run under the tenant row filter and admit a caller only for a project the token grants a role in, since every invocation carries its project. The user token is forwarded by ToolExecutorHost unchanged. A call without a token is answered 401, a token without factory.runs.read or without a role in the project of the run or the invocation 403, and an invocation that is unknown or of another tenant 404, the same answer in both cases (ADR-0015 amendment D113). The executor owns no run: ListRunToolReceipts answers 404 when it holds no invocation of that run in the tenant of the caller, which is also the answer for a run of another tenant and for a run that called no tool. Nothing is written by a read. The receipts are kept as the model states: one year by default, and seven years where audit evidence references them. The Studio run detail reads through these two operations, and so does the Operator who decides an uncertain outcome at RunControlService with the tool receipt in view (D121).

Acceptance criteria

AC1 Given a run of my project with an observed, a denied, a gated and an uncertain invocation and a caller with factory.runs.read and a role in that project, when ToolAdapterService/ListRunToolReceipts is called, then the response is 200 with the four receipts in the order of reception, each with tool id, version, effective class, policy decision id, approval id where gated, outcome, request hash, result hash and receipt reference, paged, without arguments or results (SCN-ToolAdapterService-004, FR-05).
AC2 Given one ToolAdapterService/ToolInvocation of my project that ran in a sandbox, when ToolAdapterService/GetToolInvocation is called, then the response is 200 with its scope, caller kind, declared and effective class, the pipeline stages it passed with their times, the sandbox lease with kind, pool, limits, leased and released times, and the receipt, and no argument, result or credential is in the answer (SCN-ToolAdapterService-005, ADR-0019).
AC3 Given a call without a token, a token without factory.runs.read or without a role in the project, and a run or an invocation that is unknown or of another tenant, when ToolAdapterService/ListRunToolReceipts or ToolAdapterService/GetToolInvocation is called, then the response is 401, 403 or 404 with a problem response, the 404 the same for an unknown and a foreign id, and no state changes (SCN-ToolAdapterService-004, SCN-ToolAdapterService-005, ADR-0015).
AC4 Given invocations of two tenants and of two projects of one tenant, when each caller lists and reads, then a caller receives only the receipts of the tenant of its token and of the projects it holds a role in, and nothing is written by any read (SCN-ToolAdapterService-004, ADR-0015).
Traces: services ToolAdapterService
Traces: aggregates ToolAdapterService/ToolInvocation
Traces: apis ToolAdapterService/ListRunToolReceipts, ToolAdapterService/GetToolInvocation
Traces: descriptors tool-receipt-v1
Traces: adrs ADR-0015, ADR-0019
Traces: requirements FR-05, NFR-04, NFR-10
Traces: scenarios SCN-ToolAdapterService-004, SCN-ToolAdapterService-005
Depends on AIFACTORY-US-602
Sources model/services/tools-mcp/ToolAdapterService.yaml, docs/reference/schemas/tool-invocation.schema.json, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#data-model-and-storage, docs/planes/capability-tools/tools/services/tool-adapter-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2440 ListRunToolReceipts and GetToolInvocation read model with tenant row filter, project admission and paging implementation ListRunToolReceipts returns the receipts of a run paged in the order of reception with tool id, version, effective class, policy decision id, approval id, outcome, request hash, result hash and receipt reference; GetToolInvocation returns one invocation with its pipeline stages, sandbox lease and receipt; both apply the tenant row filter and admit only a project the token grants a role in, answer 401, 403 and 404 (also for a run or an invocation of another tenant, ADR-0015), inline no argument or result and write nothing. ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-2441 Verify the receipt reads through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ToolAdapterService-004\|Scenario=SCN-ToolAdapterService-005)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-610 over the two-tenant, two-project invocation fixture with an observed, a denied, a gated and an uncertain invocation, the three refusals and the assertion that no answer holds an argument, a result or a credential. ConnectSoft.AI.SoftwareFactory.ToolAdapterService