The token-capped /ship child on Claude Code now starts its prompt with the typed /ship command (GST-3078) (#4487)

The /ship child that `gstack-ship-budget launch` starts on Claude Code
now opens its prompt with `/ship --continue ` (or `/gstack-ship` under
`skill_prefix`), so Claude Code expands the skill instead of hoping the
model finds it.

Why: Claude Code expands a skill only when the prompt starts with the
typed command, and unattended Opus 5.5 found a skill from its
description in 0 of 60 sessions (gstack-evals#366).

Nothing to do: the rule for parents is now in docs/unattended.md.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-18 13:32:03 +00:00
1 parent 0109703797
commit 3ecd7168b2
6 files changed
+52 -8

No files matched your search

+1 -1
View File
@@ -30,7 +30,7 @@ With `GSTACK_CAPY=1`, a workflow started in an unattended or spawned session che
For Capy running GPT-6 Astra, read `${CODEX_HOME:-$HOME/.codex}/skills/gstack/SKILL.md` for routing, then `${CODEX_HOME:-$HOME/.codex}/skills/gstack-<skill>/SKILL.md` for the selected workflow. They are generated for GPT-6 Astra.
For Claude Code, read `~/.claude/skills/gstack/SKILL.md` for routing and `~/.claude/skills/<skill>/SKILL.md` for the selected workflow. When launching a Claude Code session, tell it to load gstack and name the intended workflow. Capy on a Claude model reads the Claude files directly with the Capy adaptations below; that does not make Capy the Claude Code harness.
For Claude Code, read `~/.claude/skills/gstack/SKILL.md` for routing and `~/.claude/skills/<skill>/SKILL.md` for the selected workflow. When launching a Claude Code session, start its prompt with the typed `/<skill>` command and put everything else after it (`docs/unattended.md`, "Starting a child agent"). Capy on a Claude model reads the Claude files directly with the Capy adaptations below; that does not make Capy the Claude Code harness.
If no specific skill was requested, use the router's task-to-skill mapping. Read only the selected workflow and its referenced files. Other models use the closest profile, never claiming one was generated or evaluated for them.
@@ -0,0 +1 @@
- **The token-capped /ship child on Claude Code now starts its prompt with the typed `/ship` command, so the skill actually loads.** When /ship hands its remaining steps to a fresh child (`gstack-ship-budget launch`), the child's prompt used to open with "Load gstack. … Run /ship --continue <brief>". Claude Code expands a skill only when the prompt starts with the typed command, so the child got plain text and had to find /ship on its own, which unattended Opus 5.5 did in 0 of 60 sessions in gstack-evals#366. The prompt now opens with `/ship --continue <brief>` (`/gstack-ship` when `skill_prefix` is on). docs/unattended.md gains the rule for any parent that starts a child agent, and the Capy skill's Claude Code line now says the same.
+3 -1
View File
@@ -244,7 +244,9 @@ line prints `call`, `call_floor` and `above_floor`, so each verdict can be check
remaining sub-cap instead (cap − used − reserved − unknown − its stop overhead).
2. The child is a Capy subagent on the shared machine, or on Claude Code
`gstack-ship-budget launch --in <brief>`: a background `claude -p` (resolved through lib/claude-bin.ts)
with explicit permission flags and the return file named.
with explicit permission flags and the return file named, whose prompt opens with the typed
`/ship --continue <brief>` (`/gstack-ship` under `skill_prefix: true`; see
[unattended.md](unattended.md#starting-a-child-agent-type-the-skill-first)).
3. The child runs `verify-handoff` first; a moved pin refuses
([HANDOFF_PIN_MOVED](troubleshooting.md#handoff-pin-moved)). It admits against its sub-cap
with child_used = its own counter's reading − its reading at `verify-handoff` (a parent-metered
+23
View File
@@ -390,6 +390,29 @@ owner's own words: nothing a person wrote leaves without their click (GST-1243).
`gstack-artifact validate --public <pub> --private <dir>/run.json` runs the
same scan, renderings included, on an existing copy.
## Starting a child agent: type the skill first
When a parent starts another agent to run a gstack skill, the child's prompt
opens with the skill command typed the way a person types it, for example
`/ship --continue <brief>`, and everything else comes after it. Claude Code
expands a skill only when the prompt starts with `/<skill>`. A prompt such as
"Load gstack. … Run /ship …" reaches the model as plain text, and the model
then has to decide on its own to load the skill. In gstack-evals#366, Opus 5.5
found a skill from its description in 0 of 60 unattended sessions, while a
typed command put the skill's text in front of it in 60 of 60.
- **Use the installed name.** With `skill_prefix: true` the command is
`/gstack-<skill>`; a typed name that isn't installed expands to nothing.
- **No Skill tool needed.** Claude Code expands a typed command itself, without
a Skill tool call, so the child's `--allowedTools` doesn't have to list
`Skill` for this.
- **Hosts that don't expand a typed skill**, such as a Capy subagent, get the
skill's SKILL.md path to read instead.
`gstack-ship-budget launch` (`lib/ship-handoff.ts`), the token-capped /ship
child on Claude Code, follows this rule, and `test/ship-budget.test.ts`
checks its prompt.
## How a parent consumes a run
1. **Decide whether the run finished.** For an `/autoplan` run directory,
+3 -1
View File
@@ -22,6 +22,7 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import { spawn, spawnSync } from 'node:child_process';
import { resolveClaudeCommand } from './claude-bin';
import { readConfigKey } from './state-root';
import { wtreeFingerprint } from './script-invocation';
import { resultLine } from './result-codes';
import {
@@ -300,7 +301,8 @@ export function cmdLaunch(argv: string[], ctx: Ctx): Outcome {
const claude = resolveClaudeCommand(ctx.env);
if (!claude) throw usageError('no claude binary resolves (PATH, GSTACK_CLAUDE_BIN); launch the child by hand or rerun with --delegate never');
const session = crypto.randomUUID();
const prompt = `Load gstack. Your Claude Code session id is ${session}. Run /ship --continue ${path.resolve(file)}: first gstack-ship-budget verify-handoff --in ${path.resolve(file)} --session ${session}, then only the steps the brief names, then gstack-ship-budget return as its return contract says.`;
const ship = readConfigKey('skill_prefix', ctx.env) === 'true' ? '/gstack-ship' : '/ship';
const prompt = `${ship} --continue ${path.resolve(file)} Your Claude Code session id is ${session}. First run gstack-ship-budget verify-handoff --in ${path.resolve(file)} --session ${session}, then only the steps the brief names, then gstack-ship-budget return as its return contract says.`;
const log = path.join(path.dirname(block.return_file), `child-${session}.log`);
joinMeter(block.parent_ledger, session, ctx.env);
const out = fs.openSync(log, 'a', 0o600);
+21 -5
View File
@@ -322,8 +322,8 @@ describe('Claude Code child launch', () => {
return { options, prompts };
}
test('launch runs the child in the background with explicit permission flags and the return file named', async () => {
const h = fresh();
/** Launches a child through a fake claude that records its argv. */
async function launchChild(h: Harness) {
const s = started(h, ['--token-cap', '80M', '--meter', 'estimate']);
const ho = h.sb(['handoff', '--run', s.run, '--from', '12', '--to', '22', '--base', 'origin/main']);
const file = ho.out.match(/^HANDOFF: (\S+)/m)![1]!;
@@ -332,16 +332,32 @@ describe('Claude Code child launch', () => {
fs.writeFileSync(fake, `#!/bin/sh\nprintf '%s\\n' "$@" > "${argsFile}.tmp" && mv "${argsFile}.tmp" "${argsFile}"\n`, { mode: 0o755 });
const r = h.sb(['launch', '--in', file], { GSTACK_CLAUDE_BIN: fake });
expect(r.code).toBe(0);
const session = h.field(r.out, 'CHILD', 'session');
expect(h.field(r.out, 'CHILD', 'return')).toBe(ho.out.match(/^RETURN_FILE: (\S+)$/m)![1]!);
for (let i = 0; i < 50 && !fs.existsSync(argsFile); i++) await Bun.sleep(100);
const args = fs.readFileSync(argsFile, 'utf8').split('\n').slice(0, -1);
return { ho, file, r, session: h.field(r.out, 'CHILD', 'session'), args, parsed: parseLikeClaudeCli(args) };
}
test('launch runs the child in the background with explicit permission flags and the return file named', async () => {
const h = fresh();
const { ho, file, r, session, args, parsed } = await launchChild(h);
expect(h.field(r.out, 'CHILD', 'return')).toBe(ho.out.match(/^RETURN_FILE: (\S+)$/m)![1]!);
expect(args.slice(0, 7)).toEqual(['-p', '--session-id', session, '--permission-mode', 'acceptEdits', '--allowedTools', 'Bash,Read,Edit,Write,Grep,Glob']);
const parsed = parseLikeClaudeCli(args);
expect(parsed.options['--allowedTools']).toEqual(['Bash,Read,Edit,Write,Grep,Glob']);
expect(parsed.prompts).toHaveLength(1);
expect(parsed.prompts[0]).toContain(`verify-handoff --in ${file} --session ${session}`);
});
// Value: protects=the Claude Code child loads /ship: Claude Code expands a skill only when the prompt starts with the typed command, and unattended Opus found a skill from its description 0 of 60 times (gstack-evals#366); fails_when=the prompt opens with prose ("Load gstack. … Run /ship") or types /ship under a gstack- prefixed install;
// why_new=the test above checks only that verify-handoff appears somewhere in the prompt; seam=GSTACK_CLAUDE_BIN fake; no_claim=that a real claude expands it
test('the child prompt opens with the typed /ship --continue <brief>, under the installed skill name', async () => {
const plain = await launchChild(fresh());
expect(plain.parsed.prompts[0]).toStartWith(`/ship --continue ${plain.file} `);
const h = fresh();
fs.mkdirSync(h.state, { recursive: true });
fs.writeFileSync(path.join(h.state, 'config.yaml'), 'skill_prefix: true\n');
const prefixed = await launchChild(h);
expect(prefixed.parsed.prompts[0]).toStartWith(`/gstack-ship --continue ${prefixed.file} `);
});
});
describe('stop, resume and recovery', () => {