@astrosheep/square 0.3.83 → 0.3.85

package/dist/square-tools.d.ts

@@ -1,15 +1,27 @@
 import { z } from 'zod/v4';
-import type { Square } from './square-api.js';
+import { type Square } from './square-api.js';
 import type { OperationControl } from './square-facade.js';
 type JsonObject = Record<string, unknown>;
 type Outcome = Promise<object>;
+type ToolRender = (result: JsonObject, args: JsonObject) => string | undefined;
 interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodObject<z.ZodRawShape>;
-    run(square: Square, args: JsonObject, control: OperationControl): Outcome;
+    run(square: Square, args: JsonObject, control: ToolControl): Outcome;
+    /** Human text identical to what the CLI prints; transports show this to people. */
+    render: ToolRender;
+}
+/** A transport that shows people the square asks the same operation for its rendering facts. */
+export interface ToolControl extends OperationControl {
+    readonly observe?: boolean;
 }
 export declare const SQUARE_TOOL_INSTRUCTIONS = "The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.";
 export declare const SQUARE_TOOLS: readonly ToolDefinition[];
 export declare function squareToolFailure(error: unknown, signal?: AbortSignal): JsonObject;
+/** Readable failure text with the same recovery commands the CLI offers, never raw JSON. */
+export declare function squareToolFailureText(failure: JsonObject, context?: {
+    location?: string;
+    participant?: string;
+}): string;
 export {};

package/dist/square-tools.js

@@ -1,12 +1,22 @@
 import { z } from 'zod/v4';
 import { isSquareError } from './model.js';
