Your coding agent, your project

This excerpt adapts the companion’s registered binding; ApplicationCodingAgentBinding is its application-owned type. The matching execution profile must be authored in runtime configuration. It keeps provider, model and execution profile together. A coding agent requires executionProfileRef; unlike a language-model API call, it cannot omit the authority and environment under which its subprocess runs.

const codingAgentBinding = {
  ref: 'application-coding.agent',
  displayName: 'Application Coding Agent',
  providerRef: 'anthropic',
  executionProfileRef: 'claude-code-acp',
  model: LLM_Model.CLAUDE_OPUS_5,
} satisfies ApplicationCodingAgentBinding;

The ACP runner negotiates the protocol, opens or resumes the session, exchanges turns and answers permission requests. Enforcement depends on which callbacks the provider actually raises. The dispatch layer checks the provider’s declared permission-escalation behavior before accepting a restrictive ceiling. Do not describe mutation scope as an operating-system sandbox: a child doing its own I/O without a relevant callback is a different boundary, and the recorded run/change set remains important.

Author the matching companion execution profile

The binding above names claude-code-acp. Declare that same key under providerConfigurations.anthropic[ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL].executionProfiles in wildo.saas.config.ts. This selected profile follows Wonder Todos’ development setup; the omitted settings govern recording and data-processing declarations, not provider selection. The AgentClientProtocol_* enums, APPLICATION_ENVIRONMENT and ExternalProvider_ExchangeProtocol_Kind come from @wildo-ai/external-connectors-models.

providerConfigurations: {
  anthropic: {
    [ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL]: {
      defaultExecutionProfileRef: 'claude-code-acp',
      executionProfiles: {
        'claude-code-acp': {
          runnerHost: AgentClientProtocol_RunnerHost.BACKEND_SUBPROCESS,
          authMode: AgentClientProtocol_AuthMode.HOST_MANAGED,
          allowedApplicationEnvironments: [APPLICATION_ENVIRONMENT.DEVELOPMENT],
          workingDirectoryPolicy: AgentClientProtocol_WorkingDirectoryPolicy.WORKSPACE_ROOT,
          permissionCeiling: AgentClientProtocol_PermissionCeiling.UNRESTRICTED,
          hostConfigurationInheritance: AgentClientProtocol_HostConfigurationInheritance.APPLICATION_SCOPED,
          turnTimeoutMs: 30 * 60_000,
          maxAutoContinuations: 12,
          awaitingInputTtlMs: 30 * 60_000,
        },
      },
    },
  },
},

HOST_MANAGED uses the operator’s existing agent login. The provider owns its launch command; the host supplies the workspace at invocation. The unrestricted ceiling admits all tool categories; declared locations and available approval options still govern individual requests. It is not a sandbox: filesystem confinement still depends on participating callbacks, and the host must inspect the resulting changes.

Enable EngineCapability.AI_CODING_AGENT, then merge this entry into providers.scopes.companion.providers. EngineCapability comes from @wildo-ai/saas-models. An AI_LLM backend entry cannot substitute for this companion transport:

anthropic: {
  engineCapabilities: [EngineCapability.AI_CODING_AGENT],
  providerCapabilities: ['CODING_AGENT'],
  protocols: ['AGENT_CLIENT_PROTOCOL'],
},

Run wildo config sync after configuration changes. The host needs the provider’s supported agent installation and login before dispatch; selecting a model does not install or authenticate the subprocess. Application runtime language generation has its own backend provider setup.

Dispatch the task in a trusted workspace

The companion constructs this invocation after admitting its typed task and rendering the task prompt. A resumed run supplies the operator’s answer and the existing session ID; a new run supplies the rendered task.

const invocation: FlowsActors_Agent_Invocation<
  typeof CodingAgent_RunTaskInputSchema,
  typeof CodingAgent_RunTaskOutputSchema,
  typeof CodingAgent_OperationContext_BaseSchema
> = {
  agentRef: APPLICATION_CODING_AGENT_REF,
  initiator: {},
  invocationContext: [],
  input: resume
    ? { prompt: resume.answerPrompt, continuationOfSessionId: resume.continuationOfSessionId }
    : { prompt: renderedPrompt },
  output: { finalMessage: '', stopReason: CodingAgent_StopReason.END_TURN },
  executionContext: { callTimestamp: new Date().toISOString() },
  artifactBindings: [],
};

