@harnessforce/claude-code-plugin 0.2.0 → 0.3.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harnessforce",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Harnessforce plugin for Claude Code",
   "author": {
     "name": "Lambda Script"

package/README.md

@@ -11,6 +11,7 @@ and does not bundle the CLI (`/harnessforce:setup` installs `@harnessforce/cli`
 | Part | Purpose |
 | --- | --- |
 | `SessionStart` and `UserPromptSubmit` hooks | Register each session and its config snapshot with Harnessforce |
+| `CwdChanged`, `Stop` and `PostToolUse` (`Write` and `Edit`) hooks | Record the repository and branch of the Git working trees a session works in, and send them at the end of a turn in which they changed |
 | `PostToolUse`, `PostToolUseFailure`, `UserPromptExpansion`, `PermissionRequest`, `PostCompact` and `SessionEnd` hooks | Count the configured skills, commands, subagents and MCP servers a session uses, and send the session usage summary |
 | MCP server `harnessforce` (`<connection URL>/mcp`, HTTP) | Tools to start a run, read an Issue, and complete a run |
 | Skill `using-harnessforce` | What Harnessforce records and does not collect, which hook sends what, and when to use the other skills. The `SessionStart` hook injects its body into the context of every session (the build embeds the same text into the hook and the CLI) |
@@ -72,8 +73,8 @@ running. `harnessforce init` turns on automatic updates for the `harnessforce-ag
 The `harnessforce` plugin registers each Claude Code session with Harnessforce so that runs can be
 linked to issues. On `SessionStart` (`startup`, `clear`, `fork`) it sends the session ID and the git
 repository, branch and commit of `cwd` to `POST <HARNESSFORCE_ENDPOINT>/v1/sessions`. On the first
-prompt it sends the same registration again with the prompt ID. Prompts, responses and file
-contents are never sent.
+prompt it sends the same registration again with the prompt ID. The hook never sends prompts,
+responses or file contents; they are sent only through the OTel settings you choose.
 
 - For an organization, set `HARNESSFORCE_ENDPOINT` (the ingest base URL, `https:`) and
   `HARNESSFORCE_INGEST_KEY` (a Workspace ingest key) in
@@ -94,6 +95,22 @@ contents are never sent.
   "The organization's ingest key has been revoked. Contact a Workspace administrator" (Workspace key) or
   "Your ingest key has been revoked. Run `harnessforce init`" (user key)
 
+## Work location hooks
+
+A session often starts in the repository's main checkout and then works in a worktree or on a new
+branch. To link such runs to their pull requests, the plugin records the repository and branch of
+each Git working tree the session works in, at the time it observes it: the new working directory on
+`CwdChanged`, the directory of the file on `PostToolUse` of `Write` and `Edit`, and `cwd` on `Stop`.
+At the end of each turn (`Stop`), when these pairs differ from the pairs sent last, it sends them to
+`POST <HARNESSFORCE_ENDPOINT>/v1/sessions/locations`.
+
+- It sends only the agent, the session ID and up to 10 pairs of repository and branch. Paths,
+  commits, file names and the content of edits are never sent. The record lives in
+  `scratchpad_dir` (`locations-<session_id>.json`); without `scratchpad_dir` nothing is recorded.
+- The hooks run asynchronously and never delay a turn. A failure writes
+  `harnessforce: session location failed (<reason>)` to stderr and is retried at the next turn; after a
+  `401` the session stops sending. `CwdChanged` writes nothing to stderr.
+
 ## Config snapshot
 
 At the same `SessionStart`, the hook also sends a config snapshot to

package/commands/setup.md

@@ -1,11 +1,21 @@
 ---
-description: Harnessforce setup. Walks through checking Node.js, choosing whether to send prompt content, installing the CLI, running harnessforce init, importing past sessions, and confirming the first event after the restart
-disable-model-invocation: true
+description: Harnessforce setup. Walks through checking Node.js, choosing whether to send session content, installing the CLI, running harnessforce init, importing past sessions, showing the remaining workspace steps, and confirming the first event after the restart
 ---
 
 # Harnessforce setup
 
-Go through the steps below in order, interacting with the user. If a command fails, show its output to the user and stop without moving on to the later steps.
+Go through the steps below in order, interacting with the user. Run this setup when the user types `/harnessforce:setup`, or when the user asks to install, connect or set up Harnessforce. Do not run it when the user has not asked for it. Running it again is safe: every step converges to the same state.
+
+## How setup ends
+
+Setup ends only at one of the endings below, and the last line of the ending is the text shown here, as it is. Do not tell the user that setup has ended at any other point, and do not use words that say setup is finished ("complete", "done" and so on) except in the second ending of part 2.
+
+- Node.js is missing or below 18 (step 1): the text in step 1.
+- Stopped part way: "Harnessforce setup stopped at step {n} ({name}). Fix the cause shown above, then run `/harnessforce:setup` again. Steps already done are safe to repeat." Replace `{n}` and `{name}` with the number and the heading of the step that failed.
+- End of part 1 (step 8): "Harnessforce setup, part 1 of 2, is done. Restart Claude Code, then run `/harnessforce:setup` again in the new session. Part 2 checks that the first event arrived."
+- End of part 2 (step 9): "Harnessforce setup is complete."
+
+When a command fails, show its output to the user. Whether setup then stops or goes on is written in each step. Errors that other plugins' hooks show do not affect setup: do not stop because of them and do not mention them.
 
 ## 1. Check Node.js
 
@@ -15,51 +25,73 @@ First run `node --version`. If the command is not found, or the version is below
 
 ## 2. Check whether this run is after the restart
 
-If `harnessforce --version` succeeds and the environment variable `HARNESSFORCE_WORKSPACE_ID` of this session is not empty, this is a session restarted after `harnessforce init`. Skip steps 3 to 7 and go to step 8.
+If `harnessforce --version` succeeds and the environment variable `HARNESSFORCE_WORKSPACE_ID` of this session is not empty, this is a session restarted after `harnessforce init`. Skip steps 3 to 8 and go to step 9.
 
 ## 3. Install the CLI
 
-Run the following, then confirm the install with `harnessforce --version`.
+If `harnessforce --version` succeeds, do not install anything. Otherwise run the following, then confirm the install with `harnessforce --version`.
 
 ```sh
 npm install -g @harnessforce/cli
 ```
 
-## 4. Choose whether to send prompt content
+If the install fails, show its output and stop at this step. When npm cannot write to its global install location (`EACCES`), also show the following before the last line.
 
-Before `harnessforce init`, present the option to send prompt content to the user, not selected by default. The login is not done yet at this point, so neither the Workspace to connect nor its opt-in state is known. Do not change what you show depending on the opt-in.
+> npm cannot write to its global install location. Use a Node.js installed with a version manager such as nvm, or change npm's prefix to your own directory, then try again.
+
+## 4. Choose whether to send content
+
+Before `harnessforce init`, present the option to send the content of the user's sessions, with "send" selected by default. The login is not done yet at this point, so neither the Workspace to connect nor what it stores is known. Do not change what you show depending on the Workspace; `harnessforce init` decides each category from the Workspace it connects, and writes `0` for a category the Workspace does not store.
 
 Present the option together with the following.
 
-- If selected, the body of the prompts the user types to the agent is delivered to this Workspace. Secret patterns, email addresses, and phone numbers are replaced with `[REDACTED:kind]` before storing, and the content is deleted after the content retention period (at most 30 days). Secrets and personal information that do not match a pattern are not masked, and not everything can be detected. Within the Workspace, only the person who sent the stored content can read it; Owners and Admins cannot read it either. That person can delete their own content at any time from My practices.
-- Content is stored only when both this setting on the device and the Workspace opt-in are in place. If the Workspace opt-in is withdrawn, later content is discarded on receipt and existing content data can no longer be read. This setting does not enable sending model responses or tool input and output.
-- If selected, run `harnessforce init --send-content`; if not, run `harnessforce init` (step 5). Write this setting to the `env` of the Claude Code user settings, and do not write it to the `env` of the project (`.claude/settings.json`) or local (`.claude/settings.local.json`) files, because the content variable is ignored in the `env` of those two files.
-- To stop after selecting it, set `OTEL_LOG_USER_PROMPTS` in the `env` of the user settings to `0`. The value that stops it also takes effect in the project and local `env`.
+- If selected, the prompts the user types, model responses, and tool input and output (including Bash commands and file paths) are delivered to this Workspace for the categories the Workspace stores. Secret patterns, email addresses, and phone numbers are replaced with `[REDACTED:kind]` before storing, and the content is deleted after the content retention period (30 days by default, at most 30 days). Secrets and personal information that do not match a pattern are not masked, and not everything can be detected. Who can read the stored content follows the Workspace setting (everyone in the Workspace by default); `harnessforce init` shows the setting of the Workspace it connects. The user can delete their own content from the account settings, and the sender, owners and admins can delete a session's content at any time.
+- Content is stored only when both this setting on the device and the Workspace's storing of that category are in place. If the Workspace stops storing a category, later content is discarded on receipt.
+- If selected, run `harnessforce init --send-content`; if not, run `harnessforce init` (step 5). Write this setting to the `env` of the Claude Code user settings, and do not write it to the `env` of the project (`.claude/settings.json`) or local (`.claude/settings.local.json`) files, because the content variables are ignored in the `env` of those two files. A restart is needed after `harnessforce init` for the setting to take effect.
+- To stop afterwards, run `harnessforce init` again without `--send-content`. It rewrites the content variables to `0`.
 
 Use the following option text as it is.
 
-> You can send the prompts you type for analysis (off by default; it takes effect only if the workspace has opted in to prompts you typed). If enabled, the prompts you type to the agent are delivered to this workspace and stored. Values that match known patterns for secrets and personal information are replaced with `[REDACTED:kind]`, but not everything can be detected. Content is deleted after the content retention period (at most 30 days), and within the workspace only you can read it. You can delete it at any time from My practices. Enable this?
->
-> Content is not sent (by default). You can enable it later.
+> Send the content of your sessions (on by default). The prompts you type, model responses and tool input and output (including Bash commands and file paths) are delivered to this workspace and stored for the categories the workspace stores. Values that match known patterns for secrets and personal information are replaced with `[REDACTED:kind]`, but not everything can be detected. Content is deleted after the content retention period (30 days by default, at most 30 days). Who can read it follows the workspace setting (everyone in the workspace by default); `harnessforce init` shows the setting of the workspace you connect. You can delete your own content from your account settings, and the sender, owners and admins can delete a session's content at any time.
 
 ## 5. Connect to Harnessforce
 
-Follow the choice in step 4: run `harnessforce init --send-content` if selected, or `harnessforce init` if not. Tell the user to log in to Harnessforce in the browser and choose one Workspace to connect. If the browser does not open, show the user the URL that `harnessforce init` prints. The command waits up to 5 minutes for the login to complete, so run it with a Bash timeout of 10 minutes.
+Follow the choice in step 4: run `harnessforce init --send-content` if selected, or `harnessforce init` if not. Tell the user to log in to Harnessforce in the browser, or sign up, and choose one Workspace to connect. A user without a Workspace can create one on the same page and continue. If the browser does not open, show the user the URL that `harnessforce init` prints. The command waits up to 5 minutes for the login to complete, so run it with a Bash timeout of 10 minutes.
 
-For a Workspace that has not opted in, `harnessforce init --send-content` does not write the content setting. It prints a message about that and about the Data retention page of the Workspace settings, and exits with code 0. Do not treat this as a failure; show the printed text to the user as it is.
+For a Workspace that stores no content, `harnessforce init --send-content` writes the content variables as `0`. It prints a message about that and about Collection & retention in the Workspace settings, and exits with code 0. Do not treat this as a failure; show the printed text to the user as it is.
+
+If `harnessforce init` ends with the line saying the CLI version is unsupported and exit code 1, run `npm install -g @harnessforce/cli@latest`, then run this step again. If `harnessforce init` fails for any other reason, show what it printed and stop at this step; a failed `harnessforce init` changes neither the keychain nor the settings files.
 
 ## 6. Import past sessions
 
 Run `harnessforce import` and tell the user, as it is, the imported count it prints, along with the breakdown of sessions that were not imported and the guidance. Do not omit the printed reason and the next action even when the count is 0.
 
-## 7. Ask for a restart
+Then run `harnessforce status --json`. If `repository.connected` is `false` (the repository of the working directory is not connected), tell the user the following.
+
+> This repository is not connected to the GitHub App, so its sessions were not imported. After connecting it, restart Claude Code and run `/harnessforce:setup` to import them.
 
-Tell the user the following and stop.
+If `harnessforce import` fails, show its output and go on; importing is not needed for telemetry and can be run later. Before the last line of the ending, show "Importing past sessions failed. Run `harnessforce import` later." If `harnessforce status --json` fails, show its output and go on.
+
+## 7. Show the remaining steps
+
+From the result of `harnessforce status --json` in step 6, show the steps that are not done (`status` other than `done` in `steps`, and every step in `admin_steps`) in the order of their numbers, each with its title, who does it, and the URL of its page. Use these titles: step 2 "Connect the GitHub App", step 3 "Assign repositories to a project", step 4 "Set up telemetry", step 5 "Wait for your first run". Steps 2 and 3 are done by an owner or admin, and steps 4 and 5 by the user. For a step the user is not responsible for (steps 2 and 3 when the user's `role` is `member`), add "Send this URL to the person responsible."
+
+If `has_seat` is `false`, first show "You don't have a developer seat, so the telemetry you send is not stored." If no step remains, show only "Your workspace is ready." If `harnessforce status --json` failed in step 6, show the URL of the Harnessforce Home (the environment variable `HARNESSFORCE_URL`) instead of the steps.
+
+## 8. Ask for a restart
+
+If the user also uses Codex, tell them first: restart Codex, then run `/hooks` in Codex and trust the harnessforce `SessionStart`, `PostToolUse`, and `Stop` hooks. Codex runs a hook only after the user trusts it, and `harnessforce init` cannot do this for them.
+
+Then end with the following.
 
 > Harnessforce setup, part 1 of 2, is done. Restart Claude Code, then run `/harnessforce:setup` again in the new session. Part 2 checks that the first event arrived.
 
-## 8. Confirm the first event
+## 9. Confirm the first event
+
+At the start of this session, the plugin hook sent the session to Harnessforce. Run `harnessforce import` again to import the sessions of repositories connected to the GitHub App after step 6; sessions already imported are not sent twice. Tell the user the result as in step 6.
+
+Then run `harnessforce status --json`. If step 5 is `done`, show "Your first run arrived." with the URL of the Harnessforce Home (the environment variable `HARNESSFORCE_URL`). If not, show the Home URL and tell the user to check on the waiting screen for the first run that it was received; if nothing arrives after 15 minutes, follow the checks for each cause shown on the waiting screen. Show the steps that are not done in the same way as step 7.
 
-At the start of this session, the plugin hook sent the session to Harnessforce. Tell the user to open the Harnessforce Home in the browser (the URL in the environment variable `HARNESSFORCE_URL`) and confirm on the waiting screen for the first Run that it was received. If nothing arrives after 15 minutes, tell the user to follow the checks for each cause shown on the waiting screen. Finish with the following line.
+If `harnessforce import` fails, show its output, go on, and show "Importing past sessions failed. Run `harnessforce import` later." before the last line. If `harnessforce status --json` fails, show its output and the Home URL, and still end with the line below: the settings were made in step 5, so not being able to read the status is not a failure of setup.
 
 > Harnessforce setup is complete.

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Register Claude Code sessions with Harnessforce and send their usage summaries",
+  "description": "Register Claude Code sessions with Harnessforce and send their usage summaries and work locations",
   "hooks": {
     "SessionStart": [
       {
@@ -60,6 +60,20 @@
             "async": true
           }
         ]
+      },
+      {
+        "matcher": "^(Write|Edit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/scripts/harnessforce-hook.cjs",
+              "work-location"
+            ],
+            "async": true
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [
@@ -122,6 +136,36 @@
           }
         ]
       }
+    ],
+    "CwdChanged": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/scripts/harnessforce-hook.cjs",
+              "cwd-changed"
+            ],
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/scripts/harnessforce-hook.cjs",
+              "stop"
+            ],
+            "async": true
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harnessforce/claude-code-plugin",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Harnessforce plugin for Claude Code",
   "keywords": [
     "harnessforce",

package/scripts/harnessforce-hook-main.cjs

@@ -28,8 +28,7 @@ function isInstant(value) {
 	const nanos = Number(fraction.slice(0, 9) || "0");
 	return secondMs >= MIN_INSTANT_MS && !(secondMs > MAX_INSTANT_MS || secondMs === MAX_INSTANT_MS && nanos > 0);
 }
-//#endregion
-//#region ../../packages/semconv/dist/repository.js
+// ../../packages/semconv/dist/repository.js
 const SCHEME_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
 const SCP_LIKE = /^(?:[^@/\s]+@)?([^:/\s]+):(?!\/)(.+)$/;
 const HOST = /^[a-z0-9.-]+$/;
@@ -63,11 +62,9 @@ function normalizeRepository(remoteUrl) {
 	const [owner, name] = host === "github.com" ? segments.map((segment) => segment.toLowerCase()) : segments;
 	return `${host}/${owner}/${name}`;
 }
-//#endregion
-//#region ../../packages/agent-core/src/object.ts
+// ../../packages/agent-core/src/object.ts
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-//#endregion
-//#region ../../packages/agent-core/src/config/canonical.ts
+// ../../packages/agent-core/src/config/canonical.ts
 const byCodeUnit$1 = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 function canonicalJson(value) {
 	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
@@ -83,8 +80,7 @@ function hashFileContent(content) {
 function sortComponents(components) {
 	return [...components].sort((a, b) => byCodeUnit$1(a.kind, b.kind) || byCodeUnit$1(a.source, b.source) || byCodeUnit$1(a.id, b.id));
 }
-//#endregion
-//#region ../../packages/agent-core/src/config/files.ts
+// ../../packages/agent-core/src/config/files.ts
 const MAX_DEPTH = 8;
 const MAX_FILE_BYTES = 1048576;
 var CollectionExpired = class extends Error {};
@@ -145,8 +141,7 @@ async function listDirectories(dir, guard) {
 	for (const entry of await entries(dir, guard)) if (await kindOf(dir, entry, guard) === "directory") names.push(entry.name);
 	return names;
 }
-//#endregion
-//#region ../../packages/agent-core/src/config/hash-input.ts
+// ../../packages/agent-core/src/config/hash-input.ts
 function withoutSecrets(entry) {
 	const { env, headers, url, args: _args, ...rest } = entry;
 	const result = rest;
@@ -178,8 +173,7 @@ function hashInput(kind, value) {
 	if (kind === "hook" && Array.isArray(value)) return value.map(reduceHookGroup);
 	return value;
 }
-//#endregion
-//#region ../../packages/agent-core/src/config/scope.ts
+// ../../packages/agent-core/src/config/scope.ts
 const MAX_COMPONENTS = 1e3;
 var TooManyComponents = class extends Error {};
 var Sink = class {
@@ -235,8 +229,7 @@ function collectMcpServers(s, servers) {
 	if (!isObject(servers)) return;
 	for (const [name, value] of Object.entries(servers)) if (isObject(value)) s.addValue("mcp_server", name, value);
 }
-//#endregion
-//#region ../../packages/agent-core/src/hook-warning.ts
+// ../../packages/agent-core/src/hook-warning.ts
 const RESTART_FAILED_WARNING = "Could not restart the Harnessforce hook";
 const INVALID_ENDPOINT_WARNING = "The Harnessforce destination is invalid. Run `harnessforce init` again";
 const REGISTRATION_FAILED_WARNING = "Harnessforce session registration failed. Check your network connection";
@@ -250,8 +243,7 @@ const DESTINATION_MISMATCH_WARNING = {
 };
 const TELEMETRY_NOT_CONFIGURED_WARNING = "Claude Code telemetry for Harnessforce is not configured. Run `harnessforce init`";
 const warningOnlyOutput = (message) => `${JSON.stringify({ systemMessage: message })}\n`;
-//#endregion
-//#region ../../packages/agent-core/src/managed.ts
+// ../../packages/agent-core/src/managed.ts
 const MANAGED_DIRS = {
 	darwin: "/Library/Application Support/ClaudeCode",
 	win32: "C:\\Program Files\\ClaudeCode"
@@ -270,8 +262,7 @@ async function readManagedEnv(managedDir, names) {
 	}
 	return values;
 }
-//#endregion
-//#region ../../packages/agent-core/src/plugin-auto-update.ts
+// ../../packages/agent-core/src/plugin-auto-update.ts
 const MARKETPLACE_NAME = "harnessforce-agent";
 const MARKETPLACE_KEYS = ["extraKnownMarketplaces", "additionalMarketplaces"];
 const DISABLING_VARIABLES = [
@@ -314,8 +305,7 @@ async function isPluginAutoUpdateEffective(options) {
 	const entry = marketplacesOf(await readJsonObjectFile(options.userSettingsPath, noGuard$1))?.[MARKETPLACE_NAME];
 	return isObject(entry) && entry.autoUpdate === true;
 }
-//#endregion
-//#region ../../packages/agent-core/src/process/lookup.ts
+// ../../packages/agent-core/src/process/lookup.ts
 const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
 const NPM_SHIM_MAX_BYTES = 65536;
 const SHEBANG_MAX_BYTES = 256;
@@ -496,8 +486,7 @@ async function commandLineFor(file, args, context, { quoteArgs = true } = {}) {
 		verbatim: true
 	};
 }
-//#endregion
-//#region ../../packages/agent-core/src/process/git.ts
+// ../../packages/agent-core/src/process/git.ts
 const GIT_TIMEOUT_MS = 1e3;
 const execGit = (file, args, env, timeoutMs) => new Promise((resolve) => {
 	(0, node_child_process.execFile)(file, args, {
@@ -535,8 +524,7 @@ function createGitRunner({ platform, env, processCwd, excludeTarget, timeoutMs =
 		], gitEnv, timeoutMs);
 	};
 }
-//#endregion
-//#region ../../packages/agent-core/src/process/runtime-env.ts
+// ../../packages/agent-core/src/process/runtime-env.ts
 const RUNTIME_VARIABLES = [
 	"NODE_TLS_REJECT_UNAUTHORIZED",
 	"NODE_EXTRA_CA_CERTS",
@@ -600,8 +588,7 @@ function relaunchWithoutRuntimeVariables({ platform, env, stash, spawnSelf: star
 		}));
 	});
 }
-//#endregion
-//#region ../../packages/agent-core/src/telemetry-settings.ts
+// ../../packages/agent-core/src/telemetry-settings.ts
 const EXPECTED = {
 	CLAUDE_CODE_ENABLE_TELEMETRY: (value) => value === "1",
 	OTEL_LOGS_EXPORTER: (value) => includesOtlp(value),
@@ -621,8 +608,7 @@ async function isTelemetryConfigured(options) {
 		return typeof value === "string" && EXPECTED[name](value);
 	}) && typeof settings?.otelHeadersHelper === "string";
 }
-//#endregion
-//#region ../../packages/agent-core/src/url.ts
+// ../../packages/agent-core/src/url.ts
 const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
 	"localhost",
 	"127.0.0.1",
@@ -643,8 +629,7 @@ function underBase(base, path) {
 	url.pathname = `${base.pathname.replace(/\/+$/, "")}/${path}`;
 	return url;
 }
-//#endregion
-//#region ../../packages/agent-core/src/client-update.ts
+// ../../packages/agent-core/src/client-update.ts
 const CLIENT_UPDATE_HEADER = "harnessforce-client-update";
 const UPDATE_COMMANDS = {
 	cli: "npm install -g @harnessforce/cli@latest",
@@ -803,8 +788,7 @@ async function recheckClientStatus(options) {
 	}
 	return await readUpdateState(options.statePath, options.version) ?? state;
 }
-//#endregion
-//#region ../../packages/agent-core/src/config/plugins.ts
+// ../../packages/agent-core/src/config/plugins.ts
 const NON_MARKETPLACE_ORIGINS = /* @__PURE__ */ new Set([
 	"inline",
 	"skills-dir",
@@ -845,8 +829,7 @@ async function collectPlugins(pluginsRoot, settingsByPrecedence, scope, guard) {
 		collectMcpServers(s, (await readJsonObjectFile((0, node_path.join)(root, ".mcp.json"), guard))?.mcpServers);
 	}
 }
-//#endregion
-//#region ../../packages/agent-core/src/config/collect.ts
+// ../../packages/agent-core/src/config/collect.ts
 const COLLECT_BUDGET_MS = 1e3;
 async function readManagedSettings(managedDir, guard) {
 	let merged = await readJsonObjectFile((0, node_path.join)(managedDir, "managed-settings.json"), guard);
@@ -980,8 +963,7 @@ async function collectConfig(options) {
 		components: sortComponents(sink.components)
 	};
 }
-//#endregion
-//#region ../../packages/agent-core/src/ingest.ts
+// ../../packages/agent-core/src/ingest.ts
 const SEND_TIMEOUT_MS = 2e3;
 const INGEST_KEY_WORKSPACE = /^hf_ik_([A-Za-z0-9-]{1,128})_/;
 const workspaceIdOf = (key) => INGEST_KEY_WORKSPACE.exec(key)?.[1];
@@ -992,6 +974,7 @@ function ingestBaseFrom(endpoint) {
 	ingestBase.pathname = base.pathname.replace(/\/+$/, "");
 	return ingestBase;
 }
+const postItem = (destination, path, item, fetchImpl, timeoutMs = SEND_TIMEOUT_MS) => postItems(destination, path, [item], fetchImpl, timeoutMs);
 async function postItems(destination, path, items, fetchImpl, timeoutMs = SEND_TIMEOUT_MS) {
 	try {
 		const response = await fetchImpl(underBase(destination.ingestBase, path), {
@@ -1017,21 +1000,17 @@ async function postItems(destination, path, items, fetchImpl, timeoutMs = SEND_T
 		};
 	}
 }
-//#endregion
-//#region ../../packages/agent-core/src/issue.ts
+// ../../packages/agent-core/src/issue.ts
 const isIssueIdentifier = (value) => isToken(value, 300);
-//#endregion
-//#region ../../packages/agent-core/src/using-harnessforce.ts
-const usingHarnessforceBody = "---\nname: using-harnessforce\ndescription: Use when starting a session in an environment with the Harnessforce hook, when starting work on an Issue, or when asked what is recorded or collected. The hook injects this text into the context at session start.\n---\n\n# Using Harnessforce\n\nThis session has the Harnessforce hook installed. Harnessforce links the work of people and AI to Issues and records it. Follow these rules.\n\n## What is recorded\n\n- Session registration: agent, session ID, repository, branch, commit, start time, and the first prompt ID.\n- Config snapshot: the structure of the configuration in use (Claude Code only).\n- OTel telemetry: what the user chooses to send.\n- For work on an Issue, `record-run` registers the session as a Run and closes it. It records no Plan, Decision, or Definition of Done.\n\n## What is not collected\n\n- Prompts, responses, tool input and output, and the body of code diffs arrive only when the user opts in with `--send-content` and the Workspace has opted in. They are not collected by default.\n- Never put these contents, secrets, or environment variable values in MCP tool input or in a record.\n\n## Which hook sends what\n\n- SessionStart: session registration and the config snapshot (Codex sends session registration only).\n- UserPromptSubmit: resends on the first prompt (Claude Code only).\n- A failing hook never stops the session. When the hook cannot send, it shows a one-line warning. Tell the user when a warning appears.\n\n## Which skill and tool to use, and when\n\n- For work on a specified Issue ID, or when the environment variable `HARNESSFORCE_ISSUE` is set, follow `record-run` and use `start_run`, `get_issue`, and `complete_run`. An agent that cannot load the skill calls the tools in the same order.\n- Pass the value of the `harnessforce session_id:` line in the context to `start_run`. If there are several, use the last one. If the line is missing, do not guess the session ID, and do not call `start_run` or `complete_run`.\n- Use `propose-improvements` for the analysis of `/harnessforce:tune`.\n- When no Issue is specified, do not start recording a Run.\n\n## Red Flags\n\nStop when one of these thoughts comes up.\n\n| Thought | Reality |\n| --- | --- |\n| An Issue was specified, but the work is small, so recording is unnecessary | Work on a specified Issue is recorded regardless of its size |\n| The session ID line is missing, so I will guess it and call `start_run` | Do not guess. The Run would no longer be linked to the session |\n| Summarizing the content before recording would help | Do not pass content to the tool. It goes beyond what is collected |\n| A warning appeared, but I can ignore it | Sending is not working. Tell the user |\n\n## Priority\n\n1. The user's instructions (CLAUDE.md, AGENTS.md, direct requests). If the user tells you to stop recording, stop recording the Run.\n2. This introduction.\n3. Default behavior.\n\n## Subagents\n\nA subagent that was delegated only a specific task by its parent does not register a Run by following this introduction. The parent registers the Run.\n".replace(/\r\n/g, "\n").replace(/^---\n[\s\S]*?\n---\n+/, "").trimEnd();
-//#endregion
-//#region ../../packages/agent-core/src/session-context.ts
+// ../../packages/agent-core/src/using-harnessforce.ts
+const usingHarnessforceBody = "---\nname: using-harnessforce\ndescription: Use when starting a session in an environment with the Harnessforce hook, when starting work on an Issue, or when asked what is recorded or collected. The hook injects this text into the context at session start.\n---\n\n# Using Harnessforce\n\nThis session has the Harnessforce hook installed. Harnessforce links the work of people and AI to Issues and records it. Follow these rules.\n\n## What is recorded\n\n- Session registration: agent, session ID, repository, branch, commit, start time, and the first prompt ID.\n- Work locations: the repository and branch of each Git working tree the session works in. Paths are not sent.\n- Config snapshot: the structure of the configuration in use (Claude Code only).\n- OTel telemetry: what the user chooses to send.\n- For work on an Issue, `record-run` registers the session as a Run and closes it. It records no Plan, Decision, or Definition of Done.\n\n## What is not collected\n\n- Prompts, responses, tool input and output, and the body of code diffs arrive only when the user sends them (`--send-content` or managed settings) and the Workspace stores that category. The members the Workspace chooses can read them. `harnessforce import` never sends them.\n- Never put these contents, secrets, or environment variable values in MCP tool input or in a record.\n\n## Which hook sends what\n\n- SessionStart: session registration and the config snapshot (Codex sends session registration only).\n- UserPromptSubmit: resends on the first prompt (Claude Code only).\n- Stop: sends the work locations at the end of a turn in which they changed.\n- A failing hook never stops the session. When the hook cannot send, it shows a one-line warning. Tell the user when a warning appears.\n\n## Which skill and tool to use, and when\n\n- For work on a specified Issue ID, or when the environment variable `HARNESSFORCE_ISSUE` is set, follow `record-run` and use `start_run`, `get_issue`, and `complete_run`. An agent that cannot load the skill calls the tools in the same order.\n- Pass the value of the `harnessforce session_id:` line in the context to `start_run`. If there are several, use the last one. If the line is missing, do not guess the session ID, and do not call `start_run` or `complete_run`.\n- Use `propose-improvements` for the analysis of `/harnessforce:tune`.\n- When no Issue is specified, do not start recording a Run on your own. For work that commits changes, follow \"When no Issue is specified\" in `record-run` and ask the user once whether to link it to an existing Issue.\n\n## Red Flags\n\nStop when one of these thoughts comes up.\n\n| Thought | Reality |\n| --- | --- |\n| An Issue was specified, but the work is small, so recording is unnecessary | Work on a specified Issue is recorded regardless of its size |\n| The session ID line is missing, so I will guess it and call `start_run` | Do not guess. The Run would no longer be linked to the session |\n| Summarizing the content before recording would help | Do not pass content to the tool. It goes beyond what is collected |\n| A warning appeared, but I can ignore it | Sending is not working. Tell the user |\n\n## Priority\n\n1. The user's instructions (CLAUDE.md, AGENTS.md, direct requests). If the user tells you to stop recording, stop recording the Run.\n2. This introduction.\n3. Default behavior.\n\n## Subagents\n\nA subagent that was delegated only a specific task by its parent does not register a Run by following this introduction. The parent registers the Run.\n".replace(/\r\n/g, "\n").replace(/^---\n[\s\S]*?\n---\n+/, "").trimEnd();
+// ../../packages/agent-core/src/session-context.ts
 const sessionContextLine = (sessionId) => `harnessforce session_id: ${sessionId}`;
 const sessionContext = (sessionId) => ({ hookSpecificOutput: {
 	hookEventName: "SessionStart",
 	additionalContext: `${sessionContextLine(sessionId)}\n\n${usingHarnessforceBody}`
 } });
-//#endregion
-//#region ../../packages/agent-core/src/vcs.ts
+// ../../packages/agent-core/src/vcs.ts
 async function selectRemote(cwd, git) {
 	if (await git(cwd, ["rev-parse", "--is-inside-work-tree"]) !== "true") return void 0;
 	const remotes = (await git(cwd, ["remote"]))?.split("\n") ?? [];
@@ -1070,8 +1049,120 @@ async function resolveProjectRoot(cwd, git) {
 	const topLevel = await git(cwd, ["rev-parse", "--show-toplevel"]);
 	return topLevel && (0, node_path.isAbsolute)(topLevel) ? topLevel : cwd;
 }
-//#endregion
-//#region src/input.ts
+// ../../packages/agent-core/src/work-location.ts
+const absolute = (value) => typeof value === "string" && (0, node_path.isAbsolute)(value) ? value : void 0;
+const toolInputOf = (fields) => isObject(fields.tool_input) ? fields.tool_input : {};
+const PATCH_FILE_LINE = /^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/;
+function patchedDirectories(command, cwd) {
+	if (typeof command !== "string") return [];
+	return command.split(/\r?\n/).flatMap((line) => {
+		const path = PATCH_FILE_LINE.exec(line)?.[1]?.trim();
+		return path ? [(0, node_path.dirname)((0, node_path.resolve)(cwd, path))] : [];
+	});
+}
+/**
+* eventの入力から、作業位置を求めるdirectoryを返す。読むのは`new_cwd`、`file_path`、patchのfileの行のpathだけで、編集の
+* 本文を読まない。
+*/
+function observedDirectories(agent, event, fields, cwd) {
+	if (event === "stop") return [cwd];
+	if (agent === "claude_code" && event === "cwd-changed") {
+		const newCwd = absolute(fields.new_cwd);
+		return newCwd ? [newCwd] : [];
+	}
+	if (event !== "post-tool-use") return [];
+	const input = toolInputOf(fields);
+	if (agent === "codex") return fields.tool_name === "apply_patch" ? [...new Set(patchedDirectories(input.command, cwd))] : [];
+	if (fields.tool_name !== "Write" && fields.tool_name !== "Edit") return [];
+	const filePath = absolute(input.file_path);
+	return filePath ? [(0, node_path.dirname)(filePath)] : [];
+}
+const isDirectory = (path) => (0, node_fs_promises.stat)(path).then((found) => found.isDirectory(), () => false);
+/** directoryのworking treeの、その時点のrepositoryとbranch。repositoryかbranchを求められなければundefined。 */
+async function observePair(directory, git) {
+	if (!await isDirectory(directory)) return void 0;
+	const vcs = await resolveVcs(directory, git);
+	return vcs?.repository && vcs.branch ? {
+		repository: vcs.repository,
+		branch: vcs.branch
+	} : void 0;
+}
+const emptyLocationState = () => ({
+	pairs: [],
+	sent: [],
+	unauthorized: false
+});
+const pairKey = (pair) => JSON.stringify([pair.repository, pair.branch]);
+/** 組を加える。記録済みの組と、10件に達した後の組は加えない。 */
+function withObservedPair(state, pair) {
+	if (state.pairs.some((saved) => pairKey(saved) === pairKey(pair)) || state.pairs.length >= 10) return state;
+	return {
+		...state,
+		pairs: [...state.pairs, pair]
+	};
+}
+/** 記録した組の集合が、最後に送った集合と異なる場合だけ送る組。 */
+function locationsToSend(state) {
+	if (state.unauthorized || state.pairs.length === 0) return void 0;
+	const sent = new Set(state.sent.map(pairKey));
+	return sent.size === state.pairs.length && state.pairs.every((pair) => sent.has(pairKey(pair))) ? void 0 : state.pairs;
+}
+const isPair = (value) => isObject(value) && typeof value.repository === "string" && typeof value.branch === "string";
+async function readLocationState(path) {
+	try {
+		const saved = JSON.parse(await (0, node_fs_promises.readFile)(path, "utf8"));
+		if (!isObject(saved) || !Array.isArray(saved.pairs) || !Array.isArray(saved.sent)) return emptyLocationState();
+		return {
+			pairs: saved.pairs.filter(isPair),
+			sent: saved.sent.filter(isPair),
+			unauthorized: saved.unauthorized === true
+		};
+	} catch {
+		return emptyLocationState();
+	}
+}
+async function writeLocationState(path, state) {
+	const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+	await (0, node_fs_promises.writeFile)(temporary, JSON.stringify(state), { mode: 384 });
+	await (0, node_fs_promises.rename)(temporary, path);
+}
+const FILE_SAFE_SESSION_ID$1 = /^[A-Za-z0-9_-]+$/;
+/** Claude Codeの記録のfile。`scratchpad_dir`が無ければ記録も送信もしない。 */
+const claudeLocationStatePath = (scratchpadDir, sessionId) => FILE_SAFE_SESSION_ID$1.test(sessionId) ? (0, node_path.join)(scratchpadDir, `locations-${sessionId}.json`) : void 0;
+/** 観測したdirectoryの組を記録のfileへ加える。gitの外のdirectoryは記録しない。 */
+async function recordObservedPairs(statePath, directories, deps) {
+	const pairs = await Promise.all(directories.map((directory) => observePair(directory, deps.git)));
+	const before = await readLocationState(statePath);
+	const after = pairs.reduce((state, pair) => pair ? withObservedPair(state, pair) : state, before);
+	if (after !== before) await writeLocationState(statePath, after);
+	return after;
+}
+/**
+* 記録した組の集合が最後に送った集合と異なれば`/v1/sessions/locations`へ送る。2xxなら送った集合を記録し、401なら以後送らない
+* ことを記録する。それ以外の失敗では記録を変えず、次の`Stop`が送り直しを兼ねる。
+*/
+async function sendLocations(statePath, state, item, destination, fetchImpl) {
+	const locations = locationsToSend(state);
+	if (!locations) return { kind: "unchanged" };
+	const outcome = await postItem(destination, "v1/sessions/locations", {
+		agent: item.agent,
+		session_id: item.sessionId,
+		locations
+	}, fetchImpl);
+	if (outcome.kind === "accepted") await writeLocationState(statePath, {
+		...state,
+		sent: locations
+	});
+	if (outcome.kind === "unauthorized") await writeLocationState(statePath, {
+		...state,
+		unauthorized: true
+	});
+	return {
+		kind: "sent",
+		outcome
+	};
+}
+// src/input.ts
 const FILE_SAFE_SESSION_ID = /^[A-Za-z0-9_-]+$/;
 const isFileSafeSessionId = (sessionId) => FILE_SAFE_SESSION_ID.test(sessionId);
 const token = (value) => typeof value === "string" && isToken(value) ? value : void 0;
@@ -1102,8 +1193,7 @@ function parseHookInput(raw) {
 		fields
 	};
 }
-//#endregion
-//#region src/scratchpad.ts
+// src/scratchpad.ts
 const registrationFile = (pad) => (0, node_path.join)(pad.dir, `registration-${pad.sessionId}.json`);
 const unauthorizedMark = (pad) => (0, node_path.join)(pad.dir, `unauthorized-${pad.sessionId}`);
 const firstPromptSentMark = (pad) => (0, node_path.join)(pad.dir, `first-prompt-sent-${pad.sessionId}`);
@@ -1130,8 +1220,7 @@ async function isFirstPromptSent(pad) {
 async function claimFirstPrompt(pad) {
 	return (0, node_fs_promises.writeFile)(firstPromptSentMark(pad), "", { flag: "wx" }).then(() => true, () => false);
 }
-//#endregion
-//#region src/usage/names.ts
+// src/usage/names.ts
 const PLUGIN_COMPONENT = /^([A-Za-z0-9._-]+)@[A-Za-z0-9._-]+:(.+)$/;
 function pluginPartsOf(identifier) {
 	const parts = identifier.plugin ? PLUGIN_COMPONENT.exec(identifier.id) : null;
@@ -1167,8 +1256,7 @@ const mcpServerOfTool = (toolName, servers) => onlyOne(servers.filter((server) =
 	const prefix = toolPrefixOf(server);
 	return prefix !== void 0 && toolName.startsWith(prefix);
 }));
-//#endregion
-//#region src/usage/count.ts
+// src/usage/count.ts
 const COUNTING_EVENTS = [
 	"post-tool-use",
 	"post-tool-use-failure",
@@ -1218,8 +1306,7 @@ function countedOf(event, fields, identifiers) {
 		} : void 0;
 	}
 }
-//#endregion
-//#region src/usage/store.ts
+// src/usage/store.ts
 function usageStoreOf(sessionId, env) {
 	const data = env.CLAUDE_PLUGIN_DATA;
 	if (!data || !(0, node_path.isAbsolute)(data) || !isFileSafeSessionId(sessionId)) return void 0;
@@ -1338,8 +1425,7 @@ async function removeExpiredFiles(store, now) {
 		if (await (0, node_fs_promises.unlink)(file).then(() => true, () => false)) removed += 1;
 	}
 }
-//#endregion
-//#region src/usage/summary.ts
+// src/usage/summary.ts
 const COLLECTOR_VERSION = "0.1.0";
 const MAX_ITEMS = 200;
 const byCodeUnit = (a, b) => a < b ? -1 : a > b ? 1 : 0;
@@ -1416,8 +1502,7 @@ function buildSummary(sessionId, lines) {
 		}
 	};
 }
-//#endregion
-//#region src/usage/send.ts
+// src/usage/send.ts
 async function sendSessionUsage(store, destination, deadlineMs, deps) {
 	const state = await readState(store);
 	if (!state || state.workspaceId !== workspaceIdOf(destination.key)) return void 0;
@@ -1470,8 +1555,7 @@ async function sendUnsentUsage(store, destination, deps) {
 	if (outcome.kind === "accepted") await Promise.all(batch.map((sent) => writeSentLength(store, sent.sessionId, sent.state, sent.record.length)));
 	return outcome;
 }
-//#endregion
-//#region src/hook.ts
+// src/hook.ts
 const pluginStatePath = (env) => env.CLAUDE_PLUGIN_DATA && (0, node_path.isAbsolute)(env.CLAUDE_PLUGIN_DATA) ? (0, node_path.join)(env.CLAUDE_PLUGIN_DATA, "update-status.json") : void 0;
 const cliStatePath = (homeDir) => (0, node_path.join)(homeDir, ".harnessforce", "update-status.json");
 const CLI_UNSUPPORTED_WARNING = unsupportedLine("cli");
@@ -1750,10 +1834,43 @@ const onCountingEvent = (event) => async (input, deps) => {
 		...counted
 	});
 };
+const locationStatePathOf = (input) => input.scratchpad ? claudeLocationStatePath(input.scratchpad.dir, input.sessionId) : void 0;
+/**
+* correlation.md「sessionの作業位置」: 観測した時点のworking treeのrepositoryとbranchを記録する。`Stop`は加えて、記録した組の
+* 集合が最後に送った集合と異なれば送る。stdoutへ何も書かず、`CwdChanged`ではstderrにも書かない。
+*/
+const onLocationEvent = (event) => async (input, deps) => {
+	const statePath = locationStatePathOf(input);
+	if (!statePath) return;
+	const state = await recordObservedPairs(statePath, observedDirectories("claude_code", event, input.fields, input.cwd), deps);
+	if (event !== "stop" || !input.scratchpad) return;
+	if (await isMarkedUnauthorized(input.scratchpad)) return;
+	if (await isPluginBlocked(deps, false)) return;
+	const { destination } = await resolveDestination(deps, input.cwd);
+	if (!destination) return;
+	const sent = await sendLocations(statePath, state, {
+		agent: "claude_code",
+		sessionId: input.sessionId
+	}, destination, deps.fetch);
+	if (sent.kind !== "sent" || sent.outcome.kind === "accepted") return;
+	if (sent.outcome.kind === "unauthorized") {
+		await markUnauthorized(input.scratchpad).catch(logError(deps));
+		deps.stderr("harnessforce: session location failed (unauthorized)\n");
+		return;
+	}
+	deps.stderr(`harnessforce: session location failed (${sent.outcome.reason})\n`);
+};
+const silently = (handler) => (input, deps) => handler(input, {
+	...deps,
+	stderr: () => {}
+}).catch(() => {});
 const HANDLERS = new Map([
 	["session-start", onSessionStart],
 	["user-prompt-submit", onUserPromptSubmit],
 	["session-end", onSessionEnd],
+	["cwd-changed", silently(onLocationEvent("cwd-changed"))],
+	["work-location", onLocationEvent("post-tool-use")],
+	["stop", onLocationEvent("stop")],
 	...COUNTING_EVENTS.map((event) => [event, onCountingEvent(event)])
 ]);
 async function runHook(event, rawInput, hookDeps) {
@@ -1767,8 +1884,7 @@ async function runHook(event, rawInput, hookDeps) {
 	};
 	await handler(input, deps).catch(logError(deps));
 }
-//#endregion
-//#region src/user-key.ts
+// src/user-key.ts
 const HF_TIMEOUT_MS = 1e3;
 const HF_OUTPUT_LIMIT_BYTES = 65536;
 const BEARER = /^Bearer (\S+)$/;
@@ -1829,8 +1945,7 @@ const execHf = (file, args, options) => new Promise((resolve) => {
 		...error && !error.killed && typeof error.code === "number" ? { exitCode: error.code } : {}
 	}));
 });
-//#endregion
-//#region src/main.ts
+// src/main.ts
 delete process.env.HARNESSFORCE_RUNTIME_ENV;
 async function readStdin() {
 	const chunks = [];
@@ -1880,7 +1995,7 @@ async function main() {
 		}),
 		client: {
 			component: "claude-code-plugin",
-			version: "0.2.0",
+			version: "0.3.1",
 			dev: false
 		},
 		isPluginAutoUpdateEffective: (cwd) => isPluginAutoUpdateEffective({
@@ -1892,4 +2007,3 @@ async function main() {
 	});
 }
 main();
-//#endregion

package/skills/record-run/SKILL.md

@@ -9,13 +9,26 @@ Use the tools of the Harnessforce MCP server to link the work to the Issue. The
 
 ## At the start of the work
 
-1. Pass the value of `harnessforce session_id: <session_id>` in the context as `session_id`, and register the Run with `start_run`. The Harnessforce plugin adds this line to the context at session start. If there are several, use the last one added. The input is the Issue identifier (`issue_identifier`), `agent` (`claude_code`), and `session_id`. If you know the repository, branch, and commit you are working on, pass them too. Keep the returned `run_id` until the end. If the line is missing from the context, follow "When the session ID is missing" below.
+1. Pass the value of `harnessforce session_id: <session_id>` in the context as `session_id`, and register the Run with `start_run`. The Harnessforce plugin adds this line to the context at session start. If there are several, use the last one added. The input is the Issue identifier (`issue_identifier`), `agent` (`claude_code`), and `session_id`. Do not pass the repository, branch, or commit: the hook registers the same session and fills them in. Keep the returned `run_id` until the end. If the line is missing from the context, follow "When the session ID is missing" below.
 2. Check the Issue with `get_issue`.
 
 ## When the session ID changes
 
 - If the value of the last `harnessforce session_id:` in the context differs from the value you passed to the previous `start_run` (for example after forking the conversation or running `/clear`), call `start_run` once more with the new value before continuing, and use the returned `run_id` for later `complete_run` calls.
 
+## When no Issue is specified
+
+Ask the user once whether to link the work to an existing Issue, only when all of the following hold. Do not create an Issue: Issues are GitHub Issues.
+
+- The user has not given an Issue identifier. If the current branch name contains an identifier (a branch name `gh-<number>` is passed as `<owner>/<repo>#<number>` of the repository) and `get_issue` resolves it, treat it as the specified Issue and do not ask. If `get_issue` returns `not_found`, treat it as no identifier.
+- The work commits changes. Do not ask for research, answering questions, or conversations that only plan.
+- The context has a `harnessforce session_id:` line.
+- You have not asked yet for the last `harnessforce session_id:` value in the context. If the user declines, do not ask again while the value stays the same. After a fork or `/clear` changes the value, you may ask again.
+
+To show the candidates, pick up to 3 words from the summary of the work that are likely to appear in an Issue title, and call `list_issues` once per word with `q` set to `-status:done,canceled <word>` and `sort` set to `updated`. Merge the results, remove duplicates, and show at most 5 Issues, most recently updated first. If the user picks one, call `start_run` with that Issue. If there is no candidate or the user picks none, continue the work without calling `start_run`.
+
+If `start_run` returns `forbidden` (a view-only token or a view-only Workspace), tell the user the reason as it is, and do not ask again for that session ID.
+
 ## At the end of the work
 
 - Call `complete_run` with the `run_id`.

package/skills/using-harnessforce/SKILL.md

@@ -10,19 +10,21 @@ This session has the Harnessforce hook installed. Harnessforce links the work of
 ## What is recorded
 
 - Session registration: agent, session ID, repository, branch, commit, start time, and the first prompt ID.
+- Work locations: the repository and branch of each Git working tree the session works in. Paths are not sent.
 - Config snapshot: the structure of the configuration in use (Claude Code only).
 - OTel telemetry: what the user chooses to send.
 - For work on an Issue, `record-run` registers the session as a Run and closes it. It records no Plan, Decision, or Definition of Done.
 
 ## What is not collected
 
-- Prompts, responses, tool input and output, and the body of code diffs arrive only when the user opts in with `--send-content` and the Workspace has opted in. They are not collected by default.
+- Prompts, responses, tool input and output, and the body of code diffs arrive only when the user sends them (`--send-content` or managed settings) and the Workspace stores that category. The members the Workspace chooses can read them. `harnessforce import` never sends them.
 - Never put these contents, secrets, or environment variable values in MCP tool input or in a record.
 
 ## Which hook sends what
 
 - SessionStart: session registration and the config snapshot (Codex sends session registration only).
 - UserPromptSubmit: resends on the first prompt (Claude Code only).
+- Stop: sends the work locations at the end of a turn in which they changed.
 - A failing hook never stops the session. When the hook cannot send, it shows a one-line warning. Tell the user when a warning appears.
 
 ## Which skill and tool to use, and when
@@ -30,7 +32,7 @@ This session has the Harnessforce hook installed. Harnessforce links the work of
 - For work on a specified Issue ID, or when the environment variable `HARNESSFORCE_ISSUE` is set, follow `record-run` and use `start_run`, `get_issue`, and `complete_run`. An agent that cannot load the skill calls the tools in the same order.
 - Pass the value of the `harnessforce session_id:` line in the context to `start_run`. If there are several, use the last one. If the line is missing, do not guess the session ID, and do not call `start_run` or `complete_run`.
 - Use `propose-improvements` for the analysis of `/harnessforce:tune`.
-- When no Issue is specified, do not start recording a Run.
+- When no Issue is specified, do not start recording a Run on your own. For work that commits changes, follow "When no Issue is specified" in `record-run` and ask the user once whether to link it to an existing Issue.
 
 ## Red Flags