+import { CATCH_DEFAULT_LIMIT } from './square-api.js';
+import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderListeningResult, renderParticipantsResult, renderStatusResult, } from './operation-presentation.js';
 const location = z.string().optional().describe('Path to the .square artifact, relative to the current working directory. Defaults to the configured square.');
 const participant = z.string().optional().describe('Participant name. Defaults to the configured participant or the current session’s unambiguous participant.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
-function tool(name, description, shape, run) {
+/** Keep the observation request internal: it is not an argument a caller decides. */
+function observation(control) {
+    return control.observe === true ? { observe: true } : {};
+}
+/** Tool receipts are plain JSON; each renderer re-declares the facts it reads. */
+function rendering(render) {
+    return (result, args) => render(result, args);
+}
+function tool(name, description, shape, run, render) {
     const inputSchema = z.object({ ...shape, location }).strict();
-    return { name, description, inputSchema, run: (square, args, control) => {
+    return { name, description, inputSchema, render, run: (square, args, control) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
             return run(square, operationArgs, control);
         } };
@@ -14,35 +24,40 @@ function tool(name, description, shape, run) {
 export const SQUARE_TOOL_INSTRUCTIONS = 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.';
 export const SQUARE_TOOLS = [
     tool('join', 'Join the square as a participant.', { as: participant, takeover: z.boolean().optional().describe('Take the name from its current session owner.') }, async (square, { as, takeover }, control) => {
-        const { participant, ...receipt } = await square.join(as, { takeover }, control);
+        const { participant, ...receipt } = await square.join(as, { takeover, ...observation(control) }, control);
         return { ...receipt, participant: participant.name };
-    }),
+    }, rendering((result) => renderJoinResult(result))),
     tool('express', 'Express a message or embodied action in the square. Mentions and replies direct attention; bell reaches everyone and keeps body @names literal. Bell cannot combine with explicit mentions. Bare activity is valid even with no listeners.', {
         as: participant, body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(),
         reply: activityId.optional(), noMention: z.boolean().optional().describe('Disable body @name scanning; explicit mentions and reply still apply.'),
         force: z.boolean().optional().describe('Speak without first catching unread activity or satisfying attention etiquette.'),
         noWait: z.boolean().optional().describe('Return an error rather than waiting when held or throttled.'),
     }, async (square, { body, as, ...options }, control) => {
-        const { delivery: _delivery, ...result } = await (await square.participant(as)).express(body, options, control);
+        const { delivery: _delivery, ...result } = await (await square.participant(as)).express(body, { ...options, ...observation(control) }, control);
         return result;
-    }),
+    }, rendering((result) => renderExpression(result.observation?.location ?? '', result))),
     tool('catch', 'Catch and consume activities perceptible to the participant. idle waits for relevant activity or this many milliseconds of quiet; omitted means immediate. id catches one activity and cannot be combined with filters, idle or limit.', {
         as: participant, id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(),
         mention: z.boolean().optional(), limit: z.number().int().min(1).optional(),
-    }, async (square, { as, ...options }, control) => (await square.participant(as)).catch(options, control)),
+    }, async (square, { as, ...options }, control) => (await square.participant(as)).catch({ ...options, ...observation(control) }, control), rendering((result, args) => {
+        // The CLI always spells the default cap in its continuation, so the tool does too.
+        const options = args;
+        const renderOptions = options.id === undefined ? { ...options, limit: options.limit ?? CATCH_DEFAULT_LIMIT } : options;
+        return renderCatchOutcome(result.observation?.location ?? '', result, renderOptions).stdout;
+    })),
     tool('history', 'Read the activity stream without consuming it, using stable activity-id cursors. Default page size is 10, maximum 100. grep is a regex; fixed is literal text; use only one.', {
         limit: z.number().int().min(1).optional(), order: z.enum(['asc', 'desc']).optional(), before: activityId.optional(), after: activityId.optional(),
         grep: z.string().optional(), fixed: z.string().optional(), from: stringArray.optional(), mention: z.string().optional(),
-    }, (square, args, control) => square.history(args, control)),
-    tool('listen', 'Listen for future activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).listen(target, {}, control)),
-    tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).ignore(target, {}, control)),
-    tool('unlisten', 'Stop listening to a participant’s future activity; mentions and replies still reach you. An existing ignore is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).unlisten(target, {}, control)),
-    tool('listening', 'List participants this participant is listening to.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).listening({}, control)),
-    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, async (square, { as, reason }, control) => (await square.participant(as)).hold(reason, {}, control)),
-    tool('resume', 'Release the current hold.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).resume({}, control)),
-    tool('done', 'Leave the square without adding a message.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, {}, control)),
-    tool('status', 'Read the public status of the square.', {}, (square, _args, control) => square.status({}, control)),
-    tool('participants', 'List participants standing in or done with the square.', {}, (square, _args, control) => square.participants({}, control)),
+    }, (square, args, control) => square.history({ ...args, ...observation(control) }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: args }))),
+    tool('listen', 'Listen for future activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).listen(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'listen', result))),
+    tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).ignore(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'ignore', result))),
+    tool('unlisten', 'Stop listening to a participant’s future activity; mentions and replies still reach you. An existing ignore is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).unlisten(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'unlisten', result))),
+    tool('listening', 'List participants this participant is listening to.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).listening(observation(control), control), rendering((result) => renderListeningResult(result.observation?.location ?? '', result))),
+    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, async (square, { as, reason }, control) => (await square.participant(as)).hold(reason, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'hold', result))),
+    tool('resume', 'Release the current hold.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).resume(observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'resume', result))),
+    tool('done', 'Leave the square without adding a message.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'done', result))),
+    tool('status', 'Read the public status of the square.', {}, (square, _args, control) => square.status(observation(control), control), rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
+    tool('participants', 'List participants standing in or done with the square.', {}, (square, _args, control) => square.participants(observation(control), control), rendering((result) => renderParticipantsResult(result.observation?.location ?? '', result))),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted
@@ -55,3 +70,7 @@ export function squareToolFailure(error, signal) {
     const operation = error instanceof Error ? error.operation : undefined;
     return operation === undefined ? normalized : { ...normalized, operation };
 }
+/** Readable failure text with the same recovery commands the CLI offers, never raw JSON. */
+export function squareToolFailureText(failure, context = {}) {
+    return renderFailureLines(failure, { squarePath: context.location, name: context.participant }).join('\n');
+}

package/dist/wake-evidence.d.ts

@@ -1,6 +1,7 @@
-import type { EvidenceRecord, WakeAttention } from './host-ledger.js';
+import type { EvidenceRecord, WakeAttention, NativeDeliveryObservation } from './host-ledger.js';
 import type { WakeRouteKind } from './model.js';
 export interface WakeAttempt {
+    readonly nativeObservations?: readonly NativeDeliveryObservation[];
     readonly at: number;
     readonly attention: WakeAttention;
     readonly routeKind: WakeRouteKind;

package/dist/wake-evidence.js

@@ -27,5 +27,6 @@ export function decodeWakeEvidence(record, now) {
         return undefined;
     if (record.routeKind === undefined || typeof record.attemptN !== 'number')
         return undefined;
-    return { kind: 'attempt', value: { ...value, routeKind: record.routeKind, attemptN: record.attemptN, outcome: record.outcome } };
+    return { kind: 'attempt', value: { ...value, routeKind: record.routeKind, attemptN: record.attemptN, outcome: record.outcome,
+            ...(record.nativeObservations === undefined ? {} : { nativeObservations: record.nativeObservations }) } };
 }

package/guides/catch-cold-path-optimization.md

@@ -9,7 +9,7 @@ The comparison is against `90752ba`, the current production implementation plus
 ## Two changes
 
 - `model.ts`: try the existing Unicode text-name grammar before the full RGI emoji grammar. It accepts letters, numbers, marks excluding variation selectors, hyphens, underscores, and nonempty slash-separated segments. It is an exact subset of the original grammar; the original full matcher remains the fallback. `NAME_GRAPHEME_SOURCE`, also used by mention scanning, retains its original value.
-- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. Paseo precedence, Codex fallback, harness identity, and publication failure isolation remain unchanged.
+- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. These measurements predate the [native-first route policy](claude-native.md#native-first-routing-and-policy-holds); the optimization itself did not change route priority, harness identity, or publication failure isolation.
 
 CPU sampling of the baseline pointed to cold name validation inside reader transactions and optional adapter module loading during catch. The changes remove that work rather than prewarm it or move it outside measurement. The sampling and this combined experiment do not establish each change's individual contribution.
 

package/guides/claude-native.md

@@ -19,6 +19,39 @@ peer/plugin authority. Native OS-user socket permissions and Claude policy apply
 `square harness doctor delivery` derives current routes/evidence without sending.
 An absent/broken endpoint is unavailable; it does not consume Square activity.
 
+## Native-first routing and policy holds
+
+Native delivery is preferred, including under Paseo. Codex proposes its capable
+native queue before Paseo. Claude and OpenCode receivers register their native
+routes only through their loaded integrations. The common publication transaction
+keeps a fresh native registration ahead of a Paseo proposal for the same
+participant, session, channel and ownership epoch. Tool operations cannot flip it
+back to Paseo between receiver reconciliations. An absent, expired or explicitly
+retired native registration does not block a Paseo fallback; a replacement epoch
+cannot inherit an older native registration.
+
+This is route preference, not permission to bypass receiver policy. Claude can
+legitimately hold an unsolicited peer message with `no-mode-asserted`, especially
+under `bypassPermissions`. Square neither asserts a made-up permission mode nor
+changes `crossSessionInbound`. After bytes may have been sent, `unknown` remains
+attention-wide and prevents another send through Paseo, even if routes later change.
+
+Each native send persists a message ID before writing; the wire `uuid` and
+`msg_id` carry that ID. Square records no native custody telemetry from Paseo:
+official Paseo exposes no delivery-status lifecycle event, so a held message stays
+`unknown` with `native_admission_unconfirmed`. Recording a `held`, `released` or
+`dropped` observation would require a Paseo-provided event; Square does not patch
+Paseo to invent one. Even when such an observation exists, the event ID is
+deduplicated and the native reason and observation time remain diagnostic only.
+Neither a release nor a drop is a queue receipt, proof of consumption or retry
+authorization.
+
+`square harness doctor delivery` shows native custody separately from pending
+attention, including after the activity is seen or the participant leaves. Paseo
+presents the `peer_message_hold` state in its own timeline. Acceptance means normal
+delivery when the receiver allows it, or a visible reason without bypass/replay when
+policy holds it.
+
 ## MCP tools and call identity
 
 The plugin's `.mcp.json` starts the existing Square MCP server. The mod no longer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.83",
+  "version": "0.3.85",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.83",
+  "version": "0.3.85",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.83",
+  "version": "0.3.85",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"