The call also receives the trusted workspace and task-location predicate. This reduced excerpt omits the companion’s event collection and turn-classification callbacks; it shows where workspace and cancellation enter the runtime:

const response = await this.agentsService.invokeAgent(
  invocation,
  traceContext,
  {
    workspaceRootPath: this.companionContext.saasRoot,
    isPermittedCodingLocation: buildApplicationCodingTaskLocationPredicate(
      this.companionContext.saasRoot,
      task.mutationScope.allowedPathPrefixes,
      task.mutationScope.prohibitedPathPrefixes,
    ),
    ...(this.activeRun ? { codingSessionAbortSignal: this.activeRun.abortController.signal } : {}),
  },
);
const codingOutput = response.output as Partial<CodingAgent_RunTaskOutput> | undefined;
const text = codingOutput?.finalMessage;
const stopReason = codingOutput?.stopReason;

finalMessage is not itself acceptance of the changes. The host checks the stop reason, records the run and inspects the resulting change set. A parked run is asking for input, not reporting a finished implementation. Permission callbacks constrain participating operations; they do not turn arbitrary subprocess I/O into a filesystem sandbox.

Set the ceiling in the ACP execution profile referenced by the coding-agent binding. This is a selected configuration fragment; the profile also needs the provider, runner, authentication and environment settings described in coding-agent setup.

executionProfiles: {
  'reviewed-edits-acp': {
    // Other required execution-profile settings belong here.
    permissionCeiling: AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS_AND_EDITS,
  },
},

AgentClientProtocol_PermissionCeiling is exported by @wildo-ai/external-connectors-models. The agent binding must name this profile. After changing application configuration, run wildo config sync and verify the companion is using the updated profile before dispatch.

Match the policy to the work

These are tool-kind policies. Reads and edits are different sets, not successive levels of the same permission. An invocation override retains only operations admitted by both policies. Requesting reads from an edit-only profile therefore grants neither reads nor edits; it cannot turn the override into new access. Leaving the override absent retains the profile’s policy.

Follow an individual decision

The runner applies the ceiling first, then the task’s location predicate, then selects an acceptable one-time approval. The following selected source shows the separate scope and approval steps after the ceiling has passed:

if (options.isPermittedLocation && locations.some((path) => !options.isPermittedLocation!(path))) {
  record(false, ACPPermissionDecisionReason.LOCATION_OUT_OF_SCOPE);
  return { allowed: false };
}

const once = rawOptions.find((entry) => isRecord(entry) && entry.kind === 'allow_once');
if (isRecord(once) && typeof once.optionId === 'string') {
  record(true, ACPPermissionDecisionReason.ALLOWED_ONCE);
  return { allowed: true, optionId: once.optionId };
}
record(false, ACPPermissionDecisionReason.NO_SELECTABLE_OPTION);
return { allowed: false };

The runner does not select an allow_always option that could change later decisions. Its bounded decision record includes the declared tool kind, locations, offered options and result. Direct client filesystem writes also check the edit ceiling and the location predicate, even if the agent sends no permission request first. Read-only policies do not advertise client write support; attempts to use it are still refused and recorded.

Check whether the provider can participate

The provider contract declares whether the agent raises permission requests before mutation. Dispatch checks that declaration and the composed environment. A restrictive ceiling is refused when those guards cannot fire; a conditionally escalating provider needs its configuration pointer present in the child environment.

UNRESTRICTED deliberately permits that broader execution. It does not create a filesystem sandbox. An agent performing its own I/O without callbacks, or an allowed shell command declaring no locations, does not receive a per-file scope check from these permission decisions. Inspect the resulting changes and run warnings as well as the configured policy.

The host-side admission probe tests refusal against an actual filesystem result. Use the supported arguments shown by the installed CLI before evaluating a new adapter or configuration:

wildo acp probe --help

A provider declaration tells dispatch how to proceed; a probe checks the behavior behind it. Re-evaluate that behavior when the adapter or its host configuration changes.

Admission holds the lock through execution

The companion admits a typed application coding task, resolves its required checks, and takes the application’s workspace-mutation lock before capturing its baseline and creating the durable task. An in-memory active-run check provides a fast conflict response; the file lock coordinates separate processes.

