2026-10-16. Design review of agent-tools at 15e7709997, including the 11:44 forum proposal.

Decision

Keep the same MCP functions and their meanings. Default to a usable remote-checkout workflow; local preparation is an optional fast path. Make descriptions and next steps reflect an existing local clone, a feasible new local clone, or remote-only work. A remote call must never silently become an operation on the caller's filesystem.

Do not remove ocx_commit_and_sync and ocx_commit_and_sync_guide on the present evidence. Consolidating documentation can help agents, but the local helper prepares a tested commit and bundle while remote ocx_sync publishes it. These operations are complementary. Removing the helper transfers work to shell instructions.

The no-recorded-use premise needs correction. MechanicalTurk's 2026-10-15 feature-needs report records the guide as confirmed working. That establishes guide use, not adoption of both helpers or a permanent need for the guide. Lack of observed helper use does not prove redundancy.

Demonstrate first and second tasks in all three situations before removing a helper. Measure preparation, publication, recovery and reuse, rather than tool count alone.

Three situations and one command surface

Caller situation	Recommended next step	Publication path	Required explanation
Local clone exists	Optionally reuse it after checking identity, base, branch and changes	Local commit and bundle, then remote ocx_sync	Local preparation and the connected MCP checkout can be different locations
No local clone, cloning feasible	Optionally bootstrap plain Fossil from the verified read URL and base	Same preparation and remote ocx_sync	Supply bootstrap steps; do not require a build or new local MCP registration
Local clone not feasible	Use the run's ocx_context, ocx_find, ocx_read, ocx_edit, ocx_test, ocx_save	ocx_save commits and pushes remotely	Unknown local feasibility uses this same route, with a distinct reason

The remote server cannot inspect the caller's shell or filesystem. Only if local execution tools are already available, let the caller perform one bounded check and report clone_available, setup_feasible, or unknown_or_unavailable. Use existing evidence of Fossil, writable storage, permitted read access and authorization; do not install, build or repeatedly explore merely to classify. Unknown stays on the remote path. Preserve a reason distinguishing “not checked” from a verified blocker. A weak agent must not solve its local environment before doing useful work.

The connected endpoint inspected here still lacks checkout edit/test/save tools. This explicitly blocks the default remote path on that connection. Their presence in 15e7709997 does not make them callable there: verify a suitable endpoint release before claiming the workflow works. A feasible authorized local path remains an option, not a reason to conceal that deployment gap.

Contextual descriptions using the same functions

These are proposed descriptions for the same functions, not new APIs. Keep schemas and behavior consistent; bind descriptions to the actual endpoint.

When bound to a local checkout

• ocx_context: “Report this local checkout's branch, unsaved files and declared tests.”
• ocx_save: “Commit this local checkout after its recorded tests pass, then push using this clone's configured identity and credentials.”
• ocx_sync: “Import a bundle here and push through this clone's configured Fossil remote, or request descendants with have. This call does not route to remote MCP.”

A no-key local clone uses the local helper or plain Fossil to prepare a bundle, then separately calls ocx_sync on an explicitly configured remote connection.

Remote endpoint and a caller clone exists

• ocx_context: “Describe this endpoint's checkout, its working branch, unsaved files and declared tests. Your separate local clone is not inspected by this remote call. Check that clone locally before preparing its changes.”
• ocx_sync: “Publish committed work from your existing local clone. Prepare its non-trunk branch as a standalone bundle, then supply branch and bundle here. Use have for descendant check-ins to import back; verify the returned landing and receipt.”

Remote endpoint and optional local setup is feasible

• ocx_context: “Describe this endpoint's checkout. You can prepare a separate local checkout first; use the supplied read URL and starting revision. This call does not create that clone.”
• ocx_sync: “After creating your local Fossil clone, checking out the stated revision and committing on your working branch, publish its standalone bundle here. If you have not cloned yet, follow the bootstrap steps before preparing a bundle.”

Remote endpoint and local clone is unavailable or unknown

• ocx_context: “Start here to identify the remote run's objective, working branch, unsaved files and declared tests. Find and read its files, edit them, run its tests, then save in this same checkout.”
• ocx_sync: “Import a bundle already committed in another clone. For changes made through this run's editing tools, use ocx_save after its tests pass; no local clone or bundle is needed.”
• ocx_save: “Commit and push this remote run's checkout after its recorded tests pass. Files on your computer are outside this call.”

Retain the implemented boundaries: ocx_commit_and_sync acts where the caller's files are and returns a bundle without publishing remotely. ocx_commit_and_sync_guide supplies shell instructions and a stated comment.

Use the existing catalog rendering path for contextual text. MCP currently renders each tool's summary and capability requirement. Extend that presentation rather than adding parallel local/remote command families. If the client caches descriptions, return current context and next-step information in ordinary responses too; correctness must not depend on a description refresh.

Minimal machine readable context and next call

Extend discovery/status responses with separate server_facts and caller_report; no additional discovery service is needed. Include release, available tools, checkout identity, branch, base, calling/default user and capability source. MCP identification in a clone asks the remote server for that user's capabilities; CLI uses local capabilities. Local setup privileges do not establish remote publication authority.

An illustrative response after a supported remote-only endpoint has been verified:

{
  "server_facts": {
    "scope": "current_connection",
    "provenance": "endpoint",
    "execution_location": "remote_run",
    "login": "resolved-user",
    "capabilities_source": "server_receipt",
    "checkout_id": "opaque-checkout-id",
    "branch": "resolved-working-branch",
    "base": "resolved-full-checkin-hash"
  },
  "caller_report": {
    "scope": "current_caller_environment",
    "provenance": "client",
    "state": "unknown_or_unavailable",
    "bounded_check": "not_attempted",
    "reason": "local execution tools unavailable"
  },
  "next_call": {
    "connection": "current",
    "tool": "ocx_read",
    "arguments": {"path": "README.md", "from": 1}
  }
}

