@hydraharness/harness-tool-bash 0.0.0-stage → 0.1.1-rc.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @hydraharness/harness-tool-bash
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The model-facing `bash` tool registered over the `ctx.shell` executor seam. Foreground execution stays behind that seam; a background process handle is registered with the generic `ctx.jobs` runtime and controlled through `job_output`, `job_list`, and `job_kill` from `@hydraharness/harness-tool-jobs`.
+
+Requires a loaded executor Service Provider (e.g. `@hydraharness/harness-bash-local`) and the [`@hydraharness/harness-shell-env`](../shell-env/README.md) registry; the plugin stays pending until every injected service exists (`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`). The tool contract is bash-dialect — mount a bash-parsing executor.
+
+The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering and background-process adaptation remain package-internal.
+
+The plugin also contributes the `tool:bash` prompt section (order 105): check the `[exit code: N]` marker on every result and investigate failures before moving on.
+
+## Tools
+
+### `bash`
+
+| Arg | Type | Notes |
+|---|---|---|
+| `command` | string (required) | Run via `bash -c`. No state persists between calls — use `workdir`, not `cd`. |
+| `description` | string (required) | One-line, active-voice summary of the command (5-10 words), for UI/log display only — no effect on execution. |
+| `timeoutMs` | number | Timeout override in milliseconds. The executor applies its configured default and cap. |
+| `workdir` | string | Working directory for this call. Defaults to the filesystem identity of the calling agent's session cwd (`session.header.cwd`) so each session runs in its own workspace; a relative `workdir` is resolved against that same identity. |
+| `changed_paths` | string[] | Optional explicit paths changed by a successful foreground command; used only to refresh workspace instructions, never inferred from shell text. |
+| `run_in_background` | boolean | Return a job id immediately; no timeout applies. |
+| `sandbox_permissions` | string enum | ADVERTISED ONLY when the mounted executor sandboxes (`ctx.shell.sandboxMode` reports a confining default): the wider mode a denied command needs, from the closed target vocabulary `workspace-write`/`danger-full-access` (never cut down to the executor's default — the effective mode is per-session; strict widening is checked at execution against it, and a non-widening request fails without prompting anyone). |
+| `justification` | string | Required together with `sandbox_permissions` (each without the other is a validation error): one sentence for the user explaining why this exact command needs the wider access. |
+
+`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.shell.resolve()` before execution, so the Service Definition (`ShellExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`. When sandbox policy is present, the tool reuses its already-canonical `workspaceRoot` as the workdir base so confinement and process launch cannot resolve the same session spelling differently.
+
+### Managed shell environment
+
+Every foreground and background model bash call receives a freshly collected trusted `HYDRA_*` environment through the shared [`@hydraharness/harness-shell-env`](../shell-env/README.md) registry: `HYDRA_HOME` (the absolute Harness home), `HYDRA_SHELL=1`, the agent's `HYDRA_SESSION_ID`, and `HYDRA_SESSION_JSONL` when the active persistence backend locates one. The registry contract — contributor registration, loud duplicate/undeclared-key failure, the built-in reservations, and the contributor example — lives in that package's README. The snapshot passes through the dedicated `ShellExecRequest.hydraEnv` channel; the local executor removes all inherited `HYDRA_*` before merging it, so nested harnesses and concurrent parent/child agents cannot leak stale identities, and `process.env` is never modified. The tool description teaches the generic `$HYDRA_*` convention rather than naming persistence-specific variables or adding a permanent system-prompt section.
+
+Result text contains stdout, an optional `[stderr]` section, then applicable sandbox-denial, timeout, signal, exit-code, and truncation markers. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Truncation links a safe complete spill file or reports it unavailable. Only infrastructure failures such as spawn errors and aborts produce `isError`.
+
+The canonical success is `{ kind: 'foreground', ...ShellRunResult }` for a completed foreground process or `{ kind: 'background', jobId }` for a published task. The Native renderer preserves the text above, including exactly `started background job <id>`; programmatic consumers use the typed fields without parsing those strings. Executor stream caps remain acquisition limits on `ShellRunResult` and carry their spill paths.
+
+A foreground call may declare `changed_paths`. After a successful foreground result, `agent-instructions` resolves those exact strings against the effective workdir and uses them as context-refresh hints; it never infers paths from shell text. Failed, aborted, and background calls do not refresh instructions, and these hints are not mutation records.
+
+When `run_in_background` is true, this plugin preflights `ctx.jobs.start()` before spawning, registers the calling agent as owner, and adapts the returned `ShellProcess` handle into generic cancel/done/incremental-output hooks. The job runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps bash exit/sandbox facts into job output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time.
+
+## UI presentation
+
+The tool owns its `presentCall`/`presentResult` render intent. A foreground call is a terminal card carrying command, description, cwd, output, and parsed exit status. Because the card shows the exit as its own pill, the `[exit code: N]` / `[killed by signal: …]` marker the parse consumes leaves the output; every other marker (truncation, timeout, sandbox) stays in it. A background start is a generic execute card because it returns only a job id; the generic `job_*` tools own their own cards. These presenters are pure and replay-safe.
+
+## The tool builds its request from named args only
+
+`ShellExecRequest` carries optional `stdoutMaxBytes`, `stdin`, ordinary `env`, and managed `hydraEnv`, used by trusted in-process plugins and this tool's environment registry. The model-facing tool exposes none of `stdoutMaxBytes`, `stdin`, or `env`: it builds requests from named command/workdir/timeout/signal/sandbox fields plus the registry-collected `hydraEnv`. Extra model keys are ignored and cannot replace managed values. Shell syntax provides equivalent command-level behavior, while the local executor scrubs ambient credentials and stale `HYDRA_*` values. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md).
+
+## Permissions and escalation
+
+Commands run with the executor's full authority unless a sandboxing executor ([`@hydraharness/harness-bash-sandbox`](../bash-sandbox/)) confines them — the deny-only sandbox reports denials as result facts, rendered here as the denial marker; per-call allow/deny/ask policy is the `tools/pre-execute` waterfall (see docs/architecture.md).
+
+Escalating bash calls resolve `ctx.approval` before execution. `allowed-once` applies the requested mode only to that call; rejection, cancellation, unavailability, or missing approval context executes nothing and returns a distinct error. On a real denial, the model may retry the same command once in the same turn with the narrowest sufficient mode and justification; the approval prompt itself is the consent step. Escalation is never speculative, and a disabled or rejected approval is final. The [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
+
+## Per-session mode switching
+
+For sandboxing executors, each call resolves mode as one-shot escalation, then session override, then executor default. Non-sandboxing and agent-less calls carry no session override. The policy owner contributes the current capability-neutral standing mode; denial results still own the operation-specific effective mode and retry guidance. See the [`@hydraharness/harness-shell` fold](../shell/README.md) and [sandbox switching contract](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+Every request in this plugin's registration scope contains the bash guidance below. The policy owner contributes current sandbox state through its cache-safe runtime context rather than changing this section. Scoped tool restrictions can hide the schemas without removing this independently registered section.
+
+##### Bash guidance
+
+```markdown
+Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+```
+
+#### Token effect
+
+Small fixed input cost per request while the plugin is active, unchanged by sandbox mode or mode switches.
+
+#### KV Cache effect
+
+Prefix-stable while the registration scope and prompt text are unchanged. Plugin activation or disposal may invalidate reuse from this prompt section; sandbox mode switches do not.
+
+### Tool schemas
+
+#### What the model sees
+
+The model sees the generated [`bash` schema](../../../docs/tool-catalog.md#hydraharness-tool-bash). `run_in_background` appears only when this producer enables it; `sandbox_permissions` and `justification` appear only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definition for that agent.
+
+#### Token effect
+
+Fixed schema cost on every request where the tools are visible; sandbox support adds the escalation fields and its conditional description paragraph.
+
+#### KV Cache effect
+
+Prefix-stable while visibility, background support, and executor sandbox capabilities are unchanged. A restriction, config change, or executor change may invalidate reuse from the first changed tool definition.
+
+### Foreground result
+
+#### What the model sees
+
+The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. With no output it emits exactly `(no output)`. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]`, `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]`; the sandbox escalation and runner-failure lines are quoted in [`@hydraharness/harness-bash-sandbox`](../bash-sandbox/README.md).
+
+#### Token effect
+
+Zero result tokens before a call. Output is bounded per stream, while each emitted line remains in history until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Background job context and results
+
+#### What the model sees
+
+Start returns exactly `started background job <jobId>`. This producer supplies incremental process output, optional `[some output was dropped from memory; full output: <paths-or-(unavailable)>]`, sandbox facts, and terminal detail such as `exit code: <exitCode>` or `signal: <signal>` to the generic job runtime. [`@hydraharness/harness-tool-jobs`](../../jobs/tool-jobs/README.md) owns the visible status line, completion notice, listing, and cancellation response.
+
+#### Token effect
+
+The start acknowledgement is small and retained; collected output is data-dependent and bounded by the executor's stream buffers. Consuming reads do not repeat prior output.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Tool errors
+
+#### What the model sees
+
+Validation and policy failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background jobs unavailable: load @hydraharness/harness-jobs and @hydraharness/harness-tool-jobs`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`, the approval-availability/rejection/cancellation variants, and `tool call aborted`.
+
+#### Token effect
+
+Only the failing call adds these retained tokens; a rejected escalation does not add command output because the command does not run.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Replay exit pills parse from result text** — output whose final line happens to be exactly `[exit code: N]` / `[killed by signal: …]` shows a wrong pill on session replay and loses that line from the card body, because the parse treats it as the marker it consumes; a display-only known residual.
+- **The `bash` tool opts out of `timeout-policy` budgets** — it keeps the executor-owned `BASH_TIMEOUT` path, per [the tool-call timeout-policy Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).
+- **Background processes have no executor timeout** — callers must use `job_kill`, or rely on owner/service disposal, when work no longer matters.

package/lib/index.js

@@ -0,0 +1,454 @@
+import z from "@hydraharness/schemastery";
+import { isAbsolute, resolve } from "node:path";
+import { TOOL_ABORTED, defineTool } from "@hydraharness/harness-tools";
+import { HarnessError } from "@hydraharness/harness-llm";
+import { ESCALATION_TARGETS, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@hydraharness/harness-sandbox";
+import { HYDRA_ENV_PREFIX, parseExitStatus } from "@hydraharness/harness-shell";
+//#region lib/types/background.js
+/**
+* Generic-task adaptation for background bash process handles.
+*
+* @module @hydraharness/harness-tool-bash/background
+*/
+/**
+* Map a settled background process onto the generic task-outcome vocabulary:
+* `killed` stays `killed` (detail: the signal when one is known), everything
+* else is `completed` with the exit code as detail. A nonzero command exit is
+* reported, not failed, exactly like the foreground rendering.
+* @param proc - the settled process handle.
+* @returns the outcome for the `ctx.jobs` registration.
+*/
+function processOutcome(proc) {
+	if (proc.status === "killed") return {
+		status: "killed",
+		detail: proc.signal !== null ? `signal: ${proc.signal}` : "killed before exit"
+	};
+	return {
+		status: "completed",
+		detail: `exit code: ${proc.exitCode ?? 0}`
+	};
+}
+//#endregion
+//#region lib/types/render.js
+/**
+* Model-facing result rendering for the bash tool.
+*
+* @module @hydraharness/harness-tool-bash/render
+*/
+/** Append the truncation notice (with the full-output spill path) to a stream's text. */
+function streamText(output) {
+	if (!output.truncated) return output.text;
+	return `${output.text}\n[output truncated; full output: ${output.spillPath ?? "(unavailable)"}]`;
+}
+/**
+* Shape one finished run into the text the model sees: stdout, then a marked
+* stderr section, then exit-status markers. Non-zero exits are reported, not
+* errored — the model decides how to react; only infrastructure failures
+* (spawn errors, aborts) surface as isError results.
+* @param result - the completed foreground run from the executor.
+* @param escalationModes - the escalation targets this composition advertises;
+*   non-empty adds the same-turn escalation hint after a denial marker
+*   (default `[]`: no hint).
+* @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+*/
+function renderResult(result, escalationModes = []) {
+	const out = streamText(result.stdout);
+	const err = streamText(result.stderr);
+	let body = out;
+	if (err.length > 0) {
+		if (body.length > 0 && !body.endsWith("\n")) body += "\n";
+		body += `[stderr]\n${err}`;
+	}
+	if (body.length === 0) body = "(no output)";
+	const markers = [];
+	if (result.sandbox?.denied) {
+		markers.push(sandboxDenialMarker(result.sandbox.mode));
+		if (escalationModes.length > 0) markers.push(escalationHintMarker("command"));
+	}
+	if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`);
+	if (result.signal !== null) markers.push(`[killed by signal: ${result.signal}]`);
+	else if (result.exitCode !== 0) markers.push(`[exit code: ${result.exitCode}]`);
+	if (markers.length === 0) return body;
+	if (!body.endsWith("\n")) body += "\n";
+	return body + markers.join("\n");
+}
+/**
+* Shape one background-process read into the `job_output` delta the model
+* sees: the incremental delta, plus the lossy-read notice (with full-stream
+* spill paths) when in-memory truncation dropped unread bytes. Empty-delta
+* rendering (`(no new output)`) is the generic job controller's job.
+* @param read - one incremental read from the process handle.
+* @param sandbox - settled sandbox facts, when this was a confined process.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the delta text with any loss or sandbox notice appended.
+*/
+function renderProcessRead(read, sandbox, escalationModes = []) {
+	const notices = [];
+	if (read.lossy) {
+		const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path) => path !== void 0);
+		notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(", ") : "(unavailable)"}]`);
+	}
+	if (sandbox?.runnerFailed) notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`);
+	else if (sandbox?.denied) {
+		notices.push(sandboxDenialMarker(sandbox.mode));
+		if (escalationModes.length > 0) notices.push(escalationHintMarker("command"));
+	}
+	if (notices.length === 0) return read.delta;
+	return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Model-facing Consumer of the `ctx.shell` capability seam. Background calls
+* register process handles with `ctx.jobs`; their work uses job cancellation
+* rather than the tool-call signal after an id is returned.
+*
+* TODO(permissions): deployment policy belongs in `tools/pre-execute` and
+* sandboxing executors; see docs/architecture.md § Where new behavior goes.
+* @module @hydraharness/harness-tool-bash
+*/
+const name = "tool-bash";
+const inject = [
+	"tools",
+	"shell",
+	"systemPrompt",
+	"shellEnv"
+];
+/** Runtime configuration schema for the bash tool plugin. */
+const Config = z.object({ enableRunInBackground: z.boolean().default(true) });
+function validateBashArgs(args) {
+	if (args.command.trim().length === 0) throw new Error("invalid command: expected a non-empty string");
+	if (args.description.trim().length === 0) throw new Error("invalid description: expected a non-empty string");
+	if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`);
+	validateEscalationArgs(args.sandbox_permissions, args.justification);
+	if (args.changed_paths?.some((path) => path.length === 0)) throw new Error("invalid changed_paths: expected non-empty file paths");
+}
+function bashDescription(backgroundEnabled, escalationModes) {
+	const background = backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." : "Background execution is not available; long-running commands must finish within the timeout.";
+	const base = `Execute a bash command (\`bash -c\`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass \`workdir\` instead of using \`cd\`. Non-zero exits are reported as \`[exit code: N]\`. Current harness environment facts are exposed through managed \`$${HYDRA_ENV_PREFIX}*\` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as \`[sandbox: file access denied under <mode> mode]\` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. ` + background;
+	if (escalationModes.length === 0) return base;
+	return base + " Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.";
+}
+function presentBashCall(args) {
+	if (args.run_in_background === true) return {
+		card: "generic",
+		title: args.command,
+		kind: "execute",
+		rawInput: args.command,
+		content: [{
+			type: "text",
+			text: args.description
+		}]
+	};
+	return {
+		card: "terminal",
+		title: args.command,
+		description: args.description,
+		...args.workdir !== void 0 ? { cwd: args.workdir } : {}
+	};
+}
+/**
+* Present completed foreground output as a terminal; background acknowledgements
+* and execution errors use generic fenced output without an exit-status pill.
+*/
+function presentBashResult(args, result) {
+	const block = result.content.length === 1 ? result.content[0] : void 0;
+	if (block === void 0 || block.type !== "text") return void 0;
+	const raw = block.text;
+	if (typeof args === "object" && args !== null && args.run_in_background === true || result.isError) return {
+		card: "generic",
+		content: [{
+			type: "text",
+			text: `\`\`\`console\n${raw.replace(/\n+$/, "")}\n\`\`\``
+		}]
+	};
+	const { body, ...exit } = parseExitStatus(raw);
+	return {
+		card: "terminal",
+		output: body,
+		...exit
+	};
+}
+/**
+* Resolve an explicit workdir first, making a relative one session-workspace-relative;
+* otherwise use the filesystem identity of the session cwd and leave executor
+* defaulting as the fallback. A resolved sandbox-policy root wins so workdir
+* and confinement use the exact same per-call identity.
+*/
+function resolveWorkdir(modelWorkdir, exec, policyWorkspaceRoot) {
+	const headerCwd = exec.agent?.session.header.cwd;
+	const sessionCwd = policyWorkspaceRoot ?? (headerCwd === void 0 ? void 0 : canonicalPath(headerCwd));
+	if (modelWorkdir === void 0) return sessionCwd;
+	if (sessionCwd !== void 0 && !isAbsolute(modelWorkdir)) return resolve(sessionCwd, modelWorkdir);
+	return modelWorkdir;
+}
+/** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
+function canonicalBashResult(result) {
+	const output = (stream) => ({
+		text: stream.text,
+		truncated: stream.truncated,
+		...stream.spillPath !== void 0 ? { spillPath: stream.spillPath } : {}
+	});
+	return {
+		exitCode: result.exitCode,
+		signal: result.signal,
+		timedOut: result.timedOut,
+		aborted: result.aborted,
+		timeoutMs: result.timeoutMs,
+		stdout: output(result.stdout),
+		stderr: output(result.stderr),
+		...result.sandbox !== void 0 ? { sandbox: {
+			mode: result.sandbox.mode,
+			denied: result.sandbox.denied,
+			...result.sandbox.enforcement !== void 0 ? { enforcement: result.sandbox.enforcement } : {},
+			...result.sandbox.runnerFailed !== void 0 ? { runnerFailed: result.sandbox.runnerFailed } : {}
+		} } : {}
+	};
+}
+/** Canonical background-handle properties shared by the bash output union. */
+const BACKGROUND_OUTPUT_PROPERTIES = {
+	kind: {
+		type: "string",
+		required: true,
+		const: "background"
+	},
+	jobId: {
+		type: "string",
+		required: true
+	}
+};
+function apply(ctx, config = {}) {
+	const backgroundEnabled = config.enableRunInBackground ?? true;
+	const defaultMode = ctx.shell.sandboxMode;
+	const escalationModes = defaultMode === void 0 ? [] : ESCALATION_TARGETS;
+	const sandboxPolicy = defaultMode === void 0 ? void 0 : ctx.get("sandboxPolicy");
+	if (defaultMode !== void 0 && sandboxPolicy === void 0) throw new Error("tool-bash: the mounted bash executor confines but ctx.sandboxPolicy is missing");
+	/** Resolve the complete standing policy for this call when a confining executor is mounted. */
+	const resolveSandboxPolicy = (exec) => sandboxPolicy?.resolve(exec.agent === void 0 ? {} : { session: exec.agent.session });
+	/**
+	* Resolve a sandbox-escalation request through `ctx.approval` BEFORE
+	* anything executes, delegating the shared fail-closed sequence (strict
+	* widening, channel resolution, outcome mapping) to
+	* {@link approveEscalation}. This tool contributes only the composition
+	* guard (the fields are unadvertised without a sandboxing executor, yet
+	* schema validation checks advertised keys only, so an unadvertised
+	* `sandbox_permissions` still reaches execute) and the approval
+	* ingredients. The shared policy resolver is required whenever the executor
+	* advertises confinement, so a split composition fails at tool-plugin load.
+	*/
+	const approveBashEscalation = (mode, justification, exec, standingPolicy) => {
+		if (escalationModes.length === 0) throw new Error("sandbox_permissions is not available in this composition (no sandboxing executor to escalate)");
+		const effectiveMode = standingPolicy.mode;
+		return approveEscalation({
+			requestedMode: mode,
+			justification,
+			effectiveMode,
+			subject: "command"
+		}, {
+			approver: ctx.get("approval"),
+			agent: exec.agent,
+			callId: exec.callId,
+			toolName: "bash",
+			signal: exec.signal
+		});
+	};
+	ctx.systemPrompt.section({
+		name: "tool:bash",
+		order: 105,
+		text: "Check the [exit code: N] marker on every bash result; investigate failures before moving on."
+	});
+	ctx.tools.register(defineTool({
+		name: "bash",
+		description: bashDescription(backgroundEnabled, escalationModes),
+		parameters: {
+			command: {
+				type: "string",
+				required: true,
+				description: "The bash command to execute."
+			},
+			description: {
+				type: "string",
+				required: true,
+				description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
+			},
+			timeoutMs: {
+				type: "number",
+				description: "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+			},
+			workdir: {
+				type: "string",
+				description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+			},
+			changed_paths: {
+				type: "array",
+				items: { type: "string" },
+				description: "Foreground files this command changed, declared explicitly for workspace instruction refresh."
+			},
+			...backgroundEnabled ? { run_in_background: {
+				type: "boolean",
+				description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
+			} } : {},
+			...escalationModes.length > 0 ? {
+				sandbox_permissions: {
+					type: "string",
+					enum: [...escalationModes],
+					description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
+				},
+				justification: {
+					type: "string",
+					description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
+				}
+			} : {}
+		},
+		output: {
+			schema: { oneOf: [{
+				type: "object",
+				additionalProperties: false,
+				properties: BACKGROUND_OUTPUT_PROPERTIES
+			}, {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "foreground"
+					},
+					exitCode: {
+						required: true,
+						oneOf: [{ type: "integer" }, { type: "null" }]
+					},
+					signal: {
+						required: true,
+						oneOf: [{ type: "string" }, { type: "null" }]
+					},
+					timedOut: {
+						type: "boolean",
+						required: true
+					},
+					aborted: {
+						type: "boolean",
+						required: true
+					},
+					timeoutMs: {
+						type: "number",
+						required: true
+					},
+					stdout: {
+						type: "object",
+						additionalProperties: false,
+						required: true,
+						properties: {
+							text: {
+								type: "string",
+								required: true
+							},
+							truncated: {
+								type: "boolean",
+								required: true
+							},
+							spillPath: { type: "string" }
+						}
+					},
+					stderr: {
+						type: "object",
+						additionalProperties: false,
+						required: true,
+						properties: {
+							text: {
+								type: "string",
+								required: true
+							},
+							truncated: {
+								type: "boolean",
+								required: true
+							},
+							spillPath: { type: "string" }
+						}
+					},
+					sandbox: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							mode: {
+								type: "string",
+								required: true
+							},
+							denied: {
+								type: "boolean",
+								required: true
+							},
+							enforcement: { type: "string" },
+							runnerFailed: { type: "boolean" }
+						}
+					}
+				}
+			}] },
+			render: (_args, value) => [{
+				type: "text",
+				text: value.kind === "background" ? `started background job ${value.jobId}` : renderResult(value, escalationModes)
+			}]
+		},
+		async execute(args, exec) {
+			validateBashArgs(args);
+			const standingPolicy = resolveSandboxPolicy(exec);
+			const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
+			const policy = approvedMode === void 0 ? standingPolicy : {
+				...standingPolicy,
+				mode: approvedMode
+			};
+			const workdir = resolveWorkdir(args.workdir, exec, standingPolicy?.workspaceRoot);
+			const hydraEnv = ctx.shellEnv.collect(exec);
+			const request = {
+				command: args.command,
+				...workdir !== void 0 ? { workdir } : {},
+				...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
+				hydraEnv,
+				...policy !== void 0 ? { sandboxPolicy: policy } : {}
+			};
+			if (args.run_in_background === true) {
+				if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
+				const jobs = ctx.get("jobs");
+				if (jobs === void 0) throw new Error("background jobs unavailable: load @hydraharness/harness-jobs and @hydraharness/harness-tool-jobs");
+				if (exec.signal.aborted) {
+					const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+					error.name = "AbortError";
+					throw error;
+				}
+				return {
+					kind: "background",
+					jobId: jobs.start({
+						kind: "bash",
+						label: args.command,
+						...exec.agent ? { owner: exec.agent } : {},
+						run: () => {
+							const proc = ctx.shell.start(ctx.shell.resolve(request));
+							return {
+								cancel: () => void proc.kill(),
+								done: proc.done.then(() => processOutcome(proc)),
+								readOutput: () => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes)
+							};
+						}
+					})
+				};
+			}
+			const result = await ctx.shell.run(ctx.shell.resolve({
+				...request,
+				signal: exec.signal
+			}));
+			if (result.aborted) {
+				const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+				error.name = "AbortError";
+				throw error;
+			}
+			return {
+				kind: "foreground",
+				...canonicalBashResult(result)
+			};
+		},
+		presentCall: presentBashCall,
+		presentResult: presentBashResult
+	}));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-tool-bash`.
+* @module @hydraharness/harness-tool-bash/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-tool-bash";
+/** Cordis companion plugin name. */
+const name = "tool-bash-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the environment registry validates ownership and collected values at each
+* mutation/read; it publishes no independent snapshot that a companion could cross-check.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/background.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generic-task adaptation for background bash process handles.
+ *
+ * @module @hydraharness/harness-tool-bash/background
+ */
+import type { ShellProcess } from '@hydraharness/harness-shell';
+/**
+ * Map a settled background process onto the generic task-outcome vocabulary:
+ * `killed` stays `killed` (detail: the signal when one is known), everything
+ * else is `completed` with the exit code as detail. A nonzero command exit is
+ * reported, not failed, exactly like the foreground rendering.
+ * @param proc - the settled process handle.
+ * @returns the outcome for the `ctx.jobs` registration.
+ */
+export declare function processOutcome(proc: ShellProcess): {
+    status: 'completed' | 'killed';
+    detail: string;
+};
+//# sourceMappingURL=background.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model-facing Consumer of the `ctx.shell` capability seam. Background calls
+ * register process handles with `ctx.jobs`; their work uses job cancellation
+ * rather than the tool-call signal after an id is returned.
+ *
+ * TODO(permissions): deployment policy belongs in `tools/pre-execute` and
+ * sandboxing executors; see docs/architecture.md § Where new behavior goes.
+ * @module @hydraharness/harness-tool-bash
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+export declare const name = "tool-bash";
+export declare const inject: string[];
+/** Configuration for the bash tool. */
+export interface Config {
+    /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+    enableRunInBackground?: boolean;
+}
+/** Runtime configuration schema for the bash tool plugin. */
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-tool-bash`.
+ * @module @hydraharness/harness-tool-bash/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-bash-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/render.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Model-facing result rendering for the bash tool.
+ *
+ * @module @hydraharness/harness-tool-bash/render
+ */
+import type { ShellProcessRead, ShellRunResult, ShellSandboxInfo } from '@hydraharness/harness-shell';
+import type { SandboxMode } from '@hydraharness/harness-sandbox';
+/**
+ * Shape one finished run into the text the model sees: stdout, then a marked
+ * stderr section, then exit-status markers. Non-zero exits are reported, not
+ * errored — the model decides how to react; only infrastructure failures
+ * (spawn errors, aborts) surface as isError results.
+ * @param result - the completed foreground run from the executor.
+ * @param escalationModes - the escalation targets this composition advertises;
+ *   non-empty adds the same-turn escalation hint after a denial marker
+ *   (default `[]`: no hint).
+ * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+ */
+export declare function renderResult(result: ShellRunResult, escalationModes?: readonly SandboxMode[]): string;
+/**
+ * Shape one background-process read into the `job_output` delta the model
+ * sees: the incremental delta, plus the lossy-read notice (with full-stream
+ * spill paths) when in-memory truncation dropped unread bytes. Empty-delta
+ * rendering (`(no new output)`) is the generic job controller's job.
+ * @param read - one incremental read from the process handle.
+ * @param sandbox - settled sandbox facts, when this was a confined process.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the delta text with any loss or sandbox notice appended.
+ */
+export declare function renderProcessRead(read: ShellProcessRead, sandbox?: ShellSandboxInfo, escalationModes?: readonly SandboxMode[]): string;
+/**
+ * The exit-status parse is the shared marker-contract half of the shell-tool
+ * rendering story, owned by `@hydraharness/harness-shell` so `@hydraharness/harness-tool-pwsh` reuses
+ * it (its renderer emits the same markers). Re-exported here to keep
+ * `../src/render.ts` a single import root for bash-tool consumers.
+ */
+export { parseExitStatus, type ParsedExitStatus } from '@hydraharness/harness-shell';
+//# sourceMappingURL=render.d.ts.map

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@hydraharness/harness-tool-bash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Model-facing bash tool with optional generic background-job and sandbox-escalation support",
+  "hydra": {
+    "plugin": {
+      "application": "Let the agent run Bash commands and collect their output."
+    }
+  },
+  "version": "0.1.1-rc.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/shell/tool-bash"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.7",
+    "@hydraharness/harness-shell-env": "^0.1.1-rc.7",
+    "@hydraharness/harness-shell": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-llm": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.7",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.7",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.7",
+    "@hydraharness/harness-tools": "^0.1.1-rc.7",
+    "@hydraharness/harness-user-approval": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.7",
+    "@hydraharness/harness-agent-loop": "^0.1.1-rc.7",
+    "@hydraharness/harness-agent-loop-testkit": "^0.1.1-rc.7",
+    "@hydraharness/harness-shell": "^0.1.1-rc.7",
+    "@hydraharness/harness-shell-env": "^0.1.1-rc.7",
+    "@hydraharness/harness-bash-local": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-llm": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.7",
+    "@hydraharness/harness-subprocess-local": "^0.1.1-rc.7",
+    "@hydraharness/harness-session-persistence-jsonl": "^0.1.1-rc.7",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.7",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.7",
+    "@hydraharness/harness-user-approval": "^0.1.1-rc.7",
+    "@hydraharness/harness-jobs-local": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-session": "^0.1.1-rc.7",
+    "@hydraharness/harness-tool-jobs": "^0.1.1-rc.7",
+    "@hydraharness/harness-tools": "^0.1.1-rc.7"
+  }
 }