@juanbenjumea/pi-agy 0.6.3 → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.5
4
+
5
+ - Add `agy_agents` and `/agy agents` to list configured custom agy agents through the CLI's read-only `agy agents` subcommand without spending a model turn; parsing is control-safe and capped at 200 names.
6
+ - Add validated custom-agent selection to `agy_execute` (`agent`) and `/agy` (`agent=name`), passed as a distinct `--agent` argv value with no shell interpolation.
7
+ - Persist custom-agent identity with conversation history and restore it automatically for known `conversation_id`, `continue=true`, `/agy continue`, and `/agy sessions` resumes.
8
+ - Show the effective custom agent in write confirmations, progress, native tool cards, durable receipts, history output, and session-picker labels; add focused discovery, validation, argv, rendering, and continuity coverage.
9
+
10
+ ## 0.6.4
11
+
12
+ - Add bounded active-tool progress details from agy's existing stream (`TargetFile`, task id, human-facing action/summary, and async threshold) while deliberately never exposing full `CommandLine` values that may contain secrets.
13
+ - Strip ANSI CSI/OSC sequences, ASCII/C1 controls, and Unicode bidi controls from streamed tool names and progress details before rendering.
14
+ - Make timeout recovery guidance truthful: successfully persisted conversation ids point to `conversation_id`, `/agy continue`, and `/agy sessions`; observed-only ids fall back to explicit `conversation_id` when the local session store could not be written.
15
+ - Document and preserve the bounded execution invariant: background tasks are not detached because agy 1.2.7 exposes no reliable headless lifecycle or task-to-process ownership; timeout/cancellation continues to kill the full process tree before releasing the workspace lock.
16
+
3
17
  ## 0.6.3
4
18
 
5
19
  - Add `/agy doctor` diagnostics for the CLI/version, stable model discovery, quota health, config validation, session-store corruption, active/stale workspace locks, and the repository verification gate; add `/agy usage [model]` for direct quota inspection.
package/README.md CHANGED
@@ -24,11 +24,12 @@ Requires Node.js >= 20.3.
24
24
  |---------|----------|-----------|
25
25
  | Live progress | Final text only | `stream-json` → Pi `onUpdate` cards |
26
26
  | Model aliases | Hardcoded ids | Live `agy models` catalog (newest stable generation wins; preview/experimental ignored), static map fallback |
27
- | Conversation resume | None | `conversation_id`, `continue`, session store with task summaries, `/agy sessions` picker, `agy_history` discovery tool — runs that time out or are cancelled are recorded too |
27
+ | Conversation resume | None | `conversation_id`, `continue`, session store with task summaries and custom-agent identity, `/agy sessions` picker, `agy_history` discovery tool — runs that time out or are cancelled are recorded too |
28
28
  | Verify injection | `npm test` only | `just ci` first, then `npm test`/`uv run pytest` |
29
29
  | Post-write summary | None | Appends `git diff --stat` for newly-dirty files only; pre-existing dirt (including renames and unstaged edits) is listed separately and never misattributed |
30
30
  | Preflight | Every call | Health/model checks cached 5 min per process; model quotas refresh every minute |
31
31
  | Quota discovery | None | Read-only `/usage` probe exposes model-specific remaining quota and reset times to agents |
32
+ | Custom agents | None | Read-only `agy_agents` / `/agy agents` discovery plus validated `agent` / `agent=name` selection via `--agent` |
32
33
  | Concurrency | Unlocked | Per-directory lock (in-process + filesystem, symlink-aware), lock wait counts against the timeout |
33
34
  | Transient failures | Fatal | One retry when agy fails before doing any work |
34
35
  | Cancellation | Direct child only | Full process-tree kill on cancel/timeout via detached process groups; a fully delivered result is preserved |
@@ -42,6 +43,13 @@ waits, preflight probes, and post-run summaries all count against it. When
42
43
  it fires, the full agy process group is killed so nested tools cannot
43
44
  outlive the run.
44
45
 
46
+ Active tool updates show bounded intent (for example a tool action or async
47
+ threshold) but never echo full command lines, which may contain secrets.
48
+ Background commands are intentionally not detached or managed out-of-band:
49
+ agy exposes no reliable headless task lifecycle or task-to-process ownership,
50
+ so timeout/cancellation still kills the full process tree and prevents work from
51
+ continuing after the directory lock is released.
52
+
45
53
  The deadline never discards finished work:
46
54
 
47
55
  - A response that fully arrived before the kill is returned with an
@@ -51,6 +59,9 @@ The deadline never discards finished work:
51
59
  are skipped with a note rather than failing the run.
52
60
  - The conversation id is recorded on timeout and cancellation, so the run
53
61
  stays resumable via `conversation_id`, `/agy continue`, or `/agy sessions`.
62
+ Timeout errors distinguish ids successfully recorded for `/agy continue` or
63
+ `/agy sessions` from ids merely observed when local persistence failed; the
64
+ latter can still be resumed by passing `conversation_id` explicitly.
54
65
 
55
66
  ## Tool params (new)
56
67
 
@@ -60,6 +71,7 @@ The deadline never discards finished work:
60
71
  | `continue` | `--continue` most recent conversation |
61
72
  | `new_session` | Force fresh session; set `false` to reuse last ID for dir |
62
73
  | `effort` | Reasoning effort via `--effort` where supported; `gpt-oss` accepts it, while Claude thinking models reject it and Gemini aliases already encode it |
74
+ | `agent` | Optional configured custom agy agent name; discover names with `agy_agents` |
63
75
  | `stream` | Use `stream-json` (default `true`) |
64
76
  | `context` | Optional Pi history handoff: `none` (default), `summary`, or `recent` |
65
77
  | `mode` | `accept-edits` by default; use `plan` for exploration/review |
@@ -86,10 +98,16 @@ Both exclude Pi system prompts, thinking, tool arguments, tool results, images,
86
98
  and custom extension messages. The current delegated task is appended after the
87
99
  reference context and remains authoritative.
88
100
 
101
+ The `agy_agents` tool runs the read-only `agy agents` subcommand and returns
102
+ configured custom-agent names without spending a model turn. Pass an exact
103
+ name as `agy_execute agent`; initial selection is always explicit, while known
104
+ conversation resumes restore their recorded agent.
105
+
89
106
  The `agy_history` tool lists recorded conversations for a directory — ids,
