iosm-cli 0.2.9 → 0.2.11

package/docs/cli-reference.md

@@ -127,6 +127,14 @@ These commands run inside interactive mode (`iosm`), not as top-level CLI subcom
   - baseline repository scan + standard agent pass
   - outputs exactly 3 implementation options with recommendation
   - lets user choose option `1/2/3`, then `Start with Swarm` or `Continue without Swarm`
+- `/ultrathink [-q N|--iterations N] [query]` — deep read-only iterative analysis:
+  - runs root-agent analysis in strict read-only tool mode for `N` iterations (default `5`, max `12`)
+  - 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]`
@@ -260,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.
@@ -293,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

@@ -56,6 +56,7 @@ iosm --continue
 | `/semantic` | Open semantic search manager (`setup/auto-index/status/index/rebuild/query`) | `/semantic` |
 | `/contract` | Interactive engineering contract editor (field-by-field, auto JSON build) | `/contract` |
 | `/singular` | Feature feasibility analyzer with implementation options and recommendation | `/singular add account dashboard` |
+| `/ultrathink` | Deep multi-iteration read-only analysis mode with self-check checkpoints | `/ultrathink -q 7 investigate auth regression` |
 | `/swarm` | Recommended multi-agent orchestration runtime for complex/risky tasks (`run`, `from-singular`, `watch`, `retry`, `resume`) | `/swarm run refactor auth module --max-parallel 3` |
 | `/memory` | Interactive memory manager (`add/edit/remove/scope/path`) | `/memory` |
 | `/settings` | View/modify settings | `/settings` |
@@ -82,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` |
 
@@ -109,11 +111,16 @@ In `/semantic setup`, the headers step is optional: press `Enter` on empty input
 `/memory` opens an interactive manager. `/memory <text>` saves a note to `memory.md` and reloads session context. Use `/memory edit <index> <text>` for direct updates.
 `/contract` edits contract fields interactively (`goal`, scope, constraints, quality gates, DoD, risks, etc.), then writes JSON automatically.
 `/singular <request>` runs a two-pass feasibility analysis (baseline scan + standard agent pass), builds concrete implementation options, then prompts `Start with Swarm` / `Continue without Swarm` / `Cancel`.
+`/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.9",
+	"version": "0.2.11",
 	"description": "Standalone IOSM CLI with agent tooling, session management, and IOSM artifact orchestration",
 	"type": "module",
 	"iosmConfig": {