The lock remains held while the managed execution runs and records its outcome. Resuming a suspended coding session reacquires the same lock. A new request is not queued as a future coding run.

Why the command line participates

Configuration sync can rewrite generated application files from a different process. This selected fragment from the sync command shows it using the shared lock helper around its actual sync work:

try {
  return await withDedicatedFileLock(
    getWorkspaceMutationLockPath(saasRoot),
    runSyncDomains,
    { retries: { retries: 2 } },
  );
} catch (error) {
  if ((error as { code?: string })?.code === 'ELOCKED') {
    ctx.log.error(
      `The workspace-mutation lock is held (${getWorkspaceMutationLockPath(saasRoot)}) — `
      + 'an active coding-agent dispatch run or another worktree-writing command owns the '
      + 'application worktree right now. Retry after it completes.',
    );
    return { success: false };
  }
  throw error;
}

The highlighted call coordinates the real writer, rather than checking a flag and then writing later. Contention becomes an actionable command outcome. The companion maps its corresponding lock conflict to the conflict response vocabulary, rather than treating it as a successful admission.

Keep the unit of coordination clear

The lock applies to the application, not individual files or modules. Two managed coding tasks with disjoint declared scopes are still serialized. That same scope-independent exclusion prevents an active dispatched task from recursively starting another managed coding run.

A permission profile and a mutation scope answer different questions: what the agent may request, and where its task is intended to write. The shared lock answers when participating writers may proceed. It does not turn a shell into an isolated environment or stop an external editor.

Do not assume every companion generator participates in this coding lock. Schedule other file-producing work outside the capture window when it can change the application files being reviewed.

Review after the run settles

Wait for the active run to finish or use its supported cancellation flow before starting competing managed work. Do not remove a live lock to force a second writer through. Use the captured changes to inspect the outcome and any overlapping manual edits, then run the checks relevant to the change.

Understand how the starting brief is assembled

The build dispatch composes sources from the task and its target. The source categories are declared in code; their contents vary with the application and task. This is distinct from a model autonomously choosing every source before a run.

The workspace and domain-plan sources are best effort. If introspection fails or the relevant plan is absent, dispatch can continue with the remaining sources. The host logs failures; absence of a source is not proof that the application has no matching resources.

Inspect before choosing an identifier

Run these commands from the application workspace with its companion available:

# Discover the queries exposed by this running companion.
wildo context list

# Read registered resources rather than inventing their names.
wildo context info resources-registry

# Inspect relationships between accepted product declarations.
wildo context coherence

The registry snapshot describes what the companion can currently introspect. The domain plan describes intended structure. Keep those two meanings separate when deciding whether a task creates a resource or enriches one already registered.

Keep scope and context as separate inputs

This selected framework excerpt shows the boundary between supplied content and the mutation/check policy:

export interface BuildTaskCodingBoundary {
  readonly allowedPathPrefixes: readonly string[];
  readonly prohibitedPathPrefixes: readonly string[];
  readonly requiredCheckRefs: readonly string[];
}

export interface BuildTaskContextSource {
  readonly sourceRef: string;
  readonly originRef: string;
  readonly content: unknown;
}

composeBuildTaskCodingContract combines those inputs with the typed build task. It refuses a missing target, a companion generation task assigned to a coding agent, an empty allowed scope, missing required checks or an empty context set. Task skills are translated to namespaced references for the coding contract.

Every selected source is mandatory in this composer. Its token figure is a coarse estimate derived from serialized content and summed across the selected sources; it does not trim content to a configurable spending limit. Model safety also remains the source selector’s responsibility: the composer labels supplied content SAFE_FOR_MODEL without inspecting it. Do not use that label as a content-classification or secret-redaction service.

Configure the research posture separately

The research agent uses its own execution profile. These selected settings appear in the Wonder CRM research profile; the complete configuration also supplies the provider launch details and model destinations:

permissionCeiling: AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS_AND_EDITS,
hostConfigurationInheritance:
  AgentClientProtocol_HostConfigurationInheritance.ISOLATED,
turnTimeoutMs: 15 * 60_000,
maximumRecordedEventBytes: 2 * 1024 * 1024,