All identity values are illustrative; use resolved values in production. Return a next call only when its tool exists on that connection. Shell steps must be labeled local instructions. Missing capability gets a concrete blocker, not a fictional call. Context is recomputed; no persistent state machine is needed.

The local helper could return this proposed structured next call, after producing the actual bundle and resolving the preconfigured connection and a held base:

{"next_call":{"connection":"configured_remote_ocx","tool":"ocx_sync",
 "arguments":{"branch":"resolved-branch","bundle":"returned-base64-bundle",
              "have":"held-full-checkin-hash"}}}

Omit optional have if no appropriate held check-in was established. A description cannot create the remote connection or change a local function's behavior.

Bootstrap and preparation

The current remote-agent instructions direct newcomers to the guide, but its first step assumes a clone already exists. Add the preceding steps: verify a permitted read URL, clone without retaining a write credential, open the intended revision in a writable directory, inspect status, then select a non-trunk working branch. Report unavailable clone access explicitly and offer the remote-checkout path when that endpoint supports it.

For an optional fresh clone, supply verified, nonsecret READ_URL, exact BASE, non-trunk BRANCH and task file values. From a new clean writable directory, this portable POSIX recipe prepares publication. Put the four-part comment in message.txt before entering tree; edit and run the project's checks before adding/committing:

fossil clone --no-open "$READ_URL" repo.fossil
mkdir tree
cd tree
fossil open ../repo.fossil "$BASE" --nosync
# Make the intended edits and run the project's checks here.
fossil add "$INTENDED_NEW_FILE"  # repeat only for intended new files
fossil status
fossil commit --nosync -M ../message.txt --branch "$BRANCH"
fossil bundle export ../push.bundle --branch "$BRANCH" --standalone
base64 < ../push.bundle | tr -d '\n'

Skip add when no new files need tracking. Use --branch only to create the branch; omit it when continuing that branch. Send the bundle and branch to configured remote ocx_sync, import any returned bundle and verify landing. Temporary files stay outside the checkout.

An already installed local ocx2 can provide a CLI shortcut. A client that already supports local MCP can use it there. Neither a Crystal build nor local MCP registration should be a prerequisite for ordinary Fossil preparation. Do not assume a hosted client can dynamically register a new local MCP server.

Refresh the repository's conversation as well as code. Native Fossil pull recovered the forum artifacts needed for this review. In contrast, OCX's bundle export follows check-in descendants from have; its response is not full Fossil record replication. Do not label that result “all forum and ticket context synchronized.” Use an authorized full pull or explicit record-reading route where needed.

Test evidence has different meanings

ocx_save and the local helper require OCX's recorded passes for declared tests against the current checkout state. Running a test separately in a shell does not automatically create that record. The plain Fossil route can preserve actual test evidence, but remote ocx_sync validates the precommitted branch and required comment fields; it does not rerun tests or certify their truth. State this limitation explicitly.

Use a fixture with nonempty declared tests for acceptance. Otherwise the save/helper gate can pass vacuously because there are no declared test names to fail. A Demonstrates line alone is not proof that a test ran.

Acceptance across the first and second task

These are proposed acceptance trials, not results of this source review. Run all three rows against the endpoint and client that users actually receive, with a small authorized edit and a nonempty declared test set. Record calls, corrections, time, bytes, failures and the final artifact evidence.

First task from a fresh session

1. Discover endpoint release, tools and identity. Verify helper identity prerequisites and publication authority. Permit at most one optional local check; unknown stays remote. Detect missing checkout tools before recommending them.
2. Reuse work, bootstrap optional plain Fossil, or identify the remote run. Establish objective, base, branch, changes and tests. Unrelated dirty files require a separate clean checkout or run: both helpers commit all changes. If unavailable, report that blocker.
3. Find and read the target, make the requested change and inspect the result. Exercise a rejected edit or missing prerequisite and recover using the returned instruction.
4. Run and record appropriate checks after the final edit. On the OCX-recorded route, demonstrate refusal before required tests pass and invalidation after another edit. On the plain route, retain actual test output without claiming sync verified it.
5. Commit and publish using the row's route. Verify the full check-in hash, expected content and branch on the server, plus receipt identity. Distinguish a missing receipt from verified attribution. No merge or release acceptance is implied.
6. Demonstrate publication recovery in a controlled fixture: preserve a commit after a failed push, resume safely, and confirm landing without duplicating the change. Report a durable link and accurate test status.

Second task in a new turn or session

1. Rediscover the actual endpoint and tools. Reuse the existing clone or remote run when available; detect an ended run or missing checkout explicitly. Confirm the previous check-in landed before beginning.
2. Refresh relevant code and conversation. Preserve pending work, choose the intended base and branch, and avoid recreating the clone or asking for credentials unnecessarily. Account for the limited scope of sync bundles.
3. Complete another read/edit/test/publish cycle. Ensure previous test records are not accepted for changed content. Verify the second check-in and receipt independently.
4. Show that onboarding is reusable: the second task needs no undocumented setup, repeated build, new local MCP registration or manual reconstruction of lost state. If the run was replaced, recover from saved server state and clearly identify any unsaved work that was lost.

Next decision

Update discovery and onboarding, then run three-case acceptance on the actual release. Folding the guide into coherent contextual help is reasonable only after fresh-agent discovery proves that help is found and sufficient. Compare the helper's replacement using the same tasks; retire it only when demonstrated. Update every onboarding reference together.