@team-agent/installer 0.5.104 → 0.5.105

package/crates/team-agent/src/state/repository.rs

@@ -162,7 +162,8 @@ impl<'a> StateRepository<'a> {
         test_support::before_commit();
         let team_key = match intent {
             StateWriteIntent::ResultCollection { owner_team_id } => owner_team_id,
-            StateWriteIntent::ForkAgent { team_key, .. } => Some(team_key),
+            StateWriteIntent::ForkAgent { team_key, .. }
+            | StateWriteIntent::StartAgent { team_key, .. } => Some(team_key),
             _ => {
                 return Err(StateError::SaveFailed(
                     "intent does not accept a bounded Team delta".into(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.104",
+  "version": "0.5.105",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.5.104",
-    "@team-agent/cli-darwin-x64": "0.5.104",
-    "@team-agent/cli-linux-x64": "0.5.104"
+    "@team-agent/cli-darwin-arm64": "0.5.105",
+    "@team-agent/cli-darwin-x64": "0.5.105",
+    "@team-agent/cli-linux-x64": "0.5.105"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

package/skills/team-agent/SKILL.md

@@ -7,48 +7,83 @@ requires_team_agent: ">=0.5.0"
 
 The current assistant is the **leader**. Workers use separate role files and report through Team Agent. Start from a tmux-addressable terminal or supported agent pane, in the workspace root (the parent of the team directory).
 
+## Decide before creating a team
+
+**The user decides each worker's provider and permission bypass. Do not silently choose Pi, true, or false.** Reuse an explicit user policy when it covers the worker; otherwise explain the choices and ask before starting.
+
+Use existing resources rather than establishing new accounts: `team-agent doctor --workspace . --json` reports discovered tools, but installed does not mean authenticated and an absent entry or unknown auth is not proof of unavailability. For providers supported by `models`, use `team-agent models --provider NAME` to check exact model IDs. Do not inspect credentials, automatically log in, or silently substitute a provider after a failed probe.
+
+| Choice | What to explain |
+|---|---|
+| Pi | One Agent tool can use several model catalogs; explicit models require a qualified ID such as `openai-codex/gpt-6-luna` |
+| Codex | The user's existing Codex workflow, native tools, permissions and resumable sessions |
+| Claude / Claude Code | The user's existing Claude workflow, models, native tools and session behavior |
+| Bypass `true` | Fewer permission interruptions, but broader automatic execution authority |
+| Bypass `false` | Keep the selected tool's native permissions; human confirmation may interrupt unattended work |
+
+False is **not** a read-only or sandbox guarantee. Native permission capabilities differ between tools. Suggest combinations based on the user's installed tools, subscriptions and task: for example, an explicitly chosen Codex implementer and Claude reviewer, or two Pi workers when those are the available resources. Different workers may use different providers; an existing worker cannot change provider.
+
 ## Create and start
 
-A team can be plain text; no YAML frontmatter is required:
+Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The filename stem is the worker's in-team short name.
 
 ```text
 .team/current/
-  TEAM.md                 # the team's goal
-  agents/reviewer.md      # the worker's instructions
+  TEAM.md
+  agents/reviewer.md
 ```
 
-Put the goal in `TEAM.md` and the worker's instructions in each `agents/*.md` body. Use the filename stem as the worker id and in-team short name in commands such as `send` and `inbox`.
+For a **new plan**, record the user's two decisions in every role. This example assumes the user selected Pi and bypass false; it is not a default:
+
+```markdown
+---
+provider: pi
+dangerously_skip_permissions: false
+---
+Review the change and report concrete regression risks.
+```
 
 ```sh
 team-agent quick-start .team/current
 team-agent send reviewer "Review this change"
 team-agent inbox reviewer -n 3
-team-agent add-agent analyst --role-file /absolute/path/to/analyst.md
-team-agent shutdown --workspace .
 ```
 
-The `reviewer` argument is an in-team short name; use `<workspace>::<team>/<agent>` when the recipient needs a fully qualified identity. A successful `send` may mean only queued; it is not the worker's reply. Wait for a natural response or result before treating the task as complete.
+Traditional file-based quick-start/compile behavior remains supported, including legacy minimal role documents; no conversion to CLI-created roles is required. Legacy interpretation is not permission to silently choose settings for a new user plan. Model and effort may remain unset; preserve the existing file compiler's native/default interpretation rather than inventing a model or effort.
 
-## Role defaults
+To add a **new** seat to an existing team, provider and bypass must be explicitly defined in the CLI or role file. A complete traditional role file needs no repeated flags. If both sources define a field, equal values are accepted and **conflicting values are rejected before any write or startup**:
 
-All role metadata is optional. With no overrides:
+```sh
+# These values must be the user's choices, not inferred defaults.
+team-agent add-agent analyst --provider pi --bypass true --prompt "Analyze the proposed change"
+# auditor.md already contains the user's provider and bypass decisions.
+team-agent add-agent auditor --role-file /absolute/path/to/auditor.md
+```
 
-| Setting | Default |
-|---|---|
-| Provider | `pi` |
-| Model | unset; let the provider choose |
-| Effort | unset; let the provider choose |
-| Permission bypass | `false`; keep provider-native permissions |
+Add creates and immediately starts the seat. Ordinary add rejects an occupied ID, including stopped seats. Disaster recovery has one explicit exception: `add-agent ID --role-file FILE --force` may reuse the existing force-recreate lifecycle only when the registered old pane is positively confirmed dead and no live target cohort exists. A live seat or unknown/missing death proof is refused; force is not a routine configuration-update shortcut. External role files are imported into the team's `agents/ID.md` and left untouched. A file already at that path is used in place, without copying itself.
+
+## Change and start an existing worker
+
+**Stop first if it is running.** Start never implicitly kills or restarts a running worker:
+
+```sh
+team-agent stop-agent reviewer
+team-agent start-agent reviewer --effort high --bypass true
+team-agent stop-agent reviewer
+team-agent start-agent reviewer --prompt "Review only regression risks; do not change product code"
+```
+
+Start updates the same role file and recompiles it before normal startup. Omitted options preserve the file's values and body; `--prompt` replaces the permanent role body, not a one-time task message. `--bypass true` and `--bypass false` are explicit values, not bare switches. Model, effort and an existing profile can also be set. Direct file edits followed by start use the same reload path.
 
-Add frontmatter only when a role needs an override. Supported fields include `agent_id` (legacy alias: `name`), `role`, `provider`, `model`, `effort`, `auth_mode`, `profile`, `dangerously_skip_permissions`, and `communication_mode`. Old `tools`, `permission_mode`, and `label` role keys do not configure a worker.
+A different `--provider`, including a manually edited role provider, is rejected before launch. A matching provider is allowed. Create a separate ID to use a different engine. If startup fails, the role file and runtime spec are restored to their pre-command contents; the command reports failure, not an applied update.
 
-Profiles keep provider authentication, endpoint, and custom-model settings local. Never put secrets in `TEAM.md` or a role file. See [the operator reference](references/team-agent-operator.md) for profile setup and field details.
+Profiles keep provider authentication, endpoints and custom-model settings local. Imported roles use this team's/workspace's `profiles`, never the original external directory. Prepare a named profile locally through the public profile commands; do not search for or copy external credentials. Never put secrets in `TEAM.md` or a role file. See [the operator reference](references/team-agent-operator.md) for existing profile and field details. Supported metadata also includes `agent_id` (legacy `name`), `role`, `auth_mode`, and `communication_mode`; old `tools`, `permission_mode`, and `label` keys do not configure a worker.
 
-## Inspect
+## Inspect and stop
 
-Use `team-agent status --json` for readiness and `team-agent --help` for current command syntax. `ok: true` with `ready: false` means the command succeeded but the team is not ready; follow the reported action.
+Use `team-agent status --json` for readiness and the installed command's `--help` for syntax. `ok: true` with `ready: false` means the team is not ready; follow the reported action. Accepted/queued send is not the worker's reply: wait for a natural response or result. Use `<workspace>::<team>/<agent>` when a fully qualified recipient is needed.
 
-Worker MCP provides `send_message`, `report_result`, and `get_team_status`. Lifecycle actions remain on the authorized CLI. See [nested teams](references/team-in-team.md) only when the task needs them.
+Worker MCP provides `send_message`, `report_result`, and `get_team_status`. Lifecycle actions remain on the authorized CLI. See [nested teams](references/team-in-team.md) only when needed. Stop the selected team with `team-agent shutdown --workspace .` when authorized.
 
 ---
 This skill is a concise public guide. Do not infer a tested version from package metadata; verify the installed CLI with `team-agent --version` when version-specific behavior matters.

package/skills/team-agent/references/team-agent-operator.md

@@ -20,15 +20,16 @@ From a tmux-addressable terminal or supported agent pane, run commands in the wo
 team-agent quick-start my-team
 team-agent send reviewer "Review the current change and report the main risk."
 team-agent inbox reviewer -n 3
+# The role file already records the user's provider and bypass choices.
 team-agent add-agent analyst --role-file /absolute/path/to/analyst.md
 team-agent shutdown --workspace .
 ```
 
 A successful `send` can mean only accepted or queued. Wait for the worker's actual reply/result; acceptance is not completion. Use `team-agent status --json` to inspect readiness. `ok: true` with `ready: false` means the command succeeded but the team is not ready; follow the reported action.
 
-## Defaults and optional role fields
+## User decisions and legacy compatibility
 
-No role frontmatter is required. With no explicit overrides, Team Agent uses:
+For a new team plan, explicitly record each user's provider and bypass decisions; do not silently select either. Existing file-based compilation remains compatible, including minimal documents. The following table describes legacy interpretation, not defaults to choose on the user's behalf:
 
 | Setting | Default behavior |
 |---|---|
@@ -37,21 +38,27 @@ No role frontmatter is required. With no explicit overrides, Team Agent uses:
 | `effort` | Unset by Team Agent; leave effort selection to the provider |
 | `dangerously_skip_permissions` | `false`; preserve native permissions |
 
-Do not write `model: null`, `effort: max`, or a bypass setting just to restate a default. The absence of a model or effort override is not a promise about what the provider's own UI eventually displays. Team Agent does not fill role model from TEAM-level defaults. An unspecified role effort defaults to None (native); for non-Pi roles, a legacy explicit TEAM provider_effort remains supported for compatibility.
+Do not invent `model: null` or `effort: max`. Record the user's bypass decision explicitly in a new role, even when it is false. The absence of a model or effort override is not a promise about what the provider's own UI eventually displays. Team Agent does not fill role model from TEAM-level defaults. An unspecified role effort defaults to None (native); for non-Pi roles, a legacy explicit TEAM provider_effort remains supported for compatibility.
 
 Optional supported role metadata:
 
 - `agent_id` (or legacy `name`) and `role` for identity.
 - `provider`, `model`, and `effort` to explicitly choose supported provider settings.
 - `auth_mode` and `profile` to use a provider profile.
-- `dangerously_skip_permissions: true` only when the user explicitly wants the provider-supported bypass behavior. The default is false.
+- `dangerously_skip_permissions: true` or `false` records the user's explicit permission choice. False preserves native permissions; it is not a read-only or sandbox guarantee.
 - `communication_mode` to select a supported worker communication contract.
 
 Unknown and historical role keys are ignored, not used as a way to restrict tools or permissions. In particular, `tools`, `permission_mode`, and `label` do not configure a worker through role frontmatter.
 
+## Add and start
+
+`add-agent ID --provider NAME --bypass true|false` creates and starts a new seat without a prepared file. A traditional `add-agent ID --role-file FILE` needs no repeated flags when the file already defines provider and boolean bypass. Missing decisions may be supplied by CLI; equal file/CLI values are accepted, but conflicting definitions (including model, effort, prompt and profile) are rejected before writing or startup. Model, effort, prompt and profile remain optional. External role-file inputs are imported into the selected team's `agents/ID.md`; the original stays untouched. A file already there is used in place. Ordinary add rejects occupied IDs. Explicit `--force` is restricted to disaster recovery: the registered old pane must be positively confirmed dead and the target must have no live cohort. Live or unknown targets remain refused; the existing force-recreate transaction is reused, not a general update/implicit-restart path.
+
+`start-agent ID` starts an existing stopped seat; it refuses a running seat, so use `stop-agent ID` first. Optional model, effort, bypass, prompt and profile update that same role document. Omitted fields and body are preserved; prompt replaces the body. A matching provider is allowed; any engine change, including manual file edits, is refused. Startup failure restores role and runtime spec bytes, and reports failure. File edits followed by start use the same compiler reload path.
+
 ## Profiles and custom models
 
-A profile keeps provider credentials, endpoint settings, and optional model settings outside role text. This supports subscription profiles and custom/third-party API models, including Claude Code-compatible providers.
+A profile keeps provider credentials, endpoint settings, and optional model settings outside role text. This supports subscription profiles and custom/third-party API models, including Claude Code-compatible providers. Once an external role is imported, profile lookup uses the current team's/workspace's `profiles`, not the external source directory. Prepare the profile locally through public commands; do not discover or copy external credentials.
 
 Create a local profile, then edit its generated file on the user's machine:
 
@@ -64,6 +71,7 @@ Reference it without copying secrets into Markdown:
 ```yaml
 ---
 provider: claude_code
+dangerously_skip_permissions: false
 auth_mode: compatible_api
 profile: my-api
 ---
@@ -76,4 +84,4 @@ The profile can supply its model when the role has no explicit `model`; an expli
 
 Use `team-agent --help` or a command's `--help` for the installed CLI syntax. Worker MCP exposes `send_message`, `report_result`, and `get_team_status`; workers use `report_result` to return completion. Nested-team guidance is in [team-in-team.md](team-in-team.md).
 
-Keep role instructions in Markdown. Add metadata only for an intentional override; do not copy internal state fields or old frontmatter templates into new roles.
+Keep role instructions in Markdown. Record explicit provider/bypass decisions for new plans, and add other metadata only for intentional settings; do not copy internal state fields into roles.