The permission ceiling admits recognized reading, searching, fetching and thinking tools, plus edits. It excludes command execution and unclassified tool kinds. The host restricts declared filesystem access to specifications/research-evidence/. It applies the same evidence boundary to direct client reads and writes, including callbacks sent without a permission request. A refused read is recorded as a scope denial; research can persist findings without receiving general workspace access.

These controls depend on the adapter exposing the relevant permission requests or client filesystem operations. Wildo’s provider compatibility checks and execution profile matter here as they do for coding. An isolated host configuration controls inherited agent guidance; it does not mean an offline run or a local model.

Keep findings across research rounds

Each request has an objective and can name an evidenceScope for the investigation. The companion resolves the scope to a directory and adds the same evidence-store instructions to each round:

specifications/
  research-evidence/
    provider-selection/
      published-plans.md
      usage-conditions.md

This is an illustrative directory layout. The agent is instructed to read existing findings first, write coherent topic files as it works and keep source URLs beside findings. The store sits outside the specification TypeScript source tree, so a research note does not become a typed product declaration.

At the end of a non-cancelled run, the companion also attempts to save the final brief with its objective, timestamp, elapsed time, stop reason and optional playbook reference. A failed backstop write is logged and can leave persistedEvidencePath empty; callers should inspect that field before reporting that a durable record exists.

Interpret research results before accepting them

A cancelled final response is not saved as a completed brief. Files already written during the run remain available for inspection. Research can run alongside coding; the coding change-set logic records research-store changes as a concurrent host lane and excludes them from the coding task’s mutation-scope decision.

Choose which findings enter the product definition through the appropriate review and validation process. Neither a source URL nor successful persistence establishes the truth of a claim. The turn timeout stops a runaway turn; it is not a token or monetary budget.

Enable the check on the method that needs it

The existing refinement.compliance-document-candidate playbook contains this method excerpt. This is selected configuration from the framework catalogue, not a complete standalone playbook:

{
  "contextSources": ["document_blueprint"],
  "briefAdequacyGate": true,
  "briefAdequacyExcludedSources": ["compliance_primary_facts"],
  "skillRefs": ["compliance-document-authoring"]
}

briefAdequacyGate defaults to false. The source exclusion preserves an intentional information boundary: this document drafter works from accepted document facts rather than interpreting raw resource mechanisms as new statements about the application.

Follow one check and one recomposition

The companion composes the generation outputs, then asks the brief-adequacy judge about the first output’s brief. The judge receives the brief and a menu of undeclared, non-excluded context sources. Its structured response names a verdict and proposed missing sources.

This selected runtime excerpt shows the add-only update:

const declared = new Set(playbook.method?.contextSources ?? []);
const excludedSources = new Set(playbook.method?.briefAdequacyExcludedSources ?? []);
const addedSources = judged.missingSources.filter((source) => !declared.has(source) && !excludedSources.has(source));
if (judged.verdict === BriefAdequacyVerdict.INSUFFICIENT && addedSources.length > 0) {
  const widened = {
    ...playbook,
    method: { ...playbook.method, contextSources: [...declared, ...addedSources] },
  } as typeof playbook;
  outputs = await composeGenerationOutputs(widened);
}

The effective declaration is a union for this run. The stored playbook is not rewritten, declared sources are not removed, and the same composers build the expanded outputs. There is no recursive planner loop.

Read the verdict for what it establishes

The companion logs the verdict and added sources, including an unavailable result. This is advisory assistance for input quality, not an artifact acceptance gate: the artifact still needs its own validation and review.

The mechanism selects from the declared context-source vocabulary. It does not invent new input families, browse arbitrary sources, or automatically plan context for every coding task. Coding dispatch separately supplies task-specific initial context and a live-query door for the agent to use.

How a run gets its baseline

The companion captures a working-tree snapshot before invoking the coding agent, then captures the result after execution. Dirty tracked files have a fingerprint derived from their diff; untracked files use their content. The comparison excludes files that were already dirty but did not change again.

This selected fragment from the capture service shows the distinction. It runs inside the per-file comparison; the surrounding method also handles new files, committed paths and summary statistics:

const changedDuringRun = baselineState.fingerprint !== postState.fingerprint
  || baselineState.changeKind !== postState.changeKind;
if (!changedDuringRun) {
  // Dirty before the run, untouched during it — not part of this
  // run's change set at all.
  continue;
}

