iosm-cli 0.2.10 → 0.2.11

package/docs/cli-reference.md

@@ -132,6 +132,9 @@ These commands run inside interactive mode (`iosm`), not as top-level CLI subcom
   - carries compact checkpoint state between iterations (facts, rejected hypotheses, open questions, next checks)
   - auto-injects a grounding retry when early passes return no tool evidence, forcing live workspace probes
   - if query is omitted, reuses latest meaningful user request from session context
+- `/bg [list [limit]|status [id]|logs [id] [lines]|stop [id]]` — interactive background shell process manager:
+  - run detached shell commands with `! <command> &`
+  - inspect process state, log tail, and stop running background jobs
 - `/swarm` — canonical gated execution runtime:
   - `/swarm run <task> [--max-parallel N] [--budget-usd X]`
   - `/swarm from-singular <run-id> --option <1|2|3> [--max-parallel N] [--budget-usd X]`
@@ -265,6 +268,7 @@ iosm --api-key sk-test-123           # Override for this run
 `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`, `semantic_search`, `fetch`, `web_search`, `git_read`, `git_write`, `fs_ops`, `test_run`, `lint_run`, `typecheck_run`, `db_run`, `todo_read`, `todo_write`
 
 Tool notes:
+- `bash` supports optional `run_in_background=true` for detached execution; returned details include `backgroundTaskId` and metadata/log paths.
 - `rg`, `fd` are managed by iosm-cli and auto-resolved when missing.
 - `ast_grep`, `comby`, `jq`, `yq`, `semgrep` are optional external CLIs and should be available in `PATH` to use their tools.
 - `sed` tool is preview/extraction-oriented; in-place edits are intentionally blocked.
@@ -298,6 +302,7 @@ Best-practice patterns:
 - File exploration: use bounded reads/searches (`path`, `glob`, `context`, `limit`); for large files, page with `read` using `offset`/`limit` instead of dumping whole files.
 - File mutation: prefer `edit` for surgical changes and `write` for full rewrites; use `fs_ops` for `mkdir/move/copy/delete`, with `force=true` only when replacement/no-op behavior is intentional.
 - Verification: prefer `test_run` / `lint_run` / `typecheck_run` over ad-hoc bash commands for deterministic runner resolution and normalized status reporting.
+- Long-running shell jobs: prefer detached `bash` (`run_in_background=true`) or interactive `! <command> &`, then monitor with `/bg` instead of blocking the foreground turn.
 - DB operations: prefer `db_run` with named profiles; keep read flows in `query/schema/explain` and use `allow_write=true` only for `exec/migrate`.
 - Structured data transforms: use `jq`/`yq` to compute/preview transforms, then persist the final state through `edit`/`write`.
 - Semantic retrieval: use `semantic_search status` first when relevance looks stale, then run `query`; run `index`/`rebuild` when config or index freshness requires it.

package/docs/configuration.md

@@ -101,8 +101,15 @@ Settings are merged in this order (later wins):
       }
     }
   },
