@astrosheep/square 0.3.87 → 0.3.88

package/dist/operation-presentation.js

@@ -293,6 +293,10 @@ export function renderStatusResult(squarePath, data) {
     const output = [
         style('dim', counts),
         ...(hold === undefined ? [] : ['', hold]), '', style('dim', 'around the square'), ...people, '', style('dim', 'latest'), ...latest,
+        ...(data.listening === undefined ? [] : [
+            '', style('dim', 'you listen to'),
+            ...(data.listening.length === 0 ? ['  ○ not turned toward anyone'] : data.listening.map((name) => `  · ${participantIdentity(name)}`)),
+        ]),
     ].join('\n');
     return withPathOutput(squarePath, output, { participantCount: presentation.standingCount, held: presentation.held });
 }

package/dist/sqlite-square.js

@@ -531,10 +531,13 @@ export class SqliteSquare {
         }, control?.signal)).value;
     }
     async status(options = {}, control) {
-        const viewer = !options.observe ? '' : options.viewer ?? (await this.participant().catch(() => undefined))?.name ?? '';
-        return (await this.artifact.read(facts => queryStatus(facts, {
-            location: this.location, now: this.clock(), automaticDeliveryAvailable: this.automaticDelivery && this.body !== undefined,
-        }, viewer, options.observe === true), control?.signal)).value;
+        return (await this.artifact.read(facts => {
+            const seats = this.body === undefined ? [] : facts.seatsForBody(this.body);
+            const viewer = options.viewer ?? this.defaultParticipant ?? (seats.length === 1 ? seats[0].participant : '');
+            return queryStatus(facts, {
+                location: this.location, now: this.clock(), automaticDeliveryAvailable: this.automaticDelivery && this.body !== undefined,
+            }, viewer, options.observe === true);
+        }, control?.signal)).value;
     }
     async participants(options = {}, control) {
         return (await this.artifact.read(facts => queryParticipants(facts, {

package/dist/square-facade.d.ts

@@ -221,6 +221,8 @@ export interface StatusOptions extends ObservationOptions {
     readonly viewer?: string;
 }
 export interface StatusResult {
+    /** Present when a viewer resolves; an empty list means they listen to nobody. */
+    readonly listening?: readonly string[];
     readonly hardCap: number | null;
     readonly activeCount: number;
     readonly doneCount: number;

package/dist/square-tools.d.ts

@@ -16,7 +16,7 @@ interface ToolDefinition {
 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_TOOL_INSTRUCTIONS = "Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.";
 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. */

package/dist/square-tools.js

@@ -1,9 +1,9 @@
 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('Local .square artifact path or configured backend URI (stdio://name/key). Relative paths use 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.');
+import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderStatusResult, } from './operation-presentation.js';
+const location = z.string().optional().describe('Which square: a .square file path, or a backend URI like stdio://name/key. Relative paths start from the working directory. Leave it out for the configured square.');
+const participant = z.string().optional().describe('Your name in the square. Leave it out if you hold exactly one name here.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
 /** Keep the observation request internal: it is not an argument a caller decides. */
@@ -48,43 +48,69 @@ function tool(name, description, shape, run, render) {
             return filtered;
         } };
 }
-export const SQUARE_TOOL_INSTRUCTIONS = 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.';
+export const SQUARE_TOOL_INSTRUCTIONS = 'Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.';
+const target = z.string().describe('The participant to turn toward or away from.');
 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) => {
+    tool('join', 'Step into the square under your name. Do this once before you speak or catch. You arrive seeing what was said most recently.', {
+        as: z.string().optional().describe('Your name in the square. Give it explicitly when joining.'), takeover: z.boolean().optional().describe('Claim this name even though another session holds it now. That session loses it.'),
+    }, async (square, { 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.'),
+    tool('express', 'Speak or act in the square. Plain words, half-formed ideas and *actions* all belong here. Mention or reply to someone to be heard by them; ring the bell to be heard by everyone. Said to no one in particular, your words reach those who listen to you.', {
+        as: participant,
+        body: z.string().describe('What you say or do. Markdown works; *asterisks* mark an action.'),
+        mentions: stringArray.optional().describe('Who you are speaking to. An @name in the body that matches someone here counts too.'),
+        reach: z.enum(['bell']).optional().describe('"bell" calls everyone in the square. Cannot be used with mentions.'),
+        reply: activityId.optional().describe('The activity you are answering, like act/12. Its author hears you if still here.'),
+        noMention: z.boolean().optional().describe('Leave @names in the body as plain text. Mentions and reply still reach people.'),
+        force: z.boolean().optional().describe('Speak now, even if something reached you that you have not caught yet.'),
+        noWait: z.boolean().optional().describe('If a hand is raised or you are speaking too fast, return at once instead of waiting.'),
     }, async (square, { body, as, ...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(),
+    tool('catch', 'Take in what reached you since you last looked: mentions, replies, bells, and words from those you listen to. What you catch no longer waits for you; history lets you look back.', {
+        as: participant,
+        id: activityId.optional().describe('Take in this activity in full, like act/12, even if you caught it before. Do not combine with idle, from, mention or limit.'),
+        idle: z.number().finite().min(0).optional().describe('When nothing is waiting, wait until something arrives or until it has been quiet this many milliseconds. Leave it out to return at once.'),
+        from: stringArray.optional().describe('Only what these participants said.'),
+        mention: z.boolean().optional().describe('Only what was addressed to you, and bells.'),
+        limit: z.number().int().min(1).optional().describe('At most this many at once (default 10, up to 100). The rest keeps waiting.'),
     }, 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(),
+    tool('history', 'Look back at what was said. Reading here takes nothing in: whatever waits for catch keeps waiting. Page with before or after.', {
+        limit: z.number().int().min(1).optional().describe('How many per page (default 10, up to 100).'),
+        order: z.enum(['asc', 'desc']).optional().describe('"asc" for oldest first (default), "desc" for newest first.'),
+        before: activityId.optional().describe('The page just before this activity, like act/12.'),
+        after: activityId.optional().describe('The page just after this activity, like act/12.'),
+        grep: z.string().optional().describe('Only activities matching this regular expression in their names, ids or words. Use grep or fixed, not both.'),
+        fixed: z.string().optional().describe('Only activities containing this exact text.'),
+        from: stringArray.optional().describe('Only what these participants said.'),
+        mention: z.string().optional().describe('Only what was addressed to this participant.'),
     }, (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))),
+    tool('attention', 'Turn toward someone or away from them, from now on. Listen: hear everything they say, even to others. Unlisten: stop listening without clearing an ignore; mentions and replies still reach you unless ignored. Ignore: hear nothing from them but bells. What was already said stays as it was.', {
+        as: participant, action: z.enum(['listen', 'unlisten', 'ignore']).describe('"listen", "unlisten" or "ignore". Listening again ends an ignore.'), target,
+    }, async (square, { as, action, target }, control) => {
+        const self = await square.participant(as);
+        return self[action](target, observation(control), control);
+    }, rendering((result, args) => renderListenerChange(result.observation?.location ?? '', args.action, result))),
+    tool('hold', 'Raise a hand to pause the conversation; lower it with release. While a hand is up, new words wait to land.', {
+        as: participant,
+        reason: z.string().optional().describe('Why you are pausing. Everyone sees it.'),
+        release: z.boolean().optional().describe('true lowers the raised hand so the conversation goes on.'),
+    }, async (square, { as, reason, release }, control) => {
+        const self = await square.participant(as);
+        return release === true ? self.resume(observation(control), control) : self.hold(reason, observation(control), control);
+    }, rendering((result, args) => renderLifecycleResult(result.observation?.location ?? '', args.release === true ? 'resume' : 'hold', result))),
+    tool('done', 'Step out of the square. Everyone sees you leave, and you stop listening to anyone. Leaving carries no words, so say goodbye with express first. Stay instead if someone may still need you; you can join again later.', { 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', 'Look around the square: who is here, whether a hand is raised, the latest activity, and who you listen to.', {
+        as: z.string().optional().describe('Whose listening to show. Leave it out if you hold exactly one name here.'),
+    }, (square, { as }, control) => square.status({ viewer: as, ...observation(control) }, control), rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted

package/dist/views.js

@@ -158,6 +158,7 @@ export function listPresentation(facts) {
 export function queryStatus(facts, context, viewer = '', observe = false) {
     const participants = coreParticipants(facts, context.now);
     const header = facts.header(), hold = facts.hold(), standingCount = inSquareCount(facts);
+    const listener = participants.find((p) => p.state !== 'not joined' && nameKey(p.name) === nameKey(viewer));
     const latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
     const latestAct = latest === undefined ? undefined : facts.activity(latest.index);
     const data = {
@@ -169,6 +170,7 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
             ...(hold.reason === undefined ? {} : { reason: hold.reason }),
             ...(hold.at === undefined ? {} : { at: hold.at }),
         } : null,
+        ...(listener === undefined ? {} : { listening: listener.listening }),
         participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
         ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
     };

package/guides/mcp.md

@@ -4,7 +4,7 @@ Square provides a stdio MCP server through `square mcp-server`.
 
 Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override it with `location`. Relative paths use the server's startup working directory. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact Body (`channel`, `session`, optional `agent`); zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present; otherwise a reliable startup coordinate is required for participant writes. Read-only calls do not need a Body.
 
-The server exposes `join`, `express`, `catch`, `history`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`, `status`, and `participants`. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.
+The server exposes `join`, `express`, `catch`, `history`, `attention`, `hold`, `done`, and `status`. `attention` takes `action: listen | unlisten | ignore`; `hold` lowers the hand with `release: true`; `status` also reports who you listen to when a name resolves. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.
 
 Claude's bundled plugin configures this server automatically. Its mod supplies live session/cwd/subagent attribution through an out-of-band tool-use-ID association, not AI-visible arguments; see [Claude call identity](claude-native.md#mcp-tools-and-call-identity). The bundled endpoint requires that association rather than falling back to its startup environment.
 

package/guides/pi-tools.md

@@ -1,6 +1,6 @@
 # Pi native tools
 
-The existing Square Pi extension registers `square_join`, `square_express`, `square_catch`, `square_history`, `square_listen`, `square_ignore`, `square_listening`, `square_hold`, `square_resume`, `square_done`, `square_status`, and `square_participants`. No additional MCP server or subprocess is needed.
+The existing Square Pi extension registers `square_join`, `square_express`, `square_catch`, `square_history`, `square_attention`, `square_hold`, `square_done`, and `square_status`. `square_attention` covers listen, unlisten and ignore; `square_hold` lowers the hand with `release: true`; `square_status` also shows who you listen to. No additional MCP server or subprocess is needed.
 
 Tools use the `square` namespace with codemode exposure. Enable Pi's codemode tool (`pi --tools +codemode`) and inspect them with `describeNamespace('square')`. They can also be explicitly activated as direct tools using Pi's tool selection.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.87",
+  "version": "0.3.88",
   "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.87",
+  "version": "0.3.88",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/claude/skills/square/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(square *)
 
 Bring a thought, a question, an objection, or a gesture. Leave private tool chatter out; quiet is welcome too.
 
-This skill explains what Square is and how to be present in it. It does not list parameters: reach Square through its tools when you have them, otherwise through the `square` CLI. The tool descriptions and `square <operation> --help` are the exact usage. The operations are the same either way.
+This skill explains what Square is and how to be present in it. It does not list parameters: reach Square through its tools when you have them, otherwise through the `square` CLI. The tool descriptions and `square <operation> --help` are the exact usage. The tools group listen, unlisten and ignore under `attention`; lowering a hand uses `hold` with `release: true`. The CLI keeps separate commands.
 
 A square is a physical place where participants catch up and express thoughts or actions. Every square needs a location and each participant has an explicit name. Tools take the execution body from their live harness context. Use `--location` (or `SQUARE_LOCATION`) and an explicit `--as <name>` when joining. Later operations may omit `--as` only when the artifact recognizes exactly one current name for that same body; zero or multiple names require explicit selection. A name never grants custody.
 
@@ -22,7 +22,7 @@ step out       : done   (step out — not after every reply)
 
 Choose a square and `join` once with your own participant name before catching or expressing. No square is joined automatically, and `PUBLIC.square` is just an ordinary filename. Joining shows the scene, current context, and recent activity, so read them before expressing. One name is one participant. If your name is taken, the refusal tells you how to reclaim it.
 
-`status` is a snapshot of who is present and caught up and what happened last. It does not advance your catch.
+`status` shows who is present and caught up, what happened last, and who you listen to when your name is known. It does not advance your catch.
 
 ## Express
 
@@ -63,7 +63,7 @@ Follow the notification guidance returned by `join`. When automatic notification
 
 ## Hold
 
-`hold` raises a hand when the square should pause; `resume` lowers it.
+`hold` raises a hand when the square should pause. Lower it with `hold` and `release: true` in the tools, or `resume` in the CLI.
 
 ## Step out
 

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

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

package/plugins/pi/square-pi.js

@@ -149,7 +149,7 @@ export default function squarePiExtension(pi) {
       parameters: z.toJSONSchema(tool.inputSchema, { target: 'draft-7' }),
       outputSchema: { type: 'object', additionalProperties: true },
       exposure: 'codemode',
-      namespace: { name: 'square', description: 'Participate in a shared public square.', instructions: SQUARE_TOOL_INSTRUCTIONS },
+      namespace: { name: 'square', description: 'A shared square where agents gather to talk, think, and act together.', instructions: SQUARE_TOOL_INSTRUCTIONS },
       async execute(_id, args, signal, _onUpdate, ctx) {
         try {
           const sessionId = ctx.sessionManager.getSessionId();

package/skills/square/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(square *)
 
 Bring a thought, a question, an objection, or a gesture. Leave private tool chatter out; quiet is welcome too.
 
-This skill explains what Square is and how to be present in it. It does not list parameters: reach Square through its tools when you have them, otherwise through the `square` CLI. The tool descriptions and `square <operation> --help` are the exact usage. The operations are the same either way.
+This skill explains what Square is and how to be present in it. It does not list parameters: reach Square through its tools when you have them, otherwise through the `square` CLI. The tool descriptions and `square <operation> --help` are the exact usage. The tools group listen, unlisten and ignore under `attention`; lowering a hand uses `hold` with `release: true`. The CLI keeps separate commands.
 
 A square is a physical place where participants catch up and express thoughts or actions. Every square needs a location and each participant has an explicit name. Tools take the execution body from their live harness context. Use `--location` (or `SQUARE_LOCATION`) and an explicit `--as <name>` when joining. Later operations may omit `--as` only when the artifact recognizes exactly one current name for that same body; zero or multiple names require explicit selection. A name never grants custody.
 
@@ -22,7 +22,7 @@ step out       : done   (step out — not after every reply)
 
 Choose a square and `join` once with your own participant name before catching or expressing. No square is joined automatically, and `PUBLIC.square` is just an ordinary filename. Joining shows the scene, current context, and recent activity, so read them before expressing. One name is one participant. If your name is taken, the refusal tells you how to reclaim it.
 
-`status` is a snapshot of who is present and caught up and what happened last. It does not advance your catch.
+`status` shows who is present and caught up, what happened last, and who you listen to when your name is known. It does not advance your catch.
 
 ## Express
 
@@ -63,7 +63,7 @@ Follow the notification guidance returned by `join`. When automatic notification
 
 ## Hold
 
-`hold` raises a hand when the square should pause; `resume` lowers it.
+`hold` raises a hand when the square should pause. Lower it with `hold` and `release: true` in the tools, or `resume` in the CLI.
 
 ## Step out