Nagent

nagent

Read this before bb thread spawn. Use bb-cli for other thread operations.

Defaults

Use Codex gpt-5.6-sol, reasoning high, service tier fast ("GPT 5.6 Sol High Fast"). Use xhigh for larger refactors. The user's explicit choices override these defaults.

For a different requested model, use its catalog defaultReasoningEffort when unspecified, and enable fast only when asked. Do not infer a higher reasoning level from the model name.

Prefer bare bb; "$BB_CLI" is also valid when set.

Look Up the Target

bb project list --json
bb provider list --json
bb provider models <provider-id> --json

• Project: Match the name and confirm sources[].path is the requested repository. Always pass --project; never hardcode an ID.
• Provider: Look it up. Common mappings are Cursor CLI → acp-cursor, Codex/ChatGPT subscription → codex, and Claude Code → claude-code. Grok via Cursor is not acp-grok, which is Grok Build.
• Model: Use the catalog ID. Match both displayName and supportedReasoningEfforts[].description; model IDs, reasoning labels, and service tiers are separate.

For Cursor/Grok or Codex Max naming traps, read provider details. Verify examples against the current catalog; do not guess IDs or substitute a different provider.

Pi Agent: billing safety

--provider pi selects the harness; the full --model provider/model selects the inference and billing route. ChatGPT subscription example:

--provider pi --model openai-codex/gpt-6-astra --reasoning-level xhigh

Query Pi's catalog on the target --machine or --environment. openai-codex uses the ChatGPT subscription; OpenRouter and Vercel AI Gateway bill separately. Never substitute routes without the user's approval; stop if unavailable. After spawning, verify the full model ID and reasoning in the client/turn/requested execution metadata, not just the display name.

Permission Checks

The user's investigation/build workers default to full. A child cannot exceed the parent's permission mode, so verify the parent before requesting it and the child after spawning.

Run the bundled script relative to this skill's directory:

scripts/permission-mode.sh "$BB_THREAD_ID"

For a full worker, this must print full. Otherwise, stop and report that the requested mode is unavailable under the parent's limits. Do not bypass those limits. If the user requests another mode, confirm the provider supports it.

The modes are accept-edits (sandbox, human-reviewed escalations), auto (sandbox, automatic review), and full (no sandbox). A read-only brief must forbid writes regardless of mode. For Cursor permission issues, use the provider-details reference.

Spawn

Use the resolved IDs and chosen settings. This example shows the default worker's reasoning, tier, and permissions; replace them when the user requests different settings.

bb thread spawn --json \
  --project <project-id> \
  --new-environment worktree \
  --provider <provider-id> \
  --model <model-id> \
  --reasoning-level high \
  --service-tier fast \
  --permission-mode full \
  --title "Short title" \
  --prompt "$(cat <<'EOF'
Objective: ...
Constraints: ...
Skills and files: ...
Deliverable: ...
Validation: ...
Report back: ...
EOF
)"

Always include --json, --title, and a complete prompt. The quoted heredoc preserves quotes in the brief.

Parent and Sidebar Placement

• Omit parent flags for a standalone, top-level thread: "not as your own subagent".
• Use --parent-self when this thread coordinates the worker or the job is its subtask.
• Use --parent-thread <id> to nest under another thread. Never combine the two parent flags.

Do not nest unrelated one-off work by default.

Worktree

Use --new-environment worktree for a bb-managed worktree. Do not create one manually unless the user asks.

• Worktrees start with tracked files. Include required untracked files such as .env through the repo's .worktreeinclude; setup may also use .bb-env-setup.sh. See bb guide environments.
• Omit --base-branch for the project default; specify it only when needed.
• Do not combine --machine with an existing --environment ID.
• A null environmentId in the spawn response can mean the worktree is still being created.