Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(mcp): init --surface help names the starter default; verbs notice scopes the reveal to stdio; document install-client listing (#7983)

garrytan5b47ce55d569
diff --git a/docs/mcp/DEPLOY.md b/docs/mcp/DEPLOY.md
index 2d3cce2b56..eb61470ec2 100644
--- a/docs/mcp/DEPLOY.md
+++ b/docs/mcp/DEPLOY.md
@@ -97,8 +97,12 @@ instructions tell the agent how many more tools are callable. On stdio,
`request_tools` with `tools: [names]` returns their schemas and adds them to
that session's list (the server sends `tools/list_changed`). On the OAuth HTTP
server, a client that set its own surface (`request_tools` with `surface`, or
-`gbrain auth rescope-client`) has that surface listed in full. Unset
-advertises the whole callable set.
+`gbrain auth rescope-client`) has that surface listed in full, and a client an
+install default set up (`gbrain auth clients` shows `full (set by install)`)
+lists the memory verbs and `request_tools` whatever the server's `--advertise`
+or `mcp.advertised_surface` says; `gbrain auth rescope-client <client_id>
+--surface full` lists everything for it. Unset advertises the whole callable
+set.
#### Stdio source binding
diff --git a/src/commands/init.ts b/src/commands/init.ts
index 56fbad442a..f91448eea5 100644
--- a/src/commands/init.ts
+++ b/src/commands/init.ts
@@ -1868,7 +1868,7 @@ OPTIONS
Default subagent driver (v0.27+)
--no-embedding Defer embedding setup (skips the embedding-key check)
--surface <verbs|starter|full> Tool surface the printed harness registration pins, listed in full
- (default: full, listing the memory verbs and request_tools)
+ (default: starter, listing the memory verbs and request_tools)
--search-mode <conservative|balanced|tokenmax> Record the operator's search mode (no first-run ask; an existing brain's mode needs --force)
--skip-embed-check Skip the init-time embedding-key validation (config +
live test-embed). Also via GBRAIN_INIT_SKIP_EMBED_CHECK=1
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index d2bcaa71a8..a1263d2aaa 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1294,7 +1294,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.452.0', id: 'starter_tools_list_params_gbra156', text: 'The starter MCP tool list is about 27% smaller: it leaves out parameters MCP callers cannot use (local-only, server-set provenance) and rarely needed ones (legacy, admin, versioned skill catalog, image and code search, tuning and recovery knobs with safe defaults). Every left-out parameter is still accepted, and `request_tools {tools: [names]}` now returns each tool\'s full schema with every optional parameter, also on a server capped at starter. Memory verb descriptions no longer start with `MEMORY VERB (v1):`. The verbs and full surfaces list every parameter as before.' },
{ since: '0.60.452.0', id: 'sources_not_readable_gbra156', text: 'An unscoped `search`, `query`, `recall` or `list_pages` from a token or agent connection with no source grant that comes back empty, while every source it can read holds no page and other sources do, now carries a `sources_not_readable` notice (kind degraded). It says the empty result is not proof of absence, never names a hidden source, and its fix is `gbrain sources federate <source>` on the brain host, or a grant for the token. Granted tokens and OAuth clients never get it.' },
// GBRA-199. since: '0.60.503.0' is stamped at the merge slot.
- { since: '0.60.503.0', id: 'registration_lists_verbs_gbra199', text: 'New MCP registrations gbrain writes now list only the seven memory verbs (`recall`, `remember`, `entity`, …) and `request_tools` in tools/list: `gbrain setup claude-code|codex`, `gbrain bootstrap hooks`, the readiness and `gbrain init` registration lines (`serve --surface starter --advertise verbs`: the starter tools stay callable) and `gbrain mcp expose` (its `serve --http` runs with `--surface full --advertise verbs`, so clients without their own surface see that list and every operation stays callable). `request_tools` lists the rest and returns any tool\'s full schema, and a tool it describes joins the session\'s list. The initialize instructions follow the listed tools, so they point agents at `recall` instead of `search`. Existing registrations and exposures keep their listing, and an explicit `--surface full` (or starter, or verbs) lists that whole surface. New `gbrain serve --advertise <verbs|starter|full>` sets the listing per server and wins over config `mcp.advertised_surface`; a listing narrower than the callable set now always includes `request_tools`. Remote harness and bot clients get the same listing: a new `gbrain mcp provision` grant with the memory-reader, memory-writer or coding-agent profile and a new `gbrain agent register` daily-driver or coding-agent client keep the full callable surface but list the verbs and `request_tools` (`auth list-clients` shows `full (set by install)`); `gbrain auth rescope-client <id> --surface full` lists everything, and clients the operator pinned before keep their listing. Plugin manifests and a bare `serve` are unchanged.' },
+ { since: '0.60.503.0', id: 'registration_lists_verbs_gbra199', text: 'New MCP registrations gbrain writes now list only the seven memory verbs (`recall`, `remember`, `entity`, …) and `request_tools` in tools/list: `gbrain setup claude-code|codex`, `gbrain bootstrap hooks`, the readiness and `gbrain init` registration lines (`serve --surface starter --advertise verbs`: the starter tools stay callable) and `gbrain mcp expose` (its `serve --http` runs with `--surface full --advertise verbs`, so clients without their own surface see that list and every operation stays callable). `request_tools` lists the rest and returns any tool\'s full schema, and on stdio a tool it describes joins the session\'s list. The initialize instructions follow the listed tools, so they point agents at `recall` instead of `search`. Existing registrations and exposures keep their listing, and an explicit `--surface full` (or starter, or verbs) lists that whole surface. New `gbrain serve --advertise <verbs|starter|full>` sets the listing per server and wins over config `mcp.advertised_surface`; a listing narrower than the callable set now always includes `request_tools`. Remote harness and bot clients get the same listing: a new `gbrain mcp provision` grant with the memory-reader, memory-writer or coding-agent profile and a new `gbrain agent register` daily-driver or coding-agent client keep the full callable surface but list the verbs and `request_tools` (`auth list-clients` shows `full (set by install)`); `gbrain auth rescope-client <id> --surface full` lists everything, and clients the operator pinned before keep their listing. Plugin manifests and a bare `serve` are unchanged.' },
{ since: '0.60.452.0', id: 'sources_add_federation_warning_gbra156', text: '`gbrain sources add` without `--federated` or `--no-federated` now warns on stderr that the new source is not federated, so a remote token or agent connection with no source grant cannot read its pages, and names `gbrain sources federate <id>` and `gbrain auth rescope --token <name> --sources <id>`. The stored default is still non-federated.' },
{ since: '0.60.527.0', id: 'private_pages_granted_sources_gbra156', text: 'Access tokens and OAuth clients have a new private-pages grant, `none` for every existing and new token and client, so remote reads still hide `visibility: private` pages until the brain host opts a connection in: `gbrain auth rescope --token <name> --private-pages granted-sources` (or `--client <id>`) lets it read private pages in the sources its grant names, and only those; in a named source that also covers privacy-alias pages and atoms, concepts and events derived from private or unknown origins, while pinned questions stay owner-only. A token with no source grant, federated sources the grant does not name and a request\'s `source_ids` never add one; `context_pack`, `delta` and writes keep hiding private pages. `--private-pages none` turns it off on the next request.' },
// GBRA-187 harness-eval items (HARN-2, HARN-5). `since` is stamped at the merge slot.
diff --git a/src/core/bootstrap/hooks.ts b/src/core/bootstrap/hooks.ts
index be3affdb37..fd13b23150 100644
--- a/src/core/bootstrap/hooks.ts
+++ b/src/core/bootstrap/hooks.ts
@@ -1131,7 +1131,7 @@ export type CodexMcpRegistration = Omit<ClaudeMcpRegistration, 'scope'>;
* (binary first) — the dispatcher execs them; nothing here touches the
* filesystem or the network. Shape per TARGETS['claude-code-2026-08'].
*
- * The serve argv comes from `stdioServeArgv`: `--surface full` by default
+ * The serve argv comes from `stdioServeArgv`: `--surface starter` by default
* (REGISTRATION_SURFACE; bootstrap's contract — put_page, get_page,
* add_timeline_entry, search, query — stays callable, and a pre-existing `mcp_surface: verbs` config row cannot
* narrow a pinned registration), listing the memory verbs and request_tools
diff --git a/test/behavior-change-notice.test.ts b/test/behavior-change-notice.test.ts
index e13f582638..3d0e126e7c 100644
--- a/test/behavior-change-notice.test.ts
+++ b/test/behavior-change-notice.test.ts
@@ -325,6 +325,12 @@ describe('per-release content', () => {
expect(all.why).toContain(noticeHeader('0', true));
expect(all.fix?.argv).toEqual(['unset', 'GBRAIN_CHAT_FALLBACK_CHAIN']);
});
+
+ // Value: protects=the verbs-listing notice only promises the request_tools reveal where it exists; fails_when=the text says a described tool joins the session's list with no transport, and HTTP has no reveal; why_new=#7983 item 7; seam=none; no_claim=the reveal itself (mcp server tests)
+ test('the verbs-listing notice scopes the request_tools reveal to stdio', () => {
+ const text = BEHAVIOR_CHANGES.find(c => c.id === 'registration_lists_verbs_gbra199')!.text as string;
+ expect(text).toContain("on stdio a tool it describes joins the session's list");
+ });
});
describe('concurrent initializations', () => {
diff --git a/test/cli-help-without-brain.test.ts b/test/cli-help-without-brain.test.ts
index 042bfcd986..fafbf01bf8 100644
--- a/test/cli-help-without-brain.test.ts
+++ b/test/cli-help-without-brain.test.ts
@@ -189,6 +189,14 @@ describe('--help without a configured brain', () => {
}
}, 120_000);
+ // Value: protects=init --help names the surface the printed registration really pins; fails_when=the help says default full while readiness pins REGISTRATION_SURFACE (starter); why_new=the help line was written before the starter default (#7983 item 5); seam=none; no_claim=the registration argv itself (readiness tests)
+ test('init --help names the registration surface default', async () => {
+ const { REGISTRATION_SURFACE } = await import('../src/core/mcp-registration.ts');
+ const r = await runCli(['init', '--help']);
+ expect(r.code).toBe(0);
+ expect(r.out).toContain(`(default: ${REGISTRATION_SURFACE}, listing the memory verbs and request_tools)`);
+ }, 60_000);
+
test('the known-unfixed set is exactly what it claims', async () => {
// Concurrently: seven sequential CLI spawns is most of this file's wall
// clock, and each one is independent (its own temp GBRAIN_HOME).