90
- models, ages, and one-line task summaries — so agents can find a
107
+ models, custom agents, ages, and one-line task summaries — so agents can find a
91
108
  `conversation_id` to resume; `/agy sessions` offers the same in the TUI
92
- picker. Summaries are stored locally (first ~80 chars of each prompt).
109
+ picker. Summaries are stored locally (first ~80 chars of each prompt), and a
110
+ recorded custom agent is restored when that conversation resumes.
93
111
 
94
112
  ## Human-callable `/agy` command
95
113
 
@@ -98,6 +116,8 @@ Run agy directly from the Pi TUI — fast path when fully specified, wizard othe
98
116
  ```
99
117
  /agy flash fix git conflicts # fully specified → runs immediately
100
118
  /agy plan sonnet review the diff # mode + model + prompt
119
+ /agy agents # list configured custom agents (read-only)
120
+ /agy plan agent=gsd-debugger investigate the crash
101
121
  /agy context=summary plan sonnet review our earlier decision
102
122
  /agy plan # wizard: model select → task editor
103
123
  /agy # wizard: mode → model → task editor
@@ -108,10 +128,10 @@ Run agy directly from the Pi TUI — fast path when fully specified, wizard othe
108
128
  /agy usage # inspect model quotas and reset times
109
129
  ```
110
130
 
111
- Leading option tokens (`plan`, a model alias, `continue`, `context=summary`,
112
- `context=recent`, `timeout=…`) are
113
- consumed in any order; the remainder is the prompt. `/agy continue` reuses the
114
- last model when the session store recorded one. `timeout=` caps at 10m.
131
+ Leading option tokens (`plan`, a model alias, `agent=name`, `continue`,
132
+ `context=summary`, `context=recent`, `timeout=…`) are consumed in any order;
133
+ the remainder is the prompt. `/agy continue` reuses the last model and custom
134
+ agent when the session store recorded them. `timeout=` caps at 10m.
115
135
 
116
136
  First token optional: `accept-edits` / `plan` / `sandbox` mode prefix, then a
117
137
  model alias (`flash`, `pro`, `sonnet`, `opus`, `gpt-oss`, …), then the prompt.
@@ -131,7 +151,8 @@ is appended to Pi's transcript. Receipts are TUI-only custom entries: they are
131
151
  not sent to the primary model, and context handoff excludes them. Stored task
132
152
  text is capped at 500 characters and result text at 8,000 characters. Stripped-down
133
153
  hosts fall back to a normal notification. `/agy usage` performs the same read-only
134
- quota check without starting a model turn.
154
+ quota check without starting a model turn; `/agy agents` likewise lists custom
155
+ agents without inference.
135
156
 
136
157
  ## Config
137
158
 
@@ -3,7 +3,9 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
3
3
  import {
4
4
  checkAgyUsage,
5
5
  formatAgyUsage,
6
+ inspectAgyAgents,
6
7
  isAgyModel,
8
+ normalizeAgyAgentName,
7
9
  resolveAgyModelId,
8
10
  type AgyModel,
9
11
  } from "./lib/cli.js";
