@agentworkforce/cli 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -9,11 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `agentworkforce agent` now records launch metadata for direct harness
+  launches; opt out with `--no-launch-metadata` or
+  `AGENTWORKFORCE_LAUNCH_METADATA=0`.
 - `agentworkforce create` now opens `persona-maker@best`, supports `--to` and
   `--save-default`, and passes `TARGET_DIR` / `CREATE_MODE` persona inputs.
 - Persona source config supports `defaultCreateTarget` for the implicit create target.
 - `--version`/`-v` now prints the CLI package version.
 
+## [0.11.0] - 2026-05-08
+
+### Released
+
+- v0.11.0
+
+## [0.10.0] - 2026-05-08
+
+### Released
+
+- v0.10.0
+
 ## [0.8.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -6,8 +6,8 @@ built-in one from `/personas/`, or an installed/local one that extends a lower
 source.
 
 ```
-agentworkforce create [--to <target>] [--save-default]
-agentworkforce agent <persona>[@<tier>]
+agentworkforce create [--to <target>] [--save-default] [--install-in-repo] [--no-launch-metadata]
+agentworkforce agent [--install-in-repo] [--no-launch-metadata] <persona>[@<tier>]
 agentworkforce list [flags]
 agentworkforce show <persona>[@<tier>]
 agentworkforce install [flags] <pkg|path>
@@ -68,7 +68,7 @@ Unknown persona prints the full catalog with each entry's origin.
 ## Create
 
 ```
