diff --git a/capy/skill/gstack/SKILL.md b/capy/skill/gstack/SKILL.md index 9c6fcb697..303cf135b 100644 --- a/capy/skill/gstack/SKILL.md +++ b/capy/skill/gstack/SKILL.md @@ -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.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.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.md` for the selected workflow. When launching a Claude Code session, start its prompt with the typed `/` 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. diff --git a/changelog.d/ship-child-starts-with-typed-ship.md b/changelog.d/ship-child-starts-with-typed-ship.md new file mode 100644 index 000000000..e832153c5 --- /dev/null +++ b/changelog.d/ship-child-starts-with-typed-ship.md @@ -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 ". 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 ` (`/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. diff --git a/docs/ship-budget.md b/docs/ship-budget.md index 5bd755e76..626a4fc2b 100644 --- a/docs/ship-budget.md +++ b/docs/ship-budget.md @@ -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 `: 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 ` (`/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 diff --git a/docs/unattended.md b/docs/unattended.md index c45a1dcd4..4d9bb7f93 100644 --- a/docs/unattended.md +++ b/docs/unattended.md @@ -390,6 +390,29 @@ owner's own words: nothing a person wrote leaves without their click (GST-1243). `gstack-artifact validate --public --private /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 `, and everything else comes after it. Claude Code +expands a skill only when the prompt starts with `/`. 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-`; 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, diff --git a/lib/ship-handoff.ts b/lib/ship-handoff.ts index 786d187dc..cc0bf8af4 100644 --- a/lib/ship-handoff.ts +++ b/lib/ship-handoff.ts @@ -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); diff --git a/test/ship-budget.test.ts b/test/ship-budget.test.ts index af8871f95..3e334427a 100644 --- a/test/ship-budget.test.ts +++ b/test/ship-budget.test.ts @@ -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 , 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', () => {