@@ -60,6 +62,7 @@ const MAX_TIMEOUT_MS = 600_000;
60
62
  export interface AgyCommandArgs {
61
63
  mode?: "plan" | "accept-edits" | "sandbox";
62
64
  model?: AgyModel;
65
+ agent?: string;
63
66
  prompt?: string;
64
67
  continue?: boolean;
65
68
  timeout_ms?: number;
@@ -68,7 +71,7 @@ export interface AgyCommandArgs {
68
71
  }
69
72
 
70
73
  /**
71
- * Parse `/agy [mode] [model] [continue] [timeout=10m] <prompt>` — leading
74
+ * Parse `/agy [mode] [model] [agent=name] [continue] [timeout=10m] <prompt>` — leading
72
75
  * option tokens are consumed in any order; the remainder is the prompt.
73
76
  */
74
77
  export function parseAgyCommandArgs(args: string): AgyCommandArgs {
@@ -87,6 +90,12 @@ export function parseAgyCommandArgs(args: string): AgyCommandArgs {
87
90
  parsed.model = MODEL_ALIASES[value];
88
91
  } else if (value === "continue") {
89
92
  parsed.continue = true;
93
+ } else if (value.startsWith("agent=")) {
94
+ try {
95
+ parsed.agent = normalizeAgyAgentName(token.value.slice("agent=".length));
96
+ } catch (error) {
97
+ parsed.error = error instanceof Error ? error.message : String(error);
98
+ }
90
99
  } else if (value.startsWith("context=")) {
91
100
  const context = value.slice("context=".length);
92
101
  if (context === "none" || context === "summary" || context === "recent") {
@@ -124,6 +133,7 @@ function readToken(value: string): { value: string; end: number } | undefined {
124
133
  interface InteractiveRun {
125
134
  mode: "plan" | "accept-edits" | "sandbox";
126
135
  model: AgyModel;
136
+ agent?: string;
127
137
  prompt: string;
128
138
  conversation_id?: string;
129
139
  continue?: boolean;
@@ -143,7 +153,7 @@ export function registerAgyCommand(pi: ExtensionAPI): void {
143
153
 
144
154
  pi.registerCommand("agy", {
145
155
  description:
146
- "Run agy directly: /agy [mode] [model] [continue] [context=summary|recent] [timeout=10m] <prompt>; use /agy doctor for diagnostics or /agy usage for quotas.",
156
+ "Run agy directly: /agy [mode] [model] [agent=name] [continue] [context=summary|recent] [timeout=10m] <prompt>; use /agy agents to list custom agents.",
147
157
  getArgumentCompletions: (prefix: string) => {
148
158
  const tokens = prefix.trim().split(/\s+/).filter(Boolean);
149
159
  const p = prefix.toLowerCase();
@@ -159,6 +169,7 @@ export function registerAgyCommand(pi: ExtensionAPI): void {
159
169
  ...(tokens[0] === "usage" || tokens[0] === "quota"
160
170
  ? []
161
171
  : [
172
+ { value: "agent=", label: "agent=" },
162
173
  { value: "continue", label: "continue" },
163
174
  { value: "timeout=10m", label: "timeout=10m" },
164
175
  ]),
@@ -180,6 +191,8 @@ export function registerAgyCommand(pi: ExtensionAPI): void {
180
191
  const extras = [
181
192
  "continue",
182
193
  "sessions",
194
+ "agents",
195
+ "agent=",
183
196
  "doctor",
184
197
  "usage",
185
198
  "quota",
@@ -206,6 +219,15 @@ export function registerAgyCommand(pi: ExtensionAPI): void {
206
219
  await runSessionsPicker(pi, ctx);
207
220
  return;
208
221
  }
222
+ const agentsMatch = /^agents(?:\s+(.+))?$/.exec(command);
223
+ if (agentsMatch) {
224
+ if (agentsMatch[1]) {
225
+ ctx.ui.notify("agy: agents takes no arguments", "error");
226
+ return;
227
+ }
228
+ await showAgents(ctx);
229
+ return;
230
+ }
209
231
  const doctorMatch = /^doctor(?:\s+(.+))?$/.exec(command);
210
232
  if (doctorMatch) {
211
233
  if (doctorMatch[1]) {
@@ -243,9 +265,17 @@ export function registerAgyCommand(pi: ExtensionAPI): void {
243
265
  }
244
266
 
245
267
  let model = parsed.model;
246
- if (!model && parsed.continue) {
268
+ let agent = parsed.agent;
269
+ if (parsed.continue && (!model || !agent)) {
247
270
  const prior = await getSession(ctx.cwd);
248
- if (prior?.last_model && isAgyModel(prior.last_model)) model = prior.last_model;
271
+ if (!model && prior?.last_model && isAgyModel(prior.last_model)) model = prior.last_model;
272
+ if (!agent && prior?.last_agent) {
273
+ try {
274
+ agent = normalizeAgyAgentName(prior.last_agent);
275
+ } catch {
276
+ // Ignore malformed legacy session metadata.
277
+ }
278
+ }
249
279
  }
250
280
  if (!model) {
251
281
  const pick = await ctx.ui.select("agy model", MODEL_OPTIONS);
@@ -269,6 +299,7 @@ export function registerAgyCommand(pi: ExtensionAPI): void {
269
299
  await executeConfirmedRun(pi, ctx, {
270
300
  mode,
271
301
  model,
302
+ agent,
272
303
  prompt,
273
304
  continue: parsed.continue,
274
305
  timeout_ms: parsed.timeout_ms,
@@ -298,6 +329,27 @@ async function showDoctor(ctx: ExtensionCommandContext): Promise<void> {
298
329
  }
299
330
  }
300
331
 
332
+ /** `/agy agents` — list configured custom agents without inference. */
333
+ async function showAgents(ctx: ExtensionCommandContext): Promise<void> {
334
+ try {
335
+ await ctx.waitForIdle();
336
+ ctx.ui.setStatus("agy", "agy: discovering custom agents…");
337
+ const agents = await inspectAgyAgents(ctx.cwd, ctx.signal);
338
+ ctx.ui.notify(
339
+ agents.length ? `configured agy agents:\n${agents.map((agent) => `- ${agent}`).join("\n")}` : "No custom agy agents are configured.",
340
+ "info",
341
+ );
342
+ } catch (error) {
343
+ if (ctx.signal?.aborted) ctx.ui.notify("agy: agent discovery cancelled", "info");
344
+ else {
345
+ const message = error instanceof Error ? error.message : String(error);
346
+ ctx.ui.notify(`agy agent discovery failed: ${message}`, "error");
347
+ }
348
+ } finally {
349
+ ctx.ui.setStatus("agy", undefined);
350
+ }
351
+ }
352
+
301
353
  /** `/agy usage` — show model quotas without starting an agent turn. */
302
354
  async function showUsage(
303
355
  ctx: ExtensionCommandContext,
@@ -328,8 +380,9 @@ async function runSessionsPicker(
328
380
  const options = history.map((entry, index) => {
329
381
  const id = entry.conversation_id.slice(0, 8);
330
382
  const model = entry.model ?? "unknown model";
383
+ const agent = entry.agent ? ` · agent ${entry.agent}` : "";
331
384
  const summary = entry.summary ? `${entry.summary.slice(0, 50)} · ` : "";
332
- return `${index + 1}. ${summary}${model} · ${describeWhen(entry.updated_at)} · ${id}…`;
385
+ return `${index + 1}. ${summary}${model}${agent} · ${describeWhen(entry.updated_at)} · ${id}…`;
333
386
  });
334
387
  const pick = await ctx.ui.select("resume agy conversation", options);
335
388
  if (!pick) {
@@ -358,6 +411,7 @@ async function runSessionsPicker(
358
411
  await executeConfirmedRun(pi, ctx, {
359
412
  mode,
360
413
  model: isAgyModel(entry.model) ? entry.model : "flash-medium",
414
+ agent: entry.agent,
361
415
  prompt: text.trim(),
362
416
  conversation_id: entry.conversation_id,
363
417
  });
@@ -379,6 +433,7 @@ async function executeConfirmedRun(
379
433
  if (run.mode === "accept-edits") {
380
434
  const dirt = await describePreRunDirt(cwd, ctx.signal).catch(() => null);
381
435
  const dirtLine = dirt ? `\nworkspace: ${dirt}` : "";
436
+ const agentLine = run.agent ? `\nagent: ${run.agent}` : "";
382
437
  const contextLine =
383
438
  contextMode === "none"
384
439
  ? "\ncontext: none"
@@ -391,7 +446,7 @@ async function executeConfirmedRun(
391
446
  : "";
392
447
  const ok = await ctx.ui.confirm(
393
448
  "Run agy (accept-edits)?",
394
- `model: ${run.model} (${resolveAgyModelId(run.model)})\ndir: ${cwd}${dirtLine}${contextLine}\n\ntask: ${run.prompt.slice(0, 200)}${run.prompt.length > 200 ? "…" : ""}\n\nThis grants agy permission to modify files and run commands.${warning}`,
449
+ `model: ${run.model} (${resolveAgyModelId(run.model)})${agentLine}\ndir: ${cwd}${dirtLine}${contextLine}\n\ntask: ${run.prompt.slice(0, 200)}${run.prompt.length > 200 ? "…" : ""}\n\nThis grants agy permission to modify files and run commands.${warning}`,
395
450
  );
396
451
  if (!ok) {
397
452
  ctx.ui.notify("agy: cancelled", "info");
@@ -403,11 +458,12 @@ async function executeConfirmedRun(
403
458
  // a second LLM turn and the command works even when tools are limited.
404
459
  const status = createStatusThrottler(ctx);
405
460
  try {
406
- status(`starting (${run.model} · ${run.mode})`);
461
+ status(`starting (${run.model} · ${run.mode}${run.agent ? ` · agent ${run.agent}` : ""})`);
407
462
  const result = await executeAgyTask(
408
463
  {
409
464
  prompt: run.prompt,
410
465
  model: run.model,
466
+ agent: run.agent,
411
467
  mode: run.mode,
412
468
  dir: cwd,
413
469
  timeout_ms: run.timeout_ms ?? DEFAULT_TIMEOUT_MS,
@@ -7,7 +7,9 @@ import {
7
7
  checkAgyUsage,
8
8
  findAgyQuotaEntries,
9
9
  formatAgyUsage,
10
+ inspectAgyAgents,
10
11
  isAgyQuotaExhausted,
12
+ normalizeAgyAgentName,
11
13
  resolveAgyModelAlias,
12
14
  resolveAgyModelId,
13
15
  type AgyModel,
@@ -22,7 +24,7 @@ import {
22
24
  } from "./lib/execute.js";
23
25
  import { describeWhen, truncate } from "./lib/output.js";
24
26
  import { renderAgyCall, renderAgyResult } from "./lib/render.js";
25
- import { getHistory } from "./lib/sessions.js";
27
+ import { getHistory, getSession } from "./lib/sessions.js";
26
28
 
27
29
  const DEFAULT_TIMEOUT_MS = 300_000;
28
30
  const MAX_TIMEOUT_MS = 600_000;
@@ -52,6 +54,7 @@ export default function piAgyExtension(pi: ExtensionAPI) {
52
54
  "Use gpt-oss when an open-model alternative is specifically desired.",
53
55
  "For consequential work, use one family to produce and the opposite family to cross-review in mode=plan; do not spend both quota groups on trivial tasks.",
54
56
  "Reuse conversation_id or continue=true for multi-step plan→implement→review handoffs.",
57
+ "Use agent only when the user requests a configured custom agy agent; call agy_agents first if the exact name is unknown.",
55
58
  "Keep agy_execute context=none unless the delegated task depends on prior Pi discussion; use summary before recent to minimize disclosure.",
56
59
  "Use agy_usage before choosing a model when quota availability matters; agy_execute also refreshes and returns a quota snapshot.",
57
60
  "Batch related work, prefer digest output for non-write calls, and avoid parallel agy_execute calls within one shared-quota group or directory.",
@@ -85,6 +88,13 @@ export default function piAgyExtension(pi: ExtensionAPI) {
85
88
  "Reasoning effort passed to agy (--effort). Optional; mostly useful for sonnet/opus/gpt-oss since Gemini aliases encode effort in the model id.",
86
89
  }),
87
90
  ),
91
+ agent: Type.Optional(
92
+ Type.String({
93
+ description: "Configured custom agy agent name. Use agy_agents to discover names.",
94
+ minLength: 1,
95
+ maxLength: 128,
96
+ }),
97
+ ),
88
98
  tier: Type.Optional(
89
99
  Type.Union(
90
100
  [Type.Literal("flash"), Type.Literal("flash-lo"), Type.Literal("pro")],
@@ -156,6 +166,19 @@ export default function piAgyExtension(pi: ExtensionAPI) {
156
166
  const mode = resolveAgyMode(params.mode);
157
167
  const model = params.model as AgyModel | undefined;
158
168
  const contextMode = (params.context ?? "none") as AgyContextMode;
169
+ let agent = normalizeAgyAgentName(params.agent);
170
+ if (!agent && params.conversation_id) {
171
+ agent = (await getHistory(cwd)).find(
172
+ (entry) => entry.conversation_id === params.conversation_id,
173
+ )?.agent;
174
+ } else if (!agent && (params.continue || params.new_session === false)) {
175
+ const storedAgent = (await getSession(cwd))?.last_agent;
176
+ try {
177
+ agent = normalizeAgyAgentName(storedAgent);
178
+ } catch {
179
+ // Ignore malformed legacy session metadata.
180
+ }
181
+ }
159
182
  const contextText =
160
183
  contextMode === "none"
161
184
  ? undefined
@@ -165,6 +188,7 @@ export default function piAgyExtension(pi: ExtensionAPI) {
165
188
  model,
166
189
  tier: params.tier,
167
190
  effort: params.effort,
191
+ agent,
168
192
  mode,
169
193
  dir: cwd,
170
194
  digest: params.digest,
@@ -190,6 +214,7 @@ export default function piAgyExtension(pi: ExtensionAPI) {
190
214
  const excerpt =
191
215
  params.prompt.slice(0, 200) + (params.prompt.length > 200 ? "…" : "");
192
216
  const dirtLine = dirt ? `\nworkspace: ${dirt}` : "";
217
+ const agentLine = agent ? `\nagent: ${agent}` : "";
193
218
  const contextLine =
194
219
  contextMode === "none"
195
220
  ? "\ncontext: none"
@@ -202,7 +227,7 @@ export default function piAgyExtension(pi: ExtensionAPI) {
202
227
  : "";
203
228
  const approved = await ctx.ui.confirm(
204
229
  "Run agy (accept-edits)?",
205
- `model: ${modelLabel}\ndir: ${cwd}${dirtLine}${contextLine}\n\ntask: ${excerpt}\n\nThis grants agy permission to modify files and run commands.${warning}`,
230
+ `model: ${modelLabel}${agentLine}\ndir: ${cwd}${dirtLine}${contextLine}\n\ntask: ${excerpt}\n\nThis grants agy permission to modify files and run commands.${warning}`,
206
231
  );
207
232
  if (!approved) throw new Error("agy accept-edits cancelled by user");
208
233
  }
@@ -230,6 +255,44 @@ export default function piAgyExtension(pi: ExtensionAPI) {
230
255
  },
231
256
  });
232
257
 
258
+ pi.registerTool({
259
+ name: "agy_agents",
260
+ label: "Antigravity Agents",
261
+ description:
262
+ "List configured custom agy agents without spending a model turn. Use the returned name as agy_execute agent.",
263
+ promptSnippet: "Discover configured custom agy agents before selecting one",
264
+ parameters: Type.Object({
265
+ dir: Type.Optional(
266
+ Type.String({
267
+ description: "Working directory used for the agy CLI check. Defaults to current project root.",
268
+ }),
269
+ ),
270
+ }),
271
+
272
+ async execute(_toolCallId, params, signal, _onUpdate, ctx) {
273
+ const cwd = params.dir ? path.resolve(ctx.cwd, params.dir) : ctx.cwd;
274
+ if (params.dir) {
275
+ try {
276
+ const info = await stat(cwd);
277
+ if (!info.isDirectory()) throw new Error(`Working directory is not a directory: ${cwd}`);
278
+ } catch (error) {
279
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
280
+ throw new Error(`Working directory does not exist: ${cwd}`);
281
+ }
282
+ throw error;
283
+ }
284
+ }
285
+ const agents = await inspectAgyAgents(cwd, signal);
286
+ const text = agents.length
287
+ ? `configured agy agents:\n${agents.map((agent) => `- ${agent}`).join("\n")}`
288
+ : "No custom agy agents are configured.";
289
+ return {
290
+ content: [{ type: "text", text }],
291
+ details: { cwd, agents },
292
+ };
293
+ },
294
+ });
295
+
233
296
  pi.registerTool({
234
297
  name: "agy_history",
235
298
  label: "Antigravity Conversations",
@@ -267,12 +330,13 @@ export default function piAgyExtension(pi: ExtensionAPI) {
267
330
  }
268
331
  const lines = limited.map((entry, index) => {
269
332
  const model = entry.model ?? "unknown model";
333
+ const agent = entry.agent ? ` · agent ${entry.agent}` : "";
270
334
  const summary = entry.summary ? ` · ${entry.summary}` : "";
271
- return `${index + 1}. ${entry.conversation_id} · ${model} · ${describeWhen(entry.updated_at)}${summary}`;
335
+ return `${index + 1}. ${entry.conversation_id} · ${model}${agent} · ${describeWhen(entry.updated_at)}${summary}`;
272
336
  });
273
337
  const text =
274
338
  `agy conversations for ${cwd} (most recent first):\n${lines.join("\n")}\n\n` +
275
- "Resume with agy_execute conversation_id=<id>, or continue=true for the most recent.";
339
+ "Resume with agy_execute conversation_id=<id>, or continue=true for the most recent; recorded agents are restored automatically.";
276
340
  return {
277
341
  content: [{ type: "text", text }],
278
342
  details: { dir: cwd, conversations: limited },
@@ -78,6 +78,8 @@ export interface AgyOptions {
78
78
  model?: AgyModel;
79
79
  tier?: "flash" | "flash-lo" | "pro";
80
80
  effort?: AgyEffort;
81
+ /** Optional custom agent name passed to `agy --agent`. */
82
+ agent?: string;
81
83
  mode?: "plan" | "accept-edits" | "sandbox";
82
84
  dir: string;
83
85
  timeout_ms: number;
@@ -239,12 +241,59 @@ export function isTransientAgyFailure(message: string): boolean {
239
241
  return TRANSIENT_FAILURE_PATTERN.test(message);
240
242
  }
241
243
 
244
+ const MAX_AGENT_NAME_LENGTH = 128;
245
+ const MAX_AGENT_COUNT = 200;
246
+
247
+ export function normalizeAgyAgentName(value?: string): string | undefined {
248
+ if (value === undefined) return undefined;
249
+ const agent = value.trim();
250
+ if (!agent) throw new Error("agy agent must not be empty");
251
+ if (/[\x00-\x1f\x7f]/.test(agent)) {
252
+ throw new Error("agy agent must not contain control characters");
253
+ }
254
+ if (agent.length > MAX_AGENT_NAME_LENGTH) {
255
+ throw new Error(`agy agent must be at most ${MAX_AGENT_NAME_LENGTH} characters`);
256
+ }
257
+ return agent;
258
+ }
259
+
260
+ /** Parse the intentionally simple, line-oriented output of `agy agents`. */
261
+ export function parseAgyAgents(output: string): string[] {
262
+ const agents: string[] = [];
263
+ for (const raw of output.split(/\r?\n/)) {
264
+ const line = raw.trim();
265
+ if (
266
+ !line ||
267
+ /^available\s+agents:?$/i.test(line) ||
268
+ /^name\s+/i.test(line) ||
269
+ /^(?:no|zero)\s+(?:custom\s+)?agents?\b/i.test(line)
270
+ ) {
271
+ continue;
272
+ }
273
+ const candidate = line
274
+ .split(/\t|\s{2,}/, 1)[0]
275
+ ?.replace(/^[-*]\s*/, "")
276
+ .trim();
277
+ try {
278
+ const agent = normalizeAgyAgentName(candidate);
279
+ if (agent && !agents.includes(agent)) {
280
+ agents.push(agent);
281
+ if (agents.length >= MAX_AGENT_COUNT) break;
282
+ }
283
+ } catch {
284
+ // Ignore malformed diagnostics and overlong names from CLI output.
285
+ }
286
+ }
287
+ return agents;
288
+ }
289
+
242
290
  export function buildAgyArgs(options: AgyOptions): string[] {
243
291
  if (options.continue && options.conversation_id) {
244
292
  throw new Error("agy cannot use --continue and --conversation together");
245
293
  }
246
294
 
247
295
  const model = resolveAgyModelId(options.model, options.tier);
296
+ const agent = normalizeAgyAgentName(options.agent);
248
297
  const timeoutSec = Math.ceil(options.timeout_ms / 1000);
249
298
  const mode = options.mode ?? "accept-edits";
250
299
  const writes = mode === "accept-edits";
@@ -266,6 +315,7 @@ export function buildAgyArgs(options: AgyOptions): string[] {
266
315
  ...(options.effort && supportsAgyEffort(options.model, options.tier)
267
316
  ? ["--effort", options.effort]
268
317
  : []),
318
+ ...(agent ? ["--agent", agent] : []),
269
319
  ];
270
320
 
271
321
  if (options.continue) {
@@ -366,6 +416,23 @@ export async function checkAgyConnectivity(
366
416
  await inspectAgyModels(cwd, signal, timeoutMs);
367
417
  }
368
418
 
419
+ /** List configured custom agents without spending a model turn. */
420
+ export async function inspectAgyAgents(
421
+ cwd: string,
422
+ signal?: AbortSignal,
423
+ timeoutMs?: number,
424
+ ): Promise<string[]> {
425
+ const output = await runPreflightCommand(
426
+ ["agents"],
427
+ cwd,
428
+ signal,
429
+ "agy agents check",
430
+ true,
431
+ timeoutMs,
432
+ );
433
+ return parseAgyAgents(output);
434
+ }
435
+
369
436
  /**
370
437
  * Refresh model-specific quotas without spending a model turn. Newer agy
371
438
  * versions answer read-only `/usage` in print mode; older versions may not,
@@ -8,6 +8,7 @@ import {
8
8
  getAgyConversationId,
9
9
  isAgyQuotaExhausted,
10
10
  isTransientAgyFailure,
11
+ normalizeAgyAgentName,
11
12
  resolveAgyModelAlias,
12
13
  resolveAgyModelId,
13
14
  spawnAgyStream,
@@ -25,7 +26,7 @@ import {
25
26
  type GitBaseline,
26
27
  } from "./postflight.js";
27
28
  import { resetPreflightCache, runPreflight } from "./preflight.js";
28
- import { getSession, saveSession, conversationSummary } from "./sessions.js";
29
+ import { getHistory, getSession, saveSession, conversationSummary } from "./sessions.js";
29
30
 
30
31
  export type AgyMode = "plan" | "accept-edits" | "sandbox";
31
32
 
@@ -34,6 +35,7 @@ export interface AgyExecutionOptions {
34
35
  model?: AgyModel;
35
36
  tier?: "flash" | "flash-lo" | "pro";
36
37
  effort?: AgyEffort;
38
+ agent?: string;
37
39
  mode: AgyMode;
38
40
  dir: string;
39
41
  digest?: boolean;
@@ -55,6 +57,7 @@ export interface AgyExecutionDetails {
55
57
  verify_cmd: string | null;
56
58
  permissions_skipped?: boolean;
57
59
  effort?: AgyEffort;
60
+ agent?: string;
58
61
  usage?: AgyUsage;
59
62
  duration_seconds?: number;
60
63
  changed_files?: string[];
@@ -77,6 +80,7 @@ export async function executeAgyTask(
77
80
  onProgress?: (message: string) => void,
78
81
  ): Promise<AgyExecutionResult> {
79
82
  validateAgyExecutionOptions(options);
83
+ let agent = normalizeAgyAgentName(options.agent);
80
84
  const startedAt = Date.now();
81
85
  const budgetController = new AbortController();
82
86
  const abortSignal = signal
@@ -108,16 +112,32 @@ export async function executeAgyTask(
108
112
  }
109
113
 
110
114
  let conversationId = options.conversation_id;
115
+ const resumesLatest = options.continue || options.new_session === false;
116
+ const prior =
117
+ (!conversationId && options.new_session !== true) || (!agent && resumesLatest)
118
+ ? await getSession(options.dir)
119
+ : undefined;
111
120
  if (
112
121
  !conversationId &&
113
122
  !options.continue &&
114
- options.new_session !== true
123
+ prior?.last_conversation_id &&
124
+ options.new_session === false
115
125
  ) {
116
- const prior = await getSession(options.dir);
117
- if (prior?.last_conversation_id && options.new_session === false) {
118
- conversationId = prior.last_conversation_id;
126
+ conversationId = prior.last_conversation_id;
127
+ }
128
+ if (!agent && resumesLatest && prior?.last_agent) {
129
+ try {
130
+ agent = normalizeAgyAgentName(prior.last_agent);
131
+ } catch {
132
+ // Ignore malformed legacy store data rather than blocking a resume.
119
133
  }
120
134
  }
135
+ if (!agent && conversationId) {
136
+ const recorded = (await getHistory(options.dir)).find(
137
+ (entry) => entry.conversation_id === conversationId,
138
+ );
139
+ if (recorded?.agent) agent = normalizeAgyAgentName(recorded.agent);
140
+ }
121
141
 
122
142
  const useDigest = options.digest ?? options.mode !== "accept-edits";
123
143
  const verifyCmd =
@@ -182,7 +202,7 @@ export async function executeAgyTask(
182
202
  // Emitted via onProgress directly: progress tracking (and therefore
183
203
  // retry eligibility) must only reflect activity from agy itself.
184
204
  onProgress?.(
185
- `agy: starting (${effectiveModel}, ${options.mode}${options.effort ? `, effort ${options.effort}` : ""})…`,
205
+ `agy: starting (${effectiveModel}, ${options.mode}${agent ? `, agent ${agent}` : ""}${options.effort ? `, effort ${options.effort}` : ""})…`,
186
206
  );
187
207
 
188
208
  return spawnAgyStream(
@@ -190,6 +210,7 @@ export async function executeAgyTask(
190
210
  prompt: finalPrompt,
191
211
  model,
192
212
  effort: options.effort,
213
+ agent,
193
214
  mode: options.mode,
194
215
  dir: options.dir,
195
216
  timeout_ms: runTimeoutMs,
@@ -213,6 +234,7 @@ export async function executeAgyTask(
213
234
  effectiveModel,
214
235
  AbortSignal.timeout(10_000),
215
236
  conversationSummary(options.prompt),
237
+ agent,
216
238
  );
217
239
  } catch (error) {
218
240
  const reason = error instanceof Error ? error.message : String(error);
@@ -256,6 +278,7 @@ export async function executeAgyTask(
256
278
  verify_cmd: verifyCmd,
257
279
  permissions_skipped: options.mode === "accept-edits" ? skipPermissions : false,
258
280
  effort: options.effort,
281
+ agent,
259
282
  usage: run.usage,
260
283
  duration_seconds: run.duration_seconds,
261
284
  changed_files: changedFiles,
@@ -272,6 +295,7 @@ export async function executeAgyTask(
272
295
  );
273
296
  } catch (error) {
274
297
  const conversationId = getAgyConversationId(error);
298
+ let conversationPersisted = false;
275
299
  if (conversationId) {
276
300
  try {
277
301
  // The composed signal is aborted in exactly the cases this save
@@ -284,13 +308,20 @@ export async function executeAgyTask(
284
308
  effectiveModel,
285
309
  AbortSignal.timeout(10_000),
286
310
  conversationSummary(options.prompt),
311
+ agent,
287
312
  );
313
+ conversationPersisted = true;
288
314
  } catch {
289
315
  // Preserve the original agy failure; session persistence is best effort.
290
316
  }
291
317
  }
292
318
  if (budgetController.signal.aborted && !signal?.aborted) {
293
- throw new Error(`agy timed out after ${options.timeout_ms}ms`);
319
+ const resume = conversationId
320
+ ? conversationPersisted
321
+ ? `; conversation ${JSON.stringify(conversationId.slice(0, 128))} was recorded — resume with conversation_id, /agy continue, or /agy sessions`
322
+ : `; conversation ${JSON.stringify(conversationId.slice(0, 128))} was observed — resume with conversation_id`
323
+ : "";
324
+ throw new Error(`agy timed out after ${options.timeout_ms}ms${resume}`);
294
325
  }
295
326
  throw error;
296
327
  } finally {
@@ -300,6 +331,7 @@ export async function executeAgyTask(
300
331
 
301
332
  export function validateAgyExecutionOptions(options: AgyExecutionOptions): void {
302
333
  if (!options.prompt?.trim()) throw new Error("agy prompt must not be empty");
334
+ normalizeAgyAgentName(options.agent);
303
335
  if (!Number.isFinite(options.timeout_ms) || options.timeout_ms <= 0) {
304
336
  throw new Error("agy timeout_ms must be a positive finite number");
305
337
  }
@@ -64,6 +64,7 @@ export function renderAgyCall(
64
64
  model?: unknown;
65
65
  tier?: unknown;
66
66
  mode?: unknown;
67
+ agent?: unknown;
67
68
  context?: unknown;
68
69
  prompt?: unknown;
69
70
  } | undefined,
@@ -73,12 +74,13 @@ export function renderAgyCall(
73
74
  const model = callArgs.model ?? callArgs.tier ?? "default";
74
75
  const mode = callArgs.mode ?? "accept-edits";
75
76
  const contextMode = callArgs.context ?? "none";
77
+ const agent = callArgs.agent ? oneLine(callArgs.agent, 128) : "";
76
78
  const header =
77
79
  theme.fg("toolTitle", theme.bold("agy ")) +
78
80
  theme.fg("accent", String(model)) +
79
81
  theme.fg(
80
82
  "dim",
81
- ` · ${String(mode)}${contextMode === "none" ? "" : ` · context ${String(contextMode)}`}`,
83
+ ` · ${String(mode)}${agent ? ` · agent ${agent}` : ""}${contextMode === "none" ? "" : ` · context ${String(contextMode)}`}`,
82
84
  );
83
85
  const promptLine = oneLine(callArgs.prompt, 180);
84
86
  return new Text(
@@ -123,7 +125,10 @@ function formatAgyResult(
123
125
  : "";
124
126
  const lines = [
125
127
  theme.fg("success", "✓ agy") +
126
- theme.fg("muted", ` · ${details.model} · ${details.mode}${duration}`),
128
+ theme.fg(
129
+ "muted",
130
+ ` · ${details.model} · ${details.mode}${details.agent ? ` · agent ${oneLine(details.agent, 128)}` : ""}${duration}`,
131
+ ),
127
132
  ];
128
133
 
129
134
  const metadata: string[] = [];
@@ -16,6 +16,7 @@ import { randomUUID } from "node:crypto";
16
16
  export interface AgyConversationEntry {
17
17
  conversation_id: string;
18
18
  model?: string;
19
+ agent?: string;
19
20
  updated_at: string;
20
21
  /** Short task excerpt so humans and agents can tell conversations apart. */
21
22
  summary?: string;
@@ -24,6 +25,7 @@ export interface AgyConversationEntry {
24
25
  export interface AgySessionRecord {
25
26
  last_conversation_id?: string;
26
27
  last_model?: string;
28
+ last_agent?: string;
27
29
  updated_at?: string;
28
30
  /** Recent conversations for the directory, most recent first. */
29
31
  history?: AgyConversationEntry[];
@@ -69,6 +71,7 @@ export interface AgySessionStore {
69
71
  model?: string,
70
72
  signal?: AbortSignal,
71
73
  summary?: string,
74
+ agent?: string,
72
75
  ): Promise<void>;
73
76
  }
74
77
 
@@ -160,6 +163,12 @@ export function createSessionStore(
160
163
  updated_at: entry.updated_at,
161
164
  };
162
165
  if (typeof entry.model === "string") normalized.model = entry.model;
166
+ if (typeof entry.agent === "string") {
167
+ const agent = entry.agent.trim();
168
+ if (agent && agent.length <= 128 && !/[\x00-\x1f\x7f]/.test(agent)) {
169
+ normalized.agent = agent;
170
+ }
171
+ }
163
172
  if (typeof entry.summary === "string") normalized.summary = entry.summary;
164
173
  return normalized;
165
174
  })
@@ -245,6 +254,7 @@ export function createSessionStore(
245
254
  model?: string,
246
255
  signal?: AbortSignal,
247
256
  summary?: string,
257
+ agent?: string,
248
258
  ): Promise<void> {
249
259
  const operation = waitForMutation(signal).then(() =>
250
260
  withStoreLock(async () => {
@@ -255,9 +265,10 @@ export function createSessionStore(
255
265
  store[key] = {
256
266
  last_conversation_id: conversationId,
257
267
  last_model: model,
268
+ last_agent: agent,
258
269
  updated_at: updatedAt,
259
270
  history: [
260
- { conversation_id: conversationId, model, updated_at: updatedAt, summary },
271
+ { conversation_id: conversationId, model, agent, updated_at: updatedAt, summary },
261
272
  ...(Array.isArray(record.history) ? record.history : []).filter(
262
273
  (entry) =>
263
274
  entry &&
@@ -295,6 +306,7 @@ export function saveSession(
295
306
  model?: string,
296
307
  signal?: AbortSignal,
297
308
  summary?: string,
309
+ agent?: string,
298
310
  ): Promise<void> {
299
- return defaultStore.saveSession(dir, conversationId, model, signal, summary);
311
+ return defaultStore.saveSession(dir, conversationId, model, signal, summary, agent);
300
312
  }
@@ -1,3 +1,5 @@
1
+ import { stripTerminalSequences } from "@earendil-works/pi-tui";
2
+
1
3
  export interface AgyUsage {
2
4
  input_tokens?: number;
3
5
  output_tokens?: number;
@@ -70,6 +72,25 @@ export function parseStreamLine(line: string): AgyStreamLine | null {
70
72
  }
71
73
  }
72
74
 
75
+ function compactProgressValue(value: unknown, max = 120): string | undefined {
76
+ if (typeof value !== "string") return undefined;
77
+ const compact = stripTerminalSequences(value)
78
+ .replace(/[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]+/g, " ")
79
+ .replace(/\s+/g, " ")
80
+ .trim();
81
+ if (!compact) return undefined;
82
+ return compact.length > max ? compact.slice(0, max - 1) + "…" : compact;
83
+ }
84
+
85
+ function formatAsyncThreshold(value: unknown): string | undefined {
86
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
87
+ if (value >= 1_000) {
88
+ const seconds = value / 1_000;
89
+ return `${Number.isInteger(seconds) ? seconds : seconds.toFixed(1)}s`;
90
+ }
91
+ return `${value}ms`;
92
+ }
93
+
73
94
  export function formatStepProgress(parsed: AgyStreamLine): string | null {
74
95
  if (parsed.event === "init") {
75
96
  const model = parsed.init?.model ?? "agy";
@@ -88,9 +109,24 @@ export function formatStepProgress(parsed: AgyStreamLine): string | null {
88
109
  if (!step) return null;
89
110
 
90
111
  if (step.step_type === "tool" && step.state === "ACTIVE") {
91
- const name = step.tool_name ?? step.tool_info?.name ?? "tool";
92
- const target = step.tool_info?.parameters?.TargetFile;
93
- return target ? `▸ ${name} → ${String(target)}` : `▸ ${name}`;
112
+ const name =
113
+ compactProgressValue(step.tool_name ?? step.tool_info?.name, 40) ?? "tool";
114
+ const parameters = step.tool_info?.parameters;
115
+ const target = compactProgressValue(parameters?.TargetFile);
116
+ const action =
117
+ compactProgressValue(parameters?.toolAction) ??
118
+ compactProgressValue(parameters?.toolSummary);
119
+ const taskId = compactProgressValue(parameters?.TaskId, 60);
120
+ const asyncThreshold = formatAsyncThreshold(parameters?.WaitMsBeforeAsync);
121
+ const detail = target
122
+ ? ` → ${target}`
123
+ : taskId
124
+ ? ` → task ${taskId}${action ? ` — ${action}` : ""}`
125
+ : action
126
+ ? ` — ${action}`
127
+ : "";
128
+ const asyncNote = asyncThreshold ? ` · async threshold ${asyncThreshold}` : "";
129
+ return `▸ ${name}${detail}${asyncNote}`;
94
130
  }
95
131
 
96
132
  if (step.step_type === "agent_response" && step.text_delta) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@juanbenjumea/pi-agy",
3
- "version": "0.6.3",
3
+ "version": "0.6.5",
4
4
  "description": "Reliable Antigravity delegation for Pi — quota-aware runs, resumable tasks, repo verification, cancellation, and trustworthy diff summaries.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -3,7 +3,7 @@ name: agy-delegate
3
3
  description: >
4
4
  Delegate bulk implementation, scaffolding, repetitive refactors, and
5
5
  exhaustive test generation to the Antigravity CLI (agy).
6
- argument-hint: "prompt=\"...\" [model=flash-low|flash-medium|flash-high|pro-low|pro-high|sonnet|opus|gpt-oss] [mode=plan|accept-edits|sandbox]"
6
+ argument-hint: "prompt=\"...\" [model=flash-low|flash-medium|flash-high|pro-low|pro-high|sonnet|opus|gpt-oss] [agent=name] [mode=plan|accept-edits|sandbox]"
7
7
  license: MIT
8
8
  ---
9
9
 
@@ -43,6 +43,8 @@ agy_execute prompt="Plan the migration to ESM" model=sonnet mode=plan digest=tru
43
43
  agy_execute prompt="Review our earlier API decision" model=sonnet mode=plan context=summary
44
44
  agy_execute prompt="Implement the approved plan" conversation_id=<id> mode=accept-edits
45
45
  agy_execute prompt="Adversarial review the diff" model=opus effort=high mode=plan
46
+ agy_agents
47
+ agy_execute prompt="Investigate the crash" agent=gsd-debugger mode=plan
46
48
  agy_history
47
49
  agy_usage
48
50
  ```
@@ -60,8 +62,9 @@ agy_usage
60
62
  - **Default to `mode=plan`** for exploration; escalate to `accept-edits` only for scoped batches.
61
63
  - **Always review the `git diff`** after agy runs with `accept-edits`.
62
64
  - **Run `just ci`** (or the project gate) after write modes in this repo.
63
- - **Never use agy for irreversible production changes.**
65
+ - **Never use agy for irreversible production changes or persistent background servers/watchers.** Delegations are bounded; timeout/cancellation kills the full process tree rather than releasing unowned work.
64
66
  - Reuse `conversation_id` or `continue=true` for multi-step plan → implement → review.
67
+ - Use `agent` only when the user requests a configured custom agent; call `agy_agents` first when the exact name is unknown. Recorded agent identity is restored on resume.
65
68
  - Keep `context=none` (default) unless the task depends on prior Pi discussion; prefer `summary` over `recent` to minimize disclosure. Context handoff excludes system prompts, thinking, tool arguments/results, images, and custom messages.
66
69
  - Use `flash-medium` by default, `flash-low` for trivial/high-volume work, and `flash-high` for difficult agentic work.
67
70
  - Escalate within the Gemini quota group to `pro-low` or `pro-high` only when needed.
@@ -74,6 +77,7 @@ agy_usage
74
77
  ## Enhancements over upstream pi-agy
75
78
 
76
79
  - **Quota discovery** — `agy_usage` and `/agy usage` report model-specific remaining quota and reset times; executions refresh quota snapshots, automatically fall back when an implicit default is exhausted, and return machine-readable `quota_status` as well.
80
+ - **Custom-agent selection** — `agy_agents` and `/agy agents` list configured agents without inference; `agent` / `agent=name` passes a validated `--agent` and persists its identity with resumable conversations.
77
81
  - **Streaming progress and receipts** — live tool steps via `stream-json` and Pi `onUpdate`; direct `/agy` runs persist bounded, expandable TUI-only receipts without feeding them to the primary model.
78
82
  - **Conversation continuity** — `conversation_id`, `continue`, session store under `$PI_CODING_AGENT_DIR/agy-sessions.json` (or `~/.pi/agent/agy-sessions.json` by default) with one-line task summaries; runs that time out or are cancelled are recorded too and stay resumable, and the `agy_history` tool lets agents list past conversations.
79
83
  - **Optional Pi context handoff** — `context=summary|recent` sends bounded text-only history while excluding system prompts, thinking, tool calls/results, images, and custom messages; default is `none`.