@harnessforce/claude-code-plugin 0.1.0 → 0.3.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -11,12 +11,17 @@ 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 record plans, decisions and the Definition of Done |
+| 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) |
-| Skill `record-run` | Tells the agent when to call those tools |
-| Command `/harnessforce:setup` | Checks Node.js, installs the `harnessforce` CLI, asks whether to send content, runs `harnessforce init` (`--send-content` when chosen) and `harnessforce import`, offers (unchecked by default) to share your usage limits with `harnessforce usage-limits on --yes`, and confirms the first event after a restart |
+| Skill `record-run` | Tells the agent when to start and complete a run |
+| Command `/harnessforce:setup` | Checks Node.js, installs the `harnessforce` CLI, asks whether to send content, runs `harnessforce init` (`--send-content` when chosen) and `harnessforce import`, and confirms the first event after a restart |
 | Command `/harnessforce:tune` | Tells you that the agent reads parts of your transcripts through your model provider, runs `harnessforce tune --json`, shows the analysis and the before and after of earlier applied proposals, and makes proposals for the targets with enough data |
+| Command `/harnessforce:status` | Runs `harnessforce top --once --json` and summarizes the sessions on this machine. Read-only |
+| Command `/harnessforce:import` | Runs `harnessforce import` and shows the imported count and why sessions were skipped |
+| Command `/harnessforce:run <issue>` | Shows how to start an agent on an Issue with `harnessforce run --issue <issue> -- <agent>` in a terminal, and how `HARNESSFORCE_ISSUE` ties a session to an Issue. Runs nothing |
+| Command `/harnessforce:help` | Lists the CLI commands (`harnessforce --help`) and these commands, and says which ones are not wrapped (`init`, the interactive `top`) |
 | Skill `propose-improvements` | How the agent writes a proposal (evidence, diff or pull request draft, expected effect, how to measure), keeps permissions minimal and loops bounded, and records it with `harnessforce tune record` before showing it |
 
 The hooks and the MCP server exist only in the build output, because their scripts and connection URL
@@ -25,7 +30,8 @@ come from the build. The copy of the plugin in this repository has no hooks and
 
 ## Install
 
-Public distribution starts once the production domain of Harnessforce is decided. After that:
+The marketplace installs the plugin from npm, with no version pinned, so you get the latest
+published version:
 
 ```text
 /plugin marketplace add lambda-script/harnessforce-agent
@@ -33,7 +39,8 @@ Public distribution starts once the production domain of Harnessforce is decided
 /harnessforce:setup
 ```
 
-Until then, install the [local marketplace build](../../docs/runbooks/local-marketplace.md).
+To connect to a staging or local `apps/web` instead, install the
+[local marketplace build](../../docs/runbooks/local-marketplace.md).
 
 ## Requirements
 
@@ -44,20 +51,33 @@ continues without sending anything.
 
 When a hook cannot send, it shows one line in the session instead of staying silent: Node.js older than 18,
 a failed restart of the hook process, sending not set up (`/harnessforce:setup`), an endpoint that is set
