@astrosheep/square 0.3.83 → 0.3.84

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,38 @@ 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. On a matching Paseo build, the Square server plugin records
+`held`, `released` and `dropped` observations from `agent.delivery_status` on the
+original host-ledger wake attempt. 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. Unknown IDs do
+not create evidence; older attempts without message IDs cannot be backfilled.
+
+`square harness doctor delivery` shows native custody separately from pending
+attention, including after the activity is seen or the participant leaves. Paseo
+also presents the native state in its timeline. This integration requires the
+matching local Paseo 0.12.1-square.1 lifecycle API and plugin SDK; see
+[the Paseo plugin](../plugins/paseo/README.md). Acceptance means normal delivery
+when policy 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.84",
   "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.84",
   "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.84",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/paseo/OVERVIEW.md

@@ -5,10 +5,13 @@ who reached you and where. Expand it to see the original custom-message content,
 select text, or copy it in full. The card follows the active Paseo theme on
 desktop and mobile.
 
-Requires Paseo 0.11.2 or newer with custom-message tool rows (#6090). Square
+Requires the local Paseo 0.12.1-square.1 patch build and its plugin SDK,
+which add `agent.delivery_status` to official 0.12.0. Square
 0.3.69 or newer supplies structured card headings. Older messages and joining
 context use a neutral “Square context” heading.
 
-The plugin changes presentation only. It does not send prompts or alter model
-context. If Square clipped a body before delivery, expansion shows that same
-preview and the command for reading the rest, not an additional fetch.
+The client changes presentation only. It does not send prompts or alter model
+context. Expansion uses the complete renderer text when present, otherwise the
+original preview; it never fetches extra activity. The server records Claude native
+held/released/dropped diagnostics on Square's original wake attempt. It does not
+change admission policy, confirm consumption, or resend notifications.

package/plugins/paseo/README.md

@@ -1,7 +1,8 @@
 # Square for Paseo
 
-A client-only presentation plugin for Square custom messages. No daemon restart,
-backend entry, extra notifications, or model-context changes.
+Presentation for Square custom messages, plus a server entry that records Claude
+native custody diagnostics. It never changes admission policy, sends a second
+notification, marks an activity seen, or alters model context.
 
 ## Install from GitHub
 
@@ -15,9 +16,13 @@ directory. Square tags up to v0.3.69 do not contain it.
 Paseo supplies all runtime modules. No Git preparation step is needed. Plugins
 are trusted, unsandboxed code running inside the Paseo app.
 
-Requires Paseo >=0.11.2 with custom-message tool rows (#6090). Square 0.3.69+
-provides `details.items` for the collapsed heading. Messages without those
-details still expand to their original content.
+The server entry requires the local **Paseo 0.12.1-square.1** patch build, based
+on official 0.12.0 and adding `agent.delivery_status`. Official 0.12.0 does not
+provide that API. The manifest pins the tested patch build rather than claiming
+support for an unpatched or hypothetical future official release. The client
+card uses custom-message tool rows (#6090).
+Square 0.3.69+ provides `details.items` for the collapsed heading. Messages without
+those details still expand to their original content.
 
 ## Display
 
@@ -40,11 +45,29 @@ and compact layout on narrow displays. Expansion starts at the top-right arrow;
 collapse returns from the arrow below the expanded content. Removing the plugin restores Paseo's
 ordinary custom-message row.
 
+## Native custody evidence
+
+Paseo renders Claude `peer_message_hold` events as timeline notifications. The
+server entry forwards socket observations (original event ID, native session and
+message ID, held/released/dropped state, reason and observation time) to
+`square claude-mod` over JSON stdin in the agent's working directory. Square
+matches a message ID persisted before sending and appends the observation to the
+original wake attempt. Unknown message IDs create no evidence. Failures surface
+as plugin hook errors; forwarding is bounded to five seconds and honors hook
+cancellation.
+
+`held`, `released` and `dropped` are not queue receipts or proof of consumption.
+They never turn `unknown` into `accepted` or authorize a replay. `square harness
+doctor delivery` shows the native state and reason, including after the activity is seen.
+The `square` executable must resolve to the matching Square release on the daemon's PATH.
+
 ## Develop
 
 ```bash
 cd plugins/paseo
 npm ci
+# Link the SDK from the built Paseo 0.12.1-square.1 source checkout:
+npm link --no-save /path/to/paseo/packages/plugin
 npm run typecheck
 npm test
 paseo plugin install "$PWD"
@@ -56,4 +79,5 @@ After editing an installed directory source:
 paseo plugin reload square
 ```
 
-No Paseo restart is needed. The plugin ID is `square`.
+Plugin-only reloads need no Paseo restart once the host provides the lifecycle
+API. Reloading a plugin cannot add that API to an older daemon. The plugin ID is `square`.

package/plugins/paseo/index.server.ts

@@ -0,0 +1,10 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { recordDeliveryStatus } from "./server/record-delivery.ts";
+
+export default function contribute(server: Pick<PluginServerContext, "on">) {
+  return server.on("agent.delivery_status", async ({ agent, observation }, { signal }) => {
+    // Agent providers can wrap Claude (for example yescode); the observation identifies the native producer.
+    if (observation.provider !== "claude" || observation.lane !== "socket" || !observation.eventId) return;
+    await recordDeliveryStatus(agent.cwd, observation, signal);
+  });
+}

package/plugins/paseo/package.json

@@ -8,12 +8,12 @@
     "test": "node --experimental-strip-types --test test/*.test.ts"
   },
   "devDependencies": {
-    "@getpaseo/plugin": "0.11.2",
-    "@types/react": "~19.2.0",
+    "@getpaseo/plugin": "0.12.0",
     "@types/node": "^22",
+    "@types/react": "~19.2.0",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "typescript": "^5.9.3",
-    "zod": "^4.4.3"
+    "zod": "4.4.3"
   }
 }

package/plugins/paseo/paseo-plugin.json

@@ -2,6 +2,6 @@
   "id": "square",
   "name": "Square",
   "requirements": {
-    "paseo": ">=0.11.2"
+    "paseo": "0.12.1-square.1"
   }
 }

package/plugins/paseo/server/record-delivery.ts

@@ -0,0 +1,28 @@
+import { spawnProcess, type AgentDeliveryObservation } from "@getpaseo/plugin/server";
+
+/** Forward native facts only. Square matches its pre-persisted message ID; no text parsing. */
+export async function recordDeliveryStatus(
+  cwd: string,
+  observation: AgentDeliveryObservation,
+  signal: AbortSignal,
+): Promise<void> {
+  const child = spawnProcess("square", ["claude-mod"], {
+    cwd, env: process.env, stdio: "pipe", signal, timeout: 5_000,
+  });
+  await new Promise<void>((resolve, reject) => {
+    child.once("error", reject);
+    child.stdin.once("error", reject);
+    // Output contains no user-facing content. Drain both pipes; the bridge exit is authoritative.
+    child.stdout.resume();
+    child.stderr.resume();
+    child.once("close", (code, killedBy) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Square native status recorder failed (${killedBy ?? code}).`));
+    });
+    const { provider, sessionId, messageId, eventId, state, reason, observedAt } = observation;
+    child.stdin.end(JSON.stringify({ operation: "status", cwd, sessionId, status: {
+      provider, sessionId, messageId, eventId, state, observedAt,
+      ...(reason === null ? {} : { reason }),
+    } }));
+  });
+}