-agentworkforce create [--to <target>] [--save-default] [--install-in-repo]
+agentworkforce create [--to <target>] [--save-default] [--install-in-repo] [--no-launch-metadata]
 ```
 
 `create` is the persona-authoring entry point. It runs `persona-maker@best`
@@ -515,6 +515,10 @@ library has no `extends`.
   },
   "env": { … },                // union, local wins per key
   "mcpServers": { … },         // union by server name, local wins per key
+  "mount": {                   // Relayfile file scope; pattern arrays append
+    "ignoredPatterns": ["…"],
+    "readonlyPatterns": ["…"]
+  },
   "permissions": {             // allow/deny union (dedup), mode replaces
     "allow": ["…"], "deny": ["…"], "mode": "default"
   },
@@ -617,6 +621,9 @@ Use this when you are not extending an existing persona:
     "deny": ["Bash(npm publish *)"],
     "mode": "default"
   },
+  "mount": {
+    "readonlyPatterns": ["*"]
+  },
   "tiers": {
     "best": {
       "harness": "codex",
@@ -729,12 +736,39 @@ either a literal string or an env reference. Two forms:
 Secrets therefore stay in your shell/keychain, not in files on disk — local
 persona JSON remains commit-safe as long as you only use references.
 
+## Relayfile mount rules
+
+Interactive `claude` and `opencode` sessions run inside a Relayfile mount by
+default. File visibility and writability are controlled by the persona's
+`mount` block plus project-level dotfiles:
+
+```jsonc
+{
+  "mount": {
+    "ignoredPatterns": ["secrets/**", ".env*"],
+    "readonlyPatterns": [
+      "*",
+      "!docs/",
+      "!docs/**"
+    ]
+  }
+}
+```
+
+- `ignoredPatterns` are omitted from the mount entirely.
+- `readonlyPatterns` are copied into the mount but edits do not sync back.
+- Patterns use gitignore semantics, so later `!` negations can reopen paths.
+- Persona patterns append to inherited persona patterns. At launch, the CLI
+  also merges project-root `.agentignore`, `.agentreadonly`,
+  `.<personaId>.agentignore`, and `.<personaId>.agentreadonly`.
+
 ## Permissions
 
 A persona can declare which tool calls the harness should auto-approve, block,
 or gate via a permission mode. Skip the approval prompts for trusted tools
 (e.g. a persona's own MCP server); keep them on for anything you want to
-eyeball.
+eyeball. File visibility and writability are not defined here; use Relayfile
+mount rules (`.agentignore` / `.agentreadonly`) for that.
 
 ```jsonc
 {
@@ -747,9 +781,8 @@ eyeball.
 ```
 
 - **Tool patterns** are passed through verbatim; use the harness's native
-  grammar. For Claude Code: `Bash(<pattern>)`, `Edit(<glob>)`,
-  `mcp__<server>` (all tools from that server), `mcp__<server>__<tool>`
-  (specific tool).
+  grammar. For Claude Code: `Bash(<pattern>)`, `mcp__<server>` (all tools
+  from that server), `mcp__<server>__<tool>` (specific tool).
 - **Harness support today:** only `claude` is wired (flags: `--allowedTools`,
   `--disallowedTools`, `--permission-mode`). codex and opencode emit a
   warning and fall back to their defaults when `permissions` is set.
@@ -827,7 +860,7 @@ persona session, add it to the persona's `mcpServers` block.
 ## Interactive
 
 ```sh
-agentworkforce agent [--install-in-repo] <persona>[@<tier>]
+agentworkforce agent [--install-in-repo] [--no-launch-metadata] <persona>[@<tier>]
 ```
 
 By default, claude and opencode sessions run inside a sandbox mount — see
@@ -854,10 +887,34 @@ By default, claude and opencode sessions run inside a sandbox mount — see
      initial argument.
 5. Runs the skill cleanup command on exit, regardless of exit status. In
    stage-dir mode this is a single `rm -rf <stage-dir>`.
-6. Propagates the harness's exit code.
+6. Records launch metadata for the session and refreshes harness session logs
+   while the child runs, then once more after exit. The harness is still
+   launched directly.
+7. Propagates the harness's exit code.
 
 Signals (SIGINT, SIGTERM) are forwarded to the child.
 
+### Launch Metadata
+
+Persona launches record metadata by default when the installed backend supports
+launcher metadata. AgentWorkforce records:
+`agentworkforce=1`, `persona=<id>`, `personaTier=<tier>`,
+`personaVersion=<sha256>`, and `personaSource=<cwd|user|dir:n|library>`.
+`personaVersion` is the SHA-256 of the fully resolved persona spec after
+cascade/extends merge and before prompt input substitution.
+
+Opt out for one launch:
+
+```sh
+agentworkforce agent --no-launch-metadata code-reviewer@best
+```
+
+Opt out through the environment:
+
+```sh
+AGENTWORKFORCE_LAUNCH_METADATA=0 agentworkforce agent code-reviewer@best
+```
+
 ## Skill staging
 
 By default, interactive `claude` sessions stage skills under the user's home
@@ -922,13 +979,23 @@ stage dir conflicts with something else (network filesystem, read-only
 
 By default, claude and opencode interactive sessions run inside a
 [`@relayfile/local-mount`](https://www.npmjs.com/package/@relayfile/local-mount)
-symlink mount that hides repo-level harness configuration from the session
-and routes skill-install writes into the sandbox — so the model sees
-persona context + user-level context, and nothing the repo itself declares.
-Codex sessions never mount (no harness-side support).
+mount that hides repo-level harness configuration from the session, applies
+the persona `mount` block plus Relayfile `.agentignore` / `.agentreadonly`
+rules, and routes skill-install writes into the sandbox — so the model sees
+persona context + user-level context, and only the project files the mount
+exposes. Codex sessions never mount (no harness-side support).
 
 `--install-in-repo` opts out and runs against the real cwd.
 
+The CLI reads these files from the project root before creating the mount:
+
+| File | Effect |
+| --- | --- |
+| `.agentignore` | Hide matching files for every persona. |
+| `.agentreadonly` | Copy matching files into the mount as read-only and skip syncing their edits back. |
+| `.<personaId>.agentignore` | Hide matching files only for that persona. |
+| `.<personaId>.agentreadonly` | Make matching files read-only only for that persona. |
+
 **What's hidden (gitignore semantics, at any depth):**
 
 For claude:

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { type Harness } from '@agentworkforce/workload-router';
+import { type Harness, type PersonaMount, type PersonaSelection, type SidecarMdMode } from '@agentworkforce/workload-router';
 export declare const CLI_VERSION: string;
 export declare const CREATE_SELECTOR = "persona-maker@best";
 /**
@@ -40,7 +40,7 @@ export declare function assertSafeRelativePath(relPath: string): void;
  * Applied by `@relayfile/local-mount` with gitignore semantics, so bare names
  * match at any depth in the project tree (e.g. `.claude` hides both
  * `./.claude/` and `./packages/foo/.claude/`). */
-export declare const CLEAN_IGNORED_PATTERNS: readonly ["CLAUDE.md", "CLAUDE.local.md", ".claude", ".mcp.json"];
+export declare const CLEAN_IGNORED_PATTERNS: readonly ["CLAUDE.md", "CLAUDE.local.md", ".claude", ".mcp.json", "AGENTS.md"];
 /**
  * Skill-install artifacts that should never be copied into the mount nor
  * synced back to the real repo. Applied to non-claude interactive sessions
@@ -51,7 +51,18 @@ export declare const CLEAN_IGNORED_PATTERNS: readonly ["CLAUDE.md", "CLAUDE.loca
  * Claude sessions use `installRoot` for out-of-repo staging instead, so
  * these patterns don't apply there.
  */
-export declare const SKILL_INSTALL_IGNORED_PATTERNS: readonly [".agents", ".claude/skills", ".factory/skills", ".kiro/skills", "skills", ".opencode", ".skills", "prpm.lock", "skills-lock.json"];
+export declare const SKILL_INSTALL_IGNORED_PATTERNS: readonly [".agents", ".claude/skills", ".factory/skills", ".kiro/skills", "skills", ".opencode", ".skills", "prpm.lock", "skills-lock.json", "AGENTS.md"];
+export interface RelayfileMountPatterns {
+    ignoredPatterns: string[];
+    readonlyPatterns: string[];
+}
+export declare function buildRelayfileMountPatterns(input: {
+    projectDir: string;
+    personaId: string;
+    harness: Harness;
+    mount?: PersonaMount;
+    configFilePaths?: readonly string[];
+}): RelayfileMountPatterns;
 /**
  * Build the block appended to `<mount>/.git/info/exclude` so untracked-and-
  * hidden files (e.g. `.claude/skills/` materialized by skill installs, or
@@ -78,6 +89,37 @@ export declare function buildMountGitExcludeBlock(patterns: readonly string[]):
  * writes here are sandboxed and never leak to the user's main checkout.
  */
 export declare function configureGitForMount(mountDir: string, patterns: readonly string[]): void;
+/**
+ * Persona-supplied sidecar markdown materialized into a sandbox mount.
+ * Pure data carrier — `runInteractive` translates it into the on-disk
+ * write inside `onBeforeLaunch` (mount path) and warns/skips when the
+ * harness has no mount (codex / `--install-in-repo`).
+ */
+export interface ResolvedSidecar {
+    /** Filename inside the mount: `CLAUDE.md` (claude) or `AGENTS.md` (opencode). */
+    mountFile: 'CLAUDE.md' | 'AGENTS.md';
+    /** Persona-author content. Already inlined for built-ins; read from disk for local. */
+    personaContent: string;
+    mode: SidecarMdMode;
+}
+/**
+ * Resolve the sidecar for a given selection + harness, returning the
+ * persona-author content the runtime should materialize into the mount.
+ * Returns `{}` when no sidecar applies (no path/content set, or harness
+ * doesn't support sidecar files at all). Read errors surface as a warning
+ * string so the caller can drop the sidecar gracefully rather than
+ * failing the whole session.
+ */
+export declare function loadSidecarForSelection(selection: PersonaSelection): {
+    sidecar?: ResolvedSidecar;
+    warning?: string;
+};
+/**
+ * Compute the bytes to write into the mount for a sidecar. In `extend`
+ * mode, prepends the user's real-cwd file (if any) joined to the persona
+ * content with `\n\n---\n\n`. Pure — exposed for unit tests.
+ */
+export declare function buildSidecarBody(sidecar: ResolvedSidecar, realCwdDir: string): string;
 /**
  * Decide whether to run the interactive session inside a
  * `@relayfile/local-mount` sandbox.
@@ -101,6 +143,7 @@ export declare function parseInstallArgs(args: readonly string[]): PersonaInstal
 export declare function main(): Promise<void>;
 export interface AgentFlags {
     installInRepo: boolean;
+    noLaunchMetadata: boolean;
 }
 export interface CreateFlags extends AgentFlags {
     to?: string;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAOL,KAAK,OAAO,EAMb,MAAM,iCAAiC,CAAC;AA8IzC,eAAO,MAAM,WAAW,QAAuB,CAAC;AAChD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAgDpD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AA6ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,mEAKzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,8IAajC,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAwmBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CA+B5E;AAolBD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6D1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAwBA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CA4DA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAQL,KAAK,OAAO,EAEZ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAIrB,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAwJzC,eAAO,MAAM,WAAW,QAAuB,CAAC;AAChD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAmDpD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AAyJD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,gFAUzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,2JAiBjC,CAAC;AAEX,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,GAAG,sBAAsB,CAqBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,SAAS,EAAE,WAAW,GAAG,WAAW,CAAC;IACrC,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,gBAAgB,GAC1B;IAAE,OAAO,CAAC,EAAE,eAAe,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqDjD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,MAAM,GACjB,MAAM,CAkBR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAipBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CA+B5E;AAqmBD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6D1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CA4BA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CAgEA"}