-but not allowed, and a session registration that failed with anything other than 401. The line appears
-only at a session start that registers (`startup`, `clear`, `fork`), except for the two startup failures,
-which appear at every session start. A missing key while `HARNESSFORCE_WORKSPACE_ID` is set shows nothing.
+but not allowed, no ingest key in the keychain (for example after a reboot cleared the kernel keyring), a
+destination that differs from the one `harnessforce init` saved, the Claude Code telemetry settings that
+`harnessforce init` wrote missing from the user settings, a keychain that could not be read, and a session
+registration that failed with anything other than 401. The line appears only at a session start that
+registers (`startup`, `clear`, `fork`), except for the two startup failures, which appear at every session
+start. Nothing is shown while sending works, and nothing is checked again later in the session. When
+`harnessforce` is not on `PATH`, the hook shows nothing: Claude Code reports that `otelHeadersHelper` failed.
+
+## Updates
+
+The hooks send `User-Agent: harnessforce-claude-code-plugin/<version>` and keep the update status the
+server returns in `${CLAUDE_PLUGIN_DATA}/update-status.json`. When a session starts they show one line
+for a newer version (once a day, and not while Claude Code updates the plugin automatically), for the
+date a version stops sending after a security fix, or for an unsupported version. An unsupported version
+sends nothing until you run `claude plugin update harnessforce@harnessforce-agent`; the session keeps
+running. `harnessforce init` turns on automatic updates for the `harnessforce-agent` marketplace.
 
 ## Session registration hooks
 
 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:`, or `http:` only
-  for `localhost`, `127.0.0.1` and `[::1]`) and `HARNESSFORCE_INGEST_KEY` (a Workspace ingest key) in
+- For an organization, set `HARNESSFORCE_ENDPOINT` (the ingest base URL, `https:`) and
+  `HARNESSFORCE_INGEST_KEY` (a Workspace ingest key) in
   the `env` of the managed settings file (`managed-settings.json` or `managed-settings.d/*.json` in
   the managed directory). The hook reads the Workspace key and its endpoint only from those files,
   never from the process environment, because a repository's `.claude/settings.json` can set
@@ -72,8 +92,24 @@ contents are never sent.
   configuration, on errors, or after 2 seconds it gives up quietly and writes the reason to stderr
   (Claude Code's debug log). Without Node.js, Claude Code shows a non-blocking `hook error`.
 - If the key is revoked, Claude Code shows once per session:
-  組織の送信キーが失効しています。Workspaceの管理者に連絡してください (Workspace key) or
-  送信キーが失効しています。`harnessforce init`を実行してください (user key)
+  "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
 
@@ -89,7 +125,9 @@ an identifier, plus a SHA-256 hash:
 - The same kinds of component from enabled marketplace plugins in the plugin cache.
 
 File contents, settings values and MCP server configuration (URLs, headers, environment) are never
-sent, only their hashes. Nothing is sent when there are no components, and the snapshot is skipped
+sent, only their hashes. The hashes of hooks and MCP servers leave out the values that can carry
+credentials: `env` and `headers` values, `args`, and the userinfo, query and fragment of URLs, so a
+hash cannot be brute-forced back to a short secret. Nothing is sent when there are no components, and the snapshot is skipped
 when collection takes over 1 second or finds more than 1,000 components. The collector lives in
 `packages/agent-core/src/config`, shared with `harnessforce run` so it can compute the same snapshot ID.
 

package/commands/help.md

@@ -0,0 +1,31 @@
+---
+description: List the harnessforce CLI commands and the /harnessforce:* commands, and say which one to use for what
+disable-model-invocation: true
+---
+
+# Harnessforce help
+
+Show the user this guide. To list the CLI commands with a one-line description each, run:
+
+```sh
+harnessforce --help
+```
+
+If the command is not found, tell the user to run `/harnessforce:setup`. `harnessforce <command> --help` shows what a command does, what it sends and does not send, and its exit codes.
+
+## Commands in a session
+
+| Command | What it does |
+| --- | --- |
+| `/harnessforce:setup` | Installs the CLI, connects to Harnessforce with `harnessforce init`, imports past sessions and confirms the first event. |
+| `/harnessforce:status` | Summarizes the sessions on this machine (read-only). |
+| `/harnessforce:import` | Imports past sessions. |
+| `/harnessforce:tune` | Analyzes your past sessions and proposes improvements. |
+| `/harnessforce:run <issue>` | Shows how to start an agent on an Issue. |
+
+## Not wrapped
+
+- `harnessforce init` opens a browser to log in and takes up to 5 minutes, so it is not wrapped as its own command. `/harnessforce:setup` runs it for you.
+- `harnessforce top` without `--once` is an interactive view that needs a terminal. Run it in a terminal.
+- `harnessforce run` starts an agent as a new process. See `/harnessforce:run`.
+- `harnessforce otel-headers` and `harnessforce hook` are run by the agents, not by you.

package/commands/import.md

@@ -0,0 +1,18 @@
+---
+description: Import your past sessions on this machine into Harnessforce and report how many were imported and why others were skipped
+disable-model-invocation: true
+---
+
+# Import past sessions
+
+`harnessforce import` sends a summary of each past session of the repositories connected to your Workspace, inside the import window. It sends no prompt text, responses, tool inputs or results, or code. It is safe to run again, because sessions that were already sent are skipped.
+
+Run it:
+
+```sh
+harnessforce import
+```
+
+- If the command is not found, tell the user to run `/harnessforce:setup` and stop.
+- If it reports that you are not logged in, tell the user to run `/harnessforce:setup` (it runs `harnessforce init`, which needs a browser) and stop.
+- Show the imported count and the breakdown of skipped sessions with the next action, exactly as printed. Do not leave out the reason when nothing was imported.

package/commands/run.md

@@ -0,0 +1,25 @@
+---
+description: Explain how to start an agent on a Harnessforce Issue with harnessforce run, because a session cannot start its own agent
+argument-hint: "<issue-identifier>"
+disable-model-invocation: true
+---
+
+# Run an agent on an Issue
+
+`harnessforce run` starts an agent for an Issue. It has to start that agent as a new process in a terminal, so this command cannot do it from inside a session. It runs nothing. It only shows the steps.
+
+Take the Issue identifier from `$ARGUMENTS` (for example `ABC-123`). If it is empty, ask the user for it.
+
+## Start the agent in a terminal
+
+Tell the user to run this in a terminal, outside this session. Replace `claude` with the agent to start (for example `codex`).
+
+```text
+harnessforce run --issue <identifier> -- claude
+```
+
+Everything after `--` is passed to the agent unchanged. The agent's exit code becomes the exit code of `harnessforce run`. It needs `harnessforce init` to have been done; if not, run `/harnessforce:setup` first.
+
+## Already in a session?
+
+The plugin's hooks tie a session to an Issue when the environment variable `HARNESSFORCE_ISSUE` is set to the identifier before the agent starts. `harnessforce run` sets it for you. This session was started without it unless the user set it, and an environment variable cannot be added to a running session. To work on the Issue, start a new session as above.

package/commands/setup.md

@@ -1,83 +1,63 @@
 ---
-description: Harnessforceのsetup。Node.jsの確認、本文データを送るかの選択、CLIの導入、harnessforce init、過去のsessionの取り込み、利用枠を共有するかの選択、再起動後の最初のイベントの確認までを対話で進める
+description: Harnessforce setup. Walks through checking Node.js, choosing whether to send session content, installing the CLI, running harnessforce init, importing past sessions, and confirming the first event after the restart
 disable-model-invocation: true
 ---
 
-# Harnessforceのsetup
+# Harnessforce setup
 
-次の手順を順に、利用者と対話しながら進める。commandが失敗したら、その出力を利用者へ示し、以降の手順へ進まずに止まる。
+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.
 
-## 1. Node.jsを確かめる
+## 1. Check Node.js
 
-最初に`node --version`を実行する。commandが見つからない、またはversionが18未満なら、CLIの導入へ進まずに次の文言をそのまま表示して終わる。
+First run `node --version`. If the command is not found, or the version is below 18, do not move on to installing the CLI. Show the following text as it is and stop.
 
-> プラグインのフックにはNode.js 18以上が必要です。Node.jsを導入してからClaude Codeを再起動し、もう一度`/harnessforce:setup`を実行してください
+> Harnessforce hooks require Node.js 18 or later. Install Node.js, restart Claude Code, then run `/harnessforce:setup` again.
 
-## 2. 再起動後の実行かを確かめる
+## 2. Check whether this run is after the restart
 
-`harnessforce --version`が成功し、かつこのsessionの環境変数`HARNESSFORCE_WORKSPACE_ID`が空でなければ、`harnessforce init`の後に再起動したsessionである。手順3から8を行わずに手順9へ進む。
+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.
 
-## 3. CLIを導入する
+## 3. Install the CLI
 
-次を実行し、続けて`harnessforce --version`で導入できたことを確かめる。
+Run the following, then confirm the install with `harnessforce --version`.
 
 ```sh
 npm install -g @harnessforce/cli
 ```
 
-## 4. 本文データを送るかを選ぶ
+## 4. Choose whether to send content
 
-`harnessforce init`の前に、本文データを送る設定の選択肢を、既定では選ばれない状態で利用者に示す。この時点ではログインが済んでおらず、接続するWorkspaceもそのopt-inの状態も分からないため、opt-inの有無で表示を変えない。
+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.
 
-- 選ぶと、agentに入力した指示（prompt）の本文がこのWorkspaceへ届き、secretのパターンとメールアドレス・電話番号を`[REDACTED:種類]`に置き換えたうえで保存され、本文データの保持期間（最大30日）で削除される。パターンに一致しない秘密値と個人情報は伏せ字にならず、すべてを検出できるとは限らない。保存した本文は、Workspaceのメンバーの中では送った本人だけが読め、OwnerとAdminも読めない。本人は「自分のやり方」でいつでも自分の本文を削除できる。
-- 本文が保存されるのは、端末のこの設定とWorkspaceのopt-inの2つがそろう場合だけ。Workspaceのopt-inを解除すると、それ以降の本文は受信時に破棄され、既存の本文データも読めなくなる。この設定はモデルの応答やツールの入出力を送る設定を有効にしない。
-- 選んだ場合は`harnessforce init --send-content`、選ばない場合は`harnessforce init`を実行する（手順5）。この設定はClaude Codeのuser settingsの`env`に書き、project（`.claude/settings.json`）とlocal（`.claude/settings.local.json`）の`env`には書かない。その2つのfileの`env`では本文の変数が無視されるため。
-- 選んだ後で止めるときは、user settingsの`env`の`OTEL_LOG_USER_PROMPTS`を`0`にする。止める値はprojectと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.
 
-> 入力した指示の本文を送って分析に使えます（既定では無効。Workspaceが指示本文をオプトインしている場合だけ有効になります）。有効にすると、エージェントに入力した指示の本文がこのWorkspaceへ届き、保存されます。パターンに一致した秘密値と個人情報は`[REDACTED:種類]`に置き換えますが、すべてを検出できるとは限りません。本文データの保持期間（最大30日）で削除し、Workspaceのメンバーの中では、読めるのは送ったあなただけです。自分のやり方の画面からいつでも削除できます。有効にしますか？
->
-> 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. Harnessforceに接続する
+## 5. Connect to Harnessforce
 
-手順4の選択に従い、選んだ場合は`harnessforce init --send-content`、選ばない場合は`harnessforce init`を実行する。ブラウザでHarnessforceにログインし、接続するWorkspaceを1つ選ぶよう利用者へ伝える。ブラウザが開かなければ、`harnessforce init`が表示するURLを利用者へ示す。ログインの完了を最大5分待つため、Bashのtimeoutを10分にして実行する。
+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.
 
-opt-inしていないWorkspaceでは`harnessforce init --send-content`は本文の設定を書かず、その旨とWorkspaceの設定のデータの保持への案内を表示して終了コード0で終わる。失敗として扱わず、表示された文言をそのまま利用者へ示す。
+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.
 
-## 6. 過去のsessionを取り込む
+## 6. Import past sessions
 
-`harnessforce import`を実行し、送信した件数と読み飛ばした件数を利用者へ伝える。
+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. 利用枠を共有するかを選ぶ
+## 7. Ask for a restart
 
-`harnessforce init`の後に、`harnessforce usage-limits status`を実行する。表示のWorkspaceのopt-inが「有効」でなければ（「無効」「確認できません」を含む）、利用枠の選択肢を示さず手順8へ進む。「有効」なら、利用枠（Claude Codeの5時間と7日の枠の使用率とリセット時刻）をこのWorkspaceのメンバーと共有する選択肢を、既定では選ばれない状態で利用者に示す。選ばれなければ、何も実行せず手順8へ進む。
+Tell the user the following and stop.
 
-選択肢の文言は次をそのまま使う。
+> 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.
 
-> 利用枠を共有できます（既定では共有しません）。共有すると、あなたの名前とともに、あなたの利用枠（5時間・7日などの窓の使用率とリセット時刻だけ）を、このWorkspaceのメンバー全員が見られます。プロンプトなどの本文は送りません。いつでもやめられ、やめると保存済みの値も削除します。メンバーの順位づけには使いません。共有しますか？
->
-> You can share your usage limits (not shared by default). If shared, everyone in this workspace can see your usage limits together with your name (only the usage percentage and reset time of each window, such as 5 hours and 7 days). No prompt or other content is sent. You can stop at any time, and stopping deletes the stored values. They are not used to rank members. Share them?
->
-> 共有しません（既定）。後から`harnessforce usage-limits on`で設定できます
->
-> Not shared (by default). You can set it up later with `harnessforce usage-limits on`.
+## 8. Confirm the first event
 
-共有を選んだ場合だけ、利用者自身が同意の文面に答えるため、`!harnessforce usage-limits on`を利用者に入力してもらう。`--yes`は付けず、agentが同意を代行しない。同意の文面に`y`と答えると、既にstatusLineを使っている場合（claude-hudなど）は、そのcommandを包んで表示と終了コードを変えずに残す。Windowsや、組み込めないstatusLineでは、このcommandは何も変えずに理由を表示して0以外で終わる。その表示を利用者へそのまま示し、他の手順は続ける。やめるときは`harnessforce usage-limits off`を案内する。
+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.
 
-## 8. 再起動を案内する
-
-次を利用者へ伝えて終わる。
-
-> Claude Codeを再起動すると設定が反映されます。再起動したsessionで、もう一度`/harnessforce:setup`を実行してください。最初のイベントが届いたかを確認します。
-
-## 9. 最初のイベントを確認する
-
-このsessionの開始時に、pluginのhookがsessionをHarnessforceへ送っている。利用者に、ブラウザでHarnessforceのHome（環境変数`HARNESSFORCE_URL`のURL）を開き、最初のRunの待機画面で受信を確認するよう伝える。15分待っても届かなければ、待機画面が示す原因ごとの確認手順に沿って確かめるよう伝える。
+> Harnessforce setup is complete.

package/commands/status.md

@@ -0,0 +1,26 @@
+---
+description: Show the running and recent agent sessions on this machine as a short summary, using a read-only snapshot of harnessforce top
+disable-model-invocation: true
+---
+
+# Session status
+
+This command only reads. It changes no file, setting or Workspace data, and sends nothing to Harnessforce.
+
+## 1. Take a snapshot
+
+Run this once. It prints one snapshot as JSON and exits, so it does not open the interactive view.
+
+```sh
+harnessforce top --once --json
+```
+
+If the command is not found, tell the user to run `/harnessforce:setup` and stop. If it fails, show its output as is and stop.
+
+## 2. Summarize
+
+Summarize the snapshot for the user in a few lines: how many sessions are running, which agent and repository each belongs to, and any recent sessions that ended. Report only values that are in the JSON. Do not guess a value that is missing, and do not turn a missing value into 0.
+
+## 3. Point to the live view
+
+The interactive view needs a terminal, so this command does not start it. Tell the user to run `harnessforce top` in a terminal when they want the live view.

package/commands/tune.md

@@ -1,39 +1,39 @@
 ---
-description: 自分の過去のsessionを分析し、分析結果、前回の提案の前後と、人の介入、ループにできる繰り返し、MCP server、使い方の改善の提案を表示する。ファイルは書き換えない
+description: Analyze your past sessions and show the analysis results, the before and after of the previous suggestion, and suggested improvements for human interventions, repeatable loops, MCP servers, and usage. Does not modify files
 argument-hint: "[--all] [--no-send]"
 disable-model-invocation: true
 ---
 
-# 過去のsessionの分析と改善の提案
+# Analyze past sessions and suggest improvements
 
-次の手順を順に進める。この実行では、利用者のファイル、設定、repository、managed settingsを書き換えない。書き込むのは`harnessforce tune`と`harnessforce tune record`が`~/.harnessforce/tune/`へ書くものだけである。
+Go through the steps below in order. This run does not modify the user's files, settings, repository, or managed settings. The only things written are what `harnessforce tune` and `harnessforce tune record` write to `~/.harnessforce/tune/`.
 
-## 1. modelのproviderへ渡ることを伝える
+## 1. Say that content goes to the model provider
 
-何かを実行する前に、次の文言をそのまま表示する。
+Before running anything, show the following text as it is.
 
-> この実行では、提案を作るために、この端末のsessionの記録の一部をagentが読みます。読んだ内容は、ふだんこのagentに使っているmodelのproviderへ、通常のsessionと同じ経路で渡ります。Harnessforceへは渡りません。Harnessforceへ送るのは、公開の規則で数えた分析結果の値だけです。
+> To make suggestions, the agent reads part of the session records on this device in this run. What it reads goes to the provider of the model you normally use with this agent, through the same path as a normal session. It does not go to Harnessforce. Harnessforce receives only the analysis result values counted by the public rules.
 
-## 2. 分析する
+## 2. Analyze
 
-次を実行する。`harnessforce tune --json`を起動し、分析結果と、提案を作る条件を対象ごとに判定した結果を表示する。送信と未送信の分の再送を含むため、Bashのtimeoutを10分にする。
+Run the following. It starts `harnessforce tune --json` and shows the analysis results and, for each target, the result of checking the conditions for making a suggestion. It includes sending and resending unsent results, so set the Bash timeout to 10 minutes.
 
 ```sh
 node "${CLAUDE_PLUGIN_ROOT}/skills/propose-improvements/scripts/summarize.mjs" $ARGUMENTS
 ```
 
-- stderrの行は`harnessforce tune`の文言である。省略も言い換えもせずに、すべてそのまま表示する。
-- stdoutの分析結果（人の介入、ループにできる繰り返し、MCP server、使い方）をそのまま表示する。「未計測」を0と言い換えない。使い方は端末だけの値であり、Harnessforceへ送られない。
-- 「前回の提案の前後」の行があれば、新しい提案の前に「前回の提案の前後」としてそのまま表示し、「前後の差（因果を示しません）」と「起点は適用を検出した時刻です」を省略しない。「比較データなし」を差0と言い換えない。
-- 終了コードが0と3以外なら、提案を作らずに終わる。`harnessforce`が見つからない旨の文言が出た場合も同じである。
-- 「データ不足のため提案を作りません」の行があれば、その行を表示し、提案を作らずに終わる。
+- The lines on stderr are the messages of `harnessforce tune`. Show all of them as they are, without omitting or rephrasing them.
+- Show the analysis results on stdout (human interventions, repeatable loops, MCP servers, usage) as they are. Do not rephrase "not measured" as 0. Usage values stay on this device and are not sent to Harnessforce.
+- If there is a "Before and after the previous suggestion" section, show it as it is before the new suggestions, and do not omit "Before/after difference (does not show causation)" or "The starting point is the time the application was detected". Do not rephrase "No comparison data" as a difference of 0.
+- If the exit code is anything other than 0 or 3, finish without making suggestions. The same applies when the message says `harnessforce` was not found.
+- If there is a "Not enough data, so no suggestions are made" line, show that line and finish without making suggestions.
 
-## 3. 提案を作る
+## 3. Make suggestions
 
-「提案の対象」の行をすべて表示する。「データ不足」と「未計測のため提案しません」の行は、あと何が必要かを含めてそのまま表示し、その対象の提案を作らない。
+Show all the "Targets for suggestions" lines. Show the "Not enough data" and "not measured, so no suggestion is made" lines as they are, including what is still needed, and make no suggestion for those targets.
 
-「提案を作れます」の対象について、このpluginの`propose-improvements`のskillの手順に従って提案を作り、`harnessforce tune record`で記録してから表示する。記録が終了コード0で終わらなかった提案は表示しない。
+For the targets marked "a suggestion can be made", make suggestions by following the `propose-improvements` skill of this plugin, record them with `harnessforce tune record`, and then show them. Do not show a suggestion whose recording did not end with exit code 0.
 
-## 4. 適用の仕方を伝える
+## 4. Explain how to apply
 
-最後に、提案の適用は利用者が行うことを伝える。手で編集する、`git apply`する、自分のsessionでagentに適用を指示する、のいずれかで適用する。このcommandは適用しない。適用した提案は、次の`/harnessforce:tune`の実行で検出され、件数だけがHarnessforceへ送られる。
+Finally, tell the user that applying the suggestions is up to the user. They apply them by editing by hand, running `git apply`, or telling the agent in their own session to apply them. This command does not apply them. A suggestion that was applied is detected in the next run of `/harnessforce:tune`, and only counts are sent to Harnessforce.

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.1.0",
+  "version": "0.3.0",
   "description": "Harnessforce plugin for Claude Code",
   "keywords": [
     "harnessforce",