+  "promptContext": {
+    "enableContextDedupe": true,
+    "maxContextCharsPerFile": 4000,
+    "maxTotalContextChars": 12000,
+    "enableGitSnapshotContext": false
+  },
   "permissions": {
-    "autoApprove": false
+    "autoApprove": false,
+    "extensionToolEnforcement": false
   }
 }
 ```
@@ -110,6 +117,8 @@ Settings are merged in this order (later wins):
 `githubTools.networkEnabled` controls whether `git_write` network actions (`fetch`, `pull`, `push`) are allowed.  
 `githubTools.token` is optional and, when set, is injected for GitHub HTTPS authentication during network git actions.
 `dbTools` defines named DB connection profiles consumed by `db_run`; for network adapters (`postgres`, `mysql`, `mongodb`, `redis`) use `dsnEnv` so secrets stay in environment variables instead of tool input.
+`promptContext` controls system prompt context compaction before model call: dedupe by normalized content hash, per-file char budget, total char budget, and optional git snapshot context inclusion.
+`permissions.extensionToolEnforcement` enables strict runtime permission tier checks for extension tools (off by default).
 
 ### `db_run` Setup (Recommended)
 
@@ -389,6 +398,53 @@ Permissions control tool execution approval behavior.
 - **Shell commands**: Whether `bash` executions require approval
 - **Destructive actions**: Special handling for `rm`, `sudo`, etc.
 
+### Extension Tool Permission Tiers
+
+Extension tools can declare one of the runtime tiers:
+
+- `read-only`
+- `workspace-write`
+- `danger-full-access`
+
+When `permissions.extensionToolEnforcement=true`, interactive mode enforces stricter behavior for extension tools:
+
+- in `auto` mode, extension tools marked `read-only` are allowed automatically
+- extension tools missing `requiredPermission` metadata are blocked in `auto` mode (with warning)
+- `ask` and `yolo` modes keep their expected approval semantics
+
+Example:
+
+```json
+{
+  "permissions": {
+    "extensionToolEnforcement": true
+  }
+}
+```
+
+### Prompt Context Budgets
+
+`promptContext` applies deterministic preprocessing to loaded context files before they are appended to the system prompt:
+
+- normalize line endings and trim
+- optional dedupe by normalized-content hash
+- per-file cap (`maxContextCharsPerFile`)
+- total cap (`maxTotalContextChars`)
+- optional git snapshot context (`enableGitSnapshotContext`)
+
+Default values:
+
+```json
+{
+  "promptContext": {
+    "enableContextDedupe": true,
+    "maxContextCharsPerFile": 4000,
+    "maxTotalContextChars": 12000,
+    "enableGitSnapshotContext": false
+  }
+}
+```
+
 ### Safety Defaults
 
 By default, `iosm-cli` asks for confirmation before:

package/docs/development-and-testing.md

@@ -38,6 +38,7 @@ iosm-cli/
 │   │   ├── skills.ts             # Skill discovery and loading
 │   │   ├── prompt-templates.ts   # Prompt template system
 │   │   ├── bash-executor.ts      # Shell command execution
+│   │   ├── background-processes.ts # Detached background process runtime
 │   │   ├── tools/                # Built-in tools
 │   │   │   ├── read.ts           # File reading
 │   │   │   ├── bash.ts           # Shell execution
@@ -70,7 +71,7 @@ iosm-cli/
 │       ├── clipboard.ts          # Clipboard access
 │       ├── image-resize.ts       # Image processing
 │       └── ...
-├── test/                         # Vitest test suite (73 files)
+├── test/                         # Vitest test suite (74 files)
 ├── examples/
 │   ├── extensions/               # 66 extension examples
 │   └── sdk/                      # 12 SDK examples
@@ -157,7 +158,7 @@ Tests are organized by feature area:
 
 | Area | Test Files | Coverage |
 |------|-----------|----------|
-| **Tools** | `tools.test.ts` | Built-in tools (`read`, `bash`, `edit`, `write`, `git_write`, `fs_ops`, `test_run`, `lint_run`, `typecheck_run`, `db_run`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`, `semantic_search`, `fetch`, `web_search`, `git_read`) |
+| **Tools** | `tools.test.ts`, `background-processes.test.ts` | Built-in tools (`read`, `bash`, `edit`, `write`, `git_write`, `fs_ops`, `test_run`, `lint_run`, `typecheck_run`, `db_run`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`, `semantic_search`, `fetch`, `web_search`, `git_read`) + detached background process lifecycle |
 | **Session** | `session-manager/`, `session-*.test.ts` | Persistence, branching, migration |
 | **Extensions** | `extensions-*.test.ts` | Discovery, running, hooks, input events |
 | **Compaction** | `compaction*.test.ts` | Context summarization |

package/docs/extensions-packages-themes.md

@@ -47,6 +47,7 @@ export default function (pi: ExtensionAPI) {
     name: "weather",
     label: "Weather",
     description: "Get current weather for a city",
+    requiredPermission: "read-only",
     parameters: Type.Object({
       city: Type.String({ description: "City name" }),
     }),
@@ -68,6 +69,32 @@ export default function (pi: ExtensionAPI) {
 > action: StringEnum(["add", "remove", "list"] as const)
 > ```
 
+### Extension Tool Permission Metadata
+
+Custom tools can declare `requiredPermission` to participate in runtime permission tier policies:
+
+- `read-only`
+- `workspace-write`
+- `danger-full-access`
+
+Example for mutating tool:
+
+```typescript
+pi.registerTool({
+  name: "repo_sync",
+  label: "Repo Sync",
+  description: "Synchronize local repository metadata cache",
+  requiredPermission: "workspace-write",
+  parameters: Type.Object({ force: Type.Optional(Type.Boolean()) }),
+  async execute(_toolCallId, params) {
+    // ...
+    return { content: [{ type: "text", text: "ok" }] };
+  },
+});
+```
+
+When runtime setting `permissions.extensionToolEnforcement` is enabled, these tiers are used in interactive permission flow.
+
 ### Registering Commands
 
 ```typescript

package/docs/interactive-mode.md

@@ -83,6 +83,7 @@ iosm --continue
 | `/agents` | Inspect custom/system agents | `/agents` |
 | `/subagent-runs` | List subagent run history | `/subagent-runs` |
 | `/subagent-resume` | Resume a subagent run | `/subagent-resume run-123` |
+| `/bg` | Background shell process manager (`list/status/logs/stop`) | `/bg status bg_...` |
 | `/team-runs` | List team orchestration runs | `/team-runs` |
 | `/team-status` | Check team run status | `/team-status team-456` |
 
@@ -113,11 +114,13 @@ In `/semantic setup`, the headers step is optional: press `Enter` on empty input
 `/ultrathink [-q N|--iterations N] [query]` runs `N` root-agent analysis passes in strict read-only mode (`N` defaults to `5`, max `12`), carries a compact checkpoint between passes, and emits concise per-iteration summaries with a final synthesis.
 `/ultrathink` without query reuses the latest meaningful user request from session context.
 If early passes produce no tool evidence, ultrathink injects an internal grounding retry so the agent probes the workspace with read-only tools before continuing.
+Run detached shell jobs with `! <command> &` (example: `! npm run dev &`) and manage them using `/bg`, `/bg status <id>`, `/bg logs <id> [lines]`, `/bg stop <id>`.
 `/swarm` enforces `Scopes -> Touches -> Locks -> Gates -> Done`. If effective contract is missing, it blocks execution and opens a bootstrap menu (auto-draft, guided Q&A, or manual `/contract` editor).
 `/orchestrate --parallel` defaults `--max-parallel` to `--agents` when omitted and auto-selects `meta` workers when profiles are not explicitly set (outside read-only host contexts).
 For orchestrate assignments, `delegate_parallel_hint` is carried into child task calls; high hints should trigger nested delegate fan-out or explicit `DELEGATION_IMPOSSIBLE`.
 If a model emits raw pseudo markup like `<tool_call>`, `<function=...>`, or `<delegate_task>` instead of real tool calls, interactive mode injects bounded protocol-recovery retries.
 If a model returns a silent `stop` (no visible text and no tool call), interactive mode injects bounded stall-recovery retries.
+After `/compact`, compaction summaries carry a continuation hint to proceed from current state without repeating a full recap unless user explicitly asks.
 `/blast` and `/shadow` are removed from active interactive workflow.
 
 ### `/contract` Detailed Guide

package/docs/orchestration-and-subagents.md

@@ -165,6 +165,11 @@ Create markdown files in `.iosm/agents/`:
 ---
 name: security-auditor
 description: Specialized security vulnerability analysis
+tools:
+  - read
+  - git-read
+disallowed_tools:
+  - write
 ---
 
 You are a security auditor specializing in web application security.
@@ -194,6 +199,17 @@ Always provide:
 
 Built-in system agents remain available; inspect via `/agents`.
 
+### Tool List Normalization in Agent Frontmatter
+
+For custom agent frontmatter fields `tools` and `disallowed_tools`, runtime applies compatibility normalization:
+
+- trims whitespace
+- lowercases names
+- converts `-` to `_` (for example `git-read` -> `git_read`)
+- drops unknown tool names and records diagnostics
+
+This keeps old/frontmatter variants compatible while preventing invalid tool names from breaking delegation.
+
 ---
 
 ## Safety Guidance

package/docs/rpc-json-sdk.md

@@ -129,6 +129,20 @@ agent.stdout.on("data", (data) => {
 });
 ```
 
+### Detached Bash via Tool Parameters
+
+When the `bash` tool is available, callers can request detached execution with `run_in_background: true`.
+The result details include `backgroundTaskId` plus paths to metadata/log files.
+
+```typescript
+const result = await bashTool.execute("bg-1", {
+  command: "npm run dev",
+  run_in_background: true,
+});
+
+console.log(result.details?.backgroundTaskId);
+```
+
 ### RPC Extension UI
 
 Extensions can expose UI elements through RPC mode. See [rpc-extension-ui.ts](../examples/rpc-extension-ui.ts) for a complete example of using `confirm`, `select`, `notify`, and other UI methods over RPC.

package/docs/sessions-traces-export.md

@@ -129,12 +129,19 @@ Traces are stored as `<session-id>.jsonl` files. Each line is a JSON event:
 ```jsonl
 {"type":"session_start","timestamp":"2026-03-09T15:42:00Z","sessionId":"abc123"}
 {"type":"user_message","timestamp":"2026-03-09T15:42:05Z","content":"Analyze the project"}
+{"type":"system_prompt_context_compose","timestamp":"2026-03-09T15:42:05Z","context_before_chars":16422,"context_after_chars":11998,"dedupe_hits":2,"truncated_files":["README.md"],"dropped_files":1}
 {"type":"tool_call","timestamp":"2026-03-09T15:42:06Z","tool":"ls","input":{"path":"."}}
 {"type":"tool_result","timestamp":"2026-03-09T15:42:06Z","tool":"ls","output":"..."}
+{"type":"bash_end","timestamp":"2026-03-09T15:42:07Z","command":"npm run dev","backgroundTaskId":"bg_1770000000000_ab12cd34"}
 {"type":"assistant_message","timestamp":"2026-03-09T15:42:10Z","content":"Here's my analysis..."}
 {"type":"turn_end","timestamp":"2026-03-09T15:42:10Z","usage":{"totalTokens":1500}}
 ```
 
+Notable runtime events:
+
+- `system_prompt_context_compose` shows prompt-context preprocessing stats (before/after chars, dedupe hits, truncation, dropped files).
+- `bash_end.backgroundTaskId` is populated when a shell command was started in detached background mode.
+
 ### Analyzing Traces
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "iosm-cli",
-	"version": "0.2.10",
+	"version": "0.2.11",
 	"description": "Standalone IOSM CLI with agent tooling, session management, and IOSM artifact orchestration",
 	"type": "module",
 	"iosmConfig": {