entries.push({
  path,
  changeKind: postState.changeKind,
  attribution: ownedByConcurrentLane
    ? ChangeSetAttributionClass.CONCURRENT_HOST_LANE
    : ChangeSetAttributionClass.BASELINE_DIRTY_AMBIGUOUS,
  dirtyAtBaseline: true,
  ...(postState.fingerprint !== undefined ? { postRunFingerprint: postState.fingerprint } : {}),
  ...(postState.sizeBytes !== undefined ? { sizeBytes: postState.sizeBytes } : {}),
});

The first highlighted region removes unrelated pre-existing work. The second retains a changed file while distinguishing an ordinary overlap from a path owned by a concurrent companion lane.

Interpret the attribution before accepting the work

These are observations about time and location, not an operating-system record of which process wrote a byte. Even a clean starting file can be edited by an external session during the window. The research classification likewise comes from the path’s owner, not proof that a research process made that particular write.

Follow the change set into the result

The structured task artifact retains paths, classifications, starting and ending commit positions, and post-run fingerprints. Full diff text belongs to the verbose trace artifact. The agent’s reported file locations remain a separate claim; they do not replace the workspace capture.

The post-run scope assessment checks observed changes against the task’s declared scope, including baseline-dirty files that changed again. Uncertain authorship does not exempt a path from that check. It excludes committed-window entries and concurrent research-store paths, while recording those conditions. A baseline-dirty file disappearing also receives separate handling when history moved.

This assessment detects observed effects after execution. It does not prevent shell commands from making those changes. Review the permission policy alongside the change set when deciding how the agent may work.

Preserve a useful review window

Avoid committing unrelated work during a coding run when practical: moving the commit position makes ownership harder to establish. Capture uses a guarded read-only Git command set and selected ignored paths, rather than staging files to discover them. Host bookkeeping is deliberately separated from application edits.

Use the actual diff and the task’s required checks to judge the result. A captured file list explains what moved; it does not establish that the feature works.

Recorded playbook output has its own recovery path

The playbook landing service records generated specification files, their export-wiring changes, the refreshed coherence report and generated review diagrams. For each file it keeps the path, whether it existed, its previous content and the content written by the run.

This is distinct from a coding agent’s observed change set. Arbitrary coding-agent edits do not enter this register; review and recover those through version control. A register write is best-effort after landing, so inspect the available run record before relying on its undo action.

Inspect the record before requesting a revert

The workbench exposes run-write records and a revert action. Its resource operation and the companion route reach the same service. The companion also provides GET /runs/writes, returning run identifiers, playbook references, timestamps and file summaries; previous file contents stay in the local register.

The following is an illustrative request sequence relative to the authenticated companion API mount. Substitute an actual listed run identifier; it is not a public application endpoint:

GET /runs/writes

POST /runs/writes/run-example/revert
Content-Type: application/json

{ "force": false }

The response separates reverted from refusedDiverged. A response with refused files means only part of the run was undone. Read those paths before taking another action.

How the content comparison protects an edited file

This selected service fragment shows the actual restore decision. The surrounding method loads the record and collects the outcome for every file:

const createdFileAlreadyAbsent = !file.existedBefore && current === undefined;
if (options.force !== true && !createdFileAlreadyAbsent && current !== file.writtenContent) {
  refusedDiverged.push(file.path);
  continue;
}
if (file.existedBefore && file.previousContent !== undefined) {
  await writeFile(absolutePath, file.previousContent, 'utf8');
} else {
  await unlink(absolutePath).catch((error: NodeJS.ErrnoException) => {
    if (error?.code !== 'ENOENT') throw error;
  });
}
reverted.push(file.path);

An overwritten file with different content—or one deleted afterwards—is refused unless force is explicitly true. A newly created file that is already absent is settled without recreating it.

Treat partial undo as a review step

Files are processed individually, not in one atomic filesystem transaction. After a partial outcome, the register retains only refused paths and their saved contents. A retry acts on those remaining files; it does not revisit earlier restored files or overwrite later edits to them, even when the retry uses force.

Force is a deliberate replacement of current content, not a merge. Preserve any wanted changes before using it. The register is local development convenience in the companion’s ignored state directory; Git remains the record of accepted work.